@aragon-agent/cli 0.6.44 → 0.6.45

package/CHANGELOG.md

@@ -8,6 +8,44 @@ were written.
 ## Unreleased
 
 ### Added
+- **Governance mode - a multi-agent "legion" collaboration posture.** `Shift+Tab` (and `Ctrl+N`)
+  now cycle `BUILD -> PLAN -> GOVERN -> PLAN+GOVERN -> BUILD`; `/gov` goes to any of them
+  directly. In `GOVERN` the main agent becomes an **Orchestrator** that cannot write files or run
+  shell commands (enforced at the tool layer) and drives a team under a separation of powers
+  (development, review, testing, plus an unscored inspector) and a GT token economy: automatic
+  scoring from structured verdicts, escrow released only when integration passes, clawback on
+  failure, elimination and respawn. `PLAN+GOVERN` interviews you for at least
+  `governance.minAskRounds` answered rounds before the plan is accepted, then runs the approved
+  plan as the specification. New: the `gov_run` / `gov_dispatch` tools (never part of
+  `aragon exec`), the `/gov` command (`status|on|plan|off|board|runs|resume|abort|budget|help`), a
+  Legion panel, settlement cards in the transcript, a `/gov board` overview, the `governAccent`
+  theme token, `--govern` / `--plan-govern` / `--no-governance`, the `governance.*` config keys
+  and `ARAGON_GOVERNANCE=0`. Runs are persisted under `<home>/governance/` and survive `Esc`,
+  crashes and restarts. With governance disabled the system prompt, the tool list and the tool
+  timeout table are byte-identical to before. Cost note: the two orchestrator tool definitions
+  add a small per-request overhead to every session in which governance is available.
+- **Governance mode, round two: a gentle stop, a settings page, visible cost, a report you can
+  re-read.** `/gov pause` pauses a governed run at the end of the stage that is running - nothing is
+  killed, no submission is lost, no GT moves (Esc is still the immediate stop) - and pauses at once
+  when no stage is running; `/gov pause cancel` withdraws a request that has not fired. While it
+  waits, the panel header reads `pausing after REVIEW`, the status chip `GOV pausing`, and the hint
+  row `pause pending: /gov pause cancel`. A run that is `escalated` (waiting on your ruling) is never
+  overwritten by a pause. The Orchestrator is told to stop and wait, and not to resume a run you
+  paused. **Settings > Governance** is now a page (a row under Team): the eleven `governance.*`
+  keys adjust with the arrow keys and save with the rest of Settings; turning `Governance` on or
+  off says that it applies next launch. `/gov runs` is a table with phase, health, team tokens,
+  cost (`n/a` when the model is unpriced, never `$0.00`) and the last update, and marks unfinished
+  runs with `*`; the columns drop with the terminal width. `/gov report [runId]` re-reads the final
+  report of a run (or its newest phase report, or the board) in the transcript, capped at 120
+  lines with the full path. The charter card, `/gov status` and the Orchestrator's `gov_run start`
+  result now carry a **dispatch plan** (`Dispatch plan: 10 for a clean run; a rework round adds up to
+  3, a fix cycle up to 2; the run is capped at 120. Counts only`). It states counts of
+  `gov_dispatch` calls only - never tokens or money - and it is deliberately not an upper bound.
+  A model-free screen gallery (`GOV_GALLERY=1 npx vitest run governance-gallery`) renders every
+  governance surface at 60/80/100/160 columns in colour, no-colour and ASCII variants. No config
+  key changed. On disk, `index.jsonl` rows gain an optional `digest` and a run now appends at most
+  one extra index row per change of that digest (about 250 rows for a run of 120 dispatches);
+  older rows read back as `-`.
 - **Automatic skill triage, and no round limit on questions.** Two changes that
   share one idea: replace a hard limit with guidance the agent can act on.
   `ask_user` is no longer capped at four rounds per turn — the cap, its prompt
@@ -168,6 +206,12 @@ were written.
   the same bytes it wrote before.
 
 ### Fixed
+- `/gov runs` listed the **oldest** ten governed runs instead of the newest ten once there
+  were more than ten (the store already returned newest first and the listing then took the last
+  ten and reversed them). It now shows the newest ten, newest first.
+- A settings save now composes the Orchestrator prompt from the config being saved, not from the
+  one it replaces, so the limits the prompt quotes (`maxRework`, `maxWorkPackages`, ...) are the
+  new ones the moment Settings closes.
 - Changing only the fan-out width no longer drops the subagent model a session kit
   installed. The settings save read "the `team` section was written" as "the user
   re-decided the subagent slot", so adjusting `Max subagents` silently released a slot the

package/README.md

@@ -950,7 +950,8 @@ ignores them rather than rejecting the library):
 | `/save [file]` | Export the session to JSON - a file you keep, unchanged by this feature |
 | `/resume [file]` | Load a saved session. This session moves to a NEW id, and the spend counter restarts |
 | `/session [copy\|pin]` | Report this session's id, file and branch parent; `copy` puts `aragon --resume <id>` on the clipboard; `pin` makes `sessions prune` skip the file forever |
-| `/plan [on\|off\|status]` | Toggle plan mode - the keyboard-free equivalent of `Shift+Tab` |
+| `/plan [on\|off\|status]` | Toggle plan mode (and leave governance) - the keyboard-free equivalent of `Shift+Tab` |
+| `/gov [status\|on\|plan\|off\|board\|runs\|report [id]\|resume [id]\|pause [cancel]\|abort\|budget <n\|off>\|help]` | **Governance mode**: a governed engineering team (dev / review / test / inspector) with a GT scoring economy. `on` = GOVERN, `plan` = PLAN+GOVERN (interview first), `board` opens the full-screen overview, `runs` lists past runs with phase / health / tokens / cost, `report` re-reads a run's report, `pause` stops at the end of the running stage (nothing is killed), `abort` stops the running stage at once (the run is resumable). See [Governance mode](#governance-mode) |
 | `/team [on\|off\|status]` / `/team [-n <n>] [--parts a,b,c] [--read-only] <brief>` | **Force team mode and start now.** `/team <brief>` arms forced team mode and submits that work as a normal turn: the lead analyses and plans it, then calls `task` — the directive, the `<forced_team_mode>` prompt block and a mechanical end-of-turn gate all say so. `/team on` arms without submitting, `/team off` leaves, `/team` reports. The configuration it used to carry (team switch, width, concurrency, supervisor, subagent model) lives in `Settings > Team` |
 | `/todo [on\|off\|panel on\|off\|follow <mode>\|acceptance on\|off\|reset\|clear\|continue]` | Todo planning: status, the on/off switch, the rail, follow-through, acceptance criteria, and picking an unfinished plan back up |
 | `/retry [show\|on\|off\|max <n>]` | API retry: the effective ladder, the on/off switch, the retry count. Takes effect **in the running session**, children included |
@@ -984,7 +985,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Ctrl+G` | **快捷键抽屉**：自上而下列出全部快捷键、各自的作用关键词，选中行下方再给一句话说明。`Up`/`Down`（或 `k`/`j`）移动、`PgUp`/`PgDn` 翻页、`d` 切换状态详情行、`r` 重新生成任务摘要、`Esc` 关闭。再按一次 `Ctrl+G` 关闭；其它参考类浮层打开时按它会直接接管，等待决策的 `confirm` / `question` / `plan` 除外 |
 | `Enter` | 空闲时发送，运行时加入队列；收到 Core 已纳入会话的接收凭据后才移除 Queue 提示 |
 | `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | 插入换行。应用默认请求终端区分修饰键（Windows 用 win32-input-mode，macOS/Linux 用 kitty/modifyOtherKeys），Shift+Enter 在支持的终端开箱即用；不支持的终端用 Ctrl+J。参见 [终端设置](#terminal-setup-for-shiftenter) |
-| `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
+| `Shift+Tab` | Cycle the posture `BUILD` -> `PLAN` -> `GOVERN` -> `PLAN+GOVERN` -> `BUILD` (two states when governance is unavailable or `governance.shiftTab` is off). Equivalent: `/plan`, `/gov`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+N` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing. Written `Ctrl+N` everywhere, never `^N` - `^N` is the header's line-offset chip |
 | `Ctrl+P` | **Quick prompt library**: the manager - create, edit, delete, favourite and reorder your own prompts. See [Quick prompt library](#quick-prompt-library) |
 | `Ctrl+B` | **Agents board**: the details of a running dispatch. Left column lists every child (not just the five the roster fits), the right-hand sections show the selected child's state, turns, tools, tokens, files, mail, supervisor actions, retries, compaction, its current activity, its final answer or error, and the last 24 events. `Up` / `Down` change the child, `PgUp` / `PgDn` and the wheel page, `Esc` closes. The board survives the end of the dispatch - it freezes the last live snapshot and marks it `dispatch ended` - and opens after the fact from the session's own team card, where everything except the live-only sections (current activity, mail count, timeline) is still readable. Pressing `Ctrl+B` again, or `/agents`, opens and closes it |
@@ -1539,6 +1540,72 @@ rung. `--no-render-governor` (or `renderGovernor: false`, or
 `ARAGON_RENDER_GOVERNOR=0`) turns the adaptation off entirely; the output is
 identical, just heavier under load.
 
+## Governance mode
+
+`GOVERN` and `PLAN+GOVERN` are two more postures on the same `Shift+Tab` cycle. In either,
+your session is led by an **Orchestrator** that cannot touch your files: it reads, asks you what
+it must, splits the work into work packages (WPs) and drives a governed team through the
+`gov_run` / `gov_dispatch` tools. Every implementation step is done by a dispatched agent, and
+the writer of a change is never the one who judges it.
+
+| Power | Role | What it does |
+| --- | --- | --- |
+| Development | `DEV` | Implements one WP completely and reports which interface contracts it verified |
+| Review | `REV` | Reviews independently, may reject or fix small issues directly |
+| Testing | `TEST` | Verifies behaviour and traces every acceptance criterion to evidence |
+| Inspector | `INSP` | The fourth power: rules on claims, checks contracts, runs the registered integration commands, arbitrates. Not scored |
+
+**GT (governance tokens)** is a score for the run, unrelated to LLM context tokens. Every
+DEV / REV / TEST agent starts with 100 GT. Rule-engine events are booked automatically from
+structured verdicts (a passed review is +15, a rejection -20, ...); positive scores are held in
+**escrow** until the phase's integration check passes, and are clawed back from whoever caused a
+failure. An agent whose confirmed score reaches zero is replaced by a successor that is told why.
+The inspector books only judgement events, and each one needs written evidence.
+
+Each phase runs `dev -> review -> test -> settle -> integrate` (plus `fix` and a second
+`integrate` if integration fails). The engine refuses illegal orders and every tool result ends
+with `NEXT:` - the legal next actions - so a compacted or `/clear`ed session can resume.
+Disputes go to the inspector first and, if fundamental, to you (`ask_user`), and your ruling
+closes the loop with `gov_run resolve`.
+
+`PLAN+GOVERN` first runs the normal plan mode with at least `governance.minAskRounds` (default 2)
+**answered** question rounds before `submit_plan` is accepted; approving the plan switches to
+`GOVERN` and the plan becomes the specification.
+
+While a stage runs, a compact panel shows the pipeline, the roster, the GT bars and the latest
+ledger movements; the transcript gets a card only at charter, phase settlement, escalation and
+close. `/gov board` opens the full overview. `Esc` stops the running stage; the run is saved
+(`<home>/governance/<runId>/`) and `/gov resume` picks it up, re-dispatching only the missing
+work. A stage in flight defers any posture change until it ends.
+
+**Stopping gently.** `/gov pause` lets the stage that is running finish - every submission lands,
+nothing is killed or rolled back, no GT moves - and then pauses the run; with no stage running it
+pauses at once. `/gov pause cancel` withdraws a request that has not fired, and `/gov resume`
+continues a paused run. Unlike `Esc`, it never throws away work in progress. A run that is waiting
+on your ruling is left as it is.
+
+**Cost before you start.** The charter, `/gov status` and the `gov_run start` result carry a
+dispatch plan: how many `gov_dispatch` calls a clean run needs (stages wider than
+`team.maxSubagents` are split, which adds calls), how many one more rework round or fix cycle adds,
+and the hard cap of 120 per run. These are counts of calls, not a forecast of tokens or money, and
+not an upper bound on the total.
+
+**Looking back.** `/gov runs` shows each run's phase, health, team tokens, cost (`n/a` for an
+unpriced model) and last update, newest first, with `*` on runs you can still resume. `/gov report
+[runId]` prints the run's final report (else its newest phase report, else the board) in the
+transcript, up to 120 lines and the path of the full file. Nothing is regenerated; it only reads.
+
+Limits and switches (`aragon config set governance.<key> <value>`, or **Settings > Governance**): `enabled`, `shiftTab`,
+`panel`, `profile` (`general` / `ml` / `product` / `api-security`), `maxWorkPackages` (<= 8),
+`maxPhases` (<= 6), `maxRework` (<= 5), `maxFixCycles` (<= 5), `minAskRounds` (0-5),
+`budgetTokens` (team tokens only; 0 = unlimited), `confirmCharter`. `ARAGON_GOVERNANCE=0` and
+`--no-governance` disable it; `--govern` / `--plan-govern` start in a governed posture. It is not
+available in `aragon exec` / `-p`. Governed agents are team agents: each one spends tokens, so a
+run costs several times a single-agent turn - watch the status-bar chip and set `budgetTokens`.
+
+The information boundary is a tripwire, not a sandbox: roles are shown only what they may see and
+cannot read the governance store through the tools, but a determined `bash` command could.
+
 ## Plan mode
 
 `aragon` has two postures, and `Shift+Tab` switches between them. `/plan` does

package/dist/agent/controller.d.ts

@@ -35,6 +35,12 @@ import type { TaskSummaryOutcome } from '../fast/task-summary-types.js';
 import { ContextMeter, type ContextUsageListener } from '../compaction/meter.js';
 import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot } from '../compaction/types.js';
 import type { AcceptanceItem, TodoEventListener, TodoSnapshot } from '../todo/types.js';
+import { GovernanceWiring } from './governance-wiring.js';
+import { type GovernanceConfig } from '../config/governance-config.js';
+import { type Posture } from '../governance/posture.js';
+import type { GovernanceAvailability } from '../governance/copy.js';
+import type { PauseOutcome } from '../governance/engine/pause.js';
+import type { GovernanceEventListener, GovernanceSnapshot } from '../governance/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
 import type { SkillRoutingReport } from '../skills/triage.js';
@@ -198,6 +204,12 @@ export interface AgentModeState {
     /** Non-null only while a `plan -> build` switch is waiting for `agent_end`. */
     pending: AgentMode | null;
 }
+/** What `setPosture` adopted (governance-mode 4.2): the same contract as `AgentModeState`. */
+export interface PostureState {
+    effective: Posture;
+    /** A change waiting for `agent_end` (plan-to-build, or any change while a stage runs). */
+    pending: Posture | null;
+}
 export interface PreflightResult {
     ok: boolean;
     message?: string;
@@ -297,6 +309,11 @@ export declare class AgentController {
     private readonly planInteractive;
     private readonly teamRegistered;
     private readonly teamRuntime;
+    /**
+     * Governance mode (governance-mode 14.2). Every decision lives in the wiring class; this
+     * file only forwards. `registered` inside it is fixed at construction (D-22).
+     */
+    private readonly governance;
     private forcedTeam;
     private readonly todoRegistered;
     private todoEnabled;
@@ -635,6 +652,58 @@ export declare class AgentController {
     applyPendingMode(): AgentModeState | null;
     /** Named read surface for `/plan status`, so no command reaches into internals. */
     getPlanStatus(): AgentModeState;
+    getPosture(): Posture;
+    getPostureState(): PostureState;
+    /** The Shift+Tab cycle: four states when governance is usable, else the classic two. */
+    getPostureCycle(): readonly Posture[];
+    isGovernanceAvailable(): GovernanceAvailability;
+    /** The precise sentence for why governance cannot be used now, or null. */
+    getGovernanceUnavailableText(): string | null;
+    /**
+     * Request a posture and return what was ADOPTED (the `setAgentMode` contract: the caller
+     * dispatches the returned value, never the requested one). Tighten at once, loosen when
+     * idle, and while a governed stage runs defer EVERYTHING to `agent_end` (D-23).
+     */
+    setPosture(next: Posture, opts?: {
+        force?: boolean;
+    }): PostureState;
+    /** Adopt a deferred posture. Call from `agent_end`. Null when nothing was pending. */
+    applyPendingPosture(): PostureState | null;
+    /** Esc / `/gov abort`: stop the in-flight governed stage (the run becomes `paused`). */
+    abortGovernanceStage(): void;
+    isGovernanceStageRunning(): boolean;
+    getGovernanceSnapshot(): GovernanceSnapshot | null;
+    /** Run + ledger behind the `/gov board` tabs that the snapshot alone cannot fill. */
+    getGovernanceBoardInput(): ReturnType<GovernanceWiring['boardInput']>;
+    subscribeGovernance(listener: GovernanceEventListener): () => void;
+    /** Recent governed runs (`/gov runs`). */
+    listGovernanceRuns(): ReturnType<GovernanceWiring['listRuns']>;
+    /** `/gov pause` and `/gov pause cancel`: stop at the next clean stage boundary. */
+    requestGovernancePause(): Promise<PauseOutcome>;
+    cancelGovernancePause(): boolean;
+    /** Whether the governance tools were registered at launch (Settings > Governance). */
+    isGovernanceRegistered(): boolean;
+    /** `/gov report [runId]`: a stored report, read-only. */
+    readGovernanceReport(runId?: string): ReturnType<GovernanceWiring['readReport']>;
+    /** The dispatch-plan line for the live run, for `/gov status`. */
+    getGovernanceDispatchPlan(): string | null;
+    /**
+     * The PLAN+GOVERN interview progress for the question overlay's chip, or null outside that
+     * posture or when no minimum is enforced (governance-mode 9.3).
+     */
+    getGovernanceInterview(): {
+        answered: number;
+        required: number;
+    } | null;
+    /** `/gov resume`: the run id to hand to the orchestrator, or null when none exists. */
+    findResumableGovernanceRun(runId?: string): Promise<string | null>;
+    getGovernanceConfig(): GovernanceConfig;
+    /** Adopt a governance config patch for this session and re-render (the block quotes limits). */
+    setGovernanceConfig(patch: Partial<GovernanceConfig>): GovernanceConfig;
+    /** `submit_plan` approval: PLAN+GOVERN hands over to the team, plain PLAN goes to BUILD. */
+    private onPlanApproved;
+    /** What a team child costs per token, or undefined for an unpriced model (never $0.00). */
+    private teamModelCost;
     /**
      * READ-ONLY guard probe, called by `ask_user` BEFORE it opens the overlay.
      *

package/dist/agent/controller.js

@@ -48,6 +48,12 @@ import { TodoStore } from '../todo/store.js';
 import { createTodoTool } from '../todo/todo-tool.js';
 import { buildTodoBlock } from '../todo/prompt.js';
 import { createPlanTools } from '../tools/plan-tools.js';
+import { GovernanceWiring } from './governance-wiring.js';
+import { clampGovernanceConfig } from '../config/governance-config.js';
+import { decidePostureTransition } from '../governance/posture-transition.js';
+import { composePosture, splitPosture } from '../governance/posture.js';
+import { APPROVED_GOVERN_RESULT } from '../governance/prompts/refusals.js';
+import { GOV_LEAD_TOOL_NAMES } from '../governance/limits.js';
 import { ASK_GUARD_LIMITS, DENY_ALL_HUMAN_INPUT, questionFingerprint, } from '../tools/human-input.js';
 import { getLogger } from '../logging/logger.js';
 import { createNodeSkillHost } from '../skills/node-host.js';
@@ -190,6 +196,11 @@ export class AgentController {
     // -----------------------------------------------------------------------
     teamRegistered;
     teamRuntime;
+    /**
+     * Governance mode (governance-mode 14.2). Every decision lives in the wiring class; this
+     * file only forwards. `registered` inside it is fixed at construction (D-22).
+     */
+    governance;
     // -----------------------------------------------------------------------
     // Forced team mode (team-command-forced-dispatch §3.5 / D-4).
     //
@@ -447,6 +458,29 @@ export class AgentController {
         // snapshot of "is `task` in this.tools at all". The live switch is
         // `config.team.enabled`, read through `isTeamEnabled()` — no second copy.
         this.teamRegistered = config.team.enabled;
+        // BEFORE the runtime: its child hooks are read off this object. `getRuntime` is a
+        // closure because the engine (created lazily on first use) needs the runtime, and the
+        // runtime needs these hooks.
+        this.governance = new GovernanceWiring({
+            teamRegistered: this.teamRegistered,
+            config: () => this.config,
+            gate: humanInput,
+            getCwd: () => this.cwd,
+            getGateMode: () => this.effectiveMode,
+            withPausedWatchdog: (fn) => this.withPausedWatchdog(fn),
+            withHumanWait: (fn) => this.withHumanWait(fn),
+            hasApiKey: () => this.hasApiKey(),
+            modelCost: () => this.teamModelCost(),
+            getRuntime: () => this.teamRuntime,
+        });
+        // THE LAUNCH POSTURE (`--govern` / `--plan-govern`, governance-mode 11.2). Only when the
+        // tools were actually registered: `loadConfig` already degraded an unusable request to the
+        // classic posture, and this guards the remaining construction-time case.
+        const initialPosture = config.initialPosture;
+        if (this.governance.isRegistered() && (initialPosture === 'govern' || initialPosture === 'plan_govern')) {
+            this.governance.setGovernOn(true);
+            this.effectiveMode = initialPosture === 'plan_govern' ? 'plan' : 'build';
+        }
         this.teamRuntime = this.teamRegistered
             ? new TeamRuntime({
                 getConfig: () => this.config,
@@ -530,6 +564,16 @@ export class AgentController {
                 // and nothing anywhere reports it. Spread conditionally so a session
                 // with no policy builds `SubagentDeps` exactly as it does today.
                 ...(deps.permission ? { permission: deps.permission } : {}),
+                // GOVERNANCE CHILD HOOKS (governance-mode 13.2): present only when governance was
+                // registered, so every other session builds children exactly as before.
+                ...(this.governance.isRegistered()
+                    ? {
+                        extraToolsFor: (spec) => this.governance.childToolsFor(spec),
+                        narrowToolsFor: (spec, tools) => this.governance.narrowToolsFor(spec, tools),
+                        governanceRoleBlockFor: (spec) => this.governance.roleBlockFor(spec),
+                        extraPolicyExempt: this.governance.childPolicyExempt(),
+                    }
+                    : {}),
             })
             : null;
         // ABOVE `createBuiltinTools`, and the ordering is load-bearing for the
@@ -654,7 +698,8 @@ export class AgentController {
                 hasAnsweredQuestions: (questions) => this.hasAnswered(questions),
                 noteAnsweredQuestions: (questions) => this.noteAnswered(questions),
                 withHumanWait: (fn) => this.withHumanWait(fn),
-                onPlanApproved: () => this.setAgentMode('build', { force: true }),
+                onPlanApproved: (plan) => this.onPlanApproved(plan),
+                beforeSubmit: () => this.governance.beforeSubmitPlan(),
             }),
             // THROUGH THE FACTORY for the reason `teamTools` records below (C-2), and
             // empty when todo planning was off at construction — which leaves the
@@ -742,14 +787,7 @@ export class AgentController {
                         // table (I-2 byte parity); a fast or profile model the static
                         // tables do not price yields undefined, so the report says
                         // `pricing unknown` rather than fabricating $0.00 (C-11 / RV-4).
-                        modelCost: () => {
-                            const resolution = this.subagentModelResolution();
-                            if (resolution.effective === 'main')
-                                return this.getModelInfo().cost;
-                            return this.isPricedModel(resolution.ref)
-                                ? this.getModelInfoFor(resolution.ref).cost
-                                : undefined;
-                        },
+                        modelCost: () => this.teamModelCost(),
                         // The same resolution, re-read per dispatch, feeds the report's
                         // disclosure line - one read per consumer, one authority both.
                         subagentModel: () => this.subagentModelResolution(),
@@ -770,6 +808,20 @@ export class AgentController {
                     }),
                 ]
                 : [],
+            // GOVERNANCE (governance-mode 14.3): the Orchestrator's two tools, the ceiling
+            // exemption for exactly those two names (D-22b: NOT HOST_TOOL_NAMES), and the live gate
+            // that refuses the lead's own writes. All three are spread ONLY when registered, so a
+            // session without governance builds the identical options bag.
+            ...(this.governance.isRegistered()
+                ? {
+                    governTools: this.governance.leadTools(),
+                    policyExempt: GOV_LEAD_TOOL_NAMES,
+                    governGate: () => ({
+                        governOn: this.governance.isGovernOn(),
+                        mode: this.effectiveMode,
+                    }),
+                }
+                : {}),
             // Read at CALL time, never cached: the mode flips mid-run when the user
             // approves a plan, and a cached 'plan' would refuse the work they just
             // authorized.
@@ -909,6 +961,14 @@ export class AgentController {
                     // outlived a mid-session `Settings > Team` switch to the supervisor
                     // and killed the dispatch the supervisor was meant to look after.
                     ...(this.teamRegistered ? { task: 0 } : {}),
+                    // P0 (governance-mode D-21 / RV-0): `gov_dispatch` runs a whole governed stage,
+                    // routinely longer than `toolTimeoutMs`, and it listens to `ctx.signal` (it hands
+                    // it to `TeamRuntime.dispatch`), which is what makes `0` safe. Registered in the SAME
+                    // change as the tool itself: a registered tool with no entry here is killed by the
+                    // executor at the default timeout on the first long stage, and no unit test with an
+                    // instant stub dispatch would notice. Absent when unregistered, so the table is
+                    // unchanged for every session without governance.
+                    ...(this.governance.isRegistered() ? { gov_dispatch: 0 } : {}),
                 },
             },
         });
@@ -1066,6 +1126,13 @@ export class AgentController {
         const triageBlock = triageOn && skillsCatalog.length > 0
             ? buildSkillTriageBlock({ candidates: this.turnRouting?.candidates ?? [] })
             : '';
+        // GOVERNANCE (governance-mode 6.1). '' for every non-governed posture, which splices
+        // nothing. In GOVERN with gate mode `build` the team blocks are dropped below: `task` is
+        // refused there, and advertising it would describe a refused capability.
+        const posture = this.getPosture();
+        const governBlock = this.governance.orchestratorBlock(posture, config);
+        const governAddendum = this.governance.planAddendum(posture, config);
+        const dropTeamBlocks = governBlock !== '' && this.effectiveMode === 'build';
         return buildSystemPrompt({
             cwd: this.cwd,
             tools: this.tools,
@@ -1075,13 +1142,15 @@ export class AgentController {
             skillTriageBlock: triageBlock,
             agentMode: this.effectiveMode,
             planInteractive: this.planInteractive,
+            ...(governBlock ? { governBlock } : {}),
+            ...(governAddendum ? { governAddendum } : {}),
             // BOTH halves, and both are required (§4.5). `teamRegistered` false means
             // there is no `task` tool to advertise; `config.team.enabled` false means
             // the user turned the capability off (in settings — the only writer).
             // Advertising in either case would describe a capability the model does not
             // have. Read through the field rather than `this.isTeamEnabled()` so the
             // sentence and the code agree, as the two flags always have here (P1-4).
-            teamBlock: this.teamRegistered && this.config.team.enabled
+            teamBlock: this.teamRegistered && this.config.team.enabled && !dropTeamBlocks
                 ? buildTeamBlock({
                     maxSubagents: config.team.maxSubagents,
                     maxConcurrent: config.team.maxConcurrent,
@@ -1094,7 +1163,7 @@ export class AgentController {
             // session can never be told to use a tool the prompt above it does not
             // mention. Empty everywhere else, which is what keeps I-2 (byte-identical
             // prompt) true for every session that never types `/team`.
-            forcedTeamBlock: this.forcedTeam && this.teamRegistered && this.config.team.enabled
+            forcedTeamBlock: this.forcedTeam && this.teamRegistered && this.config.team.enabled && !dropTeamBlocks
                 ? buildForcedTeamBlock({
                     count: this.forcedTeam.count,
                     planMode: this.effectiveMode === 'plan',
@@ -1635,6 +1704,148 @@ export class AgentController {
             pending: this.pendingMode,
         };
     }
+    // -----------------------------------------------------------------------
+    // Posture (governance-mode 4.2). The gate mode above stays the only thing the tools
+    // read; governance is a second, orthogonal flag (D-1), so none of the 25 `=== 'plan'`
+    // sites changed. These methods compose the two and are the only writers of both.
+    // -----------------------------------------------------------------------
+    getPosture() {
+        return composePosture(this.effectiveMode, this.governance.isGovernOn());
+    }
+    getPostureState() {
+        return { effective: this.getPosture(), pending: this.governance.getPendingPosture() };
+    }
+    /** The Shift+Tab cycle: four states when governance is usable, else the classic two. */
+    getPostureCycle() {
+        return this.governance.postureCycle();
+    }
+    isGovernanceAvailable() {
+        return this.governance.isAvailable();
+    }
+    /** The precise sentence for why governance cannot be used now, or null. */
+    getGovernanceUnavailableText() {
+        return this.governance.unavailableText();
+    }
+    /**
+     * Request a posture and return what was ADOPTED (the `setAgentMode` contract: the caller
+     * dispatches the returned value, never the requested one). Tighten at once, loosen when
+     * idle, and while a governed stage runs defer EVERYTHING to `agent_end` (D-23).
+     */
+    setPosture(next, opts = {}) {
+        const before = this.getPosture();
+        // An unregistered session has no governance to be "on": a stray governed request
+        // degrades to its classic half, so the badge can never claim a gate that is not there.
+        const target = this.governance.isRegistered() ? next : splitPosture(next).mode;
+        const result = decidePostureTransition({
+            current: { mode: this.effectiveMode, governOn: this.governance.isGovernOn() },
+            target,
+            force: opts.force === true,
+            running: this.isRunning(),
+            stageRunning: this.governance.isStageRunning(),
+        });
+        this.effectiveMode = result.mode;
+        this.governance.setGovernOn(result.governOn);
+        this.governance.setPendingPosture(result.pending);
+        // A posture request supersedes a stale plan-to-build deferral from `setAgentMode`.
+        this.pendingMode = null;
+        this.governance.onPostureAdopted(this.getPosture(), before);
+        this.rebuildSystemPrompt();
+        return this.getPostureState();
+    }
+    /** Adopt a deferred posture. Call from `agent_end`. Null when nothing was pending. */
+    applyPendingPosture() {
+        const pending = this.governance.getPendingPosture();
+        if (pending === null)
+            return this.applyPendingMode() === null ? null : this.getPostureState();
+        if (this.governance.isStageRunning())
+            return null;
+        this.governance.setPendingPosture(null);
+        return this.setPosture(pending, { force: true });
+    }
+    /** Esc / `/gov abort`: stop the in-flight governed stage (the run becomes `paused`). */
+    abortGovernanceStage() {
+        this.governance.abortStage();
+    }
+    isGovernanceStageRunning() {
+        return this.governance.isStageRunning();
+    }
+    getGovernanceSnapshot() {
+        return this.governance.snapshot();
+    }
+    /** Run + ledger behind the `/gov board` tabs that the snapshot alone cannot fill. */
+    getGovernanceBoardInput() {
+        return this.governance.boardInput();
+    }
+    subscribeGovernance(listener) {
+        return this.governance.subscribe(listener);
+    }
+    /** Recent governed runs (`/gov runs`). */
+    listGovernanceRuns() {
+        return this.governance.listRuns();
+    }
+    /** `/gov pause` and `/gov pause cancel`: stop at the next clean stage boundary. */
+    requestGovernancePause() {
+        return this.governance.requestPause();
+    }
+    cancelGovernancePause() {
+        return this.governance.cancelPause();
+    }
+    /** Whether the governance tools were registered at launch (Settings > Governance). */
+    isGovernanceRegistered() {
+        return this.governance.isRegistered();
+    }
+    /** `/gov report [runId]`: a stored report, read-only. */
+    readGovernanceReport(runId) {
+        return this.governance.readReport(runId);
+    }
+    /** The dispatch-plan line for the live run, for `/gov status`. */
+    getGovernanceDispatchPlan() {
+        return this.governance.dispatchPlanText();
+    }
+    /**
+     * The PLAN+GOVERN interview progress for the question overlay's chip, or null outside that
+     * posture or when no minimum is enforced (governance-mode 9.3).
+     */
+    getGovernanceInterview() {
+        if (this.getPosture() !== 'plan_govern')
+            return null;
+        const required = this.getGovernanceConfig().minAskRounds;
+        if (required <= 0)
+            return null;
+        return { answered: this.governance.answeredRoundCount(), required };
+    }
+    /** `/gov resume`: the run id to hand to the orchestrator, or null when none exists. */
+    findResumableGovernanceRun(runId) {
+        return this.governance.findResumableRun(runId);
+    }
+    getGovernanceConfig() {
+        return clampGovernanceConfig(this.config.governance);
+    }
+    /** Adopt a governance config patch for this session and re-render (the block quotes limits). */
+    setGovernanceConfig(patch) {
+        const governance = clampGovernanceConfig({ ...this.getGovernanceConfig(), ...patch });
+        this.advanceSettingsRevision();
+        this.config = { ...this.config, governance };
+        this.rebuildSystemPrompt();
+        return governance;
+    }
+    /** `submit_plan` approval: PLAN+GOVERN hands over to the team, plain PLAN goes to BUILD. */
+    onPlanApproved(plan) {
+        if (this.governance.handlePlanApproved(plan) === 'govern') {
+            this.setPosture('govern', { force: true });
+            return APPROVED_GOVERN_RESULT;
+        }
+        this.setAgentMode('build', { force: true });
+    }
+    /** What a team child costs per token, or undefined for an unpriced model (never $0.00). */
+    teamModelCost() {
+        const resolution = this.subagentModelResolution();
+        if (resolution.effective === 'main')
+            return this.getModelInfo().cost;
+        return this.isPricedModel(resolution.ref)
+            ? this.getModelInfoFor(resolution.ref).cost
+            : undefined;
+    }
     /**
      * READ-ONLY guard probe, called by `ask_user` BEFORE it opens the overlay.
      *
@@ -1653,6 +1864,7 @@ export class AgentController {
      * deleted round cap wearing a bigger number.
      */
     noteAnswered(questions) {
+        this.governance.noteAnsweredRound(questions);
         this.askedFingerprints.add(questionFingerprint(questions));
         while (this.askedFingerprints.size > ASK_GUARD_LIMITS.maxRemembered) {
             const oldest = this.askedFingerprints.values().next();
@@ -1872,6 +2084,7 @@ export class AgentController {
         this.modelMetadataGeneration += 1;
         this.modelMetadataAbort.abort();
         this.teamRuntime?.dispose();
+        this.governance.dispose();
         this.fast?.dispose();
         this.compaction?.dispose();
         this.contextMeter.dispose();

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

@@ -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 type { AgentMode } from './agent-mode.js';
+import type { GovernanceSnapshot } from '../governance/types.js';
+import { type Posture } from '../governance/posture.js';
+/** The posture half of a `setAgentMode` action. */
+export interface AdoptedPostureInput {
+    mode: AgentMode;
+    pending: AgentMode | null;
+    /** Written from the controller's adopted state; absent for callers that predate postures. */
+    posture?: Posture;
+    pendingPosture?: Posture | null;
+}
+/**
+ * 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 declare function adoptPosture(current: Posture, action: AdoptedPostureInput): {
+    posture: Posture;
+    pendingPosture: Posture | null;
+};
+/**
+ * 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 declare function foldGovernanceSnapshot(held: GovernanceSnapshot | null, incoming: GovernanceSnapshot): GovernanceSnapshot;