create-agdf 0.20.2 → 0.31.0

package/lib/scaffold/plan.js

@@ -1,3 +1,5 @@
+import { CURRENT_LAYOUT } from '#agdf-core/control-state/run-identity.js';
+import { canonicalInitPlan } from "#agdf-core/resources/canonical-init-plan.js";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { generatedRoot, languageConfigContent, pluginDefinition } from "../cli/runtime-context.js";
@@ -16,12 +18,11 @@ const codexPluginFiles = [
   join(".agents", "plugins", "marketplace.json"),
   join("plugins", "agdf", ".codex-plugin", "plugin.json"),
   join("plugins", "agdf", "control", "README.md"),
-  join("plugins", "agdf", "control", "templates", "AGDF_RUN.md"),
   join("plugins", "agdf", "control", "templates", "RUN_STATE.md"),
-  join("plugins", "agdf", "control", "templates", "MASTER_BACKLOG.md"),
   join("plugins", "agdf", "control", "templates", "SOT_REGISTRY.md"),
   join("plugins", "agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join("plugins", "agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join("plugins", "agdf", "control", "templates", "BRAND.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "UR.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
   join("plugins", "agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
@@ -43,12 +44,11 @@ const codexPluginFiles = [
 ];
 const controlFiles = [
   join(".agdf", "control", "README.md"),
-  join(".agdf", "control", "templates", "AGDF_RUN.md"),
   join(".agdf", "control", "templates", "RUN_STATE.md"),
-  join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
   join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
   join(".agdf", "control", "templates", "CONTEXT_GRAPH.md"),
   join(".agdf", "control", "templates", "AGENT_QUALITY_CONTRACTS.json"),
+  join(".agdf", "control", "templates", "BRAND.md"),
   join(".agdf", "control", "templates", "artefacts", "UR.md"),
   join(".agdf", "control", "templates", "artefacts", "BROWNFIELD_REVIEW.md"),
   join(".agdf", "control", "templates", "artefacts", "VERIFIED_CHANGE.md"),
@@ -60,10 +60,6 @@ const controlFiles = [
   join(".agdf", "control", "templates", "artefacts", "OR.md"),
 ];
 const liveControlFiles = [
-  {
-    path: join(".agdf", "control", "MASTER_BACKLOG.md"),
-    source: join(".agdf", "control", "templates", "MASTER_BACKLOG.md"),
-  },
   {
     path: join(".agdf", "control", "SOT_REGISTRY.md"),
     source: join(".agdf", "control", "templates", "SOT_REGISTRY.md"),
@@ -104,37 +100,20 @@ export function generatedFilesForTarget(target, targetDir, force, languagePrefer
   const files = [];
 
   if (target === "config") {
+    const configPath = join(targetDir, '.agdf', 'control', 'config.json');
+    let existing = { control_layout: CURRENT_LAYOUT };
+    try { existing = JSON.parse(readFileSync(configPath, 'utf8')); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (!existing || typeof existing !== 'object' || Array.isArray(existing)) throw Error('invalid_control_config');
     files.push({
       path: join(".agdf", "control", "config.json"),
-      content: languageConfigContent(languagePreference),
+      content: languageConfigContent(languagePreference, existing),
       allowOverwrite: true,
     });
     return files;
   }
 
-  if (target === "init") {
-    addLanguageConfig(files, languagePreference);
-    files.push({
-      path: join(".agdf", "control", "README.md"),
-      content: loadAsset(join(".agdf", "control", "README.md")),
-    });
-
-    for (const controlPath of liveControlFiles) {
-      files.push({
-        path: controlPath.path,
-        content: loadAsset(controlPath.source),
-      });
-    }
-
-    for (const templatePath of artefactTemplateFiles) {
-      files.push({
-        path: templatePath,
-        content: loadAsset(templatePath),
-      });
-    }
-
-    return files;
-  }
+  if (target === "init") return canonicalInitPlan(languagePreference);
 
   if (target === "codex-repo") {
     addLanguageConfig(files, languagePreference);

package/lib/scaffold/presentation.js

@@ -31,7 +31,7 @@ export function createCanonicalInitLifecycleResult(destination, initialization)
     restart: { required: false, reason: "none" },
     next_action: {
       kind: "control_setup",
-      text: "Create or migrate one canonical run with an explicit run id before drafting durable delivery state.",
+      text: 'Capture a planned UR, or create a canonical Run for delivery. Inspect inventory before selecting existing work.',
     },
     changes: created,
     retained,
@@ -113,7 +113,7 @@ export function printNextSteps(target, destination, files, removedOpenCodeAgents
     io.log(`- AGDF language preference: artefacts=${language.artifact_language}, chat=${language.chat_language}, runtime=${language.runtime_language}.`);
   }
   if (target === "init") {
-    io.log("- Create the canonical run with `run-create --run <run_id>` and record each later step with `run-step` instead of editing RUN_STATE.md by hand.");
+    io.log("- Create a current Run with `run-create --title <title> --operation <uuid>`; retain its returned Run/revision and record later steps through their inspected current commands.");
     io.log("- An active delivery intake continues without a second setup prompt: write the UR, record it with `run-step --step ur`, then dispatch gate-check with `--intake`.");
     io.log("- Run the installed `agdf doctor` to check the control state before the next agent run.");
     io.log("- Commit the live control files once they represent the repository's current delivery state.");

package/lib/scaffold/write.js

@@ -1,16 +1,21 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { pluginDefinition } from "../cli/runtime-context.js";
+import { atomicWrite } from '#agdf-core/owned-file-lock.js';
+import { markControlMutationEffect } from '#agdf-core/control-state/control-layout.js';
+import { hasSymlinkComponent } from '#agdf-core/control-state/contained-file.js';
 
 export function writeGeneratedFile(targetDir, relativePath, content, force, allowOverwrite = false) {
   const outputPath = join(targetDir, relativePath);
+  if (relativePath.replaceAll('\\', '/') === '.agdf/control/config.json' && hasSymlinkComponent(targetDir, '.agdf/control/config.json')) throw Error('AGDF_CONTROL_PATH_INVALID');
   mkdirSync(dirname(outputPath), { recursive: true });
 
   if (existsSync(outputPath) && !force && !allowOverwrite) {
     throw new Error(`Refusing to overwrite existing file: ${relativePath}. Re-run with --force if you want to replace it.`);
   }
 
-  writeFileSync(outputPath, content, "utf8");
+  if (relativePath.replaceAll('\\', '/') === '.agdf/control/config.json') { markControlMutationEffect(); atomicWrite(outputPath, content); }
+  else writeFileSync(outputPath, content, 'utf8');
 }
 
 export function removeOwnedLegacyOpenCodeAgents(targetDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.20.2",
+  "version": "0.31.0",
   "description": "Install AGDF plugins, bootstrap supported repository surfaces and validate durable governance state.",
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
     "generated/.opencode",
     "generated/opencode.json",
     "generated/plugins/agdf",
+    "generated/plugins/agdf-planning",
     "generated/plugins/copilot/agdf",
     "generated/submissions/openai/agdf",
     "opencode-plugin.js",
@@ -26,7 +27,10 @@
     "./control-command": "./lib/control-command.js",
     "./cli": "./bin/create-agdf.js",
     "./mcp-dispatch-runtime": "./lib/mcp-dispatch-runtime.js",
-    "./opencode-plugin": "./opencode-plugin.js"
+    "./opencode-plugin": "./opencode-plugin.js",
+    "./mcp-protocol-runtime": "./lib/mcp-protocol-runtime.js",
+    "./mcp-worker-runtime": "./lib/mcp-worker-runtime.js",
+    "./mcp-owner-protocol": "./lib/mcp-owner-protocol.js"
   },
   "bin": {
     "create-agdf": "./bin/create-agdf.js"

package/runtime/core/lib/companion/events.js

@@ -0,0 +1,154 @@
+// Companion events (SD SDD-005, SDD-009): the pure mapping from the final result of an AGDF MCP tool
+// call to zero or one event of schema `companion-event/1`, and the reader of the versioned journal
+// format. Events come from real MCP outcomes, never from host hooks, so the agent cannot shape them.
+// Read-only tools produce none. Review facts (SDD-008) are computed by the runtime and handed in.
+// Host-neutral: no Node built-in, no host API.
+import { COMMAND_TOOL_NAMES, TOOL_RESULT_META } from '../mcp-tool-errors.js';
+import { RUN_STEP_SLOTS } from '../control-state/run-identity.js';
+
+export const COMPANION_EVENT_SCHEMA = 'companion-event/1';
+export const EVENT_KINDS = Object.freeze(['approval_requested', 'approval_recorded', 'write_rejected', 'effect_unknown',
+  'recovery_required', 'run_completed', 'material_staged', 'document_recorded']);
+// Decision P1: these kinds interrupt as a toast, together with a digest mismatch (a drift warning of
+// the run view); approval recorded and write rejected appear in the pane only.
+export const TOAST_KINDS = Object.freeze(['approval_requested', 'effect_unknown', 'recovery_required', 'run_completed']);
+// Decision P2: at most 40 lines or 4 KiB, whichever is smaller.
+export const PREVIEW_LIMITS = Object.freeze({ lines: 40, bytes: 4096 });
+export const SOURCE_MATCHES = Object.freeze(['match', 'mismatch', 'not_determinable', 'unavailable']);
+
+// The tool-result descriptor key and the command tools come from the MCP tool-error contract, and the
+// slot of a recorded step from the run identity owner; all three modules are pure (CR finding CIR-04).
+export const TOOL_RESULT_META_KEY = TOOL_RESULT_META;
+const COMMAND_TOOLS = new Set(COMMAND_TOOL_NAMES);
+const TEXT_LIMIT = 256;
+const encoder = new TextEncoder();
+const bounded = value => (typeof value === 'string' && value.length ? value.slice(0, TEXT_LIMIT) : null);
+
+// The bounded preview of a text: cut after the 40th line break unless the text ends there, then to
+// at most 4096 UTF-8 bytes on a character boundary. Exactly 40 lines or 4096 bytes stay whole.
+export function reviewPreview(text) {
+  const value = String(text ?? '');
+  let preview = value;
+  let at = -1;
+  for (let line = 0; line < PREVIEW_LIMITS.lines; line += 1) {
+    at = value.indexOf('\n', at + 1);
+    if (at < 0) break;
+  }
+  if (at >= 0 && at < value.length - 1) preview = value.slice(0, at + 1);
+  if (encoder.encode(preview).length > PREVIEW_LIMITS.bytes) {
+    let size = 0;
+    let cut = 0;
+    for (const char of preview) {
+      const width = encoder.encode(char).length;
+      if (size + width > PREVIEW_LIMITS.bytes) break;
+      size += width;
+      cut += char.length;
+    }
+    preview = preview.slice(0, cut);
+  }
+  return { text: preview, truncated: preview.length < value.length, bytes: encoder.encode(value).length };
+}
+
+// One review fact: what the runtime saw of recorded or staged material. Unknown values stay null
+// ("unavailable"), never guessed (PRD AC-007).
+export function reviewFact({ slot = null, source, path = null, digest = null, text = null, sourceMatch }) {
+  const preview = typeof text === 'string' ? reviewPreview(text) : null;
+  return {
+    slot: bounded(slot),
+    source: source === 'path' ? 'path' : 'staged',
+    path: bounded(path),
+    digest: /^sha256:[a-f0-9]{64}$/u.test(digest ?? '') ? digest : null,
+    bytes: preview?.bytes ?? null,
+    preview: preview?.text ?? null,
+    truncated: preview?.truncated ?? null,
+    source_match: SOURCE_MATCHES.includes(sourceMatch) ? sourceMatch : 'unavailable',
+  };
+}
+
+// The slot (gate or step) a command names, for the event's gate field.
+export function commandGate(command = {}) {
+  const payload = command.payload ?? {};
+  if (command.kind === 'closeout.record') return 'OR';
+  if (command.kind === 'step.record') return payload.internal_step ?? RUN_STEP_SLOTS[payload.step] ?? null;
+  if (command.kind === 'operation.recover') return null;
+  return typeof payload.gate === 'string' ? payload.gate : null;
+}
+
+function successKind(command, result) {
+  const kind = command?.kind;
+  if (kind === 'presentation.deliver') {
+    return result.historical_effect === true || result.presentation_delivery?.historical_delivery === true
+      ? null : 'approval_requested';
+  }
+  if (kind === 'approval.record') return 'approval_recorded';
+  if (kind === 'closeout.record') return 'run_completed';
+  if (kind === 'material.stage' && command.payload?.action === 'seal') return 'material_staged';
+  if (kind === 'step.record' || kind === 'artefact.record') return 'document_recorded';
+  return null;
+}
+
+// The event kind of one final command result, or null for a read, a replay or an outcome outside
+// the eight kinds. A failure is classified by the projected descriptor's effect state first, so a
+// thrown failure of unknown effect is never reported as rejected.
+export function eventKind(toolName, input, result) {
+  if (!COMMAND_TOOLS.has(toolName) || !result || typeof result !== 'object') return null;
+  const descriptor = result._meta?.[TOOL_RESULT_META_KEY] ?? null;
+  if (result.outcome === 'accepted') return successKind(input?.command, result);
+  if (result.outcome === 'already_applied') return null;
+  if (result.outcome === 'recovery_required') return 'recovery_required';
+  if (result.outcome === 'effect_unknown' || descriptor?.effect_state === 'unknown') return 'effect_unknown';
+  if (descriptor?.failed || result.outcome === 'rejected') return 'write_rejected';
+  return null;
+}
+
+// The event of one final tool result: { schema_version, id, at, root, run_id, gate, kind, outcome,
+// reason, operation_id, review } or null. `id`, `at` and `root` come from the writer; `review` holds
+// the runtime's review facts for staged or recorded material.
+export function deriveEvent(toolName, input, result, { id, at, root = null, review = null } = {}) {
+  const kind = eventKind(toolName, input, result);
+  if (!kind) return null;
+  const descriptor = result._meta?.[TOOL_RESULT_META_KEY] ?? null;
+  const facts = Array.isArray(review) && review.length && ['material_staged', 'document_recorded'].includes(kind) ? review.slice(0, 4) : null;
+  return {
+    schema_version: COMPANION_EVENT_SCHEMA,
+    id: bounded(id),
+    at: bounded(at),
+    root: typeof root === 'string' && root.length ? root : bounded(input?.primary_target) ?? bounded(input?.working_directory),
+    run_id: bounded(input?.run_id) ?? bounded(result.run_id),
+    gate: kind === 'material_staged' ? facts?.[0]?.slot ?? null : commandGate(input?.command),
+    kind,
+    outcome: bounded(result.outcome) ?? (descriptor?.failed ? 'failed' : null),
+    reason: descriptor?.failed ? bounded(descriptor.code) ?? bounded(result.reason) : null,
+    operation_id: bounded(input?.operation_id),
+    review: facts,
+  };
+}
+
+// A journal line is an event when it parses and carries the schema, a known kind and an id.
+export function validEvent(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value) && value.schema_version === COMPANION_EVENT_SCHEMA
+    && EVENT_KINDS.includes(value.kind) && typeof value.id === 'string' && typeof value.at === 'string';
+}
+
+// The events of a journal text in file order; malformed or foreign lines are skipped, since several
+// MCP servers may interleave lines (SDD-006).
+export function parseEventLines(text) {
+  const events = [];
+  for (const line of String(text ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const value = JSON.parse(line);
+      if (validEvent(value)) events.push(value);
+    } catch { /* an interleaved or cut line */ }
+  }
+  return events;
+}
+
+// Roots compare after normalizing separators, a trailing separator and, on win32, case (SD 5).
+export function sameRoot(left, right, { win32 = false } = {}) {
+  const normal = value => {
+    const text = String(value ?? '').replaceAll('\\', '/').replace(/\/+$/u, '');
+    return win32 ? text.toLowerCase() : text;
+  };
+  return Boolean(left) && Boolean(right) && normal(left) === normal(right);
+}

package/runtime/core/lib/companion/figure-state.js

@@ -0,0 +1,36 @@
+// Companion figure state (SD SDD-004): one mood and a reason descriptor per run-view entry, derived
+// only from the status-card fields the run view copied. Pure and host-neutral; hosts localize the
+// reason with the catalog's companion section and may overlay their own activity (turn in progress).
+import { COMPANION_MOODS } from '../interaction-catalog.js';
+import { RUN_MODES } from '../control-state/run-identity.js';
+
+export { COMPANION_MOODS };
+// The internal steps between an approved TP and QA, shown as building in structured runs; hosts that
+// mark the build phase use this list (CR finding CIR-04).
+export const BUILD_GATES = Object.freeze(['Brownfield Analysis', 'CD+Tests', 'CR']);
+export const STRUCTURED_MODES = Object.freeze(RUN_MODES.filter(mode => mode.startsWith('structured_')));
+// The ended lifecycles of run-operations.js (ENDED_LIFECYCLES), kept here so this module stays pure;
+// the companion tests assert both agree.
+export const ENDED_LIFECYCLES = Object.freeze(['superseded', 'abandoned']);
+// The pending approval as the run inventory reads it (run-inventory.js runAttention): a negated
+// mention ("No Approval: QA") is no pending approval.
+const pendingApproval = missing => String(missing ?? '').match(/(?<!\b(?:[Nn]o|[Nn]ot|[Ww]ithout) )\bApproval: (UR|PRD|SD|TP|QA|UAT|OR)\b/u)?.[1] ?? null;
+
+// { mood, reason: { key, gate?, decision?, reason? } }; null or no entry is the idle figure.
+export function deriveFigureState(entry) {
+  if (!entry) return { mood: 'bereit', reason: { key: 'idle' } };
+  if (entry.valid === false) return { mood: 'blockiert', reason: { key: 'unreadable', reason: entry.unreadable_reason ?? 'run_state_invalid' } };
+  if (entry.evaluation_error) return { mood: 'blockiert', reason: { key: 'unreadable', reason: entry.evaluation_error } };
+  if (entry.lifecycle === 'completed') return { mood: 'fertig', reason: { key: 'done' } };
+  if (ENDED_LIFECYCLES.includes(entry.lifecycle)) return { mood: 'bereit', reason: { key: 'ended' } };
+  if (!entry.evaluated) return { mood: 'bereit', reason: { key: 'idle' } };
+  const gate = entry.current_gate;
+  if (entry.status === 'blocked' || (entry.blocking_reason && entry.blocking_reason !== 'none'))
+    return { mood: 'blockiert', reason: { key: 'blocked', gate, decision: entry.blocking_reason } };
+  const approval = pendingApproval(entry.missing_approval);
+  if (approval) return { mood: 'wartet', reason: { key: 'waitingApproval', gate: approval } };
+  if (entry.user_action_required === 'yes') return { mood: 'wartet', reason: { key: 'waitingDecision', gate } };
+  if (entry.status === 'pass') return { mood: 'fertig', reason: { key: 'done' } };
+  if (STRUCTURED_MODES.includes(entry.mode) && BUILD_GATES.includes(gate)) return { mood: 'baut', reason: { key: 'building', gate } };
+  return { mood: 'laeuft', reason: { key: 'working', gate } };
+}

package/runtime/core/lib/companion/journal.js

@@ -0,0 +1,180 @@
+// Companion event journal (SD SDD-006, SDD-008): the runtime appends one line per event of a final
+// AGDF MCP tool result to `companion/events.jsonl` below the plugin data root, bounded to 256 KiB with
+// one rotation file `events.1.jsonl`. It is a notification channel only, never a source of truth, and
+// nothing here writes under `.agdf/control`. Every failure is swallowed: the tool result never changes.
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { resolveTaskTarget } from '../task-target-resolution.js';
+import { artefactFileDigest } from '../control-state/run-seal-compute.js';
+import { containedRegularFile } from '../control-state/contained-file.js';
+import { atomicWrite, withOwnedFileLock } from '../owned-file-lock.js';
+import { commandGate, deriveEvent, eventKind, reviewFact } from './events.js';
+
+export const JOURNAL_DIRECTORY = 'companion';
+export const JOURNAL_FILE = 'events.jsonl';
+export const JOURNAL_ROTATED_FILE = 'events.1.jsonl';
+export const JOURNAL_LIMIT_BYTES = 256 * 1024;
+// The launcher hands its data root (CLAUDE_PLUGIN_DATA on Claude, --data on Codex) to the runtime
+// processes through this variable (SDD-006).
+export const COMPANION_DATA_ROOT_ENV = 'AGDF_COMPANION_DATA_ROOT';
+const SOURCE_TEXT_LIMIT = 1024 * 1024;
+const RESERVATIONS_FILE = 'approval-requests.json';
+const RESERVATIONS_LIFETIME_MS = 30 * 60_000;
+const RESERVATIONS_MAX_ENTRIES = 8192;
+const RESERVATIONS_MAX_BYTES = 1024 * 1024;
+const RESERVATIONS_LOCK_WAIT_MS = 50;
+const DIGEST = /^[a-f0-9]{64}$/u;
+
+export const journalPath = dataRoot => join(dataRoot, JOURNAL_DIRECTORY, JOURNAL_FILE);
+
+const isLink = path => { try { return lstatSync(path).isSymbolicLink(); } catch { return false; } };
+
+function readReservations(path) {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  if (!stat.isFile() || stat.size > RESERVATIONS_MAX_BYTES) throw Error('invalid notification reservations');
+  const bytes = readFileSync(path);
+  if (bytes.length > RESERVATIONS_MAX_BYTES) throw Error('invalid notification reservations');
+  const stored = JSON.parse(bytes);
+  if (!stored || typeof stored !== 'object' || Array.isArray(stored)) throw Error('invalid notification reservations');
+  const entries = Object.entries(stored);
+  if (entries.length > RESERVATIONS_MAX_ENTRIES
+      || entries.some(([key, expires]) => !DIGEST.test(key) || !Number.isSafeInteger(expires) || expires < 0)) {
+    throw Error('invalid notification reservations');
+  }
+  return entries;
+}
+
+// Only the notification survives a serving-process restart. Neither this
+// reservation nor the journal line participates in delivery or approval.
+function reserveApprovalRequest(dataRoot, input, at) {
+  const identity = [input.target_id, input.run_id, input.expected_revision_id,
+    input.command.payload.presentation_id, input.operation_id];
+  if (!identity.every(value => typeof value === 'string' && value.length > 0)) return false;
+  const key = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+  const directory = join(dataRoot, JOURNAL_DIRECTORY);
+  if (isLink(dataRoot) || isLink(directory)) return false;
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const path = join(directory, RESERVATIONS_FILE);
+  const deadline = performance.now() + RESERVATIONS_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      return withOwnedFileLock(path, () => {
+        const live = new Map(readReservations(path).filter(([, expires]) => expires > at));
+        if (live.has(key) || live.size >= RESERVATIONS_MAX_ENTRIES) return false;
+        live.set(key, at + RESERVATIONS_LIFETIME_MS);
+        const bytes = JSON.stringify(Object.fromEntries(live));
+        if (Buffer.byteLength(bytes) > RESERVATIONS_MAX_BYTES) return false;
+        atomicWrite(path, bytes);
+        return true;
+      });
+    } catch (error) {
+      const remaining = deadline - performance.now();
+      if (error.lock_owner_status !== 'live' || remaining <= 0) return false;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(5, remaining));
+    }
+  }
+}
+
+// Appends one event line; rotates first when the line would cross the bound. Returns whether the line
+// was written. Concurrent servers may interleave whole lines or lose some at rotation (accepted).
+export function appendJournalEvent(dataRoot, event, { limit = JOURNAL_LIMIT_BYTES } = {}) {
+  try {
+    if (typeof dataRoot !== 'string' || !dataRoot || !event) return false;
+    const directory = join(dataRoot, JOURNAL_DIRECTORY);
+    if (isLink(dataRoot) || isLink(directory)) return false;
+    mkdirSync(directory, { recursive: true });
+    const line = `${JSON.stringify(event)}\n`;
+    const size = Buffer.byteLength(line, 'utf8');
+    if (size > limit) return false;
+    const file = join(directory, JOURNAL_FILE);
+    if (isLink(file)) return false;
+    let current = 0;
+    try { current = statSync(file).size; } catch { current = 0; }
+    if (current > 0 && current + size > limit) renameSync(file, join(directory, JOURNAL_ROTATED_FILE));
+    appendFileSync(file, line, 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The governance root of a command input, resolved like the material store does; the input's own
+// target path when it does not resolve.
+export function commandRoot(input = {}) {
+  try {
+    const target = resolveTaskTarget({ workingDirectory: input.working_directory, targetSource: input.target_source, primaryTarget: input.primary_target });
+    if (target.resolution_state === 'resolved' && target.governance_target) return target.governance_target;
+  } catch { /* fall back to the input path */ }
+  return input.primary_target ?? input.working_directory ?? null;
+}
+
+// The event's root: the caller's target path when it names the same directory as the resolved root
+// through another spelling (junction, symlink, subst drive), so a host comparing with its own session
+// root still matches (SD SDD-005 "the MCP target path", CR finding A6); else the resolved root.
+// Review facts keep reading below the resolved root.
+export function eventRoot(input = {}, root = commandRoot(input)) {
+  const given = typeof input.primary_target === 'string' && isAbsolute(input.primary_target) ? resolve(input.primary_target) : null;
+  if (!given || !root || given === root) return root;
+  try { return realpathSync(given) === realpathSync(root) ? given : root; } catch { return root; }
+}
+
+// Review facts of a path source: the file read now, its canonical digest from the node digest owner
+// compared with the declared digest (match or mismatch); unreadable files are unavailable.
+function pathFact(root, slot, source) {
+  const current = root ? artefactFileDigest(root, source.path) : 'unresolved';
+  if (!/^sha256:/u.test(current)) return reviewFact({ slot, source: 'path', path: source.path, digest: source.digest, sourceMatch: 'unavailable' });
+  let text = null;
+  try {
+    const file = containedRegularFile(root, String(source.path).trim());
+    if (file.status === 'valid' && statSync(file.path).size <= SOURCE_TEXT_LIMIT) text = readFileSync(file.path, 'utf8');
+  } catch { text = null; }
+  return reviewFact({ slot, source: 'path', path: source.path, digest: source.digest, text, sourceMatch: current === source.digest ? 'match' : 'mismatch' });
+}
+
+// Review facts (SDD-008, decision P4): sealed staged material carries its preview, size and digest
+// with source_match not_determinable; a recording from a path carries the path, the recorded digest
+// and whether the file still matches it; a recording from staged material names its digest only.
+export function reviewFacts(toolName, input, result, { sealedFiles = () => null, root = commandRoot(input) } = {}) {
+  const kind = eventKind(toolName, input, result);
+  const command = input?.command ?? {};
+  if (kind === 'material_staged') {
+    const files = sealedFiles(command.payload?.transfer_id) ?? [];
+    return files.map(file => reviewFact({ slot: file.slot, source: 'staged', digest: file.digest, text: file.content, sourceMatch: 'not_determinable' }));
+  }
+  if (kind !== 'document_recorded') return null;
+  const payload = command.payload ?? {};
+  const source = payload.source ?? payload.material ?? null;
+  const slot = commandGate(command);
+  if (source?.path) return [pathFact(root, slot, source)];
+  if (source?.material_id) return [reviewFact({ slot, source: 'staged', digest: source.digest, sourceMatch: 'not_determinable' })];
+  return null;
+}
+
+// The runtime's observer of final tool results. Without a data root it does nothing.
+export function createCompanionJournal({ dataRoot = process.env[COMPANION_DATA_ROOT_ENV], sealedFiles = () => null,
+  now = () => new Date(), newId = randomUUID, limit = JOURNAL_LIMIT_BYTES } = {}) {
+  const enabled = typeof dataRoot === 'string' && dataRoot.length > 0;
+  return Object.freeze({
+    enabled,
+    path: enabled ? journalPath(dataRoot) : null,
+    observe(toolName, input, result) {
+      if (!enabled) return false;
+      try {
+        const kind = eventKind(toolName, input, result);
+        if (!kind) return false;
+        const root = commandRoot(input);
+        const review = reviewFacts(toolName, input, result, { sealedFiles, root });
+        const at = now();
+        const event = deriveEvent(toolName, input, result, { id: newId(), at: at.toISOString(), root: eventRoot(input, root), review });
+        if (!event) return false;
+        if (kind === 'approval_requested' && !reserveApprovalRequest(dataRoot, input, at.getTime())) return false;
+        return appendJournalEvent(dataRoot, event, { limit });
+      } catch {
+        return false;
+      }
+    },
+  });
+}