@bluewombat/slots 0.7.0 → 0.9.0

package/README.md

@@ -1,11 +1,9 @@
 # Slots
 
-The Planner, Builder, and Gate commands that ship with mason. A Project points
+The Builder, Gate, and publishing commands that ship with mason. A Project points
 its config at one of these paths; nothing here is imported.
 
 ```yaml
-planner:
-  cmd: [node, ./node_modules/@bluewombat/slots/planners/one-subtask.mjs]
 builder:
   producer:
     cmd:
@@ -52,7 +50,6 @@ these all use it. How Host wires a slot into a run:
   - [The rules](#the-rules)
   - [Transcripts](#transcripts)
 - [Gates](#gates)
-- [Planners](#planners)
 
 ## Catalogue
 
@@ -60,21 +57,19 @@ 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/producer.mjs`       | Builder   | First pass of a Subtask: fill `{{task}}`, then spawn the agent                             |
-| `builders/repair.mjs`         | Builder   | A Gate refused the Subtask: fill `{{task}}` and `{{report}}`                               |
-| `assembly/fix.mjs`            | Builder   | A judgement refused the assembled feature: fill `{{task}}` and `{{report}}`                |
-| `assembly/validate.mjs`       | Builder   | Read-only review of the assembled feature: fill `{{task}}`; answers `MASON_VERDICT: VALIDATED` or `MASON_VERDICT: REFUSED: …` |
+| `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}}`                               |
+| `assembly/fix.mjs`            | Builder   | A judgement refused the assembled work: fill `{{task}}` and `{{report}}`                |
+| `assembly/validate.mjs`       | Builder   | Read-only review of the assembled work: fill `{{task}}`; answers `MASON_VERDICT: VALIDATED` or `MASON_VERDICT: REFUSED: …` |
 | `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/gitignore-leak.mjs`    | Gate      | The feature's commits add nothing its own `.gitignore` excludes                            |
+| `gates/gitignore-leak.mjs`    | Gate      | The ticket's commits add nothing its own `.gitignore` excludes                            |
 | `gates/ci-green.mjs`          | Gate      | The work line's own checks came back green                                                 |
-| `planners/one-subtask.mjs`    | Planner   | Bootstrap: one Subtask that is the FeatureStandard itself                                  |
-| `publishers/git.mjs`          | Publisher | Pushes the feature's branch to the work line's own remote                                  |
+| `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                             |
-| `planners/producer.mjs`       | Planner   | An agent CLI splits the FeatureStandard                                                    |
-| `messages/conventional.mjs`   | Message   | `<type>: <title>` for the feature's fold, no agent; `--scope`, `--type`                    |
-| `messages/git-producer.mjs`   | Describer | An agent reads the git diff and writes the feature's subject and body under `--rules-file` |
+| `messages/conventional.mjs`   | Message   | `<type>: <title>` for the ticket's fold, no agent; `--scope`, `--type`                    |
+| `messages/git-producer.mjs`   | Describer | An agent reads the git diff and writes the ticket's subject and body under `--rules-file` |
 
 ## Agents
 
@@ -95,7 +90,13 @@ or `--report`. A role slot after `--` is what names one:
 `cursor.mjs` needs `cursor-agent` on PATH. Without `--agent-home` it uses the
 CLI's own login (`cursor-agent login`). With `--agent-home DIR` and
 `--api-key-env NAME` the vendor process gets that directory as `HOME` and
-`CURSOR_API_KEY` from `NAME`; the value never appears on the argv. `claude.mjs`
+`CURSOR_API_KEY` from `NAME`; the value never appears on the argv. It also gets
+a short environment (`PATH`, locale, proxy and certificate variables and a few
+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`
 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.
 
@@ -112,6 +113,8 @@ isolated yet, and starting it would keep the operator's own config.
 | `--agent-arg VALUE`                | Appended to the CLI argv, before the prompt. Repeatable                          |
 | `--agent-home DIR`                 | Isolate the vendor process: its `HOME` is this directory. Cursor only; Claude refuses |
 | `--api-key-env NAME`               | With `--agent-home`, read `process.env[NAME]` for the vendor key. Never the value itself |
+| `--pass-env NAME`                  | With `--agent-home`, also hand the vendor this environment variable. Repeatable |
+| `--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 |
 | `--profile NAME`                   | The project's deck profile for this role, read in the working directory. Cursor only; Claude refuses |
 | `--plugins-out DIR`                | Where `--profile` is built, one folder per profile. Required with `--profile`; never the workspace |
@@ -229,24 +232,40 @@ builder:
 ```
 
 A path that names a file next to the config resolves against the config; any
-other relative path resolves inside the Subtask workspace, so a template
+other relative path resolves inside the workspace, so a template
 committed in the Project travels with it.
 
 Each role owns a closed set. An unknown name, or a required name the template
-never places, is `fail-blocking`. `{{done_when}}` is `Done when:` plus the
-definition of done, and vanishes whole when there is none — which is every
-assembly, so `assembly/fix` does not fill it at all.
+never places, is `fail-blocking`.
 
 | Role                | Required                              | Also fills                                                 |
 | ------------------- | ------------------------------------- | ---------------------------------------------------------- |
-| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{done_when}}`, `{{id}}`, `{{attempt}}`                   |
-| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{done_when}}`, `{{id}}`, `{{attempt}}` |
-| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{refused_by}}`, `{{id}}`, `{{attempt}}`                  |
+| `builders/producer` | `{{task}}`, `{{rules}}`               | `{{history}}`, `{{id}}`, `{{attempt}}`                     |
+| `builders/repair`   | `{{task}}`, `{{report}}`, `{{rules}}` | `{{history}}`, `{{refused_by}}`, `{{id}}`, `{{attempt}}`    |
+| `assembly/fix`      | `{{task}}`, `{{report}}`, `{{rules}}` | `{{history}}`, `{{refused_by}}`, `{{id}}`, `{{attempt}}`   |
 | `assembly/validate` | `{{task}}`, `{{rules}}`               | `{{id}}`, `{{attempt}}`                                    |
 
 A first-pass command that receives `--report` is `fail-blocking`: that report
 belongs to the repair command. A repair or fix command without `--report` is the same.
 
+`{{history}}` is what the Task went through before this Attempt, oldest first (the
+refusal it came with, each Attempt, each Gate's answer; see Implementer's SPECS §
+History). It is empty on a first Attempt and vanishes whole then, so a template
+that does not place it simply omits it.
+
+### The way out
+
+Every shipped producer prompt ends with the same exit: when what the agent was
+given is not enough to act on, it changes nothing and ends its final message with
+one line, `MASON_BLOCKED: <what is missing>`. The slot reads the last such line
+in the agent's final message, and answers `fail-blocking` with that reason, so the
+Task stops as `escalated` and a person reads it instead of another Attempt
+inventing a change. This is the same kind of signal as `assembly/validate`'s
+`MASON_VERDICT:` line, and it is not tied to any refuser. A clean exit prints
+`{ "said": "<the agent's final message, clipped>" }` on stdout, which the Task
+keeps for its History. A Project's own template should keep a paragraph that
+tells the agent about the line, or the agent has no way to use it.
+
 ### The repair prompt
 
 A pass a Gate refused is a different job from a first pass: not "do this" but
@@ -259,10 +278,9 @@ a run spent on nothing. A command that arrives with a report and no
 
 ### The fix prompt
 
-A judgement of the assembled feature that refused it is not a Subtask retry.
-The units already passed. `assembly/fix.mjs` tells the agent to change what the
-refusal names and leave the rest. Same placeholders as repair except
-`{{done_when}}`, which an assembly has nothing to fill.
+A judgement of the assembled work that refused it is not a retry of the unit.
+The unit already passed. `assembly/fix.mjs` tells the agent to change what the
+refusal names and leave the rest. Same placeholders as repair.
 
 ### The validate prompt
 
@@ -293,7 +311,7 @@ nothing pushed. A producing template must place it — one that leaves it out is
 Gates are what says no, which is slower, reaches the tracker, and spends a run.
 
 `--rules-file` replaces them with the Project's own. The last three are not a
-matter of taste: the Gates read the working tree of the Subtask directory, so an
+matter of taste: the Gates read the working tree of the workspace, so an
 agent that commits, stashes or writes elsewhere leaves them nothing to see and
 the pass is refused for having done nothing. Replacing the rules does not lift
 that; it only stops saying it out loud.
@@ -309,7 +327,7 @@ loop that misbehaves cannot be read back, only guessed at.
 as sent, stdout, stderr, how long it took, and — when the agent wrapper passed
 them — `skills`, `usage` and what the tools did (`unknown`, `(none)`, or the
 values). Files are
-filed under the Feature the Task belongs to, named for the Subtask and the
+filed under the Ticket the Task belongs to, named for the Subtask and the
 Attempt. It belongs on the **agent** command, after `--`.
 
 ```yaml
@@ -378,15 +396,15 @@ 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.
 
-`gitignore-leak --base REF` fail-retries if the feature's commits add a path the
+`gitignore-leak --base REF` fail-retries if the ticket's commits add a path the
 workspace's own `.gitignore` excludes — a Builder's `node_modules/`, a build's
-`dist/`, a generated file. `REF` is the work line the feature is offered to
-(`main`): only what the feature adds since it left that line is judged, and
-only what is committed, so a path tracked on purpose before the feature began
+`dist/`, a generated file. `REF` is the work line the ticket is offered to
+(`main`): only what the ticket adds since it left that line is judged, and
+only what is committed, so a path tracked on purpose before the ticket began
 is not blamed on it, and a removal staged but not committed does not pass. The
 report is written for `assembly.fix`: untrack the paths, or change `.gitignore`
 if tracking one is the point. It passes at `--stage unit`, where no commit
-holds a Subtask's work yet.
+holds a the unit's work yet.
 
 It is a second line, not the first: the `isolation-git` fold already keeps an
 ignored path out of the commits it makes. It catches a leak that came some
@@ -420,7 +438,7 @@ the work in front of the checks did that before the Gate ran; a workspace
 with nothing published is `fail-blocking`, because no Attempt of that Task
 can change it.
 
-It waits while checks are running, so give it a ceiling of its own. On a red
+It waits while checks are running, so give it a ceiling of its own (the Gate's `timeoutMs`, which Implementer passes to it as `--timeout-ms`). A CI that does not answer is not a refusal of the work: a Gate killed by its clock reads as one, and a refusal sends the work to a producer with nothing to fix. So a few seconds before the ceiling, with no check yet or checks still running, `ci-green` answers `fail-blocking` itself, saying what it was waiting for and for how long, and a person reads it. A check that failed still refuses at once, with its reason. On a red
 check the report carries the failing job's log, cut at the error the runner
 marked — a check name and the word "failure" tell the next Attempt nothing it
 can act on. Right after a push the checks may not be created yet, and an empty
@@ -438,47 +456,11 @@ without the other.
 is what Isolator makes when WorkLineStable is a git tree. They fail-block on a
 workspace Isolator had to copy.
 
-## Planners
-
-`one-subtask.mjs` is the bootstrap Planner: one Subtask that is the
-FeatureStandard itself. It is what `mason init` writes into a fresh config, and
-it takes no option.
-
-`planners/producer.mjs` hands the split to an agent CLI. It reads the project
-before answering and writes nothing into it. `--prompt-file` and `--read` belong
-on the role; the vendor is named after `--`, the same way a Builder names it.
-
-```yaml
-planner:
-  cmd:
-    - node
-    - ./node_modules/@bluewombat/slots/planners/producer.mjs
-    - --read
-    - ./work-line-stable
-    - --
-    - node
-    - ./node_modules/@bluewombat/slots/agents/cursor.mjs
-  timeoutMs: 600000
-```
-
-| Option               | Meaning                                                       |
-| -------------------- | ------------------------------------------------------------- |
-| `--read PATH`        | The project the agent may read before splitting. Default: cwd |
-| `--prompt-file PATH` | Prompt template. Must place `{{intention}}` and `{{out}}`     |
-
-`--bin`, `--model`, `--transcript-dir` and `--agent-arg` are the agent's, after
-`--`. Optional placeholder: `{{max_units}}`.
-
-A Plan it cannot use — a cycle, a dangling dependency, more Subtasks than
-`--max-units` — is this slot's own failure: it exits non-zero so the Breakdown is
-retried. A FeatureStandard that cannot be split is a refusal on stdout, which
-is a verdict on the intention instead.
-
 ## Publishers
 
-The slot that puts an assembled feature where the Authority can read it. It runs
+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 feature — and `--target`, the work line it is offered to.
+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
@@ -493,12 +475,12 @@ read another. It comes back when that half is a slot too.
 The answer is one JSON object on stdout, like every slot:
 
 ```json
-{ "ref": "issue/feature-42" }
+{ "ref": "issue/ticket-42" }
 { "outcome": "refused", "reason": "the remote rejected the push" }
 ```
 
 The reference is opaque above this line — a branch, a directory, a URL. Whatever
-the Publisher answers is what the FeatureManager is told to judge, so a Project
+the Publisher answers is what the TicketTracker is told to judge, so a Project
 that places its work some other way writes its own Publisher and changes nothing
 else. A refusal stops the Submission and travels back to the tracker; a slot that
 could not run at all exits non-zero and says why on stderr.
@@ -556,12 +538,11 @@ type in JSDoc.
 ```
 README.md      this file
 agents/        vendor CLIs: filled prompt in, serialized run out
-builders/      first-pass and repair roles for a Subtask
-assembly/      the same two roles for the assembled feature
+builders/      first-pass and repair roles for the unit of work
+assembly/      the same two roles for the assembled work
 lib/           what the shipped templates say, shared by the roles
 gates/         checks on the workspace, and on the work line
-planners/      FeatureStandard in, a Plan out
 messages/      what a commit says: a rule, or an agent under the team's guideline
 test/          one suite per kind; each spawns the real command
-fixtures/      fake agent CLIs the Builder and Planner suites run against
+fixtures/      fake agent CLIs the Builder suites run against
 ```

package/agents/cursor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import {
   AGENT_OPTIONS,
   findExecutable,
@@ -30,6 +30,12 @@ import { extrasFromCursor } from "./cursor-extras.mjs";
 //   --agent-home DIR      isolate this process: HOME is DIR, not the operator's
 //   --api-key-env NAME    required with --agent-home. Read process.env[NAME];
 //                         the value is never put on the argv
+//   --pass-env NAME       with --agent-home: also hand the vendor this variable
+//                         of the operator. Repeatable. The vendor otherwise
+//                         gets a short list (KEPT_ENV), not the whole environment
+//   --deny-shell NAME     with --agent-home: also refuse this command to the
+//                         vendor (`gh`, `vercel`…). Repeatable. ssh and scp are
+//                         always refused
 //   --plugin-dir / --profile / --plugins-out / --deck-bin   plugin folders,
 //                         see agent-plugins.mjs
 //   --id / --attempt / --context   how a transcript is filed
@@ -38,6 +44,45 @@ const NAME = "Cursor CLI";
 const CLI_NAMES = ["cursor-agent", "agent"];
 const INSTALL_DIRS = [join(homedir(), ".local/bin"), join(homedir(), ".cursor/bin")];
 
+/**
+ * What the vendor gets of the operator's environment, besides what this file
+ * sets itself: enough to find tools, name the locale and reach the network.
+ * Tokens, agent sockets and the rest of an interactive shell stay with the
+ * operator; a Project that needs one more names it with `--pass-env`.
+ */
+const KEPT_ENV = [
+  "PATH",
+  "TERM",
+  "LANG",
+  "LC_ALL",
+  "LC_CTYPE",
+  "TZ",
+  "TMPDIR",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "PNPM_HOME",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "NO_PROXY",
+  "http_proxy",
+  "https_proxy",
+  "no_proxy",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "NODE_EXTRA_CA_CERTS",
+];
+
+/**
+ * Commands refused to the vendor whatever the Project says: the ones that
+ * reach for the operator's own logins through a socket or a key. A Project adds
+ * its own with `--deny-shell` (the GitHub CLI reads a keychain whatever HOME
+ * is; `security` is macOS only; each machine has its own). The vendor's
+ * permission list refuses a command even under `--force`. It is a list of
+ * names, not a sandbox: `python -c` goes round it.
+ */
+const DENIED_SHELL = ["ssh", "scp"];
+
 const cwd = process.cwd();
 
 const parsed = parseOptions(process.argv.slice(2), AGENT_OPTIONS, NAME);
@@ -142,42 +187,93 @@ function cursorIsolation(options, dir) {
       reason: `The environment variable ${keyEnv} is empty. An isolated Cursor agent needs it, or the CLI tries to store credentials in the login keychain.`,
     };
   }
-  return { ok: true, env: isolatedVendorEnv(resolve(dir, home), apiKey) };
+  const passEnv = listOption(options, "passEnv");
+  const bad = passEnv.find((name) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name));
+  if (bad !== undefined) {
+    return { ok: false, reason: `--pass-env must name an environment variable, not "${bad}".` };
+  }
+  const denyShell = listOption(options, "denyShell");
+  const badCommand = denyShell.find((name) => !/^[A-Za-z0-9._+-]+$/.test(name));
+  if (badCommand !== undefined) {
+    return {
+      ok: false,
+      reason: `--deny-shell must name a command, not "${badCommand}".`,
+    };
+  }
+  const agentHome = resolve(dir, home);
+  const env = isolatedVendorEnv(agentHome, apiKey, passEnv);
+  denyShellCommands(agentHome, denyShell);
+  return { ok: true, env };
 }
 
 /**
  * @param {string} agentHome
  * @param {string} apiKey
+ * @param {readonly string[]} passEnv
  * @returns {NodeJS.ProcessEnv}
  */
-function isolatedVendorEnv(agentHome, apiKey) {
+function isolatedVendorEnv(agentHome, apiKey, passEnv) {
   mkdirSync(agentHome, { recursive: true });
   const parentHome = homedir();
   /** @type {NodeJS.ProcessEnv} */
-  const env = { ...process.env, HOME: agentHome };
-  if (process.env.PATH !== undefined) {
-    env.PATH = process.env.PATH;
+  const env = { HOME: agentHome };
+  for (const name of [...KEPT_ENV, ...passEnv]) {
+    if (process.env[name] !== undefined) {
+      env[name] = process.env[name];
+    }
   }
   env.CURSOR_API_KEY = apiKey;
   env.AGENT_CLI_CREDENTIAL_STORE = "memory";
+  // The operator's git config may name a credential helper (a keychain with
+  // their account). An empty helper first clears that list for the vendor's
+  // git, and a missing credential fails instead of prompting.
+  env.GIT_CONFIG_COUNT = "1";
+  env.GIT_CONFIG_KEY_0 = "credential.helper";
+  env.GIT_CONFIG_VALUE_0 = "";
+  env.GIT_TERMINAL_PROMPT = "0";
   const gitConfig = parentGitConfig(parentHome);
-  if (gitConfig === undefined) {
-    delete env.GIT_CONFIG_GLOBAL;
-  } else {
+  if (gitConfig !== undefined) {
     env.GIT_CONFIG_GLOBAL = gitConfig;
   }
   const npmCache = process.env.npm_config_cache;
   env.npm_config_cache =
     npmCache !== undefined && npmCache.length > 0 ? npmCache : join(parentHome, ".npm");
   const corepack = parentCorepack(parentHome);
-  if (corepack === undefined) {
-    delete env.COREPACK_HOME;
-  } else {
+  if (corepack !== undefined) {
     env.COREPACK_HOME = corepack;
   }
   return env;
 }
 
+/**
+ * Write the denials into the vendor's own config in `agentHome`, keeping what
+ * else is in it. Every pass, because the vendor can edit that file.
+ *
+ * @param {string} agentHome
+ * @param {readonly string[]} extra  commands the Project also refuses
+ */
+function denyShellCommands(agentHome, extra) {
+  const file = join(agentHome, ".cursor", "cli-config.json");
+  /** @type {Record<string, any>} */
+  let config = {};
+  try {
+    config = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    // none yet, or unreadable: start from nothing rather than refuse to run
+  }
+  const permissions = config.permissions ?? {};
+  const deny = Array.isArray(permissions.deny) ? permissions.deny : [];
+  config.permissions = {
+    ...permissions,
+    allow: Array.isArray(permissions.allow) ? permissions.allow : [],
+    deny: [...new Set([...deny, ...[...DENIED_SHELL, ...extra].map((name) => `Shell(${name})`)])],
+  };
+  mkdirSync(dirname(file), { recursive: true });
+  const next = `${file}.${process.pid}.tmp`;
+  writeFileSync(next, `${JSON.stringify(config, null, 2)}\n`);
+  renameSync(next, file);
+}
+
 /**
  * The global git file the parent already resolves. `~/.gitconfig` wins over
  * the XDG file, which is git's own order when both exist.

package/assembly/fix.mjs

@@ -19,9 +19,9 @@ const NAME = "assembly fix";
 
 const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
 
-This directory is the assembled feature. The units of work that made it have
-already been validated. An earlier judgement of the whole refused it. Do not
-redo those units. Fix what the refusal names.
+This directory is the assembled work. It passed the checks made on the unit
+itself. An earlier judgement of the whole refused it. Do not redo the work.
+Fix what the refusal names.
 
 Refused by: {{refused_by}}
 
@@ -40,6 +40,19 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
 ## Rules of this run
 
 {{rules}}
@@ -79,6 +92,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",

package/assembly/validate.mjs

@@ -19,11 +19,11 @@ const NAME = "assembly validate";
 
 const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
 
-This directory is the assembled feature. Every unit of work that makes it up
-has already been validated on its own. Your job now is different: read the
-diff this feature carries against the work line it will land on, and judge
-whether the WHOLE meets what was asked. Do not redo the units. Do not change
-anything — this is a read-only review, not a repair.
+This directory is the assembled work. It has already passed the checks made on
+the unit itself. Your job now is different: read the diff it carries against
+the work line it will land on, and judge whether the WHOLE meets what was
+asked. Do not redo the work. Do not change anything — this is a
+read-only review, not a repair.
 
 ## What was asked
 
@@ -34,7 +34,7 @@ anything — this is a read-only review, not a repair.
 End your final message with exactly one line in this form, and nothing after
 it:
 
-- \`MASON_VERDICT: VALIDATED\` — the assembled feature meets what was asked.
+- \`MASON_VERDICT: VALIDATED\` — the assembled ticket meets what was asked.
 - \`MASON_VERDICT: REFUSED: <one paragraph>\` — it does not, and the paragraph
   says what is wrong, specifically enough for another agent to fix it without
   redoing your review. Keep the whole paragraph on that one line.
@@ -162,7 +162,7 @@ function answer(run, bin, name) {
       "fail-retryable",
       why.length > 0
         ? why
-        : "assembly.validate refused the assembled feature, with no reason given.",
+        : "assembly.validate refused the assembled ticket, with no reason given.",
     );
     process.exit(1);
   }

package/builders/producer.mjs

@@ -13,7 +13,7 @@ import {
   textOption,
   transcriptArgs,
 } from "@bluewombat/slot-kit";
-import { attemptOf, doneWhen } from "../lib/fill.mjs";
+import { attemptOf } from "../lib/fill.mjs";
 
 const NAME = "builder producer";
 
@@ -22,11 +22,21 @@ const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkou
 Task:
 {{task}}
 
-{{done_when}}
+This checkout is the project as it stands. Add or change only what this task
+names, and leave the project's own checks green on the whole tree.
 
-This checkout already includes any earlier subtasks that were folded into the
-feature. Do not rewrite that work. Add or change only what this task names, and
-leave the project's own checks green on the whole tree.
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
 
 Rules of this run:
 {{rules}}
@@ -68,7 +78,7 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
-    done_when: doneWhen(take(process.argv, "--definition-of-done")),
+    history: (take(process.argv, "--history") ?? "").trim(),
     rules: rules.value.trim(),
     id: take(process.argv, "--id") ?? "",
     attempt: String(attemptOf(process.argv)),

package/builders/repair.mjs

@@ -13,7 +13,7 @@ import {
   textOption,
   transcriptArgs,
 } from "@bluewombat/slot-kit";
-import { attemptOf, doneWhen } from "../lib/fill.mjs";
+import { attemptOf } from "../lib/fill.mjs";
 
 const NAME = "builder repair";
 
@@ -38,7 +38,18 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
-{{done_when}}
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
 
 ## Rules of this run
 
@@ -79,10 +90,10 @@ const rendered = fillPrompt(
   template.value,
   {
     task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
     report,
     refused_by:
       refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",
-    done_when: doneWhen(take(process.argv, "--definition-of-done")),
     rules: rules.value.trim(),
     id: take(process.argv, "--id") ?? "",
     attempt: String(attemptOf(process.argv)),

package/gates/ci-green.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
-import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
+import { emitVerdict, GATE_FLAGS, ownArgv, take } from "@bluewombat/slot-kit";
 
 // The work line's own checks, on the work this workspace published: GitHub
 // Actions' check runs, and the commit statuses CI outside Actions reports
@@ -20,6 +20,12 @@ import { emitVerdict, GATE_FLAGS, ownArgv } from "@bluewombat/slot-kit";
 //                        to it failed only at the first assembly of a real run
 //   --require-checks     wait for a check to appear; without it, a commit with no
 //                        check at all passes
+//
+// It also receives `--timeout-ms` from Implementer: the ceiling it will be
+// killed at. A Gate that waits on a CI it does not run must not wait to be cut
+// off: a kill reads as "refused", and a refusal sends the work to an agent that
+// has nothing to fix. Near that ceiling it says so itself, `fail-blocking`, with
+// what it was waiting for.
 
 // What the runner writes at the top of every step it runs.
 const STEP_OPEN = "##[group]Run ";
@@ -63,8 +69,10 @@ if (pull === undefined) {
   process.exit(0);
 }
 
-// Ask again until the answer settles. The ceiling is this Gate's own timeout:
-// reaching it ends the Attempt, and the next one asks from scratch.
+// Ask again until the answer settles, or until just before Implementer would
+// kill this Gate (`--timeout-ms`); without that flag, until it does.
+const startedAt = Date.now();
+const stopAt = stopTime(startedAt, take(process.argv, "--timeout-ms"));
 for (;;) {
   const checks = await readChecks(pull.sha);
   if (checks === undefined) {
@@ -77,16 +85,61 @@ for (;;) {
   }
   if (checks.total === 0 && options.requireChecks) {
     // Just after a push there is a window where the checks are not created
-    // yet, and an empty list then says nothing. Ask again; the Gate's timeout
-    // is what ends the wait on a commit no check ever picks up.
-    await sleep(options.pollMs);
+    // yet, and an empty list then says nothing. Ask again, until the wait
+    // runs out: a commit no check ever picks up is not a refusal of the work.
+    if (Date.now() >= stopAt) {
+      stopWaiting(pull, "no check has appeared");
+    }
+    await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
     continue;
   }
   if (checks.running === 0) {
     emitVerdict("pass");
     process.exit(0);
   }
-  await sleep(options.pollMs);
+  if (Date.now() >= stopAt) {
+    stopWaiting(
+      pull,
+      `${checks.running} check${checks.running === 1 ? " was" : "s were"} still running`,
+    );
+  }
+  await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
+}
+
+/**
+ * The moment to stop waiting: a margin before Implementer's ceiling (5 %, between
+ * 2 and 30 seconds, and at most half of it), so the verdict is out before the
+ * kill. `Infinity` when Implementer gave no ceiling.
+ *
+ * @param {number} from
+ * @param {string | undefined} raw
+ */
+function stopTime(from, raw) {
+  const ceiling = Number.parseInt(raw ?? "", 10);
+  if (!Number.isInteger(ceiling) || ceiling <= 0) {
+    return Number.POSITIVE_INFINITY;
+  }
+  const margin = Math.min(Math.max(2_000, ceiling * 0.05), 30_000, ceiling / 2);
+  return from + ceiling - margin;
+}
+
+/**
+ * The CI did not answer. That says nothing of the work, and nothing the work
+ * could change: blocking, so a person reads it instead of an agent being sent
+ * to repair what was never judged.
+ *
+ * @param {{ number: number; sha: string }} pr
+ * @param {string} what
+ * @returns {never}
+ */
+function stopWaiting(pr, what) {
+  const seconds = Math.round((Date.now() - startedAt) / 1000);
+  const lasted = seconds >= 120 ? `${Math.round(seconds / 60)} min` : `${seconds} s`;
+  emitVerdict(
+    "fail-blocking",
+    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.`,
+  );
+  process.exit(0);
 }
 
 /**

package/gates/gitignore-leak.mjs

@@ -2,17 +2,17 @@
 import { spawnSync } from "node:child_process";
 import { emitVerdict, GATE_FLAGS, ownArgv, stageOf } from "@bluewombat/slot-kit";
 
-// Fail-retryable when the feature's commits add a path the workspace's own
+// Fail-retryable when the ticket's commits add a path the workspace's own
 // .gitignore excludes — a Builder's node_modules/, a build's dist/, a generated
 // file — so it would ship in the Submission.
 //
-// --base REF (required): the work line the feature is offered to. Only what the
-// feature adds since it left that line is judged, in what is committed: a path
-// tracked on purpose before the feature began is not this feature's leak, and
+// --base REF (required): the work line the ticket is offered to. Only what the
+// ticket adds since it left that line is judged, in what is committed: a path
+// tracked on purpose before the ticket began is not this ticket's leak, and
 // a removal staged but not committed has not removed anything yet.
 //
-// A unit only: nothing. A Subtask's work is uncommitted until a fold records it,
-// so there is no commit of its own here to judge.
+// A unit only: nothing. The work is uncommitted until a fold records it, so
+// there is no commit of its own here to judge.
 
 const cwd = process.cwd();
 const tokens = ownArgv(process.argv, GATE_FLAGS);
@@ -37,7 +37,7 @@ for (let i = 0; i < tokens.length; i++) {
 if (base === undefined) {
   emitVerdict(
     "fail-blocking",
-    "gitignore-leak needs --base <ref>: the work line the feature is offered to.",
+    "gitignore-leak needs --base <ref>: the work line the ticket is offered to.",
   );
   process.exit(0);
 }
@@ -105,7 +105,7 @@ emitVerdict(
   [
     `These paths are committed on top of ${base}, and this workspace's .gitignore excludes them.`,
     "Take them out of the commit with git rm -r --cached <path> and keep the files. If the",
-    "feature does mean to track one, change .gitignore so it no longer excludes it:",
+    "ticket does mean to track one, change .gitignore so it no longer excludes it:",
     ...shown,
     ...(rest > 0 ? [`… and ${rest} more`] : []),
   ].join("\n"),

package/lib/fill.mjs

@@ -4,12 +4,6 @@
  */
 import { take } from "@bluewombat/slot-kit";
 
-/** @param {string | undefined} raw */
-export function doneWhen(raw) {
-  const done = (raw ?? "").trim();
-  return done.length > 0 ? `Done when:\n${done}` : "";
-}
-
 /** @param {readonly string[]} argv */
 export function attemptOf(argv) {
   const parsed = Number.parseInt(take(argv, "--attempt") ?? "", 10);

package/messages/conventional.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { emitMessage, MESSAGE_FLAGS, ownArgv, take, writeDiagnostic } from "@bluewombat/slot-kit";
 
-// The feature's commit in the Conventional Commits shape, from the issue's
+// The ticket's commit in the Conventional Commits shape, from the issue's
 // title and body and with no agent: `<type>: <title>`, the body as written.
 //
 // The type is read off the title's first word — a Project that wants a

package/messages/git-producer.mjs

@@ -16,9 +16,9 @@ import {
   writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
-// The feature's commit message — and the pull request's description with it
+// The ticket's commit message — and the pull request's description with it
 // — written by an agent that read the diff, under the Project's own rules.
-// Asked once per feature. A role slot like the builders: it fills a template
+// Asked once per ticket. A role slot like the builders: it fills a template
 // and hands it to the agent after `--`; the agent answers in a file this slot
 // reads back. `--prompt-file` replaces the template, `--rules-file` the rules
 // — that is where a team's commit guideline goes.

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
-  "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
+  "description": "Shipped mason slots: Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
     "mason",
     "bluewombat",
     "gate",
-    "builder",
-    "planner"
+    "builder"
   ],
   "license": "MIT",
   "homepage": "https://github.com/tilap/bluewombat/tree/main/packages/plugins/slots#readme",
@@ -19,7 +18,6 @@
     "directory": "packages/plugins/slots"
   },
   "exports": {
-    "./planners/*": "./planners/*",
     "./builders/*": "./builders/*",
     "./assembly/*": "./assembly/*",
     "./agents/*": "./agents/*",
@@ -29,7 +27,6 @@
     "./messages/*": "./messages/*"
   },
   "files": [
-    "planners",
     "builders",
     "assembly",
     "agents",
@@ -53,7 +50,7 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.7.0",
+    "@bluewombat/slot-kit": "^0.9.0",
     "@pinkpuma/deck": "1.0.0"
   }
 }

package/publishers/git.mjs

@@ -11,7 +11,7 @@ import {
   writeDiagnostic,
 } from "@bluewombat/slot-kit";
 
-// Put the feature's work where the Authority can read it, by pushing the name
+// Put the ticket's work where the Authority can read it, by pushing the name
 // Isolator gave it to the work line's own remote.
 //
 // A plain push, and no force of any kind. Integrator only ever adds history, so

package/refreshers/git.mjs

@@ -16,6 +16,9 @@ import {
 // would make the next Isolation start from a version that no longer exists, so
 // this runs before anything else in a pass.
 //
+// The copy moves onto the target line first: a Feature's Tickets are cut from
+// and folded into that Feature's line, not the final branch.
+//
 // Fast-forward only: this system never rewrites that line. A copy that cannot
 // fast-forward has been written to by somebody else, and that is a person's
 // problem, not a merge to attempt.
@@ -41,7 +44,8 @@ if (!existsSync(join(cwd, ".git"))) {
   process.exit(0);
 }
 
-const fetched = git(["fetch", "origin", target]);
+// An explicit refspec: a single-branch clone only knows its own branch.
+const fetched = git(["fetch", "origin", `+refs/heads/${target}:refs/remotes/origin/${target}`]);
 if (fetched.status !== 0) {
   emitRefreshRefusal(
     `Cannot fetch origin/${target} from ${cwd}: ${fetched.stderr.trim().slice(-500)}`,
@@ -49,6 +53,18 @@ if (fetched.status !== 0) {
   process.exit(0);
 }
 
+const current = git(["symbolic-ref", "--short", "HEAD"]);
+if (current.status !== 0 || current.stdout.trim() !== target) {
+  const exists = git(["rev-parse", "--verify", "--quiet", `refs/heads/${target}`]).status === 0;
+  const switched = git(
+    exists ? ["checkout", target] : ["checkout", "-b", target, `origin/${target}`],
+  );
+  if (switched.status !== 0) {
+    emitRefreshRefusal(`Cannot move ${cwd} onto ${target}: ${switched.stderr.trim().slice(-500)}`);
+    process.exit(0);
+  }
+}
+
 const merged = git(["merge", "--ff-only", `origin/${target}`]);
 if (merged.status !== 0) {
   // The one way a copy stops fast-forwarding is a commit made into it that

package/planners/one-subtask.mjs

@@ -1,21 +0,0 @@
-#!/usr/bin/env node
-/**
- * Bootstrap Planner: one Subtask that is the FeatureStandard itself.
- * FeatureBreakdown appends --intention, --key, --max-units.
- */
-import { emitPlan, emitRefusal, take } from "@bluewombat/slot-kit";
-
-const intention = (take(process.argv, "--intention") ?? "").trim();
-if (intention.length === 0) {
-  emitRefusal("The FeatureStandard has no intention to turn into a Subtask.");
-  process.exit(0);
-}
-
-emitPlan([
-  {
-    id: "A",
-    intention,
-    definition_of_done: "The intention is realized in the workspace.",
-    depends_on: [],
-  },
-]);

package/planners/producer.mjs

@@ -1,233 +0,0 @@
-#!/usr/bin/env node
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  checkPlan,
-  emitPlan,
-  emitRefusal,
-  fillPrompt,
-  loadPrompt,
-  PLANNER_FLAGS,
-  parseRole,
-  spawnFilled,
-  take,
-  textOption,
-  transcriptArgs,
-  writeDiagnostic,
-} from "@bluewombat/slot-kit";
-
-const NAME = "planner producer";
-
-const DEFAULT_TEMPLATE = `You are splitting one piece of work into an ordered list of subtasks.
-
-You are not writing any of it. Do not modify anything in this directory. Read as
-much of it as you need first: the split has to fit the project as it is. Do not
-invent conventions you can discover from the repository.
-
-The work:
-{{intention}}
-
-Treat that as the source of truth for the desired outcome, not as a finished
-specification. Its wording may be incomplete. Separate what it explicitly
-requires from what the repository or ordinary engineering practice implies.
-Do not invent requirements to make the plan look complete.
-
-How the subtasks will be run, which is what makes a good split:
-
-- One at a time, never in parallel. Each runs in its own copy of this project,
-  and its result is folded back before the next one starts. So a later subtask
-  sees the earlier ones' work. If two slices would both change the same path
-  (a README, an index or barrel file, a changelog, package.json, or any other
-  shared file), make them **one** subtask, or give the second a \`depends_on\` on
-  the first and let **only** that second one write the shared path. Do not invent
-  a docs-only subtask unless the work asked for documentation.
-- Every subtask is checked by the project's own checks — its tests, its lint —
-  on its own. **A subtask must leave the project working.** This is the rule that
-  decides your split: never cut by layer. "Add the types", then "add the code",
-  then "add the tests" is wrong, because the first two leave the project broken.
-  Cut by thin slices that each work end to end. Tests belong in the subtask that
-  introduces or changes the behavior they verify.
-- Each subtask is given to an agent with no memory of you and no memory of the
-  others. Its intention has to stand alone: no "as discussed above", no knowledge
-  of this planning process, no requirement that lives only in the original work
-  description. Copy into the subtask everything its agent needs. A pointer at
-  existing code is fine if it names the behavior or location clearly enough to
-  investigate.
-- Write each intention the way a good commit message is written: one headline
-  of at most 72 characters in the imperative ("Add titleCase in
-  src/title-case.js"), a blank line, then everything the agent needs. The
-  headline is what people see: in the plan on the tracker, in the change list
-  of the submission, on the commit.
-- Its definition of done has to be checkable by someone who cannot read your
-  mind, and preferably by a test. It describes this subtask's observable result,
-  not the whole feature and not an intention.
-- \`depends_on\` means "cannot start before this one is done", and nothing else.
-  Sharing a file is a reason not to start side by side: pack those slices into
-  one subtask, or make the later one depend on the earlier. The graph describes
-  what must land before a merge is safe, not the order you happened to think in.
-  Chaining every subtask to the one before it when their files do not overlap
-  hides which ones were actually independent.
-
-You are choosing between two costs, and both are real.
-
-Splitting too finely costs a full agent run per slice, and each slice pays the
-project's whole check sequence again. Do not create a subtask solely to read
-code, decide what to implement, create folders, rename things, add comments,
-write documentation (unless the work asked for it), clean up, or refactor
-speculatively.
-
-Not splitting enough costs more, and less visibly. One subtask is one agent run,
-with one budget of attempts and one clock: a subtask too large for that exhausts
-them and the whole piece of work stops. And a subtask that fails goes back to
-nothing, while a subtask that succeeded is never redone. Ten modules in one
-subtask means ten modules redone when the tenth goes wrong.
-
-Prefer adapting what the project already does over introducing a parallel
-mechanism. Do not propose an architectural change merely because it might be
-cleaner.
-
-So: as few subtasks as the work allows, and none larger than what one competent
-engineer would finish in a single sitting without losing the thread. At most
-{{max_units}}.
-
-Write your answer as JSON, and nothing else, to this file:
-
-{{out}}
-
-It looks like this:
-
-{
-  "subtasks": [
-    { "id": "s1", "intention": "Headline\\n\\nEverything the agent needs.", "definition_of_done": "...", "depends_on": [] },
-    { "id": "s2", "intention": "Headline\\n\\n...", "definition_of_done": "...", "depends_on": ["s1"] }
-  ]
-}
-
-If the work cannot be split as it is written — contradictory outcomes, a
-critical requirement so ambiguous that the implementation would change with
-the reading, or too little to determine what should be built — write this
-instead, and do not invent a plan to fill the silence. Do not refuse merely
-because some implementation details are unspecified; those come from the
-repository.
-
-{ "outcome": "refused", "reason": "..." }
-`;
-
-const intention = (take(process.argv, "--intention") ?? "").trim();
-if (intention.length === 0) {
-  fail("The Planner received no --intention.");
-}
-
-const parsed = parseRole(process.argv, PLANNER_FLAGS, NAME, { "--read": {} });
-if (!parsed.ok) {
-  fail(parsed.reason);
-}
-
-const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
-if (!template.ok) {
-  fail(template.reason);
-}
-
-const maxUnits = Number.parseInt(take(process.argv, "--max-units") ?? "", 10);
-const scratch = mkdtempSync(join(tmpdir(), "plan-"));
-const out = join(scratch, "plan.json");
-const cwd = textOption(parsed.options, "read") ?? process.cwd();
-
-try {
-  const rendered = fillPrompt(
-    template.value,
-    {
-      intention,
-      max_units: Number.isInteger(maxUnits) ? String(maxUnits) : "a handful",
-      out,
-    },
-    ["intention", "out"],
-    textOption(parsed.options, "promptFile") ?? "built-in template",
-  );
-  if (!rendered.ok) {
-    fail(rendered.reason);
-  }
-
-  const spawned = await spawnFilled(
-    parsed.runner,
-    rendered.prompt,
-    transcriptArgs(process.argv, {
-      id: "breakdown",
-      context: take(process.argv, "--key"),
-    }),
-    cwd,
-  );
-  if (!spawned.ok) {
-    fail(spawned.reason);
-  }
-  if (spawned.run.error !== undefined) {
-    fail(`Could not start the agent at ${spawned.about.bin}: ${spawned.run.error.message}`);
-  }
-
-  const answer = readAnswer(out);
-  if (answer === undefined) {
-    fail(`The agent wrote no usable plan to ${out}. ${tail(spawned.run.output)}`);
-  }
-  if (answer.outcome === "refused") {
-    const reason =
-      typeof answer.reason === "string" && answer.reason.trim().length > 0
-        ? answer.reason.trim()
-        : "The Planner refused without saying why.";
-    emitRefusal(reason);
-    process.exit(0);
-  }
-
-  const checked = checkPlan(answer.subtasks, maxUnits);
-  if (!checked.ok) {
-    fail(`The agent returned a plan that cannot be used: ${checked.reason}`);
-  }
-  emitPlan(
-    checked.subtasks.map((subtask) => ({
-      id: subtask.id,
-      intention: subtask.intention,
-      definition_of_done: subtask.definition_of_done,
-      depends_on: subtask.depends_on,
-    })),
-  );
-  process.exit(0);
-} finally {
-  rmSync(scratch, { recursive: true, force: true });
-}
-
-/** @param {string} path @returns {Record<string, unknown> | undefined} */
-function readAnswer(path) {
-  let text;
-  try {
-    text = readFileSync(path, "utf8");
-  } catch {
-    return undefined;
-  }
-  const fenced = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
-  for (const candidate of [fenced?.[1], text]) {
-    if (candidate === undefined) {
-      continue;
-    }
-    try {
-      const value = JSON.parse(candidate);
-      if (value !== null && typeof value === "object") {
-        return value;
-      }
-    } catch {
-      // try the next reading
-    }
-  }
-  return undefined;
-}
-
-/** @param {string | undefined} output */
-function tail(output) {
-  const trimmed = (output ?? "").trim();
-  return trimmed.length === 0 ? "" : trimmed.slice(-1000);
-}
-
-/** @param {string} reason @returns {never} */
-function fail(reason) {
-  writeDiagnostic(`${reason}\n`);
-  process.exit(1);
-}