@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/agent/governance-view.js

@@ -0,0 +1,40 @@
+/**
+ * The governance slice of the view model: the small pure folds `reducer.ts` delegates to
+ * (governance-mode section 14.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`agent/` is glyph-scanned).
+ *
+ * WHY A FILE OF ITS OWN. `reducer.ts` is already past the file-size ceiling and the repo
+ * rule is "wiring-style growth only": each governance `case` in the reducer is a line or
+ * two that calls a function here, so the logic is unit-testable without a `ViewState`.
+ */
+import { composePosture, isGovernancePosture } from '../governance/posture.js';
+/**
+ * The pair of posture fields one `setAgentMode` dispatch writes.
+ *
+ * "NEVER DISPATCH THE REQUESTED VALUE, ONLY THE ADOPTED ONE" (spec 4.3): the controller
+ * reports all four values together and the reducer mirrors them, so the badge and the gate
+ * cannot disagree. A dispatch that carries only the gate mode (every pre-governance call
+ * site) keeps the governance dimension the view already has and swaps the mode half, which
+ * is exactly what such a caller meant.
+ */
+export function adoptPosture(current, action) {
+    const governed = isGovernancePosture(current);
+    const posture = action.posture ?? composePosture(action.mode, governed);
+    const pendingPosture = action.pendingPosture !== undefined
+        ? action.pendingPosture
+        : action.pending === null
+            ? null
+            : composePosture(action.pending, governed);
+    return { posture, pendingPosture };
+}
+/**
+ * Fold a pushed snapshot into the view: a snapshot OLDER than the one held, for the same
+ * run, is dropped (the wiring throttles, and a late flush must not roll the panel back).
+ * Returns the held object unchanged when nothing should change.
+ */
+export function foldGovernanceSnapshot(held, incoming) {
+    if (held !== null && held.runId === incoming.runId && incoming.rev < held.rev)
+        return held;
+    return incoming;
+}

package/dist/agent/governance-wiring.d.ts

@@ -0,0 +1,162 @@
+/**
+ * GovernanceWiring - the host side of governance mode (governance-mode 3.2, 14.2).
+ *
+ * ASCII ONLY (`agent/` is inside the glyph scanner's scope).
+ *
+ * `AgentController` is 3000+ lines over the repo's file limit, so every governance decision
+ * it needs lives here and the controller only forwards: registration, availability, the
+ * Orchestrator and role prompt blocks, the PLAN+GOVERN interview gate, the approved-plan
+ * stash, the engine's lifecycle, the child tool hooks. The posture TRANSITION rule is a
+ * pure function in `governance/posture-transition.ts` for the same reason.
+ *
+ * TWO LAYERS OF "CAN I USE THIS" (D-22 / RV-1 / RV-14), and they are not the same thing:
+ *
+ *  - REGISTERED is decided ONCE, in the constructor, from inputs that cannot change
+ *    afterwards: team tools exist, `governance.enabled`, the env kill switch, and the
+ *    channel's STATIC `neverPrompts` (NOT the live `canPrompt()`: at construction the App
+ *    has not attached its human channel yet, so `canPrompt()` is false for every TUI
+ *    session and keying off it would register nothing, silently, forever). The tool array
+ *    is immutable after `new Agent(...)`, so this is irreversible for the session.
+ *  - AVAILABLE is live: registered AND `team.enabled` AND an API key. It is what `/gov`,
+ *    `doctor` and the key cycle ask.
+ */
+import type { AgentTool, ModelCost } from '@aragon-agent/core';
+import type { CliConfig } from '../config/schema.js';
+import { type GovernanceAvailability } from '../governance/copy.js';
+import type { TeamRuntimeLike } from '../governance/engine/engine-core.js';
+import type { PauseOutcome } from '../governance/engine/pause.js';
+import { type Posture } from '../governance/posture.js';
+import { type RunReportResult } from '../governance/report-reader.js';
+import { type IndexEntry } from '../governance/store/run-store.js';
+import type { GovernanceEventListener, GovernanceSnapshot, LedgerState, RunState } from '../governance/types.js';
+import type { SubagentSpec } from '../team/types.js';
+import type { HumanInputGate, NormalizedPlan, NormalizedQuestion } from '../tools/human-input.js';
+import type { AgentMode } from './agent-mode.js';
+export interface WiringDeps {
+    /** `config.team.enabled` at construction: whether `task` (and a TeamRuntime) exist. */
+    teamRegistered: boolean;
+    config: () => CliConfig;
+    gate: HumanInputGate;
+    getCwd: () => string;
+    /** The gate mode (`build` | `plan`); the controller owns it. */
+    getGateMode: () => AgentMode;
+    getSessionId?: () => string | undefined;
+    withPausedWatchdog: <T>(fn: () => Promise<T>) => Promise<T>;
+    withHumanWait: <T>(fn: () => Promise<T>) => Promise<T>;
+    hasApiKey: () => boolean;
+    modelCost: () => ModelCost | undefined;
+    getRuntime: () => TeamRuntimeLike | null;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: () => number;
+}
+/** Render the approved plan as the run specification (<= `specChars`). */
+export declare function renderPlanAsSpec(plan: NormalizedPlan): string;
+/** What `/gov runs` shows per run: the index row without the cwd / session plumbing. */
+export type GovernanceRunRow = Pick<IndexEntry, 'runId' | 'goal' | 'status' | 'updatedAt' | 'digest'>;
+export declare class GovernanceWiring {
+    private readonly deps;
+    private readonly registered;
+    private readonly enabledAtStart;
+    private readonly env;
+    private governOn;
+    private pendingPosture;
+    private engine;
+    private store;
+    private readonly listeners;
+    private engineUnsubscribe;
+    private approvedPlan;
+    private answeredRounds;
+    private readonly coveredTopics;
+    /** A lazy facade: tools are built before the engine exists and the engine needs the runtime. */
+    private readonly api;
+    constructor(deps: WiringDeps);
+    /** Whether governance tools were registered at construction. Never changes. */
+    isRegistered(): boolean;
+    /** The live answer, with the precise reason when it is no. */
+    isAvailable(): GovernanceAvailability;
+    private unregisteredReason;
+    /** The exact sentence for the current unavailability, or null when available. */
+    unavailableText(): string | null;
+    /** Shift+Tab cycle: four states when usable and `governance.shiftTab`, else the classic two. */
+    postureCycle(): readonly Posture[];
+    isGovernOn(): boolean;
+    setGovernOn(on: boolean): void;
+    getPendingPosture(): Posture | null;
+    setPendingPosture(pending: Posture | null): void;
+    /** Entering PLAN+GOVERN starts a fresh interview and drops any older plan (9.3). */
+    onPostureAdopted(posture: Posture, previous: Posture): void;
+    isStageRunning(): boolean;
+    /**
+     * `''` unless governance is on, registered and available (closed state: byte-equal).
+     *
+     * `config` is the config the prompt is being composed FOR. A settings save composes the
+     * prompt from the candidate BEFORE it becomes live, so reading the live config here would
+     * quote the limits from before the save (governance-mode-v1-1 IF-3).
+     */
+    orchestratorBlock(posture: Posture, config?: CliConfig): string;
+    /** `''` unless PLAN+GOVERN. */
+    planAddendum(posture: Posture, config?: CliConfig): string;
+    roleBlockFor(spec: SubagentSpec): string;
+    /** Called from the controller's `noteAnswered`: one real, answered, non-duplicate round. */
+    noteAnsweredRound(questions?: readonly NormalizedQuestion[]): void;
+    answeredRoundCount(): number;
+    /** `submit_plan` pre-check: a refusal text, or null to proceed. */
+    beforeSubmitPlan(): string | null;
+    /** Stash the approved plan when governance is on. Returns which way the session goes. */
+    handlePlanApproved(plan: NormalizedPlan): 'govern' | 'build';
+    /** `gov_run start` consumes the stash exactly once. */
+    takeApprovedPlan(): string | null;
+    /** `[]` when not registered, which is the byte-identical closed path. */
+    leadTools(): AgentTool[];
+    leadPolicyExempt(): ReadonlySet<string>;
+    childPolicyExempt(): ReadonlySet<string>;
+    /** Role tools for a governed child; `[]` for anything else. */
+    childToolsFor(spec: SubagentSpec): AgentTool[];
+    /**
+     * Narrow a governed child's finished tool array: the inspector loses its write tools and
+     * gets the restricted shell, and every read-class tool gets the store tripwire.
+     *
+     * This runs on the factory's RESULT (see `SubagentDeps.narrowToolsFor`) because it has to
+     * see the built-in `bash` to replace it, while the role tools had to go IN through the
+     * factory. A non-governed spec comes back untouched.
+     */
+    narrowToolsFor(spec: SubagentSpec, tools: AgentTool[]): AgentTool[];
+    /** The engine is created on first use: a session that never governs never opens a store. */
+    private ensureEngine;
+    /** `confirmCharter` through the EXISTING plan-review overlay; no new overlay kind (RV-10). */
+    private confirmCharter;
+    /** Subscribe to the governance event stream (works before the engine exists). */
+    subscribe(listener: GovernanceEventListener): () => void;
+    snapshot(): GovernanceSnapshot | null;
+    /** Run + ledger for the `/gov board` overlay (read-only views of live memory). */
+    boardInput(): {
+        run: RunState;
+        ledger: LedgerState;
+        boardPath: string;
+    } | null;
+    abortStage(): void;
+    /**
+     * Recent runs for `/gov runs`, newest first. Opens the store lazily; `[]` when governance
+     * is unusable. `RunStore.listRuns()` is ALREADY newest-first: the previous
+     * `slice(-10).reverse()` therefore returned the OLDEST ten once there were more than ten.
+     */
+    listRuns(): Promise<GovernanceRunRow[]>;
+    /** `/gov report [runId]`: a stored report, read-only (governance-mode-v1-1 7.2). */
+    readReport(runId?: string): Promise<RunReportResult | {
+        kind: 'no_run';
+    }>;
+    /** `/gov pause`: the engine's verdict, or `no_run` when no engine was ever created. */
+    requestPause(): Promise<PauseOutcome>;
+    cancelPause(): boolean;
+    /** The dispatch-plan line for the live run (`/gov status`), or null without one. */
+    dispatchPlanText(): string | null;
+    /**
+     * The run `/gov resume [runId]` should hand to the orchestrator: the named one when it
+     * exists, else the newest resumable run for this directory. `null` when there is none.
+     */
+    findResumableRun(runId?: string): Promise<string | null>;
+    dispose(): void;
+    private buildLazyApi;
+    /** Posture helper for callers that only hold the gate mode. */
+    currentPosture(mode: AgentMode): Posture;
+}

package/dist/agent/governance-wiring.js

@@ -0,0 +1,470 @@
+/**
+ * GovernanceWiring - the host side of governance mode (governance-mode 3.2, 14.2).
+ *
+ * ASCII ONLY (`agent/` is inside the glyph scanner's scope).
+ *
+ * `AgentController` is 3000+ lines over the repo's file limit, so every governance decision
+ * it needs lives here and the controller only forwards: registration, availability, the
+ * Orchestrator and role prompt blocks, the PLAN+GOVERN interview gate, the approved-plan
+ * stash, the engine's lifecycle, the child tool hooks. The posture TRANSITION rule is a
+ * pure function in `governance/posture-transition.ts` for the same reason.
+ *
+ * TWO LAYERS OF "CAN I USE THIS" (D-22 / RV-1 / RV-14), and they are not the same thing:
+ *
+ *  - REGISTERED is decided ONCE, in the constructor, from inputs that cannot change
+ *    afterwards: team tools exist, `governance.enabled`, the env kill switch, and the
+ *    channel's STATIC `neverPrompts` (NOT the live `canPrompt()`: at construction the App
+ *    has not attached its human channel yet, so `canPrompt()` is false for every TUI
+ *    session and keying off it would register nothing, silently, forever). The tool array
+ *    is immutable after `new Agent(...)`, so this is irreversible for the session.
+ *  - AVAILABLE is live: registered AND `team.enabled` AND an API key. It is what `/gov`,
+ *    `doctor` and the key cycle ask.
+ */
+import { join } from 'node:path';
+import { clampGovernanceConfig, isGovernanceEnvDisabled, } from '../config/governance-config.js';
+import { getGovernanceDir } from '../config/app-paths.js';
+import { RESTART_REQUIRED_TEXT, unavailableReasonText, } from '../governance/copy.js';
+import { createGovernanceEngine } from '../governance/engine/engine.js';
+import { estimateForRun } from '../governance/engine/estimate.js';
+import { formatDispatchEstimate } from '../governance/copy.js';
+import { GOV_CHILD_TOOL_NAMES, GOV_LEAD_TOOL_NAMES, GOV_LIMITS } from '../governance/limits.js';
+import { composePosture, isGovernancePosture, POSTURES_CLASSIC, POSTURES_FULL, } from '../governance/posture.js';
+import { buildPlanGovernAddendum } from '../governance/prompts/plan-addendum.js';
+import { buildOrchestratorBlock } from '../governance/prompts/orchestrator-block.js';
+import { PLAN_INTERVIEW_TOPICS, govAskRoundsRefusal } from '../governance/prompts/refusals.js';
+import { buildRoleBlock } from '../governance/prompts/role-blocks.js';
+import { readRunReport } from '../governance/report-reader.js';
+import { ArtifactStore } from '../governance/store/artifacts.js';
+import { RunStore } from '../governance/store/run-store.js';
+import { buildChildTools } from '../governance/tools/child-tools.js';
+import { applyInspectorToolPolicy, withGovernanceReadGuard } from '../governance/tools/guard.js';
+import { makeGovDispatchTool, makeGovRunTool } from '../governance/tools/lead-tools.js';
+import { TEAM_LIMITS } from '../team/limits.js';
+/** Keyword probes that map an answered question onto the fixed interview topics. */
+const TOPIC_PROBES = [
+    /goal|success|outcome|objective|criteria/i,
+    /scope|in scope|out of scope|include|exclude/i,
+    /constraint|stack|compat|performance|style|forbid/i,
+    /quality|test|security|review|strict/i,
+    /team|parallel|budget|cost|work package|\bwp/i,
+    /risk|depend|decision/i,
+];
+function governanceOf(config) {
+    return clampGovernanceConfig(config.governance);
+}
+/** Render the approved plan as the run specification (<= `specChars`). */
+export function renderPlanAsSpec(plan) {
+    const lines = [`# ${plan.title}`, '', plan.summary, ''];
+    plan.steps.forEach((step, i) => {
+        lines.push(`${i + 1}. ${step.title}`);
+        if (step.detail)
+            lines.push(`   ${step.detail.replace(/\n/g, '\n   ')}`);
+    });
+    if (plan.filesTouched.length > 0)
+        lines.push('', `Files: ${plan.filesTouched.join(', ')}`);
+    if (plan.risks.length > 0)
+        lines.push('', 'Risks:', ...plan.risks.map((r) => `- ${r}`));
+    if (plan.openQuestions.length > 0) {
+        lines.push('', 'Open questions:', ...plan.openQuestions.map((q) => `- ${q}`));
+    }
+    const text = lines.join('\n');
+    return text.length > GOV_LIMITS.specChars ? text.slice(0, GOV_LIMITS.specChars) : text;
+}
+const RUNS_LISTED = 10;
+export class GovernanceWiring {
+    deps;
+    registered;
+    enabledAtStart;
+    env;
+    governOn = false;
+    pendingPosture = null;
+    engine = null;
+    store = null;
+    listeners = new Set();
+    engineUnsubscribe = null;
+    approvedPlan = null;
+    answeredRounds = 0;
+    coveredTopics = new Set();
+    /** A lazy facade: tools are built before the engine exists and the engine needs the runtime. */
+    api;
+    constructor(deps) {
+        this.deps = deps;
+        this.env = deps.env ?? process.env;
+        const gov = governanceOf(deps.config());
+        this.enabledAtStart = gov.enabled;
+        // STATIC, evaluated once (D-22). `neverPrompts` is read off the gate object, which is
+        // exactly what `createPlanTools` registers on.
+        this.registered =
+            deps.teamRegistered &&
+                gov.enabled &&
+                !isGovernanceEnvDisabled(this.env) &&
+                deps.gate.neverPrompts !== true;
+        this.api = this.buildLazyApi();
+    }
+    // -------------------------------------------------------------------------
+    // Registration and availability
+    // -------------------------------------------------------------------------
+    /** Whether governance tools were registered at construction. Never changes. */
+    isRegistered() {
+        return this.registered;
+    }
+    /** The live answer, with the precise reason when it is no. */
+    isAvailable() {
+        const config = this.deps.config();
+        const gov = governanceOf(config);
+        if (!this.registered)
+            return { ok: false, reason: this.unregisteredReason(gov) };
+        if (isGovernanceEnvDisabled(this.env))
+            return { ok: false, reason: 'disabled_env' };
+        if (!gov.enabled)
+            return { ok: false, reason: 'disabled_config' };
+        if (!config.team.enabled)
+            return { ok: false, reason: 'team_off' };
+        if (!this.deps.hasApiKey())
+            return { ok: false, reason: 'no_api_key' };
+        return { ok: true };
+    }
+    unregisteredReason(gov) {
+        if (isGovernanceEnvDisabled(this.env))
+            return 'disabled_env';
+        if (this.deps.gate.neverPrompts === true)
+            return 'headless';
+        if (!this.deps.teamRegistered)
+            return 'no_team';
+        // Disabled at start. Now on => the tool array cannot grow: restart. Still off => config.
+        return !this.enabledAtStart && gov.enabled ? 'restart_required' : 'disabled_config';
+    }
+    /** The exact sentence for the current unavailability, or null when available. */
+    unavailableText() {
+        const a = this.isAvailable();
+        if (a.ok)
+            return null;
+        return a.reason === 'restart_required' ? RESTART_REQUIRED_TEXT : unavailableReasonText(a.reason);
+    }
+    /** Shift+Tab cycle: four states when usable and `governance.shiftTab`, else the classic two. */
+    postureCycle() {
+        const gov = governanceOf(this.deps.config());
+        return this.isAvailable().ok && gov.shiftTab ? POSTURES_FULL : POSTURES_CLASSIC;
+    }
+    // -------------------------------------------------------------------------
+    // Posture state (the gate mode lives in the controller)
+    // -------------------------------------------------------------------------
+    isGovernOn() {
+        return this.governOn;
+    }
+    setGovernOn(on) {
+        this.governOn = on;
+    }
+    getPendingPosture() {
+        return this.pendingPosture;
+    }
+    setPendingPosture(pending) {
+        this.pendingPosture = pending;
+    }
+    /** Entering PLAN+GOVERN starts a fresh interview and drops any older plan (9.3). */
+    onPostureAdopted(posture, previous) {
+        if (posture === 'plan_govern' && previous !== 'plan_govern') {
+            this.answeredRounds = 0;
+            this.coveredTopics.clear();
+            this.approvedPlan = null;
+        }
+    }
+    isStageRunning() {
+        return this.engine?.isStageRunning() ?? false;
+    }
+    // -------------------------------------------------------------------------
+    // Prompt blocks
+    // -------------------------------------------------------------------------
+    /**
+     * `''` unless governance is on, registered and available (closed state: byte-equal).
+     *
+     * `config` is the config the prompt is being composed FOR. A settings save composes the
+     * prompt from the candidate BEFORE it becomes live, so reading the live config here would
+     * quote the limits from before the save (governance-mode-v1-1 IF-3).
+     */
+    orchestratorBlock(posture, config) {
+        if (!this.registered || !isGovernancePosture(posture) || !this.isAvailable().ok)
+            return '';
+        const gov = governanceOf(config ?? this.deps.config());
+        return buildOrchestratorBlock({
+            posture,
+            limits: {
+                maxWorkPackages: gov.maxWorkPackages,
+                maxPhases: gov.maxPhases,
+                maxRework: gov.maxRework,
+                maxFixCycles: gov.maxFixCycles,
+                budgetTokens: gov.budgetTokens,
+            },
+        });
+    }
+    /** `''` unless PLAN+GOVERN. */
+    planAddendum(posture, config) {
+        if (!this.registered || posture !== 'plan_govern' || !this.isAvailable().ok)
+            return '';
+        return buildPlanGovernAddendum(governanceOf(config ?? this.deps.config()).minAskRounds);
+    }
+    roleBlockFor(spec) {
+        const ext = spec.governance;
+        if (ext === undefined)
+            return '';
+        return buildRoleBlock(ext, { integrationCommands: ext.integrationCommands ?? [] });
+    }
+    // -------------------------------------------------------------------------
+    // PLAN+GOVERN interview and approval
+    // -------------------------------------------------------------------------
+    /** Called from the controller's `noteAnswered`: one real, answered, non-duplicate round. */
+    noteAnsweredRound(questions = []) {
+        if (!this.governOn || this.deps.getGateMode() !== 'plan')
+            return;
+        this.answeredRounds += 1;
+        const text = questions.map((q) => `${q.header} ${q.question}`).join(' ');
+        TOPIC_PROBES.forEach((probe, index) => {
+            if (probe.test(text))
+                this.coveredTopics.add(index);
+        });
+    }
+    answeredRoundCount() {
+        return this.answeredRounds;
+    }
+    /** `submit_plan` pre-check: a refusal text, or null to proceed. */
+    beforeSubmitPlan() {
+        if (!this.governOn || this.deps.getGateMode() !== 'plan')
+            return null;
+        const need = governanceOf(this.deps.config()).minAskRounds;
+        if (need <= 0 || !this.deps.gate.canPrompt())
+            return null;
+        if (this.answeredRounds >= need)
+            return null;
+        const uncovered = PLAN_INTERVIEW_TOPICS.filter((_, i) => !this.coveredTopics.has(i));
+        return govAskRoundsRefusal(this.answeredRounds, need, uncovered);
+    }
+    /** Stash the approved plan when governance is on. Returns which way the session goes. */
+    handlePlanApproved(plan) {
+        if (!this.governOn)
+            return 'build';
+        this.approvedPlan = renderPlanAsSpec(plan);
+        return 'govern';
+    }
+    /** `gov_run start` consumes the stash exactly once. */
+    takeApprovedPlan() {
+        const plan = this.approvedPlan;
+        this.approvedPlan = null;
+        return plan;
+    }
+    // -------------------------------------------------------------------------
+    // Tools
+    // -------------------------------------------------------------------------
+    /** `[]` when not registered, which is the byte-identical closed path. */
+    leadTools() {
+        if (!this.registered)
+            return [];
+        return [makeGovRunTool(this.api), makeGovDispatchTool(this.api)];
+    }
+    leadPolicyExempt() {
+        return GOV_LEAD_TOOL_NAMES;
+    }
+    childPolicyExempt() {
+        return GOV_CHILD_TOOL_NAMES;
+    }
+    /** Role tools for a governed child; `[]` for anything else. */
+    childToolsFor(spec) {
+        const ext = spec.governance;
+        if (ext === undefined)
+            return [];
+        const identity = { id: ext.identity, role: ext.role, generation: ext.generation };
+        return buildChildTools(ext.role, this.api, identity, { getCwd: () => this.deps.getCwd() });
+    }
+    /**
+     * Narrow a governed child's finished tool array: the inspector loses its write tools and
+     * gets the restricted shell, and every read-class tool gets the store tripwire.
+     *
+     * This runs on the factory's RESULT (see `SubagentDeps.narrowToolsFor`) because it has to
+     * see the built-in `bash` to replace it, while the role tools had to go IN through the
+     * factory. A non-governed spec comes back untouched.
+     */
+    narrowToolsFor(spec, tools) {
+        const ext = spec.governance;
+        if (ext === undefined)
+            return tools;
+        const root = getGovernanceDir();
+        const base = ext.role === 'INSP'
+            ? applyInspectorToolPolicy(tools, { integrationCommands: ext.integrationCommands ?? [] })
+            : tools;
+        return base.map((tool) => withGovernanceReadGuard(tool, root));
+    }
+    // -------------------------------------------------------------------------
+    // Engine lifecycle and events
+    // -------------------------------------------------------------------------
+    /** The engine is created on first use: a session that never governs never opens a store. */
+    ensureEngine() {
+        if (this.engine !== null)
+            return this.engine;
+        const runtime = this.deps.getRuntime();
+        if (runtime === null)
+            throw new Error('governance: no team runtime in this session');
+        const store = new RunStore({ root: getGovernanceDir() });
+        this.store = store;
+        const engineDeps = {
+            runtime,
+            store,
+            artifacts: new ArtifactStore(store),
+            getConfig: () => governanceOf(this.deps.config()),
+            getTeamCeiling: () => Math.max(1, Math.min(this.deps.config().team.maxSubagents, TEAM_LIMITS.hardMaxSubagents)),
+            getCwd: () => this.deps.getCwd(),
+            getSessionId: () => this.deps.getSessionId?.(),
+            withPausedWatchdog: (fn) => this.deps.withPausedWatchdog(fn),
+            hasApiKey: () => this.deps.hasApiKey(),
+            modelCost: () => this.deps.modelCost(),
+            takeApprovedPlan: () => this.takeApprovedPlan(),
+            confirmCharter: (charter, signal) => this.confirmCharter(charter, signal),
+            now: this.deps.now ?? Date.now,
+        };
+        this.engine = createGovernanceEngine(engineDeps);
+        this.engineUnsubscribe = this.engine.subscribe((event) => {
+            for (const listener of [...this.listeners])
+                listener(event);
+        });
+        return this.engine;
+    }
+    /** `confirmCharter` through the EXISTING plan-review overlay; no new overlay kind (RV-10). */
+    async confirmCharter(charter, signal) {
+        if (!this.deps.gate.canPrompt())
+            return { decision: 'approved' };
+        const plan = {
+            title: charter.title,
+            summary: charter.summary,
+            steps: charter.steps,
+            filesTouched: charter.filesTouched,
+            risks: charter.risks,
+            openQuestions: [],
+        };
+        const response = await this.deps.withHumanWait(() => this.deps.gate.request({ kind: 'plan', plan }, signal));
+        if (response === null || response.kind !== 'planDecision')
+            return null;
+        return { decision: response.decision, feedback: response.feedback };
+    }
+    /** Subscribe to the governance event stream (works before the engine exists). */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    snapshot() {
+        return this.engine?.snapshot() ?? null;
+    }
+    /** Run + ledger for the `/gov board` overlay (read-only views of live memory). */
+    boardInput() {
+        const core = this.engine?.internals;
+        if (core === undefined || core.run === null)
+            return null;
+        return {
+            run: core.run,
+            ledger: core.ledger,
+            boardPath: join(getGovernanceDir(), core.run.runId, 'board.md'),
+        };
+    }
+    abortStage() {
+        this.engine?.abortStage();
+    }
+    /**
+     * Recent runs for `/gov runs`, newest first. Opens the store lazily; `[]` when governance
+     * is unusable. `RunStore.listRuns()` is ALREADY newest-first: the previous
+     * `slice(-10).reverse()` therefore returned the OLDEST ten once there were more than ten.
+     */
+    async listRuns() {
+        if (!this.registered)
+            return [];
+        const store = this.store ?? new RunStore({ root: getGovernanceDir() });
+        const rows = await store.listRuns();
+        return rows.slice(0, RUNS_LISTED).map((r) => ({
+            runId: r.runId,
+            goal: r.goal,
+            status: r.status,
+            updatedAt: r.updatedAt,
+            ...(r.digest !== undefined ? { digest: r.digest } : {}),
+        }));
+    }
+    /** `/gov report [runId]`: a stored report, read-only (governance-mode-v1-1 7.2). */
+    async readReport(runId) {
+        if (!this.registered)
+            return { kind: 'no_run' };
+        const store = this.store ?? new RunStore({ root: getGovernanceDir() });
+        const wanted = (runId ?? '').trim();
+        if (wanted !== '')
+            return readRunReport(store, wanted);
+        const latest = await store.latestForCwd(this.deps.getCwd());
+        return latest === null ? { kind: 'no_run' } : readRunReport(store, latest.runId);
+    }
+    /** `/gov pause`: the engine's verdict, or `no_run` when no engine was ever created. */
+    requestPause() {
+        return this.engine?.requestPause() ?? Promise.resolve('no_run');
+    }
+    cancelPause() {
+        return this.engine?.cancelPause() ?? false;
+    }
+    /** The dispatch-plan line for the live run (`/gov status`), or null without one. */
+    dispatchPlanText() {
+        const run = this.engine?.internals.run ?? null;
+        if (run === null)
+            return null;
+        const ceiling = Math.max(1, Math.min(this.deps.config().team.maxSubagents, TEAM_LIMITS.hardMaxSubagents));
+        return formatDispatchEstimate(estimateForRun(run, ceiling)) || null;
+    }
+    /**
+     * The run `/gov resume [runId]` should hand to the orchestrator: the named one when it
+     * exists, else the newest resumable run for this directory. `null` when there is none.
+     */
+    async findResumableRun(runId) {
+        if (!this.registered)
+            return null;
+        const store = this.store ?? new RunStore({ root: getGovernanceDir() });
+        if (runId !== undefined && runId !== '') {
+            const known = (await store.listRuns()).find((r) => r.runId === runId);
+            return known ? known.runId : null;
+        }
+        const latest = await store.latestResumable(this.deps.getCwd());
+        return latest ? latest.runId : null;
+    }
+    dispose() {
+        this.engineUnsubscribe?.();
+        this.engineUnsubscribe = null;
+        this.engine?.dispose();
+        this.engine = null;
+        this.listeners.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Lazy facade
+    // -------------------------------------------------------------------------
+    buildLazyApi() {
+        const e = () => this.ensureEngine();
+        return {
+            start: (input, signal) => e().start(input, signal),
+            status: () => e().status(),
+            resume: (runId) => e().resume(runId),
+            dispatchStage: (input, signal) => e().dispatchStage(input, signal),
+            close: (summary) => e().close(summary),
+            abandon: (reason) => e().abandon(reason),
+            resolve: (input) => e().resolve(input),
+            snapshot: () => this.snapshot(),
+            isStageRunning: () => this.isStageRunning(),
+            abortStage: () => this.abortStage(),
+            subscribe: (listener) => this.subscribe(listener),
+            dispose: () => this.dispose(),
+            submitWork: (id, input) => e().submitWork(id, input),
+            submitReview: (id, input) => e().submitReview(id, input),
+            submitTest: (id, input) => e().submitTest(id, input),
+            inspectorApply: (input) => e().inspectorApply(input),
+            inspectorRule: (input) => e().inspectorRule(input),
+            inspectorSettle: (input) => e().inspectorSettle(input),
+            standings: () => e().standings(),
+            readArtifact: (id, input) => e().readArtifact(id, input),
+            requestView: (id, input) => e().requestView(id, input),
+            scan: (id, input) => e().scan(id, input),
+        };
+    }
+    /** Posture helper for callers that only hold the gate mode. */
+    currentPosture(mode) {
+        return composePosture(mode, this.governOn);
+    }
+}