@event4u/agent-config 14.19.0 → 14.20.0

package/src/scripts/_lib/mcp_consent_residual.ts

@@ -0,0 +1,173 @@
+/**
+ * Per-host MCP consent residuals (roadmap step 3.2).
+ *
+ * A RESIDUAL is what remains non-automatic after this package has installed:
+ * the step the human still has to take before the MCP server actually runs.
+ * The step's own framing is the design constraint — "a checklist of things that
+ * did work is noise, a named residual is actionable" — so this module models
+ * only what is left, and the surfaces that print it print nothing else.
+ *
+ * Provenance is carried, not assumed.
+ *
+ * Every residual says where its text came from, and the surfaces print it:
+ *
+ * - `vendor-doc` — the host's own documentation says so. Nobody here watched it
+ *   happen. Vendor documentation drifts, so this is a starting value, never a
+ *   fact about the machine the reader is on.
+ * - `observed` — a session on that host recorded it. Only an observation may
+ *   replace a documented value, and only in that direction.
+ *
+ * An absent host is UNRECORDED, never "no residual".
+ *
+ * A host with no entry here has not been looked at. `residualFor` returns
+ * `null` and the callers say so in words, because printing nothing would make
+ * "this host needs no step" and "nobody checked this host" the same line — the
+ * exact confusion the capability manifest's own `default` provenance exists to
+ * prevent.
+ */
+
+import { describeHostCapabilities } from './host_capability.js';
+
+/** Where a residual's text came from. Only an observation may replace a doc. */
+export type ResidualSource = 'vendor-doc' | 'observed';
+
+export interface ConsentResidual {
+    /** Capability-manifest host id (`claude`), not the installer tool id. */
+    hostId: string;
+    /** The step the human still has to take. One sentence, imperative. */
+    residual: string;
+    source: ResidualSource;
+    /** Why we believe it — a doc reference, or the session that observed it. */
+    cite: string;
+}
+
+/**
+ * Seeded residuals.
+ *
+ * DELIBERATELY SHORT. Only hosts whose residual is establishable today appear;
+ * a row invented for a host nobody checked would be the "vendor-doc residuals
+ * harden into asserted facts" risk this roadmap's own register names, arriving
+ * one step earlier than predicted. Absence here is the honest state, and the
+ * callers render it as such.
+ */
+const SEEDED: Readonly<Record<string, ConsentResidual>> = {
+    claude: {
+        hostId: 'claude',
+        residual:
+            'Approve the project-scoped `agent-config` server the first time the host '
+            + 'prompts — the installer writes `.mcp.json` but does not pre-approve it.',
+        source: 'vendor-doc',
+        cite:
+            'Host documentation: a project-scope MCP server requires explicit approval, '
+            + 'suppressible only through the user-global `enabledMcpjsonServers` key, '
+            + 'which this package deliberately does not write '
+            + '(blocker `mcp-user-scope-approval-consent`).',
+    },
+};
+
+/** Installer `--tools` id → capability-manifest host id, for the report. */
+export const TOOL_TO_HOST: Readonly<Record<string, string>> = {
+    'claude-code': 'claude',
+    cursor: 'cursor',
+    'gemini-cli': 'gemini',
+    windsurf: 'windsurf',
+    cline: 'cline',
+    copilot: 'copilot',
+    augment: 'augment',
+};
+
+/**
+ * The residual for one host, or `null` when none is recorded.
+ *
+ * An OBSERVATION outranks the documented value, and in one direction only: a
+ * host whose capability row explicitly records `mcp_needs_manual_activation:
+ * false` — an observation, since the field's provenance reads `registry` only
+ * when the row wrote it — has no residual left, and that clearance is itself
+ * reported as `observed`. The reverse never happens: a documented residual is
+ * not upgraded to `observed` by anything short of a session.
+ */
+export function residualFor(hostId: string): ConsentResidual | null {
+    const { manifest, sources } = describeHostCapabilities(hostId);
+    if (sources.mcp_needs_manual_activation === 'registry' && !manifest.mcp_needs_manual_activation) {
+        return null;
+    }
+    return SEEDED[hostId] ?? null;
+}
+
+/** Was this host looked at at all? Distinguishes "cleared" from "unrecorded". */
+export function isRecorded(hostId: string): boolean {
+    const { sources } = describeHostCapabilities(hostId);
+    return hostId in SEEDED || sources.mcp_needs_manual_activation === 'registry';
+}
+
+/** One rendered line per host, for the doctor check and the installer report. */
+export interface ResidualLine {
+    hostId: string;
+    /** `residual` · `cleared` · `unrecorded` — the three honest states. */
+    state: 'residual' | 'cleared' | 'unrecorded';
+    text: string;
+}
+
+/** Render the state of one host. Never silent, in any of the three states. */
+export function residualLine(hostId: string): ResidualLine {
+    const r = residualFor(hostId);
+    if (r !== null) {
+        return {
+            hostId,
+            state: 'residual',
+            text: `${hostId}: ${r.residual} (source: ${r.source} — not observed here)`,
+        };
+    }
+    if (isRecorded(hostId)) {
+        return {
+            hostId,
+            state: 'cleared',
+            text: `${hostId}: nothing left to do (source: observed)`,
+        };
+    }
+    return {
+        hostId,
+        state: 'unrecorded',
+        text: `${hostId}: no residual recorded — nobody checked this host, which is not the same as nothing to do`,
+    };
+}
+
+/**
+ * The lines an installer run should print, for the tools it selected.
+ *
+ * Only hosts with a real residual OR an unrecorded state are returned: a host
+ * whose residual was observed away has nothing actionable to say, and the step
+ * asks for exactly the actionable set.
+ */
+export function residualReport(toolIds: Iterable<string>): ResidualLine[] {
+    const seen = new Set<string>();
+    const out: ResidualLine[] = [];
+    for (const toolId of toolIds) {
+        const hostId = TOOL_TO_HOST[toolId];
+        if (hostId === undefined || seen.has(hostId)) continue;
+        seen.add(hostId);
+        const line = residualLine(hostId);
+        if (line.state !== 'cleared') out.push(line);
+    }
+    return out;
+}
+
+/**
+ * Print the residuals for one install's selected tools, or nothing.
+ *
+ * Lives here rather than inline in the installer's closing block for the same
+ * reason `registerMcpHosts` does: `install.ts` sits far over the source-size
+ * ratchet's ceiling, and the rendering belongs beside the table it renders.
+ */
+export function printResiduals(
+    toolIds: Iterable<string>,
+    quiet: boolean,
+    write: (s: string) => void = (s) => process.stdout.write(s),
+): void {
+    if (quiet) return;
+    const lines = residualReport(toolIds);
+    if (lines.length === 0) return;
+    write('  Still needs you (MCP):\n');
+    for (const line of lines) write(`    \u2022 ${line.text}\n`);
+    write('\n');
+}

package/src/scripts/_lib/orchestration_record.ts

@@ -16,6 +16,7 @@
  * add one. (Mirrors `domain-safety-pii` § Surface 2 / artifact-engagement.)
  */
 
+import { appliedIds } from './audit_field_provenance.js';
 import type { LookupClass } from './auto_dispatch.js';
 import type { EvidenceBasis } from './evidence_basis.js';
 // TYPE-ONLY on purpose. `runtime_journal.ts` imports `node:sqlite` at runtime,
@@ -104,6 +105,24 @@ export interface RecordInput {
      * the rules bound in the contract.
      */
     skills_applied?: string[] | null | undefined;
+    /**
+     * Stable rule ids the run ACTUALLY carried, as an observation.
+     *
+     * Until 2026-09-07 this producer wrote the literal `['delegation-policy']`
+     * on every line, and so did `review_skipped_record.ts`. Mining the real
+     * stream with `extract_audit_patterns --min-count 2` therefore minted
+     * exactly ONE pattern at count 1074 over 1104 lines: not a regularity, just
+     * arithmetic over a constant. Every per-asset reader downstream was
+     * aggregating over the writer rather than over the work.
+     *
+     * ABSENT now means an EMPTY list, not a fabricated one. An empty list is an
+     * honest absence — the same answer `activation_receipt_producer.ts` has
+     * always given — and it is what makes the field's variation, when a caller
+     * does supply ids, evidence about the run.
+     *
+     * Ids only, never bodies. Bounded to <= 32, mirroring the contract.
+     */
+    rules_applied?: string[] | null | undefined;
     /**
      * What this dispatch was supposed to produce. Drives the anti-forgery gate
      * in `envelopeOutcome`. Absent or `unknown` disables the gate for this
@@ -253,6 +272,7 @@ const ORIGIN_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
  */
 const MAX_APPLIED_IDS = 32;
 
+
 /**
  * What THIS producer's lines carry. `ids-only` and not `counts-only` because
  * every line carries `rules_applied`, and some carry `skills_applied`.
@@ -626,7 +646,9 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         risk_class: risk,
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
-        rules_applied: ['delegation-policy'],
+        // COMPUTED, never a producer constant. See `rules_applied` on the input
+        // interface for the measurement that retired the constant.
+        rules_applied: appliedIds(input.rules_applied),
         // MANDATORY, never optional and never derived by the reader. This line
         // carries `rules_applied` and may carry `skills_applied`, both of which
         // are stable artefact ids, so the class it declares is `ids-only`

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -5,8 +5,11 @@
  * when it is stale. A second copy of any of these values is the drift seam
  * Risk 6 warns about.
  */
+import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { safe_stem } from './session_register.js';
+
 /** Where `session:recycle` writes the pending envelope (gitignored runtime state). */
 export const RECYCLE_ENVELOPE_REL = path.join('agents', 'runtime', 'state', 'recycle-envelope.json');
 
@@ -33,3 +36,190 @@ export const RECYCLE_MAX_AGE_HOURS = 48;
  * for the wrapper block and a co-pending handoff.
  */
 export const RECYCLE_ENVELOPE_MAX_BYTES = 6144;
+
+// ---------------------------------------------------------------------
+// Per-SESSION keying (road-to-one-continuity-record Phase 2.1)
+// ---------------------------------------------------------------------
+
+/** State directory the two constants above live in. */
+const _STATE_REL = path.join('agents', 'runtime', 'state');
+
+/**
+ * Per-SESSION record path. The two constants above name **one file per
+ * workspace**, and the session register in the same tree models concurrent
+ * sessions per checkout — so the continuity artifact and the identity model
+ * disagreed, and the artifact lost. Two sessions in one checkout overwrite
+ * each other's record and each resumes from whichever wrote last.
+ *
+ * This is the same defect `roadmap_claim_rel` (`session_register_hook.ts:105`)
+ * was repaired for, and it is deliberately repaired the same way rather than a
+ * better way: one shape for "state keyed by session", so a reader who has seen
+ * one recognises the other. `safe_stem` is imported from the register rather
+ * than re-implemented — a second sanitiser is a second traversal guard to keep
+ * correct.
+ *
+ * **No `latest` index, by decision.** A pointer file naming the newest record
+ * would restore the shared write target one layer up and re-create the same
+ * race with an extra indirection. Resolution is by register identity,
+ * workspace and branch — never by recency.
+ *
+ * When no session id is resolvable the legacy shared path is returned, so an
+ * older record keeps working and the fallback degrades to the previous
+ * behaviour instead of losing the record. The reader's ambiguity rule
+ * (`resolveContinuityRecord`) is what keeps that fallback from becoming a
+ * cross-session read.
+ */
+export function recycle_envelope_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(session_id, RECYCLE_ENVELOPE_REL, 'recycle-envelope', '.json');
+}
+
+/** Consumed sibling of {@link recycle_envelope_rel}, same keying. */
+export function recycle_consumed_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(session_id, RECYCLE_CONSUMED_REL, 'recycle-envelope', '.consumed.json');
+}
+
+/**
+ * Shared builder. Containment is asserted locally rather than trusted from
+ * `safe_stem`: a guarantee living in another module's implementation is one
+ * refactor away from being untrue here, and the failure mode of being wrong is
+ * a write outside the state directory.
+ */
+function _sessionKeyed(
+    session_id: string | null | undefined,
+    legacy: string,
+    stem: string,
+    suffix: string,
+): string {
+    const id = String(session_id ?? '').trim();
+    if (id === '') {
+        return legacy;
+    }
+    const rel = path.join(_STATE_REL, `${stem}-${safe_stem(id)}${suffix}`);
+    const norm = path.normalize(rel);
+    if (!norm.startsWith(`${_STATE_REL}${path.sep}`) || norm.includes('..')) {
+        return legacy;
+    }
+    return norm;
+}
+
+/** Every session-keyed record present in a workspace, plus the legacy file. */
+export function listContinuityRecords(workspace_root: string): string[] {
+    const dir = path.join(workspace_root, _STATE_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return names
+        .filter(
+            (n) =>
+                n.startsWith('recycle-envelope') &&
+                n.endsWith('.json') &&
+                !n.endsWith('.consumed.json'),
+        )
+        .sort()
+        .map((n) => path.join(dir, n));
+}
+
+/** What {@link resolveContinuityRecord} decided, and why — the reason is emitted, never dropped. */
+export interface ContinuityResolution {
+    /** Absolute path to read, or `null` when the reader must start clean. */
+    file: string | null;
+    /** One line, always present. On `file === null` this is what the reader says out loud. */
+    reason: string;
+}
+
+/**
+ * Which record THIS session may read.
+ *
+ * Three cases, and the third is the one the per-session key exists for:
+ *
+ * 1. **Own id resolves.** Read the record keyed to it, and nothing else. A peer
+ *    session's record is not a candidate at any point, so "neither observes the
+ *    other's" holds by construction rather than by a comparison that could be
+ *    skipped.
+ * 2. **No id, one candidate.** Read it. A single record in a checkout with no
+ *    resolvable identity is the pre-key situation and is unchanged.
+ * 3. **No id, several candidates.** START CLEAN and say so. Picking the newest
+ *    is precisely the recency resolution the no-index rule forbids: it would
+ *    hand this session a stranger's state and look like a successful resume.
+ */
+export function resolveContinuityRecord(
+    workspace_root: string,
+    session_id: string | null | undefined,
+): ContinuityResolution {
+    const id = String(session_id ?? '').trim();
+    if (id !== '') {
+        const own = path.join(workspace_root, recycle_envelope_rel(id));
+        return fs.existsSync(own)
+            ? { file: own, reason: `continuity record for this session (${safe_stem(id)})` }
+            : { file: null, reason: `no continuity record for this session (${safe_stem(id)})` };
+    }
+    const candidates = listContinuityRecords(workspace_root);
+    if (candidates.length === 0) {
+        return { file: null, reason: 'no continuity record present' };
+    }
+    if (candidates.length === 1) {
+        return { file: candidates[0] as string, reason: 'one continuity record, no session id to key on' };
+    }
+    return {
+        file: null,
+        reason:
+            `starting clean: ${candidates.length} continuity records in this workspace and no session id ` +
+            'to tell them apart — resuming from the newest would resume a peer session, not this one',
+    };
+}
+
+/**
+ * Is there any trace in this workspace of the session a record names as its
+ * predecessor?
+ *
+ * The normal case resolves through the consumed sibling: when this session
+ * started, its reader consumed the predecessor's record and moved it to this
+ * session's consumed path, so that file carries `session_id === predecessor`.
+ * A live record under the predecessor's own key also counts — that is the
+ * shape when the chain has not been walked yet.
+ *
+ * **A `false` here is a refusal, not a repair.** The reader discards the record
+ * and says why. The alternative — injecting a record whose stated lineage
+ * cannot be corroborated — is the guess this check exists to prevent, and it is
+ * the expensive direction: a refused resume costs one session's context, a
+ * wrong resume costs a session working from a stranger's state without knowing
+ * it.
+ *
+ * **Known false-refusal, stated rather than hidden:** the janitor prunes old
+ * state, so a long-idle chain can lose its consumed sibling and be refused
+ * although it was genuine. That is the same cost as the record having expired,
+ * which at {@link RECYCLE_MAX_AGE_HOURS} it very likely has.
+ */
+export function predecessorTracePresent(workspace_root: string, predecessor: string): boolean {
+    const id = String(predecessor ?? '').trim();
+    if (id === '' || id === 'none') {
+        return true;
+    }
+    if (fs.existsSync(path.join(workspace_root, recycle_envelope_rel(id)))) {
+        return true;
+    }
+    const dir = path.join(workspace_root, _STATE_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return false;
+    }
+    for (const n of names) {
+        if (!n.startsWith('recycle-envelope') || !n.endsWith('.json')) continue;
+        try {
+            const raw = JSON.parse(fs.readFileSync(path.join(dir, n), 'utf-8')) as {
+                session_id?: unknown;
+            };
+            if (String(raw.session_id ?? '').trim() === id) {
+                return true;
+            }
+        } catch {
+            // unreadable file proves nothing in either direction
+        }
+    }
+    return false;
+}

package/src/scripts/_lib/release_position.ts

@@ -0,0 +1,96 @@
+/**
+ * Where a release may START — the branch it may run from, and whether a dirty
+ * working tree is tolerated there.
+ *
+ * Its own module because `release.ts` sits 456 lines over the 1500-line source
+ * ratchet, so growing it is a gate failure by construction. `_lib/` is where
+ * `release_highlights.ts` and `release_material.ts` already put the predicates
+ * the pipeline and its gates share.
+ */
+
+export interface PositionVerdict {
+    proceed: boolean;
+    /** Printed before the run continues. Never a refusal. */
+    notice?: string;
+    /** Printed on refusal (no trailing newline). */
+    message?: string;
+}
+
+/**
+ * Where a release may START, resolved as a pure verdict (no I/O, so it is
+ * unit-testable — same shape as `confirmGate`).
+ *
+ * THE DEADLOCK THIS REMOVES.
+ *
+ * `guard_release_curation` refuses BETWEEN step 2 and step 3: step 1 has
+ * already created and checked out `release/{target}`, step 2 has already
+ * written the bump, the changelog section and every regenerated derived file,
+ * and nothing is committed yet. Its message says to curate the head and re-run
+ * `task release`. Measured on 14.19.0, neither re-run reached step 1:
+ *
+ *   - `task release`            → `release must run from 'main'` (this check)
+ *   - `task release --resume`   → `working tree is not clean` (this check)
+ *
+ * So the guard prescribed a remedy the preflight refused, in both spellings,
+ * and the only way through was to hand-craft the `release: X.Y.Z` commit the
+ * pipeline makes for itself one step later.
+ *
+ * `docs/release-runbook.md` already claimed this was closed on 2026-09-03 and
+ * the drill pins `plain-run-reuses-an-existing-branch` for it. Both were true
+ * of the fix that landed — in `checkout_release_branch`, which is STEP 1. The
+ * preflight runs before step 1, so from the release branch the run never
+ * arrived at the code that had been repaired. The claim was not wrong about
+ * step 1; it was wrong that step 1 was reachable from that position.
+ *
+ * Why `release/{target}` is a legitimate start, with or without `--resume`:
+ *
+ * It is the position the pipeline itself leaves behind. `--resume` remains
+ * meaningful for what it was always for — skipping a COMMIT, a PR, a tag or a
+ * Release that already exists — and the `!resume` tag-exists check in
+ * `preflight` still refuses a plain re-run of an already-tagged version.
+ *
+ * Why a dirty tree is accepted THERE and nowhere else:
+ *
+ * On `release/{target}` the dirt is this pipeline's own step-2 output, and
+ * step 3 sweeps it with `git add -A` regardless. Refusing it can therefore
+ * only ever fire against the tool's own state. On `main` the same tree is an
+ * operator's unrelated work about to be swept into a release commit, so the
+ * refusal stays exactly as it was. The accepted files are PRINTED rather than
+ * absorbed silently, and `check_release_pr_shape` still refuses anything
+ * outside the version-bump allowlist on the resulting PR — two nets under the
+ * one place this relaxes.
+ */
+export function preflightPosition(opts: {
+    branch: string;
+    mainBranch: string;
+    releaseBranch: string;
+    porcelain: string;
+}): PositionVerdict {
+    const { branch, mainBranch, releaseBranch, porcelain } = opts;
+    if (branch !== mainBranch && branch !== releaseBranch) {
+        return {
+            proceed: false,
+            message:
+                `release must run from '${mainBranch}' or '${releaseBranch}', ` +
+                `currently on '${branch}'`,
+        };
+    }
+    if (!porcelain.trim()) {
+        return { proceed: true };
+    }
+    if (branch === mainBranch) {
+        return { proceed: false, message: 'working tree is not clean; commit or stash first' };
+    }
+    return {
+        proceed: true,
+        notice:
+            `working tree is not clean, and on '${releaseBranch}' that is this pipeline's own ` +
+            'step-2 output — step 3 commits it with `git add -A`. Files that will be swept ' +
+            'into the release commit:\n' +
+            porcelain
+                .split('\n')
+                .filter((l) => l.trim())
+                .map((l) => `      ${l}`)
+                .join('\n'),
+    };
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -34,6 +34,7 @@
  */
 export type MutationMeasure = 'exact' | 'capped_approximation';
 
+import { appliedIds } from './audit_field_provenance.js';
 import type { NoFreeForm } from './runtime_journal.js';
 import { type PrivacyClass } from './privacy_class.js';
 
@@ -55,6 +56,20 @@ export interface ReviewSkippedInput {
     /** Stable id (ULID, UUID, or content hash); caller supplies. */
     id: string;
     work_id?: string | undefined;
+    /**
+     * Stable rule ids the run ACTUALLY carried. Absent means `[]`, an honest
+     * absence — this writer observes a review that did NOT happen, so it
+     * usually has no rules observation to offer in either direction.
+     *
+     * It wrote the literal `['delegation-policy']` on every line until
+     * 2026-09-07, which made the whole audit stream's most frequent "pattern" a
+     * property of the writer. See `_lib/audit_field_provenance.ts` for the
+     * measurement, and note the difference from `skills_applied` below: that
+     * field is OMITTED because audit-log-v1 lets absence mean "not recorded",
+     * while `rules_applied` is mandatory on every line and `[]` is how absence
+     * is spelled there.
+     */
+    rules_applied?: string[] | null | undefined;
 }
 
 export interface BuiltReviewSkippedLine {
@@ -102,7 +117,8 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
         risk_class: input.diff_lines >= HIGH_RISK_DIFF_LINES ? 'high' : 'medium',
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
-        rules_applied: ['delegation-policy'],
+        // COMPUTED, never a producer constant.
+        rules_applied: appliedIds(input.rules_applied),
         // MANDATORY on every audit line, same as the orchestration producer.
         privacy_class: PRODUCER_PRIVACY_CLASS,
         // `skills_applied` is OMITTED here, deliberately and not by oversight.