@ngockhoale/ukit 3.4.27 → 3.4.28

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to UKit are documented here.
 
+## Unreleased
+
+**`/ukit:ci-check`: manual-only cross-platform CI (not yet released; no version bump).**
+- `cross-platform-ci.yml` is now `workflow_dispatch` only (push trigger removed). No push/pull_request/schedule/workflow_run path can start CI.
+- New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
+- Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
+
+## 3.4.28 - 2026-10-09
+
+**Release-safety close-out: config preservation, safe `ukit update`, OMP eval/Bash hardening (local RC; not yet published).**
+- **U1 `.claude/settings.json` ownership merge.** User `model`, `permissions.allow|deny|ask`, `permissions.defaultMode`, user environment entries, `statusLine`, plugins and unknown keys survive install/update. UKit-owned: `hooks` (safety wiring) and the template's own environment keys. Permission lists are a union (template entries always present). Behaviour change: user-added top-level keys no longer count as drift.
+- **U2 `.ukit/storage/config.json` ownership merge** (`src/core/runtimeConfigMerge.js`). User values (model routing, `autonomy`, `orchestration.permissionMode`, thresholds, unknown keys) win; new template keys are filled; `version`/`agent`/`_help` follow the release. The opt-in `orchestration.allowUnsafeEval` is reset to `false` on every upgrade and reported. A merge that would produce an invalid config leaves the file untouched; a corrupt file is replaced (timestamped backup first).
+- **F5 safe `ukit update`.** Preflight (npm runnable, install metadata readable, project writable), project snapshot with sha256 manifest before `npm install -g`, automatic restore + hash verification when the project refresh fails. The global package is **never** rolled back automatically: the output says so and prints `npm install -g @ngockhoale/ukit@<previous>`. Last 3 snapshots kept under `.claude/ukit/.ukit/update-snapshots/`.
+- **F1 OMP `eval` payload** (`{language, code}`) is now seen by the Bash guard chain (was an empty command).
+- **F2 OMP `eval` default-deny** in the bridge itself (independent of `.omp/config.yml`): allowed only with `orchestration.allowUnsafeEval=true`. The guard is best-effort for eval; threat model in `docs/release/MULTI-ENGINE-RELEASE-GATE.md`.
+- **F4 OMP Bash/eval fail closed** on hook-runner transport failure (no verdict = no execution). Read/Grep/Glob stay fail-open. User escape hatch: `UKIT_OMP_BASH_FAIL_OPEN=1`. The Stop lane is unaffected (no Stop loop).
+- Known limits: OMP tools `task`, MCP, `browser`, `user_bash`, `user_python` have no UKit guard chain; the Read/Grep secret guard is advisory on a runner outage.
+
 ## 3.4.27 - 2026-10-09
 
 **Stop-gate evidence loop hardening and linked-worktree isolation (follow-up to 3.4.26).**

package/manifests/documentation.yaml

@@ -418,6 +418,28 @@ entries:
     validation: [none]
     archive_policy: immutable
     notes: C99 measurement-only sub-agent cost audit snapshot; registered in 3.4.25 (was unclassified on 3.4.24)
+  - id: docs-analysis-c100-frag-a-d
+    path: docs/analysis/c100/frag-A-D.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/c100/frag-A-D.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: C100 report fragment A+D (cache-accounting trace, model/provider confidence, telemetry gaps); landed pre-integration, registered during MB-1
+  - id: docs-analysis-c100-frag-b-c
+    path: docs/analysis/c100/frag-B-C.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/c100/frag-B-C.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: C100 report fragment B+C (127-agent fan-out findings, root cause, productive vs avoidable); landed pre-integration, registered during MB-1
   - id: docs-skill-audits
     path: docs/skill-audits/
     class: archive
@@ -754,6 +776,7 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+    local_only: true
   - id: mirror-omp-dir
     path: .omp/
     class: derived
@@ -774,6 +797,7 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+    local_only: true
 
   # ── Same-wave additions (DOC-201 batch; files authored by TASK-208/212) ────
   - id: docs-host-capability-matrix
@@ -821,6 +845,41 @@ entries:
     archive_policy: never
     notes: C69 G7 operator doc — timeline render, support bundle contents/exclusions, replay limits
 
+  - id: docs-design-ci-cross-platform-matrix
+    path: docs/design/CI-CROSS-PLATFORM-MATRIX.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/design/CI-CROSS-PLATFORM-MATRIX.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: C100 native CI matrix design (macOS/Windows/Linux); maintainer-only, not shipped to user projects
+
+  - id: docs-release-multi-engine-release-gate
+    path: docs/release/MULTI-ENGINE-RELEASE-GATE.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/release/MULTI-ENGINE-RELEASE-GATE.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: OMP-first multi-engine release gate report (3.4.28 candidate); maintainer-only, not shipped to user projects
+
+  - id: docs-release-3-4-28-team-upgrade-notice
+    path: docs/release/3.4.28-TEAM-UPGRADE-NOTICE.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/release/3.4.28-TEAM-UPGRADE-NOTICE.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Team upgrade notice for 3.4.28 (local RC); maintainer-only, not shipped to user projects
 # Declared complexity→docs mapping consumed by the router's `docs=` summary segment
 # (src/index/taskRouting.js CONTEXT_LAYER_DOCS mirrors this block; DOC-201 FR-001/002).
 # queued-task intent omitted v1: docs/TASKS.md is optional per-repo (SPEC §14).

package/manifests/platform.full.yaml

@@ -1174,6 +1174,18 @@ items:
     packs:
       - core
 
+  - id: command-ci-check
+    type: command
+    sourceTemplate: .claude/commands/ukit/ci-check.md
+    targetPath: .claude/commands/ukit/ci-check.md
+    requires:
+      - ukit-ci-check-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: command-handoff-fullstack
     type: command
     sourceTemplate: .claude/commands/ukit/handoff-fullstack.md
@@ -1629,6 +1641,18 @@ items:
     packs:
       - core
 
+  - id: ukit-ci-check-script
+    type: config
+    sourceTemplate: .claude/ukit/index/ci-check.mjs
+    targetPath: .claude/ukit/index/ci-check.mjs
+    requires:
+      - ukit-index-safe-patch-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-provision-worktree-script
     type: config
     sourceTemplate: .claude/ukit/index/provision-worktree.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.27",
+  "version": "3.4.28",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,10 @@
     "bin/",
     "src/",
     "scripts/",
+    "!scripts/audit/c100/attribution-gap.mjs",
+    "!scripts/audit/c100/implementer-attribution.mjs",
+    "!scripts/audit/c100/trees-lifetimes.mjs",
+    "!scripts/audit/c100/usage-provenance.mjs",
     "template_project/",
     "template_user/",
     "!template_project/**/.smbdelete*",
@@ -59,6 +63,7 @@
     "worktree:preflight": "node ./scripts/dev/worktree-preflight.mjs",
     "docs:render": "node scripts/docs/render-instructions.mjs --write",
     "docs:render:check": "node scripts/docs/render-instructions.mjs --check",
+    "test:python:setup": "node tests/python/setup-test-venv.mjs",
     "test:artifact": "vitest run tests/integration/packageArtifact.test.js tests/integration/artifactReferenceIntegrity.test.js",
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",

package/scripts/audit/subagent-cost/metrics.mjs

@@ -39,9 +39,21 @@ const totalFor = (calls) => ({
   uncached: calls.reduce((n, c) => n + uncached(c), 0),
   inputSide: calls.reduce((n, c) => n + inputSide(c), 0),
 });
+// Cache metadata is only trustworthy when the read key was recorded (present_zero/present_positive).
+// Absent/invalid calls are excluded from the hit-rate denominator — they are UNKNOWN, not a miss.
+// Calls without a status (historical corpora built before MB-1) are treated as recorded.
+const cacheKnown = (call) => call.cacheMetadataStatus == null
+  || call.cacheMetadataStatus === 'present_zero' || call.cacheMetadataStatus === 'present_positive';
 const cacheFor = (calls) => {
-  const totals = totalFor(calls);
-  return { hitRate: ratio(totals.cacheRead, totals.inputSide), cacheRead: totals.cacheRead, inputSide: totals.inputSide };
+  const known = calls.filter(cacheKnown);
+  const totals = totalFor(known);
+  return {
+    hitRate: ratio(totals.cacheRead, totals.inputSide),
+    cacheRead: totals.cacheRead,
+    inputSide: totals.inputSide,
+    knownCalls: known.length,
+    unknownCalls: calls.length - known.length,
+  };
 };
 const sortedTop = (items, getValue, getKey) => [...items]
   .map((item) => ({ ...item, uncached: getValue(item), inputSide: getKey(item) }))

package/scripts/audit/subagent-cost/reader.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash } from 'node:crypto';
+import { classifyCacheRead, classifyCacheWrite, cacheMetadataStatus, extractIdentity } from './usage-fields.mjs';
 
 const sha1 = (value) => createHash('sha1').update(value).digest('hex').slice(0, 12);
 const timestampMs = (value) => {
@@ -82,12 +83,15 @@ async function readMeta(file) {
   }
 }
 
-function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs) {
+function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs, meta = null) {
   const message = record.message ?? {};
   const usage = message.usage ?? {};
   const input = Number(usage.input_tokens) || 0;
-  const cacheRead = Number(usage.cache_read_input_tokens ?? usage.cache_read_tokens) || 0;
-  const cacheWrite = Number(usage.cache_creation_input_tokens ?? usage.cache_creation_tokens) || 0;
+  const readMetric = classifyCacheRead(usage);
+  const writeMetric = classifyCacheWrite(usage);
+  const cacheRead = readMetric.value;
+  const cacheWrite = writeMetric.value;
+  const identity = extractIdentity(record, meta);
   const output = Number(usage.output_tokens) || 0;
   const key = message.id ?? record.requestId ?? record.uuid;
   return {
@@ -102,6 +106,13 @@ function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs) {
     input,
     cacheRead,
     cacheWrite,
+    cacheReadStatus: readMetric.status,
+    cacheWriteStatus: writeMetric.status,
+    cacheMetadataStatus: cacheMetadataStatus(readMetric, writeMetric),
+    providerId: identity.providerId,
+    gatewayId: identity.gatewayId,
+    taskId: identity.taskId,
+    spawnPrefixHash: identity.spawnPrefixHash,
     output,
     zero: input === 0 && cacheRead === 0 && cacheWrite === 0 && output === 0,
     depth,
@@ -181,6 +192,7 @@ export async function loadCorpus(root, { since = null, until = null } = {}) {
         depth,
         ts,
         previousTs,
+        meta,
       );
       previousTs = ts;
       const key = call._dedupeKey ?? `line:${stats.lines}`;

package/scripts/audit/subagent-cost/usage-fields.mjs

@@ -0,0 +1,82 @@
+// MB-1 (C100) — telemetry correctness helpers shared by the sub-agent cost reader.
+// Pure, local, no LLM calls. Rules: a missing/invalid usage field is NEVER a measured zero;
+// an explicit 0 stays 0; provider/gateway/task/prefix identity is read only from explicit
+// allowlisted keys (the model name is never a signal) and unknown stays null.
+
+export const CACHE_STATUS = Object.freeze({
+  PRESENT_ZERO: 'present_zero',
+  PRESENT_POSITIVE: 'present_positive',
+  ABSENT: 'absent',
+  INVALID: 'invalid',
+});
+
+const READ_KEYS = ['cache_read_input_tokens', 'cache_read_tokens'];
+const WRITE_KEYS = ['cache_creation_input_tokens', 'cache_creation_tokens'];
+const PROVIDER_KEYS = ['providerId', 'provider_id', 'provider', 'apiProvider'];
+const GATEWAY_KEYS = ['gatewayId', 'gateway_id', 'gatewayName', 'gateway'];
+const MAX_ID_LENGTH = 128;
+const SAFE_ID = /^[A-Za-z0-9._:/@-]{1,128}$/;
+const SECRET_LIKE = /sk-[A-Za-z0-9]{8,}|bearer|secret|passw|token=|key=|api[_-]?key/i;
+
+function numericOrNull(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? raw : null;
+  if (typeof raw === 'string' && raw.trim() !== '') {
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : null;
+  }
+  return null;
+}
+
+/** Classify one cache metric. `value` is only the measured number; 0 for absent/invalid is a
+ * summing convenience — consumers must read `status`, never infer a miss from value 0. */
+export function classifyCacheMetric(usage, keys) {
+  if (!usage || typeof usage !== 'object') return { status: CACHE_STATUS.ABSENT, value: 0 };
+  for (const key of keys) {
+    const raw = usage[key];
+    if (raw === undefined || raw === null) continue;
+    const value = numericOrNull(raw);
+    if (value === null || value < 0) return { status: CACHE_STATUS.INVALID, value: 0 };
+    return { status: value === 0 ? CACHE_STATUS.PRESENT_ZERO : CACHE_STATUS.PRESENT_POSITIVE, value };
+  }
+  return { status: CACHE_STATUS.ABSENT, value: 0 };
+}
+
+export const classifyCacheRead = (usage) => classifyCacheMetric(usage, READ_KEYS);
+export const classifyCacheWrite = (usage) => classifyCacheMetric(usage, WRITE_KEYS);
+
+/** Combined status for a call: a known read status wins; otherwise the worse of the pair. */
+export function cacheMetadataStatus(read, write) {
+  if (read.status === CACHE_STATUS.INVALID || write.status === CACHE_STATUS.INVALID) return CACHE_STATUS.INVALID;
+  if (read.status === CACHE_STATUS.ABSENT) return CACHE_STATUS.ABSENT;
+  return read.status;
+}
+
+function safeId(raw) {
+  if (typeof raw !== 'string') return null;
+  const value = raw.trim();
+  if (value.length === 0 || value.length > MAX_ID_LENGTH) return null;
+  if (!SAFE_ID.test(value) || SECRET_LIKE.test(value)) return null;
+  return value;
+}
+
+function firstId(sources, keys) {
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+    for (const key of keys) {
+      const id = safeId(source[key]);
+      if (id) return id;
+    }
+  }
+  return null;
+}
+
+/** Identity metadata from explicit keys only; null means UNKNOWN (never a guessed value). */
+export function extractIdentity(record, meta = null) {
+  const sources = [record, record?.message, meta];
+  return {
+    providerId: firstId(sources, PROVIDER_KEYS),
+    gatewayId: firstId(sources, GATEWAY_KEYS),
+    taskId: firstId(sources, ['taskId', 'task_id']),
+    spawnPrefixHash: firstId(sources, ['spawnPrefixHash', 'spawn_prefix_hash']),
+  };
+}

package/src/cli/commands/update.js

@@ -1,8 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { preflightUpdate, createUpdateSnapshot, restoreUpdateSnapshot } from '../../core/updateSafety.js';
 import { updateUkit, runInstallAfterUpdate, readInstalledGlobalVersion, UKIT_PACKAGE_NAME } from '../../core/update.js';
 
 const KNOWN_UPDATE_FLAGS = new Set(['--help', '-h', '--no-install']);
 
-export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd() }) {
+const projectHasUkit = (cwd) => ['.ukit', path.join('.claude', 'ukit')].some((m) => fs.existsSync(path.join(cwd, m)));
+const INSTALL_FAILURE = /^install-(failed|exited)/;
+
+export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd(), safety = { preflightUpdate, createUpdateSnapshot, restoreUpdateSnapshot } }) {
   if (argv.includes('--help') || argv.includes('-h')) {
     console.log('Usage: ukit update [--no-install]');
     console.log('');
@@ -28,9 +34,39 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
   }
 
   console.log(`[UKit] Version before update: ${packageVersion}`);
+
+  // F5: preflight + project snapshot BEFORE anything changes. A failed preflight aborts
+  // with nothing modified; the snapshot is what makes a failed project refresh recoverable.
+  const refreshWanted = !argv.includes('--no-install') && projectHasUkit(cwd);
+  let snapshot = null;
+  if (refreshWanted) {
+    const pre = await safety.preflightUpdate({ projectRoot: cwd });
+    if (!pre.ok) {
+      console.log('[UKit] Update NOT started — preflight failed, nothing was changed:');
+      for (const problem of pre.problems) console.log(`  - ${problem}`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      snapshot = await safety.createUpdateSnapshot({ projectRoot: cwd, previousGlobalVersion: packageVersion });
+      console.log(`[UKit] Project snapshot saved: ${path.relative(cwd, snapshot.dir) || snapshot.dir}`);
+    } catch (error) {
+      console.log(`[UKit] Update NOT started — could not snapshot the project (${error.message}). Nothing was changed.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   console.log(`[UKit] Running: npm install -g ${UKIT_PACKAGE_NAME}`);
 
-  updateUkit();
+  try {
+    updateUkit();
+  } catch (error) {
+    console.log(`[UKit] npm update failed: ${error.message}`);
+    console.log('[UKit] The project was not touched. The global package may be partially installed — run `ukit --version` to check, then retry `ukit update`.');
+    process.exitCode = 1;
+    return;
+  }
 
   // This process still runs the OLD code, so report the version the update actually
   // installed (read from disk), never the stale `packageVersion`.
@@ -72,5 +108,26 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
     return;
   }
   console.log(`[UKit] CLI upgraded, but the project refresh did not finish (${reason}).`);
+  process.exitCode = 1;
+  if (snapshot && INSTALL_FAILURE.test(reason || '')) {
+    let result;
+    try {
+      result = await safety.restoreUpdateSnapshot({ projectRoot: cwd, snapshotDir: snapshot.dir });
+    } catch (error) {
+      result = { ok: false, failures: [error.message], mismatches: [] };
+    }
+    if (result.ok) {
+      console.log(`[UKit] PROJECT files restored from the snapshot and verified (${result.restored} files).`);
+    } else {
+      console.log('[UKit] PROJECT restore was incomplete — snapshot kept for manual recovery:');
+      for (const item of [...result.failures, ...result.mismatches]) console.log(`  - ${item}`);
+      console.log(`[UKit] Snapshot: ${snapshot.dir}`);
+    }
+    // Never imply a full rollback: only project files were restored.
+    console.log(`[UKit] The GLOBAL package was NOT rolled back — it is still ${installedVersion ?? 'the new version'}, while this project is on the previous files.`);
+    console.log(`[UKit] To return to the old CLI as well: npm install -g ${UKIT_PACKAGE_NAME}@${packageVersion}`);
+    console.log('[UKit] To retry the migration with the new CLI: ukit install');
+    return;
+  }
   console.log('[UKit] Run `ukit install` to retry.');
 }

package/src/core/agentRuntime/context.js

@@ -15,6 +15,7 @@ import crypto from 'node:crypto';
 
 import { validateTaskContract } from './contract.js';
 import { eligible } from '../memory/policy.js';
+import { isSensitivePath } from '../../index/sensitivePath.js';
 
 const STALE_MS = 15 * 60 * 1000; // default freshness window for evidence
 
@@ -491,3 +492,80 @@ export async function buildSubagentContext({
     contextRefs,
   };
 }
+
+// --- TASK-B3 (PLAN-ENDUR-B §B3): context pack → delegation candidates -------
+// Pure mapping from a buildContextPack result (TASK-B2, plain data) into
+// candidates for buildSubagentContext. No fs/config/network/LLM access here —
+// the pack is supplied by the caller; this module stays I/O-free.
+//
+// Freshness honesty (documented choice, TASK-B3 Discussion): the pack carries
+// no generation timestamp (B2 is clock-free), so "not fresh" is expressed via
+// the EXISTING observedAt/ttlMs staleness path of buildSubagentContext —
+// no new exclusion machinery, no change to its output shape:
+// - fresh pack (stale:false, fallback:null): observedAt = mapping `now`,
+//   ttlMs = STALE_MS → included while within the default evidence window.
+// - degraded pack (stale:true OR fallback set): observedAt = 0, ttlMs = 0 →
+//   excluded 'stale' by any real downstream clock (nowMs > 0). Candidates are
+//   still mapped (visible as excluded manifest items), never fresh-labeled.
+// Sensitive paths use the shared pure predicate src/index/sensitivePath.js
+// (same one contextPack.js uses — no mirrored copy) and map with
+// sensitivity:'sensitive' so the existing redaction path excludes them.
+
+// Deterministic content text over path/reason/outline only. Outline order is
+// authoritative from the pack (B2 emits line-sorted outlines).
+function packEntryText(entry) {
+  const lines = [
+    `path: ${entry.path}`,
+    `reason: ${isNonEmptyStr(entry.reason) ? entry.reason : 'unknown'}`,
+  ];
+  for (const symbol of Array.isArray(entry.outline) ? entry.outline : []) {
+    if (symbol == null || typeof symbol !== 'object' || !isNonEmptyStr(symbol.name)) {
+      continue;
+    }
+    const type = isNonEmptyStr(symbol.type) ? symbol.type : 'symbol';
+    const signature = isNonEmptyStr(symbol.signature) ? ` ${symbol.signature}` : '';
+    lines.push(`symbol: ${symbol.name} (${type})${signature}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Map a buildContextPack result to buildSubagentContext candidates (pure).
+ *
+ * @param {object|null} pack buildContextPack result; malformed input maps to [].
+ * @param {object} [options]
+ * @param {number} [options.now] Mapping clock; anchors fresh candidates'
+ *   observedAt (default Date.now(), matching module convention).
+ * @returns {Array<object>} One candidate per pack file: ref `pack:<path>`,
+ *   kind 'evidence', provenance 'context-pack', required:false, deterministic
+ *   content; degraded packs (stale/fallback) carry observedAt:0/ttlMs:0 so the
+ *   existing staleness path excludes them; sensitive paths carry
+ *   sensitivity:'sensitive' for the existing redaction path.
+ */
+export function contextPackToCandidates(pack, { now } = {}) {
+  const nowMs = typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
+  const files = pack != null && typeof pack === 'object' && Array.isArray(pack.files)
+    ? pack.files
+    : [];
+  const degraded = pack?.stale === true || pack?.fallback != null;
+  const observedAt = degraded ? 0 : nowMs;
+  const ttlMs = degraded ? 0 : STALE_MS;
+
+  const candidates = [];
+  for (const entry of files) {
+    if (entry == null || typeof entry !== 'object' || !isNonEmptyStr(entry.path)) {
+      continue;
+    }
+    candidates.push({
+      ref: `pack:${entry.path}`,
+      content: packEntryText(entry),
+      required: false,
+      kind: 'evidence',
+      provenance: 'context-pack',
+      observedAt,
+      ttlMs,
+      ...(isSensitivePath(entry.path) ? { sensitivity: 'sensitive' } : {}),
+    });
+  }
+  return candidates;
+}