@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/proc/kill-tree.d.ts

@@ -38,5 +38,23 @@ export declare function killTree(pid: number | undefined, signal?: NodeJS.Signal
  * The only kill primitive a signal handler, `process.on('exit')` or
  * `handleFatal` may reach (I-9). No escalation ladder and no logging: a reaper
  * that can block or throw is worse than one that misses a child.
+ *
+ * IT RETURNS WHETHER THE KILL WAS CONFIRMED, AND THAT IS NOT BOOKKEEPING. The
+ * Windows branch is a `taskkill` PROCESS, and `spawnSync`'s own `timeout` kills
+ * that process when the budget runs out. Measured on 2026-10-23: one
+ * `taskkill /t /f` of a shell plus its node child takes 1027-1058 ms on an IDLE
+ * machine (five samples), and a `taskkill` cut off at a 150 ms deadline leaves the
+ * tree ALIVE 1.5 s later (`ETIMEDOUT`, `status = null`, `signal = SIGTERM`). This
+ * function used to `catch {}` that result and return `void`, so the one caller
+ * that promises "no service outlives the CLI" could not tell a kill from a
+ * timeout - and a loaded host, where a single tree kill genuinely needs more than
+ * the old 2000 ms, silently leaked every child it was asked to reap.
+ *
+ * The budget therefore lives in `PROC_LIMITS.killTreeSyncTimeoutMs`, sized from
+ * that measurement rather than from optimism, and the answer comes back to the
+ * caller so `reapSync` can raise `killIncomplete` instead of pretending.
+ *
+ * POSIX reports `true` when a signal was DELIVERED, which is as much as a signal
+ * can ever confirm.
  */
-export declare function killTreeSync(pid: number | undefined): void;
+export declare function killTreeSync(pid: number | undefined): boolean;

package/dist/proc/kill-tree.js

@@ -24,6 +24,7 @@
  */
 import { spawn, spawnSync } from 'node:child_process';
 import process from 'node:process';
+import { PROC_LIMITS } from './limits.js';
 /** Is the pid still there? `signal 0` tests for existence without delivering. */
 export function isAlive(pid) {
     if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
@@ -88,32 +89,58 @@ export function killTree(pid, signal = 'SIGKILL') {
  * The only kill primitive a signal handler, `process.on('exit')` or
  * `handleFatal` may reach (I-9). No escalation ladder and no logging: a reaper
  * that can block or throw is worse than one that misses a child.
+ *
+ * IT RETURNS WHETHER THE KILL WAS CONFIRMED, AND THAT IS NOT BOOKKEEPING. The
+ * Windows branch is a `taskkill` PROCESS, and `spawnSync`'s own `timeout` kills
+ * that process when the budget runs out. Measured on 2026-10-23: one
+ * `taskkill /t /f` of a shell plus its node child takes 1027-1058 ms on an IDLE
+ * machine (five samples), and a `taskkill` cut off at a 150 ms deadline leaves the
+ * tree ALIVE 1.5 s later (`ETIMEDOUT`, `status = null`, `signal = SIGTERM`). This
+ * function used to `catch {}` that result and return `void`, so the one caller
+ * that promises "no service outlives the CLI" could not tell a kill from a
+ * timeout - and a loaded host, where a single tree kill genuinely needs more than
+ * the old 2000 ms, silently leaked every child it was asked to reap.
+ *
+ * The budget therefore lives in `PROC_LIMITS.killTreeSyncTimeoutMs`, sized from
+ * that measurement rather than from optimism, and the answer comes back to the
+ * caller so `reapSync` can raise `killIncomplete` instead of pretending.
+ *
+ * POSIX reports `true` when a signal was DELIVERED, which is as much as a signal
+ * can ever confirm.
  */
 export function killTreeSync(pid) {
     if (pid === undefined || !Number.isFinite(pid) || pid <= 0)
-        return;
+        return false;
     if (process.platform === 'win32') {
+        let result;
         try {
-            spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], {
+            result = spawnSync('taskkill', ['/pid', String(pid), '/t', '/f'], {
                 windowsHide: true,
                 stdio: 'ignore',
-                timeout: 2000,
+                timeout: PROC_LIMITS.killTreeSyncTimeoutMs,
             });
         }
         catch {
-            /* ignore */
+            return false;
         }
-        return;
+        // `error` is set for a spawn failure AND for the budget expiring (`ETIMEDOUT`,
+        // with `signal = SIGTERM`), and neither is a kill.
+        if (result.error)
+            return false;
+        return result.status === 0;
     }
     try {
         process.kill(-pid, 'SIGKILL');
+        return true;
     }
     catch {
         try {
             process.kill(pid, 'SIGKILL');
+            return true;
         }
         catch {
             /* already gone */
+            return false;
         }
     }
 }

package/dist/proc/limits.d.ts

@@ -102,6 +102,25 @@ export declare const PROC_LIMITS: {
     readonly killVerifyMs: 2000;
     /** Liveness poll interval while waiting for a `SIGKILL` to land. */
     readonly killVerifyPollMs: 50;
+    /**
+     * How long ONE synchronous tree kill (`killTreeSync`) may take.
+     *
+     * MEASURED, NOT GUESSED. A `taskkill /pid <shell> /t /f` of a shell plus its
+     * node child takes 1027-1058 ms on the reference machine on an IDLE host (five
+     * samples, 2026-10-23), so the old 2000 ms was 1.9x the honest cost and the
+     * 2026-10-23 release run - where the whole suite took 340 s against the usual
+     * 200-240 s - is comfortably inside the range where a single tree kill exceeds
+     * it. Crossing it is not a slow kill, it is NO kill: `spawnSync` kills
+     * `taskkill` itself at the deadline and the tree keeps running (verified: a
+     * 150 ms budget left the child alive 1.5 s later, `ETIMEDOUT` / `status null`).
+     *
+     * 5000 ms is ~5x the measured cost. It is a CEILING and not a cost: a tree that
+     * dies in the usual second still returns in that second. The worst case is
+     * `maxJobs` (16) trees at the ceiling on an exit hook, which is why this is not
+     * any larger - the reaper prefers a reported miss to an exit that never ends,
+     * and the miss is now reported (`ProcRecord.killIncomplete`).
+     */
+    readonly killTreeSyncTimeoutMs: 5000;
     /** Below this many terminal columns the status chip degrades to `[N]`. */
     readonly statusCompactCols: 92;
     /**

package/dist/proc/limits.js

@@ -102,6 +102,25 @@ export const PROC_LIMITS = {
     killVerifyMs: 2000,
     /** Liveness poll interval while waiting for a `SIGKILL` to land. */
     killVerifyPollMs: 50,
+    /**
+     * How long ONE synchronous tree kill (`killTreeSync`) may take.
+     *
+     * MEASURED, NOT GUESSED. A `taskkill /pid <shell> /t /f` of a shell plus its
+     * node child takes 1027-1058 ms on the reference machine on an IDLE host (five
+     * samples, 2026-10-23), so the old 2000 ms was 1.9x the honest cost and the
+     * 2026-10-23 release run - where the whole suite took 340 s against the usual
+     * 200-240 s - is comfortably inside the range where a single tree kill exceeds
+     * it. Crossing it is not a slow kill, it is NO kill: `spawnSync` kills
+     * `taskkill` itself at the deadline and the tree keeps running (verified: a
+     * 150 ms budget left the child alive 1.5 s later, `ETIMEDOUT` / `status null`).
+     *
+     * 5000 ms is ~5x the measured cost. It is a CEILING and not a cost: a tree that
+     * dies in the usual second still returns in that second. The worst case is
+     * `maxJobs` (16) trees at the ceiling on an exit hook, which is why this is not
+     * any larger - the reaper prefers a reported miss to an exit that never ends,
+     * and the miss is now reported (`ProcRecord.killIncomplete`).
+     */
+    killTreeSyncTimeoutMs: 5000,
     /** Below this many terminal columns the status chip degrades to `[N]`. */
     statusCompactCols: 92,
     // --- long-task-jobs: bounded waiting, progress, notices, log mirror --------

package/dist/proc/supervisor.js

@@ -404,9 +404,16 @@ export class ProcSupervisor {
         for (const entry of this.services.values()) {
             if (isTerminalStatus(entry.record.status))
                 continue;
-            killTreeSync(entry.record.pid);
+            // THE ANSWER IS PART OF THE REAP (AC-42, 2026-10-23 release). A `taskkill`
+            // that outlived its budget is killed itself and the tree survives, so an
+            // unconfirmed kill has to reach the record the card and `bash_output` read -
+            // otherwise "stopped" is a claim nobody made good on. `killIncomplete` is
+            // that field (P2-6), and it is the reason the reaper may keep a bound at all.
+            const killed = killTreeSync(entry.record.pid);
             entry.record.status = 'stopped';
             entry.record.endedAt = Date.now();
+            if (!killed)
+                entry.record.killIncomplete = true;
             entry.watcher?.stop();
             if (entry.outputTimer)
                 clearTimeout(entry.outputTimer);

package/dist/session/validate-session.js

@@ -4,6 +4,7 @@ import { TODO_LIMITS } from '../todo/limits.js';
 import { acceptanceSummary, normalizeAcceptance } from '../todo/acceptance.js';
 import { validateCompactionIdentity } from '../compaction/memory-identity.js';
 import { MemoryError } from '../compaction/memory.js';
+import { GOVERNANCE_CARD_FALLBACK_TEXT, normalizeGovernanceCard } from '../governance/card-normalize.js';
 function fail(path, expected) {
     throw new Error(`Invalid session file: ${path} must be ${expected}.`);
 }
@@ -145,6 +146,12 @@ const subagent = shape({
 });
 const ENTRY_FIELDS = {
     user: { text: string },
+    // A GOVERNANCE CARD IS HISTORY, so it is validated LENIENTLY (governance-mode 10.4):
+    // unknown fields are ignored (`shape` only reads the declared ones) and `card` is not
+    // shape-checked here at all - `sanitizeGovernanceEntries` below repairs a card it can
+    // and degrades one it cannot to a one-line notice, so a corrupt footnote never costs
+    // the session. `at` is advisory.
+    governance: { at: optional(number), card: () => { } },
     queued: { text: string, queueId: optional(nonempty) },
     notice: { text: string, level: enumeration('info', 'warn', 'error') },
     assistant: {
@@ -282,9 +289,33 @@ export function validateSession(value) {
     if (source.acceptance !== undefined) {
         prepared.acceptance = normalizeAcceptance(source.acceptance, [], { enabled: true }).items;
     }
-    prepared.entries = sanitizeEntryAcceptance(prepared.entries);
+    prepared.entries = sanitizeGovernanceEntries(sanitizeEntryAcceptance(prepared.entries));
     return prepared;
 }
+/**
+ * Repair every governance card the file carries, or degrade it to a one-line notice.
+ *
+ * The card is rebuilt from `normalizeGovernanceCard`'s output so only known fields survive
+ * (a hand-edited file cannot smuggle a 10 000-row table into the transcript), and a value
+ * with nothing renderable becomes a `notice` entry that keeps the entry's id: ids must stay
+ * unique and in order, and the transcript should say that something was here.
+ */
+function sanitizeGovernanceEntries(entries) {
+    if (!Array.isArray(entries))
+        return entries;
+    return entries.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return entry;
+        const record = entry;
+        if (record.kind !== 'governance')
+            return entry;
+        const card = normalizeGovernanceCard(record.card);
+        if (card === null) {
+            return { id: record.id, kind: 'notice', level: 'info', text: GOVERNANCE_CARD_FALLBACK_TEXT };
+        }
+        return { id: record.id, kind: 'governance', at: typeof record.at === 'number' ? record.at : 0, card };
+    });
+}
 /**
  * Drop the acceptance rows a persisted card cannot use, keeping every usable one.
  *

package/dist/team/runtime.d.ts

@@ -98,6 +98,14 @@ export interface TeamRuntimeDeps {
      * `TeamOverseer`), so a mid-dispatch `/fast off` stops the next look.
      */
     overseer?: OverseerProvider;
+    /**
+     * Governance hooks, passed straight through to `SubagentDeps` (governance-mode 13.2).
+     * ABSENT outside a governed session, which leaves every child built as before.
+     */
+    extraToolsFor?: SubagentDeps['extraToolsFor'];
+    narrowToolsFor?: SubagentDeps['narrowToolsFor'];
+    governanceRoleBlockFor?: SubagentDeps['governanceRoleBlockFor'];
+    extraPolicyExempt?: SubagentDeps['extraPolicyExempt'];
 }
 export declare class TeamRuntime {
     private readonly deps;

package/dist/team/runtime.js

@@ -512,6 +512,15 @@ export class TeamRuntime {
             ...(this.deps.contextManagerFor
                 ? { contextManagerFor: this.deps.contextManagerFor }
                 : {}),
+            // Site two of two for the four governance hooks, with the same silent failure as
+            // the lines above: declared on `TeamRuntimeDeps` and not forwarded here, a governed
+            // child would run with no role tools and the dispatch would simply never submit.
+            ...(this.deps.extraToolsFor ? { extraToolsFor: this.deps.extraToolsFor } : {}),
+            ...(this.deps.narrowToolsFor ? { narrowToolsFor: this.deps.narrowToolsFor } : {}),
+            ...(this.deps.governanceRoleBlockFor
+                ? { governanceRoleBlockFor: this.deps.governanceRoleBlockFor }
+                : {}),
+            ...(this.deps.extraPolicyExempt ? { extraPolicyExempt: this.deps.extraPolicyExempt } : {}),
             // Same conditional-spread rule: a dispatch without a supervisor builds
             // the exact pre-feature `SubagentDeps`, and the child's idle watchdog
             // keeps its un-lengthened ceiling (team-overseer §3.6).

package/dist/team/subagent.d.ts

@@ -138,6 +138,29 @@ export interface SubagentDeps {
     toolGateFor?: (label: string) => ToolGate;
     /** Added to each gated tool's executor timeout; see `gatedToolTimeouts`. */
     decisionBudgetMs?: number;
+    /**
+     * Governance hooks (governance-mode 13.2 / 14.3). ALL FOUR ABSENT outside a governed
+     * dispatch, and `buildSubagentTools` then produces exactly the array it always did.
+     *
+     * `extraToolsFor` returns the role tools this child gets (`gov_submit_*`, `ledger_*`,
+     * ...). They travel through the `teamTools` slot of the factory, next to the comm
+     * tools, so the plan gate and the ceiling treat them like `team_send`.
+     *
+     * `narrowToolsFor` runs on the factory's RESULT: it is where the inspector loses its
+     * write tools and gets the restricted `bash`, and where the governance-store tripwire is
+     * wrapped around the read-class tools. It is a separate hook (not folded into
+     * `extraToolsFor`) because it must see the finished built-ins, while the role tools must
+     * enter the factory. Both are closures supplied by the host, which keeps the dependency
+     * direction `governance/ -> team/` (this module never imports governance code).
+     *
+     * `extraPolicyExempt` is merged with `TEAM_SUBAGENT_TOOL_NAMES` for the skills ceiling
+     * (7.1 rule 6). Absent, `policyExempt` stays the SAME Set object as before, so the
+     * closed state is provable by identity.
+     */
+    extraToolsFor?: (spec: SubagentSpec) => AgentTool[];
+    narrowToolsFor?: (spec: SubagentSpec, tools: AgentTool[]) => AgentTool[];
+    governanceRoleBlockFor?: (spec: SubagentSpec) => string;
+    extraPolicyExempt?: ReadonlySet<string>;
 }
 export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */

package/dist/team/subagent.js

@@ -77,7 +77,8 @@ export function buildSubagentTools(spec, deps, getAgent) {
                 : TEAM_LIMITS.waitMaxSeconds * 1000,
         }),
     ];
-    const tools = createBuiltinTools({
+    const extras = deps.extraToolsFor?.(spec) ?? [];
+    const built = createBuiltinTools({
         getCwd: deps.getCwd,
         confirmTools: deps.confirmTools,
         // THE CHILD ASKS THE CALLER TOO (section 2.3.7). Without this the approval
@@ -145,7 +146,9 @@ export function buildSubagentTools(spec, deps, getAgent) {
         // yields an empty array: a silent default is not a decision anyone can find
         // later.
         todoTools: [],
-        teamTools: commTools,
+        // Role tools ride the same slot as the comm tools (governance-mode 14.3). A spread
+        // only when a governed dispatch supplied some, so every other child is unchanged.
+        teamTools: extras.length > 0 ? [...commTools, ...extras] : commTools,
         // `spec.readOnly` forces the plan gate on for this child even in a BUILD
         // session. TIGHTENING ONLY (D-13): there is no field anywhere that gives a
         // child more permission than the session it was spawned from. Read LIVE, so
@@ -168,10 +171,13 @@ export function buildSubagentTools(spec, deps, getAgent) {
                 onToolPolicyEvent: (e) => deps.onChildToolPolicyEvent?.({ ...e, label: spec.label }),
                 // The two comm tools are not in the LEAD's registered tool list, so
                 // the ceiling would refuse them and dead-end the channel.
-                policyExempt: TEAM_SUBAGENT_TOOL_NAMES,
+                policyExempt: deps.extraPolicyExempt
+                    ? new Set([...TEAM_SUBAGENT_TOOL_NAMES, ...deps.extraPolicyExempt])
+                    : TEAM_SUBAGENT_TOOL_NAMES,
             }
             : {}),
     });
+    const tools = deps.narrowToolsFor ? deps.narrowToolsFor(spec, built) : built;
     // Mail rides on the NEXT tool result of whatever the child does next (D-4), so
     // every tool it can call has to carry the tail — the comm tools included, or a
     // child that only ever messages would never receive.
@@ -256,6 +262,11 @@ export function createSubagent(spec, deps, hooks) {
             peers: deps.bus.peersOf(spec.label),
         }),
         ...(fastBlock ? { fastBlock } : {}),
+        // The governed role block (governance-mode 6.1), after the subagent block. Spread
+        // only when this child is a governed one, so every other child's prompt is unchanged.
+        ...(spec.governance && deps.governanceRoleBlockFor
+            ? { governanceRoleBlock: deps.governanceRoleBlockFor(spec) }
+            : {}),
     });
     // LAZY ACCESSORS OVER `agentRef`, WHICH IS ASSIGNED AFTER THIS RETURNS. A
     // non-lazy read here is `undefined` at construction and the child's estimate

package/dist/team/types.d.ts

@@ -13,6 +13,7 @@
 import type { TokenUsage } from '@aragon-agent/core';
 import type { ActivityArgs } from './activity.js';
 import type { TimelineEntry } from './timeline.js';
+import type { GovernanceSpecExt } from '../governance/types.js';
 /** One normalized delegation request. Produced only by `normalizeSubagentSpecs`. */
 export interface SubagentSpec {
     /** Slug, unique within the dispatch. Shown in the panel, the report and logs. */
@@ -27,6 +28,11 @@ export interface SubagentSpec {
      * permission than the session it was spawned from.
      */
     readOnly: boolean;
+    /**
+     * Set only by the governance engine (governance-mode section 8.3). Its presence is what
+     * `isGovernedDispatch` reads to keep a governed dispatch out of the transcript.
+     */
+    governance?: GovernanceSpecExt;
 }
 export type SubagentPhase = 'queued' | 'starting' | 'thinking' | 'tool' | 'waiting' | 'done' | 'failed' | 'aborted';
 /** Live, mutable record of one child. Projected into the UI and the report. */

package/dist/tools/bounded-spawn.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A CHILD PROCESS WITH A DEADLINE (bug-diagnosis 0b33323c, release gate 2026-10-23).
+ *
+ * WHY THIS EXISTS. `search-tools.ts` used to await a bare `spawn('rg', ...)` whose
+ * promise settled on `'close'` and on nothing else. A child that never closes -
+ * a launcher shim blocked by a scanner, a wedged network drive, a filesystem that
+ * stopped answering - therefore left the tool pending FOREVER: the model's turn
+ * had no result to return, the Ink frame had no answer to draw, and the only thing
+ * that ever ended it was the test runner's wall clock
+ * (`tools.test.ts > grep finds a seeded pattern`, `Test timed out in 30000ms`,
+ * 2026-10-23 release). CLAUDE.md section 5 says exactly what is missing here: at
+ * an IO / subprocess boundary use a structured wrapper with a timeout, never a
+ * bare call.
+ *
+ * SETTLES ONCE, ALWAYS. Every way a child can end - exit, spawn failure, and OUR
+ * OWN deadline - resolves this promise, and the first of them wins. The deadline
+ * is the last resort, not a measuring instrument: a caller that has produced an
+ * answer is not interrupted by it (`clearTimeout` happens in `finish`).
+ *
+ * THE KILL IS A TREE KILL. `rg` on Windows is reached through a launcher
+ * (`shims/rg.exe`), and killing the launcher alone leaves the real search running
+ * forever - which would keep this fix from fixing anything. `killTree` is the one
+ * owner of that knowledge in this package and it never throws.
+ */
+/** What ended the child, which is the only thing the caller can act on. */
+export type DeadlineOutcome = 
+/** The child closed on its own; `exitCode` is real. */
+'exit'
+/** It outlived `deadlineMs`; it has been killed and `stdout` is what it managed. */
+ | 'deadline'
+/** It never started (`ENOENT` and friends). */
+ | 'unavailable';
+export interface DeadlineResult {
+    outcome: DeadlineOutcome;
+    /** `null` for `'deadline'` and `'unavailable'`: there was no exit status. */
+    exitCode: number | null;
+    /** Everything the child wrote to stdout before it settled. */
+    stdout: string;
+}
+export interface DeadlineOptions {
+    cwd: string;
+    /** Hard limit on the child's lifetime, in milliseconds. Must be > 0. */
+    deadlineMs: number;
+}
+/**
+ * Run `command` and settle within `deadlineMs`, whatever the child does.
+ *
+ * stderr is DROPPED rather than piped: nothing here reads it, and an undrained
+ * pipe is a second way to wedge a child (the buffer fills and it blocks on write).
+ * stdin is `ignore` for the same reason in reverse - a child that decides to read
+ * stdin must see EOF, not wait for a user who is not there.
+ *
+ * Never throws, never rejects: a caller that has to explain a failure gets
+ * `'unavailable'` or `'deadline'` instead of an exception it did not expect.
+ */
+export declare function runWithDeadline(command: string, args: string[], options: DeadlineOptions): Promise<DeadlineResult>;

package/dist/tools/bounded-spawn.js

@@ -0,0 +1,76 @@
+/**
+ * A CHILD PROCESS WITH A DEADLINE (bug-diagnosis 0b33323c, release gate 2026-10-23).
+ *
+ * WHY THIS EXISTS. `search-tools.ts` used to await a bare `spawn('rg', ...)` whose
+ * promise settled on `'close'` and on nothing else. A child that never closes -
+ * a launcher shim blocked by a scanner, a wedged network drive, a filesystem that
+ * stopped answering - therefore left the tool pending FOREVER: the model's turn
+ * had no result to return, the Ink frame had no answer to draw, and the only thing
+ * that ever ended it was the test runner's wall clock
+ * (`tools.test.ts > grep finds a seeded pattern`, `Test timed out in 30000ms`,
+ * 2026-10-23 release). CLAUDE.md section 5 says exactly what is missing here: at
+ * an IO / subprocess boundary use a structured wrapper with a timeout, never a
+ * bare call.
+ *
+ * SETTLES ONCE, ALWAYS. Every way a child can end - exit, spawn failure, and OUR
+ * OWN deadline - resolves this promise, and the first of them wins. The deadline
+ * is the last resort, not a measuring instrument: a caller that has produced an
+ * answer is not interrupted by it (`clearTimeout` happens in `finish`).
+ *
+ * THE KILL IS A TREE KILL. `rg` on Windows is reached through a launcher
+ * (`shims/rg.exe`), and killing the launcher alone leaves the real search running
+ * forever - which would keep this fix from fixing anything. `killTree` is the one
+ * owner of that knowledge in this package and it never throws.
+ */
+import { spawn } from 'node:child_process';
+import { killTree } from '../proc/kill-tree.js';
+/**
+ * Run `command` and settle within `deadlineMs`, whatever the child does.
+ *
+ * stderr is DROPPED rather than piped: nothing here reads it, and an undrained
+ * pipe is a second way to wedge a child (the buffer fills and it blocks on write).
+ * stdin is `ignore` for the same reason in reverse - a child that decides to read
+ * stdin must see EOF, not wait for a user who is not there.
+ *
+ * Never throws, never rejects: a caller that has to explain a failure gets
+ * `'unavailable'` or `'deadline'` instead of an exception it did not expect.
+ */
+export function runWithDeadline(command, args, options) {
+    return new Promise((settle) => {
+        let child;
+        try {
+            child = spawn(command, args, {
+                cwd: options.cwd,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                windowsHide: true,
+            });
+        }
+        catch {
+            settle({ outcome: 'unavailable', exitCode: null, stdout: '' });
+            return;
+        }
+        let stdout = '';
+        let settled = false;
+        let timer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            settle(result);
+        };
+        timer = setTimeout(() => {
+            // A pid is all `killTree` needs, and it is the only kill that reaches a
+            // grandchild. Partial output is still output: the caller decides whether a
+            // truncated answer is worth having.
+            killTree(child.pid);
+            finish({ outcome: 'deadline', exitCode: null, stdout });
+        }, options.deadlineMs);
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.on('error', () => finish({ outcome: 'unavailable', exitCode: null, stdout }));
+        child.on('close', (code) => finish({ outcome: 'exit', exitCode: code, stdout }));
+    });
+}

package/dist/tools/index.d.ts

@@ -250,15 +250,38 @@ export interface BuiltinToolsOptions {
      * Tool names that skip the CEILING wrapper only (never the plan gate, never
      * confirmation).
      *
-     * It exists for a subagent's two comm tools and for nothing else (§3.11).
-     * `team_send` / `team_wait` are not in the LEAD's registered tool list, so
-     * evaluating them against the lead's `allowed-tools` ceiling would refuse them
-     * and dead-end the channel — the same dead end `SKILL_TOOL_FLOOR` exists to
-     * prevent one level up. Widening this set to anything that can write to disk
-     * would turn delegation into a ceiling bypass, which is exactly what §3.11
-     * re-applies the lead's policy to children to avoid.
+     * It has TWO users, and only two (§3.11, governance-mode 7.1 rule 6 / D-22b).
+     * First, a subagent's comm tools `team_send` / `team_wait`, which are not in the
+     * LEAD's registered tool list, so evaluating them against the lead's
+     * `allowed-tools` ceiling would refuse them and dead-end the channel. Second, the
+     * governance tools: the Orchestrator's `gov_run` / `gov_dispatch` and a governed
+     * child's role tools. Those are exempt for the same reason (a ceiling written
+     * before they existed names none of them) and because they never touch the user's
+     * workspace: the lead's two only write the host's own governance store, and the
+     * agents they dispatch each pass the full ceiling and plan gate for what they do.
+     *
+     * Widening this set to anything that can write to the user's workspace would turn
+     * delegation into a ceiling bypass, which is exactly what §3.11 re-applies the
+     * lead's policy to children to avoid. The governance names deliberately do NOT
+     * live in `HOST_TOOL_NAMES` / `SKILL_TOOL_FLOOR`: those feed `exec --allow-tool`
+     * validation and the `tools` diagnostics, and joining them would change both.
      */
     policyExempt?: ReadonlySet<string>;
+    /**
+     * The Orchestrator's two tools (`gov_run`, `gov_dispatch`), appended AFTER
+     * `teamTools` (governance-mode 14.3). Spread conditionally by the controller, so a
+     * session without governance builds the identical array.
+     */
+    governTools?: AgentTool[];
+    /**
+     * Live read of `{ governOn, mode }` for the governance gate. Never cached: Shift+Tab
+     * and `/gov off` flip it mid-run. Omitting it applies no gate, which is what keeps the
+     * closed state provable by object identity.
+     */
+    governGate?: () => {
+        governOn: boolean;
+        mode: AgentMode;
+    };
     /**
      * The non-interactive tool policy of `aragon exec`
      * (cli-integration-surface §4.2). A denied tool is NOT REGISTERED AT ALL, so

package/dist/tools/index.js

@@ -10,6 +10,7 @@
  */
 import { errorResult, evaluateToolCall, } from '@aragon-agent/core';
 import { planRefusal, submitPlanRefusal } from '../agent/agent-mode.js';
+import { withGovernanceGate } from '../governance/tools/guard.js';
 import { makeReadFile, makeWriteFile, makeEditFile, makeListDir } from './fs-tools.js';
 import { makeGlob, makeGrep } from './search-tools.js';
 import { makeBash } from './bash-tool.js';
@@ -382,6 +383,12 @@ export function createBuiltinTools(options) {
     if (options.teamTools && options.teamTools.length > 0) {
         tools = [...tools, ...options.teamTools];
     }
+    // The Orchestrator's tools, after `task` (governance-mode 14.3). Inside the factory for
+    // the reason `teamTools` records: appending later would let the ceiling and the plan
+    // gate see a different array than the one `HOST_TOOL_NAMES` is checked against.
+    if (options.governTools && options.governTools.length > 0) {
+        tools = [...tools, ...options.governTools];
+    }
     // --- The caller's per-call approval gate (headless-host-bridge §2.3.3). ---
     //
     // AFTER THE LAST APPEND AND BEFORE THE PERMISSION FILTER, for the two structural
@@ -495,6 +502,13 @@ export function createBuiltinTools(options) {
             return list;
         return list.map((tool) => withToolPostHooks(tool, hookRunner));
     };
+    // The governance gate is the INNER wrapper and the plan gate the outer one
+    // (governance-mode 13.2): `withPlanModeGate(withGovernanceGate(t))`, because the plan
+    // refusal is the more specific message and speaks first.
+    if (options.governGate) {
+        const getState = options.governGate;
+        tools = tools.map((t) => withGovernanceGate(t, getState));
+    }
     if (!options.agentMode)
         return withHooksPost(withJobNotices(tools));
     const getMode = options.agentMode;

package/dist/tools/plan-tools.d.ts

@@ -17,7 +17,7 @@
  * selected by whether an optional install step succeeded.
  */
 import { type AgentTool } from '@aragon-agent/core';
-import { type HumanInputGate, type NormalizedQuestion } from './human-input.js';
+import { type HumanInputGate, type NormalizedPlan, type NormalizedQuestion } from './human-input.js';
 export interface PlanToolsOptions {
     gate: HumanInputGate;
     /**
@@ -52,8 +52,20 @@ export interface PlanToolsOptions {
      * This is the one place a `plan -> build` transition is not deferred to
      * `agent_end`, and the asymmetry is the whole point: the user has just read
      * the plan and authorized exactly this work. A stray `Shift+Tab` has not.
+     *
+     * Receives the approved plan (governance-mode 9.2): PLAN+GOVERN stashes it as the
+     * run specification. Returning a string REPLACES the tool result, which is how that
+     * path tells the model it is now the Orchestrator; returning nothing keeps
+     * `APPROVED_RESULT`, so every pre-existing caller is unchanged.
+     */
+    onPlanApproved: (plan: NormalizedPlan) => string | void;
+    /**
+     * Pre-submit check (governance-mode 9.2). Called after `normalizePlan` and BEFORE
+     * the review overlay opens; a non-null return is a refusal text, delivered as a
+     * NON-error result (an error invites an identical retry). Absent everywhere but
+     * PLAN+GOVERN, so plain plan mode is byte-identical.
      */
-    onPlanApproved: () => void;
+    beforeSubmit?: () => string | null;
 }
 /**
  * Build the plan tools, or `[]` for a channel that can never reach a human.

package/dist/tools/plan-tools.js

@@ -165,13 +165,16 @@ function makeSubmitPlan(opts) {
             const plan = normalizePlan(params);
             if (!plan)
                 return errorResult('A plan needs at least one step with a title.');
+            const refusal = opts.beforeSubmit?.() ?? null;
+            if (refusal !== null)
+                return textResult(refusal);
             const response = await opts.withHumanWait(() => opts.gate.request({ kind: 'plan', plan }, ctx.signal));
             if (response === null || response.kind !== 'planDecision') {
                 return textResult(DISMISSED_RESULT);
             }
             if (response.decision === 'approved') {
-                opts.onPlanApproved();
-                return textResult(APPROVED_RESULT);
+                const replacement = opts.onPlanApproved(plan);
+                return textResult(typeof replacement === 'string' ? replacement : APPROVED_RESULT);
             }
             if (response.decision === 'revise') {
                 return textResult(`Plan rejected. The user's feedback: "${response.feedback}". ` +