Parallel Task Isolation

The operating model#

AIT permits parallel authoring with serialized admission. Multiple coding agents may work at the same time, but they do not share one mutable checkout and they do not write directly to main.

Each governed request receives its own Task, Change, feature Line, and bound worktree. The agent records immutable Snapshots in that lineage. A candidate is admitted to the target Line only after its exact Patchset has the required evidence and the target head has been checked again.

This division is important:

• Task-bound worktrees and command locks prevent workspace operations from colliding.
• immutable Snapshots prevent a reviewed revision from changing underneath its evidence;
• rebase and target-head checks prevent a stale candidate from overwriting newer work; and
• atomic Land prevents a last-writer-wins update to the shared target Line.

AIT does not make it safe for two agents to edit the same worktree. High parallelism comes from creating more isolated Task worktrees, not from sharing one directory more aggressively.

One Task owns one mutable checkout#

ait task start creates and binds these working identities. Its output prints the exact cd command. The agent must enter that path before modifying code.

ait task start \
  --from docs/sprints/login.md#login/password-visibility \
  --intent "Add accessible password visibility" \
  --base-line main

A second agent starts a different open item and receives a different Task, Change, Line, and worktree.

ait task start \
  --from docs/sprints/login.md#login/session-regression \
  --intent "Repair session renewal regression" \
  --base-line main

Do not assign the same sprint item to two agents. RC.6 validates that an item is open and taskable before Task creation, but it does not claim that one Plan item has a complete cross-client, server-owned uniqueness lock. Parallel Tasks should begin from distinct exact item references.

Two agents, one target Line#

Assume both Tasks fork from main at Snapshot S0:

main @ S0
|
+-- Task A -> Change A -> feature Line A -> worktree A
|              `-> Snapshot A -> Patchset A
|
`-- Task B -> Change B -> feature Line B -> worktree B
               `-> Snapshot B -> Patchset B

The agents implement and test concurrently inside their printed paths.

# Agent A, inside worktree A
ait snapshot create --message "Add password visibility control"
ait workflow ready <change-a> --apply

# Agent B, inside worktree B
ait snapshot create --message "Repair session renewal regression"
ait workflow ready <change-b> --apply

Suppose Task A lands first and moves main from S0 to S1. Task B does not overwrite S1 with a candidate based on S0.

Task A: main S0 -> S1

Task B readiness:
  base S0 != current main S1
  |
  +-- clean rebase -> refresh Snapshot/Patchset evidence -> eligible Land
  |
  `-- conflict -> stop with main unchanged -> explicit resolution required

For a clean bound worktree, guided readiness can rebase it onto the current target before publishing the next candidate. The resulting candidate is new content and must carry evidence for that exact selected Patchset; an earlier CI pass is not reused as proof for the rebased revision.

If rebase conflicts, AIT records the paused state and leaves the target Line unchanged. Inspect and either continue or abort explicitly:

ait worktree status --json
ait worktree rebase --continue
# or
ait worktree rebase --abort

After conflict resolution, record and prepare the resulting revision as directed by the current workflow output. ait task land consumes an already ready selected Patchset. If the target head changes again before Land, the operation fails closed instead of hiding the intervening result.

Why AIT_RAM is part of the strategy#

Filesystem isolation is correct but can be expensive when every Task restores an entire repository onto disk. The AIT_RAM strategy places managed Task worktrees on a verified memory-backed filesystem and maintains one reusable read-only main-seed for rapid fan-out.

AIT_RAM is an execution and cache layer. It is not the AIT authority, a backup, or a replacement for ait-server recovery. Task, Line, Snapshot, and other repository authority remains in the persistent repository state or the configured server. Only the materialized checkout is placed in volatile memory.

Persistent repository
|
+-- .ait/                         Task, Line, Snapshot authority
+-- .ait-worktree-links/task-a --+
`-- .ait-worktree-links/task-b --+---- stable local aliases
                                  |
/Volumes/AIT_RAM/                 |    memory-backed execution
`-- .ait-repos/<repository-key>/  |
    |                             |
    +-- main-seed                 |    read-only main Snapshot
    +-- task-a <------------------+    writable Agent A checkout
    `-- task-b <------------------+    writable Agent B checkout

The Repository key is derived from the authoritative repository path. It partitions the shared memory root so different repositories do not collide even when their Task worktree names are similar. The default stable alias root is .ait-worktree-links inside the repository.

Inspect the resolved paths rather than assuming them:

ait config show --json
ait worktree list --json

The configuration projection reports task_worktree.memory_root, the derived ephemeral_root, the alias root, and any main-seed RAM budget.

Effective RC.6 memory defaults#

The defaults are deliberately literal; RC.6 does not derive them from a percentage of host memory.

Use ait config show --json and ait doctor memory-root --json to distinguish stored Repository policy from the host's current capacity. The former reports the typed memory-root selection and repo-local seed limit; the latter reports requested capacity, total bytes, available bytes, and the built-in zero-byte validation floor with each value's source.

Memory-root validation and provisioning#

Before relying on RAM placement, prove that the configured root is genuinely memory-backed and writable:

ait doctor memory-root

The diagnostic is always read-only. Managed Task placement is a separate path: while resolving a new worktree on macOS, it may provision the configured or built-in RAM volume. If that attempt cannot produce a usable root, placement continues to the persistent-disk fallback. A path merely named AIT_RAM is not accepted as proof that the storage is memory-backed.

The repository configuration uses these typed fields:

ait init records a supported root when one is already detected. On macOS, new-Task placement can still try the built-in /Volumes/AIT_RAM specification when the repository has no stored memory root. There is no environment-variable override for this Task-worktree contract.

main-seed fan-out#

main-seed is a read-only materialization of one exact Snapshot at the default Line head. It is a cache, not a mutable shared checkout.

When a Task forks from the current default Line, bootstrap follows this path:

1. Resolve the verified memory root and Repository-specific worktree root.
2. Verify that main-seed matches the exact default-Line Snapshot.
3. Refresh or rebuild a missing, stale, or invalid seed from Snapshot authority.
4. Copy the seed into the new Task path.
5. Make only the copied Task tree writable and attach its Task, Change, and feature-Line metadata.
6. Expose the stable alias printed to the agent.

The per-file copy preference is:

1. macOS clonefile;
2. Linux reflink;
3. ordinary file copy when copy-on-write is unavailable.

Copy-on-write avoids paying for a complete independent physical copy at Task start. Each worktree still becomes logically independent as soon as an agent changes a file. If copying the seed fails safely, bootstrap removes the partial target and restores the feature-Line Snapshot directly. The Task is still isolated; only the acceleration path changed.

Keeping the seed current#

After a successful Land to the default Line, AIT aligns main-seed with the landed Snapshot. The refresh path:

• uses a Repository and Line-specific refresh lock;
• validates the candidate worktree against the landed Snapshot;
• can promote the completed bound worktree or rebuild from Snapshot authority;
• prepares a staging seed and a recoverable previous-seed backup;
• makes the installed seed read-only; and
• rechecks the target Line generation before and during the atomic directory swap.

If main advances while the refresh is being prepared, AIT refuses to install the stale seed. A cache refresh failure does not manufacture successful seed state. It is reported separately so the landed code authority and the disposable acceleration cache are not confused.

Capacity and disk fallback#

RAM parallelism must be bounded explicitly. By default, task_worktree.main_seed_ram_max_bytes is unset, so RC.6 has no automatic Snapshot-size cutoff. An operator can set the default-Line Snapshot size admitted to main-seed-backed RAM placement:

ait config set \
  --task-worktree-main-seed-ram-max-bytes <bytes>

ait config unset task-worktree-main-seed-ram-max-bytes

The placement decision for each new Task is:

configured seed limit exists AND Snapshot bytes > limit
  -> Repository-internal persistent disk
else if a supported RAM root can be selected and its Repository directory created
  -> RAM
else
  -> Repository-internal persistent disk

The comparison is strictly greater-than. A Snapshot exactly equal to the configured limit remains RAM-eligible. When the limit is exceeded, AIT records main_seed_ram_budget_exceeded and selects .ait-worktree/<worktree-name> under the persistent Repository root (normally SSD-backed). With the built-in unset value, this size-triggered switch is disabled.

AIT also selects that persistent root when every eligible memory candidate is unavailable or unusable. This includes no detected tmpfs/ramfs on Linux, no DRIVE_RAMDISK on Windows, an unavailable or failed RAM-volume attempt on macOS, a configured memory/ephemeral path that cannot be accepted under its declared root, or failure to create the Repository-specific worktree directory.

The read-only memory-root diagnostic reports a built-in minimum of zero bytes. RC.6 does not use that value as an automatic Task-placement switch and has no hidden low-memory percentage threshold. Operators that require a reserve must enforce it through host monitoring and stop admitting new Tasks before the filesystem is exhausted.

Placement does not migrate an existing Task midway from RAM to disk. If main-seed copying fails after the RAM path has been selected, AIT first tries a direct Snapshot restore at that same path; that is a materialization fallback, not an SSD switch. If the selected filesystem cannot complete the restore or later becomes full, the command fails and the operator must preserve recorded Snapshots, resolve capacity, and recreate or start work on an eligible root.

Fallback changes performance, not Task identity, Snapshot semantics, or Land safety. Inspect root_source, ephemeral_enabled, target_path, and fallback_reason in the Task/worktree output. root_source equal to repo_internal_fallback with ephemeral_enabled: false proves persistent-root placement; do not infer that a stable alias necessarily points to RAM.

Before starting a large fan-out, check current capacity and live worktrees:

ait doctor memory-root --json
ait worktree doctor --refresh --json
ait queue summary --all-changes

Durability and recovery boundary#

This is the operational rule: create a Snapshot at coherent checkpoints when work must survive loss of volatile execution storage. AIT_RAM accelerates worktree materialization; it does not make unsnapshotted files durable.

After an unexpected unmount or restart, diagnose before deleting metadata:

ait doctor memory-root
ait worktree doctor --refresh --json
ait worktree recreate <worktree-name> --dry-run
ait worktree recreate <worktree-name>

If registry recovery must begin from a known Task and Change binding, use the explicit recovery surface shown by ait worktree recover-task --help. Recovery never reopens completed or canceled authority merely because an old directory exists.

Cleanup and operating rules#

Successful Task closeout removes the bound worktree and archives its Task feature Line after verifying that the accepted Snapshot is still its head. This releases volatile capacity without deleting Snapshot history.

For leftovers after interruption, preview ownership-aware cleanup first:

ait worktree cleanup-candidates --all --json
ait worktree cleanup --dry-run
ait worktree prune-stale --dry-run

Keep these rules when operating many agents:

• Give every agent a distinct sprint item and Task.
• Enter only the cd path printed for that Task.
• Never use the canonical repository root as a shared editing directory.
• Record immutable checkpoints before relying on a volatile worktree.
• Let readiness refresh stale candidates; never bypass a base-head conflict.
• Treat CI as evidence for one selected Patchset, not for a Task name in general.
• Land through AIT so the target-head check and atomic transition remain in force.
• Diagnose and preview cleanup before removing a worktree.

What this does not guarantee#

Worktree isolation prevents filesystem overwrites. It cannot prove that two textually compatible changes are behaviorally compatible. Two agents can edit different files and still change the same runtime contract. Repository-owned regression tests, review, and policy remain necessary.

AIT also does not provide unlimited RAM concurrency. Repository size, dirty deltas, tool caches, test processes, and runner capacity still determine a safe fan-out. AIT_RAM makes the cost visible and bounded; it does not remove the need for capacity planning.

Related#

• ait task
• ait snapshot
• ait workflow
• `ait worktree` complete reference
• `ait doctor` complete reference