@aragon-agent/cli 0.6.44 → 0.6.46

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).
      *
@@ -189,6 +201,13 @@ export interface CommandContext {
      * TYPE-ONLY import, for the reason the `branch` note above records.
      */
     taskSummary?: TaskSummaryCommandPort;
+    /**
+     * Whether transcript invocation cards are on (tui-invocation-cards section 3.6).
+     * `false` only under `ARAGON_NO_INVOCATION_CARDS=1`; commands then fall back to the
+     * pre-card notices and submit without `invocation`. Absent (every fixture built by
+     * literal) means ON.
+     */
+    invocationCards?: boolean;
 }
 /**
  * What `/keys` and `/task` may do.
@@ -228,6 +247,12 @@ export interface SlashCommand {
     aliases?: string[];
     description: string;
     run: (ctx: CommandContext) => void | Promise<void>;
+    /**
+     * True when running with these args will submit a message that renders as an invocation
+     * card, so the `Command:` echo would only repeat it. MUST be the same predicate the
+     * command itself branches on (I-8); absent means false.
+     */
+    rendersInvocationCard?: (args: string) => boolean;
 }
 export declare class CommandRegistry {
     private readonly byName;
@@ -235,6 +260,16 @@ export declare class CommandRegistry {
     get(name: string): SlashCommand | undefined;
     all(): SlashCommand[];
 }
+/**
+ * Split raw composer input into a command word and its trimmed args; `null` when the
+ * input is not a slash command (no leading `/`, or the `//` literal-slash escape).
+ * `runSlashInput` and the App's echo suppression both go through here so they cannot
+ * disagree about what counts as a command.
+ */
+export declare function parseSlashInput(input: string): {
+    name: string;
+    args: string;
+} | null;
 /**
  * Try to run a slash command from raw input. Returns `true` if the input was a
  * (known or unknown) slash command and was consumed; `false` if it is a normal

package/dist/commands/registry.js

@@ -19,21 +19,34 @@ export class CommandRegistry {
     }
 }
 /**
- * Try to run a slash command from raw input. Returns `true` if the input was a
- * (known or unknown) slash command and was consumed; `false` if it is a normal
- * message that should go to the agent.
+ * Split raw composer input into a command word and its trimmed args; `null` when the
+ * input is not a slash command (no leading `/`, or the `//` literal-slash escape).
+ * `runSlashInput` and the App's echo suppression both go through here so they cannot
+ * disagree about what counts as a command.
  */
-export async function runSlashInput(registry, input, makeCtx) {
+export function parseSlashInput(input) {
     const trimmed = input.trimStart();
     if (!trimmed.startsWith('/'))
-        return false;
-    // `//...` escapes a literal leading slash — not a command.
+        return null;
+    // `//...` escapes a literal leading slash - not a command.
     if (trimmed.startsWith('//'))
-        return false;
+        return null;
     const withoutSlash = trimmed.slice(1);
     const spaceIdx = withoutSlash.search(/\s/);
     const name = spaceIdx === -1 ? withoutSlash : withoutSlash.slice(0, spaceIdx);
     const args = spaceIdx === -1 ? '' : withoutSlash.slice(spaceIdx + 1).trim();
+    return { name, args };
+}
+/**
+ * Try to run a slash command from raw input. Returns `true` if the input was a
+ * (known or unknown) slash command and was consumed; `false` if it is a normal
+ * message that should go to the agent.
+ */
+export async function runSlashInput(registry, input, makeCtx) {
+    const parsed = parseSlashInput(input);
+    if (parsed === null)
+        return false;
+    const { name, args } = parsed;
     const command = registry.get(name);
     const ctx = makeCtx(args);
     if (!command) {

package/dist/commands/skills.js

@@ -16,6 +16,7 @@ import { SKILL_TRIAGE_LIMITS } from '../skills/triage.js';
 import { HOST_TOOL_NAMES, SKILL_TOOL_FLOOR } from '../tools/index.js';
 import { SKILLS_TOOL_POLICY_MODES, isSkillsToolPolicyMode } from '../config/schema.js';
 import { pickGlyphs } from '../ui/glyphs.js';
+import { INDEX_SKILL_NAME, isIndexBuildArgs } from './index-build.js';
 function marksFor(ctx) {
     const cfg = ctx.controller.getConfig();
     const glyphs = pickGlyphs({ colorLevel: cfg.colorLevel ?? 0, unicode: cfg.unicode ?? false });
@@ -673,10 +674,37 @@ export function registerSkillCommands(registry, service) {
         }
     }
 }
+/**
+ * The card's raw material for one skill run (tui-invocation-cards section 3.3). The
+ * command line always uses the namespaced `/skill:<name>` form - the stable handle -
+ * even when the user typed the bare name. Ctrl+I's machine-written sentence is NOT the
+ * user's input (RV-3): the card says `ctrl+i` and shows no input row.
+ */
+function skillCardInput(record, args, sent) {
+    const machine = record.name === INDEX_SKILL_NAME && isIndexBuildArgs(args);
+    const version = record.frontmatter.version;
+    const facts = [
+        ...(machine ? ['ctrl+i'] : []),
+        ...(version ? [`v${version}`] : []),
+        record.scope,
+        `${sent.kb} KB`,
+        ...(sent.files > 0 ? [`${sent.files} files`] : []),
+        ...(sent.policy ? ['tool ceiling'] : []),
+    ];
+    const typed = machine ? '' : args;
+    return {
+        variant: 'skill',
+        name: record.name,
+        commandLine: typed === '' ? `/skill:${record.name}` : `/skill:${record.name} ${typed}`,
+        input: typed,
+        facts,
+    };
+}
 function makeSkillCommand(record, service) {
     return {
         name: record.name,
         description: shortDescription(record),
+        rendersInvocationCard: () => true,
         run: (ctx) => {
             let loaded;
             try {
@@ -703,8 +731,14 @@ function makeSkillCommand(record, service) {
             // The SUBMITTED size, not the file's. Reporting 480 KB while sending 30 KB
             // is how a user concludes the truncation marker is a rendering glitch.
             const kb = Math.max(1, Math.round(Buffer.byteLength(message, 'utf-8') / 1024));
-            ctx.notify('info', `Skill "${record.name}" loaded (${kb} KB submitted, ${loaded.files.length} bundled files).`);
-            ctx.submit(message);
+            if (ctx.invocationCards === false) {
+                ctx.notify('info', `Skill "${record.name}" loaded (${kb} KB submitted, ${loaded.files.length} bundled files).`);
+                ctx.submit(message);
+                return;
+            }
+            ctx.submit(message, {
+                invocation: skillCardInput(record, ctx.args, { kb, files: loaded.files.length, policy: !!policy }),
+            });
         },
     };
 }

package/dist/commands/subagent-command.js

@@ -17,7 +17,7 @@
  * file therefore holds ONE delegation and one line of deprecation text, and
  * `subagent-command.test.ts` asserts both (I-8).
  */
-import { runTeamCommand } from './team-command.js';
+import { runTeamCommand, teamRendersInvocationCard } from './team-command.js';
 /**
  * Run `/team`, having first said out loud that this is the same thing.
  *
@@ -33,6 +33,8 @@ export function runSubagentCommand(ctx) {
 export function registerSubagentCommand(registry) {
     registry.register({
         name: 'subagent',
+        // A fresh object inherits nothing from `/team`: reference the SAME predicate (RV-5).
+        rendersInvocationCard: teamRendersInvocationCard,
         description: 'Deprecated alias of /team - same arguments',
         run: (ctx) => { runSubagentCommand(ctx); },
     });

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

@@ -43,6 +43,12 @@
  * `Team 4` chip would wait for an unrelated state change before appearing.
  */
 import type { CommandContext, CommandRegistry } from './registry.js';
+/**
+ * Whether `/team <args>` ends in a card. The SAME function the command branches on
+ * (`readTeamIntent`), and shared by `/team` and the `/subagent` alias by reference: the
+ * alias builds a fresh object and inherits nothing (RV-5, I-8).
+ */
+export declare function teamRendersInvocationCard(args: string): boolean;
 /** The command body; `registerTeamCommand` is the only registration site. */
 export declare function runTeamCommand(ctx: CommandContext): void;
 /** Registered from `builtins.ts` with one line, next to every other subsystem. */

package/dist/commands/team-command.js

@@ -43,7 +43,7 @@
  * `Team 4` chip would wait for an unrelated state change before appearing.
  */
 import { buildForcedDirective } from '../team/forced-dispatch.js';
-import { DEFAULT_FORCED_COUNT, planForced, planNotice, readTeamIntent, } from '../team/forced-mode.js';
+import { DEFAULT_FORCED_COUNT, forcedCardNote, planForced, planNotice, readTeamIntent, } from '../team/forced-mode.js';
 import { subagentModelSummary } from '../ui/overlays/model-profile-state.js';
 /**
  * The subagent model line, phrased by the same authority the settings root row
@@ -199,6 +199,34 @@ function enterForcedMode(ctx) {
     ctx.notify('info', `Forced team mode on: ${adopted} subagents per turn. `
         + 'Your next message dispatches.');
 }
+/**
+ * The card's raw material for `/team <brief>` (tui-invocation-cards section 3.3). The
+ * command line is always spelled `/team`, even when the user came in through the
+ * deprecated `/subagent` alias: the card names the canonical command.
+ */
+function forcedCardInput(args, planned, note, ctx) {
+    const noun = planned.count === 1 ? 'subagent' : 'subagents';
+    const facts = [
+        planned.parts.length > 0 ? `parts ${planned.parts.join(', ')}` : `${planned.count} ${noun}`,
+        ...(planned.readOnly ? ['read-only'] : []),
+        ...(ctx.controller.getAgentMode() === 'plan' ? ['plan mode'] : []),
+    ];
+    return {
+        variant: 'team',
+        commandLine: args === '' ? '/team' : `/team ${args}`,
+        input: planned.brief,
+        facts,
+        ...(note !== undefined ? { note } : {}),
+    };
+}
+/**
+ * Whether `/team <args>` ends in a card. The SAME function the command branches on
+ * (`readTeamIntent`), and shared by `/team` and the `/subagent` alias by reference: the
+ * alias builds a fresh object and inherits nothing (RV-5, I-8).
+ */
+export function teamRendersInvocationCard(args) {
+    return readTeamIntent(args).kind === 'brief';
+}
 /** `/team [-n n|--parts a,b] [--read-only] <brief>`: arm and submit in one act. */
 function armAndSubmit(ctx, intent) {
     const team = ctx.controller.getTeamConfig();
@@ -209,7 +237,11 @@ function armAndSubmit(ctx, intent) {
     // directive names: the later turns reuse this count, so the first turn and the
     // rest of the session cannot disagree about how wide the fan-out is (D-7).
     ctx.controller.armForcedTeam(planned.count);
-    ctx.notify('info', planNotice(planned, team));
+    // With cards on, the disclosure rides on the card (`forcedCardNote`, same source as
+    // `planNotice`); with them off this is the pre-card notice, byte for byte.
+    const cards = ctx.invocationCards !== false;
+    if (!cards)
+        ctx.notify('info', planNotice(planned, team));
     const directive = buildForcedDirective({
         brief: planned.brief,
         count: planned.count,
@@ -222,7 +254,11 @@ function armAndSubmit(ctx, intent) {
     });
     // `userInitiated: false`: a directive the user did not type belongs in neither
     // the prompt history nor the hint-fade counter (todo-plan-followthrough C-12).
-    ctx.submit(directive, { userInitiated: false });
+    const note = forcedCardNote(planned, team);
+    ctx.submit(directive, {
+        userInitiated: false,
+        ...(cards ? { invocation: forcedCardInput(ctx.args, planned, note, ctx) } : {}),
+    });
 }
 /** The command body; `registerTeamCommand` is the only registration site. */
 export function runTeamCommand(ctx) {
@@ -253,6 +289,7 @@ export function runTeamCommand(ctx) {
 export function registerTeamCommand(registry) {
     registry.register({
         name: 'team',
+        rendersInvocationCard: teamRendersInvocationCard,
         description: 'Force team mode and start now: /team <brief>; /team [on|off|status]',
         run: (ctx) => { runTeamCommand(ctx); },
     });

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

package/dist/config/env.js

@@ -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
@@ -41,6 +42,7 @@ import process from 'node:process';
 import dotenv from 'dotenv';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
 import { clampLogLevel } from '../logging/levels.js';
+import { isGovernanceEnvDisabled } from './governance-config.js';
 import { clampContextWindow, clampMaxTokens, clampTheme, clampThinkingLevel, isAutoToken, parseThresholdInput, } from './schema.js';
 /**
  * Load a project `.env` from the given directory into `process.env` (existing
@@ -318,6 +320,13 @@ export function readEnvConfig() {
             enabled: prompts === '1' || prompts === 'true' || prompts === 'on' || prompts === 'yes',
         };
     }
+    // ARAGON_GOVERNANCE=0 is the governance-mode KILL switch (governance-mode 11.1): it can only
+    // switch `enabled` OFF, and it outranks the config file (the layers merge file < env). It is
+    // deliberately not a toggle - `ARAGON_GOVERNANCE=1` writes nothing, so an environment can
+    // never re-enable what the user's config or `--no-governance` turned off.
+    if (isGovernanceEnvDisabled(process.env)) {
+        partial.governance = { enabled: false };
+    }
     // ARAGON_TASK_SUMMARY is the header label's kill switch
     // (tui-shortcut-drawer-and-task-summary §4.8 / P2-7), and it maps `enabled` and
     // NOTHING ELSE - the same wording and the same reason as the block above. A

package/dist/config/governance-config.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Governance-mode configuration (governance-mode sections 11.1 / 13.2).
+ *
+ * LIVES IN ITS OWN FILE, NOT IN `schema.ts`: that file is far past the repo's
+ * 1000-line limit, and a section whose clamp depends on nothing else in it has no
+ * reason to grow it. `schema.ts` imports and re-exports everything below, so every
+ * importer still reaches the section through `config/schema.js`.
+ *
+ * SELF-CONTAINED ON PURPOSE. The integer/boolean helpers in `schema.ts` are private,
+ * and importing back from it would make a cycle (`schema.ts` re-exports this file).
+ * The two helpers here are four lines each.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+import type { Posture } from '../governance/posture.js';
+import { type ProfileId } from '../governance/types.js';
+export interface GovernanceConfig {
+    /** `false` => the feature is absent: no tools, no prompt blocks, no posture. */
+    enabled: boolean;
+    /** `false` => Shift+Tab stays BUILD<->PLAN; `/gov` still works. */
+    shiftTab: boolean;
+    /** `false` => the status chip only, no legion panel. */
+    panel: boolean;
+    /** Domain profile that names the roles' focus areas. */
+    profile: ProfileId;
+    /** 1..8. Work packages per run. */
+    maxWorkPackages: number;
+    /** 1..6. Phases per run. */
+    maxPhases: number;
+    /** 1..5. Rework rounds per work package. */
+    maxRework: number;
+    /** 1..5. Fix cycles per phase. */
+    maxFixCycles: number;
+    /** 0..5. Question rounds before PLAN+GOVERN may submit a plan. */
+    minAskRounds: number;
+    /** 0..1_000_000_000. Token budget per run; `0` = unlimited. */
+    budgetTokens: number;
+    /** `true` => the user approves the run charter before any dispatch. */
+    confirmCharter: boolean;
+}
+export declare const DEFAULT_GOVERNANCE_CONFIG: GovernanceConfig;
+type NumericKey = 'maxWorkPackages' | 'maxPhases' | 'maxRework' | 'maxFixCycles' | 'minAskRounds' | 'budgetTokens';
+/** The numeric keys, in display order; shared with the settings and `config` surfaces. */
+export declare const GOVERNANCE_NUMERIC_KEYS: readonly NumericKey[];
+/** The inclusive range a numeric key is clamped to. */
+export declare function governanceRangeOf(key: NumericKey): {
+    min: number;
+    max: number;
+};
+/**
+ * THE single gate for every governance-config read AND write, mirroring
+ * `clampTeamConfig` for the reason that one records: hardening only the read path
+ * leaves a bad value on disk that the read path then rewrites on every launch, which
+ * presents to the user as "my setting won't stick". Unknown keys are dropped.
+ */
+export declare function clampGovernanceConfig(raw: unknown): GovernanceConfig;
+/**
+ * `ARAGON_GOVERNANCE=0` is a KILL switch, not a toggle: it can only disable. Any other
+ * value (including `1`) is ignored, so an environment can never switch a feature ON that
+ * the user's config or a `--no-governance` flag turned off.
+ *
+ * Takes the env as a parameter so tests and `doctor` do not touch `process.env`.
+ */
+export declare function isGovernanceEnvDisabled(env?: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * The config-level reasons governance can be unavailable. A SUBSET of the
+ * `GovernanceUnavailableReason` vocabulary in `governance/copy.ts` (the controller adds
+ * `no_api_key`, `headless`, `restart_required` at runtime); the codes are spelled
+ * identically so the integration can unify the two without renaming anything.
+ */
+export type GovernanceConfigUnavailableReason = 'disabled_config' | 'disabled_env' | 'team_off';
+export type GovernanceConfigAvailability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: GovernanceConfigUnavailableReason;
+};
+/**
+ * Config-only availability, in precedence order: the environment kill switch first (it is
+ * the strongest), then the config key, then the team dependency. Pure: no I/O.
+ */
+export declare function describeGovernanceConfigAvailability(config: {
+    governance?: Pick<GovernanceConfig, 'enabled'>;
+    team: {
+        enabled: boolean;
+    };
+}, env?: Readonly<Record<string, string | undefined>>): GovernanceConfigAvailability;
+/**
+ * Merge the `governance` section across the layers (defaults > file > env > flag).
+ *
+ * The environment and `--no-governance` layers can ONLY switch `enabled` off (they are kill
+ * switches), and they are applied last so nothing in the file can outvote them. The flag is a
+ * launch-only override: it is resolved here into the in-memory config and never reaches the
+ * store, which is what "not persisted" means.
+ */
+export declare function resolveGovernanceConfig(layers: {
+    file?: unknown;
+    env?: unknown;
+    disableForLaunch?: boolean;
+}): GovernanceConfig;
+export interface InitialPostureInput {
+    /** `--govern`. */
+    govern?: boolean;
+    /** `--plan-govern`. Wins over `govern` if a programmatic caller passes both. */
+    planGovern?: boolean;
+    /** The already-resolved `--plan` / `planModeDefault` result (unchanged by governance). */
+    startInPlanMode: boolean;
+    governance: Pick<GovernanceConfig, 'enabled'>;
+    teamEnabled: boolean;
+}
+export interface InitialPostureResolution {
+    posture: Posture;
+    /** Set when a governance posture was requested but could not be honoured. */
+    degradedReason?: GovernanceConfigUnavailableReason;
+}
+/**
+ * The posture the session starts in. Governance flags win over `--plan` / `planModeDefault`
+ * (a user who asked for a governed run did not ask for a plain one); when governance is
+ * unavailable at the CONFIG level the request degrades to the classic posture the same launch
+ * would have had, and the reason is returned so the caller can say so instead of silently
+ * dropping the flag. Without a governance flag this is exactly `startInPlanMode ? 'plan' :
+ * 'build'`, so `--plan` behaviour is untouched.
+ */
+export declare function resolveInitialPosture(input: InitialPostureInput, env?: Readonly<Record<string, string | undefined>>): InitialPostureResolution;
+export {};