@telora/daemon 0.21.26 → 0.21.81

package/dist/audit/audit-phase.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Autonomous reality-tree audit phase.
+ *
+ * Replaces the runAuditPhase scaffold with a one-shot LLM assessor session
+ * that compares the focus's observable state against the CRT/FRT and mutates
+ * the graph via reality_tree_* MCP tools. The session's narrated summary
+ * is captured to an `audit_runs` row for human review.
+ *
+ * Failure modes never throw -- each path returns outcome='continue' with
+ * an explanatory rationale and metadata.errors entries. This keeps the
+ * focus loop running so a transient audit failure does not stall execution.
+ */
+import { type FocusPhaseOutcome } from '../queries/focus-cycle-evaluations.js';
+import { type AuditRunRow, type AuditRunStatus, type RecentAuditRun } from '../queries/audit-runs.js';
+import { type AuditSpawnOptions, type AuditSpawnResult } from '../spawn/index.js';
+import type { DaemonConfig } from '../types/index.js';
+/**
+ * Ordered assembly recipe for the audit prompt. Each entry resolves to a
+ * markdown section that gets composed into the assessor's input. Order
+ * matters: the assessor reads top-down so cycle context comes first, then
+ * code-level diff, then the live graph it must reconcile.
+ */
+export declare const AUDIT_ASSEMBLY_RECIPE: readonly string[];
+/**
+ * MCP tool names the assessor session is permitted to call.
+ *
+ * The audit is READ-ONLY w.r.t. code but AUTHORS intent structure: a CRT
+ * (entities + UDEs) plus an FRT of injections, self-validated via
+ * telora_reality_tree action=derive_frt (read-only, carried on the
+ * telora_reality_tree tool), then anchored to planning deliveries via
+ * telora_product_delivery create (injectionNodeId + executionStatus). It must
+ * NOT touch workflow state otherwise, and must NOT file remediation issues.
+ */
+export declare const AUDIT_MCP_TOOLS: readonly string[];
+/**
+ * Default Claude model for the audit assessor. Override via deps.
+ * Opus: the audit authors a navigable causal tree + injection plan -- the
+ * reasoning depth (root-cause attribution, FRT self-validation) warrants the
+ * stronger model. Matched as a substring by the telemetry pricing table (see
+ * spawner/lifecycle AUDIT_CAPTURE_MODEL).
+ */
+export declare const AUDIT_DEFAULT_MODEL = "opus";
+/** Default timeout for the assessor session (15 minutes). */
+export declare const AUDIT_DEFAULT_TIMEOUT_MS: number;
+/**
+ * Session lineage key for the audit assessor (INJ-E). The audit loop phase
+ * declares continuity 'resume' so the differential receiver accumulates
+ * cross-cycle memory of the gap's trajectory (convergence vs oscillation).
+ */
+export declare const AUDIT_LINEAGE = "audit";
+/**
+ * Audit prompt surface. The prompt text and its posture composition live in
+ * audit-prompt.ts (dependency-free string constants); this module owns the
+ * phase orchestration around it. Re-exported here so existing importers and
+ * tests that reference AUDIT_PROMPT / buildAuditPrompt / AuditPosture through
+ * audit-phase keep resolving.
+ */
+export { buildAuditPrompt, AUDIT_PROMPT, type AuditPosture, } from './audit-prompt.js';
+import type { AuditPosture } from './audit-prompt.js';
+export interface AuditPhaseResult {
+    outcome: FocusPhaseOutcome;
+    rationale?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The delivery fields the audit gates read. A structural subset of
+ * `FocusDeliveryInfo` -- the settle gate reads `executionStatus`, the
+ * change-detection gate reads `updatedAt`.
+ */
+export interface AuditGateDelivery {
+    executionStatus: string | null;
+    updatedAt?: string | null;
+}
+export interface AuditSummary {
+    summaryMd: string | null;
+    nodesTouched: number;
+    edgesTouched: number;
+}
+export type { AuditSpawnOptions, AuditSpawnResult } from '../spawn/index.js';
+/**
+ * Dependency-injected I/O for runAuditPhase. Tests stub these to avoid
+ * spawning processes or hitting Supabase.
+ */
+export interface AuditPhaseDeps {
+    assembleContext: (focusId: string, recipe: readonly string[]) => Promise<string>;
+    insertAuditRun: (input: {
+        focusId: string;
+        cycleNumber: number;
+        model: string | null;
+        sessionId: string | null;
+    }) => Promise<AuditRunRow>;
+    updateAuditRun: (input: {
+        auditRunId: string;
+        summaryMd: string | null;
+        nodesTouched: number;
+        edgesTouched: number;
+        status: AuditRunStatus;
+    }) => Promise<AuditRunRow>;
+    getCurrentCycleNumber: (focusId: string) => Promise<number>;
+    /**
+     * Fetch the focus's deliveries so the settle gate can decide whether to spawn
+     * the assessor at all. The execution status drives the settle gate (terminal
+     * vs not) and `updatedAt` drives the change-detection gate below it.
+     * Injected so tests drive the gates without live Supabase/MCP.
+     */
+    getFocusDeliveries: (focusId: string) => Promise<AuditGateDelivery[]>;
+    /**
+     * Fetch the focus's most recent audit run (null = never audited). Feeds the
+     * change-detection gate: a completed prior run whose `startedAt` is at or
+     * after every delivery's `updatedAt` means nothing has changed since the last
+     * audit, so there is nothing for the assessor to find. Rejects on API
+     * failure -- the gate then fails CLOSED for the tick.
+     */
+    getRecentAuditRun: (focusId: string) => Promise<RecentAuditRun | null>;
+    spawnAuditAgent: (opts: AuditSpawnOptions) => Promise<AuditSpawnResult>;
+    parseAuditSummary?: (stdout: string) => AuditSummary;
+    getConfig: () => DaemonConfig;
+    /**
+     * Resolve the prior session id for a focus's lineage (INJ-E). Returns null
+     * when there is no recorded session (first cycle). Optional so existing
+     * callers/tests that omit it simply get a fresh (non-resumed) assessor.
+     */
+    getResumeSessionId?: (focusId: string, lineage: string) => Promise<string | null>;
+    /** Persist the assessor's session id under the focus's lineage (INJ-E). */
+    persistSessionId?: (focusId: string, lineage: string, sessionId: string) => Promise<void>;
+    /**
+     * Open a role-less 'audit' agent_sessions row at assessor start and return its
+     * row id. The row id (NOT the Claude session id) becomes audit_runs.session_id
+     * so the FK resolves, and the row's run-time is observable. Best-effort: null
+     * when creation failed (the audit still records, with session_id NULL).
+     */
+    openAuditSession?: (focusId: string) => Promise<string | null>;
+    /** Close the 'audit' agent_sessions row on assessor exit (stamps ended_at). */
+    closeAuditSession?: (sessionId: string | null, success: boolean) => Promise<void>;
+}
+/**
+ * Parse the audit-summary tail block from assessor stdout. Returns null
+ * fields when the block is missing or malformed; the caller treats those
+ * as advisory zeros and writes them to the audit_runs row.
+ */
+export declare function parseAuditSummary(stdout: string): AuditSummary;
+/**
+ * Decide whether the focus's reality is provably UNCHANGED since the last
+ * completed audit run -- i.e. whether the assessor spawn is pure waste.
+ *
+ * Returns true (skip the spawn) only when every one of these holds:
+ *  - a prior audit run exists,
+ *  - that run COMPLETED (a run still in flight proves nothing about what it saw),
+ *  - every delivery carries an `updatedAt` timestamp, and
+ *  - none of those timestamps is later than the prior run's `startedAt`.
+ *
+ * Every other shape FAILS OPEN (returns false, assessor spawns): a first-ever
+ * audit, an incomplete prior run, a missing/unparseable timestamp. The gate
+ * exists to remove waste, never to withhold audit signal -- when it cannot
+ * PROVE nothing changed, it lets the audit run.
+ *
+ * `startedAt` (not `completedAt`) is the comparison point deliberately: the
+ * assessor observes the world as of the moment it began reading, so any
+ * delivery mutation after that instant is unobserved by that run.
+ */
+export declare function isUnchangedSinceLastAudit(deliveries: readonly AuditGateDelivery[], lastRun: RecentAuditRun | null): boolean;
+export declare const defaultAuditDeps: AuditPhaseDeps;
+/**
+ * Run the audit phase for a focus. Spawns a one-shot assessor, captures
+ * the audit-summary tail block, and writes an audit_runs row. Always
+ * returns 'continue' so the focus loop advances regardless of audit
+ * outcome -- the row + metadata.errors describe what happened.
+ */
+export declare function runAuditPhase(focusId: string, deps?: AuditPhaseDeps, posture?: AuditPosture): Promise<AuditPhaseResult>;
+//# sourceMappingURL=audit-phase.d.ts.map

package/dist/audit/audit-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-phase.d.ts","sourceRoot":"","sources":["../../src/audit/audit-phase.ts"],"names":[],"mappings":"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"}

package/dist/audit/audit-phase.js

@@ -0,0 +1,492 @@
+/**
+ * Autonomous reality-tree audit phase.
+ *
+ * Replaces the runAuditPhase scaffold with a one-shot LLM assessor session
+ * that compares the focus's observable state against the CRT/FRT and mutates
+ * the graph via reality_tree_* MCP tools. The session's narrated summary
+ * is captured to an `audit_runs` row for human review.
+ *
+ * Failure modes never throw -- each path returns outcome='continue' with
+ * an explanatory rationale and metadata.errors entries. This keeps the
+ * focus loop running so a transient audit failure does not stall execution.
+ */
+import { resolveAssemblyRecipe } from '../resolvers/assembly-engine.js';
+// Register resolvers used by the audit recipe at module load (side effect).
+import { initResolvers } from '../resolvers/index.js';
+initResolvers();
+import { getRecentFocusCycleEvaluation, } from '../queries/focus-cycle-evaluations.js';
+import { insertAuditRun, updateAuditRun, getRecentAuditRun, } from '../queries/audit-runs.js';
+import { openSystemSession, closeSystemSession } from '../queries/system-session.js';
+import { getFocusDeliveries, getFocusSessionIds, updateFocusClaudeSessionId } from '../queries/focuses.js';
+import { isFocusEnteringScoping } from '../focus/focus-phase.js';
+import { resolveResumeId } from '../session/session-lineage.js';
+import { getConfig } from '../queries/shared.js';
+import { spawnAuditAgent as spawnerSpawnAuditAgent, } from '../spawn/index.js';
+// ---------------------------------------------------------------------------
+// Constants exposed for testing and reuse
+// ---------------------------------------------------------------------------
+/**
+ * Ordered assembly recipe for the audit prompt. Each entry resolves to a
+ * markdown section that gets composed into the assessor's input. Order
+ * matters: the assessor reads top-down so cycle context comes first, then
+ * code-level diff, then the live graph it must reconcile.
+ */
+export const AUDIT_ASSEMBLY_RECIPE = [
+    'focus.context',
+    'retired_injections',
+    'delivery.listing(scope=done_since_last_audit)',
+    'git.diff_against_base',
+    'agent_session_summaries',
+    'agent_escalations',
+    'reality_tree.snapshot',
+];
+/**
+ * MCP tool names the assessor session is permitted to call.
+ *
+ * The audit is READ-ONLY w.r.t. code but AUTHORS intent structure: a CRT
+ * (entities + UDEs) plus an FRT of injections, self-validated via
+ * telora_reality_tree action=derive_frt (read-only, carried on the
+ * telora_reality_tree tool), then anchored to planning deliveries via
+ * telora_product_delivery create (injectionNodeId + executionStatus). It must
+ * NOT touch workflow state otherwise, and must NOT file remediation issues.
+ */
+export const AUDIT_MCP_TOOLS = [
+    'mcp__telora-products__telora_reality_tree',
+    'mcp__telora-products__telora_reality_tree_node',
+    'mcp__telora-products__telora_reality_tree_edge',
+    'mcp__telora-products__telora_reality_tree_link',
+    'mcp__telora-products__telora_product_delivery',
+];
+/**
+ * Default Claude model for the audit assessor. Override via deps.
+ * Opus: the audit authors a navigable causal tree + injection plan -- the
+ * reasoning depth (root-cause attribution, FRT self-validation) warrants the
+ * stronger model. Matched as a substring by the telemetry pricing table (see
+ * spawner/lifecycle AUDIT_CAPTURE_MODEL).
+ */
+export const AUDIT_DEFAULT_MODEL = 'opus';
+/** Default timeout for the assessor session (15 minutes). */
+export const AUDIT_DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+/**
+ * Session lineage key for the audit assessor (INJ-E). The audit loop phase
+ * declares continuity 'resume' so the differential receiver accumulates
+ * cross-cycle memory of the gap's trajectory (convergence vs oscillation).
+ */
+export const AUDIT_LINEAGE = 'audit';
+/**
+ * Audit prompt surface. The prompt text and its posture composition live in
+ * audit-prompt.ts (dependency-free string constants); this module owns the
+ * phase orchestration around it. Re-exported here so existing importers and
+ * tests that reference AUDIT_PROMPT / buildAuditPrompt / AuditPosture through
+ * audit-phase keep resolving.
+ */
+export { buildAuditPrompt, AUDIT_PROMPT, } from './audit-prompt.js';
+// Also imported for use below (a re-export does not bind these locally).
+import { buildAuditPrompt } from './audit-prompt.js';
+// ---------------------------------------------------------------------------
+// Summary parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse the audit-summary tail block from assessor stdout. Returns null
+ * fields when the block is missing or malformed; the caller treats those
+ * as advisory zeros and writes them to the audit_runs row.
+ */
+export function parseAuditSummary(stdout) {
+    const fenceRegex = /```audit-summary\s*\n([\s\S]*?)```/g;
+    let lastMatch = null;
+    let m;
+    while ((m = fenceRegex.exec(stdout)) !== null) {
+        lastMatch = m;
+    }
+    if (!lastMatch) {
+        return { summaryMd: null, nodesTouched: 0, edgesTouched: 0 };
+    }
+    const body = lastMatch[1];
+    let nodesTouched = 0;
+    let edgesTouched = 0;
+    let summaryMd = null;
+    const nodesMatch = /^\s*nodes_touched:\s*(\d+)\s*$/m.exec(body);
+    if (nodesMatch)
+        nodesTouched = parseInt(nodesMatch[1], 10);
+    const edgesMatch = /^\s*edges_touched:\s*(\d+)\s*$/m.exec(body);
+    if (edgesMatch)
+        edgesTouched = parseInt(edgesMatch[1], 10);
+    // summary: | <newline> then indented lines until end of block.
+    const summaryStart = /^\s*summary:\s*\|\s*$/m.exec(body);
+    if (summaryStart) {
+        const start = summaryStart.index + summaryStart[0].length;
+        const tail = body.slice(start);
+        // Each indented line (>= 2 spaces) is part of the summary; collect until
+        // we hit a non-indented non-empty line (none expected, but be safe).
+        const lines = tail.split('\n');
+        const collected = [];
+        for (const raw of lines) {
+            if (raw.trim().length === 0) {
+                collected.push('');
+                continue;
+            }
+            const dedented = raw.replace(/^ {2}/, '');
+            collected.push(dedented);
+        }
+        const joined = collected.join('\n').trim();
+        if (joined.length > 0)
+            summaryMd = joined;
+    }
+    return { summaryMd, nodesTouched, edgesTouched };
+}
+// ---------------------------------------------------------------------------
+// Change-detection gate
+// ---------------------------------------------------------------------------
+/**
+ * Decide whether the focus's reality is provably UNCHANGED since the last
+ * completed audit run -- i.e. whether the assessor spawn is pure waste.
+ *
+ * Returns true (skip the spawn) only when every one of these holds:
+ *  - a prior audit run exists,
+ *  - that run COMPLETED (a run still in flight proves nothing about what it saw),
+ *  - every delivery carries an `updatedAt` timestamp, and
+ *  - none of those timestamps is later than the prior run's `startedAt`.
+ *
+ * Every other shape FAILS OPEN (returns false, assessor spawns): a first-ever
+ * audit, an incomplete prior run, a missing/unparseable timestamp. The gate
+ * exists to remove waste, never to withhold audit signal -- when it cannot
+ * PROVE nothing changed, it lets the audit run.
+ *
+ * `startedAt` (not `completedAt`) is the comparison point deliberately: the
+ * assessor observes the world as of the moment it began reading, so any
+ * delivery mutation after that instant is unobserved by that run.
+ */
+export function isUnchangedSinceLastAudit(deliveries, lastRun) {
+    if (!lastRun || !lastRun.completedAt)
+        return false;
+    const runStartedMs = Date.parse(lastRun.startedAt);
+    if (Number.isNaN(runStartedMs))
+        return false;
+    for (const delivery of deliveries) {
+        if (!delivery.updatedAt)
+            return false;
+        const updatedMs = Date.parse(delivery.updatedAt);
+        if (Number.isNaN(updatedMs))
+            return false;
+        if (updatedMs > runStartedMs)
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Default dependency wiring
+// ---------------------------------------------------------------------------
+async function defaultAssembleContext(focusId, recipe) {
+    const config = getConfig();
+    const deliveries = await getFocusDeliveries(focusId);
+    const ctx = {
+        focusId,
+        deliveryIds: deliveries.map(d => d.id),
+        worktreePath: null,
+        config,
+        organizationId: config.organizationId,
+        productId: config.productId,
+    };
+    return await resolveAssemblyRecipe([...recipe], ctx);
+}
+async function defaultGetCurrentCycleNumber(focusId) {
+    const prev = await getRecentFocusCycleEvaluation(focusId);
+    if (!prev)
+        return 1;
+    // The audit phase is the entry to a new cycle iff the prior tick was
+    // evaluate -> continue. Otherwise we're inside an existing cycle.
+    if (prev.phase === 'evaluate' && prev.outcome === 'continue') {
+        return prev.cycle_number + 1;
+    }
+    return prev.cycle_number;
+}
+export const defaultAuditDeps = {
+    assembleContext: defaultAssembleContext,
+    insertAuditRun: ({ focusId, cycleNumber, model, sessionId }) => insertAuditRun({ focusId, cycleNumber, model, sessionId }),
+    updateAuditRun: ({ auditRunId, summaryMd, nodesTouched, edgesTouched, status }) => updateAuditRun({ auditRunId, summaryMd, nodesTouched, edgesTouched, status }),
+    getCurrentCycleNumber: defaultGetCurrentCycleNumber,
+    getFocusDeliveries: (focusId) => getFocusDeliveries(focusId),
+    getRecentAuditRun: (focusId) => getRecentAuditRun(focusId),
+    spawnAuditAgent: (opts) => spawnerSpawnAuditAgent(opts),
+    parseAuditSummary,
+    getConfig,
+    getResumeSessionId: async (focusId, lineage) => {
+        const map = await getFocusSessionIds(focusId);
+        // The audit phase declares continuity 'resume' (it is a loop phase, not a
+        // workflow stage); resolveResumeId keeps the resume rule uniform.
+        return resolveResumeId({ sessionMap: map, lineage, continuity: 'resume' });
+    },
+    persistSessionId: (focusId, lineage, sessionId) => updateFocusClaudeSessionId(focusId, lineage, sessionId),
+    openAuditSession: (focusId) => openSystemSession({
+        organizationId: getConfig().organizationId,
+        focusId,
+        branchName: `audit:${focusId}`,
+        sessionType: 'audit',
+    }),
+    closeAuditSession: (sessionId, success) => closeSystemSession(sessionId, { success }),
+};
+// ---------------------------------------------------------------------------
+// Core phase
+// ---------------------------------------------------------------------------
+/**
+ * Run the audit phase for a focus. Spawns a one-shot assessor, captures
+ * the audit-summary tail block, and writes an audit_runs row. Always
+ * returns 'continue' so the focus loop advances regardless of audit
+ * outcome -- the row + metadata.errors describe what happened.
+ */
+export async function runAuditPhase(focusId, deps = defaultAuditDeps, posture = 'live') {
+    const errors = [];
+    const metadata = { posture };
+    let cycleNumber = 1;
+    try {
+        cycleNumber = await deps.getCurrentCycleNumber(focusId);
+    }
+    catch (err) {
+        errors.push(`cycle_lookup: ${err.message}`);
+    }
+    metadata.cycleNumber = cycleNumber;
+    // ── Scoping-entry gate ───────────────────────────────────────────────────
+    // The audit is the scope-time CRT self-refresh: it must run when a scoping
+    // decision is about to READ the tree, and NEVER while a team is mid-stroke
+    // (spawning the opus assessor mid-coding samples the team's transient,
+    // intended error as drift -- noise -- and burns an opus --print call that
+    // authors nothing). So gate the spawn on the focus being at the FRONT OF A
+    // SCOPING ACT: it has pre-coding work to scope (a queued/planning delivery)
+    // and nothing is actuating (no coding/verify_failed delivery). See
+    // focus-phase.isFocusEnteringScoping. This REPLACES the old all-terminal
+    // settle gate -- a settled focus is not being scoped, so it no longer
+    // triggers an audit; the mid-stroke protection is preserved by the
+    // "nothing actuating" clause. A focus with zero deliveries never spawns.
+    let deliveries;
+    try {
+        deliveries = await deps.getFocusDeliveries(focusId);
+    }
+    catch (err) {
+        // Cannot read the deliveries -> cannot prove the focus is at a scoping
+        // boundary. Skip the spawn (the expensive thing this gate rations) and let
+        // the next tick retry; never throw, so the focus loop keeps advancing.
+        errors.push(`deliveries_lookup: ${err.message}`);
+        metadata.gated = true;
+        metadata.gateReason = 'deliveries_lookup_failed';
+        metadata.errors = errors;
+        return {
+            outcome: 'continue',
+            rationale: `audit cycle ${cycleNumber} skipped -- could not read deliveries to confirm scoping boundary`,
+            metadata,
+        };
+    }
+    metadata.deliveryCount = deliveries.length;
+    if (!isFocusEnteringScoping(deliveries)) {
+        const reason = deliveries.length === 0 ? 'no_deliveries' : 'not_entering_scoping';
+        metadata.gated = true;
+        metadata.gateReason = reason;
+        if (errors.length > 0)
+            metadata.errors = errors;
+        return {
+            outcome: 'continue',
+            rationale: reason === 'no_deliveries'
+                ? `audit cycle ${cycleNumber} skipped -- focus has no deliveries to scope`
+                : `audit cycle ${cycleNumber} skipped -- focus not at a scoping boundary (no pre-coding work, or a delivery is actuating)`,
+            metadata,
+        };
+    }
+    // ── Change-detection gate ────────────────────────────────────────────────
+    // The settle gate above rations the spawn to settled focuses -- but a focus
+    // STAYS settled forever, so on its own it re-spawns an opus assessor against
+    // an unchanged world every cycle. Telemetry (2026-07-22) measured the result:
+    // 1,167 of 1,192 audit runs (97.9%) touched zero nodes and zero edges. A
+    // settled focus whose deliveries have not moved since the last completed
+    // audit has, by construction, nothing new for the assessor to observe. So
+    // gate again on CHANGE: compare each delivery's updatedAt against the prior
+    // completed run's started_at. Fails OPEN on any uncertainty (see
+    // isUnchangedSinceLastAudit) -- this gate removes waste, it never withholds
+    // audit signal.
+    let lastRun = null;
+    try {
+        lastRun = await deps.getRecentAuditRun(focusId);
+    }
+    catch (err) {
+        // Cannot read the prior run -> cannot decide whether anything changed.
+        // Fail CLOSED for this tick (skip the expensive spawn, retry next), the
+        // same precedent the settle gate's deliveries-lookup failure sets.
+        errors.push(`recent_audit_lookup: ${err.message}`);
+        metadata.gated = true;
+        metadata.gateReason = 'recent_audit_lookup_failed';
+        metadata.errors = errors;
+        return {
+            outcome: 'continue',
+            rationale: `audit cycle ${cycleNumber} skipped -- could not read the last audit run to detect change`,
+            metadata,
+        };
+    }
+    if (isUnchangedSinceLastAudit(deliveries, lastRun)) {
+        metadata.gated = true;
+        metadata.gateReason = 'no_change_since_last_audit';
+        metadata.lastAuditRunId = lastRun?.id ?? null;
+        metadata.lastAuditStartedAt = lastRun?.startedAt ?? null;
+        if (errors.length > 0)
+            metadata.errors = errors;
+        return {
+            outcome: 'continue',
+            rationale: `audit cycle ${cycleNumber} skipped -- no delivery changed since the last completed audit`,
+            metadata,
+        };
+    }
+    let assembled = '';
+    try {
+        assembled = await deps.assembleContext(focusId, AUDIT_ASSEMBLY_RECIPE);
+    }
+    catch (err) {
+        errors.push(`assembly: ${err.message}`);
+    }
+    const config = deps.getConfig();
+    const auditPrompt = buildAuditPrompt(posture);
+    const prompt = assembled
+        ? `${assembled}\n\n---\n\n${auditPrompt}`
+        : auditPrompt;
+    // Resolve the prior audit-lineage session id to resume (INJ-E). Best-effort:
+    // a lookup failure or an empty slot (first cycle) just yields a fresh session.
+    let resumeSessionId = null;
+    if (deps.getResumeSessionId) {
+        try {
+            resumeSessionId = await deps.getResumeSessionId(focusId, AUDIT_LINEAGE);
+        }
+        catch (err) {
+            errors.push(`resume_lookup: ${err.message}`);
+        }
+    }
+    metadata.resumed = !!resumeSessionId;
+    // Open a role-less 'audit' agent_sessions row so (a) the assessor's run-time
+    // is observable and (b) audit_runs.session_id has a valid FK target. The row
+    // id -- NOT the Claude session id -- is what audit_runs references. Best-effort:
+    // a null id just leaves audit_runs.session_id NULL (which inserts fine).
+    let auditSessionRowId = null;
+    if (deps.openAuditSession) {
+        try {
+            auditSessionRowId = await deps.openAuditSession(focusId);
+        }
+        catch (err) {
+            errors.push(`open_audit_session: ${err.message}`);
+        }
+    }
+    metadata.auditSessionRowId = auditSessionRowId;
+    let spawnResult;
+    try {
+        spawnResult = await deps.spawnAuditAgent({
+            config,
+            prompt,
+            worktreePath: null,
+            focusId,
+            cycleNumber,
+            model: AUDIT_DEFAULT_MODEL,
+            timeoutMs: AUDIT_DEFAULT_TIMEOUT_MS,
+            allowedTools: AUDIT_MCP_TOOLS,
+            resumeSessionId,
+        });
+    }
+    catch (err) {
+        errors.push(`spawn: ${err.message}`);
+        spawnResult = { exitCode: null, stdout: '', stderr: '', errorMessage: err.message };
+    }
+    // Close the 'audit' agent_sessions row now the assessor has exited (stamps
+    // ended_at + terminal status). Success = clean exit with no spawn error.
+    if (deps.closeAuditSession) {
+        const auditSucceeded = spawnResult.exitCode === 0 && !spawnResult.errorMessage;
+        try {
+            await deps.closeAuditSession(auditSessionRowId, auditSucceeded);
+        }
+        catch (err) {
+            errors.push(`close_audit_session: ${err.message}`);
+        }
+    }
+    // Persist the assessor's session id under the focus's 'audit' lineage so the
+    // next cycle resumes it (INJ-E). Best-effort -- a persist failure only loses
+    // continuity for the next cycle, it never fails the audit.
+    if (spawnResult.sessionId && deps.persistSessionId) {
+        metadata.auditSessionId = spawnResult.sessionId;
+        try {
+            await deps.persistSessionId(focusId, AUDIT_LINEAGE, spawnResult.sessionId);
+        }
+        catch (err) {
+            errors.push(`persist_session_id: ${err.message}`);
+        }
+    }
+    // Record the audit run. session_id references the 'audit' agent_sessions ROW
+    // id (FK target), NOT the Claude session id -- writing the bare Claude id is
+    // exactly what made every insert violate audit_runs_session_id_fkey since the
+    // 2026-06-03 deploy. The Claude session id lives on the focus lineage (above)
+    // for --resume, not here.
+    let auditRunId = null;
+    try {
+        const row = await deps.insertAuditRun({
+            focusId, cycleNumber, model: AUDIT_DEFAULT_MODEL, sessionId: auditSessionRowId,
+        });
+        auditRunId = row.id;
+        metadata.auditRunId = row.id;
+    }
+    catch (err) {
+        errors.push(`insert_audit_run: ${err.message}`);
+    }
+    if (spawnResult.errorMessage) {
+        errors.push(`spawn: ${spawnResult.errorMessage}`);
+    }
+    if (spawnResult.exitCode !== null && spawnResult.exitCode !== 0) {
+        errors.push(`exit_code: ${spawnResult.exitCode}`);
+        if (spawnResult.stderr) {
+            metadata.stderrTail = spawnResult.stderr.slice(-1000);
+        }
+    }
+    const parser = deps.parseAuditSummary ?? parseAuditSummary;
+    const summary = parser(spawnResult.stdout);
+    if (summary.summaryMd === null) {
+        errors.push('summary_block_missing');
+    }
+    metadata.nodesTouched = summary.nodesTouched;
+    metadata.edgesTouched = summary.edgesTouched;
+    // Classify the run's terminal outcome so it is separable in the data and a
+    // broken run never masquerades as a clean cycle boundary.
+    //  - 'failed'       the session did not genuinely complete (non-zero exit or a
+    //                   spawn error). This takes PRECEDENCE over a missing summary:
+    //                   a failed run's absent block is a symptom, not the diagnosis,
+    //                   and the update handler leaves completed_at NULL for it so the
+    //                   change-detection gate keeps failing open.
+    //  - 'parse_failed' clean exit, but no parsable summary block -- distinguishable
+    //                   from an honest no-op, which carries a real summary_md.
+    //  - 'completed'    clean exit with a parsable summary (includes honest no-ops).
+    const runFailed = !!spawnResult.errorMessage ||
+        (spawnResult.exitCode !== null && spawnResult.exitCode !== 0);
+    const runStatus = runFailed
+        ? 'failed'
+        : summary.summaryMd === null
+            ? 'parse_failed'
+            : 'completed';
+    metadata.auditRunStatus = runStatus;
+    if (auditRunId) {
+        try {
+            await deps.updateAuditRun({
+                auditRunId,
+                summaryMd: summary.summaryMd,
+                nodesTouched: summary.nodesTouched,
+                edgesTouched: summary.edgesTouched,
+                status: runStatus,
+            });
+        }
+        catch (err) {
+            errors.push(`update_audit_run: ${err.message}`);
+        }
+    }
+    if (errors.length > 0) {
+        metadata.errors = errors;
+        return {
+            outcome: 'continue',
+            rationale: `audit cycle ${cycleNumber} completed with ${errors.length} issue(s)`,
+            metadata,
+        };
+    }
+    return {
+        outcome: 'continue',
+        rationale: `audit cycle ${cycleNumber} -- ${summary.nodesTouched} nodes touched, ${summary.edgesTouched} edges touched`,
+        metadata,
+    };
+}
+//# sourceMappingURL=audit-phase.js.map