create-agdf 0.20.2 → 0.31.0

package/runtime/core/lib/control-maintenance/presentation.js

@@ -1,122 +1,30 @@
-import { interactionLocales } from "../resources/context.js";
-import { localePack } from "../interaction-presentation.js";
-import { controlCounts } from "./contract.js";
-
-export function renderMaintenanceOffer(control, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).repositoryMaintenance;
-  return [renderControlMigration(control, { registry, language, details }),
-    `[1] ${copy.start}`, `[2] ${copy.later}`, `[3] ${copy.details}`].join("\n");
-}
-
-export function renderMaintenanceResult(report, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).repositoryMaintenance;
-  if (report.inspection_state !== "complete") return `${copy.unavailable}: ${report.target}\n${report.diagnostics.map((item) => item.code).join("\n")}`;
-  return [renderControlMigration(report.compatibility, { registry, language, details }),
-    ...report.diagnostics.map((item) => `${item.run_id ? `${item.run_id}: ` : ""}${item.code}${item.path ? `: ${item.path}` : ""}`),
-    `${copy.title}: ${copy.outcomes[report.maintenance_outcome]}`].join("\n");
-}
-
-export function renderStartupControlNotice(facts, { registry = interactionLocales, language = "en", platform = process.platform } = {}) {
-  if (!facts.invocation) return "";
-  const pack = localePack(registry, language);
-  const copy = pack.repositoryMaintenance;
-  const migration = pack.installSetup.controlMigration;
-  const quote = platform === "win32" ? (value) => `'${String(value).replaceAll("'", "''")}'`
-    : (value) => `'${String(value).replaceAll("'", `'"'"'`)}'`;
-  const command = [facts.invocation.executable, ...facts.invocation.argv].map(quote).join(" ");
-  return [copy.title, `${migration.target}: ${facts.target}`,
-    facts.status === "unavailable" ? copy.unavailable : `${migration.state}: ${migration.states[facts.status]}`,
-    ...(facts.counts ? [replacement(migration.eligibleDescription, { count: facts.counts.migration }),
-      replacement(migration.blockedDescription, { count: facts.counts.repair })] : []),
-    copy.next, `${platform === "win32" ? "& " : ""}${command}`].join("\n");
-}
-
-function replacement(template, values = {}) {
-  return Object.entries(values).reduce((current, [key, value]) => current.replaceAll(`{${key}}`, String(value)), template);
-}
-
-export function renderControlMigration(control, { registry = interactionLocales, language = "en", details = false } = {}) {
-  if (!control || control.status === "not_checked") return "";
-  const copy = localePack(registry, language).installSetup.controlMigration;
-  const lines = ["", copy.title, `${copy.target}: ${control.target}`,
-    `${copy.state}: ${copy.states[control.status]}`];
-  const { migration: eligible, repair } = controlCounts(control);
-  if (eligible) lines.push(replacement(copy.eligibleDescription, { count: eligible }));
-  if (repair) lines.push(replacement(copy.blockedDescription, { count: repair }));
-  if (control.changes.length) lines.push(replacement(copy.changed, { count: control.changes.length }));
-  if (control.repair) {
-    const repairCopy = localePack(registry, language).installSetup.controlRepair;
-    lines.push(replacement(repairCopy.repairedDescription, { count: control.repair.items.filter((item) => item.outcome === "repaired").length }));
-    for (const item of control.repair.items.filter((item) => !item.available)) {
-      for (const finding of item.required) lines.push(`${item.run_id}: ${repairCopy.reasons[finding.code] ?? repairCopy.manualDescription}${finding.path ? `: ${finding.path}` : ""}`);
-    }
-  }
-  if (!details) {
-    if (control.diagnostics.length && !repair) lines.push(copy.repairDescription);
-    if (eligible || repair || control.diagnostics.length) lines.push(copy.detailsDescription);
-    return lines.join("\n");
-  }
-  lines.push(`${copy.format}: ${control.supported_control_state_version}`,
-    replacement(copy.historicalCount, { count: control.runs.filter((run) => run.status === "historical").length }));
-  for (const run of control.runs.filter((entry) => entry.status !== "current" && entry.status !== "historical")) {
-    lines.push(`${run.run_id}: ${copy.states[run.status]}`);
-    for (const finding of run.diagnostics) lines.push(`  ${finding.code}${finding.path ? `: ${finding.path}` : ""}`);
-  }
-  for (const diagnostic of control.diagnostics) lines.push(`${diagnostic.code}${diagnostic.path ? `: ${diagnostic.path}` : ""}`);
-  for (const change of control.changes) lines.push(`${change.run_id}: ${copy.backup}: ${change.backup}`);
-  if (control.status === "migration_required") lines.push(copy.migrationDescription, copy.manualDescription, copy.legacyDescription);
-  if (control.status === "repair_required") lines.push(copy.repairDescription);
-  return lines.join("\n");
-}
-
-export function renderControlMigrationDecision(plan, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).installSetup.controlMigration;
-  const lines = [renderControlMigration(plan.control, { registry, language, details }),
-    replacement(copy.batchDescription, { count: plan.runs.length }), copy.backupDescription];
-  if (plan.approval_reset_count) lines.push(replacement(copy.resetDescription, { count: plan.approval_reset_count }));
+import { interactionLocales } from '../resources/context.js';
+import { localePack } from '../interaction-presentation.js';
+import { controlCounts } from './contract.js';
+
+export function renderControlCompatibility(control, { registry = interactionLocales, language = 'en', details = false } = {}) {
+  if (!control || control.status === 'not_checked') return '';
+  const pack = localePack(registry, language), copy = pack.installSetup.controlCompatibility;
+  const counts = controlCounts(control);
+  const lines = ['', pack.repositoryMaintenance.title, `${copy.target}: ${control.target}`,
+    `${copy.state}: ${copy.states[control.status] ?? control.status}`,
+    `run-folders-v1 · Run 4 · unsupported: ${counts.unsupported} · repair_required: ${counts.repair}`];
   if (details) {
-    for (const run of plan.runs) {
-      lines.push(`${copy.run}: ${run.run_id}`, `${copy.sourceRevision}: ${run.source_revision_id}`,
-        `${copy.nextGate}: ${run.next_gate}`,
-        ...run.prior_approvals.filter((row) => row.status !== "missing" || row.evidence)
-          .map((row) => `  ${row.gate}: ${row.status} (${row.evidence})`));
-    }
-    for (const diagnostic of plan.diagnostics) lines.push(`${diagnostic.run_id}: ${diagnostic.code}`);
-  }
-  lines.push(`[1] ${copy.migrateChoice}`, `[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`);
-  return lines.join("\n");
-}
-
-export function renderControlRepairOffer(control, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const copy = localePack(registry, language).installSetup.controlRepair;
-  return [renderControlMigration(control, { registry, language, details }), copy.searchDescription,
-    `[1] ${copy.startChoice}`, `[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`].join("\n");
-}
-
-export function renderControlRepairPlan(plan, { registry = interactionLocales, language = "en", details = false } = {}) {
-  const pack = localePack(registry, language).installSetup;
-  const copy = pack.controlRepair;
-  const candidates = plan.items.filter((item) => item.available);
-  const lines = [copy.title, `${pack.controlMigration.target}: ${plan.target}`,
-    replacement(copy.availableDescription, { count: candidates.length }), copy.backupDescription];
-  if (candidates.some((item) => item.approval_reset)) lines.push(copy.resetDescription);
-  for (const item of plan.items) {
-    lines.push(`${item.run_id}: ${copy.kinds[item.kind]}`);
-    for (const finding of item.required) lines.push(`  ${copy.reasons[finding.code] ?? copy.manualDescription}${finding.path ? `: ${finding.path}` : ""}`);
-    if (details) for (const source of item.sources) lines.push(`  ${source.path}: ${source.source} ${source.commit ?? source.journal ?? ""}`);
-    if (details && item.available && item.source_content !== item.candidate_content) {
-      const before = item.source_content.split("\n");
-      const after = item.candidate_content.split("\n");
-      let start = 0;
-      while (start < before.length && start < after.length && before[start] === after[start]) start++;
-      let end = 0;
-      while (end < before.length - start && end < after.length - start && before.at(-1 - end) === after.at(-1 - end)) end++;
-      lines.push(...before.slice(start, before.length - end).map((line) => `- ${line}`),
-        ...after.slice(start, after.length - end).map((line) => `+ ${line}`));
-    }
+    for (const finding of control.diagnostics) lines.push(`${finding.code}${finding.path ? `: ${finding.path}` : ''}`);
+    for (const run of control.runs) lines.push(`${run.run_id}: ${run.status}`, ...run.diagnostics.map(finding => `  ${finding.code}`));
   }
-  for (const finding of plan.diagnostics) lines.push(`${copy.manualDescription}${finding.path ? `: ${finding.path}` : ""}${details ? ` (${finding.code})` : ""}`);
-  if (candidates.length) lines.push(`[1] ${copy.applyChoice}`);
-  lines.push(`[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`);
-  return lines.join("\n");
+  return lines.join('\n');
+}
+export function renderMaintenanceResult(report, options = {}) {
+  if (report.inspection_state !== 'complete') return `${report.target}\n${report.diagnostics.map(item => item.code).join('\n')}`;
+  return [renderControlCompatibility(report.compatibility, options), ...report.diagnostics.map(item => item.code)].join('\n');
+}
+export function renderStartupControlNotice(facts, { registry = interactionLocales, language = 'en', platform = process.platform } = {}) {
+  if (!facts.invocation) return '';
+  const pack = localePack(registry, language), copy = pack.installSetup.controlCompatibility;
+  const quote = platform === 'win32' ? value => `'${String(value).replaceAll("'", "''")}'`
+    : value => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+  const command = [facts.invocation.executable, ...facts.invocation.argv].map(quote).join(' ');
+  return [pack.repositoryMaintenance.title, `${copy.target}: ${facts.target}`, `${copy.state}: ${copy.states[facts.status] ?? facts.status}`,
+    `${platform === 'win32' ? '& ' : ''}${command}`].join('\n');
 }

package/runtime/core/lib/control-maintenance/service.js

@@ -1,38 +1,10 @@
-import { isAbsolute } from "node:path";
-import { directoryIdentity } from "../control-state/run-store-inspection.js";
-import { inspectControlMigration } from "./compatibility.js";
-import { migrateInstallationControl } from "./migration.js";
-import { repairInstallationControl } from "./repair.js";
-import { maintenanceResult } from "./contract.js";
-
-export async function runControlMaintenance(target, { guided = false, chooseMaintenance, confirmMigration, confirmRepair, readGitOriginals } = {}) {
-  if (typeof target !== "string" || !isAbsolute(target)) throw new Error("AGDF_MAINTENANCE_TARGET_REQUIRED");
-  const identity = directoryIdentity(target);
-  const verifyTarget = () => {
-    const current = directoryIdentity(target);
-    if (current.realpath !== identity.realpath || current.dev !== identity.dev || current.ino !== identity.ino) {
-      throw new Error("AGDF_MAINTENANCE_TARGET_CHANGED: inspect the target again before applying a new plan");
-    }
-  };
-  const reviewed = (callback) => async (plan) => {
-    verifyTarget();
-    const decision = await callback(plan);
-    verifyTarget();
-    return decision;
-  };
-  const before = inspectControlMigration(target);
-  if (!guided || ["absent", "current"].includes(before.status)) return maintenanceResult(target, before, { operation: guided ? "guided" : "inspect" });
-  if (![chooseMaintenance, confirmMigration, confirmRepair].every((callback) => typeof callback === "function")) {
-    throw new Error("AGDF_MAINTENANCE_INTERACTION_REQUIRED");
-  }
-  if (await reviewed(chooseMaintenance)(structuredClone(before)) !== "start") {
-    return maintenanceResult(target, inspectControlMigration(target), { operation: "guided", outcome: "deferred" });
-  }
-  let after = await migrateInstallationControl(target, { mode: "safe", confirmMigration: reviewed(confirmMigration) });
-  const diagnostics = [...after.diagnostics];
-  after = await repairInstallationControl(after, { chooseRepair: () => "start", confirmRepair: reviewed(confirmRepair), readGitOriginals });
-  const changed = after.changes.length + (after.repair?.items.filter((item) => item.outcome === "repaired").length ?? 0);
-  const outcome = changed ? (after.status === "current" ? "applied" : "partial")
-    : diagnostics.length || after.repair?.status === "needs_input" ? "needs_input" : "deferred";
-  return maintenanceResult(target, after, { operation: "guided", outcome, diagnostics });
+import { isAbsolute } from 'node:path';
+import { directoryIdentity } from '../control-state/run-store-inspection.js';
+import { inspectControlCompatibility } from './compatibility.js';
+import { maintenanceResult } from './contract.js';
+export async function runControlMaintenance(target, { guided = false } = {}) {
+  if (typeof target !== 'string' || !isAbsolute(target)) throw Error('AGDF_MAINTENANCE_TARGET_REQUIRED');
+  if (guided) throw Error('AGDF_CONTROL_MIGRATION_UNSUPPORTED');
+  directoryIdentity(target);
+  return maintenanceResult(target, inspectControlCompatibility(target));
 }

package/runtime/core/lib/control-read/cockpit-pool.js

@@ -1,27 +1,41 @@
 import { Worker } from 'node:worker_threads';
 import { READ_LIMITS, ControlReadError } from './snapshot.js';
+export const READ_SESSION_CAPACITY = 4;
+export function createReadWorkerBudget(maximum = READ_SESSION_CAPACITY) {
+  if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > READ_SESSION_CAPACITY) throw Error('read_capacity_invalid');
+  const owners = new Set();
+  return Object.freeze({ acquire(owner) { if (owners.size >= maximum) return false; owners.add(owner); return true; },
+    release(owner) { owners.delete(owner); }, inspect() { return { occupied: owners.size, maximum }; } });
+}
 
 export class ReadWorkerPool {
   constructor(root, { timeout = READ_LIMITS.timeout, workerURL = new URL('./cockpit-worker.js', import.meta.url),
-    limits, maxOldGenerationSizeMb = 768 } = {}) {
+    limits, maxOldGenerationSizeMb = 768, budget } = {}) {
     this.root = root; this.timeout = timeout; this.workerURL = workerURL;
     this.limits = limits; this.maxOldGenerationSizeMb = maxOldGenerationSizeMb;
+    this.budget = budget;
     this.retiring = null; this.scope = null; this.changed = null; this.changeWaiter = null;
     this.worker = null; this.active = null; this.waiting = null; this.closed = false; this.sequence = 0;
   }
   #spawn() {
+    const token = {};
+    if (this.budget && !this.budget.acquire(token)) throw new ControlReadError('resource_limit');
     const env = { ...process.env }; delete env.AGDF_RUN_ID;
-    const worker = new Worker(this.workerURL, { workerData: { root: this.root, limits: this.limits }, env, execArgv: [],
-      resourceLimits: { maxOldGenerationSizeMb: this.maxOldGenerationSizeMb } });
+    let worker;
+    try { worker = new Worker(this.workerURL, { workerData: { root: this.root, limits: this.limits }, env, execArgv: [],
+      resourceLimits: { maxOldGenerationSizeMb: this.maxOldGenerationSizeMb } }); }
+    catch (e) { this.budget?.release(token); throw e; }
+    worker.once('exit', () => this.budget?.release(token));
     this.worker = worker;
-    worker.on('message', ({ id, result, error, changed }) => {
+    worker.on('message', ({ id, result, error, changed, phase }) => {
       if (this.worker !== worker) return;
+      if (phase === 'read_worker_ready') { if (this.active) this.active.startup_ms = performance.now() - this.active.started; return; }
       if (changed) {
         if (changed === this.scope?.snapshot_id) { this.changed = changed; this.changeWaiter?.finish(true); }
         return;
       }
       if (this.worker !== worker || this.active?.id !== id) return;
-      if (!error && result?.snapshot_id && ['snapshot', 'run', 'backlog_titles', 'document', 'context', 'artifact_readiness'].includes(this.active.request.operation)) {
+      if (!error && result?.snapshot_id && ['snapshot', 'run', 'document', 'context', 'artifact_readiness'].includes(this.active.request.operation)) {
         this.scope = { ...result, data: null }; this.changed = null;
         this.changeWaiter?.reject(new ControlReadError('cancelled'));
       }
@@ -34,6 +48,7 @@ export class ReadWorkerPool {
     clearTimeout(job.timer); job.signal?.removeEventListener('abort', job.abort);
     if (this.active === job) this.active = null;
     if (this.waiting === job) this.waiting = null;
+    this.lastTiming = { elapsed_ms: performance.now() - job.started, startup_ms: job.startup_ms ?? (job.reused ? 0 : null) };
     error ? job.reject(error) : job.resolve(result);
     this.#pump();
   }
@@ -59,21 +74,22 @@ export class ReadWorkerPool {
     try {
       if (!this.worker) this.#spawn();
       this.worker.postMessage({ id: job.id, ...job.request });
-    } catch { this.#reset('read_failed'); }
+    } catch (e) { this.#reset(e.code === 'resource_limit' ? 'resource_limit' : 'read_failed'); }
   }
-  request(request, signal) {
+  request(request, signal, { timeout = this.timeout } = {}) {
+    if (!Number.isFinite(timeout) || timeout <= 0) return Promise.reject(new ControlReadError('timeout'));
     if (this.closed) return Promise.reject(new ControlReadError('read_failed'));
     if (this.waiting) return Promise.reject(new ControlReadError('busy'));
     if (signal?.aborted) return Promise.reject(new ControlReadError('cancelled'));
     return new Promise((resolve, reject) => {
-      const job = { id: ++this.sequence, request, signal, resolve, reject };
+      const job = { id: ++this.sequence, request, signal, resolve, reject, started: performance.now(), reused: Boolean(this.worker) };
       job.abort = () => {
         if (this.active === job) {
           // The bounded read finishes inside its deadline; retain the immutable view for other readers.
           job.reject(new ControlReadError('cancelled'));
         } else this.#finish(job, new ControlReadError('cancelled'));
       };
-      job.timer = setTimeout(() => this.active === job ? this.#reset('timeout') : this.#finish(job, new ControlReadError('timeout')), this.timeout);
+      job.timer = setTimeout(() => this.active === job ? this.#reset('timeout') : this.#finish(job, new ControlReadError('timeout')), Math.min(timeout, this.timeout));
       signal?.addEventListener('abort', job.abort, { once: true });
       this.waiting = job; this.#pump();
     });

package/runtime/core/lib/control-read/cockpit-worker.js

@@ -12,10 +12,11 @@ const changes = createControlChangeObserver(workerData.root, () => {
 });
 parentPort.on('message', ({ id, operation, selector, snapshot, input }) => {
   try {
-    const result = operation === 'snapshot' ? reader.snapshot(input?.run_id)
+    const result = operation === 'snapshot' ? reader.snapshot(input?.run_id, input?.view)
       : operation === 'run' ? reader.run(selector, snapshot)
+      : operation === 'archive' ? reader.archive(selector, snapshot, input?.resource_id)
+      : operation === 'planned' ? reader.planned(selector, snapshot)
       : operation === 'artifact_readiness' ? reader.artifactReadiness(input.run_id, snapshot, input.gate, input.expected_revision_id)
-      : operation === 'backlog_titles' ? reader.backlogTitles(input?.row_ids, snapshot)
       : operation === 'document' ? reader.document(selector, snapshot, input?.run_id)
       : operation === 'freshness' ? reader.freshness(snapshot)
       : operation === 'context' ? reader.context(selector, snapshot)
@@ -23,7 +24,7 @@ parentPort.on('message', ({ id, operation, selector, snapshot, input }) => {
       : operation === 'validate_context' ? reader.validateContext(input.context_id, input.generation)
       : operation === 'invalidate_context' ? reader.invalidateContext()
       : (() => { throw Object.assign(Error('resource_denied'), { code: 'resource_denied' }); })();
-    if (result.snapshot_id && ['snapshot', 'run', 'backlog_titles', 'document', 'context', 'artifact_readiness'].includes(operation)) {
+    if (result.snapshot_id && ['snapshot', 'run', 'document', 'context', 'artifact_readiness'].includes(operation)) {
       current = result.snapshot_id; changes.bind(reader.dependencies());
     }
     parentPort.postMessage({ id, result });

package/runtime/core/lib/control-read/doctor-reader.js

@@ -0,0 +1,92 @@
+import { captureControlScope, ControlReadError } from './snapshot.js';
+import { resolveRuns } from '../control-state/run-state-resolver.js';
+import { evaluateDoctor, doctorInventoryFindings } from '../control-evaluation/doctor.js';
+import { aggregate } from '../control-state/aggregate.js';
+import { allowNoActiveRuns } from '../control-evaluation/shared.js';
+import { existsSync } from './fs.js';
+import { join } from 'node:path';
+
+const bytes = value => Buffer.byteLength(JSON.stringify(value));
+const error = code => { throw new ControlReadError(code); };
+const git = value => ({ gitValue: () => value?.head ?? null, gitPathList: (_root, args) => args[0] === 'diff' ? value?.tracked ?? null : value?.untracked ?? null });
+const summary = findings => ({ findings: findings.length, block: findings.filter(f => f.severity === 'block').length,
+  revise: findings.filter(f => f.severity === 'revise').length, warn: findings.filter(f => f.severity === 'warn').length });
+
+// Exactly one bounded observation per read worker. Core owns checks/aggregation;
+// the retained dependency scope owns consistency, not permission or persistence.
+export function createDoctorReader(root, { limits = {} } = {}) {
+  let scope, current, items, originalGit, allowEmpty, next = 0, invalidCount = 0, cacheBytes = 0;
+  const pages = new Map(), statuses = [], totals = { findings: 0, block: 0, revise: 0, warn: 0 };
+  let failed = false, unevaluated = 0, controlPresent = true;
+  function page(offset, snapshot, started = performance.now()) {
+    if (failed || !scope || JSON.stringify(originalGit) !== JSON.stringify(snapshot)) error('source_changed');
+    current.view.revalidate();
+    if (pages.has(offset)) return pages.get(offset);
+    if (offset !== next || pages.size >= 64) error(offset !== next ? 'diagnostic_cursor_invalid' : 'resource_limit');
+    let wanted = null;
+    const captured = scope.extend(() => {
+      const rows = [], start = performance.now(); let size = 0;
+      for (let index = offset; index < items.length && rows.length < (wanted ?? 20); index++) {
+        if (wanted === null && rows.length && performance.now() - start >= 2500) break;
+        const item = items[index];
+        const row = item.invalid ? { run_id: item.run_id, invalid: true, findings: doctorInventoryFindings(item.findings) }
+          : { run_id: item.run_id, report: evaluateDoctor(root, { runId: item.run_id, ignoreRunIdEnv: true }, git(originalGit)) };
+        if (bytes(row) > 500 * 1024) {
+          rows.push({ run_id: item.run_id, unevaluated: true, reason: 'resource_limit', findings: [] });
+        } else {
+          if (wanted === null && rows.length && size + bytes(row) > 500 * 1024) break;
+          rows.push(row); size += bytes(row);
+        }
+      }
+      if (wanted === null) wanted = rows.length;
+      return rows;
+    });
+    current = captured;
+    const rows = captured.data;
+    if (items.length && !rows.length) error('resource_limit');
+    const findings = rows.flatMap(row => row.invalid ? row.findings : row.report?.findings.map(f => ({ ...f, run_id: row.run_id })) ?? []);
+    const counts = summary(findings), nextTotals = Object.fromEntries(Object.keys(totals).map(k => [k, totals[k] + counts[k]]));
+    const end = offset + rows.length, nextUnevaluated = unevaluated + rows.filter(r => r.unevaluated).length;
+    const nextInvalid = invalidCount + rows.filter(r => r.invalid).length;
+    const nextStatuses = [...statuses, ...rows.filter(r => r.report).map(r => ({ run_id: r.run_id, status: r.report.status }))];
+    const complete = end === items.length && !nextUnevaluated;
+    const aggregated = aggregate(nextStatuses, { allowNoActiveRuns: allowEmpty });
+    const result = { schema_version: '1', available: true, status: complete ? nextInvalid ? 'block' : aggregated.status : 'partial',
+      target_dir: root, checked_at: current.view.observed_as_of, observed_as_of: scope.view.observed_as_of,
+      ...(complete && !nextInvalid && controlPresent && aggregated.empty_inventory ? { empty_inventory: aggregated.empty_inventory } : {}),
+      source_digest: current.view.digest, completeness: complete ? 'complete' : 'partial',
+      inventory: { state: !controlPresent ? 'absent' : nextInvalid ? 'incomplete' : end === items.length ? 'complete' : 'partial', active_count: items.filter(r => !r.invalid).length,
+        total_entries: items.length, accounted_count: end, evaluated_count: end - nextUnevaluated,
+        unevaluated_count: nextUnevaluated, remaining_count: items.length - end },
+      summary: complete ? nextTotals : counts, cumulative_summary: nextTotals, findings,
+      runs: rows.filter(r => r.report), invalid_entries: rows.filter(r => r.invalid), unevaluated_entries: rows.filter(r => r.unevaluated),
+      next_offset: end < items.length ? end : null, authorizes: false,
+      timing: { capture_and_evaluation_ms: performance.now() - started } };
+    if (bytes(result) > 512 * 1024 || cacheBytes + bytes(result) > 8 * 1024 * 1024) error('resource_limit');
+    next = end; unevaluated = nextUnevaluated; invalidCount = nextInvalid;
+    statuses.splice(0, statuses.length, ...nextStatuses); Object.assign(totals, nextTotals);
+    pages.set(offset, result); cacheBytes += bytes(result);
+    return result;
+  }
+  return Object.freeze({
+    open(input) {
+      if (scope) error('resource_denied');
+      const started = performance.now(); originalGit = input.git_snapshot;
+      if (!input.all_active) {
+        const selected = captureControlScope(root, () => evaluateDoctor(root, { ...(input.run_id ? { runId: input.run_id } : {}), ignoreRunIdEnv: true }, git(originalGit)), { limits });
+        return { ...selected.data, available: true, completeness: 'complete', source_digest: selected.view.digest,
+          observed_as_of: selected.view.observed_as_of, authorizes: false, next_offset: null,
+          timing: { capture_and_evaluation_ms: performance.now() - started } };
+      }
+      scope = captureControlScope(root, () => {
+        const resolved = resolveRuns(root, { allActive: true }), invalid = new Map();
+        for (const finding of resolved.findings) invalid.set(finding.run_id, [...(invalid.get(finding.run_id) ?? []), finding]);
+        return { items: [...resolved.runs.map(r => ({ run_id: r.run_id })), ...[...invalid].map(([run_id, findings]) => ({ run_id, invalid: true, findings }))]
+          .sort((a, b) => a.run_id.localeCompare(b.run_id)), allowEmpty: allowNoActiveRuns(root), controlPresent: existsSync(join(root, '.agdf/control')) };
+      }, { limits, retain: true });
+      current = scope; items = scope.data.items; allowEmpty = scope.data.allowEmpty; controlPresent = scope.data.controlPresent;
+      return page(0, originalGit, started);
+    },
+    page(input) { try { return page(input.offset, input.git_snapshot); } catch (e) { if (e.code !== 'diagnostic_cursor_invalid') failed = true; throw e; } },
+  });
+}

package/runtime/core/lib/control-read/doctor-worker.js

@@ -0,0 +1,11 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { createDoctorReader } from './doctor-reader.js';
+const reader = createDoctorReader(workerData.root, { limits: workerData.limits });
+parentPort.postMessage({ phase: 'read_worker_ready' });
+parentPort.on('message', ({ id, operation, input }) => {
+  try {
+    const result = operation === 'doctor_open' ? reader.open(input) : operation === 'doctor_page' ? reader.page(input)
+      : (() => { throw Object.assign(Error('resource_denied'), { code: 'resource_denied' }); })();
+    parentPort.postMessage({ id, result });
+  } catch (e) { parentPort.postMessage({ id, error: e.code ?? 'read_failed' }); }
+});

package/runtime/core/lib/control-read/fs.js

@@ -4,6 +4,24 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 // Only read owners import this seam. No global fs patch and no writer API.
 const context = new AsyncLocalStorage();
 const memo = new WeakMap();
+// Only a retained observation owner may inherit memoized facts after revalidation.
+export function inheritControlReadMemo(from, to) {
+  let cache = memo.get(from);
+  if (!cache) { cache = new Map(); memo.set(from, cache); }
+  memo.set(to, cache);
+}
+export const hasControlReadView = () => Boolean(context.getStore()?.view);
+export const currentControlReadView = () => context.getStore()?.view ?? null;
+// CLI readers retain their existing file scope; memoized work never survives a call.
+// MCP readers install a contained captured view before entering the same evaluators.
+export function withControlReadMemo(work) {
+  if (hasControlReadView()) return work();
+  const view = { ...native, lstatKindSync(path) {
+    const s = native.lstatSync(path);
+    return s.isSymbolicLink() ? 'symlink' : s.isDirectory() ? 'directory' : s.isFile() ? 'file' : 'other';
+  } };
+  return withControlReadView(view, work);
+}
 export function memoizeControlRead(key, work) {
   const view = context.getStore()?.view;
   if (!view) return work();

package/runtime/core/lib/control-read/snapshot.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import { resolve, join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
-import { withControlReadView } from './fs.js';
+import { withControlReadView, inheritControlReadMemo, hasControlReadView, currentControlReadView, statSync as viewStat, readFileSync as viewRead } from './fs.js';
 
 export const READ_LIMITS = Object.freeze({ files: 20_000, total: 256 * 1024 ** 2, file: 32 * 1024 ** 2,
   preview: 2 * 1024 ** 2, response: 8 * 1024 ** 2, timeout: 10_000 });
@@ -182,7 +182,8 @@ export function captureControlScope(rootInput, project, options = {}) {
   const input = resolve(rootInput), root = fs.realpathSync(input);
   if (!fs.lstatSync(input).isDirectory() || fs.lstatSync(input).isSymbolicLink()) fail('resource_denied');
   const control = join(root, '.agdf', 'control'), limits = { ...READ_LIMITS, ...options.limits };
-  const deadline = Date.now() + limits.timeout, entries = new Map();
+  let deadline = Date.now() + limits.timeout;
+  const entries = new Map();
   let total = 0, files = 0, frozen = false, building = true, fatal = null, sourceDigest = null;
   const absentError = code => Object.assign(Error('Observed entry absent'), { code });
   const guard = work => {
@@ -199,7 +200,10 @@ export function captureControlScope(rootInput, project, options = {}) {
   };
   function check() { if (building && Date.now() > deadline) fail('timeout'); }
   function pathOf(value) {
-    check(); const path = keyOf(value);
+    check(); let path = keyOf(value);
+    // The verified input root may use an OS alias (macOS /var -> /private/var).
+    // Normalize that root prefix only; never resolve arbitrary descendant symlinks.
+    if (path === input || path.startsWith(input + sep)) path = join(root, relative(input, path));
     if (path !== root && path !== join(root, '.agdf') && path !== control && !path.startsWith(control + sep)) fail('resource_denied');
     if (relative(control, path).split(sep).length > 128) fail('resource_limit');
     return path;
@@ -361,18 +365,65 @@ export function captureControlScope(rootInput, project, options = {}) {
     for (const [name, method] of Object.entries(methods)) view[name] = (...args) => guard(() => method(...args));
     return Object.freeze(view);
   }
-  const recording = makeView();
-  const recorded = withControlReadView(recording, () => project(recording));
-  if (recorded?.then) fail('read_failed');
-  recording.assertBoundary(); options.checkpoint?.('captured', root);
-  frozen = true; revalidate(deadline);
-  sourceDigest = hash(JSON.stringify([...entries].sort(([a], [b]) => a.localeCompare(b))
-    .map(([path, entry]) => [relative(root, path), entry.kind, entry.signature ?? entry.code, entry.digest ?? null, entry.children ?? null])));
-  // New view identity also gives the replay a fresh memo cache in the FS seam.
-  const view = makeView(); options.checkpoint?.('replay', root);
-  const data = withControlReadView(view, () => project(view));
-  if (data?.then) fail('read_failed');
-  view.assertBoundary(); options.checkpoint?.('published', root); revalidate(deadline);
-  building = false;
-  return Object.freeze({ view, data });
+  let previousView = null;
+  function capture(project) {
+    if (previousView) {
+      deadline = Date.now() + limits.timeout;
+      revalidate(deadline);
+    }
+    building = true; frozen = false;
+    const recording = makeView();
+    if (options.retain && previousView) inheritControlReadMemo(previousView, recording);
+    const recorded = withControlReadView(recording, () => project(recording));
+    if (recorded?.then) fail('read_failed');
+    recording.assertBoundary(); options.checkpoint?.('captured', root);
+    frozen = true; revalidate(deadline);
+    sourceDigest = hash(JSON.stringify([...entries].sort(([a], [b]) => a.localeCompare(b))
+      .map(([path, entry]) => [relative(root, path), entry.kind, entry.signature ?? entry.code, entry.digest ?? null, entry.children ?? null])));
+    const view = makeView(); options.checkpoint?.('replay', root);
+    if (options.retain) inheritControlReadMemo(recording, view);
+    const data = withControlReadView(view, () => project(view));
+    if (data?.then) fail('read_failed');
+    view.assertBoundary(); options.checkpoint?.('published', root); revalidate(deadline);
+    building = false; previousView = view;
+    return Object.freeze({ view, data });
+  }
+  const initial = capture(project);
+  return options.retain ? Object.freeze({ ...initial, extend: capture }) : initial;
+}
+
+// Single contained control source using the same descriptor/ancestor/race checks
+// as dependency capture. Mutation owners can inspect exact old bytes without
+// introducing another filesystem reader or capturing unrelated Run resources.
+function validateSingleControlPath(relativePath) {
+  if (typeof relativePath !== 'string' || !relativePath.startsWith('.agdf/control/')
+    || relativePath.includes('\\') || relativePath.includes(':') || relativePath.split('/').some(part => !part || part === '.' || part === '..')) fail('resource_denied');
+}
+export function readContainedControlText(root, relativePath, maximum = 131072) {
+  validateSingleControlPath(relativePath);
+  if (hasControlReadView()) {
+    const view = currentControlReadView();
+    if (view.readOptionalFileSync) {
+      const observed = view.readOptionalFileSync(join(root, relativePath), maximum);
+      if (observed.code) fail(observed.code);
+      return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(observed.bytes);
+    }
+    const path = join(root, relativePath), stats = viewStat(path);
+    if (!stats.isFile() || stats.size > maximum) fail('resource_limit');
+    const bytes = viewRead(path);
+    if (bytes.length > maximum) fail('resource_limit');
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+  }
+  return captureControlScope(root, view => {
+    const observed = view.readOptionalFileSync(join(root, relativePath), maximum);
+    if (observed.code) fail(observed.code);
+    return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(observed.bytes);
+  }).data;
+}
+
+export function controlPathPresent(root, relativePath) {
+  validateSingleControlPath(relativePath);
+  const path = join(root, relativePath), view = currentControlReadView();
+  if (view?.readOptionalFileSync) return view.readOptionalFileSync(path, 0).code !== 'document_missing';
+  return captureControlScope(root, observed => observed.readOptionalFileSync(path, 0).code !== 'document_missing').data;
 }

package/runtime/core/lib/control-state/aggregate.js

@@ -14,5 +14,7 @@ export function aggregate(results, { allowNoActiveRuns = false } = {}) {
       ? "pass"
       : "revise";
 
-  return { status, runs };
+  return { status, runs, ...(!runs.length ? { empty_inventory: {
+    reason: 'no_active_runs', allow_no_active_runs: allowNoActiveRuns,
+  } } : {}) };
 }