@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/agent/plan-prompt.d.ts

@@ -12,5 +12,12 @@ export declare const PLAN_MODE_BLOCK_VERSION = "v3-2026-10-26";
 export interface PlanModeBlockOptions {
     /** False under `-p` / piped stdin: no overlay can be rendered, so no tools. */
     interactive: boolean;
+    /**
+     * PLAN+GOVERN's interview addendum (governance-mode 6.3). Appended INSIDE the block,
+     * just before the closing tag, and only for an interactive block: a governed team needs
+     * a human to interview. Absent leaves the block byte-identical, so
+     * `PLAN_MODE_BLOCK_VERSION` does not move.
+     */
+    governAddendum?: string;
 }
 export declare function buildPlanModeBlock(options: PlanModeBlockOptions): string;

package/dist/agent/plan-prompt.js

@@ -42,7 +42,7 @@ const HEADLESS_PARAGRAPH = [
     '  write the finished plan as your final message in markdown.',
 ].join('\n');
 export function buildPlanModeBlock(options) {
-    const { interactive } = options;
+    const { interactive, governAddendum } = options;
     // NO ROUND COUNT APPEARS HERE, and none may be reintroduced: the number used
     // to be substituted from `planModeMaxAskRounds`, which meant the prompt itself
     // told the model it would run out. "3-5 questions" was also wrong against a
@@ -95,6 +95,7 @@ export function buildPlanModeBlock(options) {
         '- Never invent a path. Cite files you have read.',
         ...verdictRule,
         interactive ? SUPERSEDE_PARAGRAPH : HEADLESS_PARAGRAPH,
+        ...(interactive && governAddendum ? ['', governAddendum] : []),
         '</plan_mode>',
     ].join('\n');
 }

package/dist/agent/reducer.d.ts

@@ -21,9 +21,11 @@ import type { JobKind, ServiceSnapshot, ServiceStatus } from '../proc/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
 import type { TaskSummaryView } from '../fast/task-summary-types.js';
+import type { GovernanceCardData, GovernanceSnapshot } from '../governance/types.js';
+import type { Posture } from '../governance/posture.js';
 export type NoticeLevel = 'info' | 'warn' | 'error';
 export type ToastLevel = NoticeLevel | 'success';
-export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit' | 'prompts' | 'prompt-pick' | 'agents'
+export type Overlay = null | 'settings' | 'model' | 'help' | 'queue' | 'confirm' | 'question' | 'plan' | 'kit' | 'prompts' | 'prompt-pick' | 'agents' | 'governance'
 /**
  * tui-shortcut-drawer-and-task-summary §4.5: the keyboard drawer (`Ctrl+G` /
  * `/keys`). A single field, so the drawer and `/help` cannot both hold the
@@ -140,6 +142,11 @@ export type Entry = {
     kind: 'notice';
     level: NoticeLevel;
     text: string;
+} | {
+    id: string;
+    kind: 'governance';
+    at: number;
+    card: GovernanceCardData;
 } | {
     id: string;
     kind: 'team';
@@ -372,6 +379,20 @@ export interface ViewState {
     agentMode: AgentMode;
     /** Set only by a DEFERRED `plan -> build`; drives the `PLAN -> BUILD` readout. */
     pendingAgentMode: AgentMode | null;
+    /**
+     * The user-visible posture and its deferred twin (governance-mode 4.3). Written in the
+     * SAME dispatch as `agentMode` / `pendingAgentMode` and only from what the controller
+     * adopted, so the badge and the gate cannot diverge. `agentMode` keeps gating.
+     */
+    posture: Posture;
+    pendingPosture: Posture | null;
+    /**
+     * The live governed-run snapshot, or `null` when there is no run.
+     *
+     * NEVER PERSISTED, like `team`: `/save` writes `entries` (the settlement cards are the
+     * history) and a resumed session has no live run to show.
+     */
+    governance: GovernanceSnapshot | null;
     /**
      * The live team roster, or `null` when no dispatch is running.
      *
@@ -622,6 +643,17 @@ export type ViewAction = {
     type: 'setAgentMode';
     mode: AgentMode;
     pending: AgentMode | null;
+    posture?: Posture;
+    pendingPosture?: Posture | null;
+} | {
+    type: 'govSnapshot';
+    snapshot: GovernanceSnapshot;
+} | {
+    type: 'govEnd';
+} | {
+    type: 'governanceCard';
+    card: GovernanceCardData;
+    at?: number;
 } | {
     type: 'teamStart';
     dispatchId: string;

package/dist/agent/reducer.js

@@ -15,6 +15,8 @@ import { reconcileSteeringReceipt } from './queued-messages.js';
 import { emptyContextUsage } from '../compaction/meter.js';
 import { addUsage, computeCost } from './usage.js';
 import { ENTRY_LIMITS, appendBounded, entryRetain, trimEntries } from './entry-limits.js';
+import { isGovernedDispatch } from '../governance/governed-dispatch.js';
+import { adoptPosture, foldGovernanceSnapshot } from './governance-view.js';
 /** Default auto-dismiss window for a toast. */
 export const DEFAULT_TOAST_TTL_MS = 2500;
 /**
@@ -62,6 +64,9 @@ export function initialViewState(seed = {}) {
         // `controller.getAgentMode()` so `--plan` renders on the first frame.
         agentMode: 'build',
         pendingAgentMode: null,
+        posture: 'build',
+        pendingPosture: null,
+        governance: null,
         team: null,
         todos: null,
         retry: null,
@@ -904,6 +909,9 @@ export function viewReducer(state, action) {
                 // those three.
                 status: 'idle',
                 team: null,
+                // The live run snapshot goes with the conversation it was shown in (the run itself
+                // survives on disk and announces itself again on its next event).
+                governance: null,
                 fastEntryId: undefined,
                 turnProduced: false,
                 errorNoticed: false,
@@ -931,7 +939,24 @@ export function viewReducer(state, action) {
         // `controller.setAgentMode()` reported it ADOPTED, so this reducer has no
         // deferral logic of its own to get out of step with (§3.1 / R-P7).
         case 'setAgentMode':
-            return { ...state, agentMode: action.mode, pendingAgentMode: action.pending };
+            return {
+                ...state,
+                agentMode: action.mode,
+                pendingAgentMode: action.pending,
+                ...adoptPosture(state.posture, action),
+            };
+        // --- Governance (governance-mode 14.4) -------------------------------------
+        case 'govSnapshot': {
+            const governance = foldGovernanceSnapshot(state.governance, action.snapshot);
+            return governance === state.governance ? state : { ...state, governance };
+        }
+        case 'govEnd':
+            return state.governance === null ? state : { ...state, governance: null };
+        case 'governanceCard': {
+            const { id, seq } = nextId(state);
+            const entry = { id, kind: 'governance', at: action.at ?? Date.now(), card: action.card };
+            return { ...state, seq, ...appendEntry(state, state.entries, entry) };
+        }
         case 'toggleThinking':
             return { ...state, thinkingVisible: !state.thinkingVisible };
         case 'pushToast': {
@@ -976,19 +1001,26 @@ export function viewReducer(state, action) {
                 aborted: false,
                 active: true,
             };
+            const team = {
+                dispatchId: action.dispatchId,
+                active: true,
+                runs,
+                requested: action.requested,
+                startedAt: Date.now(),
+                messageCount: 0,
+            };
+            // A GOVERNED DISPATCH LEAVES NO TRANSCRIPT CARD (RV-3): a run is 10-20 dispatches,
+            // and a `TeamCard` for each would bury the conversation. The live snapshot is still
+            // written - the legion panel and `/agents` read it - and with no `teamEntryId`,
+            // `teamUpdate` / `teamEnd` already pass `entries` through untouched.
+            if (isGovernedDispatch(action.specs))
+                return { ...state, team };
             return {
                 ...state,
                 seq,
                 ...appendEntry(state, state.entries, entry),
                 teamEntryId: id,
-                team: {
-                    dispatchId: action.dispatchId,
-                    active: true,
-                    runs,
-                    requested: action.requested,
-                    startedAt: Date.now(),
-                    messageCount: 0,
-                },
+                team,
             };
         }
         case 'teamUpdate': {
@@ -1476,6 +1508,10 @@ export function viewReducer(state, action) {
                 // restored entries BEFORE this branch runs.
                 taskSummary: null,
                 taskSummaryPending: false,
+                // Same rule for a live governed run: `/resume` adopts another conversation, and
+                // a snapshot of the old one's run must not be drawn over it. Settlement cards
+                // arrive with the restored `entries`.
+                governance: null,
             };
         }
         // --- Background services (§3.10 / D-11) -----------------------------

package/dist/agent/system-prompt.d.ts

@@ -159,6 +159,25 @@ export interface SystemPromptParams {
      * own appended instructions still come last and still win.
      */
     structuredResultBlock?: string;
+    /**
+     * The rendered `<governance_mode>` block (the Orchestrator's rules), or `''`
+     * (governance-mode 6.1). Spliced AFTER the plan block and BEFORE `teamBlock`, and
+     * conditional like every block above: governance off produces the pre-feature prompt
+     * BYTE FOR BYTE. The caller omits `teamBlock` / `forcedTeamBlock` in GOVERN with gate
+     * mode `build`, because `task` is refused there and advertising it would describe a
+     * refused capability.
+     */
+    governBlock?: string;
+    /**
+     * The rendered `<governance_role>` block of a governed CHILD, or `''`. Spliced after
+     * `subagentBlock`. Never set together with `governBlock`.
+     */
+    governanceRoleBlock?: string;
+    /**
+     * PLAN+GOVERN's interview addendum (governance-mode 6.3), placed inside `<plan_mode>`.
+     * Only read when `agentMode` is `'plan'`; absent leaves the plan block unchanged.
+     */
+    governAddendum?: string;
 }
 /** Describe the active shell so the model does not emit incompatible syntax. */
 export declare function describeShell(): {

package/dist/agent/system-prompt.js

@@ -33,7 +33,10 @@ export function buildSystemPrompt(params) {
     const skillsBlock = params.skillsBlock ?? '';
     const hasSkills = skillsBlock.length > 0;
     const planBlock = params.agentMode === 'plan'
-        ? buildPlanModeBlock({ interactive: params.planInteractive !== false })
+        ? buildPlanModeBlock({
+            interactive: params.planInteractive !== false,
+            ...(params.governAddendum ? { governAddendum: params.governAddendum } : {}),
+        })
         : '';
     // `''` when the caller has no candidates or the feature is off — which is what
     // keeps this block's absence byte-identical to the pre-feature prompt (I-T1).
@@ -41,6 +44,8 @@ export function buildSystemPrompt(params) {
     const teamBlock = params.teamBlock ?? '';
     const forcedTeamBlock = params.forcedTeamBlock ?? '';
     const subagentBlock = params.subagentBlock ?? '';
+    const governBlock = params.governBlock ?? '';
+    const governanceRoleBlock = params.governanceRoleBlock ?? '';
     const todoBlock = params.todoBlock ?? '';
     const fastBlock = params.fastBlock ?? '';
     const backgroundBlock = params.backgroundBlock ?? '';
@@ -66,12 +71,15 @@ export function buildSystemPrompt(params) {
         // (whose step 1 defers to it). Conditional like every other optional block.
         ...(skillTriageBlock ? ['', skillTriageBlock] : []),
         ...(planBlock ? ['', planBlock] : []),
+        // AFTER the plan block it extends and BEFORE `<team_mode>` (governance-mode 6.1).
+        ...(governBlock ? ['', governBlock] : []),
         ...(teamBlock ? ['', teamBlock] : []),
         // IMMEDIATELY AFTER `<team_mode>`: "can" then "must". BEFORE the subagent
         // block, because a child reading an order to dispatch would be ordered to use
         // a tool it does not have (§3.6).
         ...(forcedTeamBlock ? ['', forcedTeamBlock] : []),
         ...(subagentBlock ? ['', subagentBlock] : []),
+        ...(governanceRoleBlock ? ['', governanceRoleBlock] : []),
         ...(todoBlock ? ['', todoBlock] : []),
         ...(fastBlock ? ['', fastBlock] : []),
         ...(backgroundBlock ? ['', backgroundBlock] : []),

package/dist/cli.js

@@ -25,7 +25,8 @@ import { formatMigrationNotice, migrateLegacyState } from './config/migrate-lega
 import { formatHomeMigrationNotice, migrateToHome } from './config/migrate-home.js';
 import { migrateStateOutOfConfig } from './config/migrate-state-out-of-config.js';
 import { runHistoryCommand } from './config/history-commands.js';
-import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, JOBS_CONFIG_SET_KEYS, TASK_SUMMARY_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyJobsConfigSet, applyTaskSummaryConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
+import { checkGovernanceCommandLine } from './config/governance-launch.js';
+import { COMPACTION_CONFIG_SET_KEYS, FAST_CONFIG_SET_KEYS, LOG_CONFIG_SET_KEYS, RETRY_CONFIG_SET_KEYS, TEAM_CONFIG_SET_KEYS, GOVERNANCE_CONFIG_SET_KEYS, JOBS_CONFIG_SET_KEYS, TASK_SUMMARY_CONFIG_SET_KEYS, UPDATE_CONFIG_SET_KEYS, applyCompactionConfigSet, applyFastConfigSet, applyLogConfigSet, applyRetryConfigSet, applyTeamConfigSet, applyGovernanceConfigSet, applyJobsConfigSet, applyTaskSummaryConfigSet, applyUpdateConfigSet, runConfigEdit, runConfigGet, runConfigHome, runConfigList, warnIfRedactionDisabled, } from './config/cli-commands.js';
 import { attachAgentEvents, attachTeamEvents, installLogging, setScreenRestore, setSignalTerminator, } from './logging/install.js';
 import { getLogger } from './logging/logger.js';
 import { runLogsCommand } from './logging/cli-commands.js';
@@ -230,6 +231,12 @@ function toFlags(opts) {
         // reports nothing, does nothing, and leaves compaction armed.
         compaction: opts.compaction,
         compactionThreshold: opts.compactionThreshold,
+        // Site three of three for the governance flags. `--no-governance` is declared alone, so
+        // commander defaults `opts.governance` to `true` when it is absent; only an explicit
+        // `false` is forwarded, which keeps silence from reading as an override.
+        govern: opts.govern,
+        planGovern: opts.planGovern,
+        governance: opts.governance === false ? false : undefined,
         // Site three of three for `--resume` / `--save` -- ELEVEN features, one trap
         // (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4, retry, fast, update,
         // compaction, now session identity). A flag needs the `.option()`
@@ -1599,6 +1606,11 @@ const CONFIG_SET_KEYS = new Set([
     // membership set accepts a write that never happens - the two halves the static
     // guard in `config.test.ts` exists to pair up.
     ...TASK_SUMMARY_CONFIG_SET_KEYS,
+    // `governance.*` keys are handled by `applyGovernanceConfigSet`, same reasoning again
+    // (governance-mode 11.1): without this line they fall through to `Unknown config key`,
+    // and without the matching case in `runConfigSet` the membership set accepts a write
+    // that never happens.
+    ...GOVERNANCE_CONFIG_SET_KEYS,
 ]);
 /**
  * `aragon config set maxTokens <n|auto|default>`.
@@ -1771,6 +1783,15 @@ function runConfigSetValue(key, value) {
         process.stdout.write(`Set ${key} = ${String(merged.taskSummary[field])}\n`);
         return;
     }
+    const governancePatch = applyGovernanceConfigSet(key, value);
+    if (governancePatch) {
+        // Echoed from the STORED value, like every section above: `config set
+        // governance.maxRework 9` prints 5, which is what the read path will report.
+        const merged = updatePersistedConfig(governancePatch);
+        const field = key.slice('governance.'.length);
+        process.stdout.write(`Set ${key} = ${String(merged.governance[field])}\n`);
+        return;
+    }
     const patch = {};
     switch (key) {
         case 'provider':
@@ -2188,6 +2209,13 @@ function buildProgram() {
         .option('--compaction', 'Compact the conversation when the context window fills (the default)')
         .option('--no-compaction', 'Never compact; a full context window ends the run as before')
         .option('--compaction-threshold <n>', 'Occupancy that triggers compaction for this run: 0.9 or 90% (0.5-0.95)')
+        // Governance mode (governance-mode 11.2). `--govern` and `--plan-govern` only pick the
+        // starting posture, so neither is a persisted pair. `--no-governance` is deliberately
+        // negative-only: it can only ever switch the feature off, and `toFlags` forwards it only
+        // when explicitly given. The rules between them live in `validateGovernanceLaunch`.
+        .option('--govern', 'Start in GOVERN posture (a governed team of dev / review / test roles)')
+        .option('--plan-govern', 'Start in PLAN+GOVERN posture (clarify and plan first, then govern)')
+        .option('--no-governance', 'Disable governance mode for this launch (not persisted)')
         .option('--no-skills', 'Disable the skill system entirely (no catalog, no skill tools)')
         .option('--skill <name>', 'Force-load a skill at Level 2 for this run (repeatable)', (value, previous = []) => [...previous, value])
         .option('--skills-yes', 'Approve skill installs for this run (CI / headless)')
@@ -2251,6 +2279,22 @@ function buildProgram() {
         }
         void runInteractive(flags, { initialPrompt: prompt });
     });
+    // The governance flag rules (governance-mode 11.2), checked for EVERY command because the
+    // flags are root-level options and `exec` reads them through `toFlags(program.opts())`.
+    // A `preAction` hook runs before the root action as well as before each subcommand, so one
+    // place covers `aragon -p`, piped input and `aragon exec`.
+    program.hook('preAction', (root, action) => {
+        const check = checkGovernanceCommandLine(root.opts(), {
+            commandName: action.name(),
+            isRootAction: action === root,
+            stdinIsTty: !!process.stdin.isTTY,
+            stdoutIsTty: !!process.stdout.isTTY,
+        });
+        if (check.ok)
+            return;
+        process.stderr.write(`${check.message}\n`);
+        process.exit(2);
+    });
     // aragon config [set <key> <value> | path]
     const configCmd = program
         .command('config')

package/dist/commands/builtins.js

@@ -15,7 +15,9 @@ import { mergePendingEntries } from '../agent/queued-messages.js';
 import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
 import { buildContinuationMessage } from '../todo/follow-through.js';
 import { planIsResolved } from '../todo/acceptance.js';
-import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { nextMode } from '../agent/agent-mode.js';
+import { POSTURE_LABEL } from '../governance/posture.js';
+import { registerGovernanceCommand } from './governance-command.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { applyRestoredSession } from '../session/startup-session.js';
 import { runSessionCommand } from './session-command.js';
@@ -353,12 +355,13 @@ const COMMANDS = [
         run: (ctx) => {
             const arg = ctx.args.trim().toLowerCase();
             if (arg === 'status') {
-                const s = ctx.controller.getPlanStatus();
-                const pending = s.pending ? ` (pending ${MODE_LABEL[s.pending]} after this run)` : '';
+                // The full posture (GOVERN / PLAN+GOVERN included), not just the gate mode.
+                const s = ctx.controller.getPostureState();
+                const pending = s.pending ? ` (pending ${POSTURE_LABEL[s.pending]} after this run)` : '';
                 // NO ROUND COUNT. The old line ended with `Ask rounds used: 3/4.`, which
                 // told the user their agent was rationing questions - a limit that no
                 // longer exists. Nothing replaced it: "0 of unlimited" is noise.
-                ctx.notify('info', `Mode: ${MODE_LABEL[s.effective]}${pending}.`);
+                ctx.notify('info', `Mode: ${POSTURE_LABEL[s.effective]}${pending}.`);
                 return;
             }
             if (arg.length > 0 && arg !== 'on' && arg !== 'off') {
@@ -1346,6 +1349,9 @@ export function registerBuiltinCommands(registry) {
     // now live in the settings screen, and this command is the ACT: arm forced mode
     // and start work. Unconditional, for the reason `/subagent` above records.
     registerTeamCommand(registry);
+    // `/gov` (governance-mode 11.3). Unconditional, like `/team` and for the same reason: the
+    // session where governance cannot run is exactly where a user asks the command why.
+    registerGovernanceCommand(registry);
     // The keyboard drawer (`Ctrl+G` / `/keys`) and the task label (`/task`). Two
     // registrations, no new mechanism: `/keys` sets the panel's pre-filter and opens
     // the same overlay `Ctrl+G` opens, and `/task` reports what the header cell says.

package/dist/commands/governance-command.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `/gov`: enter, leave and inspect governance mode (governance-mode 11.3).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE GUARD ORDER IS A CONTRACT, and it is the order `/team` uses (and for the same
+ * reasons), not an alphabetical one:
+ *
+ *   status / help / runs / report / board
+ *                                 - questions, answerable in ANY session, including the
+ *                                   ones where governance cannot run (that is where users
+ *                                   ask why). `report` only READS files already on disk.
+ *   off                           - leaving is always possible, even mid-stage.
+ *   available?                    - `on` / `plan` / `resume` / `pause` name the exact reason.
+ *   not busy                      - half a team dispatch under one posture and half under
+ *                                   another leaves a result nothing can explain.
+ *   act                           - switch posture / submit the resume turn / abort.
+ *
+ * `pause` sits BETWEEN `available?` and `not busy` and never takes the busy refusal: a stage
+ * running is exactly when someone wants to pause, and the request is cooperative (nothing is
+ * stopped), unlike `abort`.
+ *
+ * EVERY POSTURE CHANGE BELOW IS FOLLOWED BY A NOTICE OR TOAST IN THE SAME BRANCH: a
+ * posture change produces no `AgentEvent`, so without one the badge would wait for an
+ * unrelated state change to repaint (the lesson of team-command-forced-dispatch P1-6).
+ */
+import type { CommandContext, CommandRegistry } from './registry.js';
+/** The fixed English turn that makes the orchestrator call `gov_run resume` (11.3). */
+export declare function resumeTurnText(runId: string): string;
+/** `500`, `500k`, `2m`, `off`/`0`. NaN when unparseable. */
+export declare function parseBudgetTokens(raw: string): number;
+/** The command body; `registerGovernanceCommand` is the only registration site. */
+export declare function runGovernanceCommand(ctx: CommandContext): Promise<void>;
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export declare function registerGovernanceCommand(registry: CommandRegistry): void;