omp-conductor 0.3.13 → 0.3.16

package/skills/conductor-update/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: conductor-update
+description: Safely update an installed omp-conductor fleet as one maintenance operation across both separately installed halves: the npm omp plugin and the GitHub herdr-conductor plugin. Use when the user asks to update, upgrade, refresh, reinstall, or deploy a newly published conductor version, or when installed conductor code is behind npm/main. Quiesces work, preserves exact pane identity, performs a whole-version swap, restarts through the supported lifecycle, re-arms through Telegram proof, and verifies the live fleet.
+---
+
+# Update a conductor fleet
+
+Treat an update as one operation across two independently installed plugins:
+
+- `omp-conductor` comes from npm and owns dispatch, CLI, status, and heartbeat.
+- `herdr-conductor` comes from `TerrifiedBug/conductor/herdr` and owns exact-pane recovery.
+
+Updating only one half can leave a version that starts but cannot recover correctly.
+This skill updates an installed fleet. It does **not** publish npm, merge a PR, tag a
+release, or edit files in an install directory.
+
+## Safety boundary
+
+Run this procedure from an operator shell or maintenance omp session that is not
+hosted by the target `herdr-fleet.service`. If the current working directory
+contains `.conductor-tick.json`, or stopping that unit would kill the session
+executing this skill, stop and move the update to an external maintenance
+session. A self-terminating updater cannot produce trustworthy verification.
+
+Use the configured target host. Do not assume a hostname, state directory, Herdr
+session name, project name, or systemd availability. Read them from the existing
+installation and `omp-conductor status`. Never print bot tokens, npm tokens, or
+authentication files.
+
+## 1. Establish the desired version
+
+Read, do not guess:
+
+```bash
+omp-conductor --version
+version=$(npm view omp-conductor version)
+gitHead=$(npm view "omp-conductor@$version" gitHead)
+npm view "omp-conductor@$version" version gitHead --json
+omp plugin list --json
+omp-conductor status [--project NAME]
+```
+
+Use the registry latest as `$version` unless the user explicitly names another
+published version, then query that exact version as shown. Record its `gitHead`
+and require a full commit SHA: the npm spec and Herdr ref below are both pinned,
+so a concurrent release cannot mix two versions. If npm has no newer version, do
+not churn the fleet: report that it is current. Confirm that `herdr` and
+`systemctl` are present before taking anything down when status says Herdr
+manages the pane.
+
+## 2. Quiesce without losing work
+
+First stop new claims and heartbeat prompts:
+
+```bash
+omp-conductor hold [--project NAME]
+```
+
+Read status until `active runs (none)`. Do not kill workers to make the update
+faster. If a run does not drain, report the run and stop; ordinary update authority
+does not include discarding work.
+
+Then stop the exact conductor pane and dispatch daemon through the supported,
+fail-closed path:
+
+```bash
+omp-conductor halt --pane [--project NAME]
+```
+
+This writes the recovery pin before stopping the exact configured Herdr agent. If
+identity is invalid, missing, or ambiguous, it refuses rather than killing a guess.
+Do not bypass that refusal with `pkill`.
+
+When `herdr-fleet.service` is installed, stop it before replacing either plugin:
+
+```bash
+systemctl stop herdr-fleet.service
+```
+
+At this point the daemon is stopped, the pane is stopped, and recovery remains
+pinned. If any of those statements is false, do not modify the install.
+
+## 3. Replace both installed halves
+
+Refresh the exact npm version using omp's package installer:
+
+```bash
+omp plugin install "omp-conductor@$version"
+```
+
+Then refresh the Herdr managed checkout from the exact npm release commit. Herdr
+requires the GitHub source before its options:
+
+```bash
+herdr plugin install TerrifiedBug/conductor/herdr --ref "$gitHead" --yes
+```
+
+Do not use `git pull`, `scp`, a linked checkout, or edits under either plugin's
+install root. This is a whole-version swap. If either install fails, leave the
+fleet stopped and recovery pinned; report the failed command and do not continue
+with a mixed live version.
+
+## 4. Start through the new lifecycle
+
+Run the newly installed CLI:
+
+```bash
+omp-conductor --version
+omp-conductor start [--project NAME]
+```
+
+`start` clears the recovery pin, starts the optional `herdr-fleet.service`, and
+starts the dispatch daemon after a real `/healthz` check. Herdr then recovers the
+exact orchestrator pane and requests an immediate tick; the verification below,
+not the `start` command alone, proves that recovery completed.
+
+Wait until `omp-conductor status` reports the exact pane `live`; `start` returning
+only proves the service and dispatch daemon. `hold` deliberately disarmed ticks,
+so restore unattended operation through the existing Telegram proof:
+
+```bash
+omp-conductor arm [--project NAME]
+```
+
+Wait for the operator's inbound Telegram reply. Never create the arm marker by
+hand and never treat an outbound challenge as proof.
+
+## 5. Verify the live result
+
+Require all of the following before reporting success:
+
+```bash
+omp-conductor --version
+npm view "omp-conductor@$version" version gitHead --json
+omp plugin list --json
+herdr plugin list
+omp-conductor status [--project NAME]
+systemctl is-active herdr-fleet.service
+```
+
+- installed version and the npm package entry both equal `$version`;
+- the Herdr plugin source revision equals the npm release `gitHead`;
+- `dispatch` is `running`;
+- `ticks` is `armed` and a next tick is shown;
+- `pane` is `live` for the exact configured Herdr agent;
+- `recovery` is `clear`;
+- `herdr` is `active` when managed;
+- Telegram is `ok` (or its exact supported degraded state is reported);
+- daemon `/healthz` is `ok`;
+- no unexpected active runs appeared during maintenance.
+
+Run a second status check after the immediate recovery tick is consumed. A single
+healthy snapshot is not proof that recovery and heartbeat scheduling survived the
+swap.
+
+Report the old and new versions, both plugin refreshes, the final layered status,
+and any supported degraded state. Do not report success for a partial update.

package/src/brief-upgrade.ts

@@ -573,7 +573,7 @@ export function formatBriefStatus(path: string, status: BriefStatus): string {
       `  floor        package template → recomposed into ${status.orchestratorPath} each tick`,
       `  policy       ${status.policyPath} (Learning loop / operator edits)`,
       "",
-      "Protocol updates: npm install omp-conductor@… and restart — no brief-upgrade --apply.",
+      "Protocol updates: upgrade omp-conductor in this host's existing install root (same package manager), then restart the daemon — no brief-upgrade --apply.",
       "Legacy migrate:   omp-conductor brief-upgrade --migrate",
     ].join("\n");
   }

package/src/briefs/orchestrator.md

@@ -3,8 +3,9 @@
 This file is the **package floor**: duties, tiers, hard boundaries, and the
 Learning loop. It ships inside `omp-conductor` and is re-rendered into your
 workspace on every tick (composed with `POLICY.md` as `ORCHESTRATOR.md` for the
-session). Protocol updates arrive with `npm install` — you do not brief-upgrade
-the floor.
+session). Protocol updates arrive when you upgrade the installed `omp-conductor`
+package (same package manager / install root) and restart — you do not
+brief-upgrade the floor.
 
 Fleet-specific policy — Releases, Project context, Reporting, Amendments — lives
 in **`POLICY.md`** beside this composed brief. The Learning loop edits

package/src/briefs/worker.md

@@ -15,7 +15,7 @@ inside your own worktree.
 - **Code repo:** {{REPO}}
 - **Your worktree (cwd):** `{{WORKTREE}}`
 - **Your branch:** `{{BRANCH}}` — already created for you off the repo's default
-  branch. Never switch branches and never touch a path outside the worktree.
+  branch. Never switch branches and never touch a path outside the worktree (write/edit/read/grep/glob are also blocked mechanically outside this checkout; `bash` is still a must-not — do not use it to escape).
 
 Read the issue first — it carries the acceptance criteria and any discussion the
 dispatcher did not copy down:

package/src/cli.ts

@@ -21,12 +21,22 @@ import {
   writeMergedBrief,
 } from "./brief-upgrade.ts";
 import { findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
-import { dbPath, formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
+import { dbPath, runDaemon, setPaused } from "./daemon.ts";
+import {
+  armTicks,
+  clearPaneHalt,
+  disarmTicks,
+  halt,
+  haltWithPane,
+  hold,
+  releaseHold,
+  renderStatus,
+  startHerdrFleet,
+} from "./fleet.ts";
 import { formatGraphSetup, graphRepos, writeGraphSetup, type GraphSetupWrite } from "./graph.ts";
 import {
   clearRecord,
   DEFAULT_PORT,
-  healthCheck,
   livingDaemon,
   restartDaemon,
   startDaemon,
@@ -46,13 +56,29 @@ import { makeTracker } from "./tracker/github.ts";
 import type { ProjectConfig } from "./types.ts";
 import { formatUnblock, unblockIssue } from "./unblock.ts";
 
+function packageVersion(): string {
+  const parsed = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf8")) as {
+    version?: unknown;
+  };
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error("installed package.json has no version");
+  }
+  return parsed.version;
+}
+
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
 usage:
   omp-conductor start [--port N] [--project NAME]
+  omp-conductor --version
   omp-conductor stop
   omp-conductor restart [--port N] [--project NAME]
   omp-conductor status [--project NAME]
+  omp-conductor hold [--project NAME]
+  omp-conductor halt [--pane] [--project NAME]
+  omp-conductor arm [--project NAME]
+  omp-conductor disarm [--project NAME]
+  omp-conductor release-pane [--project NAME]
   omp-conductor tail <issue> [--project NAME]
   omp-conductor unblock <issue> [--project NAME]
   omp-conductor daemon [--once] [--port N] [--project NAME]
@@ -62,9 +88,9 @@ usage:
   omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
   omp-conductor help
 
-  start    run the dispatch loop in the background and wait until it answers
-           GET /healthz on :8787 (override with --port). Refuses if one is
-           already running.
+  start    start the installed herdr-fleet.service when present, then run the
+           dispatch loop in the background and wait until it answers GET
+           /healthz on :8787 (override with --port). Refuses if one is running.
   stop     stop the running daemon. Uses systemctl when the omp-conductor
            unit owns the process (so Restart=on-failure cannot bring it back);
            otherwise SIGTERM then SIGKILL.
@@ -73,8 +99,23 @@ usage:
            dirty live worktrees before orphaning those rows — see README
            "Deploying a new package onto a busy fleet". Goes through systemctl
            when the unit owns the live pid.
-  status   show pause state, caps, active runs, today's usage, and whether a
-           daemon is alive.
+  status   layered fleet report: dispatch (running|paused|stopped), ticks and
+           next due time, pane, herdr, Telegram bot/API health, daemon, caps
+           and active runs.
+  hold     soft stop: pause claiming AND disarm ticks. Daemon and pane stay up.
+           This is "stop the conductor overnight" without killing processes.
+  halt     hold, then stop the dispatch daemon (systemctl-aware). Pane stays up
+           unless --pane is passed.
+  halt --pane
+           halt, then pin herdr-conductor recovery off for the conductor agent
+           only — does NOT stop herdr-fleet.service or any other herdr session.
+           Clear the pin with release-pane when you want recovery again.
+  arm      proof-gated: send a Telegram challenge and write the arm marker only
+           after your reply appears as a user turn in the orchestrator transcript.
+           Never auto-armed by resume/hold.
+  disarm   remove the arm marker so ticks skip. Processes untouched.
+  release-pane
+           clear the halt --pane recovery pin so herdr-conductor may resume again.
   tail     follow the newest run for <issue>: the worker's assistant text and
            the tools it calls, printed as they land. Workers are sessions inside
            the daemon rather than terminals, so this is the only way to watch
@@ -87,8 +128,8 @@ usage:
            cost a worker.
   daemon   run the dispatch loop in the foreground; --once runs a single tick
            and exits. This is what \`start\` launches.
-  pause    stop claiming new work. The running daemon notices on its next tick.
-  resume   allow claiming again.
+  pause    stop claiming new work only (ticks keep firing if armed). Prefer hold.
+  resume   clear pause only — does NOT re-arm. Prefer hold's inverse: resume + arm.
   graph-setup
            print how to set up the code-graph indexes workers query instead of
            grepping: the clone commands for any missing index-only clone, the
@@ -105,12 +146,22 @@ usage:
            --apply still merges a bannered single-file brief. --file checks a
            brief that is not where the wizard would have put it.
   help     print this text (also --help, -h).
+  --version
+           print the installed omp-conductor package version (also -V, version).
 
 Pause is a flag file under the state directory, so it applies to every project
-and survives a daemon restart. A running daemon is tracked by a pidfile under
-$OMP_CONDUCTOR_RUNTIME_DIR (default ~/.omp/run/daemons/omp-conductor), written
-whether it was started in the background or in the foreground, and probed for
-liveness on every read — a stale one never blocks a start.`;
+and survives a daemon restart. Hold also removes the arm marker the heartbeat
+reads, so both brains go quiet without killing processes. A running daemon is
+tracked by a pidfile under $OMP_CONDUCTOR_RUNTIME_DIR (default
+~/.omp/run/daemons/omp-conductor), written whether it was started in the
+background or in the foreground, and probed for liveness on every read — a
+stale one never blocks a start.
+
+Stop the conductor:
+  hold              no claims, no tick sends (inspectable)
+  halt              hold + stop dispatch daemon
+  halt --pane       halt + pin conductor-pane recovery off
+  resume && arm     clear pause, then prove inbound Telegram before ticks resume`;
 
 /** Accepts both `--port 9000` and `--port=9000`; returns undefined when absent. */
 function flag(argv: string[], name: string): string | undefined {
@@ -146,26 +197,6 @@ function humanDuration(ms: number): string {
   return `${Math.floor(h / 24)}d ${String(h % 24).padStart(2, "0")}h`;
 }
 
-/**
- * The daemon half of `status`. Kept separate from `formatStatus` because the
- * pidfile and the endpoint are the CLI's business, not the dispatcher's, and
- * because a pid without a `/healthz` answer is a distinct — and interesting —
- * state: the process is up but the loop is not serving.
- */
-async function daemonSection(): Promise<string> {
-  const rec = livingDaemon();
-  if (rec === undefined) return "daemon    not running";
-  const health = await healthCheck(rec.port);
-  return [
-    "daemon",
-    `  pid       ${rec.pid}`,
-    `  uptime    ${humanDuration(Date.now() - rec.startedAt)}`,
-    `  port      ${rec.port}`,
-    ...(rec.project === undefined ? [] : [`  project   ${rec.project}`]),
-    `  healthz   ${health.ok ? `ok  ${health.body ?? ""}`.trimEnd() : "unreachable — the process is up but not serving"}`,
-    `  log       ${rec.logFile}`,
-  ].join("\n");
-}
 
 /**
  * The orchestrator half, and the one thing `status` has ever known about the
@@ -362,6 +393,11 @@ const cmd = argv[0];
 
 try {
   switch (cmd) {
+    case "--version":
+    case "-V":
+    case "version":
+      process.stdout.write(`${packageVersion()}\n`);
+      break;
     case "daemon": {
       // Until now only `lifecycle.startDaemon()` — the spawn path — wrote the
       // pidfile, which left a daemon started in the foreground (which is how
@@ -413,10 +449,14 @@ try {
     }
 
     case "start": {
-      const rec = await startDaemon({ port: portFlag(argv), project: flag(argv, "project") });
+      const project = flag(argv, "project");
+      const herdr = startHerdrFleet(project);
+      const rec = await startDaemon({ port: portFlag(argv), project });
       process.stdout.write(
         `started — pid ${rec.pid}, /healthz on :${rec.port}` +
-          `${rec.project === undefined ? "" : `, project ${rec.project}`}\nlog ${rec.logFile}\n`,
+          `${rec.project === undefined ? "" : `, project ${rec.project}`}\n` +
+          `herdr ${herdr.kind === "active" ? `active (${herdr.unit})${herdr.recoveryReleased ? "; recovery pin cleared" : ""}` : `unmanaged (${herdr.reason})`}\n` +
+          `log ${rec.logFile}\n`,
       );
       break;
     }
@@ -456,9 +496,84 @@ try {
     }
 
     case "status": {
-      const snapshot = formatStatus(statusSnapshot(flag(argv, "project")));
+      const project = flag(argv, "project");
+      const text = await renderStatus(project);
       const stalled = stallLine();
-      process.stdout.write(`${snapshot}\n\n${await daemonSection()}\n${stalled === undefined ? "" : `\n${stalled}\n`}`);
+      process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${stalled}\n`}`);
+      break;
+    }
+
+    case "hold": {
+      const r = hold(flag(argv, "project"));
+      process.stdout.write(
+        `held — claiming paused` +
+          `${r.wasPaused ? " (already paused)" : ""}` +
+          `; ticks disarmed at ${r.disarmed.path}` +
+          `${r.disarmed.wasArmed ? "" : " (was already disarmed)"}\n` +
+          `daemon and pane left running; halt to stop the daemon\n`,
+      );
+      break;
+    }
+
+    case "halt": {
+      const project = flag(argv, "project");
+      const withPane = argv.includes("--pane");
+      if (withPane) {
+        const r = await haltWithPane(project);
+        const stopLine =
+          r.stop.kind === "not-running"
+            ? "daemon was not running"
+            : `daemon stopped — pid ${r.stop.pid}${r.stop.via === "systemctl" ? " (via systemctl)" : ""}`;
+        process.stdout.write(
+          `halted — claiming paused; ticks disarmed at ${r.hold.disarmed.path}\n` +
+            `${stopLine}\n` +
+            `pane recovery pinned at ${r.pane.pinPath}\n` +
+            `pane stop: ${r.pane.stopped} — ${r.pane.detail}\n` +
+            `  (conductor agent "${r.pane.agentName}" only — herdr-fleet.service was NOT stopped;\n` +
+            `   release-pane clears the pin when you want recovery again)\n`,
+        );
+      } else {
+        const r = await halt(project);
+        const stopLine =
+          r.stop.kind === "not-running"
+            ? "daemon was not running"
+            : `daemon stopped — pid ${r.stop.pid}${r.stop.via === "systemctl" ? " (via systemctl)" : ""}`;
+        process.stdout.write(
+          `halted — claiming paused; ticks disarmed at ${r.hold.disarmed.path}\n` +
+            `${stopLine}\n` +
+            `pane left running (pass --pane to stop the conductor agent and pin recovery)\n`,
+        );
+      }
+      break;
+    }
+
+    case "arm": {
+      process.stdout.write("arm: sending inbound Telegram challenge…\n");
+      const r = await armTicks(flag(argv, "project"));
+      process.stdout.write(
+        `ARMED — inbound round-trip proved with owner ${r.owner}; ticks are now live.\n` +
+          `marker ${r.path}${r.alreadyArmed ? " (replaced previous marker)" : ""}\n`,
+      );
+      break;
+    }
+
+    case "disarm": {
+      const r = disarmTicks(flag(argv, "project"));
+      process.stdout.write(
+        `disarmed — ticks will be skipped` +
+          `${r.wasArmed ? "" : " (was already disarmed)"}\n` +
+          `marker ${r.path}\n`,
+      );
+      break;
+    }
+
+    case "release-pane": {
+      const r = clearPaneHalt(flag(argv, "project"));
+      process.stdout.write(
+        r.wasHalted
+          ? `pane recovery pin cleared — ${r.path}\nherdr-conductor may resume the fleet agent again\n`
+          : `no pane recovery pin at ${r.path}\n`,
+      );
       break;
     }
 
@@ -484,12 +599,18 @@ try {
 
     case "pause":
       setPaused(true);
-      process.stdout.write("paused — no new work will be claimed\n");
+      process.stdout.write(
+        "paused — no new work will be claimed\n" +
+          "note: ticks keep firing if armed; use hold to silence both\n",
+      );
       break;
 
     case "resume":
-      setPaused(false);
-      process.stdout.write("resumed — work will be claimed on the next tick\n");
+      releaseHold();
+      process.stdout.write(
+        "resumed — claiming allowed on the next tick\n" +
+          "note: did NOT re-arm; run arm after an inbound Telegram proof to resume ticks\n",
+      );
       break;
 
     case "graph-setup": {

package/src/confinement.ts

@@ -0,0 +1,123 @@
+/**
+ * Mechanical worktree confinement for worker sessions.
+ *
+ * The harness has no first-class fs-policy field, but `createAgentSession`
+ * accepts inline `extensions` that subscribe to `tool_call` and can return
+ * `{ block: true }` before a tool runs (see the harness `protected-paths`
+ * example). Workers get that gate for structured file tools; the orchestrator
+ * does not — it has to read the state directory and briefs.
+ *
+ * `bash` is deliberately not confined here: its input is an opaque shell
+ * string, and parsing it is a false-sense of security. Closing that gap is a
+ * least-privilege uid (deployment), documented beside this module's README
+ * section — not a regex over `rm -rf`.
+ */
+
+import { existsSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+/** Tools whose structured `path` (or path-like) field we can gate. */
+const GATED = new Set(["write", "edit", "read", "grep", "glob"]);
+
+/**
+ * Resolve `candidate` as a worker would, then ask whether it stays under
+ * `root`. Symlink-aware: existing path components are realpath'd so a link
+ * planted inside the worktree cannot escape by string-prefix tricks.
+ *
+ * A path that does not exist yet (a new write) realpaths the deepest existing
+ * ancestor and appends the rest — the same TOCTOU posture as the harness's
+ * own workspace confinement helper.
+ */
+export function isInsideWorktree(root: string, candidate: string): boolean {
+  if (candidate.length === 0 || candidate.includes("\0")) return false;
+
+  let rootReal: string;
+  try {
+    rootReal = realpathSync(resolve(root));
+  } catch {
+    rootReal = resolve(root);
+  }
+
+  const abs = resolve(rootReal, candidate);
+
+  const missing: string[] = [];
+  let probe = abs;
+  while (!existsSync(probe)) {
+    const parent = dirname(probe);
+    if (parent === probe) break;
+    missing.unshift(basename(probe));
+    probe = parent;
+  }
+
+  let base: string;
+  try {
+    base = realpathSync(probe);
+  } catch {
+    base = probe;
+  }
+  const resolved = missing.length === 0 ? base : join(base, ...missing);
+
+  const rel = relative(rootReal, resolved);
+  // Inside ⇒ "" or a relative path that does not climb out. Absolute `rel` is
+  // a Windows drive mismatch; anything starting with `..` has left the root.
+  return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+
+/** Pull the path-like field a gated tool carries, if any. */
+export function pathFromToolInput(toolName: string, input: Record<string, unknown>): string | undefined {
+  if (!GATED.has(toolName)) return undefined;
+  const path = input.path;
+  if (typeof path === "string" && path.length > 0) return path;
+  // glob / grep sometimes scope via target_directory / path_filter; only a
+  // concrete directory root is confinable without inventing a glob parser.
+  const target = input.target_directory ?? input.cwd;
+  if (typeof target === "string" && target.length > 0) return target;
+  return undefined;
+}
+
+export type ConfineDecision = { block: true; reason: string };
+
+/**
+ * Decide whether one tool_call may run. Undefined means "no opinion" (allow).
+ * Pure so tests pin the gate without standing up a harness session.
+ */
+export function confineToolCall(
+  root: string,
+  toolName: string,
+  input: Record<string, unknown>,
+): ConfineDecision | undefined {
+  const path = pathFromToolInput(toolName, input);
+  if (path === undefined) return undefined;
+  if (isInsideWorktree(root, path)) return undefined;
+  return {
+    block: true,
+    reason:
+      `Blocked: ${toolName} path "${path}" is outside the worker worktree (${root}). ` +
+      `Structured file tools may only touch the assigned checkout; use paths under it.`,
+  };
+}
+
+/**
+ * Minimal extension surface this package needs. Kept duck-typed so the peer
+ * harness does not have to be on disk for `tsc` — same reason `omp.ts` exists.
+ */
+export interface ConfinementPi {
+  on(
+    event: "tool_call",
+    handler: (
+      event: { toolName: string; input: Record<string, unknown> },
+      ctx: unknown,
+    ) => ConfineDecision | undefined | Promise<ConfineDecision | undefined>,
+  ): void;
+}
+
+/**
+ * Inline extension factory for `createAgentSession({ extensions: [...] })`.
+ * Installs the worktree gate on every structured file tool_call.
+ */
+export function worktreeConfinement(root: string): (pi: ConfinementPi) => void {
+  const rootAbs = resolve(root);
+  return (pi) => {
+    pi.on("tool_call", (event) => confineToolCall(rootAbs, event.toolName, event.input));
+  };
+}