@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/commands/governance-command.js

@@ -0,0 +1,292 @@
+/**
+ * `/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 { GOV_ABORTED_NOTICE, GOV_BUDGET_OFF_NOTICE, GOV_BUDGET_USAGE, GOV_COMMAND_SUMMARY, GOV_NO_RUN_NOTICE, GOV_NO_RUNS_NOTICE, GOV_NO_STAGE_NOTICE, GOV_OFF_NOTICE, GOV_OFF_WITH_RUN_NOTICE, GOV_PAUSE_ALREADY_NOTICE, GOV_PAUSE_CANCELLED_TOAST, GOV_PAUSE_ESCALATED_NOTICE, GOV_PAUSE_NONE_PENDING_NOTICE, GOV_PAUSE_NO_RUN_NOTICE, GOV_REPORT_NO_RUN_NOTICE, GOV_STAGE_BUSY_NOTICE, buildGovHelpText, formatGovStatus, govBudgetSetNotice, govPausePendingToast, govPausedNowToast, govReportBadIdNotice, govReportMissingNotice, govUnavailableNotice, posturePendingToast, postureAppliedToast, stageRunningToast, RESTART_REQUIRED_TEXT, } from '../governance/copy.js';
+import { RUN_ID_PATTERN } from '../governance/limits.js';
+import { isGovernancePosture } from '../governance/posture.js';
+import { formatReportNotice, formatRunsTable } from './governance-runs-table.js';
+const USAGE = 'Usage: /gov [status|on|plan|off|board|runs|report [runId]|resume [runId]|pause [cancel]' +
+    '|abort|budget <n|off>|help]';
+/** The fixed English turn that makes the orchestrator call `gov_run resume` (11.3). */
+export function resumeTurnText(runId) {
+    return `Resume governance run ${runId}.`;
+}
+function unavailableText(ctx) {
+    const availability = ctx.controller.isGovernanceAvailable();
+    if (availability.ok)
+        return null;
+    return availability.reason === 'restart_required'
+        ? RESTART_REQUIRED_TEXT
+        : govUnavailableNotice(availability.reason);
+}
+function reportStatus(ctx) {
+    const snapshot = ctx.controller.getGovernanceSnapshot();
+    ctx.notify('info', formatGovStatus({
+        posture: ctx.controller.getPosture(),
+        availability: ctx.controller.isGovernanceAvailable(),
+        run: snapshot
+            ? {
+                runId: snapshot.runId,
+                phase: snapshot.phase,
+                phaseCount: snapshot.phaseCount,
+                stage: snapshot.stage,
+                status: snapshot.status,
+                health: snapshot.health,
+                pauseRequested: snapshot.pauseRequested === true,
+            }
+            : null,
+        dispatchPlan: snapshot ? ctx.controller.getGovernanceDispatchPlan() : null,
+    }));
+}
+async function reportRuns(ctx) {
+    const runs = await ctx.controller.listGovernanceRuns();
+    if (runs.length === 0) {
+        ctx.notify('info', GOV_NO_RUNS_NOTICE);
+        return;
+    }
+    // Two columns less than the terminal: the transcript indents notices.
+    ctx.notify('info', formatRunsTable(runs, (process.stdout.columns ?? 80) - 2));
+}
+/** `/gov report [runId]`: a stored report as one transcript notice (read-only). */
+async function report(ctx) {
+    const raw = ctx.args.trim().split(/\s+/)[1] ?? '';
+    // Checked HERE as well as in the reader: a malformed id never reaches the controller,
+    // let alone the file system (it would become a path segment).
+    if (raw !== '' && !RUN_ID_PATTERN.test(raw)) {
+        ctx.notify('warn', govReportBadIdNotice(raw));
+        return;
+    }
+    const result = await ctx.controller.readGovernanceReport(raw === '' ? undefined : raw);
+    switch (result.kind) {
+        case 'ok':
+            ctx.notify('info', formatReportNotice(result));
+            return;
+        case 'missing':
+            ctx.notify('info', govReportMissingNotice(result.runId));
+            return;
+        case 'bad_id':
+            ctx.notify('warn', govReportBadIdNotice(raw));
+            return;
+        case 'no_run':
+            ctx.notify('info', GOV_REPORT_NO_RUN_NOTICE);
+    }
+}
+/** `/gov pause [cancel]`: stop at the next clean stage boundary; nothing is killed. */
+async function pause(ctx) {
+    const unavailable = unavailableText(ctx);
+    if (unavailable !== null) {
+        ctx.notify('warn', unavailable);
+        return;
+    }
+    const arg = (ctx.args.trim().split(/\s+/)[1] ?? '').toLowerCase();
+    if (arg === 'cancel') {
+        if (ctx.controller.cancelGovernancePause())
+            ctx.toast('info', GOV_PAUSE_CANCELLED_TOAST);
+        else
+            ctx.notify('info', GOV_PAUSE_NONE_PENDING_NOTICE);
+        return;
+    }
+    if (arg !== '') {
+        ctx.notify('warn', `Unknown argument "${arg}". Usage: /gov pause [cancel]`);
+        return;
+    }
+    const outcome = await ctx.controller.requestGovernancePause();
+    const snapshot = ctx.controller.getGovernanceSnapshot();
+    switch (outcome) {
+        case 'pending':
+            ctx.toast('info', govPausePendingToast(snapshot?.stage ?? null));
+            return;
+        case 'paused_now':
+            ctx.toast('info', govPausedNowToast(snapshot?.runId ?? ''));
+            return;
+        case 'already_paused':
+            ctx.notify('info', GOV_PAUSE_ALREADY_NOTICE);
+            return;
+        case 'escalated':
+            ctx.notify('info', GOV_PAUSE_ESCALATED_NOTICE);
+            return;
+        case 'no_run':
+            ctx.notify('info', GOV_PAUSE_NO_RUN_NOTICE);
+    }
+}
+/** Switch posture through the App's single write path and report what was ADOPTED. */
+function switchPosture(ctx, target) {
+    if (ctx.applyPosture === undefined) {
+        ctx.notify('warn', 'Governance is unavailable here: this surface cannot change posture.');
+        return null;
+    }
+    const applied = ctx.applyPosture(target);
+    if (applied.pending !== null) {
+        ctx.toast('info', ctx.controller.isGovernanceStageRunning()
+            ? stageRunningToast(applied.pending)
+            : posturePendingToast(applied.pending));
+    }
+    else {
+        ctx.toast('info', postureAppliedToast(applied.effective));
+    }
+    return applied;
+}
+function leave(ctx) {
+    const wasGoverned = isGovernancePosture(ctx.controller.getPosture());
+    const snapshot = ctx.controller.getGovernanceSnapshot();
+    if (!wasGoverned && ctx.controller.getPostureState().pending === null) {
+        ctx.notify('info', GOV_OFF_NOTICE);
+        return;
+    }
+    const applied = switchPosture(ctx, 'build');
+    // A deferred change (a stage is running) already said so in its toast.
+    if (applied === null || applied.pending !== null)
+        return;
+    // Leaving never kills an in-flight stage; the run is left resumable.
+    const hasRun = snapshot !== null && snapshot.status !== 'closed' && snapshot.status !== 'abandoned';
+    ctx.notify('info', hasRun ? GOV_OFF_WITH_RUN_NOTICE : GOV_OFF_NOTICE);
+}
+function enter(ctx, target) {
+    const unavailable = unavailableText(ctx);
+    if (unavailable !== null) {
+        ctx.notify('warn', unavailable);
+        return;
+    }
+    if (ctx.controller.isTeamBusy()) {
+        ctx.notify('warn', ctx.controller.isGovernanceStageRunning()
+            ? GOV_STAGE_BUSY_NOTICE
+            : 'Cannot change posture while a team dispatch is running.');
+        return;
+    }
+    switchPosture(ctx, target);
+}
+async function resume(ctx) {
+    const unavailable = unavailableText(ctx);
+    if (unavailable !== null) {
+        ctx.notify('warn', unavailable);
+        return;
+    }
+    if (ctx.controller.isTeamBusy()) {
+        ctx.notify('warn', GOV_STAGE_BUSY_NOTICE);
+        return;
+    }
+    const requested = ctx.args.trim().split(/\s+/)[1] ?? '';
+    const runId = await ctx.controller.findResumableGovernanceRun(requested);
+    if (runId === null) {
+        ctx.notify('info', GOV_NO_RUN_NOTICE);
+        return;
+    }
+    if (ctx.controller.getPosture() !== 'govern' && switchPosture(ctx, 'govern') === null)
+        return;
+    // `userInitiated: false` keeps the canned turn out of the prompt history, exactly like
+    // `/todo continue` (todo-plan-followthrough C-12).
+    ctx.submit(resumeTurnText(runId), { userInitiated: false });
+}
+function abort(ctx) {
+    if (!ctx.controller.isGovernanceStageRunning()) {
+        ctx.notify('info', GOV_NO_STAGE_NOTICE);
+        return;
+    }
+    ctx.controller.abortGovernanceStage();
+    ctx.notify('info', GOV_ABORTED_NOTICE);
+}
+/** `500`, `500k`, `2m`, `off`/`0`. NaN when unparseable. */
+export function parseBudgetTokens(raw) {
+    const text = raw.trim().toLowerCase();
+    if (text === 'off' || text === '0')
+        return 0;
+    const match = /^(\d+(?:\.\d+)?)([km]?)$/.exec(text);
+    if (!match)
+        return Number.NaN;
+    const scale = match[2] === 'm' ? 1_000_000 : match[2] === 'k' ? 1_000 : 1;
+    return Math.floor(Number(match[1]) * scale);
+}
+function setBudget(ctx) {
+    const raw = ctx.args.trim().split(/\s+/)[1];
+    if (raw === undefined) {
+        ctx.notify('info', GOV_BUDGET_USAGE);
+        return;
+    }
+    const tokens = parseBudgetTokens(raw);
+    if (!Number.isFinite(tokens) || tokens < 0) {
+        ctx.notify('warn', GOV_BUDGET_USAGE);
+        return;
+    }
+    // BOTH CALLS, AND NEITHER MAY BE DROPPED (the `/fast` rule): the setter makes the running
+    // session honour it and re-renders the prompt; persisting alone changes nothing until
+    // relaunch, and the setter alone is forgotten by morning.
+    const adopted = ctx.controller.setGovernanceConfig({ budgetTokens: tokens });
+    ctx.persistConfig({ governance: adopted });
+    ctx.notify('info', adopted.budgetTokens === 0 ? GOV_BUDGET_OFF_NOTICE : govBudgetSetNotice(adopted.budgetTokens));
+}
+/** The command body; `registerGovernanceCommand` is the only registration site. */
+export async function runGovernanceCommand(ctx) {
+    const verb = (ctx.args.trim().split(/\s+/)[0] ?? '').toLowerCase();
+    switch (verb) {
+        case '':
+        case 'status':
+            reportStatus(ctx);
+            return;
+        case 'help':
+            ctx.notify('info', buildGovHelpText(ctx.controller.getGovernanceConfig().minAskRounds));
+            return;
+        case 'runs':
+            await reportRuns(ctx);
+            return;
+        case 'report':
+            await report(ctx);
+            return;
+        case 'board':
+            ctx.setOverlay('governance');
+            return;
+        case 'off':
+            leave(ctx);
+            return;
+        case 'on':
+            enter(ctx, 'govern');
+            return;
+        case 'plan':
+            enter(ctx, 'plan_govern');
+            return;
+        case 'resume':
+            await resume(ctx);
+            return;
+        case 'pause':
+            await pause(ctx);
+            return;
+        case 'abort':
+            abort(ctx);
+            return;
+        case 'budget':
+            setBudget(ctx);
+            return;
+        default:
+            ctx.notify('warn', `Unknown argument "${verb}". ${USAGE}`);
+    }
+}
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export function registerGovernanceCommand(registry) {
+    registry.register({
+        name: 'gov',
+        description: GOV_COMMAND_SUMMARY,
+        run: (ctx) => runGovernanceCommand(ctx),
+    });
+}

package/dist/commands/governance-runs-table.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `/gov runs` table and the `/gov report` notice text (governance-mode-v1-1 7.1, 7.2).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. Everything this module
+ * ADDS is ASCII (column rules, the `...` cut mark, `n/a`); the only non-ASCII that can pass
+ * through is the user's own goal text, which is measured and cut in terminal CELLS
+ * (`ui/layout/cells.ts`), never in code units, so a CJK goal cannot push a row past the edge.
+ *
+ * PURE. The command hands in rows and a width; nothing here reads the terminal or the clock
+ * except through arguments, which is what lets the width matrix be tested.
+ *
+ * THE COLUMNS DEGRADE BY WIDTH, in the order of how much each one is missed: first
+ * HEALTH and COST go (they are the cheapest to look up again in `/gov board`), then UPDATED
+ * and TOKENS, and at the narrowest only `RUN STATUS PHASE GOAL` remain. The goal gets
+ * whatever is left and is cut with `...`.
+ */
+import type { GovernanceRunRow } from '../agent/governance-wiring.js';
+interface Column {
+    key: 'run' | 'status' | 'phase' | 'health' | 'tokens' | 'cost' | 'updated' | 'updatedShort';
+    title: string;
+    width: number;
+}
+/** `184k`, `2.1M`, `950`. */
+export declare function formatTokensCompact(tokens: number): string;
+/** `$1.42`; unknown pricing is `n/a`, never `$0.00` (v1 8.5 / C-11). */
+export declare function formatCostCell(costUsd: number | null): string;
+/** `2026-10-24 14:02` in local time. */
+export declare function formatStamp(ms: number): string;
+/** One row of the table, already cut to `cols` cells. */
+export declare function formatRunRow(row: GovernanceRunRow, keys: ReadonlyArray<Column['key']>, cols: number): string;
+/** The whole `/gov runs` notice for `cols` terminal columns. */
+export declare function formatRunsTable(runs: readonly GovernanceRunRow[], cols: number): string;
+/** The transcript text for a found report: header, body capped by lines, full path. */
+export declare function formatReportNotice(input: {
+    runId: string;
+    file: string;
+    text: string;
+    path: string;
+}): string;
+export {};

package/dist/commands/governance-runs-table.js

@@ -0,0 +1,130 @@
+/**
+ * The `/gov runs` table and the `/gov report` notice text (governance-mode-v1-1 7.1, 7.2).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. Everything this module
+ * ADDS is ASCII (column rules, the `...` cut mark, `n/a`); the only non-ASCII that can pass
+ * through is the user's own goal text, which is measured and cut in terminal CELLS
+ * (`ui/layout/cells.ts`), never in code units, so a CJK goal cannot push a row past the edge.
+ *
+ * PURE. The command hands in rows and a width; nothing here reads the terminal or the clock
+ * except through arguments, which is what lets the width matrix be tested.
+ *
+ * THE COLUMNS DEGRADE BY WIDTH, in the order of how much each one is missed: first
+ * HEALTH and COST go (they are the cheapest to look up again in `/gov board`), then UPDATED
+ * and TOKENS, and at the narrowest only `RUN STATUS PHASE GOAL` remain. The goal gets
+ * whatever is left and is cut with `...`.
+ */
+import { GOV_REPORT_MAX_LINES } from '../governance/copy.js';
+import { cellWidth, fitCells, padCells } from '../ui/layout/cells.js';
+const UNFINISHED = new Set(['executing', 'paused', 'escalated']);
+const MIN_GOAL_CELLS = 8;
+const GAP = '  ';
+const COLUMNS = {
+    run: { key: 'run', title: 'RUN', width: 13 },
+    status: { key: 'status', title: 'STATUS', width: 9 },
+    phase: { key: 'phase', title: 'PHASE', width: 5 },
+    health: { key: 'health', title: 'HEALTH', width: 6 },
+    tokens: { key: 'tokens', title: 'TOKENS', width: 7 },
+    cost: { key: 'cost', title: 'COST', width: 8 },
+    updated: { key: 'updated', title: 'UPDATED', width: 16 },
+    // The same column without the year, for widths where the goal text is worth more.
+    updatedShort: { key: 'updatedShort', title: 'UPDATED', width: 11 },
+};
+/** Column sets from widest to narrowest; the first whose goal still gets room wins. */
+const TIERS = [
+    ['run', 'status', 'phase', 'health', 'tokens', 'cost', 'updated'],
+    ['run', 'status', 'phase', 'tokens', 'updatedShort'],
+    ['run', 'status', 'phase', 'tokens'],
+    ['run', 'status', 'phase'],
+];
+/** `184k`, `2.1M`, `950`. */
+export function formatTokensCompact(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(1)}M`;
+    if (tokens >= 10_000)
+        return `${Math.round(tokens / 1_000)}k`;
+    if (tokens >= 1_000)
+        return `${(tokens / 1_000).toFixed(1)}k`;
+    return String(Math.max(0, Math.round(tokens)));
+}
+/** `$1.42`; unknown pricing is `n/a`, never `$0.00` (v1 8.5 / C-11). */
+export function formatCostCell(costUsd) {
+    if (costUsd === null)
+        return 'n/a';
+    return costUsd < 0.01 && costUsd > 0 ? '<$0.01' : `$${costUsd.toFixed(2)}`;
+}
+function two(n) {
+    return String(n).padStart(2, '0');
+}
+/** `2026-10-24 14:02` in local time. */
+export function formatStamp(ms) {
+    const d = new Date(ms);
+    if (Number.isNaN(d.getTime()))
+        return '-';
+    const date = `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+    return `${date} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+function cellFor(key, row, digest) {
+    switch (key) {
+        case 'run':
+            return row.runId;
+        case 'status':
+            return row.status;
+        case 'phase':
+            return digest === undefined ? '-' : `${digest.phase}/${digest.phaseCount}`;
+        case 'health':
+            return digest?.health == null ? '-' : String(digest.health);
+        case 'tokens':
+            return digest === undefined ? '-' : formatTokensCompact(digest.tokens);
+        case 'cost':
+            return digest === undefined ? '-' : formatCostCell(digest.costUsd);
+        case 'updated':
+            return formatStamp(row.updatedAt);
+        case 'updatedShort': {
+            const stamp = formatStamp(row.updatedAt);
+            return stamp === '-' ? stamp : stamp.slice(5);
+        }
+    }
+}
+function prefixWidth(keys) {
+    const widths = keys.reduce((sum, key) => sum + COLUMNS[key].width, 0);
+    return 2 + widths + GAP.length * keys.length;
+}
+function pickTier(cols) {
+    const last = TIERS[TIERS.length - 1];
+    return (TIERS.find((keys) => cols - prefixWidth(keys) - 2 >= MIN_GOAL_CELLS + 4) ?? last);
+}
+/** One row of the table, already cut to `cols` cells. */
+export function formatRunRow(row, keys, cols) {
+    const cells = keys.map((key) => padCells(cellFor(key, row, row.digest), COLUMNS[key].width));
+    const star = UNFINISHED.has(row.status) ? ' *' : '';
+    const goalRoom = cols - prefixWidth(keys) - star.length;
+    const goal = goalRoom >= 4 ? fitCells(row.goal.replace(/\s+/g, ' '), goalRoom) : '';
+    const line = `  ${cells.join(GAP)}${GAP}${goal}${star}`.trimEnd();
+    return cellWidth(line) <= cols ? line : fitCells(line, cols);
+}
+/** The whole `/gov runs` notice for `cols` terminal columns. */
+export function formatRunsTable(runs, cols) {
+    const width = Number.isFinite(cols) ? Math.max(20, Math.floor(cols)) : 80;
+    const keys = pickTier(width);
+    const header = `  ${keys.map((k) => padCells(COLUMNS[k].title, COLUMNS[k].width)).join(GAP)}`;
+    const lines = ['Governed runs (newest first):', header.trimEnd()];
+    for (const run of runs)
+        lines.push(formatRunRow(run, keys, width));
+    if (runs.some((run) => UNFINISHED.has(run.status))) {
+        lines.push('* unfinished: /gov resume <runId>');
+    }
+    return lines.join('\n');
+}
+/** The transcript text for a found report: header, body capped by lines, full path. */
+export function formatReportNotice(input) {
+    const body = input.text.replace(/\r\n/g, '\n').trimEnd().split('\n');
+    const shown = body.slice(0, GOV_REPORT_MAX_LINES);
+    const more = body.length - shown.length;
+    return [
+        `Report for run ${input.runId} (${input.file}):`,
+        ...shown,
+        ...(more > 0 ? [`... (${more} more lines; see the file below)`] : []),
+        `Full file: ${input.path}`,
+    ].join('\n');
+}

package/dist/commands/registry.d.ts

@@ -6,6 +6,7 @@ import type { SubmitMessageOptions } from '../agent/prompt-options.js';
 import type { CopyRequest, CopyRequestResult } from '../ui/clipboard-task.js';
 import type { AgentController } from '../agent/controller.js';
 import type { AgentMode } from '../agent/agent-mode.js';
+import type { Posture } from '../governance/posture.js';
 import type { Entry, NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } from '../agent/reducer.js';
 import type { PersistedConfig } from '../config/schema.js';
 import type { FollowThroughBudget } from '../todo/follow-through.js';
@@ -92,6 +93,17 @@ export interface CommandContext {
         effective: AgentMode;
         pending: AgentMode | null;
     };
+    /**
+     * The same single write path, widened to the four postures (governance-mode 4.2).
+     * OPTIONAL so the many fixtures that build this context by literal need no change; the
+     * App always supplies it, and `/gov` reports "unavailable" when it is absent.
+     */
+    applyPosture?: (next: Posture, opts?: {
+        force?: boolean;
+    }) => {
+        effective: Posture;
+        pending: Posture | null;
+    };
     /**
      * Mouse capture, for `/mouse` (tui-selection-and-scroll-follow §6.2 / G3).
      *

package/dist/config/app-paths.d.ts

@@ -151,6 +151,16 @@ export declare function getSessionsDir(): string;
  * a per-process run id and why retention is two-tier (§3.5.2 / RV-6).
  */
 export declare function getCompactionArchiveDir(): string;
+/**
+ * `<home>/governance` - governance-mode run records (governance-mode 11.1 / 12.1).
+ *
+ * ITS OWN ROOT, for the reason `getCompactionArchiveDir` above records: `logs/`, `sessions/`
+ * and `skills/` are scan roots, and every extra directory inside one is another thing each
+ * walk has to recognise and skip. Derived from the same `resolution.root`, so the
+ * `ARAGON_HOME` / VITEST isolation contract at the top of this file covers it too.
+ * The caller creates it (0700 on POSIX); this function only names it.
+ */
+export declare function getGovernanceDir(): string;
 /** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */
 export declare function getUserDataDir(): string;
 export declare function getUserSkillsDir(): string;

package/dist/config/app-paths.js

@@ -242,6 +242,18 @@ export function getSessionsDir() {
 export function getCompactionArchiveDir() {
     return join(resolution.root, 'compaction');
 }
+/**
+ * `<home>/governance` - governance-mode run records (governance-mode 11.1 / 12.1).
+ *
+ * ITS OWN ROOT, for the reason `getCompactionArchiveDir` above records: `logs/`, `sessions/`
+ * and `skills/` are scan roots, and every extra directory inside one is another thing each
+ * walk has to recognise and skip. Derived from the same `resolution.root`, so the
+ * `ARAGON_HOME` / VITEST isolation contract at the top of this file covers it too.
+ * The caller creates it (0700 on POSIX); this function only names it.
+ */
+export function getGovernanceDir() {
+    return join(resolution.root, 'governance');
+}
 /** `<home>` — parent of `skills/`, and where sidecar state such as usage lives. */
 export function getUserDataDir() {
     return resolution.root;

package/dist/config/cli-commands.d.ts

@@ -96,6 +96,11 @@ export declare const UPDATE_CONFIG_SET_KEYS: readonly ["update.mode", "update.ch
  * persisted-off-survives-a-flagless-run check — runs exactly that command.
  */
 export declare const COMPACTION_CONFIG_SET_KEYS: readonly ["compaction.enabled", "compaction.threshold", "compaction.warnThreshold", "compaction.keepRecentTurns", "compaction.useFastTier", "compaction.onFailure", "compaction.subagents", "compaction.archive"];
+/**
+ * Config keys under `governance.` that `aragon config set` accepts (governance-mode 11.1).
+ * Every key is writable and ONE level deep, so `runConfigGet`'s single-dot split resolves it.
+ */
+export declare const GOVERNANCE_CONFIG_SET_KEYS: readonly ["governance.enabled", "governance.shiftTab", "governance.panel", "governance.profile", "governance.maxWorkPackages", "governance.maxPhases", "governance.maxRework", "governance.maxFixCycles", "governance.minAskRounds", "governance.budgetTokens", "governance.confirmCharter"];
 /**
  * Translate a `log.*` dotted key into a patch, or `null` for anything else.
  *
@@ -131,6 +136,19 @@ export declare function applyJobsConfigSet(key: string, value: string): Partial<
  * rather than silently mean `false`.
  */
 export declare function applyTaskSummaryConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
+/**
+ * Translate a `governance.*` dotted key into a patch, or `null` for anything else.
+ *
+ * EVERY KEY ROUTES THROUGH `clampGovernanceConfig`, so `config set governance.maxRework 9`
+ * stores 5 (the engine's `hardMaxRework`) and the caller echoes the STORED value. The string
+ * is turned into a number HERE, because the clamp deliberately repairs a string to the
+ * default (a hand-edited `"2"` has no defensible reading); an unparseable argument becomes
+ * `NaN`, which the clamp repairs to the default - the "typo changes nothing" rule.
+ *
+ * The patch is a PARTIAL section, safe only because `updatePersistedConfig` deep-merges
+ * `governance` (the ninth time that trap is recorded in `store.ts`).
+ */
+export declare function applyGovernanceConfigSet(key: string, value: string): Partial<PersistedConfig> | null;
 /**
  * Translate a `team.*` dotted key into a patch, or `null` for anything else.
  *

package/dist/config/cli-commands.js

@@ -14,7 +14,7 @@ import { getConfigBackupPath, getConfigPath, getHomeRoot, getLogsDir, getPromptH
 import { getHomeMigrationBreadcrumbPath } from './migrate-home.js';
 import { loadPersistedConfig, updatePersistedConfig } from './store.js';
 import { normalizeModelProfiles, validateModelProfiles } from './model-profiles.js';
-import { clampFastConfig, clampRetryConfig, clampCompactionConfig, clampTeamConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_CONFIG, DEFAULT_UPDATE_CONFIG, DEFAULT_JOBS_CONFIG, clampJobsConfig, } from './schema.js';
+import { clampFastConfig, clampRetryConfig, clampCompactionConfig, clampTeamConfig, parseThresholdInput, clampUpdateConfig, coercePositiveInt, maskSecret, DEFAULT_FAST_CONFIG, DEFAULT_RETRY_CONFIG, DEFAULT_TEAM_CONFIG, DEFAULT_COMPACTION_CONFIG, DEFAULT_UPDATE_CONFIG, DEFAULT_JOBS_CONFIG, clampJobsConfig, clampGovernanceConfig, DEFAULT_GOVERNANCE_CONFIG, } from './schema.js';
 import { clampLogLevel } from '../logging/levels.js';
 /** Config keys under `log.` that `aragon config set` accepts. */
 export const LOG_CONFIG_SET_KEYS = [
@@ -167,6 +167,23 @@ export const COMPACTION_CONFIG_SET_KEYS = [
     'compaction.subagents',
     'compaction.archive',
 ];
+/**
+ * Config keys under `governance.` that `aragon config set` accepts (governance-mode 11.1).
+ * Every key is writable and ONE level deep, so `runConfigGet`'s single-dot split resolves it.
+ */
+export const GOVERNANCE_CONFIG_SET_KEYS = [
+    'governance.enabled',
+    'governance.shiftTab',
+    'governance.panel',
+    'governance.profile',
+    'governance.maxWorkPackages',
+    'governance.maxPhases',
+    'governance.maxRework',
+    'governance.maxFixCycles',
+    'governance.minAskRounds',
+    'governance.budgetTokens',
+    'governance.confirmCharter',
+];
 function isTrue(value) {
     return value === 'true' || value === '1';
 }
@@ -255,6 +272,35 @@ export function applyTaskSummaryConfigSet(key, value) {
             return null;
     }
 }
+/**
+ * Translate a `governance.*` dotted key into a patch, or `null` for anything else.
+ *
+ * EVERY KEY ROUTES THROUGH `clampGovernanceConfig`, so `config set governance.maxRework 9`
+ * stores 5 (the engine's `hardMaxRework`) and the caller echoes the STORED value. The string
+ * is turned into a number HERE, because the clamp deliberately repairs a string to the
+ * default (a hand-edited `"2"` has no defensible reading); an unparseable argument becomes
+ * `NaN`, which the clamp repairs to the default - the "typo changes nothing" rule.
+ *
+ * The patch is a PARTIAL section, safe only because `updatePersistedConfig` deep-merges
+ * `governance` (the ninth time that trap is recorded in `store.ts`).
+ */
+export function applyGovernanceConfigSet(key, value) {
+    if (!GOVERNANCE_CONFIG_SET_KEYS.includes(key))
+        return null;
+    const field = key.slice('governance.'.length);
+    const typed = parseGovernanceArgument(field, value);
+    const clamped = clampGovernanceConfig({ ...DEFAULT_GOVERNANCE_CONFIG, [field]: typed });
+    return { governance: { [field]: clamped[field] } };
+}
+function parseGovernanceArgument(field, value) {
+    const kind = typeof DEFAULT_GOVERNANCE_CONFIG[field];
+    const trimmed = value.trim();
+    if (kind === 'boolean')
+        return isTrue(trimmed);
+    if (kind === 'number')
+        return trimmed === '' ? Number.NaN : Number(trimmed);
+    return trimmed;
+}
 /**
  * Translate a `team.*` dotted key into a patch, or `null` for anything else.
  *

package/dist/config/env.d.ts

@@ -21,7 +21,8 @@
  *     ARAGON_COMPACTION_ARCHIVE,
  *     ARAGON_JOBS_ENABLED, ARAGON_JOBS_WAIT_SECONDS, ARAGON_JOBS_STALL_SECONDS,
  *     ARAGON_JOBS_PERSIST_LOG, ARAGON_JOBS_NOTICE_STEER,
- *     ARAGON_PROMPTS (the quick-prompt library's `enabled` switch, and only that).
+ *     ARAGON_PROMPTS (the quick-prompt library's `enabled` switch, and only that),
+ *     ARAGON_GOVERNANCE (a KILL switch: `0` disables governance mode, nothing enables it).
  *
  * READ ELSEWHERE, ON PURPOSE: `ARAGON_UPDATE_REGISTRY` and `npm_config_registry`
  * are resolved by `update/registry.ts::resolveRegistryUrl`, NOT here, because