@ngockhoale/ukit 3.4.1 → 3.4.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.2 - 2026-09-29
+
+**Bug-sweep cycles C91–C93 — 42 fixes.** Handoff cycles C91 (26), C92 (13) and
+C93 (3) closed the confirmed-bug backlog across deny-gates, install/uninstall
+data-loss paths, agent-runtime supervision, index integrity, codeintel
+freshness, telemetry durability, routing floors, and runtime CLI locking.
+
+- Deny gates: quote/splice/IFS bypasses and compact `-c`/`eval` operand
+  recursion in the PreToolUse guards (templateHooks + audit tests).
+- Install/uninstall: typed `InstallMetadataError` on corrupt `install.json`
+  (doctor), uninstall refuses corrupt/unreadable ledger instead of silently
+  proceeding, plus other destructive-path hardening.
+- agentRuntime: supervisor pgid kill-target fix, `cancel_pending` edge,
+  dead `recovery.js` cancelled-branch removal.
+- Index/codeintel: integrity checks, freshness/retrieval guards.
+- Handoff machinery: model-tier guard override anchor (task-file declaration +
+  `.ukit/storage/tier-override` marker), Release Policy mirror restored into
+  root `CLAUDE.md`/`AGENTS.md`.
+
 ## 3.4.1 - 2026-09-28
 
 Republish of 3.4.0 — npm staged-version E409 limbo (same content, version bump only).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.1",
+  "version": "3.4.2",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/cli/commands/code.js

@@ -9,21 +9,40 @@ import { IndexFileSyntaxProvider } from '../../core/codeintel/providers.js';
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
 const SUBCOMMANDS = new Set(['peek', 'search', 'context', 'impact']);
 
-function extractFlag(args, flag) {
-  const index = args.indexOf(flag);
+export function extractFlag(args, flag) {
+  // Both forms are accepted, mirroring indexArgs.js: `--flag value` and
+  // `--flag=value` (first `=` separates, so `a=b` values survive whole).
+  const spaceIndex = args.indexOf(flag);
+  const equalsIndex = args.findIndex((arg) => arg.startsWith(`${flag}=`));
+  const index = spaceIndex < 0 ? equalsIndex
+    : equalsIndex < 0 ? spaceIndex
+      : Math.min(spaceIndex, equalsIndex);
   if (index < 0) return { value: null, rest: args };
-  const value = args[index + 1];
+  const isEqualsForm = args[index].startsWith(`${flag}=`);
+  const value = isEqualsForm ? args[index].slice(flag.length + 1) : args[index + 1];
   // A missing value — or the next flag swallowed as the value — used to pass
   // silently (e.g. `--mode --budget 5` set mode='--budget' and dropped --budget).
-  if (typeof value !== 'string' || value.startsWith('--')) {
+  // The `=` form shares the contract: `--mode=` and `--mode=--budget` are errors.
+  if (typeof value !== 'string' || value === '' || value.startsWith('--')) {
     throw new Error(`Missing value for ${flag}.`);
   }
   return {
     value,
-    rest: [...args.slice(0, index), ...args.slice(index + 2)],
+    rest: isEqualsForm
+      ? [...args.slice(0, index), ...args.slice(index + 1)]
+      : [...args.slice(0, index), ...args.slice(index + 2)],
   };
 }
 
+// First occurrence wins; a later duplicate stays in `rest` and is rejected by
+// assertNoUnknownOptions — deterministic, never silently half-applied.
+function assertNoUnknownOptions(args) {
+  const unknown = args.find((arg) => arg.startsWith('--'));
+  if (unknown) {
+    throw new Error(`Unknown option: ${unknown.split('=', 1)[0]}`);
+  }
+}
+
 function hasFlag(args, flag) {
   return args.includes(flag);
 }
@@ -89,6 +108,7 @@ export async function runCode({ projectRoot, argv = [] }) {
 
   if (subcommand === 'peek') {
     const { value: lines, rest: args } = extractFlag(withoutJson, '--lines');
+    assertNoUnknownOptions(args);
     const filePath = args[0];
     if (!filePath) {
       console.error('[UKit] Missing file path. Usage: ukit code peek <path> [--lines a-b] [--json]');
@@ -112,6 +132,7 @@ export async function runCode({ projectRoot, argv = [] }) {
   if (subcommand === 'search') {
     const { value: limitArg, rest: args } = extractFlag(withoutJson, '--limit');
     const limit = parsePositiveInt(limitArg, 20);
+    assertNoUnknownOptions(args);
     const query = args.join(' ').trim();
     if (!query) {
       console.error('[UKit] Missing query. Usage: ukit code search "<query>" [--limit n] [--json]');
@@ -138,6 +159,7 @@ export async function runCode({ projectRoot, argv = [] }) {
     const budget = budgetArg !== null ? parsePositiveInt(budgetArg, null) : undefined;
     const diagnostics = hasFlag(afterBudget, '--diagnostics');
     const args = afterBudget.filter((arg) => arg !== '--diagnostics');
+    assertNoUnknownOptions(args);
     const task = args.join(' ').trim();
     if (!task) {
       console.error('[UKit] Missing task. Usage: ukit code context "<task>" [--mode m] [--budget n] [--diagnostics] [--json]');
@@ -156,6 +178,7 @@ export async function runCode({ projectRoot, argv = [] }) {
   // subcommand === 'impact'
   const { value: depthArg, rest: impactArgs } = extractFlag(withoutJson, '--depth');
   const depth = depthArg !== null ? parsePositiveInt(depthArg, null) : undefined;
+  assertNoUnknownOptions(impactArgs);
   const target = impactArgs[0];
   if (!target) {
     console.error('[UKit] Missing target. Usage: ukit code impact <path|symbol> [--depth N] [--json]');
@@ -185,4 +208,5 @@ export function printCodeHelp() {
   console.log('  --budget <n>        Override routed token budget');
   console.log('  --depth <N>         Impact-mode hop depth (clamped 1..codeIntel.impact.maxDepth)');
   console.log('  --diagnostics       Include post-edit diagnostics in next_actions');
+  console.log('  Every value flag also accepts the --flag=value form.');
 }

package/src/cli/commands/decision.js

@@ -51,11 +51,25 @@ function printUsage(stream = console.log) {
 
 function parseArgs(argv) {
   const out = { setUnic: false, clear: false, status: false };
+  // Value-taking flags must not swallow the NEXT flag: `--key --status` used
+  // to write the literal string '--status' into gatewayDecision.json.
+  const takeValue = (i, flag) => {
+    const value = argv[i + 1];
+    if (value === undefined || value.startsWith('-')) {
+      return { error: `${flag} requires a value` };
+    }
+    return { value };
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--base-url') out.baseUrl = argv[++i];
-    else if (a === '--key') out.key = argv[++i];
-    else if (a === '--scheme') out.scheme = argv[++i];
+    if (a === '--base-url' || a === '--key' || a === '--scheme') {
+      const taken = takeValue(i, a);
+      if (taken.error) return { error: taken.error };
+      if (a === '--base-url') out.baseUrl = taken.value;
+      else if (a === '--key') out.key = taken.value;
+      else out.scheme = taken.value;
+      i += 1;
+    }
     else if (a === '--set-unic') out.setUnic = true;
     else if (a === '--clear') out.clear = true;
     else if (a === '--status') out.status = true;
@@ -74,7 +88,7 @@ async function readGatewayFile(filePath) {
 
 async function writeGatewayFile(filePath, json) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
-  const tmp = `${filePath}.tmp-${process.pid}`;
+  const tmp = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
   await fs.writeFile(tmp, JSON.stringify(json, null, 2) + '\n', { mode: 0o600 });
   await fs.rename(tmp, filePath);
 }

package/src/cli/commands/doctor.js

@@ -2,7 +2,8 @@ import path from 'node:path';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import { parse } from 'yaml';
-import { pathExists, readJsonIfExists } from '../../core/fileOps.js';
+import { pathExists } from '../../core/fileOps.js';
+import { readInstallMetadata } from '../../core/metadata.js';
 import { buildPathConfig } from '../../core/paths.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
 import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
@@ -484,7 +485,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   const manifest = await loadManifest(pathConfig.manifestPath);
   const stack = await detectStack(projectRoot);
   const providers = await detectProviders(projectRoot);
-  const installMeta = await readJsonIfExists(pathConfig.installMetaPath);
+  const installMeta = await readInstallMetadata(pathConfig.installMetaPath);
   const runtimeConfigInspection = await inspectRuntimeConfig(projectRoot, { homeDir });
 
   const trackedPaths = Array.isArray(installMeta?.files)
@@ -498,7 +499,10 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   let worklogLineCount = 0;
   try {
     const content = await fs.readFile(path.join(projectRoot, 'docs', 'WORKLOG.md'), 'utf8');
-    worklogLineCount = content.split('\n').length;
+    // FR-025 / W2-A02 — POSIX line counting: a trailing '\n' terminates the last
+    // line, it does not start a new one. `split('\n').length` off-by-ones every
+    // well-formed file; strip one terminator first (600-line file → 600, not 601).
+    worklogLineCount = content === '' ? 0 : content.replace(/\n$/, '').split('\n').length;
   } catch {
     // file may not exist
   }

package/src/cli/commands/install.js

@@ -6,8 +6,8 @@ import { resolveDecisionApiKey, resolveDecisionBaseUrl } from '../../core/gatewa
 import { buildCodeIndex, buildDerivedIndexArtifacts } from '../../index/buildIndex.js';
 import { installIndexRefreshHooks } from '../../index/gitHooks.js';
 import fs from 'node:fs/promises';
-import { pathExists, readJsonIfExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
-import { removeTrackedPathsFromMetadata } from '../../core/metadata.js';
+import { pathExists, removeFileOrLinkOnly } from '../../core/fileOps.js';
+import { readInstallMetadata, removeTrackedPathsFromMetadata } from '../../core/metadata.js';
 import { provisionSupportDir } from '../../core/observability/support/provision.js';
 import {
   ADAPTER_BY_KEY,
@@ -72,7 +72,7 @@ function isSameOrDescendantPath(candidatePath, parentPath) {
 
 async function loadTrackedManagedPathSet(projectRoot) {
   const installMetaPath = path.join(projectRoot, '.claude', 'ukit', '.ukit', 'install.json');
-  const installMeta = await readJsonIfExists(installMetaPath);
+  const installMeta = await readInstallMetadata(installMetaPath);
   if (installMeta?.tool !== 'ukit' || !Array.isArray(installMeta.files)) {
     return null;
   }
@@ -211,8 +211,16 @@ export async function pruneDeselectedAdapters({
         continue;
       }
 
+      // C92-G-01: iterate the install.json-tracked subset only. A managed-path
+      // name is adapter-owned, not file-owned — an untracked file at a managed
+      // path (e.g. `.codex/settings.local.json`, a `mergeStrategy: skip` seed
+      // that was never written, so never tracked) is user content, and
+      // unlinking it is unrecoverable data loss.
+      const untrackedManagedPaths = adapter.managedPaths.filter(
+        (relativePath) => !existingManagedPaths.includes(relativePath),
+      );
       let removedCount = 0;
-      for (const relativePath of adapter.managedPaths) {
+      for (const relativePath of existingManagedPaths) {
         const absolutePath = path.join(projectRoot, relativePath);
         const removed = await removeFileOrLinkOnly(absolutePath);
         if (removed) {
@@ -234,6 +242,14 @@ export async function pruneDeselectedAdapters({
         }
       }
 
+      for (const relativePath of untrackedManagedPaths) {
+        if (await pathExists(path.join(projectRoot, relativePath))) {
+          console.log(
+            `[UKit] Keeping ${relativePath} — not recorded in install.json, so it is treated as user content.`,
+          );
+        }
+      }
+
       console.log(`[UKit] Removed ${removedCount} ${adapter.label} path(s).`);
     }
   } finally {
@@ -318,6 +334,15 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     );
   }
 
+  // C92-C-02: pruned obsolete managed paths (e.g. a pack skill whose heuristic
+  // flipped off) are backed up under .claude/ukit/.ukit/backups before unlink —
+  // and the count is reported, never silent.
+  if ((result.prune?.removed ?? 0) > 0) {
+    console.log(
+      `[UKit] Pruned ${result.prune.removed} obsolete managed path(s) — backups under .claude/ukit/.ukit/backups/.`,
+    );
+  }
+
   if (result.userLayer) {
     if (result.userLayer.error) {
       console.warn(`[UKit] Warning: user-layer seeding skipped — ${result.userLayer.error}`);

package/src/cli/commands/memory.js

@@ -247,19 +247,30 @@ async function runMemoryV2(projectRoot, homeDir, args) {
         counts[entry.action] = (counts[entry.action] ?? 0) + 1;
       }
       const countText = Object.entries(counts).map(([a, n]) => `${a}=${n}`).join(' ') || 'none';
-      console.log(`[UKit] migrate dry-run: ${countText} (migrated=${result.migrated} skipped=${result.skipped})`);
+      console.log(`[UKit] migrate dry-run: ${countText} (migrated=${result.migrated} skipped=${result.skipped} corrupt=${result.corruptFiles ?? 0})`);
+      if (result.corruptFiles > 0) {
+        console.warn(`[UKit] ${result.corruptFiles} corrupt legacy file(s) skipped: ${result.corrupt.join(', ')}`);
+      }
       for (const entry of result.plan) {
         console.log(`[UKit]   ${entry.action} ${entry.id} (${entry.source}) — ${entry.reason}`);
       }
       return;
     }
 
+    if (result.corruptFiles > 0) {
+      console.warn(
+        `[UKit] ${result.corruptFiles} corrupt legacy file(s) NOT migrated: ${result.corrupt.join(', ')}`
+        + ' — migration marker withheld; repair or remove them and re-run.',
+      );
+    }
     if (result.migrated === 0) {
-      console.log('[UKit] Nothing to migrate (marker present or no legacy memory).');
+      console.log(result.corruptFiles > 0
+        ? '[UKit] Nothing migratable yet — corrupt legacy files remain (see above).'
+        : '[UKit] Nothing to migrate (marker present or no legacy memory).');
       return;
     }
     console.log(`[UKit] Migrated ${result.migrated} record(s) to v2.`);
-    console.log(`[UKit] Backup: ${result.backupDir ?? 'none'} — marker: ${result.markerPath}`);
+    console.log(`[UKit] Backup: ${result.backupDir ?? 'none'} — marker: ${result.corruptFiles > 0 ? 'withheld (corrupt files remain)' : result.markerPath}`);
     const stats = await v2Stats(projectRoot, { homeDir });
     console.log(`[UKit] v2 store: ${stats.total} record(s) — ${JSON.stringify(stats.byType)}`);
     return;
@@ -487,8 +498,17 @@ async function runMemoryPromote(projectRoot, homeDir, args) {
   let existing = '';
   try {
     existing = await fs.readFile(memoryMdPath, 'utf8');
-  } catch {
-    existing = '';
+  } catch (error) {
+    // C90-11: ENOENT is the only safe fallback — any other read failure
+    // (EACCES, EIO, EISDIR…) means MEMORY.md exists but is unreadable, and
+    // proceeding would overwrite it with a fresh block, destroying the
+    // user's content. Abort with the original error.
+    if (error?.code !== 'ENOENT') {
+      throw new Error(
+        `memory promote: cannot read ${memoryMdPath} (${error?.code ?? error})`
+        + ' — fix permissions or remove the file before promoting.',
+      );
+    }
   }
 
   const outsideIds = externallyReferencedIds(existing);

package/src/cli/commands/telemetry.js

@@ -39,6 +39,7 @@ import {
 import { maybeRefreshSupport } from '../../core/observability/support/schedule.js';
 import { resolveSupportDir, SUPPORT_DIR_NAME } from '../../core/observability/support/paths.js';
 import { validateSupportBundle } from '../../core/observability/support/import.js';
+import { isValidOperationId } from '../../core/agentRuntime/eventStore.js';
 import { runEvaluation } from '../../core/observability/evaluation/runner.js';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
@@ -380,6 +381,16 @@ async function exportSupportCommand({ projectRoot, config }) {
  * writes by contract (SPEC G7-FR04).
  */
 async function exportRunCommand({ projectRoot, config, operationId }) {
+  // W2-A03: the operand becomes a journal/state filename inside
+  // agent-runtime. Validate it against the ONE canonical eventStore rule
+  // before any path/bundle work — a traversal opId is a usage error, not a
+  // degraded bundle.
+  if (!isValidOperationId(operationId)) {
+    console.error('[UKit] export-run: invalid_operation_id');
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
   const { exportSupportBundle } = await import('../../core/agentRuntime/diagnostics.js');
   const runtimeDir = path.join(projectRoot, '.ukit', 'storage', 'agent-runtime');
   let res;
@@ -454,10 +465,16 @@ export async function runTelemetry({ projectRoot, packageRoot, argv = [] }) {
   const args = Array.isArray(argv) ? argv : [];
   const sub = (args[0] ?? '').toLowerCase();
 
-  if (args.length === 0 || HELP_FLAGS.has(sub)) {
+  if (HELP_FLAGS.has(sub)) {
     printUsage();
     return;
   }
+  if (args.length === 0) {
+    // W2-A04: no subcommand is a usage error, not a no-op success.
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
   if (!SUBCOMMANDS.has(sub)) {
     console.error(`[UKit] Unknown telemetry subcommand: ${sub}`);
     printUsage();

package/src/cli/commands/vm.js

@@ -234,10 +234,16 @@ export async function runVm({ projectRoot, argv = [] }) {
   const args = Array.isArray(argv) ? argv : [];
   const sub = (args[0] ?? '').toLowerCase();
 
-  if (args.length === 0 || HELP_FLAGS.has(sub)) {
+  if (HELP_FLAGS.has(sub)) {
     printUsage();
     return;
   }
+  if (args.length === 0) {
+    // W2-A04: no subcommand is a usage error, not a no-op success.
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
   if (!SUBCOMMANDS.has(sub)) {
     console.error(`[UKit] Unknown vm subcommand: ${sub}`);
     printUsage();

package/src/context/detectProjectContext.js

@@ -11,7 +11,7 @@ function inferProjectName(projectRoot, packageJson) {
   return path.basename(projectRoot);
 }
 
-export async function detectProjectContext(projectRoot, { homeDir } = {}) {
+export async function detectProjectContext(projectRoot, { homeDir, mint = false } = {}) {
   const packageJsonPath = path.join(projectRoot, 'package.json');
   // A corrupt package.json must degrade to basename naming, not crash the
   // status/memory CLIs with a raw SyntaxError.
@@ -19,9 +19,14 @@ export async function detectProjectContext(projectRoot, { homeDir } = {}) {
 
   // Identity resolution must never break context detection: any resolver
   // failure degrades to `id: null` (SPEC §10 — deny-by-default downstream).
-  const identity = await resolveProjectIdentity(projectRoot, { homeDir })
+  // C92-C-03: `mint` defaults to false (fail-closed). Read-only commands
+  // (`ukit diff`, `ukit status`, `ukit memory list/recall`, `ukit self-improve`)
+  // must never create/modify ~/.ukit/storage/projects/registry.json or bind a
+  // generic alias — only `ukit install` opts in via `mint: !dryRun`.
+  const identity = await resolveProjectIdentity(projectRoot, { homeDir, mint })
     .catch(() => null);
 
+
   return {
     project: {
       root: projectRoot,

package/src/core/agentRuntime/contract.js

@@ -30,10 +30,14 @@ const STATE_SET = new Set(OPERATION_STATES);
 /**
  * Legal edges. `recovery_required` is reachable from every non-terminal state
  * and resolves to exactly one terminal state — it never re-enters `running`.
+ * `starting → failed` is the spawn-throw recovery edge (C92-E-02): a
+ * synchronous spawnImpl throw must be able to land the op terminal, or it
+ * strands non-terminally. Cancel before spawn does NOT get a direct edge —
+ * it routes `starting → cancel_pending → cancelled`.
  */
 const TRANSITIONS = Object.freeze({
   queued: new Set(['starting', 'recovery_required']),
-  starting: new Set(['running', 'cancel_pending', 'recovery_required']),
+  starting: new Set(['running', 'cancel_pending', 'failed', 'recovery_required']),
   running: new Set(['completed', 'failed', 'cancel_pending', 'retry_pending', 'recovery_required']),
   cancel_pending: new Set(['cancelled', 'recovery_required']),
   retry_pending: new Set(['running', 'cancel_pending', 'recovery_required']),

package/src/core/agentRuntime/eventStore.js

@@ -54,10 +54,32 @@ const STATE_DIR = 'state';
 const CONTINUATIONS_FILE = 'continuations.jsonl';
 const CONSUMPTIONS_FILE = 'consumptions.jsonl';
 
-const journalPath = (dir, operationId) =>
-  path.join(dir, JOURNAL_DIR, `${operationId}.jsonl`);
-const statePath = (dir, operationId) =>
-  path.join(dir, STATE_DIR, `${operationId}.json`);
+// W2-B2: operationId becomes a filename via path.join — anything outside a
+// strict filename charset, or containing a `..` segment (even 'a..b'), can
+// write or read a journal/state file OUTSIDE the store. Reject typed before
+// any path math. `:` is kept: engine opIds are `<planInstanceId>:<nodeId>`
+// (vmEngine/shadowRun) and it is not a path separator on any shipped host.
+// Exported (W2-A03): this is the ONE canonical opId rule — CLI surfaces
+// (telemetry export-run) must validate with it, never re-derive a copy.
+const OPERATION_ID_RE = /^[A-Za-z0-9._:-]+$/;
+
+export const isValidOperationId = (id) =>
+  typeof id === 'string' && OPERATION_ID_RE.test(id) && !id.includes('..');
+
+function assertOperationId(id) {
+  if (!isValidOperationId(id)) {
+    throw new EventStoreError('invalid_operation_id', `unsafe operationId ${JSON.stringify(id)}`);
+  }
+}
+
+const journalPath = (dir, operationId) => {
+  assertOperationId(operationId);
+  return path.join(dir, JOURNAL_DIR, `${operationId}.jsonl`);
+};
+const statePath = (dir, operationId) => {
+  assertOperationId(operationId);
+  return path.join(dir, STATE_DIR, `${operationId}.json`);
+};
 
 async function pathExists(p) {
   try {
@@ -70,7 +92,10 @@ async function pathExists(p) {
 
 /** Atomic write: temp file + fsync + rename (SPEC §6 migration/state windows). */
 async function writeFileAtomic(target, data) {
-  const tmp = `${target}.tmp-${process.pid}`;
+  // C90-15: pid-only tmp names collide between concurrent writers in one
+  // process (second rename ENOENTs the first writer's tmp). Per-call UUID
+  // makes each atomic write private.
+  const tmp = `${target}.tmp-${process.pid}-${crypto.randomUUID()}`;
   const handle = await fs.open(tmp, 'w');
   try {
     await handle.writeFile(data, 'utf8');
@@ -595,17 +620,23 @@ const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
 const isNonEmptyString = (v) => typeof v === 'string' && v.length > 0;
 const isPlainRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
+// W2-B3: artifacts are bounded at write time (~4 MiB) but the READ side was
+// unbounded — a stale/crafted ref named any in-root file and readFile
+// allocated the whole thing. Stat before read and refuse over the cap.
+const DEFAULT_MAX_RESOLVE_BYTES = 64 * 1024 * 1024;
+
 const unavailable = (reason) => ({ status: 'unavailable', reason });
 
 /**
  * Resolve a bounded run-artifact ref for an authorized caller.
  *
  * @param {object} ref `{path, sha256, bytes?, runId?, truncated?, sensitivity?}`
- * @param {object} scope `{runRoot, caller:{runId, role?}}`
+ * @param {object} scope `{runRoot, caller:{runId, role?}, maxBytes?}` —
+ *   `maxBytes` bounds the read (default 64 MiB); over-cap → `too_large`
  * @returns {Promise<{bytes:Uint8Array, sha256:string, truncated?:boolean}
  *           |{status:'unavailable', reason:string}>}
  */
-export async function resolveRunArtifact(ref, { runRoot, caller } = {}) {
+export async function resolveRunArtifact(ref, { runRoot, caller, maxBytes } = {}) {
   if (!isPlainRecord(caller) || !isNonEmptyString(caller.runId)) {
     return unavailable('unauthorized');
   }
@@ -649,6 +680,22 @@ export async function resolveRunArtifact(ref, { runRoot, caller } = {}) {
     if (err && err.code === 'ENOENT') return unavailable('missing');
     return unavailable('unreadable');
   }
+  // W2-B3: size-check BEFORE the read — stat is cheap, readFile of a
+  // multi-GB stale/crafted target is not. `isFile` also short-circuits
+  // directories that would otherwise hit readFile's EISDIR as 'unreadable'.
+  const cap = Number.isInteger(maxBytes) && maxBytes >= 0 ? maxBytes : DEFAULT_MAX_RESOLVE_BYTES;
+  let stat;
+  try {
+    stat = await fs.stat(real);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return unavailable('missing');
+    return unavailable('unreadable');
+  }
+  if (!stat.isFile()) return unavailable('unreadable');
+  if (stat.size > cap) return unavailable('too_large');
+  if (Number.isInteger(ref.bytes) && ref.bytes !== stat.size) {
+    return unavailable('bytes_mismatch');
+  }
   let bytes;
   try {
     bytes = await fs.readFile(real);

package/src/core/agentRuntime/recovery.js

@@ -127,16 +127,27 @@ export async function reconcileOwnedOperations(ctx) {
 
   const results = [];
   for (const operationId of await listOperationIds(runtimeDir)) {
-    results.push(await reconcileOne({
-      runtimeDir,
-      operationId,
-      processTable,
-      fencingEpoch,
-      ownerEpoch: undefined,
-      launchDisabled,
-      ctxOwnerEpoch: ctx?.ownerEpoch,
-      now,
-    }));
+    try {
+      results.push(await reconcileOne({
+        runtimeDir,
+        operationId,
+        processTable,
+        fencingEpoch,
+        ownerEpoch: undefined,
+        launchDisabled,
+        ctxOwnerEpoch: ctx?.ownerEpoch,
+        now,
+      }));
+    } catch (err) {
+      // W2-B2 follow-on: ids are enumerated from on-disk filenames — a stale
+      // entry the store now rejects (e.g. a legacy `..` name) must not abort
+      // the whole reconcile; record it skipped and move on.
+      results.push({
+        operationId,
+        resolution: 'skipped',
+        code: typeof err?.code === 'string' ? err.code : 'reconcile_error',
+      });
+    }
   }
   return { results };
 }
@@ -249,11 +260,7 @@ async function reconcileOne({
 
   // --- no live owned process ------------------------------------------------
   if (Number.isInteger(stateRec?.exitStatus)) {
-    const to = stateRec.exitStatus === 'cancelled'
-      ? 'cancelled'
-      : stateRec.exitStatus === 0
-        ? 'completed'
-        : 'failed';
+    const to = stateRec.exitStatus === 0 ? 'completed' : 'failed';
     return persistTerminal(effectiveState, to, 'exited_unconfirmed');
   }
   // Gone without outcome (or still starting): ambiguous — recovery_required,