@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/config/governance-config.js

@@ -0,0 +1,164 @@
+/**
+ * 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 process from 'node:process';
+import { GOV_LIMITS } from '../governance/limits.js';
+import { PROFILE_IDS } from '../governance/types.js';
+export const DEFAULT_GOVERNANCE_CONFIG = {
+    enabled: true,
+    shiftTab: true,
+    panel: true,
+    profile: 'general',
+    maxWorkPackages: 4,
+    maxPhases: 3,
+    maxRework: 3,
+    maxFixCycles: 3,
+    minAskRounds: 2,
+    budgetTokens: 0,
+    confirmCharter: false,
+};
+/**
+ * Inclusive range per numeric key. The upper bounds of the four structural keys are
+ * `GOV_LIMITS.hardMax*` (NOT repeated here), so the clamp and the engine can never
+ * disagree: a hand-edited `config.json` cannot exceed what the engine enforces.
+ */
+const NUMERIC_RANGES = {
+    maxWorkPackages: { min: 1, max: GOV_LIMITS.hardMaxWorkPackages },
+    maxPhases: { min: 1, max: GOV_LIMITS.hardMaxPhases },
+    maxRework: { min: 1, max: GOV_LIMITS.hardMaxRework },
+    maxFixCycles: { min: 1, max: GOV_LIMITS.hardMaxFixCycles },
+    minAskRounds: { min: 0, max: 5 },
+    budgetTokens: { min: 0, max: 1_000_000_000 },
+};
+/** The numeric keys, in display order; shared with the settings and `config` surfaces. */
+export const GOVERNANCE_NUMERIC_KEYS = Object.keys(NUMERIC_RANGES);
+/** The inclusive range a numeric key is clamped to. */
+export function governanceRangeOf(key) {
+    return NUMERIC_RANGES[key];
+}
+/**
+ * Only a real, finite INTEGER survives. A float, NaN, a string ("2") or null is
+ * REPAIRED TO THE DEFAULT, not rounded or coerced: a hand-edited `maxRework: 2.5` has no
+ * defensible reading, and "typo changes nothing" is the discipline every sibling clamp
+ * follows. Out-of-range integers are clamped, not rejected.
+ */
+function clampRangedInt(value, key) {
+    const range = NUMERIC_RANGES[key];
+    const fallback = DEFAULT_GOVERNANCE_CONFIG[key];
+    if (typeof value !== 'number' || !Number.isInteger(value))
+        return fallback;
+    return Math.min(range.max, Math.max(range.min, value));
+}
+function pickBool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+function pickProfile(value) {
+    return typeof value === 'string' && PROFILE_IDS.includes(value)
+        ? value
+        : DEFAULT_GOVERNANCE_CONFIG.profile;
+}
+/**
+ * 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 function clampGovernanceConfig(raw) {
+    const src = (raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {});
+    const defaults = DEFAULT_GOVERNANCE_CONFIG;
+    return {
+        enabled: pickBool(src.enabled, defaults.enabled),
+        shiftTab: pickBool(src.shiftTab, defaults.shiftTab),
+        panel: pickBool(src.panel, defaults.panel),
+        profile: pickProfile(src.profile),
+        maxWorkPackages: clampRangedInt(src.maxWorkPackages, 'maxWorkPackages'),
+        maxPhases: clampRangedInt(src.maxPhases, 'maxPhases'),
+        maxRework: clampRangedInt(src.maxRework, 'maxRework'),
+        maxFixCycles: clampRangedInt(src.maxFixCycles, 'maxFixCycles'),
+        minAskRounds: clampRangedInt(src.minAskRounds, 'minAskRounds'),
+        budgetTokens: clampRangedInt(src.budgetTokens, 'budgetTokens'),
+        confirmCharter: pickBool(src.confirmCharter, defaults.confirmCharter),
+    };
+}
+// ---------------------------------------------------------------------------
+// Environment kill switch + availability (config-level part)
+// ---------------------------------------------------------------------------
+/** The spellings of "off" the kill switch accepts, matching the other ARAGON_* switches. */
+const ENV_OFF_VALUES = new Set(['0', 'false', 'off', 'no']);
+/**
+ * `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 function isGovernanceEnvDisabled(env = process.env) {
+    const value = env.ARAGON_GOVERNANCE?.trim().toLowerCase();
+    return value !== undefined && ENV_OFF_VALUES.has(value);
+}
+/**
+ * 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 function describeGovernanceConfigAvailability(config, env = process.env) {
+    if (isGovernanceEnvDisabled(env))
+        return { ok: false, reason: 'disabled_env' };
+    if (config.governance?.enabled === false)
+        return { ok: false, reason: 'disabled_config' };
+    if (!config.team.enabled)
+        return { ok: false, reason: 'team_off' };
+    return { ok: true };
+}
+// ---------------------------------------------------------------------------
+// Launch resolution (load.ts calls these; kept here so load.ts barely grows)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function resolveGovernanceConfig(layers) {
+    return clampGovernanceConfig({
+        ...DEFAULT_GOVERNANCE_CONFIG,
+        ...(isPlainObject(layers.file) ? layers.file : {}),
+        ...(isPlainObject(layers.env) ? layers.env : {}),
+        ...(layers.disableForLaunch === true ? { enabled: false } : {}),
+    });
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * 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 function resolveInitialPosture(input, env = process.env) {
+    const classic = input.startInPlanMode ? 'plan' : 'build';
+    const requested = input.planGovern === true
+        ? 'plan_govern'
+        : input.govern === true ? 'govern' : null;
+    if (requested === null)
+        return { posture: classic };
+    const availability = describeGovernanceConfigAvailability({ governance: input.governance, team: { enabled: input.teamEnabled } }, env);
+    return availability.ok
+        ? { posture: requested }
+        : { posture: classic, degradedReason: availability.reason };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Command-line validation for the governance flags (governance-mode 11.2).
+ *
+ * PURE, AND OUT OF `cli.tsx` ON PURPOSE: that file is far past the size limit, and these four
+ * rules are exactly the kind that regress silently (a missing one lets `-p --govern` start a
+ * run that can never reach a human). `cli.tsx` only gathers the facts and prints the message.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+export interface GovernanceLaunchInput {
+    /** `--govern`. */
+    govern?: boolean;
+    /** `--plan-govern`. */
+    planGovern?: boolean;
+    /** `--plan` (`true` only when passed; `--no-plan` and silence are both falsy here). */
+    plan?: boolean;
+    /** `--no-team`. */
+    noTeam?: boolean;
+    /** `--no-governance`. */
+    noGovernance?: boolean;
+    /**
+     * The run cannot reach a human: `-p/--print`, the `exec` subcommand, piped stdin or a
+     * non-TTY stdout. Governance needs `ask_user` and the review overlays, which headless
+     * runs deny wholesale.
+     */
+    headless: boolean;
+}
+export type GovernanceLaunchCheck = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+export declare const GOVERNANCE_EXCLUSIVE_MESSAGE = "--govern, --plan-govern and --plan are mutually exclusive. Pass only one of them.";
+export declare const GOVERNANCE_HEADLESS_MESSAGE: string;
+export declare const GOVERNANCE_NO_TEAM_MESSAGE: string;
+export declare const GOVERNANCE_NO_GOVERNANCE_MESSAGE: string;
+/**
+ * The first violated rule, or `{ ok: true }`. ORDER IS THE CONTRACT: the exclusivity error
+ * is the one a user typing three flags needs to see first, and the headless rule outranks
+ * `--no-team` because it is the one that cannot be fixed by dropping a second flag.
+ * Nothing is checked unless a governance posture was actually requested.
+ */
+export declare function validateGovernanceLaunch(input: GovernanceLaunchInput): GovernanceLaunchCheck;
+/** The root-level options the rules read, as commander materialises them. */
+export interface GovernanceRootOptions {
+    govern?: boolean;
+    planGovern?: boolean;
+    plan?: boolean;
+    /** `--team` / `--no-team`: only an explicit `false` is a refusal. */
+    team?: boolean;
+    /** `--no-governance` is declared alone, so this is `true` when absent and `false` when given. */
+    governance?: boolean;
+    print?: boolean;
+}
+export interface GovernanceCommandContext {
+    /** The command about to run: `exec`, `config`, or the root command's own name. */
+    commandName: string;
+    /** `true` for the root command's own action (the TUI / `-p` entry), not a subcommand. */
+    isRootAction: boolean;
+    stdinIsTty: boolean;
+    stdoutIsTty: boolean;
+}
+/**
+ * The `preAction` hook's decision. `exec` is always headless; the root action is headless
+ * when `-p` was given or either stream is not a terminal (the TUI would refuse to start
+ * anyway, but it would do so AFTER a governance run had been promised). Other subcommands
+ * (`config`, `logs`, ...) never start a governed run, so only the flag-combination rules
+ * apply to them.
+ */
+export declare function checkGovernanceCommandLine(options: GovernanceRootOptions, context: GovernanceCommandContext): GovernanceLaunchCheck;

package/dist/config/governance-launch.js

@@ -0,0 +1,58 @@
+/**
+ * Command-line validation for the governance flags (governance-mode 11.2).
+ *
+ * PURE, AND OUT OF `cli.tsx` ON PURPOSE: that file is far past the size limit, and these four
+ * rules are exactly the kind that regress silently (a missing one lets `-p --govern` start a
+ * run that can never reach a human). `cli.tsx` only gathers the facts and prints the message.
+ *
+ * ASCII ONLY: `src/config/**` is inside the glyph scanner's scope.
+ */
+export const GOVERNANCE_EXCLUSIVE_MESSAGE = '--govern, --plan-govern and --plan are mutually exclusive. Pass only one of them.';
+export const GOVERNANCE_HEADLESS_MESSAGE = 'Governance mode needs an interactive terminal. It cannot be combined with -p/--print, '
+    + 'the exec subcommand or piped input.';
+export const GOVERNANCE_NO_TEAM_MESSAGE = '--govern and --plan-govern run their roles as team subagents, so they cannot be '
+    + 'combined with --no-team. Remove --no-team to use governance mode.';
+export const GOVERNANCE_NO_GOVERNANCE_MESSAGE = '--no-governance disables governance mode for this launch, so it cannot be combined with '
+    + '--govern or --plan-govern.';
+/**
+ * The first violated rule, or `{ ok: true }`. ORDER IS THE CONTRACT: the exclusivity error
+ * is the one a user typing three flags needs to see first, and the headless rule outranks
+ * `--no-team` because it is the one that cannot be fixed by dropping a second flag.
+ * Nothing is checked unless a governance posture was actually requested.
+ */
+export function validateGovernanceLaunch(input) {
+    const requested = input.govern === true || input.planGovern === true;
+    const exclusive = [input.govern === true, input.planGovern === true, input.plan === true];
+    if (exclusive.filter(Boolean).length > 1) {
+        return { ok: false, message: GOVERNANCE_EXCLUSIVE_MESSAGE };
+    }
+    if (!requested)
+        return { ok: true };
+    if (input.noGovernance === true)
+        return { ok: false, message: GOVERNANCE_NO_GOVERNANCE_MESSAGE };
+    if (input.headless)
+        return { ok: false, message: GOVERNANCE_HEADLESS_MESSAGE };
+    if (input.noTeam === true)
+        return { ok: false, message: GOVERNANCE_NO_TEAM_MESSAGE };
+    return { ok: true };
+}
+/**
+ * The `preAction` hook's decision. `exec` is always headless; the root action is headless
+ * when `-p` was given or either stream is not a terminal (the TUI would refuse to start
+ * anyway, but it would do so AFTER a governance run had been promised). Other subcommands
+ * (`config`, `logs`, ...) never start a governed run, so only the flag-combination rules
+ * apply to them.
+ */
+export function checkGovernanceCommandLine(options, context) {
+    const headless = context.commandName === 'exec'
+        || (context.isRootAction
+            && (options.print === true || !context.stdinIsTty || !context.stdoutIsTty));
+    return validateGovernanceLaunch({
+        govern: options.govern,
+        planGovern: options.planGovern,
+        plan: options.plan,
+        noTeam: options.team === false,
+        noGovernance: options.governance === false,
+        headless,
+    });
+}

package/dist/config/load.d.ts

@@ -240,6 +240,21 @@ export interface CliFlags {
     compaction?: boolean;
     /** `--compaction-threshold <0..1|N%>` — session override for `threshold`. */
     compactionThreshold?: string;
+    /**
+     * `--govern` / `--plan-govern` (governance-mode 11.2). Plain booleans: they only ever ask
+     * for a starting posture and are persisted nowhere, so unlike the pairs above there is no
+     * stored value for a commander default to overwrite. `cli.tsx` rejects the combinations
+     * (mutually exclusive, headless, `--no-team`) before this layer sees them.
+     */
+    govern?: boolean;
+    planGovern?: boolean;
+    /**
+     * `--no-governance`, carried as `false` ONLY. A lone negative flag makes commander default
+     * its option to `true`, so `cli.tsx` forwards `undefined` for that case and nothing here can
+     * mistake silence for an override. Launch-only: it lands in the resolved `CliConfig` and is
+     * never written to the store.
+     */
+    governance?: boolean;
     /**
      * `--resume <id|path>` - continue a saved session under a NEW id
      * (tui-session-id-resume 4).

package/dist/config/load.js

@@ -15,6 +15,7 @@ import { getConfigPath } from './app-paths.js';
 import { setHistoryEnabled } from './prompt-history.js';
 import { setEntryRetain } from '../agent/entry-limits.js';
 import { readSubmitCount } from './ui-state.js';
+import { resolveGovernanceConfig, resolveInitialPosture } from './governance-config.js';
 import { getLogger } from '../logging/logger.js';
 import { registerSecret, registerSecretsFrom } from '../logging/secret-registry.js';
 import { detectCapabilities, resolveTuiCapabilities } from '../ui/capabilities.js';
@@ -710,6 +711,28 @@ export function loadConfig(flags = {}, options = {}) {
     // `viewReducer` is pure and takes no config, so the resolved ring cap reaches
     // it through the same module-singleton channel `setHistoryEnabled` uses.
     setEntryRetain(transcriptRetain);
+    // Governance: file < env (kill switch) < `--no-governance`, clamped like every section. The
+    // initial posture is resolved against the SAME team value the config carries, and a request
+    // that cannot be honoured degrades to the classic posture with a log record, never silently.
+    const governance = resolveGovernanceConfig({
+        file: file.governance,
+        env: env.partial.governance,
+        disableForLaunch: flags.governance === false,
+    });
+    const team = resolveTeamConfig(flags, env.partial, file);
+    const posture = resolveInitialPosture({
+        govern: flags.govern,
+        planGovern: flags.planGovern,
+        startInPlanMode,
+        governance,
+        teamEnabled: team.enabled,
+    });
+    const initialPosture = posture.posture;
+    if (posture.degradedReason !== undefined) {
+        getLogger().warn('config', 'governance_initial_posture_degraded', {
+            reason: posture.degradedReason,
+        });
+    }
     const config = {
         modelProfiles: projection.issues.length ? undefined : file.modelProfiles,
         provider,
@@ -768,7 +791,7 @@ export function loadConfig(flags = {}, options = {}) {
                 : {}),
         },
         log: resolveLogConfig(flags, env.partial, file),
-        team: resolveTeamConfig(flags, env.partial, file),
+        team,
         todo: resolveTodoConfig(flags, env.partial, file),
         retry: resolveRetryConfig(flags, env.partial, file),
         fast: resolveFastConfig(flags, env.partial, file),
@@ -790,6 +813,8 @@ export function loadConfig(flags = {}, options = {}) {
         // `taskSummary.enabled: false` cannot arrive as two different shapes.
         taskSummary: clampTaskSummaryConfig({ ...DEFAULT_CONFIG.taskSummary,
             ...(env.partial.taskSummary ?? {}), ...(file.taskSummary ?? {}) }),
+        governance,
+        initialPosture,
         cwd,
         color,
         colorLevel,

package/dist/config/model-profile-store.d.ts

@@ -1,12 +1,14 @@
 import { type ModelProfilesConfig, type ModelRole, type ProfileValidationIssue } from './model-profiles.js';
 import type { SessionKitState } from './model-kits.js';
-import type { CliConfig, CompactionConfig, FastConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
-export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team'>> {
+import type { CliConfig, CompactionConfig, FastConfig, GovernanceConfig, LogConfig, PersistedConfig, TeamConfig } from './schema.js';
+export interface ModelSettingsPatch extends Partial<Omit<PersistedConfig, 'modelProfiles' | 'fast' | 'compaction' | 'log' | 'team' | 'governance'>> {
     fast?: Partial<FastConfig>;
     compaction?: Partial<CompactionConfig>;
     log?: Partial<LogConfig>;
     /** The subagent-model picker writes here (subagent-model D-5/I-5): draft-only until Save. */
     team?: Partial<TeamConfig>;
+    /** Governance writers (`config set`, `/gov budget`) send single keys; the store clamps. */
+    governance?: Partial<GovernanceConfig>;
 }
 export interface ModelSettingsDraft {
     profiles?: ModelProfilesConfig;

package/dist/config/schema.d.ts

@@ -7,7 +7,10 @@
  */
 import { type RetryPolicy, type ThinkingLevel } from '@aragon-agent/core';
 import { type LogLevelName } from '../logging/levels.js';
+import { type GovernanceConfig } from './governance-config.js';
+import type { Posture } from '../governance/posture.js';
 import type { FollowThroughMode } from '../todo/types.js';
+export { clampGovernanceConfig, DEFAULT_GOVERNANCE_CONFIG, type GovernanceConfig, } from './governance-config.js';
 /**
  * `ModelRegistry` seeds builtin lists for five providers, but `initProviders()`
  * registers only three adapters. Running a model whose provider has no adapter
@@ -1146,6 +1149,8 @@ export interface PersistedConfig {
     prompts: PromptsConfig;
     /** The header task label. The THIRTEENTH; two scalars (see TaskSummaryConfig). */
     taskSummary: TaskSummaryConfig;
+    /** Governance mode. The FOURTEENTH; scalars only (see GovernanceConfig). */
+    governance: GovernanceConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -1534,6 +1539,23 @@ export interface CliConfig {
      * switched-off feature.
      */
     taskSummary?: TaskSummaryConfig;
+    /**
+     * Governance mode (governance-mode 11.1). The FOURTEENTH nested object; scalars only.
+     *
+     * OPTIONAL HERE FOR THE SAME REASON AS `prompts` / `taskSummary` ABOVE: `CliConfig` is built
+     * by hand in many fixtures, `loadConfig` always fills it, and readers treat a missing
+     * section as the documented defaults. `enabled` here (after env kill switch and
+     * `--no-governance`) decides whether governance tools are REGISTERED, once at construction.
+     */
+    governance?: GovernanceConfig;
+    /**
+     * The posture the session starts in (governance-mode 11.2): `--plan` / `planModeDefault`
+     * still decide `startInPlanMode` exactly as before, and `--govern` / `--plan-govern` win over
+     * them when governance is available. Optional on this shape for the fixture reason above;
+     * `loadConfig` always fills it. Without a governance flag it is `'plan'` when
+     * `startInPlanMode`, else `'build'`.
+     */
+    initialPosture?: Posture;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -9,6 +9,9 @@ import { isAbsolute } from 'node:path';
 import { ABSOLUTE_MAX_OUTPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_RETRY_POLICY, MIN_MAX_OUTPUT_TOKENS, RETRY_LIMITS, } from '@aragon-agent/core';
 import { clampLogLevel } from '../logging/levels.js';
 import { TEAM_LIMITS } from '../team/limits.js';
+import { DEFAULT_GOVERNANCE_CONFIG } from './governance-config.js';
+// Governance mode (governance-mode 11.1): defined in its own file so this one does not grow.
+export { clampGovernanceConfig, DEFAULT_GOVERNANCE_CONFIG, } from './governance-config.js';
 // ---------------------------------------------------------------------------
 // Provider set — only the adapter-backed providers are usable at run time (R5).
 // ---------------------------------------------------------------------------
@@ -1194,6 +1197,9 @@ export const DEFAULT_CONFIG = {
     // `config list`, so the file would report a section it never wrote. One line
     // here, like the seven above it.
     taskSummary: DEFAULT_TASK_SUMMARY_CONFIG,
+    // And one section later again. Without this line a `config.json` predating governance
+    // resolves `governance` to `undefined`; every reader would then disagree with `config list`.
+    governance: DEFAULT_GOVERNANCE_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -17,7 +17,7 @@ import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerProfileSecrets, registerSecretsFrom } from '../logging/secret-registry.js';
 import { adaptLegacyConnectionPatch, ModelProfileConfigError, readModelSettingsDisk } from './model-profile-store.js';
 import { normalizeModelProfiles } from './model-profiles.js';
-import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, stripRetiredConfigKeys, } from './schema.js';
+import { clampBashConfig, clampJobsConfig, clampPromptsConfig, clampTaskSummaryConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampGovernanceConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, stripRetiredConfigKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -213,6 +213,13 @@ export function normalizePersistedConfig(input) {
             ...DEFAULT_CONFIG.taskSummary,
             ...(partial.taskSummary ?? {}),
         }),
+        // And the fourteenth. The READ half supplies a whole section to every user whose
+        // `config.json` predates governance, and clamps a hand-edited one: the file cannot
+        // carry a `maxRework` the engine would refuse.
+        governance: clampGovernanceConfig({
+            ...DEFAULT_CONFIG.governance,
+            ...(partial.governance ?? {}),
+        }),
     };
 }
 /**
@@ -334,6 +341,12 @@ export function mergePersistedConfig(current, patch) {
         // that must never happen is a FAILED summary call landing on "show nothing"
         // because a switch the user never touched defaulted away.
         taskSummary: clampTaskSummaryConfig({ ...current.taskSummary, ...(patch.taskSummary ?? {}) }),
+        // The fourteenth section, and the ninth time this file records the same trap.
+        // `aragon config set governance.maxRework 9` sends `{ governance: { maxRework: 9 } }`;
+        // without this merge the shallow spread REPLACES the section and `enabled` is written
+        // absent, and without the clamp 9 reaches the disk and the engine's ceiling is the
+        // only thing that stops it. The WRITE half of the two-direction gate.
+        governance: clampGovernanceConfig({ ...current.governance, ...(patch.governance ?? {}) }),
     };
     return merged;
 }

package/dist/config/ui-state.d.ts

@@ -105,6 +105,14 @@ export interface UiState {
      * and a boolean could only ever say "shown", never "shown WHAT".
      */
     promptKeyNoticeVersion: number;
+    /**
+     * Whether the one-time GOVERN explainer has been shown (governance-mode 4.3). A boolean is
+     * enough here, unlike the notices above: the sentence has never been reworded, so there is
+     * no audience of "already shown the OLD text" to reach. Like them it is a new scalar rather
+     * than a schema bump (which would reset every user's `submitCount`), and an older file reads
+     * it as `false`, which is exactly the first-run behaviour wanted.
+     */
+    governanceIntroSeen: boolean;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -125,6 +133,9 @@ export declare function setScrollModeNoticeVersion(version: number): void;
 /** `0` on a file written before the field existed; see the field's comment. */
 export declare function getPromptKeyNoticeVersion(): number;
 export declare function setPromptKeyNoticeVersion(version: number): void;
+/** `false` until the one-time GOVERN explainer has been shown; persisted across launches. */
+export declare function getGovernanceIntroSeen(): boolean;
+export declare function setGovernanceIntroSeen(seen: boolean): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -39,6 +39,7 @@ const DEFAULT_UI_STATE = {
     vtInputNoticeVersion: 0,
     scrollModeNoticeVersion: 0,
     promptKeyNoticeVersion: 0,
+    governanceIntroSeen: false,
 };
 let memory = null;
 /** Non-negative integer or `fallback`; shared by both numeric fields. */
@@ -73,6 +74,9 @@ function readFromDisk() {
             vtInputNoticeVersion: coerceCount(parsed.vtInputNoticeVersion, DEFAULT_UI_STATE.vtInputNoticeVersion),
             scrollModeNoticeVersion: coerceCount(parsed.scrollModeNoticeVersion, DEFAULT_UI_STATE.scrollModeNoticeVersion),
             promptKeyNoticeVersion: coerceCount(parsed.promptKeyNoticeVersion, DEFAULT_UI_STATE.promptKeyNoticeVersion),
+            governanceIntroSeen: typeof parsed.governanceIntroSeen === 'boolean'
+                ? parsed.governanceIntroSeen
+                : DEFAULT_UI_STATE.governanceIntroSeen,
         };
     }
     catch {
@@ -160,6 +164,13 @@ export function getPromptKeyNoticeVersion() {
 export function setPromptKeyNoticeVersion(version) {
     update({ promptKeyNoticeVersion: version });
 }
+/** `false` until the one-time GOVERN explainer has been shown; persisted across launches. */
+export function getGovernanceIntroSeen() {
+    return loadUiState().governanceIntroSeen;
+}
+export function setGovernanceIntroSeen(seen) {
+    update({ governanceIntroSeen: seen });
+}
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/diagnostics/doctor.js

@@ -16,6 +16,8 @@ import process from 'node:process';
 import { initProviders, ModelRegistry } from '@aragon-agent/core';
 import { getHomeResolutionWarning, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
 import { readConfigFile } from '../config/store.js';
+import { describeGovernanceConfigAvailability, } from '../config/governance-config.js';
+import { unavailableReasonText } from '../governance/copy.js';
 import { loadConfig, makeGetApiKey } from '../config/load.js';
 import { isAdapterProvider, toRetryPolicy } from '../config/schema.js';
 import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
@@ -28,6 +30,7 @@ export async function runDoctorChecks(flags, opts = {}) {
     checks.push(checkModel(config));
     checks.push(checkSessionsDir());
     checks.push(checkValidationStrength());
+    checks.push(checkGovernance(config));
     if (opts.probe)
         checks.push(await probeProvider(config));
     return { ok: checks.every((c) => c.verdict !== 'fail'), checks };
@@ -64,6 +67,23 @@ function checkValidationStrength() {
     return pass('ajv', 'absent: required/properties/items/additionalProperties are still enforced by the ' +
         'built-in validator; pattern/format/multipleOf are not');
 }
+/**
+ * `governance: ready | unavailable (<reason>)` (governance-mode 13.2) - a `pass` either way.
+ *
+ * An unavailable feature is a CHOICE (a config key, `ARAGON_GOVERNANCE=0`, team mode off),
+ * not a defect, so it must not warn or move the exit code; the row exists so "why does
+ * Shift+Tab not reach GOVERN" has an answer next to the other install facts. Config-level
+ * reasons only: a missing API key is already reported by the `api-key` row, and the runtime
+ * reasons (`headless`, `restart_required`) are not properties of an installation.
+ * The sentences come from `governance/copy.ts`, the one definition `/gov` and the settings
+ * screen share.
+ */
+function checkGovernance(config) {
+    const availability = describeGovernanceConfigAvailability(config, process.env);
+    if (availability.ok)
+        return pass('governance', 'ready');
+    return pass('governance', `unavailable (${unavailableReasonText(availability.reason)})`);
+}
 function pass(name, detail) {
     return { name, verdict: 'pass', detail, remedy: '' };
 }

package/dist/governance/card-normalize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `normalizeGovernanceCard` - turn an untrusted value (a session file, a hand-edited
+ * `entries` array) into a renderable `GovernanceCardData`, or `null` (section 10.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY.
+ *
+ * LENIENT BY DESIGN. A governance card is HISTORY: a resume that refuses because one row
+ * carried a string where a number belongs would throw away a conversation to protect a
+ * footnote (`validate-session.ts` makes the same argument for the todo card). So:
+ * unknown fields are dropped, a malformed ROW is dropped, a missing text field degrades
+ * to an empty string, and only a value that is not a card at all (not an object, no
+ * recognisable variant, nothing left to draw) returns `null` - which the caller turns into
+ * a one-line text entry.
+ */
+import type { GovernanceCardData } from './types.js';
+/** The one line a card degrades to when nothing of it can be drawn. */
+export declare const GOVERNANCE_CARD_FALLBACK_TEXT = "Governance card unavailable";
+/** Bounds so a corrupt file cannot make a card taller than the transcript can hold. */
+export declare const CARD_LIMITS: {
+    readonly rows: 24;
+    readonly notes: 12;
+    readonly textChars: 400;
+};
+export declare function normalizeGovernanceCard(value: unknown): GovernanceCardData | null;