@bluewombat/slots 0.10.0 → 0.11.1

package/README.md

@@ -57,8 +57,7 @@ these all use it. How Host wires a slot into a run:
 | ------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `agents/cursor.mjs`             | Agent     | Runs Cursor CLI with a filled prompt                                                                                                                                                                                                                  |
 | `agents/claude.mjs`             | Agent     | Runs Claude Code with a filled prompt                                                                                                                                                                                                                 |
-| `builders/tests.mjs`            | Builder   | The tests of the task, written before its code: one test per case of its "Tests" section (or per criterion when it has none), stubs for a missing interface, each test proved passable by a throwaway implementation in the stubs, then left failing. |
-| `builders/e2e.mjs`              | Builder   | The Ticket that holds a Feature's e2e acceptance suite: one test per scenario of the task, named after its id, and the manifest `e2e/scenarios.json`; nothing outside the suite folder, the suite never run. One command for the first pass and a refused one |
+| `builders/feature-test.mjs`     | Builder   | The Ticket that holds a Feature's tests: one test per scenario of the task, named after its id, existing tests updated when a scenario changes them, and the manifest `feature-tests/scenarios.json`; tests never run. One command for the first pass and a refused one |
 | `builders/producer.mjs`         | Builder   | First pass of the unit of work: fill `{{task}}`, then spawn the agent                                                                                                                                                                                 |
 | `builders/repair.mjs`           | Builder   | A Gate refused the unit: fill `{{task}}` and `{{report}}`                                                                                                                                                                                             |
 | `ticket/fix.mjs`                | Builder   | A judgement refused the assembled ticket: fill `{{task}}` and `{{report}}`                                                                                                                                                                            |
@@ -68,12 +67,12 @@ these all use it. How Host wires a slot into a run:
 | `gates/workspace-changed.mjs`   | Gate      | The Attempt left an uncommitted change                                                                                                                                                                                                                |
 | `gates/parent-clean.mjs`        | Gate      | Isolator's Parent working files did not move                                                                                                                                                                                                          |
 | `gates/sensitive-path.mjs`      | Gate      | No path matching a glob was touched                                                                                                                                                                                                                   |
+| `gates/base-diff.mjs`           | Gate      | What the work changed since the line (`--base`): no denied path was touched, or a command holds when a path did |
+| `gates/tests-only.mjs`          | Gate      | Every path the workspace changed matches a glob: the tests, their helpers and the manifest, nothing else |
 | `gates/workspace-unchanged.mjs` | Gate      | A read-only pass changed nothing at all (a file modified, deleted or added)                                                                                                                                                                           |
 | `gates/gitignore-leak.mjs`      | Gate      | The ticket's commits add nothing its own `.gitignore` excludes                                                                                                                                                                                        |
 | `gates/project-checks.mjs`      | Gate      | One command of the Project's own (typecheck, tests, lint, build) exits 0 in the workspace                                                                                                                                                             |
-| `gates/tests-red.mjs`           | Gate      | The tests just written fail, and not on a missing import or a syntax error (`--cmd` with `{files}`, `--test-glob`, `--not-red-when`).                                                                                                                 |
-| `gates/tests-frozen.mjs`        | Gate      | A test file held by the "Tests: " checkpoint was not modified, deleted or renamed (`--test-glob`, `--subject-prefix`)                                                                                                                                 |
-| `gates/e2e.mjs`                 | Gate      | The Feature's acceptance suite, run once on the assembled line: the Project's `--up` / `--ready` / `--run` / `--down`, a JUnit report compared with the manifest of scenario ids, each failing test retried once. |
+| `gates/feature-tests.mjs`       | Gate      | The Feature's own tests, run once on the assembled line: the Project's `--run` filtered on the ids of the manifest, a JUnit report compared with them. |
 | `gates/ci-green.mjs`            | Gate      | The work line's own checks came back green                                                                                                                                                                                                            |
 | `publishers/git.mjs`            | Publisher | Pushes the ticket's branch to the work line's own remote                                                                                                                                                                                              |
 | `refreshers/git.mjs`            | Refresher | Fast-forwards the work line copy onto what the Authority holds                                                                                                                                                                                        |
@@ -105,7 +104,10 @@ others, plus the names given with `--pass-env`), not the operator's whole
 shell; git's credential helpers are cleared for it; and `ssh`, `scp` plus the
 commands given with `--deny-shell` are denied in its own `cli-config.json`,
 rewritten every run. That
-lowers a risk and confines nothing (RESERVATIONS F32). `claude.mjs`
+lowers a risk and confines nothing: the deny list matches command names (`node -e`,
+`env gh` or an absolute path pass), the operator's files stay readable, the login
+keychain is reachable unless `gh` and `security` are denied, and `CURSOR_API_KEY`
+is visible to the agent. Real confinement is issue #36. `claude.mjs`
 needs `claude`, signed in once, and refuses those two flags: Claude is not
 isolated yet, and starting it would keep the operator's own config.
 
@@ -126,7 +128,7 @@ isolated yet, and starting it would keep the operator's own config.
 | `--deny-shell NAME`                | With `--agent-home`, also refuse this command to the vendor (`gh`, `vercel`…). `ssh` and `scp` always are. Repeatable           |
 | `--plugin-dir DIR`                 | A plugin folder of the operator's (a Mason home's `ai-plugins/core/*`). Repeatable, loaded first                                |
 | `--app-deck-profile PATH`          | The app's deck profile for this role, as a path in the checkout: `[<app dir>/].ai/profiles/<name>`. Cursor only; Claude refuses |
-| `--plugins-out DIR`                | Where the profile is built, one folder per profile. Required with `--app-deck-profile`; never the workspace                     |
+| `--plugins-out DIR`                | Where the profile is built, one folder per workspace and profile. Required with `--app-deck-profile`; never the workspace      |
 | `--deck-bin PATH`                  | The deck CLI. Default: the `@pinkpuma/deck` this package depends on                                                             |
 | `--id` / `--attempt` / `--context` | How a transcript is filed. Forwarded by the role                                                                                |
 
@@ -137,7 +139,7 @@ An agent starts with plugin folders, each passed to the vendor as
 project's [deck](https://github.com/tilap/pinkpuma-deck) profile resolves to.
 
 `--app-deck-profile .ai/profiles/builder` runs `deck materialize -C <app dir> --profile builder --out
-<plugins-out>/builder --json` before the vendor starts. The working directory
+<plugins-out>/<workspace>/builder --json` before the vendor starts. The working directory
 is the checkout the agent works on, so a role gets what the project committed
 at that commit — the base `ai-plugin.json` and `.ai/profiles/builder/`, as their
 locks pin them — never what the operator has installed. deck refuses a request
@@ -161,9 +163,12 @@ author did. `cursor-agent` ran a Claude-format one (`${CLAUDE_PLUGIN_ROOT}`,
 `PostToolUse` on edits) on a real run; a hook that runs is part of the agent's
 time and of what it reads back.
 
-deck's cache (`~/.cache/pinkpuma-deck`, or `DECK_CACHE`) has no lock, and
-`--plugins-out` holds one folder per profile: both rely on a Mason run starting
-one agent at a time, which it does.
+deck's cache (`~/.cache/pinkpuma-deck`, or `DECK_CACHE`) has no lock, so agents that
+start together (`ticket.maxParallel` above 1) materialize one after the other: the
+wrapper holds a lock in `--plugins-out` while deck runs, and takes it over when its
+holder is gone. Each workspace has its own folder there, so a running agent's plugins
+are never rewritten by another's start. The folder of a workspace that no longer exists
+is removed the next time an agent starts.
 
 `claude.mjs` takes `--plugin-dir` but refuses `--app-deck-profile`: not isolated, Claude
 also loads the operator's plugins and the project's `.claude/settings.json`, so
@@ -341,6 +346,10 @@ values). Files are
 filed under the Ticket the Task belongs to, named for the Subtask and the
 Attempt. It belongs on the **agent** command, after `--`.
 
+The file is made before the agent starts and grows with its output, then replaced
+by the finished page. An Attempt killed at its ceiling or by an interrupt leaves
+the file as it was: the prompt, the output so far, and `exit: not returned`.
+
 ```yaml
 builder:
   producer:
@@ -375,6 +384,23 @@ Every Gate answers with one JSON object on stdout — `{"verdict":"pass"}`, or
 in, and what mason appends to its argv, is in
 [`@bluewombat/runtime`](../../host/runtime/README.md).
 
+What no Gate can see, by construction:
+
+- `sensitive-path` compares the workspace with `HEAD`, so a Builder that commits
+  its work makes it blind. `workspace-changed` covers that by refusing a workspace
+  with nothing uncommitted; keep both. On the recheck after align the work is
+  committed and `sensitive-path` always passes: use `base-diff --deny GLOB`
+  where the recheck or the Feature must answer.
+- `workspace-unchanged` on `assembly.validate` runs after the Project's own
+  commands: one that writes outside `.gitignore` (coverage, `.tsbuildinfo`, a build
+  directory) reads as the review writing. Allow those paths with `--allow GLOB`.
+- `parent-clean` on a Parent with no `.git` takes the workspace's oldest file as
+  its baseline time: a file newer than that is a leak. It is the only baseline a
+  copy-mode work line has.
+- `workspace-changed` asks whether something changed, not whether the change
+  answers the report: a producer that ignores its report and changes something
+  else passes.
+
 ```yaml
 builder:
   gates:
@@ -399,7 +425,11 @@ it first: every Gate after it then judges work that exists. It passes at
 producer to send back.
 
 `parent-clean` fail-blocks if Isolator's Parent working files changed
-(`--parent DIR`, or the other git worktrees of this Child).
+(`--parent DIR`, plus the main worktree of this Child's repository). Only files written
+after the Child was created count, so an edit that was already there is not a leak. The
+other linked worktrees are sibling Children (parallel tickets, escalated leftovers) and are
+ignored; `--siblings` watches them too, for a serial run. Not covered: an Agent writing
+into a sibling worktree.
 
 `sensitive-path` fail-retries if the workspace changed a path matching a glob.
 `*` is one segment, `**` any depth. It looks at what a fold can carry out of
@@ -407,11 +437,52 @@ the workspace — tracked paths, and new ones `.gitignore` does not exclude —
 what an install left under an ignored directory (a dependency's own `.github/`)
 is not a change to guard.
 
+`base-diff` is `sensitive-path` against the work line instead of `HEAD`. It takes the
+paths that differ between the base and the workspace — the commits since the workspace
+left it (`BASE...HEAD`) and what is on disk and not committed, an ignored path excluded —
+so it still sees the work after the commit, and answers at the unit, the ticket and the
+recheck (`--stage assembly`). The base is the branch checked out in the **main worktree**
+of the repository the workspace belongs to: Isolation makes every workspace a worktree of
+the work line's copy, and Host keeps that copy on the line the work lands on, a
+Feature's own line while a Feature is open. In a Ticket of a Feature the diff is therefore
+the Ticket's own, not the Feature's so far. `--base REF` names another ref instead; a
+hand-named `main` is the copy's local branch, which Host does not move (the Refresher
+moves the Feature's line), so it can be weeks old. Two uses, alone or together:
+
+```yaml
+- id: no-workflow-edit
+  argv: [node, ./node_modules/@bluewombat/slots/gates/base-diff.mjs, --deny, ".github/workflows/**"]
+- id: e2e-when-app-changes
+  timeoutMs: 600000
+  argv:
+    - node
+    - ./node_modules/@bluewombat/slots/gates/base-diff.mjs
+    - --when
+    - "src/**"
+    - --run
+    - "npm run e2e"
+```
+
+`--deny GLOB` (repeatable) fail-retries when a changed path matches. `--when GLOB`
+(repeatable) with `--run COMMAND` hands the command to `project-checks` when a changed path
+matches (so it is cleaned, bounded by the Gate's ceiling and classified as every command of
+the Project is) and answers as it does; `MASON_BASE` is the base and `MASON_CHANGED_FILES`
+the changed paths one per line. When nothing matches it passes without running it. It
+fail-blocks where there is no base to derive: the workspace is the main worktree itself,
+the main worktree has no branch (detached), a `--base` the workspace lacks, and
+`--stage feature` without `--base` — the Feature's workspace is its line with the target
+merged in, so the line would show the target's work; name the target there.
+
+`tests-only` is its counterpart: it fail-retries if the workspace changed a path that matches
+none of the globs (added, modified, deleted or renamed, tracked or new and not ignored). It is
+the Gate of the feature-test Ticket, whose tests sit among the Project's code
+(`**/*.test.ts`), where a list of denied paths cannot say "everything but tests".
+
 `project-checks --cmd COMMAND` runs one command of the Project's own in the workspace
 and answers on its exit code. It is the Gate that makes a machine, not the Builder,
 say that the code typechecks and the tests pass. The command goes through the shell,
 so it is written as the Project writes it; it knows no stack.
-The report carries the end of the output, cleaned as it arrives: escape codes removed, a line redrawn with `\r` reduced to its last state, and spinner or progress lines (`[⣷] Pulling schema...`) dropped, so thousands of redraws cannot push the real error out of the tail. `tests-red` reads its output the same way.
+The report carries the end of the output, cleaned as it arrives: escape codes removed, a line redrawn with `\r` reduced to its last state, and spinner or progress lines (`[⣷] Pulling schema...`) dropped, so thousands of redraws cannot push the real error out of the tail. `feature-tests` reads its output the same way.
 
 ```yaml
 - id: typecheck
@@ -502,82 +573,91 @@ the variable holding a token that can read the checks — the same one the
 manager's `tokenEnv` names. It has no default on purpose: `GITHUB_TOKEN` is
 what `gh` reads ahead of its own login, so an operator must not export it,
 and a Gate that fell back to it refused only at the first assembly of a real
-run. `--remote`, `--poll-ms` and `--api-base` (GitHub Enterprise) are there too. It talks to GitHub, and knows
+run. `--remote`, `--poll-ms` and `--api-base` (GitHub Enterprise) are there too.
+`--require-check NAME` (repeatable) names a check that must exist and have succeeded:
+the check run (or status context) called exactly `NAME`. The general rule counts a
+`skipped` or `neutral` run as green, so an e2e job skipped for want of its secrets lets the
+line through; a required one that settled so is `fail-blocking`: the work cannot make it run, so a person reads it, not a fix agent. One not created yet is
+waited for like `--require-checks`, and at the ceiling the CI did not answer
+(`fail-blocking`). A name is exact: a matrix job is one check per cell (`e2e (chrome)`), and each is listed. It talks to GitHub, and knows
 nothing about `@bluewombat/manager-github`: a Project may run either one
 without the other.
 
-`sensitive-path`, `workspace-changed`, `gitignore-leak` and `ci-green` need a git workspace, which
+`sensitive-path`, `base-diff`, `workspace-changed`, `gitignore-leak` and `ci-green` need a git workspace, which
 is what Isolator makes when WorkLineStable is a git tree. They fail-block on a
 workspace Isolator had to copy.
 
-### The e2e acceptance suite
+### The feature tests
 
-`e2e.mjs` runs a Feature's acceptance suite on the assembled Feature line, from a Feature Gate
-(`feature.validate.gates`). It knows no stack: the Project supplies four commands, run through
-the shell in the workspace, and the Gate starts, waits, runs, compares and always stops.
+`feature-tests.mjs` runs the tests of a Feature on the assembled Feature line, from a Feature Gate
+(`feature.validate.gates`). Only the scenarios of this Feature run, not the Project's whole suite. It
+knows no stack and starts no application: the Project supplies one command, run through the shell
+in the workspace, and the Gate runs it, compares and judges.
 
 | Option | Meaning |
 | --- | --- |
-| `--up CMD` | Required. Starts the application. It may return once started or keep running; the Gate does not wait for it, it waits for `--ready`. An `--up` that exits non-zero before that is a start failure |
-| `--ready CMD` | Required. Exit 0 when the application answers. Polled every second until `--start-timeout-ms` |
-| `--run CMD` | Required. Runs the suite and writes a JUnit XML report to `--junit` |
-| `--rerun CMD` | Runs the failed scenarios again; `{ids}` is their ids joined with `\|` (a regular expression, `pnpm e2e --grep "{ids}"`). Absent: `--run` again, whole |
-| `--down CMD` | Required. Stops the application. Always run, whatever happened; the process group of `--up` is killed after it |
-| `--manifest PATH` | The scenarios the suite must hold. Default `e2e/scenarios.json`: an array of ids, or `{ "scenarios": [ "E1" \| { "id": "E1", "title": "…" } ] }` |
-| `--junit PATH` | Where `--run` writes its report. Default `e2e/results/junit.xml`. Removed before every run, so an old report is never read |
-| `--server-log PATH` | The application's log, whose tail goes in a red report. Default: what `--up` printed |
-| `--max-scenarios N` | The most scenarios a suite may hold. Default 5 |
-| `--max-run-ms N` | The most the whole Gate may take. Default 600000 (10 minutes), and never more than the Gate's own ceiling less 25 s |
-| `--start-timeout-ms N` | The most `--up` and `--ready` may take together. Default 120000 |
-| `--host HOST` | Handed to every command as `E2E_HOST`. Default `127.0.0.1`; any non-loopback address is refused |
-| `--port N` | Handed to every command as `E2E_PORT`. Absent: the application's own choice |
-
-Every command also gets `E2E_DATA_DIR`, an empty directory made for the run and removed after it
-(the data is disposable), and `E2E_RESULTS_DIR`, the folder of `--junit`. A secret is not an
-option of the Gate: the commands read it from the environment mason was started in, and it
-belongs in no file of the repository.
-
-A scenario is a manifest id, and every test carries its id in its name (`E2 pays by card`). The
+| `--run CMD` | Required. Runs the tests of the Feature and writes a JUnit XML report. `{ids}` is the ids of the manifest joined with `\|` (a regular expression, `pnpm test --grep "{ids}"`), `{junit}` the path of the report |
+| `--manifest PATH` | The scenarios of the Feature. Default `feature-tests/scenarios.json`: an array of ids, or `{ "scenarios": [ "S1" \| { "id": "S1", "title": "…" } ] }` |
+| `--junit PATH` | Where `--run` writes its report. Default `feature-tests/results/junit.xml`. Removed before every run, so an old report is never read |
+| `--max-run-ms N` | The most the whole Gate may take. Default 600000 (10 minutes), and never more than the Gate's own ceiling less 5 s |
+
+A scenario is a manifest id, and every test carries its id in its name (`S2 pays by card`). The
 comparison is exact: an id with no test, a test with no manifest id, and a test the runner
-skipped are failures. A failing test is run once more: a pass then is reported `UNSTABLE`, and
-is not a refusal; failing twice is red. The verdict:
+skipped are failures. There is no retry.
+
+The report must therefore hold **only** the Feature's scenarios. A name filter is enough only for a
+runner that leaves the filtered-out tests out of its report. A runner that lists them as `skipped`
+(Vitest with `-t` does) puts tests with no manifest id in the report, and the Gate refuses the run
+(`tests that carry no id of the manifest`): restrict the files the command loads as well, for
+example to the files that hold the Feature's tests by a naming convention.
+
+```yaml
+# Vitest: only the *.feature.test.ts files are loaded, then only the manifest's scenarios run
+- pnpm exec vitest run .feature.test.ts -t "{ids}" --reporter=junit --outputFile={junit}
+```
+
+`{ids}` and `{junit}` are both required in `--run`; `mason doctor` warns when one is missing. The verdict:
 
 | Verdict | When |
 | --- | --- |
-| `pass` | Every scenario ran and passed. The report says how many and which, and which were unstable |
-| `fail-retryable` | Red: the report has, per scenario, its id, the test, the step (`at`), the message, the trace path when the runner saved one, then the last 40 lines of the server log. Screenshots and traces stay on disk beside the report. The suite is frozen; the application is the producer's to repair. Also a runner that crashed before writing a report |
-| `fail-blocking` | What no change to the application fixes: a missing, empty or oversized manifest, an application that does not start or is never ready, a run or a retry that outlives the ceiling, a suite that exits 0 and writes no report, a non-loopback `--host` |
+| `pass` | Every scenario ran and passed. The report says how many and which |
+| `fail-retryable` | Red: the report has, per scenario, its id, the test, the step (`at`) and the message. Whether the test or the application is wrong is for the caller to say: the feature-test Ticket's author reads the report to fix its tests, and the Feature's fix repairs the application with the tests frozen. Also a runner that crashed before writing a report, and tests that carry no id of the manifest |
+| `fail-blocking` | What no change to the application fixes: a missing, empty or malformed manifest, a run that outlives the ceiling, a run that exits 0 and writes no report |
 
-The Project's `.gitignore` excludes the results folder (`e2e/results/`): a Gate that guards the
-suite folder (`sensitive-path e2e/**` in `feature.fix.gates`) would read the report as a change.
+The Project's `.gitignore` excludes the results folder (`feature-tests/results/`): a Gate that guards
+the folder (`sensitive-path feature-tests/**` in `feature.fix.gates`) would read the report as a change.
 
 ```yaml
-- id: e2e
-  skipWhen: skip-test-e2e   # Host's: not run for a Feature that carries the label
+- id: feature-tests
+  skipWhen: skip-feature-test   # Host's: not run for a Feature that carries the label
   timeoutMs: 720000
   argv:
     - node
-    - ./node_modules/@bluewombat/slots/gates/e2e.mjs
-    - --up
-    - pnpm e2e:up
-    - --ready
-    - pnpm e2e:ready
+    - ./node_modules/@bluewombat/slots/gates/feature-tests.mjs
     - --run
-    - pnpm e2e
-    - --down
-    - pnpm e2e:down
+    - pnpm test --grep "{ids}" --reporter=junit --outputFile={junit}
 ```
 
 ## Publishers
 
 The slot that puts an assembled ticket where the Authority can read it. It runs
 **in the work line**, and mason appends `--id`, `--ref` — the name Isolator gave
-the ticket — and `--target`, the work line it is offered to.
-
-`git.mjs` pushes that name to the work line's own remote. A plain push, no force
-of any kind: Integrator only ever adds history, so republishing after a refusal
-is a fast-forward. A rejection means the name moved under us, which is the one
-case worth refusing rather than overwriting.
+the ticket — `--target`, the work line it is offered to, and `--kind` (`ticket`, or
+`line` for a Feature's own line).
+
+`git.mjs` pushes the Ticket's result to the work line's own remote under that
+name: one commit, made from the branch's tree on top of the work line's tip
+(`--target`), not the branch's history. The workspace is snapshotted at every
+integration, so a blob an install added and a repair removed would otherwise
+travel with it and make a pack the remote refuses. The work line remembers what
+it published (`refs/published/<ref>`) and a resubmission continues it, so the
+push stays a fast-forward; the same tree on the same line publishes nothing new.
+A plain push, no force of any kind: a rejection means the name moved under us,
+which is the one case worth refusing rather than overwriting.
+
+With `--kind line`, which Host passes when a Feature closes, the ref is pushed as
+it is: a Feature's line is the history the Authority built by folding Tickets
+into it, already on the remote, so the push is a fast-forward of it.
 
 It takes no option, and the remote is `origin`. After the Authority folds, Host
 reads the work line back from `origin` on its own, with no way to learn what this
@@ -650,7 +730,7 @@ type in JSDoc.
 ```
 README.md      this file
 agents/        vendor CLIs: filled prompt in, serialized run out
-builders/      first-pass and repair roles for the unit of work, and the e2e Ticket's
+builders/      first-pass and repair roles for the unit of work, and the feature-test Ticket's
 ticket/        fix and validate for an assembled ticket
 feature/       fix for a whole feature
 lib/           what the shipped templates say, shared by the roles
@@ -659,3 +739,12 @@ messages/      what a commit says: a rule, or an agent under the team's guidelin
 test/          one suite per kind; each spawns the real command
 fixtures/      fake agent CLIs the Builder suites run against
 ```
+
+## Copy mode
+
+A work line isolated by `@bluewombat/isolation-copy` has no `.git`. The slots
+that read git need one: the `git` Publisher and Refresher,
+`messages/git-producer`, and the Gates `workspace-changed`, `workspace-unchanged`,
+`sensitive-path`, `base-diff`, `ci-green`, `gitignore-leak` and `tests-only`. A
+copy-mode Project uses `parent-clean`, `project-checks` and `feature-tests`, and
+brings its own Publisher and Gates for what it hands over.

package/agents/agent-plugins.mjs

@@ -1,5 +1,14 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { createRequire } from "node:module";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { listOption, textOption } from "@bluewombat/slot-kit";
@@ -13,15 +22,18 @@ import { listOption, textOption } from "@bluewombat/slot-kit";
 //                         checkout: `[<app dir>/].ai/profiles/<name>`. The base
 //                         and that profile, as the app's locks pin them
 //   --plugins-out DIR     where the profile is materialized, one folder per
-//                         profile. Required with --app-deck-profile: never the
+//                         workspace and profile (<DIR>/<workspace>/<profile>).
+//                         Required with --app-deck-profile: never the
 //                         workspace, whose tree the Gates read
 //   --deck-bin PATH       the deck CLI. Default: the @pinkpuma/deck this
 //                         package depends on
 //
 // The profile is read from the working directory — the checkout the agent
 // works on — so a role gets what the project committed at that commit, not
-// what the operator has installed. Agents of one Mason run one at a time,
-// which is why one folder per profile is enough.
+// what the operator has installed. Agents of one Mason may run side by side
+// (ticket.maxParallel above 1): each workspace has its own folder, so one
+// agent's plugins are never rewritten under another, and the runs of deck
+// that fill them take turns, because deck's cache has no lock of its own.
 
 const PROFILE_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
 
@@ -111,19 +123,34 @@ export function loadPlugins(options, cwd) {
   if (!deck.ok) {
     return deck;
   }
+  const outRoot = resolve(cwd, out);
   const args = [
     deck.path,
     "materialize",
     "-C",
     appDir,
     "--out",
-    resolve(cwd, out, profile),
+    join(outRoot, workspaceSegment(cwd), profile),
     "--json",
     ...(hasProfile ? ["--profile", profile] : []),
   ];
   // No timeout: this runs inside the agent wrapper's own process group, so
   // the slot's deadline ends deck with it.
-  const run = spawnSync(process.execPath, args, { cwd, encoding: "utf8" });
+  /** @type {import("node:child_process").SpawnSyncReturns<string>} */
+  let run;
+  try {
+    run = takingTurns(outRoot, () => {
+      retireStaleFolders(outRoot);
+      markWorkspace(outRoot, cwd);
+      return spawnSync(process.execPath, args, { cwd, encoding: "utf8" });
+    });
+  } catch (error) {
+    const said = error instanceof Error ? error.message : String(error);
+    return {
+      ok: false,
+      reason: `deck materialize could not start for profile ${profile}: ${said}`,
+    };
+  }
   if (run.error !== undefined || run.status !== 0) {
     const said = (run.stderr || run.error?.message || `exit ${run.status}`).trim();
     return {
@@ -146,6 +173,127 @@ export function loadPlugins(options, cwd) {
   };
 }
 
+const WORKSPACE_MARK = ".workspace";
+const LOCK_NAME = ".materialize.lock";
+const LOCK_WAIT_MS = 10 * 60 * 1000;
+const LOCK_CREATION_GRACE_MS = 10 * 1000;
+
+/**
+ * The folder under `--plugins-out` that belongs to one workspace: the same
+ * name every time the same directory asks, a different one for each directory.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function workspaceSegment(cwd) {
+  return createHash("sha256").update(resolve(cwd)).digest("hex").slice(0, 12);
+}
+
+/**
+ * Record whose folder this is, so that it can be dropped once the workspace is gone.
+ *
+ * @param {string} outRoot
+ * @param {string} cwd
+ */
+function markWorkspace(outRoot, cwd) {
+  const folder = join(outRoot, workspaceSegment(cwd));
+  mkdirSync(folder, { recursive: true });
+  writeFileSync(join(folder, WORKSPACE_MARK), `${resolve(cwd)}\n`);
+}
+
+/**
+ * Drop the folders of workspaces that no longer exist (a ticket that landed
+ * clears its own). Only a folder that carries the mark is touched.
+ *
+ * @param {string} outRoot
+ */
+function retireStaleFolders(outRoot) {
+  let names;
+  try {
+    names = readdirSync(outRoot);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const folder = join(outRoot, name);
+    let owner;
+    try {
+      owner = readFileSync(join(folder, WORKSPACE_MARK), "utf8").trim();
+    } catch {
+      continue;
+    }
+    if (owner.length > 0 && !existsSync(owner)) {
+      rmSync(folder, { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * Run `work` while holding the lock of `outRoot`: two agents starting together
+ * materialize one after the other, since deck's cache has no lock. A lock whose
+ * holder is gone is taken over.
+ *
+ * @template T
+ * @param {string} outRoot
+ * @param {() => T} work
+ * @returns {T}
+ */
+function takingTurns(outRoot, work) {
+  mkdirSync(outRoot, { recursive: true });
+  const lock = join(outRoot, LOCK_NAME);
+  const giveUpAt = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      mkdirSync(lock);
+      break;
+    } catch (error) {
+      if (/** @type {NodeJS.ErrnoException} */ (error).code !== "EEXIST") {
+        throw error;
+      }
+    }
+    if (holderGone(lock)) {
+      rmSync(lock, { recursive: true, force: true });
+      continue;
+    }
+    if (Date.now() > giveUpAt) {
+      throw new Error(`another agent held ${lock} for more than ${LOCK_WAIT_MS / 60000} minutes`);
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+  }
+  try {
+    writeFileSync(join(lock, "pid"), String(process.pid));
+    return work();
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Whether the process that took `lock` is gone. A lock with no pid yet was
+ * just made: it is given a few seconds to say whose it is.
+ *
+ * @param {string} lock
+ * @returns {boolean}
+ */
+function holderGone(lock) {
+  let pid;
+  try {
+    pid = Number(readFileSync(join(lock, "pid"), "utf8"));
+  } catch {
+    try {
+      return Date.now() - statSync(lock).mtimeMs > LOCK_CREATION_GRACE_MS;
+    } catch {
+      return false;
+    }
+  }
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return /** @type {NodeJS.ErrnoException} */ (error).code === "ESRCH";
+  }
+}
+
 /**
  * The filled prompt, then the project's own words for this role.
  *

package/agents/claude.mjs

@@ -116,7 +116,8 @@ const transcript = transcriptFor(process.argv, options, {
   prompt,
   plugins,
 });
-const run = await runAgent({ file: bin, args, cwd });
+transcript.start();
+const run = await runAgent({ file: bin, args, cwd, onOutput: transcript.tap });
 const extras = extrasFromClaude(run.stdout, outputFormat, cwd);
 transcript.write(run, extras);
 answer(run, bin, extras);

package/agents/cursor.mjs

@@ -143,10 +143,12 @@ const transcript = transcriptFor(process.argv, options, {
   prompt,
   plugins,
 });
+transcript.start();
 const run = await runAgent({
   file: bin,
   args,
   cwd,
+  onOutput: transcript.tap,
   ...(isolation.env === undefined ? {} : { env: isolation.env }),
 });
 const extras = extrasFromCursor(run.stdout, outputFormat, cwd);