create-walle 0.10.2 → 0.10.3

package/template/wall-e/lib/landing-mcp-tools.js

@@ -0,0 +1,170 @@
+'use strict';
+
+// WP-4 (local-landing-queue-multi-session-integration-2026-10-26.html §6.3, §6.4): the landing
+// queue tools. CTM owns the queue (`GET /api/landing/status`, `POST /api/landing/submit`); these
+// are thin shapers over ctm-context-client's two calls. The caller identity they default `session`
+// to is injected by the stdio proxy (CALLER_IDENTITY_TOOLS in llm/worker-mcp-routing.js).
+//
+const path = require('node:path');
+
+// Terminal job states, mirrored from CTM's lib/landing/ctm-view.js TERMINAL_STATES. COPIED, not
+// required: Wall-E must never import a coding-task-manager module (WP-3 §5 D-7).
+const TERMINAL_LANDING_STATES = Object.freeze(['landed', 'failed', 'blocked', 'canceled']);
+// §6.4: the context-hint status read is a hard 300 ms budget -- a slow CTM must never delay a
+// preflight, and a miss simply omits the line.
+const LANDING_HINT_BUDGET_MS = 300;
+// §6.4: the wait polls the status route every 5 s (first poll immediate), never a tight loop.
+const LANDING_WAIT_POLL_MS = 5000;
+const LANDING_WAIT_MAX_MS = 540000;
+
+// The caller's CTM session id: an explicit `session`, else the stdio proxy's injected
+// `parent_agent_session_id` (the same identity mechanism the delegate tools use -- D-13). `context`
+// is the transport context (`executeTool`'s third argument); it is consulted only as a fallback for
+// transports that carry the identity there rather than in the tool arguments.
+function callerLandingSessionId(args = {}, context = {}) {
+  for (const value of [args.session, args.parent_agent_session_id, context && context.parentAgentSessionId, context && context.ctmSessionId]) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return '';
+}
+
+// WP-1 (§9 S-15): the job row is relayed verbatim, so the batch fields CTM's `jobSummary` carries
+// (`batch: { id, members, attempt, index }`, null for a singleton) ride along without a second shape
+// here. A row written by an older CTM simply has no `batch` key.
+function landingJobById(status, jobId) {
+  const jobs = status && Array.isArray(status.jobs) ? status.jobs : [];
+  for (const job of jobs) {
+    if (job && String(job.id) === jobId) return job;
+  }
+  return null;
+}
+
+async function executeLandingStatus(ctmContextClient, args = {}, context = {}) {
+  const session = callerLandingSessionId(args, context);
+  const repo = typeof args.repo === 'string' && args.repo ? args.repo : undefined;
+  return ctmContextClient.landingStatus({ repo, session: session || undefined, timeoutMs: args.timeout_ms || 30000 });
+}
+
+// §6.4/D-11: land submit is idempotent -- a second submit of the same tip returns the SAME job (the
+// CLI/CTM answer it), so the answer is relayed verbatim either way.
+// WP-4 (§6.4): the two optional priority fields ride along as strings only. Nothing is validated
+// here -- the CLI is the one validator (an unknown level or a missing reason for high/urgent is its
+// exit 2, which CTM already maps to HTTP 400) -- and the client drops empty/absent values, so an
+// unprioritized call still posts the historical `{session}` body.
+async function executeLandingSubmit(ctmContextClient, args = {}, context = {}) {
+  const session = callerLandingSessionId(args, context);
+  return ctmContextClient.landingSubmit({
+    session: session || undefined,
+    priority: typeof args.priority === 'string' ? args.priority : undefined,
+    reason: typeof args.reason === 'string' ? args.reason : undefined,
+    timeoutMs: args.timeout_ms || 30000,
+  });
+}
+
+// §6.4: conflicts are derived from ONE status call -- the repo-wide radar pairs plus this session's
+// own radar rows.
+async function executeLandingConflicts(ctmContextClient, args = {}, context = {}) {
+  const session = callerLandingSessionId(args, context);
+  const status = await executeLandingStatus(ctmContextClient, args, context);
+  const radar = status && status.radar && typeof status.radar === 'object' ? status.radar : {};
+  const forSession = status && status.forSession && typeof status.forSession === 'object' ? status.forSession : {};
+  const entry = session ? forSession[session] : null;
+  return {
+    repo: status ? status.repo : undefined,
+    pairs: Array.isArray(radar.pairs) ? radar.pairs : [],
+    forSession: entry && entry.radar && Array.isArray(entry.radar.with) ? entry.radar.with : [],
+  };
+}
+
+// Test seam (§6.4 "the poll interval must be injectable for tests"): pollMs / now / sleep. Not a
+// flag -- production always polls with the real clock and a real 5 s sleep.
+let _landingWaitInjection = null;
+function _setLandingWaitInjectionForTests(value) { _landingWaitInjection = value || null; }
+
+function _defaultLandingSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// §6.4: poll GET /api/landing/status until jobs[] has this id in a terminal state or the timeout
+// passes. First poll is immediate; the loop is bounded by the deadline, never a spin.
+async function executeLandingWait(ctmContextClient, args = {}, context = {}) {
+  const jobId = typeof args.jobId === 'string' ? args.jobId.trim() : '';
+  if (!jobId) throw Object.assign(new Error('jobId is required'), { code: 'jobId_required' });
+  const injected = _landingWaitInjection || {};
+  const pollMs = Number.isInteger(injected.pollMs) ? injected.pollMs : LANDING_WAIT_POLL_MS;
+  const now = typeof injected.now === 'function' ? injected.now : Date.now;
+  const sleep = typeof injected.sleep === 'function' ? injected.sleep : _defaultLandingSleep;
+  const requested = Number.isInteger(args.timeout_ms) ? args.timeout_ms : LANDING_WAIT_MAX_MS;
+  const timeoutMs = Math.max(0, Math.min(LANDING_WAIT_MAX_MS, requested));
+  const session = callerLandingSessionId(args, context);
+  const repo = typeof args.repo === 'string' && args.repo ? args.repo : undefined;
+  const deadline = now() + timeoutMs;
+  let job = null;
+  for (;;) {
+    const remaining = Math.max(1000, deadline - now());
+    const status = await ctmContextClient.landingStatus({ repo, session: session || undefined, timeoutMs: Math.min(30000, remaining) });
+    job = landingJobById(status, jobId);
+    if (job && TERMINAL_LANDING_STATES.includes(job.state)) return { job, woke_on: 'terminal' };
+    if (now() >= deadline) return { job: job || null, woke_on: 'timeout' };
+    await sleep(pollMs);
+  }
+}
+
+// CTM names a repository by its git COMMON dir (`/x/tools/.git`), whose basename is `.git`; the
+// line wants the repository's own name.
+function repoDisplayName(repo) {
+  if (typeof repo !== 'string' || !repo) return '';
+  const base = path.basename(repo);
+  return base === '.git' ? path.basename(path.dirname(repo)) : base.replace(/\.git$/, '');
+}
+
+// §6.4/D-10: the ONE line walle_context_hint appends for a caller session with a queued job, or null
+// when there is nothing to say (no entry, or a terminal state).
+function landingHintLine(status, sessionId) {
+  if (!status || !sessionId) return null;
+  const forSession = status.forSession && typeof status.forSession === 'object' ? status.forSession : {};
+  const entry = forSession[sessionId];
+  if (!entry || !entry.jobId) return null;
+  if (TERMINAL_LANDING_STATES.includes(entry.state)) return null;
+  const order = status.queue && Array.isArray(status.queue.order) ? status.queue.order : [];
+  const index = order.indexOf(entry.jobId);
+  const position = Number.isInteger(entry.position) ? entry.position : (index >= 0 ? index + 1 : null);
+  const total = Number.isInteger(entry.total) ? entry.total : order.length;
+  const repo = repoDisplayName(status.repo);
+  const eta = Number.isFinite(entry.eta_s) ? ` · ETA ${Math.round(entry.eta_s / 60)}m` : '';
+  return `landing: job ${entry.jobId} #${position} of ${total} in ${repo} · ${entry.state}${eta} · do not re-gate or re-merge`;
+}
+
+// §6.4: the hint's status read, with the hard 300 ms budget. `null` means "no caller session -- do
+// not call CTM, do not add a sources.landing key". `{ ok:false, error }` means the read was
+// attempted and failed (line omitted, no error surfaces); `{ ok:true, line }` carries the line
+// (null when the session simply has no non-terminal job).
+async function landingHintForCaller(ctmContextClient, sessionId) {
+  if (!sessionId) return null;
+  let status;
+  try {
+    // `cached`: CTM answers from the view its sweep already holds -- a preflight must never start
+    // the `land status` child (a radar probe is N merge-trees).
+    status = await ctmContextClient.landingStatus({ session: sessionId, cached: true, timeoutMs: LANDING_HINT_BUDGET_MS });
+  } catch (err) {
+    // HANDLE: a timeout/refusal/unreachable CTM omits the line and reports the failure -- the hint
+    // itself never fails because of the landing probe.
+    return { ok: false, error: (err && err.code) || 'ctm_unreachable' };
+  }
+  if (!status || status.ok === false) {
+    const error = status && typeof status.error === 'string'
+      ? status.error
+      : (status && status.error && status.error.code) || 'ctm_unreachable';
+    // A caller CTM does not know as a session (e.g. a Codex thread id, or a non-CTM harness) simply
+    // has no landing state: same as "no job", so the hint stays byte-identical.
+    if (error === 'session_unknown') return null;
+    return { ok: false, error };
+  }
+  return { ok: true, line: landingHintLine(status, sessionId) };
+}
+
+module.exports = {
+  TERMINAL_LANDING_STATES, LANDING_HINT_BUDGET_MS, LANDING_WAIT_POLL_MS, LANDING_WAIT_MAX_MS,
+  callerLandingSessionId, executeLandingStatus, executeLandingSubmit, executeLandingConflicts,
+  executeLandingWait, landingHintLine, landingHintForCaller, repoDisplayName, _setLandingWaitInjectionForTests,
+};

package/template/wall-e/lib/mcp-client-config.js

@@ -45,25 +45,33 @@ const ERROR_CODES = Object.freeze(Object.keys(ERROR_MESSAGES));
 const SECONDARY_PHASES = Object.freeze(['rollback', 'database-close', 'directory-close']);
 const SECONDARY_CODES = Object.freeze(['BUSY', 'IO_ERROR', 'OWNERSHIP', 'UNAVAILABLE']);
 
-// FU-9: WHICH client configuration refused, and WHY, as two more FIXED
+// FU-9/D-3: WHICH client configuration refused, and WHY, as two more FIXED
 // vocabularies. Both exist only so one log line can name the failing client
 // and the kind of refusal — never a path, file name, parser message or any
 // other user text (the error class itself refuses free text in either field).
 //
-// DERIVED from mcp-gateway-migrate.js, the one migrator that captures, plans
-// and writes per-client documents (its path helpers, and the `client`-carrying
-// row it records for each of them):
+// DERIVED from the two owners that capture, parse, plan and write per-client
+// documents. `mcp-gateway-migrate.js` (its path helpers, and the `client`-
+// carrying row it records for each of them):
 //   'claude-code'     -> ~/.claude.json                          (_claudeJsonPath)
 //   'codex'           -> ~/.codex/config.toml                    (_codexTomlPath)
 //   'gateway-config'  -> ~/.walle/mcp-gateway.json               (_gatewayConfigPath)
 //   'gateway-history' -> ~/.walle/live-data/mcp-gateway-snapshots/<stamp>/manifest.json
 //                                                                (_snapshotRoot)
-// Claude Desktop is deliberately absent: mcp-gateway-migrate.js never reads or
-// writes its config (only mcp-integration.js's MCP_TARGETS writer does, and
-// that writer attaches no client token).
+// and `mcp-integration.js`'s MCP_TARGETS writer, whose MCP_TARGET_CLIENTS maps
+// every ensure target id onto one of these tokens (D-3: no ensure target is
+// anonymous):
+//   'claude-code'     -> ~/.claude.json (claude-code-user) and .mcp.json (claude-code-project)
+//   'codex'           -> ~/.codex/config.toml
+//   'cursor'          -> .cursor/mcp.json
+//   'windsurf'        -> .codeium/windsurf/mcp_config.json
+//   'claude-desktop'  -> Library/Application Support/Claude/claude_desktop_config.json
 const CLIENT_CONFIG_CLIENTS = Object.freeze([
   'claude-code',
   'codex',
+  'cursor',
+  'windsurf',
+  'claude-desktop',
   'gateway-config',
   'gateway-history',
 ]);
@@ -278,6 +286,71 @@ function configError(code, options) {
   return new ClientConfigError(code, options);
 }
 
+// ---------------------------------------------------------------------------
+// FU-9, D-3: per-client error attribution. This module OWNS the fixed client
+// vocabulary (CLIENT_CONFIG_CLIENTS), so the two helpers that put a client
+// token onto an owned refusal live here too — one implementation, used by both
+// per-client writers (mcp-gateway-migrate.js and mcp-integration.js).
+//
+// A refusal raised while handling ONE client's configuration — its capture, its
+// parse/discovery, its plan, its write — is re-thrown as the SAME fixed code
+// carrying that client's token, so the boot line names the failing file instead
+// of only "could not be parsed safely".
+//
+// Only a genuinely OWNED ClientConfigError (private-field brand + immutable
+// fixed fields, re-validated by isClientConfigError) is copied, and only its
+// bounded fields travel with it. Anything else — a raw Error, a string, a falsy
+// throw — is rethrown UNCHANGED, and no path, message, parser text or byte ever
+// enters the copy (the error class refuses anything outside its fixed
+// vocabulary).
+// ---------------------------------------------------------------------------
+
+// Descriptor-only read: an accessor is never executed, so a hostile getter can
+// neither run nor substitute a value here.
+function _readFixedField(error, key) {
+  const descriptor = Object.getOwnPropertyDescriptor(error, key);
+  return descriptor && 'value' in descriptor ? descriptor.value : undefined;
+}
+
+function attributeClient(client, error) {
+  if (!isClientConfigError(error)) return error;
+  if (_readFixedField(error, 'client') !== undefined) return error; // already attributed
+  const code = _readFixedField(error, 'code');
+  const options = attributionOptions(error);
+  options.client = client;
+  if (_readFixedField(error, 'operationCompleted') === true) options.operationCompleted = true;
+  const secondaryIssues = _readFixedField(error, 'secondaryIssues');
+  if (secondaryIssues !== undefined) options.secondaryIssues = secondaryIssues;
+  return new ClientConfigError(code, options);
+}
+
+// The bounded WHICH-client attribution of an OWNED refusal, as a fresh options
+// bag for a REBUILT error: `{client?}` plus `{refusal?}` while the code stays
+// CLIENT_CONFIG_PARSE_REFUSED (the error class refuses `refusal` on any other
+// code). This is the ONE place the two field NAMES are read off a refusal —
+// `attributeClient` copies them onto the same error, and a caller that has to
+// REBUILD one (a later fixed code, merged cleanup rows) carries them across
+// with this, so a rebuild can never quietly drop the attribution again.
+function attributionOptions(error) {
+  const options = {};
+  const client = _readFixedField(error, 'client');
+  if (client !== undefined) options.client = client;
+  if (_readFixedField(error, 'code') === 'CLIENT_CONFIG_PARSE_REFUSED') {
+    const refusal = _readFixedField(error, 'refusal');
+    if (refusal !== undefined) options.refusal = refusal;
+  }
+  return options;
+}
+
+// Run ONE per-client operation, attributing whatever owned refusal it raises.
+function asClient(client, run) {
+  try {
+    return run();
+  } catch (error) {
+    throw attributeClient(client, error);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Small structural utilities. `__proto__` (and any other dangerous key) must
 // never reach a native object's prototype, so every decoded member is written
@@ -540,10 +613,14 @@ function _tomlMakeNode(kind, segment, parentPath, extra) {
 
 // Walk (creating, when needed) the implicit/declared table named by one dotted
 // segment. Traversing a DECLARED table is legal (`[a.b]` after `[a]`);
-// traversing a scalar or an array-of-tables entry is not.
+// traversing a scalar is not. Traversing an ARRAY OF TABLES is legal TOML 1.0
+// (`[[a.b]]` / `[a.b]` refer to the most recent element) — the node is RETURNED
+// and the caller absorbs the whole header+body range into it (D-2); nothing
+// under an array of tables is ever decoded, indexed or edited.
 function _tomlChildContainer(parent, segment, start) {
   const existing = parent.children.get(segment);
   if (existing) {
+    if (existing.kind === 'array-table') return existing;
     if (existing.kind !== 'table') refuse('CLIENT_CONFIG_PARSE_REFUSED', 'shape');
     return existing;
   }
@@ -561,7 +638,12 @@ function _insertTomlKeyValue(container, kvNode, text) {
   const range = _nodeRange(kvNode);
   if (!segments || !range) refuse('CLIENT_CONFIG_PARSE_REFUSED', 'shape');
   let parent = container;
-  for (let i = 0; i < segments.length - 1; i += 1) parent = _tomlChildContainer(parent, segments[i], range[0]);
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    parent = _tomlChildContainer(parent, segments[i], range[0]);
+    // S-5: a dotted key whose prefix passes THROUGH an array of tables stays
+    // refused `shape` (valid TOML, but not a shape this contract can index).
+    if (parent.kind !== 'table') refuse('CLIENT_CONFIG_PARSE_REFUSED', 'shape');
+  }
   const segment = segments[segments.length - 1];
   if (parent.children.has(segment)) refuse('CLIENT_CONFIG_PARSE_REFUSED', 'duplicate-key');
   const native = kvNode.value;
@@ -586,18 +668,46 @@ function _insertTomlKeyValue(container, kvNode, text) {
 // Insert a `[a.b]` header and its body. The header extent is derived from the
 // native KEY token plus the closing bracket, never from table.range[1] (which
 // the parser extends over the table BODY).
+//
+// D-1/D-2: an array-of-tables node owns `entries: [{start,end}]`, one per
+// source region, in source order. A repeated `[[a]]` APPENDS an entry instead
+// of refusing, and any header (`[a.x]` / `[[a.x…]]`) whose path passes through
+// an existing array-table is ABSORBED the same way — TOML 1.0 says such a
+// reference names the most recently defined element. Nothing under an array of
+// tables is decoded, indexed or editable.
+function _absorbTomlArrayTableEntry(node, start, end) {
+  node.entries.push({ start, end });
+  return node;
+}
+
 function _insertTomlTable(root, tableNode, text) {
   const segments = _tomlKeySegments(tableNode);
   const range = _nodeRange(tableNode);
   if (!segments || !range) refuse('CLIENT_CONFIG_PARSE_REFUSED', 'shape');
   const isArray = String(tableNode.kind || 'standard') === 'array';
   let container = root;
-  for (let i = 0; i < segments.length - 1; i += 1) container = _tomlChildContainer(container, segments[i], range[0]);
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    container = _tomlChildContainer(container, segments[i], range[0]);
+    // D-2: this header descends into an array of tables — absorb its whole
+    // range (header + body) and stop. Its body is never walked.
+    if (container.kind === 'array-table') return _absorbTomlArrayTableEntry(container, range[0], range[1]);
+  }
   const segment = segments[segments.length - 1];
   const existing = container.children.get(segment);
   if (isArray) {
-    if (existing) refuse('CLIENT_CONFIG_PARSE_REFUSED', 'shape');
-    const node = _tomlMakeNode('array-table', segment, container.path, { header: tableNode, start: range[0], end: range[1] });
+    if (existing) {
+      // D-1: a second `[[a]]` appends an entry to the SAME node. Any other
+      // existing kind (a scalar, or a table declared by `[a]`/`a.b = 1`) is
+      // not this contract's shape and keeps refusing.
+      if (existing.kind !== 'array-table') refuse('CLIENT_CONFIG_PARSE_REFUSED', 'shape');
+      return _absorbTomlArrayTableEntry(existing, range[0], range[1]);
+    }
+    const node = _tomlMakeNode('array-table', segment, container.path, {
+      header: tableNode,
+      entries: [{ start: range[0], end: range[1] }],
+      start: range[0],
+      end: range[1],
+    });
     container.children.set(segment, node);
     return node;
   }
@@ -640,7 +750,9 @@ function _collectTomlItems(node, out) {
       out.push({ start: node.headerStart, end: node.headerEnd, path: node.path, header: true });
     }
   } else if (node.kind === 'array-table') {
-    out.push({ start: node.start, end: node.end, path: node.path, arrayTable: true });
+    // S-3: one item PER source entry, so the region/contiguity math sees each
+    // `[[a]]` (and every absorbed descendant header) separately.
+    for (const entry of node.entries) out.push({ start: entry.start, end: entry.end, path: node.path, arrayTable: true });
     return;
   }
   if (node.children) for (const child of node.children.values()) _collectTomlItems(child, out);
@@ -658,7 +770,11 @@ function _tomlPathIsUnder(prefix, path) {
 // header for).
 function _tomlNodeExtent(node) {
   if (!node) return null;
-  if (node.kind === 'value' || node.kind === 'array-table') {
+  if (node.kind === 'array-table') {
+    // S-4: the union of every owned source entry (D-1); entries are in source order.
+    return { start: node.entries[0].start, end: Math.max(...node.entries.map((entry) => entry.end)) };
+  }
+  if (node.kind === 'value') {
     return node.start == null ? null : { start: node.start, end: node.end };
   }
   let start = node.headerStart != null ? node.headerStart : null;
@@ -1579,6 +1695,9 @@ module.exports = {
   UNSUPPORTED_CONVERSION_FIELDS,
   admitThirdPartyMigrationTuple,
   applySourceEdits,
+  asClient,
+  attributeClient,
+  attributionOptions,
   buildOwnershipManifest,
   configError,
   BOUNDARY_VALUES,

package/template/wall-e/lib/mcp-gateway-migrate.js

@@ -41,6 +41,8 @@ const {
   SECONDARY_PHASES,
   admitThirdPartyMigrationTuple,
   applySourceEdits,
+  asClient,
+  attributionOptions,
   buildOwnershipManifest,
   deepEqualJson,
   creationBoundaryEvidence,
@@ -103,49 +105,13 @@ function _readTextSafe(filePath) {
 }
 
 // ---------------------------------------------------------------------------
-// FU-9: per-client error attribution (docs: mcp-client-config.js's
-// CLIENT_CONFIG_CLIENTS). A refusal raised while handling ONE client's
-// configuration — its capture, its parse/discovery, its plan, its write — is
-// re-thrown as the SAME fixed code carrying that client's token, so the boot
-// line names the failing file instead of only "could not be parsed safely".
-//
-// Only a genuinely OWNED ClientConfigError (private-field brand + immutable
-// fixed fields, re-validated by isClientConfigError) is copied, and only its
-// bounded fields travel with it. Anything else — a raw Error, a string, a falsy
-// throw — is rethrown UNCHANGED, and no path, message, parser text or byte ever
-// enters the copy (the error class refuses anything outside its fixed
-// vocabulary).
+// FU-9/D-3: per-client error attribution now lives in the leaf that OWNS the
+// fixed client vocabulary — `attributeClient` / `asClient` in
+// mcp-client-config.js (see the block above them). Only its callers remain
+// here: every per-client capture/parse/plan step below runs inside
+// `asClient(clientToken, fn)` so a refusal names the failing client.
 // ---------------------------------------------------------------------------
 
-// Descriptor-only read: an accessor is never executed, so a hostile getter can
-// neither run nor substitute a value here.
-function _readFixedField(error, key) {
-  const descriptor = Object.getOwnPropertyDescriptor(error, key);
-  return descriptor && 'value' in descriptor ? descriptor.value : undefined;
-}
-
-function _attributeClient(client, error) {
-  if (!isClientConfigError(error)) return error;
-  if (_readFixedField(error, 'client') !== undefined) return error; // already attributed
-  const code = _readFixedField(error, 'code');
-  const options = { client };
-  const refusal = _readFixedField(error, 'refusal');
-  if (code === 'CLIENT_CONFIG_PARSE_REFUSED' && refusal !== undefined) options.refusal = refusal;
-  if (_readFixedField(error, 'operationCompleted') === true) options.operationCompleted = true;
-  const secondaryIssues = _readFixedField(error, 'secondaryIssues');
-  if (secondaryIssues !== undefined) options.secondaryIssues = secondaryIssues;
-  return new ClientConfigError(code, options);
-}
-
-// Run ONE per-client operation, attributing whatever owned refusal it raises.
-function _asClient(client, run) {
-  try {
-    return run();
-  } catch (error) {
-    throw _attributeClient(client, error);
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Minimal span-tracking JSON reader — only what this module needs: given raw
 // JSON text, returns a tree of {start, end, value|entries|items} nodes so a
@@ -987,12 +953,10 @@ function _migrationBodyFailure(primary, cleanupIssues, progress) {
   // the code stays CLIENT_CONFIG_PARSE_REFUSED (it is meaningless, and refused
   // by the error class, on any other code).
   if (owned) {
-    const client = _readFixedField(primary, 'client');
-    if (client !== undefined) options.client = client;
-    if (primary.code === 'CLIENT_CONFIG_PARSE_REFUSED') {
-      const refusal = _readFixedField(primary, 'refusal');
-      if (refusal !== undefined) options.refusal = refusal;
-    }
+    // `attributionOptions` (mcp-client-config.js) is the ONE reader of those two
+    // fixed field names: the rebuild cannot lose — and cannot re-spell — the
+    // attribution the raising `asClient` attached.
+    Object.assign(options, attributionOptions(primary));
   }
   if (changed) {
     if (completed) options.operationCompleted = true;
@@ -1085,27 +1049,27 @@ async function enableGateway({ homeDir, port, lockDir, lockTimeoutMs } = {}) {
     let bodyFailed = false;
     try {
       // FU-9: each capture/discovery/plan below is ONE client's operation, so
-      // its refusal carries that client's token (`_asClient`).
-      const claudeSource = _asClient('claude-code', () => captureClientConfigFile(claudePath, { mutexContext: context, allowMissing: true }));
+      // its refusal carries that client's token (`asClient`).
+      const claudeSource = asClient('claude-code', () => captureClientConfigFile(claudePath, { mutexContext: context, allowMissing: true }));
       acquired.push(claudeSource);
-      const codexSource = _asClient('codex', () => captureClientConfigFile(codexPath, { mutexContext: context, allowMissing: true }));
+      const codexSource = asClient('codex', () => captureClientConfigFile(codexPath, { mutexContext: context, allowMissing: true }));
       acquired.push(codexSource);
-      const gatewaySource = _asClient('gateway-config', () => captureClientConfigFile(gatewayPath, { mutexContext: context, allowMissing: true }));
+      const gatewaySource = asClient('gateway-config', () => captureClientConfigFile(gatewayPath, { mutexContext: context, allowMissing: true }));
       acquired.push(gatewaySource);
       // Strict, in-hold discovery: a parse/read failure REFUSES (never "empty").
       const discovered = [
-        ...(claudeSource.text === null ? [] : _asClient('claude-code', () => _discoverClaudeJsonStrict(claudeSource.text))),
-        ...(codexSource.text === null ? [] : _asClient('codex', () => _discoverCodexTomlStrict(codexSource.text))),
+        ...(claudeSource.text === null ? [] : asClient('claude-code', () => _discoverClaudeJsonStrict(claudeSource.text))),
+        ...(codexSource.text === null ? [] : asClient('codex', () => _discoverCodexTomlStrict(codexSource.text))),
       ];
       const claudeEntries = discovered.filter((entry) => entry.client === 'claude');
       const codexEntries = discovered.filter((entry) => entry.client === 'codex');
       const claudePlan = claudeEntries.length
-        ? _asClient('claude-code', () => _planClaudeMigration(claudeSource.text, claudeEntries, gatewayPort))
+        ? asClient('claude-code', () => _planClaudeMigration(claudeSource.text, claudeEntries, gatewayPort))
         : { text: claudeSource.text, rows: [] };
       const codexPlan = codexEntries.length
-        ? _asClient('codex', () => _planCodexMigration(codexSource.text, codexEntries, gatewayPort))
+        ? asClient('codex', () => _planCodexMigration(codexSource.text, codexEntries, gatewayPort))
         : { text: codexSource.text, rows: [] };
-      const merged = _asClient('gateway-config', () => _mergedGatewayConfig(scopedHome, discovered, gatewayPort, {
+      const merged = asClient('gateway-config', () => _mergedGatewayConfig(scopedHome, discovered, gatewayPort, {
         claude: claudeSource.text,
         codex: codexSource.text,
         gatewayText: gatewaySource.text,
@@ -1244,7 +1208,7 @@ async function disableGateway({ homeDir, lockDir, lockTimeoutMs } = {}) {
     const scopedHome = context.homeDir;
     // The reader selects the gateway-enable operation EXPLICITLY, so an
     // own-inject (ensure-walle-entry) record can never become this proof.
-    const manifestInfo = _asClient('gateway-history', () => _newestManifest(scopedHome, OPERATIONS[0]));
+    const manifestInfo = asClient('gateway-history', () => _newestManifest(scopedHome, OPERATIONS[0]));
     const acquired = [];
     // GEN11: this disable's own business-write progress — one write per
     // document, consumed so a later physical failure is reported honestly.
@@ -1256,9 +1220,9 @@ async function disableGateway({ homeDir, lockDir, lockTimeoutMs } = {}) {
     let bodyFailure = null;
     let bodyFailed = false;
     try {
-      const claudeSource = _asClient('claude-code', () => captureClientConfigFile(_claudeJsonPath(scopedHome), { mutexContext: context, allowMissing: true }));
+      const claudeSource = asClient('claude-code', () => captureClientConfigFile(_claudeJsonPath(scopedHome), { mutexContext: context, allowMissing: true }));
       acquired.push(claudeSource);
-      const codexSource = _asClient('codex', () => captureClientConfigFile(_codexTomlPath(scopedHome), { mutexContext: context, allowMissing: true }));
+      const codexSource = asClient('codex', () => captureClientConfigFile(_codexTomlPath(scopedHome), { mutexContext: context, allowMissing: true }));
       acquired.push(codexSource);
       // GEN11 (brief criterion 3): EVERY restore is PLANNED here, before the
       // FIRST physical write — the legacy proof-based restore for each client
@@ -1279,12 +1243,12 @@ async function disableGateway({ homeDir, lockDir, lockTimeoutMs } = {}) {
           const claudeRows = rows.filter((row) => row.client === 'claude');
           const codexRows = rows.filter((row) => row.client === 'codex');
           if (claudeRows.length && claudeText !== null) {
-            const plan = _asClient('claude-code', () => _planRestoreWithProof(parseClientConfig(claudeText, { format: 'json' }), claudeRows));
+            const plan = asClient('claude-code', () => _planRestoreWithProof(parseClientConfig(claudeText, { format: 'json' }), claudeRows));
             claudeText = plan.text;
             restored += plan.restored;
           }
           if (codexRows.length && codexText !== null) {
-            const plan = _asClient('codex', () => _planRestoreWithProof(parseClientConfig(codexText, { format: 'toml' }), codexRows));
+            const plan = asClient('codex', () => _planRestoreWithProof(parseClientConfig(codexText, { format: 'toml' }), codexRows));
             codexText = plan.text;
             restored += plan.restored;
           }
@@ -1298,7 +1262,7 @@ async function disableGateway({ homeDir, lockDir, lockTimeoutMs } = {}) {
       // the plugin revert) — no second write, no intermediate on-disk state.
       let pluginResult = { ok: true, reverted: 0, reason: 'no_manifest' };
       if (claudeText !== null) {
-        const revertPlan = _asClient('claude-code', () => _planPluginRevertEdits(claudeText, scopedHome));
+        const revertPlan = asClient('claude-code', () => _planPluginRevertEdits(claudeText, scopedHome));
         pluginResult = { ok: true, reverted: revertPlan.reverted };
         if (revertPlan.reason) pluginResult.reason = revertPlan.reason;
         claudeText = revertPlan.text;
@@ -1762,12 +1726,12 @@ async function revertPluginOverrides({ homeDir, lockDir, lockTimeoutMs } = {}) {
   return withClientConfigLock((context) => {
     const scopedHome = context.homeDir;
     const claudeJsonPath = _claudeJsonPath(scopedHome);
-    const source = _asClient('claude-code', () => captureClientConfigFile(claudeJsonPath, { mutexContext: context, allowMissing: true }));
+    const source = asClient('claude-code', () => captureClientConfigFile(claudeJsonPath, { mutexContext: context, allowMissing: true }));
     try {
       if (source.text === null) return { ok: true, reverted: 0, reason: 'no_claude_json' };
       let plan;
       try {
-        plan = _asClient('claude-code', () => _planPluginRevertEdits(source.text, scopedHome));
+        plan = asClient('claude-code', () => _planPluginRevertEdits(source.text, scopedHome));
       } catch (error) {
         if (isClientConfigError(error) && error.code === 'CLIENT_CONFIG_RESTORE_REFUSED') throw error;
         if (isClientConfigError(error) && error.code === 'CLIENT_CONFIG_PARSE_REFUSED') {