@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/engine/visibility.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Information boundary (governance-mode 8.3): who may read what, the deterministic
+ * `gov_view` exception policy, and paging for `gov_read`.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * ONE TABLE. `VISIBILITY_MATRIX` is the single source for both `gov_read` and the
+ * prompt assembler: a second hand-written copy would drift, and a drift here is a silent
+ * information leak (a tester who can read the review comments grades the reviewer's
+ * opinion instead of the code - exactly what the boundary exists to prevent).
+ *
+ * Cells are either one `Access` or `{ own, other }` when the answer depends on whether
+ * the viewer wrote the artifact. Artifact KINDS (work / review / test / inspector) map
+ * onto the spec's MATERIAL columns in `accessFor`; a review artifact carries both the
+ * verdict and the comments, so a viewer's access is the stronger of the two cells.
+ *
+ * `inspector_report` is not a column in the spec's matrix: settle / integrate reports are
+ * the fourth power's own output, so only INSP reads them in full and the lead gets the
+ * digest. It is added here, in the table, rather than special-cased in code.
+ */
+import type { GovRole } from '../types.js';
+import type { ArtifactKind, ArtifactRef } from '../store/artifacts.js';
+export type Viewer = GovRole | 'lead';
+/** `own` = the viewer authored the artifact. */
+export type Relation = 'own' | 'other';
+export type Access = 'full' | 'summary' | 'verdict' | 'changes' | 'none';
+export type Material = 'spec' | 'own_submission' | 'dev_submission' | 'review_verdict' | 'review_comments' | 'test_report' | 'inspector_report' | 'standings' | 'event_details';
+type Cell = Access | {
+    own: Access;
+    other: Access;
+};
+export declare const VIEWERS: readonly Viewer[];
+export declare const MATERIALS: readonly Material[];
+export declare const VISIBILITY_MATRIX: Record<Viewer, Record<Material, Cell>>;
+/** Access to a spec-matrix column. */
+export declare function materialAccess(viewer: Viewer, material: Material, relation: Relation): Access;
+/** What `viewer` may read of an artifact of `kind`. */
+export declare function accessFor(viewer: Viewer, kind: ArtifactKind, relation: Relation): Access;
+export declare function canRead(viewer: Viewer, kind: ArtifactKind, relation: Relation): boolean;
+/** Artifacts `viewer` (acting as `identity`) may see, annotated with the access level. */
+export declare function listReadable(input: {
+    viewer: Viewer;
+    identity: string;
+    refs: readonly ArtifactRef[];
+}): Array<{
+    ref: ArtifactRef;
+    access: Access;
+}>;
+export interface ViewTarget {
+    kind: ArtifactKind;
+    relation: Relation;
+    /** The file whose review findings are asked for (TEST exception). */
+    file?: string;
+}
+export interface ViewRequest {
+    viewer: GovRole;
+    target: ViewTarget;
+    reason: string;
+    /** `gov_view` requests this child already made. */
+    requestsUsed: number;
+    /** Files of the requester's failing test cases. */
+    failingFiles: readonly string[];
+}
+export type ViewDecisionCode = 'already_allowed' | 'review_findings_same_file' | 'reason_too_short' | 'quota_exhausted' | 'not_allowed' | 'file_not_failing';
+export interface ViewDecision {
+    granted: boolean;
+    code: ViewDecisionCode;
+    message: string;
+    /** Whether the engine should count this against the child's one request. */
+    consumesRequest: boolean;
+    /** For the grant: only findings located in this file are released. */
+    scopeFile?: string;
+}
+/**
+ * Decide a `gov_view` request. Everything outside the default matrix is denied except
+ * one case: a TEST asking for the review findings that sit in the same file as one of its
+ * own failing cases. One request per child, reason of at least `viewReasonMinChars`.
+ * Malformed requests (short reason) do not burn the request: they are not misconduct.
+ */
+export declare function decideView(request: ViewRequest): ViewDecision;
+/** Keep only the findings located in `file` (path-normalized comparison). */
+export declare function findingsForFile<T extends {
+    file: string;
+}>(findings: readonly T[], file: string): T[];
+export interface PageResult {
+    text: string;
+    offset: number;
+    /** null on the last page. */
+    nextOffset: number | null;
+    total: number;
+    /** 1-based. */
+    page: number;
+    pages: number;
+}
+/** One page of `text` starting at `offset` (clamped), never splitting a surrogate pair. */
+export declare function pageText(text: string, offset?: number, pageChars?: number): PageResult;
+/** Page body plus a one-line footer telling the reader how to continue. */
+export declare function formatPage(id: string, page: PageResult): string;
+/** The `gov_read` list view: id, kind and access level, one per line. */
+export declare function formatReadableList(items: ReadonlyArray<{
+    ref: ArtifactRef;
+    access: Access;
+}>): string;
+export {};

package/dist/governance/engine/visibility.js

@@ -0,0 +1,223 @@
+/**
+ * Information boundary (governance-mode 8.3): who may read what, the deterministic
+ * `gov_view` exception policy, and paging for `gov_read`.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * ONE TABLE. `VISIBILITY_MATRIX` is the single source for both `gov_read` and the
+ * prompt assembler: a second hand-written copy would drift, and a drift here is a silent
+ * information leak (a tester who can read the review comments grades the reviewer's
+ * opinion instead of the code - exactly what the boundary exists to prevent).
+ *
+ * Cells are either one `Access` or `{ own, other }` when the answer depends on whether
+ * the viewer wrote the artifact. Artifact KINDS (work / review / test / inspector) map
+ * onto the spec's MATERIAL columns in `accessFor`; a review artifact carries both the
+ * verdict and the comments, so a viewer's access is the stronger of the two cells.
+ *
+ * `inspector_report` is not a column in the spec's matrix: settle / integrate reports are
+ * the fourth power's own output, so only INSP reads them in full and the lead gets the
+ * digest. It is added here, in the table, rather than special-cased in code.
+ */
+import { GOV_LIMITS } from '../limits.js';
+export const VIEWERS = ['DEV', 'REV', 'TEST', 'INSP', 'lead'];
+export const MATERIALS = [
+    'spec',
+    'own_submission',
+    'dev_submission',
+    'review_verdict',
+    'review_comments',
+    'test_report',
+    'inspector_report',
+    'standings',
+    'event_details',
+];
+export const VISIBILITY_MATRIX = {
+    DEV: {
+        spec: 'full',
+        own_submission: 'full',
+        dev_submission: 'summary',
+        review_verdict: 'none',
+        review_comments: 'none',
+        test_report: 'none',
+        inspector_report: 'none',
+        standings: 'full',
+        event_details: 'none',
+    },
+    REV: {
+        spec: 'full',
+        own_submission: 'full',
+        dev_submission: 'full',
+        review_verdict: { own: 'full', other: 'none' },
+        review_comments: { own: 'full', other: 'none' },
+        test_report: 'none',
+        inspector_report: 'none',
+        standings: 'full',
+        event_details: 'none',
+    },
+    TEST: {
+        spec: 'full',
+        own_submission: 'full',
+        dev_submission: 'changes',
+        review_verdict: 'full',
+        review_comments: 'none',
+        test_report: { own: 'full', other: 'none' },
+        inspector_report: 'none',
+        standings: 'full',
+        event_details: 'none',
+    },
+    INSP: {
+        spec: 'full',
+        own_submission: 'full',
+        dev_submission: 'full',
+        review_verdict: 'full',
+        review_comments: 'full',
+        test_report: 'full',
+        inspector_report: 'full',
+        standings: 'full',
+        event_details: 'full',
+    },
+    lead: {
+        spec: 'full',
+        own_submission: 'none',
+        dev_submission: 'summary',
+        review_verdict: 'summary',
+        review_comments: 'summary',
+        test_report: 'summary',
+        inspector_report: 'summary',
+        standings: 'full',
+        event_details: 'full',
+    },
+};
+function resolveCell(cell, relation) {
+    return typeof cell === 'string' ? cell : cell[relation];
+}
+/** Access to a spec-matrix column. */
+export function materialAccess(viewer, material, relation) {
+    return resolveCell(VISIBILITY_MATRIX[viewer][material], relation);
+}
+const RANK = { none: 0, verdict: 1, changes: 1, summary: 2, full: 3 };
+function stronger(a, b) {
+    return RANK[b] > RANK[a] ? b : a;
+}
+function reviewAccess(viewer, relation) {
+    if (relation === 'own')
+        return materialAccess(viewer, 'own_submission', 'own');
+    const comments = materialAccess(viewer, 'review_comments', relation);
+    const verdictCell = materialAccess(viewer, 'review_verdict', relation);
+    // The verdict column is "conclusion only": a full verdict grant is NOT the full document.
+    const verdict = verdictCell === 'full' ? 'verdict' : verdictCell;
+    return stronger(comments, verdict);
+}
+/** What `viewer` may read of an artifact of `kind`. */
+export function accessFor(viewer, kind, relation) {
+    switch (kind) {
+        case 'work':
+            return relation === 'own'
+                ? materialAccess(viewer, 'own_submission', 'own')
+                : materialAccess(viewer, 'dev_submission', relation);
+        case 'review':
+            return reviewAccess(viewer, relation);
+        case 'test':
+            return relation === 'own'
+                ? materialAccess(viewer, 'own_submission', 'own')
+                : materialAccess(viewer, 'test_report', relation);
+        case 'inspector':
+            return materialAccess(viewer, 'inspector_report', relation);
+    }
+}
+export function canRead(viewer, kind, relation) {
+    return accessFor(viewer, kind, relation) !== 'none';
+}
+/** Artifacts `viewer` (acting as `identity`) may see, annotated with the access level. */
+export function listReadable(input) {
+    const out = [];
+    for (const ref of input.refs) {
+        const relation = ref.identity === input.identity ? 'own' : 'other';
+        const access = accessFor(input.viewer, ref.kind, relation);
+        if (access !== 'none')
+            out.push({ ref, access });
+    }
+    return out;
+}
+function normalizeFile(file) {
+    return file.trim().replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
+}
+function deny(code, message, consumesRequest) {
+    return { granted: false, code, message: `NOT ACCEPTED: ${message}`, consumesRequest };
+}
+/**
+ * Decide a `gov_view` request. Everything outside the default matrix is denied except
+ * one case: a TEST asking for the review findings that sit in the same file as one of its
+ * own failing cases. One request per child, reason of at least `viewReasonMinChars`.
+ * Malformed requests (short reason) do not burn the request: they are not misconduct.
+ */
+export function decideView(request) {
+    const { viewer, target } = request;
+    if (request.reason.trim().length < GOV_LIMITS.viewReasonMinChars) {
+        return deny('reason_too_short', `the reason must be at least ${GOV_LIMITS.viewReasonMinChars} characters; ` +
+            'explain what you need and why.', false);
+    }
+    if (accessFor(viewer, target.kind, target.relation) === 'full') {
+        return {
+            granted: true,
+            code: 'already_allowed',
+            message: 'OK: this is already readable with gov_read.',
+            consumesRequest: false,
+        };
+    }
+    if (request.requestsUsed >= GOV_LIMITS.viewRequestsPerChild) {
+        return deny('quota_exhausted', 'you have used your gov_view request for this stage.', false);
+    }
+    if (viewer !== 'TEST' || target.kind !== 'review') {
+        return deny('not_allowed', 'that material is outside your information boundary.', true);
+    }
+    const wanted = normalizeFile(target.file ?? '');
+    const failing = request.failingFiles.map(normalizeFile);
+    if (wanted === '' || !failing.includes(wanted)) {
+        return deny('file_not_failing', 'review findings are only released for a file that holds one of your failing cases.', true);
+    }
+    return {
+        granted: true,
+        code: 'review_findings_same_file',
+        message: `OK: review findings for ${target.file} are released to you.`,
+        consumesRequest: true,
+        scopeFile: target.file,
+    };
+}
+/** Keep only the findings located in `file` (path-normalized comparison). */
+export function findingsForFile(findings, file) {
+    const wanted = normalizeFile(file);
+    return findings.filter((finding) => normalizeFile(finding.file) === wanted);
+}
+/** One page of `text` starting at `offset` (clamped), never splitting a surrogate pair. */
+export function pageText(text, offset = 0, pageChars = GOV_LIMITS.readPageChars) {
+    const total = text.length;
+    const start = Number.isInteger(offset) ? Math.min(Math.max(0, offset), total) : 0;
+    let end = Math.min(total, start + pageChars);
+    const last = text.charCodeAt(end - 1);
+    if (end < total && last >= 0xd800 && last <= 0xdbff)
+        end -= 1;
+    const pages = Math.max(1, Math.ceil(total / pageChars));
+    return {
+        text: text.slice(start, end),
+        offset: start,
+        nextOffset: end < total ? end : null,
+        total,
+        page: Math.min(pages, Math.floor(start / pageChars) + 1),
+        pages,
+    };
+}
+/** Page body plus a one-line footer telling the reader how to continue. */
+export function formatPage(id, page) {
+    const footer = page.nextOffset === null
+        ? `[end of ${id}; page ${page.page}/${page.pages}]`
+        : `[${id}: page ${page.page}/${page.pages}; ` +
+            `next: gov_read {"id":"${id}","offset":${page.nextOffset}}]`;
+    return `${page.text}\n${footer}`;
+}
+/** The `gov_read` list view: id, kind and access level, one per line. */
+export function formatReadableList(items) {
+    if (items.length === 0)
+        return 'No artifacts are readable by you yet.';
+    return items.map(({ ref, access }) => `${ref.id}  [${ref.kind}]  ${access}`).join('\n');
+}

package/dist/governance/governed-dispatch.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `isGovernedDispatch` - the one predicate that says whether a team dispatch belongs to a
+ * governed run (governance-mode section 10.4, RV-3).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY A FUNCTION AND NOT AN INLINE FIELD CHECK. The reducer's `teamStart` must keep a
+ * governed dispatch out of the transcript (one run is 10-20 dispatches; a `TeamCard` for
+ * each would bury the conversation) while writing the live `state.team` snapshot the
+ * panel and `/agents` read. Two call sites need the same answer (the reducer and, later,
+ * the card tests), and "does any spec carry governance" is exactly the kind of check that
+ * grows a second spelling. The reducer imports ONLY this function.
+ */
+/** The structural slice of a `SubagentSpec` this predicate reads. */
+export interface GovernedSpecLike {
+    governance?: unknown;
+}
+/** True when ANY spec of the dispatch is governed (a governed stage is homogeneous). */
+export declare function isGovernedDispatch(specs: readonly GovernedSpecLike[]): boolean;

package/dist/governance/governed-dispatch.js

@@ -0,0 +1,17 @@
+/**
+ * `isGovernedDispatch` - the one predicate that says whether a team dispatch belongs to a
+ * governed run (governance-mode section 10.4, RV-3).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY A FUNCTION AND NOT AN INLINE FIELD CHECK. The reducer's `teamStart` must keep a
+ * governed dispatch out of the transcript (one run is 10-20 dispatches; a `TeamCard` for
+ * each would bury the conversation) while writing the live `state.team` snapshot the
+ * panel and `/agents` read. Two call sites need the same answer (the reducer and, later,
+ * the card tests), and "does any spec carry governance" is exactly the kind of check that
+ * grows a second spelling. The reducer imports ONLY this function.
+ */
+/** True when ANY spec of the dispatch is governed (a governed stage is homogeneous). */
+export function isGovernedDispatch(specs) {
+    return specs.some((spec) => spec.governance !== undefined);
+}

package/dist/governance/limits.d.ts

@@ -0,0 +1,107 @@
+/**
+ * GOV_LIMITS - the single authority on every STRUCTURAL bound governance enforces
+ * (governance-mode section 8.5), plus the stable tool-name sets and block versions.
+ *
+ * ASCII ONLY: `src/governance/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`, D-18).
+ *
+ * TWO KINDS OF NUMBER, exactly like `team/limits.ts`: the entries here are STRUCTURAL
+ * (what the store, the digest and the panel can physically carry; a user has no
+ * business tuning them) while the `governance.*` config keys (`config/schema.ts`) are
+ * POLICY and clamped. `hardMax*` bound a config key and are applied twice: once in
+ * `clampGovernanceConfig` and once in the engine, because a clamp that only runs on the
+ * read path leaves a bad value on disk.
+ */
+export declare const GOV_LIMITS: {
+    /** Ceiling for `governance.maxWorkPackages`. */
+    readonly hardMaxWorkPackages: 8;
+    /** Ceiling for `governance.maxPhases`. */
+    readonly hardMaxPhases: 6;
+    /** Ceiling for `governance.maxRework`, INCLUDING L3 `retry` grants. */
+    readonly hardMaxRework: 5;
+    /** Ceiling for `governance.maxFixCycles`, INCLUDING L3 `retry` grants. */
+    readonly hardMaxFixCycles: 5;
+    /** `gov_dispatch` calls per run. */
+    readonly hardMaxDispatches: 120;
+    /** At most this many `retry` grants per WP (resolve.disposition). */
+    readonly maxReworkGrantsPerWp: 2;
+    /** At most this many extra fix cycles may be granted per phase. */
+    readonly maxFixGrantsPerPhase: 1;
+    readonly goalChars: 300;
+    readonly specChars: 12000;
+    readonly wpIdChars: 16;
+    readonly wpTitleChars: 80;
+    readonly wpGoalChars: 1200;
+    readonly wpFilesMax: 12;
+    readonly wpAcceptanceMax: 8;
+    readonly wpAcceptanceChars: 200;
+    readonly contractsMax: 12;
+    readonly contractNameChars: 80;
+    readonly contractDefinitionChars: 800;
+    readonly integrationCommandsMax: 6;
+    readonly integrationCommandChars: 300;
+    readonly noteChars: 600;
+    readonly rulingChars: 1000;
+    readonly reasonChars: 300;
+    /** `ledger_apply` evidence must carry at least this many characters (D-4). */
+    readonly evidenceMinChars: 20;
+    readonly evidenceMaxChars: 1200;
+    readonly submissionBytes: 64000;
+    readonly artifactBytesPerRun: 20000000;
+    readonly eventsFileBytes: 8000000;
+    readonly historyPerAgent: 200;
+    readonly retentionDays: 30;
+    readonly pruneMaxPerPass: 200;
+    /** Heartbeat of `run.lock` while a stage runs. */
+    readonly lockHeartbeatMs: 15000;
+    /** A lock whose heartbeat is older than this is stale and may be taken over. */
+    readonly lockStaleMs: 60000;
+    readonly digestMaxBytes: 6000;
+    readonly finalReportMaxBytes: 24000;
+    /** Spec excerpt budget inside a child prompt. */
+    readonly specExcerptChars: 2000;
+    readonly initialTokens: 100;
+    readonly respawnTokens: 80;
+    readonly maxSingleReward: 20;
+    readonly maxSingleDeduction: -40;
+    readonly maxIncidentNegative: -50;
+    readonly tailEliminationThreshold: 60;
+    readonly healthWarnThreshold: 70;
+    readonly labelWarnThreshold: 80;
+    readonly labelDangerThreshold: 60;
+    /** Active members of a role needed before tail elimination is considered. */
+    readonly tailEliminationMinRoleSize: 3;
+    /** A child may fail validation this many times before the submission counts as absent. */
+    readonly maxValidationFailures: 3;
+    /** Dispatch retries for a child that finished without a required submission. */
+    readonly maxAutoRedispatch: 1;
+    /** `gov_view` requests per child, and the minimum reason length. */
+    readonly viewRequestsPerChild: 1;
+    readonly viewReasonMinChars: 20;
+    /** `gov_scan` path cap. */
+    readonly scanPathsMax: 40;
+    /** `gov_read` page size in characters. */
+    readonly readPageChars: 6000;
+    /** Budget warning fraction (>= this share of `budgetTokens`). */
+    readonly budgetWarnFraction: 0.8;
+    /** `skeletonRatio` above this converts D9 into D11. */
+    readonly skeletonRatioThreshold: 0.3;
+};
+/** Version of the schema written to `run.json` / `ledger.json`. */
+export declare const GOV_SCHEMA_VERSION = 1;
+/** Block versions: bump on ANY wording change so behavior reports can grep for them. */
+export declare const GOVERNANCE_BLOCK_VERSION = "v1-2026-10-24";
+export declare const GOVERNANCE_ROLE_BLOCK_VERSION = "v1-2026-10-24";
+export declare const GOVERNANCE_PLAN_ADDENDUM_VERSION = "v1-2026-10-24";
+/** The two tools registered into the lead's array (NOT in HOST_TOOL_NAMES, D-22b). */
+export declare const GOV_LEAD_TOOL_NAMES: ReadonlySet<string>;
+/** Every tool a governed child may be handed. Merged into `policyExempt` (7.1 rule 6). */
+export declare const GOV_CHILD_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The lead tools a governed ORCHESTRATOR may not call: the plan-mode blocked set plus
+ * `task` (the latter only while the gate mode is `build`). Kept as a literal list so a
+ * future change to `PLAN_MODE_BLOCKED_TOOLS` is a deliberate edit, not an accident.
+ */
+export declare const GOVERN_ORCHESTRATOR_REFUSED_TOOLS: readonly string[];
+/** Run directory id: "g" + base36(timeMs) + 3 random [a-z0-9]. */
+export declare const RUN_ID_PATTERN: RegExp;

package/dist/governance/limits.js

@@ -0,0 +1,131 @@
+/**
+ * GOV_LIMITS - the single authority on every STRUCTURAL bound governance enforces
+ * (governance-mode section 8.5), plus the stable tool-name sets and block versions.
+ *
+ * ASCII ONLY: `src/governance/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`, D-18).
+ *
+ * TWO KINDS OF NUMBER, exactly like `team/limits.ts`: the entries here are STRUCTURAL
+ * (what the store, the digest and the panel can physically carry; a user has no
+ * business tuning them) while the `governance.*` config keys (`config/schema.ts`) are
+ * POLICY and clamped. `hardMax*` bound a config key and are applied twice: once in
+ * `clampGovernanceConfig` and once in the engine, because a clamp that only runs on the
+ * read path leaves a bad value on disk.
+ */
+export const GOV_LIMITS = {
+    /** Ceiling for `governance.maxWorkPackages`. */
+    hardMaxWorkPackages: 8,
+    /** Ceiling for `governance.maxPhases`. */
+    hardMaxPhases: 6,
+    /** Ceiling for `governance.maxRework`, INCLUDING L3 `retry` grants. */
+    hardMaxRework: 5,
+    /** Ceiling for `governance.maxFixCycles`, INCLUDING L3 `retry` grants. */
+    hardMaxFixCycles: 5,
+    /** `gov_dispatch` calls per run. */
+    hardMaxDispatches: 120,
+    /** At most this many `retry` grants per WP (resolve.disposition). */
+    maxReworkGrantsPerWp: 2,
+    /** At most this many extra fix cycles may be granted per phase. */
+    maxFixGrantsPerPhase: 1,
+    // --- Input sizes (tool arguments) ---
+    goalChars: 300,
+    specChars: 12_000,
+    wpIdChars: 16,
+    wpTitleChars: 80,
+    wpGoalChars: 1_200,
+    wpFilesMax: 12,
+    wpAcceptanceMax: 8,
+    wpAcceptanceChars: 200,
+    contractsMax: 12,
+    contractNameChars: 80,
+    contractDefinitionChars: 800,
+    integrationCommandsMax: 6,
+    integrationCommandChars: 300,
+    noteChars: 600,
+    rulingChars: 1_000,
+    reasonChars: 300,
+    /** `ledger_apply` evidence must carry at least this many characters (D-4). */
+    evidenceMinChars: 20,
+    evidenceMaxChars: 1_200,
+    // --- Storage ---
+    submissionBytes: 64_000,
+    artifactBytesPerRun: 20_000_000,
+    eventsFileBytes: 8_000_000,
+    historyPerAgent: 200,
+    retentionDays: 30,
+    pruneMaxPerPass: 200,
+    /** Heartbeat of `run.lock` while a stage runs. */
+    lockHeartbeatMs: 15_000,
+    /** A lock whose heartbeat is older than this is stale and may be taken over. */
+    lockStaleMs: 60_000,
+    // --- Reports ---
+    digestMaxBytes: 6_000,
+    finalReportMaxBytes: 24_000,
+    /** Spec excerpt budget inside a child prompt. */
+    specExcerptChars: 2_000,
+    // --- Ledger parameters (Appendix A fixed parameters) ---
+    initialTokens: 100,
+    respawnTokens: 80,
+    maxSingleReward: 20,
+    maxSingleDeduction: -40,
+    maxIncidentNegative: -50,
+    tailEliminationThreshold: 60,
+    healthWarnThreshold: 70,
+    labelWarnThreshold: 80,
+    labelDangerThreshold: 60,
+    /** Active members of a role needed before tail elimination is considered. */
+    tailEliminationMinRoleSize: 3,
+    // --- Validation ---
+    /** A child may fail validation this many times before the submission counts as absent. */
+    maxValidationFailures: 3,
+    /** Dispatch retries for a child that finished without a required submission. */
+    maxAutoRedispatch: 1,
+    /** `gov_view` requests per child, and the minimum reason length. */
+    viewRequestsPerChild: 1,
+    viewReasonMinChars: 20,
+    /** `gov_scan` path cap. */
+    scanPathsMax: 40,
+    /** `gov_read` page size in characters. */
+    readPageChars: 6_000,
+    /** Budget warning fraction (>= this share of `budgetTokens`). */
+    budgetWarnFraction: 0.8,
+    /** `skeletonRatio` above this converts D9 into D11. */
+    skeletonRatioThreshold: 0.3,
+};
+/** Version of the schema written to `run.json` / `ledger.json`. */
+export const GOV_SCHEMA_VERSION = 1;
+/** Block versions: bump on ANY wording change so behavior reports can grep for them. */
+export const GOVERNANCE_BLOCK_VERSION = 'v1-2026-10-24';
+export const GOVERNANCE_ROLE_BLOCK_VERSION = 'v1-2026-10-24';
+export const GOVERNANCE_PLAN_ADDENDUM_VERSION = 'v1-2026-10-24';
+/** The two tools registered into the lead's array (NOT in HOST_TOOL_NAMES, D-22b). */
+export const GOV_LEAD_TOOL_NAMES = new Set(['gov_run', 'gov_dispatch']);
+/** Every tool a governed child may be handed. Merged into `policyExempt` (7.1 rule 6). */
+export const GOV_CHILD_TOOL_NAMES = new Set([
+    'gov_submit_work',
+    'gov_submit_review',
+    'gov_submit_test',
+    'ledger_standings',
+    'gov_read',
+    'gov_scan',
+    'gov_view',
+    'ledger_apply',
+    'ledger_rule',
+    'ledger_settle',
+]);
+/**
+ * The lead tools a governed ORCHESTRATOR may not call: the plan-mode blocked set plus
+ * `task` (the latter only while the gate mode is `build`). Kept as a literal list so a
+ * future change to `PLAN_MODE_BLOCKED_TOOLS` is a deliberate edit, not an accident.
+ */
+export const GOVERN_ORCHESTRATOR_REFUSED_TOOLS = [
+    'write_file',
+    'edit_file',
+    'bash',
+    'bash_kill',
+    'skill_install',
+    'skill_create',
+    'task',
+];
+/** Run directory id: "g" + base36(timeMs) + 3 random [a-z0-9]. */
+export const RUN_ID_PATTERN = /^g[a-z0-9]{4,12}$/;

package/dist/governance/posture-transition.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The posture transition rule (governance-mode 4.2, D-23) as a pure function.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). No React, no I/O.
+ *
+ * It is the governance twin of `AgentController.setAgentMode`'s "tighten at once, loosen
+ * later" rule, extended with the one case the two-state mode never had: a governed STAGE in
+ * flight. Children read the lead's LIVE gate mode, so tightening to plan mid-stage would
+ * deny every running child its next write (RV-2); any change is therefore deferred until
+ * the stage ends, and Esc is the only way to stop it now.
+ */
+import type { AgentMode } from '../agent/agent-mode.js';
+import { type Posture } from './posture.js';
+export interface PostureTransitionInput {
+    /** Gate mode and governance flag as they stand. */
+    current: {
+        mode: AgentMode;
+        governOn: boolean;
+    };
+    target: Posture;
+    /** Informed approval (plan approved): applies immediately. */
+    force: boolean;
+    /** The lead is mid-run. */
+    running: boolean;
+    /** A governed stage is in flight (`engine.isStageRunning()`). */
+    stageRunning: boolean;
+}
+export interface PostureTransitionResult {
+    mode: AgentMode;
+    governOn: boolean;
+    /** The target waiting for `agent_end`, or null. */
+    pending: Posture | null;
+    /** Why a change was deferred, for the caller's toast. */
+    deferredBecause: 'stage' | 'running' | null;
+}
+export declare function decidePostureTransition(input: PostureTransitionInput): PostureTransitionResult;
+/** The posture a (mode, governOn) pair denotes; re-exported so callers import one module. */
+export declare function postureOf(mode: AgentMode, governOn: boolean): Posture;