@outerlayer/cli 0.17.0 → 0.19.0

package/dist/{cli-A76AXELQ.js → cli-HROW5T7X.js}

@@ -1,37 +1,40 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
-import { gatherDoctorChecks, doctorExitCode, summarizeChecks, renderDoctorText, recordWrapped, recordUnwrapped, recordRemoval, readManifest, recordInstall, recordStatusline } from './chunk-HGECYFEI.js';
-import './chunk-NBGDBTO2.js';
-import './chunk-S3NYLI2P.js';
-import './chunk-6Y5RUTHO.js';
-import './chunk-IP7BIBXJ.js';
-import './chunk-F47JBIAW.js';
+import { gatherDoctorChecks, doctorExitCode, summarizeChecks, renderDoctorText, recordWrapped, recordUnwrapped, recordRemoval, readManifest, recordInstall, recordStatusline } from './chunk-5TN7GLYX.js';
+import './chunk-TWF3RICI.js';
+import { verifiedTrackerNames, TRACKERS } from './chunk-HPJNLETG.js';
+import './chunk-IF2OSI5T.js';
+import './chunk-CG36IONK.js';
+import './chunk-G3IJ3N6F.js';
+import './chunk-BM63HB2M.js';
+import { hookFiredMarkerPath, installedCliDistDir } from './chunk-NFIR3GEE.js';
+import './chunk-DSF2FWAZ.js';
 import './chunk-BKO6JEZI.js';
-import './chunk-XCK2YAY5.js';
-import './chunk-42ZI52JW.js';
-import './chunk-3NSNIIBE.js';
-import './chunk-WUYTWNMA.js';
-import './chunk-JXYVA45C.js';
-import './chunk-4KSQKQXE.js';
-import './chunk-N6LURUEF.js';
-import { C, NO_COLOR_FLAG, warnDeprecated, stripNoColor, API_KEY_FLAG_DEPRECATION } from './chunk-YRYMNBGQ.js';
+import './chunk-QNLX477Q.js';
+import './chunk-YVZJ6GKF.js';
+import './chunk-6X4SQ5MY.js';
+import './chunk-GOSFARMS.js';
+import { C, warnDeprecated, API_KEY_FLAG_DEPRECATION, NO_COLOR_FLAG, stripNoColor } from './chunk-ANPNT6PM.js';
 import { parseTrackerNumber, trackerNumberError } from './chunk-WZBHBH3J.js';
 import { settingsPath, readSettings, SettingsParseError, listHookCandidates, wrapHooks, writeSettings, unwrapHooks, REGISTERED_EVENTS, cliCommand, removeHooks, removeStatusline, cliBinResolvable, mergeHooks, repointWrappedHooks, AUTO_WRAP_EVENTS, mergeStatusline } from './chunk-5QRP3MVS.js';
-import { pinExists } from './chunk-WTE3MQML.js';
-import './chunk-C5Y5ZJJZ.js';
-import './chunk-YO4PSLVB.js';
-import './chunk-POJMEEJJ.js';
-import './chunk-OHVJA253.js';
-import './chunk-PLMTLGYH.js';
-import './chunk-J5M7BSJQ.js';
+import './chunk-IXYZUUYQ.js';
+import './chunk-FVMYKL6L.js';
+import './chunk-NTRCK4NH.js';
+import './chunk-ZJSNLVCE.js';
+import { findGitDirs } from './chunk-BJ3KTMDH.js';
+import './chunk-G2YNJIGF.js';
+import './chunk-NNLA7LLQ.js';
+import './chunk-WFSUUUAN.js';
+import './chunk-7VUK5RFS.js';
 import './chunk-EABW6AJQ.js';
-import { resolveVersion } from './chunk-RA3O54FC.js';
-import './chunk-V7NIVOFD.js';
-import './chunk-ZM2IMMYN.js';
-import { hookFiredMarkerPath, installedCliDistDir } from './chunk-BWQ66M6N.js';
-import { managedHookScripts, removeJournalHooks, installPreCommitGuardHook, removePreCommitGuardHook } from './chunk-XCCLFVXM.js';
-import './chunk-BJ3KTMDH.js';
+import { cliInvocation, packageRunnerOf } from './chunk-CRB3POP4.js';
+import { cloneIsGoverned } from './chunk-YQR6E6OV.js';
+import { removeJournalHooks, removePreCommitGuardHook } from './chunk-TUSYOL2O.js';
 import { homeFromEnv } from './chunk-VNVZDWO3.js';
+import { resolveVersion } from './chunk-RA3O54FC.js';
+import './chunk-M2ZWWTWZ.js';
+import './chunk-N2PXGQRL.js';
+import './chunk-BQXFBI7T.js';
 import './chunk-Z5GEFMRW.js';
 import { EventEmitter } from 'events';
 import childProcess, { execFileSync } from 'child_process';
@@ -3400,7 +3403,7 @@ function useColor() {
 // ../../node_modules/commander/index.js
 new Command();
 function isEphemeralBin(bin) {
-  return bin.replace(/\\/g, "/").split("/").some((p) => p === "_npx" || p === "dlx" || p.startsWith("dlx-") || p.startsWith("bunx-"));
+  return packageRunnerOf(bin) !== void 0;
 }
 function initHookBin(opts) {
   const { runningBin } = opts;
@@ -3544,7 +3547,6 @@ function runInit(opts) {
     recordStatusline(manifestHome, path2, statuslineWrappedCommand !== void 0 ? "wrapped" : "installed", statuslineWrappedCommand);
   }
   const gitHookRemoval = removeJournalHooks(opts.cwd ?? process.cwd());
-  const guardHook = installPreCommitGuardHook(opts.cwd ?? process.cwd());
   let gitignoreUpdated = false;
   if (scope === "project" && opts.addGitignore) {
     gitignoreUpdated = ensureGitignore(opts.cwd ?? process.cwd());
@@ -3556,7 +3558,6 @@ function runInit(opts) {
     events: REGISTERED_EVENTS,
     gitignoreUpdated,
     ...gitHookRemoval.removed ? { gitHookRemoved: true } : {},
-    guardHook,
     wrapped,
     ...statusline ? { statusline } : {},
     ...statuslineWrappedCommand ? { statuslineWrappedCommand } : {}
@@ -3574,8 +3575,12 @@ function tracksOwnOuterlayerDir(cwd) {
     return false;
   }
 }
+function isGovernedCheckout(cwd) {
+  const dirs = findGitDirs(cwd);
+  return dirs !== void 0 && cloneIsGoverned(dirs.gitCommonDir);
+}
 function ensureGitignore(cwd) {
-  if (tracksOwnOuterlayerDir(cwd) || pinExists(cwd)) return false;
+  if (tracksOwnOuterlayerDir(cwd) || isGovernedCheckout(cwd)) return false;
   const gitignore = join(cwd, ".gitignore");
   const entry = ".outerlayer/";
   let contents = "";
@@ -3610,11 +3615,12 @@ function orgRolloutSnippet(cliBin) {
     "managed-settings.json:",
     managed,
     "",
-    "Each developer still runs `outerlayer login` once to attribute sessions."
+    `Each developer still runs \`${cliInvocation()} login\` once to attribute sessions.`
   ].join("\n");
 }
 
 // src/cli.ts
+var TRACKER_OPTION_FLAG = `--tracker <${verifiedTrackerNames(TRACKERS).join("|")}>`;
 function resolveCliBin() {
   try {
     return fileURLToPath(new URL("./index.js", import.meta.url));
@@ -3640,13 +3646,10 @@ function writeJson(value) {
 `);
 }
 function apiKeyOption() {
-  return new Option("--api-key <key>", "deprecated: use `outerlayer login` or OUTERLAYER_API_KEY").hideHelp();
-}
-function warnIfApiKeyFlag(opts) {
-  if (opts.apiKey !== void 0) warnDeprecated(API_KEY_FLAG_DEPRECATION);
+  return new Option("--api-key <key>", `deprecated: use \`${cliInvocation()} login\` or OUTERLAYER_API_KEY`).hideHelp();
 }
 async function installStarterPackInRepo() {
-  const { installStarterPack, formatStarterPackOutput } = await import('./starter-pack-KF66HGZR.js');
+  const { installStarterPack, formatStarterPackOutput } = await import('./starter-pack-6LQVLBIA.js');
   const cwd = process.cwd();
   let repoRoot = cwd;
   try {
@@ -3687,7 +3690,7 @@ ${C.dim}  backup: ${result.backupPath}${C.reset}` : ""}
   }
   if (result.wrapped.length > 0) {
     lines.push(
-      `${C.green}\u2713${C.reset} Auto-wrapped ${result.wrapped.length} hook(s) for execution evidence (adds one spawn per firing \u2014 see ${C.yellow}outerlayer hooks unwrap${C.reset} to undo):
+      `${C.green}\u2713${C.reset} Auto-wrapped ${result.wrapped.length} hook(s) for execution evidence (adds one spawn per firing \u2014 see ${C.yellow}${cliInvocation()} hooks unwrap${C.reset} to undo):
 `
     );
     for (const w of result.wrapped) {
@@ -3729,45 +3732,15 @@ cannot be disabled.
     (opts.next === false ? "\n" : `
 Next: launch a session naming its work item, then sync it:
   ${C.yellow}OUTERLAYER_WORK=42 claude${C.reset}
-  ${C.yellow}outerlayer sync${C.reset}
+  ${C.yellow}${cliInvocation()} sync${C.reset}
 
-`) + (opts.connected ? "This repository is connected to a factory, so launched sessions sync\nautomatically in the background after each agent turn and at the end\nof the session, at most once every five minutes.\n" : "Once you have run outerlayer login and outerlayer init in this repository,\nlaunched sessions sync automatically in the background after each agent\nturn and at the end of the session, at most once every five minutes.\n")
+`) + (opts.connected ? "This repository is connected to a factory, so launched sessions sync\nautomatically in the background after each agent turn and at the end\nof the session, at most once every five minutes.\n" : `Once you have run ${cliInvocation()} login and ${cliInvocation()} init in this repository,
+launched sessions sync automatically in the background after each agent
+turn and at the end of the session, at most once every five minutes.
+`)
   );
   return lines.join("");
 }
-function formatGuardInstallOutput(guard) {
-  switch (guard.status) {
-    case "installed":
-    case "updated":
-    case "unchanged":
-      return { lines: [`${C.green}\u2713${C.reset} materialized-context commit guard ${guard.status} \u2192 ${guard.path}`] };
-    case "skipped-foreign":
-      if (guard.adopted) {
-        return { lines: [`${C.green}\u2713${C.reset} materialized-context commit guard hand-adopted into ${guard.path} \u2014 left untouched.`] };
-      }
-      return {
-        lines: [
-          `${C.yellow}!${C.reset} a pre-commit hook we did not write already exists (${guard.path}) \u2014 left untouched.`,
-          `  Append the guard script yourself: ${C.yellow}outerlayer hooks install-git --print${C.reset}`,
-          `  Place it before any exit in the existing hook \u2014 code after an early exit never runs.`
-        ],
-        exitCode: 1
-      };
-    case "skipped-custom-hooks-path":
-      if (guard.adopted) {
-        return { lines: [`${C.green}\u2713${C.reset} materialized-context commit guard hand-adopted at ${guard.path} (core.hooksPath) \u2014 left untouched.`] };
-      }
-      return {
-        lines: [
-          `${C.yellow}!${C.reset} this repo manages hooks in its working tree (core.hooksPath) \u2014 nothing written.`,
-          `  Add the script to your hook manager instead: ${C.yellow}outerlayer hooks install-git --print${C.reset}`
-        ],
-        exitCode: 1
-      };
-    case "not-a-repo":
-      return { lines: [], error: "not inside a git repository." };
-  }
-}
 async function installHooks(opts, resolvedBin, connected, starterTemplate, withNext = true) {
   const scope = opts.project ? "project" : "user";
   let cliBin;
@@ -3775,7 +3748,7 @@ async function installHooks(opts, resolvedBin, connected, starterTemplate, withN
     cliBin = initHookBin({ home: homeFromEnv(), runningBin: resolvedBin, remove: opts.remove === true });
   } catch (err) {
     const text = `could not copy the CLI to ~/.outerlayer/cli: ${err instanceof Error ? err.message : String(err)}
-  Hooks were not changed. Fix the permissions on ~/.outerlayer, then re-run ${C.yellow}outerlayer init${C.reset}.`;
+  Hooks were not changed. Fix the permissions on ~/.outerlayer, then re-run ${C.yellow}${cliInvocation()} init${C.reset}.`;
     return { ok: false, text, detail: "could not copy the CLI to ~/.outerlayer/cli" };
   }
   try {
@@ -3789,7 +3762,7 @@ async function installHooks(opts, resolvedBin, connected, starterTemplate, withN
     });
     if (result.cliBinUnresolved) {
       const text = `the resolved CLI path (${cliBin}) does not exist \u2014 refusing to write hook entries pointing at it.
-  Reinstall OuterLayer, then re-run ${C.yellow}outerlayer init${C.reset}.`;
+  Reinstall OuterLayer, then re-run ${C.yellow}${cliInvocation()} init${C.reset}.`;
       return { ok: false, text, detail: "the CLI path does not exist" };
     }
     const starter = starterTemplate === void 0 ? null : await installStarterPackInRepo();
@@ -3806,8 +3779,8 @@ ${starter.output}`),
   }
 }
 async function realConnectDepsForCwd() {
-  const { realConnectDeps } = await import('./connect-cmd-JBKAQNSF.js');
-  const { resolveRepoIdentity } = await import('./dist-LKDWQWZ7.js');
+  const { realConnectDeps } = await import('./connect-cmd-UNYKGDAL.js');
+  const { resolveRepoIdentity } = await import('./dist-WO7NOJNG.js');
   return {
     ...realConnectDeps(),
     home: homeFromEnv(),
@@ -3822,13 +3795,55 @@ function invokedCommandToken(argv) {
 }
 function buildProgram(argv = process.argv) {
   const program2 = new Command();
-  program2.name("outerlayer").description("OuterLayer \u2014 see what your coding agents actually do").enablePositionalOptions().version(resolveVersion()).option(NO_COLOR_FLAG, "disable color (NO_COLOR=1 does the same)").addHelpText("after", SUPPORT_TEXT);
-  program2.command("init").description("Connect this repository, install hooks and agent skills, run doctor").option("--user", "install into user settings [default]").option("--project", "install into project settings (./.claude/settings.json)").option("--org", "print a managed-settings.json snippet for MDM/GPO rollout").option("--remove", "uninstall OuterLayer hooks").option("--local", "install the hooks only: no connect step and no network call").option("--factory <org/factory>", "the factory to connect this repository to (see `outerlayer connect`)").option("--gitignore", "also add .outerlayer/ to .gitignore (project scope)").option("--template <name>", "install the starter skills and a policy file (only: default)").option("--update", "update the files init wrote that you have not edited, and write missing ones").option("--dry-run", "with --update: print the plan and write nothing").option("--no-wrap-hooks", "leave PreToolUse/PostToolUse hooks unwrapped").option("--statusline", "install the status-line segment [default]").option("--no-statusline", "leave the statusLine slot untouched").option("--json", "machine-readable JSON output").addHelpText(
+  program2.name(cliInvocation()).description("OuterLayer \u2014 see what your coding agents actually do").enablePositionalOptions().version(resolveVersion()).hook("preAction", (_root, command) => {
+    if (command.opts().apiKey !== void 0) warnDeprecated(API_KEY_FLAG_DEPRECATION);
+  }).option(NO_COLOR_FLAG, "disable color (NO_COLOR=1 does the same)").addHelpText("after", SUPPORT_TEXT);
+  program2.command("init").description("Connect this repository, install hooks and agent skills, run doctor").option("--user", "install into user settings [default]").option("--project", "install into project settings (./.claude/settings.json)").option("--org", "print a managed-settings.json snippet for MDM/GPO rollout").option("--remove", "uninstall OuterLayer hooks").option("--local", "install the hooks only: no connect step and no network call").option("--factory <org/factory>", `the factory to connect this repository to (see \`${cliInvocation()} connect\`)`).option("--gitignore", "also add .outerlayer/ to .gitignore (project scope)").option("--template <name>", "install the starter skills and a policy file (only: default)").option("--update", "update the files init wrote that you have not edited, and write missing ones").option("--dry-run", "with --update: print the plan and write nothing").option("--no-wrap-hooks", "leave PreToolUse/PostToolUse hooks unwrapped").option("--statusline", "install the status-line segment [default]").option("--no-statusline", "leave the statusLine slot untouched").option("--shell-function", "make plain claude run `outerlayer claude` (edits ~/.zshrc or ~/.bashrc)").option("--no-shell-function", "do not set up the shell function, and remove it if it is there").option("--json", "machine-readable JSON output").addHelpText(
     "after",
-    "\nIn a repository, init runs four steps: connect the repository to a\nfactory (`outerlayer connect`), install the hooks, set up the coding agent,\nand run `outerlayer doctor`. It never signs in and asks nothing. With no\nlogin it skips the connect step and says to run `outerlayer login`. With\n--json it prints one document naming the outcome of each step: done,\nskipped or failed. The exit code is 1 when a step failed.\n\nThe agent setup step installs the starter skills and the `outerlayer` skill\ninto .outerlayer/skills/, writes .outerlayer/config.json for Claude Code when\nthere is none, runs `outerlayer context emit` so the skills appear in\n.claude/skills/, and adds the outerlayer and outerlayer-docs MCP servers to\n.mcp.json. Nothing you wrote is changed: an existing config, policy, edited\nskill, MCP entry or root CLAUDE.md and AGENTS.md is left as it is, and a\nhand-written file the emit would replace is kept and listed. The files are\nleft uncommitted.\nThe step is skipped outside a git repository and in a repository whose\ncontext comes from a control plane, where it arrives at session start.\n\n--local installs only the hooks: no connect step, no agent setup and no\nnetwork call. Add `--template default` to also write the starter skills and\na policy file into .outerlayer/ without compiling them; `outerlayer context\nemit` does that.\n\nIdempotent: settings are backed up before any write, and a second run\nchanges nothing. Wrapping adds one spawn per hook firing; undo it with\n`outerlayer hooks unwrap`. An occupied status-line slot is wrapped, never\nreplaced.\n\nThree of the starter skills are copied once and are yours to edit. The\nothers are rewritten from this CLI on every `context emit`.\n\n--update brings the files init wrote once up to this CLI's version: the\ntemplate skills, the policy, the two starter checks and the two MCP\nentries. A file still equal to a version an earlier release wrote is\nreplaced, and a missing one is written. A file you edited is never\ntouched. It then runs `outerlayer context emit` and leaves the changes\nuncommitted. --dry-run prints the plan, with a command to compare each\nedited file, and writes nothing. `outerlayer doctor` reports the same\nstates under Starter files.\n"
+    `
+In a repository, init runs four steps: connect the repository to a
+factory (\`${cliInvocation()} connect\`), install the hooks, set up the coding agent,
+and run \`${cliInvocation()} doctor\`. It never signs in. With no
+login it skips the connect step and says to run \`${cliInvocation()} login\`. With
+--json it prints one document naming the outcome of each step: done,
+skipped or failed. The exit code is 1 when a step failed.
+
+The agent setup step installs the starter skills and the \`outerlayer\` skill
+into .outerlayer/skills/, writes .outerlayer/config.json for Claude Code when
+there is none, runs \`${cliInvocation()} context emit\` so the skills appear in
+.claude/skills/, and adds the outerlayer and outerlayer-docs MCP servers to
+.mcp.json. Nothing you wrote is changed: an existing config, policy, edited
+skill, MCP entry or root CLAUDE.md and AGENTS.md is left as it is, and a
+hand-written file the emit would replace is kept and listed. The files are
+left uncommitted.
+The step is skipped outside a git repository and in a repository whose
+context comes from a control plane, where it arrives at session start.
+
+--local installs only the hooks: no connect step, no agent setup and no
+network call. Add \`--template default\` to also write the starter skills and
+a policy file into .outerlayer/ without compiling them; \`${cliInvocation()} context
+emit\` does that.
+
+Idempotent: settings are backed up before any write, and a second run
+changes nothing. Wrapping adds one spawn per hook firing; undo it with
+\`${cliInvocation()} hooks unwrap\`. An occupied status-line slot is wrapped, never
+replaced.
+
+Three of the starter skills are copied once and are yours to edit. The
+others are rewritten from this CLI on every \`context emit\`.
+
+--update brings the files init wrote once up to this CLI's version: the
+template skills, the policy, the two starter checks and the two MCP
+entries. A file still equal to a version an earlier release wrote is
+replaced, and a missing one is written. A file you edited is never
+touched. It then runs \`${cliInvocation()} context emit\` and leaves the changes
+uncommitted. --dry-run prints the plan, with a command to compare each
+edited file, and writes nothing. \`${cliInvocation()} doctor\` reports the same
+states under Starter files.
+`
   ).action(async (opts) => {
     if (opts.update || opts.dryRun) {
-      const { runInitUpdate, formatInitUpdate, updateFlagProblem } = await import('./init-update-CVCWD6VS.js');
+      const { runInitUpdate, formatInitUpdate, updateFlagProblem } = await import('./init-update-LWX5MPPR.js');
       const problem = updateFlagProblem(opts);
       if (problem !== void 0) {
         fail(problem);
@@ -3842,7 +3857,7 @@ function buildProgram(argv = process.argv) {
     }
     let starterTemplate;
     if (opts.template !== void 0) {
-      const { assertKnownTemplate, StarterPackError } = await import('./starter-pack-KF66HGZR.js');
+      const { assertKnownTemplate, StarterPackError } = await import('./starter-pack-6LQVLBIA.js');
       try {
         assertKnownTemplate(opts.template);
       } catch (err) {
@@ -3869,13 +3884,19 @@ function buildProgram(argv = process.argv) {
         fail(outcome.text);
         return;
       }
+      if (opts.remove) {
+        const { removeShellFunction } = await import('./shell-function-NRD4KVUK.js');
+        const changed = removeShellFunction({ home: homeFromEnv() });
+        if (changed.length > 0 && !opts.json) process.stdout.write(`Removed the claude function from ${changed.join(", ")}.
+`);
+      }
       if (opts.json) writeJson(outcome.result);
       else process.stdout.write(outcome.text);
       return;
     }
-    const { runInitCommand } = await import('./init-cmd-XAVO7HYZ.js');
+    const { runInitCommand } = await import('./init-cmd-HSMRID6A.js');
     const code = await runInitCommand(
-      { json: opts.json, factory: opts.factory },
+      { json: opts.json, factory: opts.factory, shellFunction: opts.shellFunction },
       {
         connect: await realConnectDepsForCwd(),
         stdout: process.stdout,
@@ -3885,19 +3906,55 @@ function buildProgram(argv = process.argv) {
           return { ok, text, detail };
         },
         runAgentSetup: async () => {
-          const { runAgentSetup } = await import('./agent-setup-T624CWPD.js');
+          const { runAgentSetup } = await import('./agent-setup-TPR4BBFV.js');
           return runAgentSetup({ cwd: process.cwd() });
         },
-        runDoctorChecks: gatherDoctorChecks
+        runDoctorChecks: gatherDoctorChecks,
+        shell: {
+          home: homeFromEnv(),
+          shellPath: process.env.SHELL,
+          interactive: Boolean(process.stdin.isTTY && process.stderr.isTTY) && opts.json !== true,
+          ask: async () => {
+            const { promptOnTerminal } = await import('./connect-cmd-UNYKGDAL.js');
+            const answer = await promptOnTerminal({
+              message: `Should plain claude start Claude Code through ${cliInvocation()} claude? That is how a session in a governed repository gets its control plane. It adds one block to your zsh or bash startup file.`,
+              options: [
+                { label: "Yes, add the block", value: "yes" },
+                { label: "No, I will run outerlayer claude myself", value: "no" }
+              ]
+            });
+            return answer === "yes";
+          }
+        }
       }
     );
     if (code !== 0) process.exitCode = code;
   });
   program2.command("connect").description("Choose the factory this repository's work goes to").option("--factory <org/factory>", "the factory to use: <org>/<factory> as in its dashboard address, or a factory id").option("--json", "write one JSON document to stdout; the text goes to stderr").addHelpText(
     "after",
-    "\nRun it in a repository, after `outerlayer login`. With a login, connect lists\nthe factories you can use and takes the first rule that leaves one answer:\n  1. --factory <org>/<factory>, or a factory id\n  2. the factory this repository is already connected to\n  3. the one factory this repository is linked to\n  4. the one factory you can use\n  5. on a terminal, ask; with no terminal, exit 1 and list each --factory value\n\nIt says what it chose and why. The choice is saved in this repository's git\ndirectory (outerlayer/connection.json), shared by every worktree of the\nclone and never committed. A factory key already belongs to one factory, so\nconnect changes nothing for it. Connect never links a repository.\n\nAfter it saves the choice, connect checks that this repository is linked to\nthe factory. If it is not, connect says so, prints the factory's Work page\nlink where you link it, and exits 2. The choice is saved either way. Run\nconnect again once the repository is linked. With --json, the document has\nlinked (true, false, or null when it could not be checked) and, when false,\nlinkUrl.\n"
+    `
+Run it in a repository, after \`${cliInvocation()} login\`. With a login, connect lists
+the factories you can use and takes the first rule that leaves one answer:
+  1. --factory <org>/<factory>, or a factory id
+  2. the factory this repository is already connected to
+  3. the one factory this repository is linked to
+  4. the one factory you can use
+  5. on a terminal, ask; with no terminal, exit 1 and list each --factory value
+
+It says what it chose and why. The choice is saved in this repository's git
+directory (outerlayer/connection.json), shared by every worktree of the
+clone and never committed. A factory key already belongs to one factory, so
+connect changes nothing for it. Connect never links a repository.
+
+After it saves the choice, connect checks that this repository is linked to
+the factory. If it is not, connect says so, prints the factory's Work page
+link where you link it, and exits 2. The choice is saved either way. Run
+connect again once the repository is linked. With --json, the document has
+linked (true, false, or null when it could not be checked) and, when false,
+linkUrl.
+`
   ).action(async (opts) => {
-    const { runConnectCommand } = await import('./connect-cmd-JBKAQNSF.js');
+    const { runConnectCommand } = await import('./connect-cmd-UNYKGDAL.js');
     const code = await runConnectCommand({ factory: opts.factory, json: opts.json }, await realConnectDepsForCwd(), {
       stdout: process.stdout,
       stderr: process.stderr
@@ -3915,9 +3972,28 @@ function buildProgram(argv = process.argv) {
   });
   program2.command("login").description("Sign in to your account by browser approval, or save a piped factory key").option("--dashboard <address>", "the dashboard to sign in on (default: https://app.outerlayer.ai)").option("--no-browser", "print the approve link without opening a browser").option("--check <id>", "check a login that is still waiting for approval, once").option("--url <url>", "gateway base URL for a piped key (browser login gets it from the dashboard)").option("--app-id <id>", "factory id a piped key is bound to (Settings \u2192 General)").option("--no-input", "never wait on a person; fail if the key is not on stdin").option("--json", "machine-readable JSON output").addHelpText(
     "after",
-    '\nWith no key on stdin, login prints an approve link and a code. A signed-in\nperson approves it on the dashboard. The login is a token for that person\'s\naccount, made for this machine, saved here and never printed. It picks no\nfactory: run `outerlayer connect` for that. `outerlayer logout` revokes it.\n\nWhen stdout is not a terminal, login does not wait. It prints one JSON\ndocument with the link, the code and a `login --check <id>` command, and\nexits 75. Run the check until it stops exiting 75: 0 is signed in, 1 is\ndenied or expired. A dropped connection or a 5xx also exits 75.\n\nA factory key piped on stdin is saved as it always was, never as a flag and\nnever printed back. A factory key always wins over the login, so CI and\nrunners keep acting as their key.\n\n  echo "$OUTERLAYER_KEY" | outerlayer login --url <gateway url> --app-id <factory id>\n\nEvery later command reads the saved file, so none of them needs a key on\nits command line. A saved key is checked for real on the first `sync`.\n'
+    `
+With no key on stdin, login prints an approve link and a code. A signed-in
+person approves it on the dashboard. The login is a token for that person's
+account, made for this machine, saved here and never printed. It picks no
+factory: run \`${cliInvocation()} connect\` for that. \`${cliInvocation()} logout\` revokes it.
+
+When stdout is not a terminal, login does not wait. It prints one JSON
+document with the link, the code and a \`login --check <id>\` command, and
+exits 75. Run the check until it stops exiting 75: 0 is signed in, 1 is
+denied or expired. A dropped connection or a 5xx also exits 75.
+
+A factory key piped on stdin is saved as it always was, never as a flag and
+never printed back. A factory key always wins over the login, so CI and
+runners keep acting as their key.
+
+  echo "$OUTERLAYER_KEY" | ${cliInvocation()} login --url <gateway url> --app-id <factory id>
+
+Every later command reads the saved file, so none of them needs a key on
+its command line. A saved key is checked for real on the first \`sync\`.
+`
   ).action(async (opts) => {
-    const { runLoginCommand, realLoginDeps } = await import('./login-browser-QZCS3WW6.js');
+    const { runLoginCommand, realLoginDeps } = await import('./login-browser-DX35MARZ.js');
     const code = await runLoginCommand(
       {
         browser: opts.browser !== false,
@@ -3934,9 +4010,14 @@ function buildProgram(argv = process.argv) {
   });
   program2.command("logout").description("Revoke this machine's login and remove it").addHelpText(
     "after",
-    "\nRevokes the token `outerlayer login` saved, then deletes it from the config\nfile. A factory key and the chosen factory are left alone. When the\ndashboard cannot be reached the local copy is still deleted and the exit\ncode is 1: revoke the token on /profile/security.\n"
+    `
+Revokes the token \`${cliInvocation()} login\` saved, then deletes it from the config
+file. A factory key and the chosen factory are left alone. When the
+dashboard cannot be reached the local copy is still deleted and the exit
+code is 1: revoke the token on /profile/security.
+`
   ).action(async () => {
-    const { runLogoutCommand, realLogoutDeps } = await import('./logout-cmd-QAUFDJ6J.js');
+    const { runLogoutCommand, realLogoutDeps } = await import('./logout-cmd-5V5MMBSY.js');
     const code = await runLogoutCommand(realLogoutDeps());
     if (code !== 0) process.exitCode = code;
   });
@@ -3944,15 +4025,14 @@ function buildProgram(argv = process.argv) {
     "after",
     "\nIncremental: only sessions newer than the last checkpoint ship. The tier\nis applied on this machine before anything leaves it; `--dry-run` prints\nexactly what would. The hook-triggered background sync runs `--quiet`.\nExit 2 means the server rejected at least one session.\n"
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
     if (opts.link !== void 0) {
-      const { lookupArtifactLink } = await import('./artifact-link-cmd-2F47LT7F.js');
+      const { lookupArtifactLink } = await import('./artifact-link-cmd-W7XF5BFB.js');
       const found = lookupArtifactLink(opts.link);
       if (found.ok) process.stdout.write(found.url + "\n");
       else fail(found.reason);
       return;
     }
-    const { runSync, SyncConfigError, SyncTransportError } = await import('./sync-cmd-GVPPFZ3G.js');
+    const { runSync, SyncConfigError, SyncTransportError } = await import('./sync-cmd-G7GF4UTW.js');
     try {
       const result = await runSync({
         url: opts.url,
@@ -3977,11 +4057,13 @@ function buildProgram(argv = process.argv) {
       throw err;
     }
   });
-  program2.command("daemon").alias("watch").description("Run the copy-out daemon that mirrors transcripts before they are deleted").option("--once", "do a single mirror sweep and exit").addHelpText("after", "\n`outerlayer watch` is the former name and still works, with a warning.\n").action(async (opts) => {
+  program2.command("daemon").alias("watch").description("Run the copy-out daemon that mirrors transcripts before they are deleted").option("--once", "do a single mirror sweep and exit").addHelpText("after", `
+\`${cliInvocation()} watch\` is the former name and still works, with a warning.
+`).action(async (opts) => {
     if (invokedCommandToken(argv) === "watch") {
-      warnDeprecated("`outerlayer watch` is now `outerlayer daemon`; the old name will be removed in a future release.");
+      warnDeprecated(`\`${cliInvocation()} watch\` is now \`${cliInvocation()} daemon\`; the old name will be removed in a future release.`);
     }
-    const { runWatch } = await import('./watch-23HSAEI6.js');
+    const { runWatch } = await import('./watch-EVM5GSMP.js');
     await runWatch({ once: opts.once });
   });
   program2.command("hook <event>", { hidden: true }).description("capture-hook fast path, installed by `init`").action(() => {
@@ -3990,6 +4072,8 @@ function buildProgram(argv = process.argv) {
   });
   program2.command("hook-wrap", { hidden: true }).description("runs a hook wrapped by `hooks wrap`, recording exec evidence").option("--id <base64>", "the original hook command, base64-encoded").option("--capture-output", "tee stdout/stderr into a bounded tail").action(() => {
   });
+  program2.command("claude [args...]").description("start Claude Code with the repository's control plane attached").allowUnknownOption().helpOption(false).action(() => {
+  });
   program2.command("broker-relay", { hidden: true }).description("relay a build's loopback connections to the runner's tunnel and destinations").requiredOption("--port <port>", "the loopback port to listen on").requiredOption("--socket <path>", "the runner's tunnel socket").option("--forward <port=socket>", "also relay a loopback port to a destination's socket; repeatable", (value, previous) => [...previous, value], []).action(async (opts) => {
     const { startRelay } = await import('./relay-L76HDX72.js');
     const port = Number(opts.port);
@@ -4010,7 +4094,7 @@ function buildProgram(argv = process.argv) {
     await startRelay({ port, socketPath: opts.socket, forwards });
   });
   program2.command("vm-exec", { hidden: true }).description("run a command in a microVM build's guest through its exec agent").requiredOption("--socket <path>", "the Unix socket Firecracker serves the build's vsock device on").option("--user <user>", "the user to run as", "").option("--cwd <dir>", "the working directory", "/").option("--env <NAME=value>", "an environment value the command line carries; repeatable", (value, previous) => [...previous, value], []).option("--pass <NAME>", "an environment variable whose value is read from this process; repeatable", (value, previous) => [...previous, value], []).argument("<argv...>", "the command and its arguments").action(async (argv2, opts) => {
-    const { runVmExec } = await import('./exec-client-CQV746UF.js');
+    const { runVmExec } = await import('./exec-client-7UMESIE2.js');
     const env = {};
     for (const entry of opts.env) {
       const eq = entry.indexOf("=");
@@ -4035,7 +4119,7 @@ function buildProgram(argv = process.argv) {
     }
   });
   program2.command("session-sender", { hidden: true }).description("stream a runner build's sessions to its work item while the build runs").action(async () => {
-    const { runSessionSender } = await import('./session-sender-FO3LCREV.js');
+    const { runSessionSender } = await import('./session-sender-GGIY5OAX.js');
     try {
       await runSessionSender();
     } catch (err) {
@@ -4043,7 +4127,7 @@ function buildProgram(argv = process.argv) {
     }
   });
   program2.command("vm-init", { hidden: true }).description("lay out a microVM build's guest; the guest helper runs it").action(async () => {
-    const { realGuestHost, runGuestInit } = await import('./guest-init-LJP5GPZF.js');
+    const { realGuestHost, runGuestInit } = await import('./guest-init-KPBQOFE5.js');
     const { readFileSync: readFileSync3 } = await import('fs');
     try {
       runGuestInit(realGuestHost(), readFileSync3("/proc/cmdline", "utf8"));
@@ -4057,6 +4141,7 @@ function buildProgram(argv = process.argv) {
   registerMcpCommands(program2);
   registerContextCommands(program2);
   registerWorkCommands(program2);
+  registerSpecCommands(program2);
   registerRunnerCommands(program2);
   return program2;
 }
@@ -4070,7 +4155,7 @@ async function runCli(processArgv) {
   await buildProgram(argv).parseAsync(argv);
 }
 async function compileContext(opts) {
-  const { runEmit, EmitError } = await import('./emit-cmd-IJ3GVRFD.js');
+  const { runEmit, EmitError } = await import('./emit-cmd-7SP3I6UZ.js');
   try {
     const result = runEmit({ cwd: opts.dir, check: opts.check, json: opts.json });
     if (result.exitCode !== 0) process.exitCode = result.exitCode;
@@ -4085,15 +4170,39 @@ async function compileContext(opts) {
 function registerEmitCommands(program2) {
   const emitCmd = program2.command("emit").enablePositionalOptions().description("Record evidence for a work item: a named check result").argument("[name]", "the check name a validator declares (e.g. smoke.pass)").option("--link <url>", "proof link, usually the CI run URL").option("--body <text>", "one sentence recording your judgment").option("--body-file <path>", "read the sentence from a file; - reads standard input").option("--result <pass|fail>", "check outcome (default: pass)").option("--item <number>", "work item to record on directly, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addOption(new Option("--check", "deprecated: use `context emit --check`").hideHelp()).addOption(new Option("--dir <path>", "deprecated: use `context emit --dir`").hideHelp()).addHelpText(
     "after",
-    "\n  outerlayer emit smoke.pass --item 412 --link https://ci.example.com/run/42\n  outerlayer emit code-review --result fail --item 412 --body \"The button should be red.\"\n\nRecords that a named check passed or failed, anchored to a work item.\n--item is always required, in or out of a recorded session \u2014 there is no\nsession fallback. A check that ran carries the run URL as proof (--link);\na judgment you are making yourself carries one sentence (--body, or\n--body-file to read it from a file or standard input). A fail needs at\nleast one of the two. Run from inside a session, the check is stored as\nthe session's; a session cannot record over a person's fail. With\nnothing to attach it to, the command refuses.\n\nWho recorded a check is decided by your API key, never by what you send:\na key bound to your membership records it as yours, and nothing automated\ncan then clear it.\n\nA person's pass or fail on one criterion's proof is recorded on that\ncriterion's thread instead \u2014 see `outerlayer work comment`.\n\nSubcommands: `emit artifact <file>` for screenshots, recordings, reports and\nlogs; `emit finding` / `emit findings <file>` to record a problem in the factory;\n`emit criteria <file>` to record a work item's acceptance criteria.\nCompiling .outerlayer/ moved to `outerlayer context emit`.\n"
+    `
+  ${cliInvocation()} emit smoke.pass --item 412 --link https://ci.example.com/run/42
+  ${cliInvocation()} emit code-review --result fail --item 412 --body "The button should be red."
+
+Records that a named check passed or failed, anchored to a work item.
+--item is always required, in or out of a recorded session \u2014 there is no
+session fallback. A check that ran carries the run URL as proof (--link);
+a judgment you are making yourself carries one sentence (--body, or
+--body-file to read it from a file or standard input). A fail needs at
+least one of the two. Run from inside a session, the check is stored as
+the session's; a session cannot record over a person's fail. With
+nothing to attach it to, the command refuses.
+
+Who recorded a check is decided by your API key, never by what you send:
+a key bound to your membership records it as yours, and nothing automated
+can then clear it.
+
+A person's pass or fail on one criterion's proof is recorded on that
+criterion's thread instead \u2014 see \`${cliInvocation()} work comment\`.
+
+Subcommands: \`emit artifact <file>\` for screenshots, recordings, reports and
+logs; \`emit finding\` / \`emit findings <file>\` to record a problem in the factory;
+\`emit criteria <file>\` to record a work item's acceptance criteria;
+\`emit step <name>\` to report that you started a step.
+Compiling .outerlayer/ moved to \`${cliInvocation()} context emit\`.
+`
   ).action(async (name, opts) => {
     if (name === void 0) {
-      warnDeprecated("`outerlayer emit` with no name now lives at `outerlayer context emit`; the bare form will be removed in a future release.");
+      warnDeprecated(`\`${cliInvocation()} emit\` with no name now lives at \`${cliInvocation()} context emit\`; the bare form will be removed in a future release.`);
       await compileContext({ dir: opts.dir, check: opts.check, json: opts.json });
       return;
     }
-    warnIfApiKeyFlag(opts);
-    const { runEmitResult, EmitResultError } = await import('./emit-result-cmd-I4OADKMD.js');
+    const { runEmitResult, EmitResultError } = await import('./emit-result-cmd-RUICOKWQ.js');
     try {
       const result = await runEmitResult({
         name,
@@ -4123,10 +4232,10 @@ function registerEmitCommands(program2) {
   ).option("--replaces <ids>", "artifact id(s) this one corrects; comma-separate 2-20 to retire them all").option("--pr <number>", "pull request number to anchor to").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
     `
-  outerlayer emit artifact shot.png --caption "the dot row, current dot marked" --for LOGIN-01
+  ${cliInvocation()} emit artifact shot.png --caption "the dot row, current dot marked" --for LOGIN-01
 
 Inside a recorded Claude Code session the artifact spools locally and ships,
-bound to that session, on the next \`outerlayer sync\` \u2014 but only if that
+bound to that session, on the next \`${cliInvocation()} sync\` \u2014 but only if that
 session was launched with OUTERLAYER_WORK; without it nothing the session
 produces may leave the machine, and the command refuses rather than queue an
 artifact that can never ship. Otherwise it uploads immediately, anchored to a
@@ -4143,8 +4252,7 @@ everywhere, bytes and deep link untouched; a still-queued one is cancelled
 locally so it never uploads. One correction can retire several duplicates.
 `
   ).action(async (file, opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runEmitArtifact, EmitArtifactError } = await import('./emit-artifact-cmd-MPZVR56N.js');
+    const { runEmitArtifact, EmitArtifactError } = await import('./emit-artifact-cmd-O6SCM7TV.js');
     let pr;
     if (opts.pr !== void 0) {
       pr = parseTrackerNumber(opts.pr);
@@ -4176,10 +4284,34 @@ locally so it never uploads. One correction can retire several duplicates.
   });
   emitCmd.command("finding").description("Record one finding: a problem you hit in the factory").requiredOption("--id <id>", "client id \u2014 re-emitting the same id replaces it").option("--category <context|flaky-test|tooling|environment|defect|other>", "what kind of problem this is").requiredOption("--title <text>", "one sentence").requiredOption("--file <path>", "the file the problem is in, or the instruction's own path").option("--line <number>", "line number in --file").option("--rule-path <path>", "the instruction's own path \u2014 required for a context finding").option("--rule-line <number>", "line number in --rule-path").option("--rule-quote <text>", "the instruction's quoted sentence \u2014 required unless --rule-relation is missing").option("--rule-relation <wrong|broken|missing>", "how the instruction fails \u2014 required for a context finding").requiredOption("--where <label>", 'where this was recorded, e.g. "build session"').option("--detail <text>", "what happened, a few paragraphs").option("--cause <text>", 'what is actually wrong, or "unknown"').option("--suggestion <text>", "what would help").option("--command <text>", "the command that misbehaved").option("--error <text>", "the first error line").option("--test <name>", "the test name, for a flaky test").option("--symbol <name>", "the function the problem is in, for a defect").option("--started-at <event>", "event id where you hit the problem (default: first output showing --error)").option("--ended-at <event>", "event id where you got past it (default: the newest event)").option("--untimed", "record no time, only when the problem cost none in this session").option("--find <text>", "list this session's events that contain the text, and record nothing").option("--problem <id>", "a problem this finding reports; repeat for each one (needs --link-reason)", (value, previous = []) => [...previous, value]).option("--link-reason <text>", "why the finding reports each --problem").option("--new", "record a new problem instead of linking an existing one").option("--trace-id <id>", "the session's trace id, when there is one").option("--turn <number>", "turn index within the session").option("--round <number>", "round number, when there is one").addOption(new Option("--subject <value>").hideHelp()).addOption(new Option("--kind <value>").hideHelp()).addOption(new Option("--severity <value>").hideHelp()).addOption(new Option("--verdict <value>").hideHelp()).addOption(new Option("--fixed").hideHelp()).addOption(new Option("--source <value>").hideHelp()).option("--head-sha <sha>", "the commit this batch was recorded against").option("--context-source-sha <sha>", "the context-source commit this batch was recorded against").option("--item <number>", "work item to record on directly, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    '\n  outerlayer emit finding --id gate-skip --category tooling \\\n    --title "The pre-push gate prints green when a step was skipped" \\\n    --file scripts/git/pre-push-checks.mjs --where "build session"\n\nRecords one problem you hit in the factory: an instruction that is wrong or\nmissing (context), a flaky test, a misbehaving script (tooling), a local\nsetup trap (environment), a bug outside your own change (defect), or\nanything else. A problem in your own change is fixed, not recorded.\nA context finding needs --rule-path and --rule-relation, and --rule-quote\nunless the relation is missing. Add --cause, --detail and --suggestion, and\n--command, --error (first error line), --test or --symbol when there is one.\n\nEvery finding joins a factory-level problem. When one of its keys matches a\nknown problem it joins that problem. Otherwise nothing is stored: the command\nprints the closest problems and exits with code 3. Run it again with\n--problem <id> --link-reason <why> (repeat --problem for each problem the\nfinding reports), or with --new if none of them is the same problem.\nA finding records the time it cost, read from two events of your session or\nits subagents. The start is --started-at, else the first tool output that\nshows --error. The end is --ended-at, else the newest event. When the session\nhas events and no start is found, nothing is stored: the command lists the\nrecent events with their ids. --find <text> searches all of them.\n--item names the work item; without it, inside a recorded session, the\nitem that session was launched for is used automatically.\n'
+    `
+  ${cliInvocation()} emit finding --id gate-skip --category tooling \\
+    --title "The pre-push gate prints green when a step was skipped" \\
+    --file scripts/git/pre-push-checks.mjs --where "build session"
+
+Records one problem you hit in the factory: an instruction that is wrong or
+missing (context), a flaky test, a misbehaving script (tooling), a local
+setup trap (environment), a bug outside your own change (defect), or
+anything else. A problem in your own change is fixed, not recorded.
+A context finding needs --rule-path and --rule-relation, and --rule-quote
+unless the relation is missing. Add --cause, --detail and --suggestion, and
+--command, --error (first error line), --test or --symbol when there is one.
+
+Every finding joins a factory-level problem. When one of its keys matches a
+known problem it joins that problem. Otherwise nothing is stored: the command
+prints the closest problems and exits with code 3. Run it again with
+--problem <id> --link-reason <why> (repeat --problem for each problem the
+finding reports), or with --new if none of them is the same problem.
+A finding records the time it cost, read from two events of your session or
+its subagents. The start is --started-at, else the first tool output that
+shows --error. The end is --ended-at, else the newest event. When the session
+has events and no start is found, nothing is stored: the command lists the
+recent events with their ids. --find <text> searches all of them.
+--item names the work item; without it, inside a recorded session, the
+item that session was launched for is used automatically.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runEmitFinding, refuseRemovedFindingFlags, EmitFindingError } = await import('./emit-finding-cmd-5GF3V4LR.js');
+    const { runEmitFinding, refuseRemovedFindingFlags, EmitFindingError } = await import('./emit-finding-cmd-AJPKHIOV.js');
     try {
       refuseRemovedFindingFlags(opts);
       const result = await runEmitFinding({
@@ -4229,10 +4361,24 @@ locally so it never uploads. One correction can retire several duplicates.
   });
   emitCmd.command("findings <file>").description("Record a batch of findings from a FindingBatch JSON file (- for standard input)").option("--item <number>", "work item to record on directly, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    '\n  outerlayer emit findings review.json --item 412\n\nRecords a whole batch at once \u2014 a FindingBatch JSON file (schemaVersion 3,\noptional headSha / contextSourceSha, and 1-500 findings), validated against\nthe same contract `emit finding` uses before anything is sent. Re-emitting\nan id already on the item replaces that row rather than adding a second one.\nFindings that need a choice between candidate problems are listed and not\nstored; the rest are stored, and the exit code is 3.\nEach finding records its time as `emit finding` does: "startedAt" is an event\nid, else the first tool output that shows its "error"; "endedAt" defaults to\nthe newest event. A finding with neither, in a session that has events, stops\nthe whole batch. "untimed": true records one with no time on purpose.\n--item names the work item; without it, inside a recorded session, the item\nthat session was launched for is used automatically.\n'
+    `
+  ${cliInvocation()} emit findings review.json --item 412
+
+Records a whole batch at once \u2014 a FindingBatch JSON file (schemaVersion 3,
+optional headSha / contextSourceSha, and 1-500 findings), validated against
+the same contract \`emit finding\` uses before anything is sent. Re-emitting
+an id already on the item replaces that row rather than adding a second one.
+Findings that need a choice between candidate problems are listed and not
+stored; the rest are stored, and the exit code is 3.
+Each finding records its time as \`emit finding\` does: "startedAt" is an event
+id, else the first tool output that shows its "error"; "endedAt" defaults to
+the newest event. A finding with neither, in a session that has events, stops
+the whole batch. "untimed": true records one with no time on purpose.
+--item names the work item; without it, inside a recorded session, the item
+that session was launched for is used automatically.
+`
   ).action(async (file, opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runEmitFindings, EmitFindingError } = await import('./emit-finding-cmd-5GF3V4LR.js');
+    const { runEmitFindings, EmitFindingError } = await import('./emit-finding-cmd-AJPKHIOV.js');
     try {
       const result = await runEmitFindings({
         file,
@@ -4251,10 +4397,44 @@ locally so it never uploads. One correction can retire several duplicates.
       throw err;
     }
   });
+  emitCmd.command("step <name>").description("Report that you started a step; the work item's Activity tab shows it").option("--item <number>", "work item to report on, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+    "after",
+    `
+  ${cliInvocation()} emit step "Review round 2"
+  ${cliInvocation()} emit step "Plan" --item 412
+
+Run it when you start a step. The name is free text: 1 to 80 characters on one
+line. A step has a start and nothing else, so run it again for the next step.
+--item names the work item; without it, inside a recorded session, the item that
+session was launched for is used.
+
+If the gateway cannot be reached, the step is queued with the time you ran the
+command, the command exits 0, and \`sync\` sends it later. If the gateway refuses
+the step, the command prints why and exits 1.
+`
+  ).action(async (name, opts) => {
+    const { runEmitStep, EmitStepError } = await import('./emit-step-cmd-347XNGPQ.js');
+    try {
+      await runEmitStep({
+        name,
+        item: opts.item,
+        json: opts.json,
+        url: opts.url,
+        apiKey: opts.apiKey,
+        appId: opts.appId
+      });
+    } catch (err) {
+      if (err instanceof EmitStepError) {
+        fail(err.message);
+        return;
+      }
+      throw err;
+    }
+  });
   emitCmd.command("criteria <file>").description("Record a work item's acceptance criteria from a JSON file (- for stdin)").option("--item <number>", "work item to record on directly, by its number in this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
     `
-  outerlayer emit criteria criteria.json --item 412
+  ${cliInvocation()} emit criteria criteria.json --item 412
 
 Records the item's acceptance criteria as one list. The file is JSON:
   { "criteria": [ { "id": "AC-1", "text": "Given ...", "proof": null },
@@ -4271,8 +4451,7 @@ agent session, with your own login. A key bound to no member cannot replace it e
 session was launched for is used automatically.
 `
   ).action(async (file, opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runEmitCriteria, EmitCriteriaError } = await import('./emit-criteria-cmd-EFGYI23V.js');
+    const { runEmitCriteria, EmitCriteriaError } = await import('./emit-criteria-cmd-LQNERZRV.js');
     try {
       const result = await runEmitCriteria({
         file,
@@ -4292,14 +4471,54 @@ session was launched for is used automatically.
     }
   });
 }
+function registerSpecCommands(program2) {
+  const specCmd = program2.command("spec").description("Find, file and edit the issue a spec lives in, in your factory's tracker");
+  const credentialOptions = (command) => command.option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)");
+  const run = async (action) => {
+    const { WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
+    try {
+      await action(await import('./spec-cmd-SIZBRN7D.js'));
+    } catch (err) {
+      if (err instanceof WorkCommandError) {
+        fail(err.message);
+        return;
+      }
+      throw err;
+    }
+  };
+  credentialOptions(
+    specCmd.command("target").description("Say where a spec would be filed, and whether this factory can file there").option("--tracker <name>", "one connected tracker, when the factory has more than one")
+  ).action((opts) => run((spec) => spec.runSpecTarget(opts)));
+  credentialOptions(
+    specCmd.command("search").description("Find open and closed issues that match a query, before filing a duplicate").argument("<query>", "words from the title or body").option("--tracker <name>", "one connected tracker, when the factory has more than one")
+  ).action((query, opts) => run((spec) => spec.runSpecSearch({ ...opts, query })));
+  credentialOptions(
+    specCmd.command("file").description("File a spec as an issue and print its key, URL and the command that builds it").requiredOption("--title <text>", "the issue title").option("--body-file <path>", "the spec as Markdown; - reads standard input").option("--repo <owner/name>", "the repository to file in (GitHub), or the one the work lands in").option("--tracker <name>", "the tracker, when the factory files in more than one").option("--scope <key>", "the Linear team or Jira project, when the connection covers several")
+  ).action((opts) => run((spec) => spec.runSpecFile(opts)));
+  credentialOptions(
+    specCmd.command("edit").description("Replace the body of an issue that holds a spec").argument("<key>", "the issue key, such as acme/api#12 or ENG-142").option("--body-file <path>", "the new body as Markdown; - reads standard input").option("--updated-at <timestamp>", "the updatedAt you read; the edit is refused if the issue has changed since")
+  ).action((key, opts) => run((spec) => spec.runSpecEdit({ ...opts, key })));
+}
 function registerWorkCommands(program2) {
   const workCmd = program2.command("work").description("Start, remove, or read what the factory is working on (the Work page)");
-  workCmd.command("build").description("Start work on an item: a host builds it, or with --local you do").option("--issue <number>", "issue number, or a Linear/Jira key like ENG-123 (adds it to Work first)").option("--tracker <linear|jira>", "tracker for a keyed --issue \u2014 required if more than one is connected").option("--item <number>", "the item's own number inside this factory \u2014 must already exist").option("--local", "you build it in a session you start; no host takes it").option("--repo <owner/name>", "repository \u2014 the checkout's remote for a number, never guessed for a key").option("--note <text>", "a short note stored with the request").option("--session-id <id>", "session id to record as-is, skipping detection").option("--retry <count>", "retries after a gateway answer worth trying again").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+  workCmd.command("build").description("Start work on an item: a host builds it, or with --local you do").option("--issue <number>", "issue number, or a Linear/Jira key like ENG-123 (adds it to Work first)").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue \u2014 required if more than one is connected").option("--item <number>", "the item's own number inside this factory \u2014 must already exist").option("--local", "you build it in a session you start; no host takes it").option("--repo <owner/name>", "repository \u2014 the checkout's remote for a number, never guessed for a key").option("--note <text>", "a short note stored with the request").option("--session-id <id>", "session id to record as-is, skipping detection").option("--retry <count>", "retries after a gateway answer worth trying again").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work build --issue 42                       # a host builds it\n  outerlayer work build --item 7                         # retry an item already on Work\n  outerlayer work build --issue 42 --local               # you build it\n  outerlayer work build --issue ENG-123 --tracker linear # a Linear issue\n\nWithout --local, records a build request: a host takes the item when it\nhas a free slot. It never links the calling session and never takes a\nlease, even run from inside one.\n\nWith --local, puts the item on Work with no build request, so no host\ntakes it, and prints the line that starts your session on it. That\nsession links itself and holds the item's lease while it works.\n"
+    `
+  ${cliInvocation()} work build --issue 42                       # a host builds it
+  ${cliInvocation()} work build --item 7                         # retry an item already on Work
+  ${cliInvocation()} work build --issue 42 --local               # you build it
+  ${cliInvocation()} work build --issue ENG-123 --tracker linear # a Linear issue
+
+Without --local, records a build request: a host takes the item when it
+has a free slot. It never links the calling session and never takes a
+lease, even run from inside one.
+
+With --local, puts the item on Work with no build request, so no host
+takes it, and prints the line that starts your session on it. That
+session links itself and holds the item's lease while it works.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkBuild, WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkBuild, WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkBuild(opts);
     } catch (err) {
@@ -4312,10 +4531,17 @@ function registerWorkCommands(program2) {
   });
   workCmd.command("link-session").description("Link the calling session to a work item that already exists").argument("<number>", "the item's number inside this factory").option("--session-id <id>", "session id to record as-is, skipping detection (used by the SessionStart hook)").option("--retry <count>", "resend after a failure that may pass, with backoff").option("--no-lease", "link only \u2014 ask for no session lease (used by a host's own job)").option("--ended", "release this session's lease instead of taking or renewing one").addOption(new Option("--log-failures", "append a failure to the hook error log (used by hooks)").hideHelp()).option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work link-session 42\n\nNames an item that already exists on the calling session \u2014 it never\ncreates one. Create one with `outerlayer work build --local`. Linking\nthe same session to the same item twice is a no-op. Also takes or\nrenews that session's own 20-minute lease, unless --no-lease or\n--ended is given, or another worker already holds a live one.\n"
+    `
+  ${cliInvocation()} work link-session 42
+
+Names an item that already exists on the calling session \u2014 it never
+creates one. Create one with \`${cliInvocation()} work build --local\`. Linking
+the same session to the same item twice is a no-op. Also takes or
+renews that session's own 20-minute lease, unless --no-lease or
+--ended is given, or another worker already holds a live one.
+`
   ).action(async (number, opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkLinkSession, WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkLinkSession, WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkLinkSession({ ...opts, number, noLease: opts.lease === false, logFailures: opts.logFailures === true });
     } catch (err) {
@@ -4329,7 +4555,7 @@ function registerWorkCommands(program2) {
   workCmd.command("comment").description("Post a comment on a work item's general thread or one of its criterion threads").requiredOption("--item <number>", "the item's number inside this factory").option("--criterion <id>", "the criterion thread to post on (default: the general thread)").option("--body <text>", "the comment's text").option("--artifact <id>", "artifact id \u2014 required with --attach, naming the criterion's new proof").option("--pass", "record a pass (a person's verdict; refused from an agent session or a key)").option("--fail", "record a fail (a person's verdict; refused from an agent session or a key)").option("--attach", "make --artifact the named criterion's proof").option("--ready", "hand the thread back to a person (refused from a person)").option("--session-id <id>", "session id to record as-is, skipping detection (used by the SessionStart hook)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
     `
-  outerlayer work comment --item 7 --criterion AC-9-01 --body "fixed" --artifact 3f2a1c9d --attach
+  ${cliInvocation()} work comment --item 7 --criterion AC-9-01 --body "fixed" --artifact 3f2a1c9d --attach
 
 Posts one comment. Omitting --criterion posts on the general thread;
 naming one posts on that criterion's own thread. --pass/--fail are a
@@ -4339,9 +4565,8 @@ criterion's new proof; --ready hands the thread back to a person. At
 most one action flag may be given.
 `
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkComment, WorkCommentCommandError } = await import('./work-comment-cmd-AWHP56M2.js');
-    const { WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkComment, WorkCommentCommandError } = await import('./work-comment-cmd-2ACOZQAE.js');
+    const { WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkComment(opts);
     } catch (err) {
@@ -4354,11 +4579,16 @@ most one action flag may be given.
   });
   workCmd.command("threads").description("Read a work item's general thread and its criterion threads").requiredOption("--item <number>", "the item's number inside this factory").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work threads --item 7\n\nPrints the item's general thread, then one thread per acceptance\ncriterion that carries proof or a comment, each with who is waiting\non whom next.\n"
+    `
+  ${cliInvocation()} work threads --item 7
+
+Prints the item's general thread, then one thread per acceptance
+criterion that carries proof or a comment, each with who is waiting
+on whom next.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkThreads, WorkCommentCommandError } = await import('./work-comment-cmd-AWHP56M2.js');
-    const { WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkThreads, WorkCommentCommandError } = await import('./work-comment-cmd-2ACOZQAE.js');
+    const { WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkThreads(opts);
     } catch (err) {
@@ -4369,18 +4599,42 @@ most one action flag may be given.
       throw err;
     }
   });
-  workCmd.command("remove").description("Withdraw a source's addition \u2014 never deletes the item").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number (default: named by --item instead)").option("--repo <owner/name>", "repository (default: the current checkout's remote)").requiredOption("--reason <text>", "why this source is no longer working on it").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+  workCmd.command("logs").description("Read the runner's log for a host attempt on a work item").requiredOption("--item <number>", "the item's number inside this factory").option("--attempt <claim id>", "an attempt's id, from `work status --json` (default: the newest)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+    "after",
+    `
+  ${cliInvocation()} work logs --item 7
+  ${cliInvocation()} work logs --item 7 --attempt 7b0a3c52-9f1e-4d6b-8a21-5c3e9d2f1a40
+
+Prints what the runner did around the agent on that attempt, one line
+per event with its timestamp, with secrets removed on the host. The
+runner sends it when it releases the attempt, so an attempt that is
+still running, or that an older runner released, has no log and the
+command exits 1.
+`
+  ).action(async (opts) => {
+    const { runWorkLogs, WorkLogsCommandError } = await import('./work-logs-cmd-QDD2NMJL.js');
+    const { WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
+    try {
+      await runWorkLogs(opts);
+    } catch (err) {
+      if (err instanceof WorkLogsCommandError || err instanceof WorkCommandError) {
+        fail(err.message);
+        return;
+      }
+      throw err;
+    }
+  });
+  workCmd.command("remove").description("Withdraw a source's addition \u2014 never deletes the item").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number or Linear/Jira key (default: named by --item instead)").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue, when both hold the key").option("--repo <owner/name>", "repository for an issue number (default: the checkout's remote)").requiredOption("--reason <text>", "why this source is no longer working on it").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
     `
-  outerlayer work remove --item 42 --reason "done"
+  ${cliInvocation()} work remove --item 42 --reason "done"
 
 Withdraws the caller's own addition, recording the reason. Never
 deletes anything \u2014 the item is removed from Work only once no
 live addition remains on it.
 `
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkRemove, WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkRemove, WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkRemove(opts);
     } catch (err) {
@@ -4391,9 +4645,8 @@ live addition remains on it.
       throw err;
     }
   });
-  workCmd.command("status").description("Show one item's stage, gate ledger, and additions").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number").option("--repo <owner/name>", "repository (default: the current checkout's remote)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkStatus, WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+  workCmd.command("status").description("Show one item's stage, gate ledger, and additions").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number, or a Linear/Jira key like ENG-123").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue, when both hold the key").option("--repo <owner/name>", "repository for an issue number (default: the checkout's remote)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").action(async (opts) => {
+    const { runWorkStatus, WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkStatus(opts);
     } catch (err) {
@@ -4405,8 +4658,7 @@ live addition remains on it.
     }
   });
   workCmd.command("list").description("List live work items for this factory").option("--stage <spec|build|review>", "filter by stage").option("--section <attention|waiting|flowing>", "filter by Queue section").option("--repo <owner/name>", "repository (default: the current checkout's remote)").option("--unclaimed", "only items with no live lease").option("--claimed", "only items with a live lease, held by a host or a local session").option("--startable", "only items a host can start: a build request, no open PR, no live lease").option("--needs <amend>", "only items with a thread waiting on an agent").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkList, WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkList, WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkList(opts);
     } catch (err) {
@@ -4417,12 +4669,17 @@ live addition remains on it.
       throw err;
     }
   });
-  workCmd.command("claim").description("Claim a work item under a lease this API key holds before working on it").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number (default: named by --item instead)").option("--repo <owner/name>", "repository (default: the current checkout's remote)").requiredOption("--kind <implement|amend>", "what this host is doing with the item").option("--host <name>", "the claiming host (default: this machine's hostname)").option("--seconds <n>", "lease length in seconds, clamped to 900 (default: 900)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+  workCmd.command("claim").description("Claim a work item under a lease this API key holds before working on it").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number or Linear/Jira key (default: named by --item instead)").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue, when both hold the key").option("--repo <owner/name>", "repository for an issue number (default: the checkout's remote)").requiredOption("--kind <implement|amend>", "what this host is doing with the item").option("--host <name>", "the claiming host (default: this machine's hostname)").option("--seconds <n>", "lease length in seconds, clamped to 900 (default: 900)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work claim --item 42 --kind implement\n\nRecords a lease held by the API key that sends it. A live lease held\nby a different key is refused; claiming again with the same key extends\nit. --host is a label only.\n"
+    `
+  ${cliInvocation()} work claim --item 42 --kind implement
+
+Records a lease held by the API key that sends it. A live lease held
+by a different key is refused; claiming again with the same key extends
+it. --host is a label only.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkClaim, WorkCommandError } = await import('./work-claim-cmd-LKL3GHFQ.js');
+    const { runWorkClaim, WorkCommandError } = await import('./work-claim-cmd-3J3QW56U.js');
     try {
       await runWorkClaim(opts);
     } catch (err) {
@@ -4433,12 +4690,16 @@ live addition remains on it.
       throw err;
     }
   });
-  workCmd.command("renew").description("Extend the lease this API key holds on a work item").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number (default: named by --item instead)").option("--repo <owner/name>", "repository (default: the current checkout's remote)").option("--host <name>", "the claiming host (default: this machine's hostname)").option("--seconds <n>", "lease length in seconds, clamped to 900 (default: 900)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
+  workCmd.command("renew").description("Extend the lease this API key holds on a work item").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number or Linear/Jira key (default: named by --item instead)").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue, when both hold the key").option("--repo <owner/name>", "repository for an issue number (default: the checkout's remote)").option("--host <name>", "the claiming host (default: this machine's hostname)").option("--seconds <n>", "lease length in seconds, clamped to 900 (default: 900)").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work renew --item 42\n\nExtends the live lease this API key holds. Refused with a 410 if the\nlease has expired, or a 403 if a different key holds it.\n"
+    `
+  ${cliInvocation()} work renew --item 42
+
+Extends the live lease this API key holds. Refused with a 410 if the
+lease has expired, or a 403 if a different key holds it.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkRenew, WorkCommandError } = await import('./work-claim-cmd-LKL3GHFQ.js');
+    const { runWorkRenew, WorkCommandError } = await import('./work-claim-cmd-3J3QW56U.js');
     try {
       await runWorkRenew(opts);
     } catch (err) {
@@ -4449,15 +4710,28 @@ live addition remains on it.
       throw err;
     }
   });
-  workCmd.command("release").description("Release the lease this API key holds on a work item, or this session's own lease").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number (default: named by --item instead)").option("--repo <owner/name>", "repository (default: the current checkout's remote)").option("--host <name>", "the claiming host (default: this machine's hostname); releases a host's lease").option("--session-id <id>", "the session whose lease to release, skipping detection").option(
+  workCmd.command("release").description("Release the lease this API key holds on a work item, or this session's own lease").option("--item <number>", "the item's number inside this factory").option("--issue <number>", "issue number or Linear/Jira key (default: named by --item instead)").option(TRACKER_OPTION_FLAG, "tracker for a keyed --issue, when both hold the key").option("--repo <owner/name>", "repository for an issue number (default: the checkout's remote)").option("--host <name>", "the claiming host (default: this machine's hostname); releases a host's lease").option("--session-id <id>", "the session whose lease to release, skipping detection").option(
     "--outcome <ok|incomplete|failed|timed_out|idle|lease_lost|interrupted|stopped>",
     "how a host's attempt ended (default: none)"
   ).option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work release --item 42 --outcome ok\n  outerlayer work release --item 42\n\nMarks the lease this API key holds released, optionally with an\noutcome. A lease held by a different key is refused. Releasing an\nalready-released lease is a no-op that returns the recorded release\ntime and outcome.\n\nRun inside a session with no --host, it releases that session's own\nlease instead, so the item's review opens without ending the\nsession. It never releases another session's lease. --outcome\napplies to a host's lease only. A later tool call in the session\ntakes the lease again.\n"
+    `
+  ${cliInvocation()} work release --item 42 --outcome ok
+  ${cliInvocation()} work release --item 42
+
+Marks the lease this API key holds released, optionally with an
+outcome. A lease held by a different key is refused. Releasing an
+already-released lease is a no-op that returns the recorded release
+time and outcome.
+
+Run inside a session with no --host, it releases that session's own
+lease instead, so the item's review opens without ending the
+session. It never releases another session's lease. --outcome
+applies to a host's lease only. A later tool call in the session
+takes the lease again.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkRelease, WorkCommandError } = await import('./work-claim-cmd-LKL3GHFQ.js');
+    const { runWorkRelease, WorkCommandError } = await import('./work-claim-cmd-3J3QW56U.js');
     try {
       await runWorkRelease(opts);
     } catch (err) {
@@ -4470,10 +4744,21 @@ live addition remains on it.
   });
   workCmd.command("pr <number>").description("Declare a pull request onto the launched work item, or withdraw it").option("--repo <owner/name>", "repository (default: the current checkout's remote)").option("--session-id <id>", "session id to record as-is, skipping detection").option("--withdraw", "remove the declaration instead of making one (needs --item)").option("--item <number>", "with --withdraw, the item to remove the declaration from").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    "\n  outerlayer work pr 481\n  outerlayer work pr 481 --withdraw --item 250\n\nRun inside a session already on a work item. Records that pull\nrequest 481 in the checkout's repository belongs to the item named by\nOUTERLAYER_WORK, or refuses when the session is not on it. The same\nfact a `pr-link` in the session's own transcript records on sync.\nIdempotent: declaring the same pull request twice is a no-op.\n\n--withdraw removes one item's declaration of the pull request. It\nneeds your own login; an agent session or a factory key is refused.\n"
+    `
+  ${cliInvocation()} work pr 481
+  ${cliInvocation()} work pr 481 --withdraw --item 250
+
+Run inside a session already on a work item. Records that pull
+request 481 in the checkout's repository belongs to the item named by
+OUTERLAYER_WORK, or refuses when the session is not on it. The same
+fact a \`pr-link\` in the session's own transcript records on sync.
+Idempotent: declaring the same pull request twice is a no-op.
+
+--withdraw removes one item's declaration of the pull request. It
+needs your own login; an agent session or a factory key is refused.
+`
   ).action(async (number, opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkPr, WorkPrCommandError } = await import('./work-pr-cmd-HNEUIEN7.js');
+    const { runWorkPr, WorkPrCommandError } = await import('./work-pr-cmd-H4OQR26N.js');
     try {
       await runWorkPr({ ...opts, number });
     } catch (err) {
@@ -4486,11 +4771,20 @@ live addition remains on it.
   });
   workCmd.command("open-pr").description("Open, or edit, the pull request for the work item this session is on").requiredOption("--title <title>", "the pull request's title").requiredOption("--body-file <path>", "a file holding the pull request's description").option("--repository <owner/name>", "repository to open the pull request in (default: the primary)").option("--repo <owner/name>", "same as --repository, on the gh path").option("--session-id <id>", "session id to record as-is, on the gh path, skipping detection").option("--json", "machine-readable JSON output").option("--url <url>", "cloud base URL (or OUTERLAYER_URL / config)").addOption(apiKeyOption()).option("--app-id <id>", "factory id the key is bound to (or OUTERLAYER_APP_ID / config)").addHelpText(
     "after",
-    '\n  outerlayer work open-pr --title "Add the thing" --body-file pr.md\n  outerlayer work open-pr --repository acme/web --title "Add the thing" --body-file pr.md\n\nIn a host build, which holds an item key, the gateway opens the pull\nrequest as the factory\'s GitHub App, from the branch the claim named,\nor edits the one already open on that branch. No gh command runs.\nIn your own session it runs `gh pr create` (or `gh pr edit`) under your\nlogin, then declares the pull request on the item, as `work pr` does.\nRun it again after a change to the title or description.\n'
+    `
+  ${cliInvocation()} work open-pr --title "Add the thing" --body-file pr.md
+  ${cliInvocation()} work open-pr --repository acme/web --title "Add the thing" --body-file pr.md
+
+In a host build, which holds an item key, the gateway opens the pull
+request as the factory's GitHub App, from the branch the claim named,
+or edits the one already open on that branch. No gh command runs.
+In your own session it runs \`gh pr create\` (or \`gh pr edit\`) under your
+login, then declares the pull request on the item, as \`work pr\` does.
+Run it again after a change to the title or description.
+`
   ).action(async (opts) => {
-    warnIfApiKeyFlag(opts);
-    const { runWorkOpenPr, WorkOpenPrCommandError } = await import('./work-open-pr-cmd-IOM4AVQQ.js');
-    const { WorkCommandError } = await import('./work-cmd-Z2WXLZPH.js');
+    const { runWorkOpenPr, WorkOpenPrCommandError } = await import('./work-open-pr-cmd-XNCEI4ZM.js');
+    const { WorkCommandError } = await import('./work-cmd-5EPPD33Y.js');
     try {
       await runWorkOpenPr(opts);
     } catch (err) {
@@ -4506,9 +4800,9 @@ function registerRunnerCommands(program2) {
   const runnerCmd = program2.command("runner").description("Take work from the implement and amend queues on this machine");
   const configOption = "the cloud config file to run against (default: ~/.outerlayer/config.json)";
   runnerCmd.command("start").description("Run the loop: claim work, run it, report, clean up, repeat").option("--config <path>", configOption).action(async (opts) => {
-    const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-N3C6DFQA.js');
-    const { start, RunnerStartError } = await import('./loop-FK3LPMMZ.js');
-    const { RunnerAlreadyRunningError } = await import('./pidfile-UZRH774M.js');
+    const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-CLSGABD5.js');
+    const { start, RunnerStartError } = await import('./loop-SYYPVFYW.js');
+    const { RunnerAlreadyRunningError } = await import('./pidfile-3DM4OBKO.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     try {
       const { realUpdateDeps } = await import('./real-deps-KNNBQC75.js');
@@ -4522,8 +4816,8 @@ function registerRunnerCommands(program2) {
     }
   });
   runnerCmd.command("check").description("Validate the config, the hooks and the key, and print the effective settings").option("--config <path>", configOption).action(async (opts) => {
-    const { defaultRunnerConfigPath } = await import('./config-N3C6DFQA.js');
-    const { runRunnerCheck } = await import('./check-5XE7XMC4.js');
+    const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
+    const { runRunnerCheck } = await import('./check-UWQAL2MN.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     const result = await runRunnerCheck(configPath);
     if (!result.ok) {
@@ -4539,8 +4833,8 @@ function registerRunnerCommands(program2) {
 `);
   });
   runnerCmd.command("install").description("Put this CLI in the runner's install layout; --service adds its service").option("--config <path>", configOption).option("--service", "set up the service that keeps the runner running").option("--print", "with --service, print the unit and set up nothing").option("--user <account>", "with --service, the account the service runs as").option("--replace", "replace a unit or launcher file this command did not write").option("--allow-downgrade", "install this CLI even when it is older than the version the runner runs").option("--unit-name <name>", "with --service, the unit's name, to run a second runner beside the first").action(async (opts) => {
-    const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-N3C6DFQA.js');
-    const { runRunnerInstall, RunnerInstallError, launcherSummary, restartNote } = await import('./install-cmd-5HYMXLEW.js');
+    const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-CLSGABD5.js');
+    const { runRunnerInstall, RunnerInstallError, launcherSummary, restartNote } = await import('./install-cmd-QDOTR4OM.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     if (opts.service !== true) {
       for (const flag of ["print", "user", "unitName"]) {
@@ -4552,7 +4846,7 @@ function registerRunnerCommands(program2) {
     }
     try {
       if (opts.service === true) {
-        const { installServiceCommand } = await import('./command-R2QCVX55.js');
+        const { installServiceCommand } = await import('./command-OEAV7BVX.js');
         const result2 = await installServiceCommand({
           configPath,
           print: opts.print,
@@ -4590,7 +4884,7 @@ function registerRunnerCommands(program2) {
       printLauncher(result, launcherSummary);
       process.stdout.write(
         `
-To keep it running, run ${C.yellow}outerlayer runner install --service${C.reset}. To start the runner from the install layout yourself, use this line, then restart the service:
+To keep it running, run ${C.yellow}${cliInvocation()} runner install --service${C.reset}. To start the runner from the install layout yourself, use this line, then restart the service:
   ${C.yellow}${result.execStart}${C.reset}
 `
       );
@@ -4604,11 +4898,11 @@ To keep it running, run ${C.yellow}outerlayer runner install --service${C.reset}
   });
   runnerCmd.command("uninstall").description("Stop the runner's service and remove it (needs --service)").option("--config <path>", configOption).option("--service", "remove the service, and the launch agent or scheduled task").option("--unit-name <name>", "the unit's name, when it is not the default").action(async (opts) => {
     if (opts.service !== true) {
-      fail("pass --service: `outerlayer runner uninstall --service` removes the runner's service.");
+      fail(`pass --service: \`${cliInvocation()} runner uninstall --service\` removes the runner's service.`);
       return;
     }
-    const { defaultRunnerConfigPath } = await import('./config-N3C6DFQA.js');
-    const { uninstallServiceCommand } = await import('./command-R2QCVX55.js');
+    const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
+    const { uninstallServiceCommand } = await import('./command-OEAV7BVX.js');
     const result = await uninstallServiceCommand({ configPath: opts.config ?? defaultRunnerConfigPath(), unitName: opts.unitName, home: homeFromEnv() });
     if (result.ok) for (const line of result.lines) process.stdout.write(`${C.green}\u2713${C.reset} ${line}
 `);
@@ -4616,14 +4910,31 @@ To keep it running, run ${C.yellow}outerlayer runner install --service${C.reset}
   });
   runnerCmd.command("init").description("Write a runner block that fits this machine; on macOS, offers a Linux VM").option("--config <path>", configOption).option("--vm", "on macOS, run the runner in a Linux VM (Lima), with container builds").option("--no-vm", "on macOS, skip the VM and run builds as unisolated processes").option("--allow-process-builds", "where builds cannot be isolated, run them as processes anyway").addOption(new Option("--config-stdin", "the VM-side hand-off: read the whole config as JSON on stdin").hideHelp()).option("--vm-cli-package <path>", "with --vm, install this packed CLI tarball in the VM").option("--unit-name <name>", "the service unit's name, to run a second runner beside the first").option("--agent <name>", "write commands that start this agent (claude); its credential comes on stdin").option("--factory <org/factory>", "factory to create the runner key on, as <org>/<factory>").option("--app-id <id>", "factory id, instead of --factory (Settings \u2192 General)").addHelpText(
     "after",
-    "\nWith no apiKey in the config file, and a login saved by `outerlayer login`,\nrunner init names the factory the runner is for: --factory, then --app-id,\nOUTERLAYER_APP_ID, or this repository's connection. With none of those, a\nlogin that can use one factory uses it, and one that can use several lists\nthem. It then prints the factory's API keys page, where you create a key with\nthe Runner preset, and asks you to paste it. Nothing is shown as you paste.\nWith no terminal to ask on, it stops and says what to put in the config file.\n\nWith --agent claude, the queue commands start Claude Code instead of the\nplaceholder, and Claude's credential is read from stdin: a token from\n`claude setup-token` (sk-ant-oat...) or an API key (sk-ant-api...). It is\nnever printed, and is stored in the runner.env beside the config with mode\n600. Other lines in the file are kept. With nothing piped, a credential\nalready in runner.env is used.\n\n  printf '%s' \"$CLAUDE_CODE_OAUTH_TOKEN\" | outerlayer runner init --agent claude --factory <org>/<factory>\n"
+    `
+With no apiKey in the config file, and a login saved by \`${cliInvocation()} login\`,
+runner init names the factory the runner is for: --factory, then --app-id,
+OUTERLAYER_APP_ID, or this repository's connection. With none of those, a
+login that can use one factory uses it, and one that can use several lists
+them. It then prints the factory's API keys page, where you create a key with
+the Runner preset, and asks you to paste it. Nothing is shown as you paste.
+With no terminal to ask on, it stops and says what to put in the config file.
+
+With --agent claude, the queue commands start Claude Code instead of the
+placeholder, and Claude's credential is read from stdin: a token from
+\`claude setup-token\` (sk-ant-oat...) or an API key (sk-ant-api...). It is
+never printed, and is stored in the runner.env beside the config with mode
+600. Other lines in the file are kept. With nothing piped, a credential
+already in runner.env is used.
+
+  printf '%s' "$CLAUDE_CODE_OAUTH_TOKEN" | ${cliInvocation()} runner init --agent claude --factory <org>/<factory>
+`
   ).action(async (opts) => {
-    const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-N3C6DFQA.js');
-    const { prepareRunnerInit, runRunnerInit, RunnerInitError, writeRunnerInit } = await import('./init-6XPDRDTC.js');
-    const { obtainRunnerKey, runnerKeyLogin } = await import('./runner-key-6SLBI7PP.js');
-    const { detectMachine } = await import('./machine-SQXEBAM2.js');
-    const { chooseVm, runVmInit, VmInitError } = await import('./init-PWU5YVL7.js');
-    const { AGENT_COMMANDS, credentialFromStdin, isAgentName, restartForCredential, RunnerEnvError } = await import('./runner-env-EN7YE7QX.js');
+    const { defaultRunnerConfigPath, RunnerConfigError } = await import('./config-CLSGABD5.js');
+    const { prepareRunnerInit, runRunnerInit, RunnerInitError, writeRunnerInit } = await import('./init-MOINY2DD.js');
+    const { obtainRunnerKey, runnerKeyLogin } = await import('./runner-key-276SJU5R.js');
+    const { detectMachine } = await import('./machine-6X63G2KH.js');
+    const { chooseVm, runVmInit, VmInitError } = await import('./init-LWHDMZQG.js');
+    const { AGENT_COMMANDS, credentialFromStdin, isAgentName, restartForCredential, RunnerEnvError } = await import('./runner-env-FRZFFHDF.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     if (opts.agent !== void 0 && !isAgentName(opts.agent)) {
       fail(`--agent ${opts.agent}: runner init writes commands for ${Object.keys(AGENT_COMMANDS).join(", ")}. For another agent, leave --agent out and edit runner.commands.`);
@@ -4637,7 +4948,7 @@ To keep it running, run ${C.yellow}outerlayer runner install --service${C.reset}
     try {
       let credential;
       if (agent !== void 0) {
-        const { readPipedKey } = await import('./login-browser-QZCS3WW6.js');
+        const { readPipedKey } = await import('./login-browser-DX35MARZ.js');
         credential = credentialFromStdin(
           await readPipedKey(process.stdin, {
             onWaiting: () => process.stderr.write(`runner init is waiting for Claude's credential on stdin; close stdin to use the one already in runner.env
@@ -4654,7 +4965,7 @@ To keep it running, run ${C.yellow}outerlayer runner install --service${C.reset}
         const chunks = [];
         for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
         const result2 = runRunnerInit(configPath, { machine, configFromStdin: Buffer.concat(chunks).toString("utf8"), requireContainer: true });
-        const { ensureHostKey: ensureHostKey2 } = await import('./host-key-YMLXY6QB.js');
+        const { ensureHostKey: ensureHostKey2 } = await import('./host-key-U4B5QETR.js');
         const hostKey2 = await ensureHostKey2(configPath);
         process.stdout.write(`host key ${hostKey2.fingerprint}
 hooks: ${result2.hooks}
@@ -4713,7 +5024,7 @@ hooks: ${result2.hooks}
       const prepared = prepareRunnerInit(configPath, { machine, allowProcess, agent, credential, keyFromLogin: makeKey !== void 0 });
       const created = makeKey === void 0 ? void 0 : await makeKey();
       const result = writeRunnerInit(prepared, created);
-      const { ensureHostKey } = await import('./host-key-YMLXY6QB.js');
+      const { ensureHostKey } = await import('./host-key-U4B5QETR.js');
       const hostKey = await ensureHostKey(configPath);
       if (created !== void 0) {
         process.stdout.write(`${C.green}\u2713${C.reset} saved the runner key in ${result.configPath}
@@ -4738,10 +5049,10 @@ ${C.yellow}${result.note}${C.reset}
 `);
       if (machine.platform === "darwin" && opts.vm === void 0) {
         process.stdout.write(`
-To isolate builds in containers instead, run ${C.yellow}outerlayer runner init --vm${C.reset}.
+To isolate builds in containers instead, run ${C.yellow}${cliInvocation()} runner init --vm${C.reset}.
 `);
       }
-      const { runRunnerInstall, RunnerInstallError, RunnerDowngradeError, launcherSummary } = await import('./install-cmd-5HYMXLEW.js');
+      const { runRunnerInstall, RunnerInstallError, RunnerDowngradeError, launcherSummary } = await import('./install-cmd-QDOTR4OM.js');
       let installedLayout = false;
       let noService = "it starts the runner from the install layout, which needs a CLI installed with npm";
       try {
@@ -4773,7 +5084,7 @@ ${C.yellow}The runner will not update itself: ${installErr.message}${C.reset}
       let serviceUp = false;
       let restart;
       if (installedLayout) {
-        const { installServiceCommand } = await import('./command-R2QCVX55.js');
+        const { installServiceCommand } = await import('./command-OEAV7BVX.js');
         const service = await installServiceCommand({
           configPath,
           entryPath: process.argv[1] ?? "",
@@ -4795,14 +5106,14 @@ ${C.yellow}The runner will not update itself: ${installErr.message}${C.reset}
       if (restart !== void 0) process.stdout.write(`
 ${C.yellow}${restart}${C.reset}
 `);
-      const steps = agent === void 0 ? [`Edit the command lines in ${result.configPath} to start your agent.`, `${C.yellow}outerlayer runner check${C.reset}`] : [`${C.yellow}outerlayer runner check${C.reset}`];
-      if (!serviceUp) steps.push(`${C.yellow}outerlayer runner start${C.reset}, or ${C.yellow}outerlayer runner install --service${C.reset} to keep it running.`);
+      const steps = agent === void 0 ? [`Edit the command lines in ${result.configPath} to start your agent.`, `${C.yellow}${cliInvocation()} runner check${C.reset}`] : [`${C.yellow}${cliInvocation()} runner check${C.reset}`];
+      if (!serviceUp) steps.push(`${C.yellow}${cliInvocation()} runner start${C.reset}, or ${C.yellow}${cliInvocation()} runner install --service${C.reset} to keep it running.`);
       process.stdout.write(
         `
 Next:
 ` + steps.map((step, i) => `  ${i + 1}. ${step}
-`).join("") + (serviceUp && agent === void 0 ? `  The runner service claims nothing until step 1 is done and a Claude credential is in ${join(dirname(configPath), "runner.env")}; ${C.yellow}outerlayer runner status${C.reset} shows what it is doing.
-` : serviceUp ? `  The runner service is running; ${C.yellow}outerlayer runner status${C.reset} shows what it is doing.
+`).join("") + (serviceUp && agent === void 0 ? `  The runner service claims nothing until step 1 is done and a Claude credential is in ${join(dirname(configPath), "runner.env")}; ${C.yellow}${cliInvocation()} runner status${C.reset} shows what it is doing.
+` : serviceUp ? `  The runner service is running; ${C.yellow}${cliInvocation()} runner status${C.reset} shows what it is doing.
 ` : "")
       );
     } catch (err) {
@@ -4813,29 +5124,42 @@ Next:
       throw err;
     }
   });
-  runnerCmd.command("image").description("Build a repository's image from its default branch's devcontainer file").requiredOption("--repository <owner/name>", "the repository to build the image for").option("--remote <url>", "where to fetch from (default: the repository's GitHub URL)").option("--config <path>", configOption).option("--json", "machine-readable JSON output").addHelpText(
+  runnerCmd.command("image").description("Build a repository's image from its governing repository's devcontainer").requiredOption("--repository <owner/name>", "the repository to build the image for").option("--remote <url>", "where to fetch from (default: the repository's GitHub URL)").option("--config <path>", configOption).option("--json", "machine-readable JSON output").addHelpText(
     "after",
-    "\nFetches the head of the default branch into the runner's cache, reads its\n.devcontainer/devcontainer.json, and builds the image with the devcontainer CLI. Settings\nthat reach the host or widen the container's privileges are ignored and listed. The\nimage holds this CLI and a pinned Claude Code. Nothing runs inside the image.\n"
+    "\nA repository governed by a control plane builds the control plane's image, at the commit\nthe gateway has stored for it. A repository that governs itself fetches the head of its\ndefault branch into the runner's cache. Either way it reads .devcontainer/devcontainer.json\nand builds the image with the devcontainer CLI. Settings\nthat reach the host or widen the container's privileges are ignored and listed. The\nimage holds this CLI and a pinned Claude Code. Nothing runs inside the image.\n"
   ).action(async (opts) => {
-    const { defaultRunnerConfigPath } = await import('./config-N3C6DFQA.js');
-    const { buildRepositoryImage, RecipeError } = await import('./build-BG2YENGK.js');
+    const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
+    const { buildRepositoryImage, RecipeError } = await import('./build-TQ6X5PYN.js');
     const { currentCliBuild } = await import('./cli-build-K56DK4DS.js');
-    const { createDockerHost } = await import('./docker-4J77Q2BF.js');
-    const { builderSpec } = await import('./builder-2D3WSOOY.js');
-    const { loadRunnerConfig } = await import('./config-N3C6DFQA.js');
+    const { createDockerHost } = await import('./docker-BFU3AQGY.js');
+    const { builderSpec } = await import('./builder-C4QNTYMS.js');
+    const { loadRunnerConfig } = await import('./config-CLSGABD5.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
-    const memory = (() => {
+    const loaded = (() => {
       try {
-        return loadRunnerConfig(configPath).build?.memory ?? "8g";
+        return loadRunnerConfig(configPath);
       } catch {
-        return "8g";
+        return void 0;
       }
     })();
+    const memory = loaded?.build?.memory ?? "8g";
     try {
+      const { imageTargetFor } = await import('./governing-source-V5EEGPTA.js');
+      const target = await imageTargetFor({ config: loaded, repository: opts.repository, fetchImpl: fetch });
+      if (!target.ok) {
+        if (opts.json) {
+          writeJson({ error: { code: "governing_source_unavailable", message: target.reason } });
+          process.exitCode = 1;
+          return;
+        }
+        fail(target.reason);
+        return;
+      }
       const result = await buildRepositoryImage(
         {
-          repository: opts.repository,
-          remote: opts.remote,
+          repository: target.repository,
+          ...target.pinned === void 0 ? {} : { pinned: target.pinned },
+          remote: target.pinned === void 0 ? opts.remote : void 0,
           configPath,
           cli: currentCliBuild(),
           log: (line) => {
@@ -4883,22 +5207,22 @@ Next:
     }
   });
   runnerCmd.command("stop").description("Take no more work; wait for running jobs to finish, then exit").option("--config <path>", "the cloud config file naming the runner to stop").option("--now", "end running jobs immediately, with outcome stopped").action(async (opts) => {
-    const { defaultRunnerConfigPath } = await import('./config-N3C6DFQA.js');
-    const { requestStop } = await import('./loop-FK3LPMMZ.js');
+    const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
+    const { requestStop } = await import('./loop-SYYPVFYW.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     await requestStop(configPath, Boolean(opts.now));
   });
   runnerCmd.command("status").description("List running jobs; with --recent, finished ones too").option("--config <path>", "the cloud config file naming the runner to inspect").option("--recent", "also list finished jobs, newest first, capped at 20").option("--json", "machine-readable JSON output").action(async (opts) => {
-    const { defaultRunnerConfigPath, loadRunnerConfig } = await import('./config-N3C6DFQA.js');
-    const { jobsDir, runnerDir } = await import('./paths-OYKMVYJP.js');
-    const { listJobFiles, runnerProcessState } = await import('./loop-FK3LPMMZ.js');
-    const { renderStatus } = await import('./status-7VNQN5PW.js');
-    const { readHousekeepingRecord } = await import('./record-C43U4PKS.js');
+    const { defaultRunnerConfigPath, loadRunnerConfig } = await import('./config-CLSGABD5.js');
+    const { jobsDir, runnerDir } = await import('./paths-7XP63OAX.js');
+    const { listJobFiles, runnerProcessState } = await import('./loop-SYYPVFYW.js');
+    const { renderStatus } = await import('./status-NAK6DYSF.js');
+    const { readHousekeepingRecord } = await import('./record-3WP6V2K5.js');
     const path2 = await import('path');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     const all = listJobFiles(configPath);
     const housekeeping = readHousekeepingRecord(runnerDir(configPath));
-    const { readPendingUpdate } = await import('./pending-MXLSRYMO.js');
+    const { readPendingUpdate } = await import('./pending-532ABZYC.js');
     const pendingUpdate = readPendingUpdate(runnerDir(configPath));
     let host = "unknown";
     let concurrency = 1;
@@ -4912,7 +5236,7 @@ Next:
     const service = await (async () => {
       if (process.platform !== "linux" || !existsSync("/run/systemd/system")) return void 0;
       const { inspectService, realInspectProbes } = await import('./inspect-6UYAAXH7.js');
-      const { DEFAULT_UNIT_NAME } = await import('./install-HDBIPHTX.js');
+      const { DEFAULT_UNIT_NAME } = await import('./install-4SEFIIW2.js');
       const facts = inspectService(DEFAULT_UNIT_NAME, path2.dirname(configPath), realInspectProbes());
       return facts === void 0 ? void 0 : { unit: facts.unit, running: facts.mainPid !== void 0, delegated: facts.delegate };
     })();
@@ -4947,9 +5271,9 @@ Next:
     );
   });
   runnerCmd.command("logs").argument("<item>", "the work item's number in the factory").description("Print the newest attempt's log for one item").option("--config <path>", "the cloud config file naming the runner to inspect").option("-f, --follow", "keep printing as the log grows").action(async (itemArg, opts) => {
-    const { defaultRunnerConfigPath } = await import('./config-N3C6DFQA.js');
-    const { listJobFiles } = await import('./loop-FK3LPMMZ.js');
-    const { newestAttempt, logPathFor, tail, RunnerLogsError } = await import('./logs-H55NWW4H.js');
+    const { defaultRunnerConfigPath } = await import('./config-CLSGABD5.js');
+    const { listJobFiles } = await import('./loop-SYYPVFYW.js');
+    const { newestAttempt, logPathFor, tail, RunnerLogsError } = await import('./logs-AMLKC3VP.js');
     const configPath = opts.config ?? defaultRunnerConfigPath();
     const item = parseTrackerNumber(itemArg);
     if (item === void 0) {
@@ -4983,32 +5307,22 @@ function registerHooksCommands(program2) {
     "after",
     "\n`init` auto-wraps PreToolUse/PostToolUse hooks; these subcommands cover the\nrest: manual re-scans, other events, and undo.\n"
   );
-  hooksCmd.command("install-git").description("Install the commit-guard git hook in this repo").option("--print", "print the hook scripts instead of installing").addHelpText(
+  hooksCmd.command("install-git").description("Remove the git hooks an earlier version installed in this repo").addHelpText(
     "after",
-    "\nThe same install `init` performs. `--print` writes the script to stdout for\nrepositories that manage hooks in-tree (husky and friends).\n"
-  ).action((opts) => {
-    if (opts.print) {
-      for (const [name, script] of managedHookScripts()) {
-        process.stdout.write(`# ==== ${name} ====
-${script}
-`);
-      }
-      return;
-    }
+    "\nEarlier versions installed a pre-commit guard and commit journal hooks. This removes\nthe ones OuterLayer wrote and leaves any hook it did not write untouched.\n"
+  ).action(() => {
     const removal = removeJournalHooks(process.cwd());
     if (removal.removed) {
       process.stdout.write(`${C.green}\u2713${C.reset} removed the commit journal hooks an earlier version installed \u2192 ${removal.path}
 `);
     }
-    const guard = installPreCommitGuardHook(process.cwd());
-    const report = formatGuardInstallOutput(guard);
-    if (report.error !== void 0) {
-      fail(report.error);
-      return;
+    const guard = removePreCommitGuardHook(process.cwd());
+    if (guard.removed) {
+      process.stdout.write(`${C.green}\u2713${C.reset} removed the pre-commit guard an earlier version installed \u2192 ${guard.path}
+`);
     }
-    for (const line of report.lines) process.stdout.write(`${line}
+    if (!removal.removed && !guard.removed) process.stdout.write(`${C.dim}No git hooks from an earlier version were found.${C.reset}
 `);
-    if (report.exitCode !== void 0) process.exitCode = report.exitCode;
   });
   hooksCmd.command("status").description("List hook entries in user and project settings, marking the wrapped ones").option("--json", "machine-readable JSON output").action((opts) => {
     const report = [];
@@ -5170,9 +5484,22 @@ function registerMcpCommands(program2) {
   const mcpCmd = program2.command("mcp").description("Configure MCP clients against the OuterLayer gateway");
   mcpCmd.command("install").description("Write or update the OuterLayer entry in .mcp.json or .outerlayer/mcp.json").option("--transport <stdio|http>", "how the client connects (default: stdio)").option("--command <exe>", "stdio only: executable the client spawns (default: outerlayer)").option("--url <url>", "gateway MCP endpoint (defaults to the gateway you logged in to)").option("--name <name>", 'mcpServers key to write under (default: "outerlayer")').option("--dir <path>", "repo root to write into (default: cwd)").option("--app-id <uuid>", "self-host only: factory id sent as X-Outerlayer-App-Id").option("--json", "machine-readable JSON output").addHelpText(
     "after",
-    "\nThe API key is never a flag and never written to .mcp.json as a literal value.\n  stdio (default): the client spawns `outerlayer mcp serve`, which reads the key\n  from ~/.outerlayer/config.json (or OUTERLAYER_API_KEY) on every connect, so a\n  rotated key is picked up without rewriting the entry.\n  http: the entry carries the ${OUTERLAYER_API_KEY} placeholder, which the client\n  resolves from the environment it was launched with.\n\n--command: use an absolute or ${HOME}-relative path when the CLI is not on PATH.\n--url: with stdio the endpoint resolves from OUTERLAYER_URL / the config file at\nconnect time; for self-host pass your gateway-node origin + /v1/mcp.\nSelf-host deployments also need --app-id: without a key service to resolve the\ncaller from the bearer token, the gateway answers 401 without that header.\n"
+    `
+The API key is never a flag and never written to .mcp.json as a literal value.
+  stdio (default): the client spawns \`${cliInvocation()} mcp serve\`, which reads the key
+  from ~/.outerlayer/config.json (or OUTERLAYER_API_KEY) on every connect, so a
+  rotated key is picked up without rewriting the entry.
+  http: the entry carries the \${OUTERLAYER_API_KEY} placeholder, which the client
+  resolves from the environment it was launched with.
+
+--command: use an absolute or \${HOME}-relative path when the CLI is not on PATH.
+--url: with stdio the endpoint resolves from OUTERLAYER_URL / the config file at
+connect time; for self-host pass your gateway-node origin + /v1/mcp.
+Self-host deployments also need --app-id: without a key service to resolve the
+caller from the bearer token, the gateway answers 401 without that header.
+`
   ).action(async (opts) => {
-    const { runMcpInstall, handleMcpInstallError, McpInstallError } = await import('./mcp-install-cmd-FDTPQQS6.js');
+    const { runMcpInstall, handleMcpInstallError, McpInstallError } = await import('./mcp-install-cmd-GGWB3JJ2.js');
     try {
       if (opts.transport !== void 0 && opts.transport !== "stdio" && opts.transport !== "http") {
         throw new McpInstallError(`--transport must be "stdio" or "http", got "${opts.transport}"`);
@@ -5194,7 +5521,7 @@ function registerMcpCommands(program2) {
     "after",
     "\nWhat the stdio .mcp.json entry spawns. Reads newline-delimited JSON-RPC 2.0 on\nstdin and writes responses on stdout. The API key comes from OUTERLAYER_API_KEY\nor ~/.outerlayer/config.json at start-up; with neither the command exits 1 and\nprints why, which the MCP client shows as the connect error.\n"
   ).action(async (opts) => {
-    const { runMcpServe, handleMcpServeError } = await import('./mcp-serve-cmd-3KVYEUXG.js');
+    const { runMcpServe, handleMcpServeError } = await import('./mcp-serve-cmd-N3UTY6EE.js');
     try {
       await runMcpServe({ url: opts.url, appId: opts.appId });
     } catch (err) {
@@ -5205,7 +5532,7 @@ function registerMcpCommands(program2) {
 function registerImportCommands(program2) {
   const importCmd = program2.command("import").description("Import an existing config format into .outerlayer/");
   importCmd.command("ruler").description("Port a .ruler/ tree into the equivalent .outerlayer/ tree").option("--dir <path>", "repo root to read from (default: cwd)").option("--json", "machine-readable JSON output").addHelpText("after", "\nRuler: https://github.com/intellectronica/ruler. Mostly a rename.\n").action(async (opts) => {
-    const { runImportRuler, ImportRulerError } = await import('./import-ruler-cmd-BGAZXCQM.js');
+    const { runImportRuler, ImportRulerError } = await import('./import-ruler-cmd-5P6JOXQN.js');
     try {
       const result = runImportRuler({ cwd: opts.dir, json: opts.json });
       if (result.exitCode !== 0) process.exitCode = result.exitCode;
@@ -5221,7 +5548,7 @@ function registerImportCommands(program2) {
     "after",
     "\nInstalls the four maintained skills (outerlayer-evidence, outerlayer-amend,\nouterlayer-findings, outerlayer-cli) and an AGENTS.md snippet teaching agents to run\n`emit artifact`. A skill that differs from this CLI's bundle is rewritten to it, and the output says so.\n"
   ).action(async (opts) => {
-    const { runImportCapture, ImportCaptureError } = await import('./import-capture-cmd-EQ35EARA.js');
+    const { runImportCapture, ImportCaptureError } = await import('./import-capture-cmd-KKFFOGWP.js');
     try {
       runImportCapture({ cwd: opts.dir, json: opts.json });
     } catch (err) {
@@ -5233,59 +5560,14 @@ function registerImportCommands(program2) {
     }
   });
 }
-function formatContextMaterializeOutput(result) {
-  switch (result.status) {
-    case "not-a-repo":
-      return { stdout: [], stderr: [`${C.red}\u2717${C.reset} not inside a git repository.`], exitCode: 1 };
-    case "self":
-      return { stdout: [`${C.dim}This repository is self-sourced \u2014 nothing to materialize.${C.reset}`], stderr: [] };
-    case "materialized": {
-      const stdout = [`${C.green}\u2713${C.reset} Materialized context at ${C.dim}${result.sha?.slice(0, 7)}${C.reset}`];
-      if (result.message) stdout.push(`${C.yellow}!${C.reset} ${result.message}`);
-      return { stdout, stderr: [] };
-    }
-    case "debounced": {
-      const stdout = [`${C.green}\u2713${C.reset} Already current at ${C.dim}${result.sha?.slice(0, 7)}${C.reset} (verification: ${result.verification})`];
-      if (result.message) stdout.push(`${C.yellow}!${C.reset} ${result.message}`);
-      return { stdout, stderr: [] };
-    }
-    case "adoption-conflict":
-      return { stdout: [`${C.yellow}!${C.reset} ${result.message}`], stderr: [], exitCode: 1 };
-    default:
-      return { stdout: [`${C.yellow}!${C.reset} ${result.message ?? result.status}`], stderr: [], exitCode: 1 };
-  }
-}
 function registerContextCommands(program2) {
-  const contextCmd = program2.command("context").description("Compile and materialize agent context");
+  const contextCmd = program2.command("context").description("Compile agent context");
   contextCmd.command("emit").description("Compile .outerlayer/ into each configured target tool's native files").option("--check", "compare against disk, write nothing, exit 1 on drift (CI mode)").option("--dir <path>", "repo root to read from (default: cwd)").option("--json", "machine-readable JSON output").addHelpText(
     "after",
     '\nTargets come from .outerlayer/config.json only; there is no --target flag.\nMissing or empty config: {"targets": [...]}, e.g. {"targets": ["claude-code"]}.\nKnown targets: claude-code, cursor, codex, copilot, factory.\n\nThe maintained skills (outerlayer-evidence, outerlayer-amend, outerlayer-findings,\nouterlayer-cli) follow this CLI: emit rewrites one that differs from its bundle, and --check\nreports it as drift. A copy under an earlier name (amend, emitting-evidence,\nreporting-findings, outerlayer) is deleted, and --check reports it as retired.\nTemplates (spec, writing-specs, writing-tests, build) are never rewritten or reported.\n\nOrphan detection (--check) only covers header-carrying outputs: every markdown\ntarget file gets a generated-by comment, but .mcp.json and .cursor/mcp.json are\nJSON with no comment syntax, so they can never be flagged as orphaned; missing\nand content drift still apply to them.\n'
   ).action(async (opts) => {
     await compileContext({ dir: opts.dir, check: opts.check, json: opts.json });
   });
-  contextCmd.command("adopt <stagedDir>", { hidden: true }).description("Copy context the runner staged into this checkout (container builds)").option("--json", "machine-readable JSON output").action(async (stagedDir) => {
-    const { runContextAdopt } = await import('./context-adopt-NFHCLVUB.js');
-    const { exitCode, stdout } = runContextAdopt(stagedDir, process.cwd());
-    process.stdout.write(stdout);
-    process.exitCode = exitCode;
-  });
-  contextCmd.command("materialize").description("Materialize this repository's governed context from its control plane").option("--json", "machine-readable JSON output").addHelpText(
-    "after",
-    "\nThe same flow SessionStart runs automatically, exposed for a manual retry or a\nfirst check outside a session. Writes AGENTS.md, .claude/**, and .outerlayer/**.\n"
-  ).action(async (opts) => {
-    const { materializeContext } = await import('./context-materialize-IV2TUUFO.js');
-    const result = await materializeContext({ cwd: process.cwd(), sessionId: `manual-${Date.now()}` });
-    const output = formatContextMaterializeOutput(result);
-    if (output.exitCode !== void 0) process.exitCode = output.exitCode;
-    if (opts.json) {
-      writeJson(result);
-      return;
-    }
-    for (const line of output.stdout) process.stdout.write(`${line}
-`);
-    for (const line of output.stderr) process.stderr.write(`${line}
-`);
-  });
 }
 
-export { buildProgram, formatContextMaterializeOutput, formatGuardInstallOutput, formatInitOutput, runCli };
+export { buildProgram, formatInitOutput, runCli };