@event4u/agent-config 14.19.0 → 14.21.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;
+}