@amsterdamdatalabs/enact-operator 0.1.2

package/runtime/hooks/lifecycle/stop.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Phase 7 — Stop-hook closure gate.
+ * Wraps the original continuation capture with stop-policy evaluation.
+ * On deny: writes durable stop-verdict artifact and returns a blocking
+ *   Stop-hook payload with a human-readable reason so the live loop continues
+ *   in-session until the goal is actually met.
+ * On allow: returns a minimal allow payload.
+ *
+ * Continuation state is ALWAYS captured (even on deny so the state is
+ * preserved for the next session).
+ *
+ * Policy evaluation is delegated to the compiled stop-policy and authority
+ * modules — no inline duplication. I3 (review-pending
+ * check) is included automatically via the shared evaluateStopPolicy.
+ */
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { execSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutDir, layoutPath } from "../shared/layout-dir.mjs";
+import { emitHookFired, emitStopVerdict, registerHookFailureTrap } from "../shared/observability.mjs";
+import { readHooksVerbose, verboseLog } from "../shared/_lib.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const repoRoot = join(__dirname, "..", "..", "..");
+
+// Import compiled TS modules (ESM, emitted by tsc into dist/)
+const { evaluateStopPolicy } = await import("@amsterdamdatalabs/enact-operator/stopPolicy");
+const { readOperatorAuthority } = await import("@amsterdamdatalabs/enact-operator/authority");
+const { writeStopVerdict } = await import("@amsterdamdatalabs/enact-operator/stopVerdict");
+const { markContinuationBlocked, resetContinuationState } = await import("@amsterdamdatalabs/enact-operator/continuation");
+const {
+  enqueueContinuationFollowUp,
+  buildStopDenyDedupeKey,
+  fingerprintBlockers,
+} = await import("@amsterdamdatalabs/enact-operator/continuationFollowUp");
+const { captureActiveWorkflows } = await import("@amsterdamdatalabs/enact-operator/hookContinuation");
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function readJson(path, fallback) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(value, null, 2), "utf8");
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const payload = readStdin();
+// Prefer payload.cwd (the actual workspace codex is running in) and resolve the
+// nearest workspace root from there rather than trusting the hook process cwd.
+const root = rootDirFrom(payload?.cwd ?? process.cwd());
+const startedAt = Date.now();
+const completeHook = registerHookFailureTrap({
+  payload,
+  hookEvent: "Stop",
+  startedAt,
+});
+const operatorLayout = layoutDir(root);
+mkdirSync(layoutPath(root, "logs"), { recursive: true });
+mkdirSync(layoutPath(root, "state"), { recursive: true });
+appendFileSync(layoutPath(root, "logs", "hooks.log"), `${new Date().toISOString()} Stop ${JSON.stringify(payload)}\n`, "utf8");
+
+// Always capture continuation state (even on deny — preserves active state for next session)
+const activeWorkflows = captureActiveWorkflows(root);
+const capturedAt = activeWorkflows.capturedAt;
+
+const runtimePath = join(operatorLayout, "state", "operator-hook-runtime.json");
+const runtime = readJson(runtimePath, {});
+writeJson(runtimePath, { ...runtime, lastStopAt: capturedAt, activeWorkflows });
+
+// Evaluate stop policy via the compiled shared evaluator (includes §I3 review-pending check)
+let outcome = "allow";
+let reasons = [];
+try {
+  const authority = readOperatorAuthority(root);
+  const verdict = evaluateStopPolicy({ authority, root });
+  outcome = verdict.outcome;
+  reasons = verdict.reasons;
+} catch (err) {
+  // If authority read fails, allow stop with a warning rather than hard-blocking
+  appendFileSync(join(operatorLayout, "logs", "hooks.log"), `${new Date().toISOString()} Stop policy eval error: ${err?.message ?? String(err)}\n`, "utf8");
+}
+
+const commitHash = (() => {
+  try { return execSync("git rev-parse HEAD", { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch { return "unknown"; }
+})();
+
+const verdict = {
+  outcome,
+  reasons,
+  capturedAt,
+  evidenceHorizon: {
+    commitHash,
+    verificationRunId: `vrun_${Math.random().toString(36).slice(2, 14)}`,
+    verificationRunTimestamp: capturedAt,
+    sessionSequence: 0,
+  },
+  // transportCanBlock: true — verified in interactive Codex TUI on 2026-05-16.
+  // Stop can deny live with the minimal payload shape:
+  // { decision:"block", reason:"..." }.
+  transportCanBlock: true,
+};
+
+const verdictPath = join(operatorLayout, "state", "stop-verdict.json");
+let authority;
+try {
+  authority = readOperatorAuthority(root);
+} catch (err) {
+  appendFileSync(join(operatorLayout, "logs", "hooks.log"), `${new Date().toISOString()} Stop authority read error (post-verdict): ${err?.message ?? String(err)}\n`, "utf8");
+  authority = null;
+}
+writeStopVerdict(root, verdict);
+
+// TUI gate — operator stop policy only enforces continuation for explicit autonomous lanes.
+// Interactive TUI sessions must behave like vanilla codex: no auto-stop-policy interference.
+// evaluateExecutor/Reviewer/Ultragoal/PipelineLike can emit deny without an active lane;
+// short-circuit those to allow so the user is never forced to type "continue" in TUI mode.
+const autonomousLaneActive =
+  authority?.ralph?.active === true ||
+  authority?.ultrawork?.active === true ||
+  authority?.autopilot?.active === true ||
+  authority?.team?.active === true;
+
+if (outcome === "deny" && !autonomousLaneActive) {
+  appendFileSync(
+    join(operatorLayout, "logs", "hooks.log"),
+    `${new Date().toISOString()} Stop policy deny suppressed (TUI mode — no autonomous lane active): ${reasons.map((r) => r.blocker).join("; ")}\n`,
+    "utf8",
+  );
+  resetContinuationState(root, 'tui-gate-bypass', 'stop-hook');
+  if (readHooksVerbose(root)) verboseLog("stop", "allow (TUI mode — no autonomous lane active, deny suppressed)");
+  completeHook();
+  process.stdout.write(JSON.stringify({ continue: true }));
+  process.exit(0);
+}
+
+if (outcome === "deny") {
+  await emitStopVerdict({
+    payload,
+    verdict: "deny",
+    blockers: reasons.map((r) => r.blocker),
+    stopHookActive: true,
+    latencyMs: Date.now() - startedAt,
+  });
+  await emitHookFired({
+    payload,
+    hookEvent: "Stop",
+    outcome: "denied",
+    latencyMs: Date.now() - startedAt,
+  });
+  const blockerSummary = reasons.slice(0, 3).map((r) => r.blocker).join("; ");
+  const moreCount = reasons.length > 3 ? ` (and ${reasons.length - 3} more)` : "";
+  appendFileSync(
+    join(operatorLayout, "logs", "hooks.log"),
+    `${new Date().toISOString()} Stop policy deny persisted: ${blockerSummary}${moreCount}; verdict=${verdictPath}\n`,
+    "utf8",
+  );
+  const continuation = markContinuationBlocked(root, authority, verdict, {
+    sessionId: typeof payload.session_id === 'string' ? payload.session_id : null,
+    transcriptPath: typeof payload.transcript_path === 'string' ? payload.transcript_path : null,
+  });
+  const sid = typeof payload.session_id === "string" ? payload.session_id : null;
+  const blockerFp = fingerprintBlockers(reasons.map((r) => r.blocker));
+  enqueueContinuationFollowUp(root, {
+    sessionId: sid,
+    dedupeKey: buildStopDenyDedupeKey({
+      sessionId: sid,
+      lane: continuation.lane,
+      laneId: continuation.laneId,
+      blockerFingerprint: blockerFp,
+    }),
+    trigger: "stop-deny",
+    lane: continuation.lane,
+    laneId: continuation.laneId,
+    prompt: `Operator stop policy denied exit. Resolve blockers, then continue. ${continuation.resumeHint ?? ""}`.trim(),
+  });
+  // Codex Stop hooks continue the turn when they receive the minimal block
+  // contract: decision="block" plus a human-readable reason. Do not emit extra
+  // fields here; rely on the durable verdict artifacts for richer evidence.
+  if (readHooksVerbose(root)) verboseLog("stop", `deny — ${reasons.length} blocker(s): ${blockerSummary}${moreCount}`);
+  process.stdout.write(JSON.stringify({
+    decision: "block",
+    reason: `Operator stop policy DENY: ${blockerSummary}${moreCount}. Continue working until blockers are resolved. If you need details, inspect the persisted stop verdict and use operator_stop_evaluate for a dry-run recheck. ${continuation.resumeHint ?? ''}`.trim(),
+  }));
+  completeHook();
+} else {
+  await emitStopVerdict({
+    payload,
+    verdict: "allow",
+    blockers: [],
+    stopHookActive: true,
+    latencyMs: Date.now() - startedAt,
+  });
+  await emitHookFired({
+    payload,
+    hookEvent: "Stop",
+    outcome: "allowed",
+    latencyMs: Date.now() - startedAt,
+  });
+  resetContinuationState(root, 'stop-allowed', 'stop-hook');
+  if (readHooksVerbose(root)) verboseLog("stop", "allow — no blockers, stop policy passed");
+  completeHook();
+  process.stdout.write(JSON.stringify({
+    continue: true,
+  }));
+}

package/runtime/hooks/observability.mjs

@@ -0,0 +1,2 @@
+export * from "./shared/observability.mjs";
+

package/runtime/hooks/post-tool-use-failure.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runHookScript } from "./tools/post-tool-use-failure.mjs";
+
+await runHookScript();

package/runtime/hooks/post-tool-use.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./tools/post-tool-use.mjs";
+

package/runtime/hooks/pre-compact.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./lifecycle/pre-compact.mjs";
+

package/runtime/hooks/pre-tool-use.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./tools/pre-tool-use.mjs";
+

package/runtime/hooks/resolveSkillActivation.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./lanes/resolveSkillActivation.mjs";
+

package/runtime/hooks/root-dir.mjs

@@ -0,0 +1,2 @@
+export * from "./shared/root-dir.mjs";
+

package/runtime/hooks/session-start.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./lifecycle/session-start.mjs";
+

package/runtime/hooks/shared/_continuation.mjs

@@ -0,0 +1,341 @@
+#!/usr/bin/env node
+/**
+ * _continuation.mjs — Self-contained runtime continuation orchestrator (no build step).
+ *
+ * TWIN note: src/continuationOrchestrator.ts is the typed twin of this file.
+ * If logic changes here it MUST be reflected in the TS twin, and vice-versa.
+ * The TS twin imports canonical predicates from src/terminology.ts and
+ * src/hookGating.ts; this .mjs file replicates their exact logic inline
+ * (those files are TypeScript-only and cannot be imported at runtime).
+ *
+ * This is the SINGLE SOURCE OF TRUTH for continuation orchestration at runtime.
+ * session-start.mjs imports buildContinuationContext from here rather than
+ * from dist/ so the SessionStart hook works even when dist/ is absent.
+ *
+ * Five predecessor surfaces wired here (mirroring the atlas plan):
+ *   Surface 1 (compaction-context read):  restore pending task IDs written by
+ *     pre-compact.mjs into compaction-context.json.
+ *   Surface 2 (delegated-session ledger): read delegated-sessions.json written
+ *     by subagent-tracker to find active/stale delegated sessions.
+ *   Surface 3 (protected-state guard):    all state reads go through layoutPath
+ *     (operator broker pattern) — never raw filesystem paths exposed externally.
+ *   Surface 4 (member-turn injection):    read continuation-state.json to surface
+ *     pending task IDs and active lane so the agent resumes with full context.
+ *   Surface 5 (manual-close filter):      filter out tasks closed via
+ *     task_manual_close or workitem_manual_close ledger kinds from the pending
+ *     task list, so closed tasks don't block continuation.
+ *
+ * Run: node -e "import('./runtime/hooks/_continuation.mjs').then(m=>console.log('OK', typeof m.buildContinuationContext))"
+ */
+
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+// ── Canonical predicates (replicated from src/terminology.ts) ─────────────────
+// Twin note: keep in sync with isManualTaskCloseLedgerKind in src/terminology.ts.
+// The TS version imports from @/terminology.js; we replicate the exact logic here.
+const CANONICAL_LEDGER_KINDS_TASK_MANUAL_CLOSE = 'task_manual_close';
+const CANONICAL_LEDGER_KINDS_WORKITEM_MANUAL_CLOSE = 'workitem_manual_close';
+
+/**
+ * Returns true if the ledger entry kind represents a manual task close.
+ * Mirrors isManualTaskCloseLedgerKind from src/terminology.ts exactly.
+ *
+ * @param {string} kind
+ * @returns {boolean}
+ */
+export function isManualTaskCloseLedgerKind(kind) {
+  return (
+    kind === CANONICAL_LEDGER_KINDS_TASK_MANUAL_CLOSE ||
+    kind === CANONICAL_LEDGER_KINDS_WORKITEM_MANUAL_CLOSE
+  );
+}
+
+// ── Protected-state path predicate (replicated from src/hookGating.ts) ────────
+// Twin note: keep in sync with isProtectedOperatorPath in src/hookGating.ts.
+// Used to guard against exposing raw .enact/operator/state paths externally.
+const PROTECTED_PATH_PATTERNS = [
+  /(?:^|[/\\])\.enact[/\\]operator[/\\]state(?:[/\\]|$)/,
+  /(?:^|[/\\])\.enact[/\\]operator[/\\]sessions[/\\]current\.json$/,
+  /(?:^|[/\\])\.enact[/\\]operator[/\\]team[/\\]team\.json$/,
+];
+
+/**
+ * Returns true if a path targets protected Operator control-plane state.
+ * Mirrors isProtectedOperatorPath from src/hookGating.ts exactly.
+ *
+ * @param {string} p
+ * @returns {boolean}
+ */
+export function isProtectedOperatorStatePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  const segments = p.replace(/\\/g, '/').split('/');
+  const resolved = [];
+  for (const seg of segments) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') { resolved.pop(); continue; }
+    resolved.push(seg);
+  }
+  const norm = resolved.join('/');
+  return PROTECTED_PATH_PATTERNS.some((re) => re.test(norm));
+}
+
+// ── JSON helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Read and parse a JSON file. Returns fallback on any error.
+ *
+ * @param {string} filePath
+ * @param {*} fallback
+ * @returns {*}
+ */
+function readJson(filePath, fallback) {
+  try {
+    if (!existsSync(filePath)) return fallback;
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Write a value as JSON to a file, creating parent directories as needed.
+ *
+ * @param {string} filePath
+ * @param {*} value
+ */
+function writeJson(filePath, value) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(value, null, 2), 'utf8');
+}
+
+const DEFAULT_DELEGATED_STALE_AFTER_MS = 2 * 60 * 60 * 1000;
+const DEFAULT_DELEGATED_STALE_PRUNE_AFTER_MS = 48 * 60 * 60 * 1000;
+const DEFAULT_DELEGATED_TERMINAL_PRUNE_AFTER_MS = 7 * 24 * 60 * 60 * 1000;
+
+function parseTimestampMs(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string' || candidate.trim() === '') continue;
+    const parsed = Date.parse(candidate);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function delegatedSessionRetentionBaseMs(session) {
+  if (session.status === 'stale') {
+    const staleDetectedAt =
+      session.metadata && typeof session.metadata.staleDetectedAt === 'string'
+        ? session.metadata.staleDetectedAt
+        : undefined;
+    return parseTimestampMs(staleDetectedAt, session.lastSeenAt, session.startedAt);
+  }
+  if (session.status === 'completed' || session.status === 'failed' || session.status === 'orphaned') {
+    return parseTimestampMs(session.stoppedAt, session.lastSeenAt, session.startedAt);
+  }
+  return null;
+}
+
+function reconcileDelegatedSessions(operatorLayout, opts = {}) {
+  const path = join(operatorLayout, 'state', 'delegated-sessions.json');
+  const nowMs = opts.nowMs ?? Date.now();
+  const staleAfterMs = opts.staleAfterMs ?? DEFAULT_DELEGATED_STALE_AFTER_MS;
+  const stalePruneAfterMs = opts.stalePruneAfterMs ?? DEFAULT_DELEGATED_STALE_PRUNE_AFTER_MS;
+  const terminalPruneAfterMs = opts.terminalPruneAfterMs ?? DEFAULT_DELEGATED_TERMINAL_PRUNE_AFTER_MS;
+  const raw = readJson(path, { schemaVersion: 1, updatedAt: new Date(nowMs).toISOString(), sessions: [] });
+  const sessions = Array.isArray(raw.sessions) ? raw.sessions : [];
+  let changed = false;
+
+  const promoted = sessions.map((session) => {
+    if (session.status !== 'active') return session;
+    const lastSeenMs = parseTimestampMs(session.lastSeenAt, session.startedAt);
+    if (lastSeenMs === null || nowMs - lastSeenMs <= staleAfterMs) return session;
+    changed = true;
+    return {
+      ...session,
+      status: 'stale',
+      metadata: {
+        ...(session.metadata && typeof session.metadata === 'object' ? session.metadata : {}),
+        staleDetectedAt: new Date(nowMs).toISOString(),
+      },
+    };
+  });
+
+  const kept = promoted.filter((session) => {
+    if (session.status === 'active') return true;
+    const baseMs = delegatedSessionRetentionBaseMs(session);
+    if (baseMs === null) return true;
+    const pruneAfterMs = session.status === 'stale' ? stalePruneAfterMs : terminalPruneAfterMs;
+    const keep = nowMs - baseMs <= pruneAfterMs;
+    if (!keep) changed = true;
+    return keep;
+  });
+
+  if (changed) {
+    writeJson(path, {
+      schemaVersion: 1,
+      updatedAt: new Date(nowMs).toISOString(),
+      sessions: kept,
+    });
+  }
+  return kept;
+}
+
+// ── Surface 1: Compaction-context read ───────────────────────────────────────
+
+/**
+ * Read the compaction-context.json written by pre-compact.mjs.
+ * Returns null if absent or empty.
+ *
+ * @param {string} operatorLayout  Absolute path to the operator state directory.
+ * @returns {{ pendingLocalTaskIds: string[], pendingLocalTaskTitles: string[], resumeHint: string | null } | null}
+ */
+export function readCompactionContext(operatorLayout) {
+  const path = join(operatorLayout, 'state', 'compaction-context.json');
+  const ctx = readJson(path, null);
+  if (!ctx) return null;
+  const ids = Array.isArray(ctx.pendingLocalTaskIds) ? ctx.pendingLocalTaskIds : [];
+  if (ids.length === 0) return null;
+  return {
+    pendingLocalTaskIds: ids,
+    pendingLocalTaskTitles: Array.isArray(ctx.pendingLocalTaskTitles) ? ctx.pendingLocalTaskTitles : [],
+    resumeHint: typeof ctx.resumeHint === 'string' ? ctx.resumeHint : null,
+  };
+}
+
+// ── Surface 2: Delegated-session ledger ──────────────────────────────────────
+
+/**
+ * Read delegated-sessions.json written by subagent-tracker.
+ * Returns the sessions array (active and stale sessions).
+ *
+ * @param {string} operatorLayout
+ * @returns {Array<{ continuationId: string, kind: string, status: string, startedAt: string }>}
+ */
+export function readDelegatedSessions(operatorLayout) {
+  const sessions = reconcileDelegatedSessions(operatorLayout);
+  return sessions.filter(
+    (s) => s.status === 'active' || s.status === 'stale',
+  );
+}
+
+// ── Surface 4: Member-turn injection (continuation-state.json) ────────────────
+
+/**
+ * Read continuation-state.json to get current lane, pending task IDs, and resume hint.
+ * Returns a safe default if absent.
+ *
+ * @param {string} operatorLayout
+ * @returns {{ lane: string, laneId: string | null, pendingTaskIds: string[], pendingLocalTaskIds: string[], resumeHint: string | null, activeSubagentIds: string[] }}
+ */
+export function readContinuationStateLocal(operatorLayout) {
+  const path = join(operatorLayout, 'state', 'continuation-state.json');
+  const raw = readJson(path, null);
+  return {
+    status: raw?.status ?? 'idle',
+    lane: raw?.lane ?? 'none',
+    laneId: raw?.laneId ?? null,
+    pendingTaskIds: Array.isArray(raw?.pendingTaskIds) ? raw.pendingTaskIds : [],
+    pendingLocalTaskIds: Array.isArray(raw?.pendingLocalTaskIds) ? raw.pendingLocalTaskIds : [],
+    pendingLocalTaskTitles: Array.isArray(raw?.pendingLocalTaskTitles) ? raw.pendingLocalTaskTitles : [],
+    resumeHint: raw?.resumeHint ?? null,
+    activeSubagentIds: Array.isArray(raw?.activeSubagentIds) ? raw.activeSubagentIds : [],
+  };
+}
+
+// ── Surface 5: Manual-close filter ───────────────────────────────────────────
+
+/**
+ * Read ledger.json and return the set of task IDs that have been manually closed.
+ * Uses isManualTaskCloseLedgerKind to identify manual-close ledger entries.
+ *
+ * @param {string} operatorLayout
+ * @returns {Set<string>}
+ */
+export function readManuallyClosedTaskIds(operatorLayout) {
+  const path = join(operatorLayout, 'logs', 'ledger.json');
+  const closed = new Set();
+  if (!existsSync(path)) return closed;
+  try {
+    const lines = readFileSync(path, 'utf8').split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        if (isManualTaskCloseLedgerKind(entry.kind ?? '')) {
+          // Coalese taskId from standard fields
+          const taskId = entry.taskId ?? entry.task_id ?? entry.metadata?.taskId ?? null;
+          if (typeof taskId === 'string' && taskId) {
+            closed.add(taskId);
+          }
+        }
+      } catch {
+        // skip malformed lines
+      }
+    }
+  } catch {
+    // ledger absent or unreadable — safe to return empty set
+  }
+  return closed;
+}
+
+// ── Main: buildContinuationContext ────────────────────────────────────────────
+
+/**
+ * Build the continuation context object from all five predecessor surfaces.
+ *
+ * This is the integration sink imported by session-start.mjs so that the
+ * SessionStart hook can inject a rich continuation context without depending
+ * on the compiled dist/ output.
+ *
+ * @param {string} operatorLayout  Absolute path to the operator layout root
+ *   (the value returned by layoutDir(root) from layout-dir.mjs).
+ * @returns {{
+ *   compactionContext: { pendingLocalTaskIds: string[], pendingLocalTaskTitles: string[], resumeHint: string | null } | null,
+ *   delegatedSessions: Array<{ continuationId: string, kind: string, status: string }>,
+ *   continuationState: { lane: string, laneId: string | null, pendingTaskIds: string[], pendingLocalTaskIds: string[], resumeHint: string | null, activeSubagentIds: string[] },
+ *   manuallyClosedTaskIds: string[],
+ *   effectivePendingTaskIds: string[],
+ *   hasDelegatedSessions: boolean,
+ *   hasCompactionSurvivors: boolean,
+ * }}
+ */
+export function buildContinuationContext(operatorLayout) {
+  // Surface 3 (protected-state guard): assert we're reading from operator layout,
+  // not from a raw user-exposed path. Guard is enforced by always routing reads
+  // through operatorLayout (layoutPath result), never from arbitrary strings.
+  // (isProtectedOperatorStatePath is exposed for callers to validate paths.)
+
+  // Surface 1: compaction-context read
+  const compactionContext = readCompactionContext(operatorLayout);
+
+  // Surface 2: delegated-session ledger
+  const delegatedSessions = readDelegatedSessions(operatorLayout);
+
+  // Surface 4: member-turn injection — continuation-state.json
+  const continuationState = readContinuationStateLocal(operatorLayout);
+
+  // Surface 5: manual-close filter — remove closed tasks from pending list
+  const manuallyClosedTaskIds = readManuallyClosedTaskIds(operatorLayout);
+
+  // Merge pending task IDs from continuation-state and compaction-context,
+  // then filter out any that have been manually closed.
+  const allPendingIds = new Set([
+    ...continuationState.pendingTaskIds,
+    ...continuationState.pendingLocalTaskIds,
+    ...(compactionContext?.pendingLocalTaskIds ?? []),
+  ]);
+  for (const closedId of manuallyClosedTaskIds) {
+    allPendingIds.delete(closedId);
+  }
+  const effectivePendingTaskIds = Array.from(allPendingIds);
+
+  return {
+    compactionContext,
+    delegatedSessions,
+    continuationState,
+    manuallyClosedTaskIds: Array.from(manuallyClosedTaskIds),
+    effectivePendingTaskIds,
+    hasDelegatedSessions: delegatedSessions.length > 0,
+    hasCompactionSurvivors: (compactionContext?.pendingLocalTaskIds.length ?? 0) > 0,
+  };
+}

package/runtime/hooks/shared/_lib.mjs

@@ -0,0 +1,60 @@
+/**
+ * Shared verbose-hook helper.
+ *
+ * Usage (in any hook):
+ *   import { verboseLog, readHooksVerbose } from "./_lib.mjs";
+ *   if (readHooksVerbose()) verboseLog("stop", "allow", "no autonomous lane active");
+ *
+ * The verbose flag is read from merged operator config.
+ * No env vars — non-secret config goes in config.toml per INV-024/ADR-0012.
+ */
+import { readMergedOperatorConfig } from "./config.mjs";
+
+export function readWorkspaceConfig(startDir = process.cwd()) {
+  return readMergedOperatorConfig(startDir);
+}
+
+/**
+ * Returns true when [hooks].verbose = true in config.toml.
+ * Defaults to false when the section or key is absent.
+ */
+export function readHooksVerbose(startDir = process.cwd()) {
+  const config = readWorkspaceConfig(startDir);
+  const value = config?.hooks?.verbose;
+  return value === true;
+}
+
+function operatorHookSection(startDir = process.cwd()) {
+  const config = readWorkspaceConfig(startDir);
+  return config?.operator?.hooks && typeof config.operator.hooks === "object"
+    ? config.operator.hooks
+    : null;
+}
+
+export function isOperatorHookPresetEnabled(presetId, startDir = process.cwd()) {
+  const hooks = operatorHookSection(startDir);
+  if (!hooks) return true;
+
+  const presets = Array.isArray(hooks.presets)
+    ? hooks.presets.filter((value) => typeof value === "string")
+    : null;
+  if (presets && presets.length > 0) {
+    return presets.includes(presetId);
+  }
+
+  const disabledPresets = Array.isArray(hooks.disabled_presets)
+    ? hooks.disabled_presets.filter((value) => typeof value === "string")
+    : [];
+  return !disabledPresets.includes(presetId);
+}
+
+/**
+ * Emit a single structured verbose line to stderr.
+ * Format: "[enact-operator] <hookName> ran — <result>"
+ *
+ * @param {string} hookName  e.g. "stop", "session-start", "pre-tool-use"
+ * @param {string} result    e.g. "allow (no autonomous lane active)", "denied (doom-loop)"
+ */
+export function verboseLog(hookName, result) {
+  process.stderr.write(`[enact-operator] ${hookName} ran — ${result}\n`);
+}