@principles/codex-adapter 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -13,7 +13,13 @@ export { resolveCodexHome, canonicalizePath } from './ingestion/codex-home.js';
 export { validateCodexTranscriptPath } from './ingestion/transcript-path.js';
 export type { TranscriptPathValidation, TranscriptFileIdentity } from './ingestion/transcript-path.js';
 export { classifyCodexVersion, CODEX_INGESTION_MIN_VERSION, CODEX_INGESTION_VERIFIED_VERSION } from './ingestion/codex-version.js';
-export { ingestCodexConversation, setCodexTranscriptPortForTest } from './ingestion/ingestion.js';
-export type { CodexIngestionOptions, CodexIngestionOutcome } from './ingestion/ingestion.js';
+export { ingestCodexConversation, setCodexTranscriptPortForTest, ingestCodexTranscriptFromPath } from './ingestion/ingestion.js';
+export type { CodexIngestionOptions, CodexIngestionOutcome, CodexTranscriptFromPathArgs } from './ingestion/ingestion.js';
 export { decodeTranscriptWindow, createNodeTranscriptPort, TranscriptReplacedError, CODEX_INGESTION_MAX_BATCH_BYTES, CODEX_INGESTION_MAX_BATCH_RECORDS } from './ingestion/transcript-decoder.js';
 export type { TranscriptPort, TranscriptExpectedIdentity, DecodedDelta, TranscriptDecodeStop } from './ingestion/transcript-decoder.js';
+export { catchUpCodexIngestion, CODEX_CATCH_UP_NEXT_ACTION } from './ingestion/catch-up.js';
+export type { CodexCatchUpOptions, CodexCatchUpResult, CodexCatchUpRolloutResult } from './ingestion/catch-up.js';
+export { locateCodexTranscriptByRolloutIdentity } from './ingestion/transcript-locate.js';
+export type { CodexTranscriptLookup } from './ingestion/transcript-locate.js';
+export { runCodexWorkspaceWorkerCycle, computeCodexWorkerStatusMode } from './worker/workspace-worker.js';
+export type { CodexWorkerMode, CodexWorkerCycleResult, CodexWorkerCycleStepReport, CodexWorkerCycleOptions, CodexWorkerStatusEvaluation } from './worker/workspace-worker.js';

package/dist/index.js

@@ -11,5 +11,9 @@ export * from './codec/index.js';
 export { resolveCodexHome, canonicalizePath } from './ingestion/codex-home.js';
 export { validateCodexTranscriptPath } from './ingestion/transcript-path.js';
 export { classifyCodexVersion, CODEX_INGESTION_MIN_VERSION, CODEX_INGESTION_VERIFIED_VERSION } from './ingestion/codex-version.js';
-export { ingestCodexConversation, setCodexTranscriptPortForTest } from './ingestion/ingestion.js';
+export { ingestCodexConversation, setCodexTranscriptPortForTest, ingestCodexTranscriptFromPath } from './ingestion/ingestion.js';
 export { decodeTranscriptWindow, createNodeTranscriptPort, TranscriptReplacedError, CODEX_INGESTION_MAX_BATCH_BYTES, CODEX_INGESTION_MAX_BATCH_RECORDS } from './ingestion/transcript-decoder.js';
+// PRI-624 Slice C: bounded catch-up + per-workspace worker cycle.
+export { catchUpCodexIngestion, CODEX_CATCH_UP_NEXT_ACTION } from './ingestion/catch-up.js';
+export { locateCodexTranscriptByRolloutIdentity } from './ingestion/transcript-locate.js';
+export { runCodexWorkspaceWorkerCycle, computeCodexWorkerStatusMode } from './worker/workspace-worker.js';

package/dist/ingestion/admission.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Codex governance admission orchestration (Codex Governance Closure Slice B,
+ * PRI-623; SPEC §12/§13).
+ *
+ * Owns ONLY the Codex facts: mapping live hook payloads and decoded transcript
+ * observations onto the host-neutral admission candidates of
+ * `@principles/host-runtime` (`admitGovernanceSignals`), then driving the
+ * admitted pains through the existing continuation seams —
+ * `ensureGovernanceDiagnosticianTask` (Runtime V2 async enqueue, never an
+ * LLM) and `promoteAdmittedGovernanceEvidence` (Slice A's ≤12 + trigger +
+ * next-assistant window with its durable pending tail).
+ *
+ * No Codex JSONL knowledge crosses into host-runtime; no second pain or task
+ * authority exists here.
+ */
+import { type GovernanceSignalCandidate } from '@principles/host-runtime';
+import type { GovernanceObservationInput } from '@principles/host-runtime';
+import type { PayloadFields } from './ingestion-fields.js';
+export interface GovernanceAdmissionDegradation {
+    readonly reason: string;
+    readonly nextAction: string;
+}
+export interface GovernanceAdmissionRun {
+    /** Bounded structured degradations (only real failures; duplicate / rate-limited / ordinary conversation are normal outcomes and stay silent, SPEC §20/§21). */
+    readonly degradations: readonly GovernanceAdmissionDegradation[];
+}
+/** Live UserPromptSubmit payload → correction candidate (logical key mirrors the observation). */
+export declare function buildLiveCorrectionCandidate(args: {
+    fields: PayloadFields;
+    rolloutIdentity: string;
+}): GovernanceSignalCandidate | null;
+/** Live PostToolUse payload → tool-failure candidate (logical key mirrors the observation). */
+export declare function buildLiveToolCandidate(args: {
+    fields: PayloadFields;
+    rolloutIdentity: string;
+}): GovernanceSignalCandidate | null;
+/**
+ * Decoded transcript observations → candidates. User turns carry visibleText;
+ * tool calls carry the CommandExecution facts projection. The logical keys are
+ * the decoded ones, so a replay of an already-admitted live event is an
+ * observation-level no-op (SPEC §10).
+ */
+export declare function buildTranscriptCandidates(observations: readonly GovernanceObservationInput[]): readonly GovernanceSignalCandidate[];
+/**
+ * Run admission for the given candidates and drive every admitted pain
+ * through task-ensure + evidence promotion. Exactly-once is owned by the
+ * host-runtime seams; this orchestrator only sequences them and surfaces
+ * bounded degradations (duplicate / rate-limited / ordinary conversation are
+ * normal outcomes and produce no noise, SPEC §20/§21).
+ */
+export declare function runGovernanceAdmission(args: {
+    workspaceDir: string;
+    candidates: readonly GovernanceSignalCandidate[];
+}): Promise<GovernanceAdmissionRun>;

package/dist/ingestion/admission.js

@@ -0,0 +1,137 @@
+/**
+ * Codex governance admission orchestration (Codex Governance Closure Slice B,
+ * PRI-623; SPEC §12/§13).
+ *
+ * Owns ONLY the Codex facts: mapping live hook payloads and decoded transcript
+ * observations onto the host-neutral admission candidates of
+ * `@principles/host-runtime` (`admitGovernanceSignals`), then driving the
+ * admitted pains through the existing continuation seams —
+ * `ensureGovernanceDiagnosticianTask` (Runtime V2 async enqueue, never an
+ * LLM) and `promoteAdmittedGovernanceEvidence` (Slice A's ≤12 + trigger +
+ * next-assistant window with its durable pending tail).
+ *
+ * No Codex JSONL knowledge crosses into host-runtime; no second pain or task
+ * authority exists here.
+ */
+import { admitGovernanceSignals, ensureGovernanceContinuation, } from '@principles/host-runtime';
+import { isRecord, own } from './ingestion-fields.js';
+/** The live host-event source used by the identity derivation (parity with the dispatch handler). */
+const CODEX_POST_TOOL_USE_SOURCE = 'codex:post_tool_use';
+/** Live UserPromptSubmit payload → correction candidate (logical key mirrors the observation). */
+export function buildLiveCorrectionCandidate(args) {
+    const { fields } = args;
+    if (fields.turnId === null || fields.prompt === null)
+        return null;
+    return {
+        kind: 'user_correction',
+        hostKind: 'codex',
+        logicalObservationKey: `codex|${args.rolloutIdentity}|${fields.turnId}|user`,
+        rolloutIdentity: args.rolloutIdentity,
+        rootSessionId: fields.sessionId,
+        hostTurnId: fields.turnId,
+        text: fields.prompt,
+        observedAt: new Date().toISOString(),
+    };
+}
+/** Live PostToolUse payload → tool-failure candidate (logical key mirrors the observation). */
+export function buildLiveToolCandidate(args) {
+    const { fields } = args;
+    if (fields.turnId === null || fields.toolUseId === null)
+        return null;
+    return {
+        kind: 'tool_failure',
+        hostKind: 'codex',
+        logicalObservationKey: `codex|${args.rolloutIdentity}|${fields.toolUseId}`,
+        rolloutIdentity: args.rolloutIdentity,
+        rootSessionId: fields.sessionId,
+        hostTurnId: fields.turnId,
+        toolName: fields.toolName ?? '',
+        source: CODEX_POST_TOOL_USE_SOURCE,
+        ...(fields.toolInput !== undefined ? { toolInput: fields.toolInput } : {}),
+        ...(fields.toolResponse !== undefined ? { toolOutput: fields.toolResponse } : {}),
+        observedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Decoded transcript observations → candidates. User turns carry visibleText;
+ * tool calls carry the CommandExecution facts projection. The logical keys are
+ * the decoded ones, so a replay of an already-admitted live event is an
+ * observation-level no-op (SPEC §10).
+ */
+export function buildTranscriptCandidates(observations) {
+    const candidates = [];
+    for (const observation of observations) {
+        if (observation.kind === 'user_turn') {
+            if (observation.visibleText === undefined)
+                continue;
+            candidates.push({
+                kind: 'user_correction',
+                hostKind: 'codex',
+                logicalObservationKey: observation.logicalObservationKey,
+                rolloutIdentity: observation.rolloutIdentity,
+                rootSessionId: observation.rootSessionId,
+                hostTurnId: observation.hostTurnId,
+                text: observation.visibleText,
+                observedAt: observation.observedAt,
+            });
+        }
+        else if (observation.kind === 'tool_call') {
+            const facts = observation.toolFacts;
+            if (!isRecord(facts))
+                continue;
+            const toolName = own(facts, 'toolName');
+            const exitCode = own(facts, 'exitCode');
+            candidates.push({
+                kind: 'tool_failure',
+                hostKind: 'codex',
+                logicalObservationKey: observation.logicalObservationKey,
+                rolloutIdentity: observation.rolloutIdentity,
+                rootSessionId: observation.rootSessionId,
+                hostTurnId: observation.hostTurnId,
+                toolName: typeof toolName === 'string' ? toolName : '',
+                source: CODEX_POST_TOOL_USE_SOURCE,
+                toolInput: own(facts, 'command') ?? null,
+                ...(exitCode !== undefined ? { toolOutput: { exitCode, stdout: own(facts, 'stdout') ?? null, stderr: own(facts, 'stderr') ?? null } } : {}),
+                observedAt: observation.observedAt,
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * Run admission for the given candidates and drive every admitted pain
+ * through task-ensure + evidence promotion. Exactly-once is owned by the
+ * host-runtime seams; this orchestrator only sequences them and surfaces
+ * bounded degradations (duplicate / rate-limited / ordinary conversation are
+ * normal outcomes and produce no noise, SPEC §20/§21).
+ */
+export async function runGovernanceAdmission(args) {
+    const { workspaceDir, candidates } = args;
+    if (candidates.length === 0)
+        return { degradations: [] };
+    const degradations = [];
+    const push = (reason, nextAction) => {
+        if (degradations.length < 4)
+            degradations.push({ reason: reason.slice(0, 300), nextAction: nextAction.slice(0, 300) });
+    };
+    const admitted = admitGovernanceSignals({ workspaceDir, candidates });
+    if (!admitted.ok) {
+        push(admitted.reason, admitted.nextAction);
+        return { degradations };
+    }
+    for (const outcome of admitted.outcomes) {
+        if (!('disposition' in outcome))
+            continue;
+        if (outcome.disposition !== 'admitted' && outcome.disposition !== 'already_admitted')
+            continue;
+        const cont = await ensureGovernanceContinuation({
+            workspaceDir,
+            logicalObservationKey: outcome.logicalObservationKey,
+            canonicalPainId: outcome.canonicalPainId,
+        });
+        if (!cont.ok) {
+            push(cont.reason, cont.nextAction);
+        }
+    }
+    return { degradations };
+}

package/dist/ingestion/catch-up.d.ts

@@ -0,0 +1,41 @@
+import { type CodexIngestionOutcome } from './ingestion.js';
+import type { TranscriptPort } from './transcript-decoder.js';
+export interface CodexCatchUpOptions {
+    readonly workspaceDir: string;
+    readonly env?: {
+        CODEX_HOME?: string | undefined;
+    };
+    readonly now?: Date;
+    readonly port?: TranscriptPort;
+    /** Bounded per invocation (default 8 rollouts × the 1 MiB batch bound). */
+    readonly maxRollouts?: number;
+}
+export interface CodexCatchUpRolloutResult {
+    readonly rolloutIdentity: string;
+    readonly outcome: CodexIngestionOutcome;
+    /** Admission degradations from this rollout's candidates (bounded by runGovernanceAdmission). */
+    readonly admissionDegradations: readonly {
+        reason: string;
+        nextAction: string;
+    }[];
+}
+export type CodexCatchUpResult = {
+    status: 'skipped';
+    reason: string;
+    nextAction: string;
+} | {
+    status: 'ok' | 'degraded';
+    /** Rollouts processed this invocation (bounded). */
+    readonly rollouts: readonly CodexCatchUpRolloutResult[];
+    /** Processed rollouts that still carry lag (degraded or lagBytes > 0). */
+    readonly remainingLagRollouts: readonly string[];
+    /** Checkpoints not examined this invocation because of the bound (rotation converges them over repeated passes). */
+    readonly unexaminedRollouts: readonly string[];
+};
+export declare const CODEX_CATCH_UP_NEXT_ACTION = "Set features.codex_conversation_ingestion.enabled=true in the selected Workspace .pd/config.yaml to enable bounded conversation ingestion.";
+/**
+ * Perform one bounded catch-up pass. `remainingLagRollouts` is derived from
+ * each processed rollout's reported lag plus the checkpoints left unprocessed
+ * by the bound — callers (worker cycle / CLI) repeat passes to converge.
+ */
+export declare function catchUpCodexIngestion(options: CodexCatchUpOptions): Promise<CodexCatchUpResult>;

package/dist/ingestion/catch-up.js

@@ -0,0 +1,94 @@
+/**
+ * Codex ingestion catch-up (PRI-624 Slice C; SPEC §13/§15).
+ *
+ * Bounded non-destructive catch-up of transcript lag for rollouts the
+ * authenticated Workspace hook already delivered: every checkpoint in the
+ * workspace trajectory database names a rollout that once arrived with an
+ * authenticated transcript_path. For each (bounded) checkpoint we resolve the
+ * rollout's transcript by EXACT uuid (never a session scan), re-authorize the
+ * path through the same validator the hook uses, run the same bounded
+ * incremental delta from the checkpoint, and feed any admission candidates
+ * through the same Slice B admission/continuation pass the hook runs.
+ *
+ * Gated by `codex_conversation_ingestion`: flag-off performs ZERO transcript
+ * filesystem I/O — no checkpoint-to-path resolution, no sessions-tree lookup,
+ * no reads (SPEC §10 hard privacy invariant; the port spy test covers the
+ * lookup path too).
+ */
+import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin, listGovernanceCheckpoints } from '@principles/host-runtime';
+import { resolveCodexHome } from './codex-home.js';
+import { locateCodexTranscriptByRolloutIdentity } from './transcript-locate.js';
+import { ingestCodexTranscriptFromPath } from './ingestion.js';
+import { runGovernanceAdmission } from './admission.js';
+const DEFAULT_MAX_ROLLOUTS = 8;
+export const CODEX_CATCH_UP_NEXT_ACTION = 'Set features.codex_conversation_ingestion.enabled=true in the selected Workspace .pd/config.yaml to enable bounded conversation ingestion.';
+/**
+ * Perform one bounded catch-up pass. `remainingLagRollouts` is derived from
+ * each processed rollout's reported lag plus the checkpoints left unprocessed
+ * by the bound — callers (worker cycle / CLI) repeat passes to converge.
+ */
+export async function catchUpCodexIngestion(options) {
+    const { workspaceDir } = options;
+    // Flag gate FIRST — before resolveCodexHome, checkpoint listing, any FS I/O.
+    const config = loadPdConfigForPlugin(workspaceDir);
+    if (!config.ok) {
+        const [first] = config.errors;
+        return { status: 'skipped', reason: `pd_config_invalid:${first?.reason ?? 'unknown'}`, nextAction: first?.nextAction ?? 'Repair .pd/config.yaml.' };
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    if (flags['host.codex']?.enabled !== true) {
+        return { status: 'skipped', reason: 'host.codex_disabled', nextAction: 'Set features.host.codex.enabled=true in the selected Workspace to enable PD.' };
+    }
+    if (flags.codex_conversation_ingestion?.enabled !== true) {
+        return { status: 'skipped', reason: 'feature_disabled', nextAction: CODEX_CATCH_UP_NEXT_ACTION };
+    }
+    const home = resolveCodexHome(options.env);
+    if (!home.ok)
+        return { status: 'skipped', reason: home.reason, nextAction: home.nextAction };
+    const listed = listGovernanceCheckpoints({ workspaceDir, hostKind: 'codex' });
+    if (!listed.ok)
+        return { status: 'skipped', reason: listed.reason, nextAction: listed.nextAction };
+    const maxRollouts = Math.max(1, Math.min(options.maxRollouts ?? DEFAULT_MAX_ROLLOUTS, 32));
+    const checkpoints = listed.checkpoints.slice(0, maxRollouts);
+    const unprocessed = listed.checkpoints.slice(maxRollouts);
+    const rollouts = [];
+    const remainingLagRollouts = [];
+    for (const checkpoint of checkpoints) {
+        const located = locateCodexTranscriptByRolloutIdentity(home.home, checkpoint.rolloutIdentity);
+        if (!located.ok) {
+            remainingLagRollouts.push(checkpoint.rolloutIdentity);
+            rollouts.push({
+                rolloutIdentity: checkpoint.rolloutIdentity,
+                outcome: { status: 'degraded', reason: located.reason, nextAction: located.nextAction, warnings: [] },
+                admissionDegradations: [],
+            });
+            continue;
+        }
+        const outcome = ingestCodexTranscriptFromPath({
+            workspaceDir,
+            transcriptPath: located.transcriptPath,
+            fallbackRootSessionId: checkpoint.rootSessionId,
+            env: options.env,
+            now: options.now,
+            port: options.port,
+        });
+        let admissionDegradations = [];
+        if (outcome.status === 'ok' && outcome.admissionCandidates.length > 0) {
+            const admission = await runGovernanceAdmission({ workspaceDir, candidates: outcome.admissionCandidates });
+            admissionDegradations = [...admission.degradations];
+        }
+        if (outcome.status !== 'ok' || outcome.lagBytes > 0) {
+            remainingLagRollouts.push(checkpoint.rolloutIdentity);
+        }
+        rollouts.push({ rolloutIdentity: checkpoint.rolloutIdentity, outcome, admissionDegradations });
+    }
+    const unexaminedRollouts = unprocessed.map((leftover) => leftover.rolloutIdentity);
+    const anyDegraded = rollouts.some((entry) => entry.outcome.status === 'degraded' || entry.admissionDegradations.length > 0);
+    return {
+        status: anyDegraded ? 'degraded' : 'ok',
+        rollouts,
+        remainingLagRollouts,
+        unexaminedRollouts,
+    };
+}

package/dist/ingestion/ingestion-fields.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Codex hook payload field extraction (Slice A) — shared by the live
+ * observation ingestor and the Slice B admission orchestrator.
+ */
+export interface PayloadFields {
+    transcriptPath: string | null;
+    sessionId: string;
+    turnId: string | null;
+    prompt: string | null;
+    toolUseId: string | null;
+    toolName: string | null;
+    toolInput: unknown;
+    toolResponse: unknown;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function own(value: Record<string, unknown>, key: string): unknown;
+export declare function extractFields(raw: unknown): PayloadFields | null;

package/dist/ingestion/ingestion-fields.js

@@ -0,0 +1,28 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function own(value, key) {
+    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+export function extractFields(raw) {
+    if (!isRecord(raw))
+        return null;
+    const transcriptPath = own(raw, 'transcript_path');
+    if (transcriptPath !== null && typeof transcriptPath !== 'string')
+        return null;
+    const sessionId = own(raw, 'session_id');
+    const turnId = own(raw, 'turn_id');
+    const prompt = own(raw, 'prompt');
+    const toolUseId = own(raw, 'tool_use_id');
+    const toolName = own(raw, 'tool_name');
+    return {
+        transcriptPath: transcriptPath ?? null,
+        sessionId: typeof sessionId === 'string' ? sessionId : '',
+        turnId: typeof turnId === 'string' ? turnId : null,
+        prompt: typeof prompt === 'string' ? prompt : null,
+        toolUseId: typeof toolUseId === 'string' ? toolUseId : null,
+        toolName: typeof toolName === 'string' ? toolName : null,
+        toolInput: own(raw, 'tool_input'),
+        toolResponse: own(raw, 'tool_response'),
+    };
+}

package/dist/ingestion/ingestion.d.ts

@@ -19,6 +19,7 @@
  * the transcript replay later converges with (SPEC §10 source precedence).
  */
 import type { HostEventKind } from '@principles/core/host';
+import { type GovernanceSignalCandidate } from '@principles/host-runtime';
 import { type TranscriptPort } from './transcript-decoder.js';
 export interface CodexIngestionOptions {
     readonly workspaceDir: string;
@@ -35,6 +36,9 @@ export type CodexIngestionOutcome = {
     duplicates: number;
     warnings: readonly string[];
     lagBytes: number;
+    /** Slice B: normalized admission candidates for the committed observations (host-neutral; consumed by pd-hook's admission pass). */
+    readonly admissionCandidates: readonly GovernanceSignalCandidate[];
+    readonly rolloutIdentity: string;
 } | {
     status: 'degraded';
     reason: string;
@@ -44,3 +48,24 @@ export type CodexIngestionOutcome = {
 /** Test seam: inject/inspect the transcript filesystem boundary (zero-read proofs). */
 export declare function setCodexTranscriptPortForTest(port: TranscriptPort | null): void;
 export declare function ingestCodexConversation(rawPayload: unknown, kind: HostEventKind, options: CodexIngestionOptions): CodexIngestionOutcome;
+export interface CodexTranscriptFromPathArgs {
+    readonly workspaceDir: string;
+    /** Absolute transcript path (catch-up resolves it by exact rollout identity before calling). */
+    readonly transcriptPath: string;
+    /** Fallback root session when neither the transcript nor the checkpoint carries one. */
+    readonly fallbackRootSessionId: string;
+    readonly env?: {
+        CODEX_HOME?: string | undefined;
+    };
+    readonly now?: Date;
+    readonly port?: TranscriptPort;
+}
+/**
+ * PRI-624 (Slice C): bounded incremental ingest of one known rollout from its
+ * durable checkpoint, driven by an explicit transcript path instead of a live
+ * hook payload. The path is re-authorized through the same
+ * `validateCodexTranscriptPath` containment + post-open identity contract the
+ * hook path uses (SPEC §9) — callers MUST only pass paths resolved from
+ * previously-authenticated rollouts (checkpoints), never discovered sessions.
+ */
+export declare function ingestCodexTranscriptFromPath(args: CodexTranscriptFromPathArgs): CodexIngestionOutcome;

package/dist/ingestion/ingestion.js

@@ -3,6 +3,8 @@ import { resolveCodexHome } from './codex-home.js';
 import { validateCodexTranscriptPath } from './transcript-path.js';
 import { classifyCodexVersion, CODEX_VERSION_NEXT_ACTION } from './codex-version.js';
 import { decodeTranscriptWindow, createNodeTranscriptPort, CODEX_INGESTION_MAX_BATCH_BYTES, TranscriptReplacedError } from './transcript-decoder.js';
+import { extractFields } from './ingestion-fields.js';
+import { buildLiveCorrectionCandidate, buildLiveToolCandidate, buildTranscriptCandidates } from './admission.js';
 let activePort = null;
 /** Test seam: inject/inspect the transcript filesystem boundary (zero-read proofs). */
 export function setCodexTranscriptPortForTest(port) {
@@ -11,34 +13,6 @@ export function setCodexTranscriptPortForTest(port) {
 function activeTranscriptPort(options) {
     return options.port ?? activePort ?? createNodeTranscriptPort();
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function own(value, key) {
-    return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
-}
-function extractFields(raw) {
-    if (!isRecord(raw))
-        return null;
-    const transcriptPath = own(raw, 'transcript_path');
-    if (transcriptPath !== null && typeof transcriptPath !== 'string')
-        return null;
-    const sessionId = own(raw, 'session_id');
-    const turnId = own(raw, 'turn_id');
-    const prompt = own(raw, 'prompt');
-    const toolUseId = own(raw, 'tool_use_id');
-    const toolName = own(raw, 'tool_name');
-    return {
-        transcriptPath: transcriptPath ?? null,
-        sessionId: typeof sessionId === 'string' ? sessionId : '',
-        turnId: typeof turnId === 'string' ? turnId : null,
-        prompt: typeof prompt === 'string' ? prompt : null,
-        toolUseId: typeof toolUseId === 'string' ? toolUseId : null,
-        toolName: typeof toolName === 'string' ? toolName : null,
-        toolInput: own(raw, 'tool_input'),
-        toolResponse: own(raw, 'tool_response'),
-    };
-}
 function ingestLiveObservation({ fields, rolloutIdentity, workspaceDir, now }) {
     const nowIso = now.toISOString();
     let observation = null;
@@ -85,9 +59,18 @@ function ingestLiveObservation({ fields, rolloutIdentity, workspaceDir, now }) {
     });
     if (!result.ok)
         return { status: 'degraded', reason: result.reason ?? 'governance_write_failed', nextAction: result.nextAction ?? 'inspect the workspace trajectory database.', warnings: result.warnings };
-    return { status: 'ok', inserted: result.inserted, enriched: result.enriched, duplicates: result.duplicates, warnings: result.warnings, lagBytes: 0 };
+    // Slice B: hand the live observation to the admission pass as a normalized
+    // candidate (SPEC §12) — the caller (pd-hook) runs detection/admission.
+    const candidate = observation.kind === 'user_turn'
+        ? buildLiveCorrectionCandidate({ fields, rolloutIdentity })
+        : buildLiveToolCandidate({ fields, rolloutIdentity });
+    return {
+        status: 'ok', inserted: result.inserted, enriched: result.enriched, duplicates: result.duplicates, warnings: result.warnings, lagBytes: 0,
+        admissionCandidates: candidate !== null ? [candidate] : [],
+        rolloutIdentity,
+    };
 }
-function ingestTranscriptDelta({ fields, canonicalPath, identity, rolloutIdentity, workspaceDir, now, port }) {
+function ingestTranscriptDelta({ fallbackRootSessionId, canonicalPath, identity, rolloutIdentity, workspaceDir, now, port }) {
     const checkpoint = readGovernanceCheckpoint({ workspaceDir, hostKind: 'codex', rolloutIdentity });
     if (checkpoint !== null && !('byteOffset' in checkpoint) && 'ok' in checkpoint && checkpoint.ok === false) {
         return { status: 'degraded', reason: checkpoint.reason, nextAction: checkpoint.nextAction, warnings: [] };
@@ -118,7 +101,7 @@ function ingestTranscriptDelta({ fields, canonicalPath, identity, rolloutIdentit
         fileOffset: offset,
         byteBoundReached,
         rolloutIdentity,
-        fallbackRootSessionId: existing !== null ? existing.rootSessionId : fields.sessionId,
+        fallbackRootSessionId: existing !== null ? existing.rootSessionId : fallbackRootSessionId,
         nowIso: now.toISOString(),
     });
     // Supported-version guard (SPEC §9): the version signal lives in the
@@ -142,7 +125,7 @@ function ingestTranscriptDelta({ fields, canonicalPath, identity, rolloutIdentit
     else if (decoded.stop.kind === 'oversized_record') {
         degradations.push({ reason: 'transcript_record_too_large', nextAction: 'a single transcript record exceeds the bounded-read window; inspect the rollout file.' });
     }
-    const rootSessionId = decoded.rolloutMeta.rootSessionId ?? existing?.rootSessionId ?? fields.sessionId;
+    const rootSessionId = decoded.rolloutMeta.rootSessionId ?? existing?.rootSessionId ?? fallbackRootSessionId;
     const result = ingestGovernanceObservations({
         workspaceDir,
         rollout: {
@@ -200,6 +183,11 @@ function ingestTranscriptDelta({ fields, canonicalPath, identity, rolloutIdentit
         duplicates: result.duplicates,
         warnings,
         lagBytes: Math.max(0, window.fileSize - decoded.nextByteOffset),
+        // Slice B: transcript-only user turns / tool calls that were never seen
+        // live get their admission evaluation here (SPEC §10/§12) — already
+        // admitted logical keys no-op on the marker.
+        admissionCandidates: buildTranscriptCandidates(decoded.observations),
+        rolloutIdentity,
     };
 }
 export function ingestCodexConversation(rawPayload, kind, options) {
@@ -222,7 +210,7 @@ export function ingestCodexConversation(rawPayload, kind, options) {
         return ingestLiveObservation({ fields, rolloutIdentity: validated.rolloutIdentity, workspaceDir: options.workspaceDir, now });
     }
     return ingestTranscriptDelta({
-        fields,
+        fallbackRootSessionId: fields.sessionId,
         canonicalPath: validated.canonicalPath,
         identity: validated.identity,
         rolloutIdentity: validated.rolloutIdentity,
@@ -232,3 +220,29 @@ export function ingestCodexConversation(rawPayload, kind, options) {
         port: activeTranscriptPort(options),
     });
 }
+/**
+ * PRI-624 (Slice C): bounded incremental ingest of one known rollout from its
+ * durable checkpoint, driven by an explicit transcript path instead of a live
+ * hook payload. The path is re-authorized through the same
+ * `validateCodexTranscriptPath` containment + post-open identity contract the
+ * hook path uses (SPEC §9) — callers MUST only pass paths resolved from
+ * previously-authenticated rollouts (checkpoints), never discovered sessions.
+ */
+export function ingestCodexTranscriptFromPath(args) {
+    const home = resolveCodexHome(args.env);
+    if (!home.ok)
+        return { status: 'degraded', reason: home.reason, nextAction: home.nextAction, warnings: [] };
+    const validated = validateCodexTranscriptPath(args.transcriptPath, home.home);
+    if (!validated.ok)
+        return { status: 'degraded', reason: validated.reason, nextAction: validated.nextAction, warnings: [] };
+    return ingestTranscriptDelta({
+        fallbackRootSessionId: args.fallbackRootSessionId,
+        canonicalPath: validated.canonicalPath,
+        identity: validated.identity,
+        rolloutIdentity: validated.rolloutIdentity,
+        workspaceDir: args.workspaceDir,
+        env: args.env ?? {},
+        now: args.now ?? new Date(),
+        port: args.port ?? activeTranscriptPort({ workspaceDir: args.workspaceDir }),
+    });
+}

package/dist/ingestion/transcript-locate.d.ts

@@ -0,0 +1,13 @@
+export type CodexTranscriptLookup = {
+    ok: true;
+    transcriptPath: string;
+} | {
+    ok: false;
+    reason: 'catch_up_rollout_identity_invalid' | 'catch_up_sessions_root_missing' | 'catch_up_transcript_missing' | 'catch_up_transcript_ambiguous' | 'catch_up_lookup_exhausted';
+    nextAction: string;
+};
+/**
+ * Resolve one previously-authenticated rollout identity to its transcript
+ * path by exact-uuid filename match under `<codexHome>/sessions`.
+ */
+export declare function locateCodexTranscriptByRolloutIdentity(codexHome: string, rolloutIdentity: string): CodexTranscriptLookup;

package/dist/ingestion/transcript-locate.js

@@ -0,0 +1,75 @@
+/**
+ * Codex transcript locator for catch-up (PRI-624 Slice C).
+ *
+ * The durable checkpoint stores only the rollout uuid (SPEC §18 scenario 9
+ * forbids raw paths in the DB), so catch-up must resolve a checkpointed
+ * rollout back to its transcript file. This is NOT session discovery: the
+ * lookup searches for the EXACT rollout uuid of a rollout the authenticated
+ * Workspace hook previously delivered (only hooks write checkpoints). It
+ * never guesses a "latest session", never returns a partial match, and
+ * refuses ambiguities (ADR-0020 §11.2 / SPEC §9).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseRolloutFileName } from './transcript-path.js';
+/** Bounded walk: hard cap on visited directory entries so a pathological sessions tree cannot stall the worker. */
+const MAX_LOOKUP_ENTRIES = 5000;
+const ROLLOUT_IDENTITY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Resolve one previously-authenticated rollout identity to its transcript
+ * path by exact-uuid filename match under `<codexHome>/sessions`.
+ */
+export function locateCodexTranscriptByRolloutIdentity(codexHome, rolloutIdentity) {
+    if (!ROLLOUT_IDENTITY_PATTERN.test(rolloutIdentity)) {
+        return { ok: false, reason: 'catch_up_rollout_identity_invalid', nextAction: 'the checkpointed rollout identity is not a rollout uuid; inspect the workspace trajectory database.' };
+    }
+    const sessionsRoot = path.join(codexHome, 'sessions');
+    let rootStats;
+    try {
+        rootStats = fs.statSync(sessionsRoot);
+    }
+    catch {
+        return { ok: false, reason: 'catch_up_sessions_root_missing', nextAction: 'the configured CODEX_HOME has no sessions root; verify the Codex home used by the hook and by catch-up matches.' };
+    }
+    if (!rootStats.isDirectory()) {
+        return { ok: false, reason: 'catch_up_sessions_root_missing', nextAction: 'the configured CODEX_HOME sessions path is not a directory; verify the Codex home configuration.' };
+    }
+    const matches = [];
+    let visited = 0;
+    const stack = [sessionsRoot];
+    while (stack.length > 0 && matches.length < 2) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable subtree — other subtrees may still hold the rollout
+        }
+        for (const entry of entries) {
+            visited += 1;
+            if (visited > MAX_LOOKUP_ENTRIES) {
+                return { ok: false, reason: 'catch_up_lookup_exhausted', nextAction: 'the sessions tree exceeded the bounded catch-up lookup; keep CODEX_HOME/sessions pruned or catch up rollouts manually.' };
+            }
+            if (entry.isDirectory()) {
+                stack.push(path.join(dir, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith('.jsonl')) {
+                if (parseRolloutFileName(entry.name) === rolloutIdentity) {
+                    matches.push(path.join(dir, entry.name));
+                    if (matches.length >= 2)
+                        break;
+                }
+            }
+        }
+    }
+    if (matches.length === 0) {
+        return { ok: false, reason: 'catch_up_transcript_missing', nextAction: 'the checkpointed rollout has no transcript under the Codex sessions root (rotated or cleaned by Codex); its committed observations remain, the pending lag cannot be recovered.' };
+    }
+    if (matches.length > 1) {
+        return { ok: false, reason: 'catch_up_transcript_ambiguous', nextAction: 'multiple transcripts match the rollout identity; refuse to guess — inspect the Codex sessions tree.' };
+    }
+    return { ok: true, transcriptPath: matches[0] };
+}

package/dist/ingestion/transcript-path.d.ts

@@ -20,4 +20,6 @@ export type TranscriptPathValidation = {
     reason: 'transcript_path_invalid' | 'transcript_path_outside_codex_home';
     nextAction: string;
 };
+/** rollout-<timestamp>-<uuid>.jsonl — returns the rollout uuid, or null when the name is off-contract. */
+export declare function parseRolloutFileName(fileName: string): string | null;
 export declare function validateCodexTranscriptPath(transcriptPath: string, codexHome: string): TranscriptPathValidation;

package/dist/ingestion/transcript-path.js

@@ -21,7 +21,7 @@ function isHex(value) {
     return UUID_HEX.test(value);
 }
 /** rollout-<timestamp>-<uuid>.jsonl — returns the rollout uuid, or null when the name is off-contract. */
-function parseRolloutFileName(fileName) {
+export function parseRolloutFileName(fileName) {
     if (!fileName.startsWith('rollout-') || !fileName.endsWith('.jsonl'))
         return null;
     const stem = fileName.slice('rollout-'.length, -'.jsonl'.length);

package/dist/pd-hook.js

@@ -7,6 +7,7 @@ import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
 import { CodexHooksHostAdapter } from './host-adapter.js';
 import { CodexDecoderError, CodexEncoderError } from './codec/index.js';
 import { ingestCodexConversation } from './ingestion/ingestion.js';
+import { runGovernanceAdmission } from './ingestion/admission.js';
 const MAX_DIAGNOSTIC = 500;
 function diagnostic(reason, nextAction) {
     const boundedReason = reason.replace(/\s+/g, ' ').trim().slice(0, MAX_DIAGNOSTIC);
@@ -17,11 +18,16 @@ function errorMessage(error) {
     return error instanceof Error ? error.message.slice(0, MAX_DIAGNOSTIC) : 'unknown_error';
 }
 // Bounded governance-observation ingestion (Codex Governance Closure Slice
-// A). Runs only when BOTH host.codex and codex_conversation_ingestion are
+// A) followed by the Slice B signal-admission pass (SPEC §12/§13): detection
+// → canonical pain → evidence promotion → one pending Diagnostician task.
+// Runs only when BOTH host.codex and codex_conversation_ingestion are
 // enabled — the flag gate below happens BEFORE any transcript path
 // validation or filesystem I/O, so flag-off means the transcript boundary
-// receives zero calls (SPEC §10 hard privacy invariant).
-function runConversationIngestion(args) {
+// receives zero calls (SPEC §10 hard privacy invariant). Admission runs
+// BEFORE dispatch so a live tool failure is admitted through the same
+// canonical derivation first and the production handler's duplicate probe
+// then converges to a no-op (exactly one pain per real tool call).
+async function runConversationIngestion(args) {
     const { rawPayload, kind, workspaceDir, env } = args;
     if (kind !== 'turn_complete' && kind !== 'before_prompt_build' && kind !== 'after_tool_call')
         return [];
@@ -35,6 +41,16 @@ function runConversationIngestion(args) {
             for (const warning of outcome.warnings.slice(0, 2)) {
                 diagnostics.push(diagnostic(warning, 'Inspect PD Workspace governance-observation state; ingestion continued.'));
             }
+            // Slice B admission: hook awaits only admission + durable enqueue —
+            // never an LLM (SPEC §12/§13). Ordinary conversation returns no
+            // candidates/no admissions and stays completely silent.
+            const admission = await runGovernanceAdmission({
+                workspaceDir,
+                candidates: outcome.admissionCandidates,
+            });
+            for (const degradation of admission.degradations.slice(0, 2)) {
+                diagnostics.push(diagnostic(degradation.reason, degradation.nextAction));
+            }
         }
     }
     catch (error) {
@@ -87,7 +103,7 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
         // turn on stderr — never stdout, and never on the per-tool events (that
         // would be per-event noise).
         const stderr = ingestionEnabled
-            ? runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
+            ? await runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
             : [diagnostic('feature_disabled', 'Set features.codex_conversation_ingestion.enabled=true in the selected Workspace .pd/config.yaml to enable bounded conversation ingestion.')];
         return { stdout: {}, exitCode: 0, stderr };
     }
@@ -99,7 +115,7 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
             return { stdout: adapter.encodeOutput({ decision: 'allow', source: event.source }, 'session_start'), exitCode: 0, stderr: [] };
         }
         const ingestionDiagnostics = ingestionEnabled
-            ? runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
+            ? await runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
             : [];
         const result = await createProductionHostRuntime().dispatch(event);
         const stderr = [...(result.warnings ?? []).slice(0, 16).map((warning) => diagnostic(warning, 'Inspect PD Workspace state and retry; the hook failed open.')), ...ingestionDiagnostics];

package/dist/worker/workspace-worker.d.ts

@@ -0,0 +1,57 @@
+import { type InternalizationConsumerCycleOutcome, type ConsumerCycleLogger, type ReconcileGovernanceContinuationResult } from '@principles/host-runtime';
+import { type CodexCatchUpResult } from '../ingestion/catch-up.js';
+import type { TranscriptPort } from '../ingestion/transcript-decoder.js';
+export type CodexWorkerMode = 'ready' | 'manual_action_required' | 'paused' | 'degraded';
+export interface CodexWorkerCycleStepReport {
+    readonly catchUp: CodexCatchUpResult;
+    readonly reconcile: ReconcileGovernanceContinuationResult;
+    /** At most ONE diagnostician execution per cycle (bounded work). */
+    readonly diagnostician: {
+        readonly taskId: string;
+        readonly status: 'succeeded' | 'failed' | 'retried' | 'skipped' | 'degraded';
+        readonly message?: string;
+        readonly errorCategory?: string;
+    } | null;
+    readonly downstream: InternalizationConsumerCycleOutcome | null;
+}
+export interface CodexWorkerCycleResult {
+    readonly workspaceDir: string;
+    readonly mode: CodexWorkerMode;
+    readonly reason?: string;
+    readonly nextAction?: string;
+    readonly report?: CodexWorkerCycleStepReport;
+}
+export interface CodexWorkerCycleOptions {
+    readonly workspaceDir: string;
+    readonly env?: {
+        CODEX_HOME?: string | undefined;
+    };
+    readonly now?: Date;
+    readonly logger?: ConsumerCycleLogger;
+    readonly emitEvent?: (event: string, payloadJson: string) => void;
+    readonly port?: TranscriptPort;
+    /** Cap on diagnostician candidates inspected per cycle (default 5). */
+    readonly diagnosticianCandidateLimit?: number;
+}
+/**
+ * Run ONE bounded worker cycle for a canonical workspace. Never throws:
+ * every failure becomes a structured degraded result with a nextAction.
+ */
+export declare function runCodexWorkspaceWorkerCycle(options: CodexWorkerCycleOptions): Promise<CodexWorkerCycleResult>;
+export interface CodexWorkerStatusEvaluation {
+    readonly mode: CodexWorkerMode;
+    readonly reason?: string;
+    readonly nextAction?: string;
+}
+/**
+ * SPEC §15 worker mode, evaluated WITHOUT executing anything (no lease, no
+ * LLM, no transcript I/O). `manual_action_required` means no
+ * Companion-registered worker serves this workspace — the manual CLI path
+ * (catch-up / diagnose / run-once) is the recovery route. 'ready' here means
+ * "an automatic worker would run and hold the workspace task leases";
+ * live-worker liveness surfacing belongs to the Slice D health surface.
+ */
+export declare function computeCodexWorkerStatusMode(input: {
+    workspaceDir: string;
+    registeredInInstallManifest: boolean;
+}): CodexWorkerStatusEvaluation;

package/dist/worker/workspace-worker.js

@@ -0,0 +1,231 @@
+/**
+ * Codex Workspace worker cycle (PRI-624 Slice C; SPEC §13/§15; ADR-0020 §11.1).
+ *
+ * ONE Workspace-scoped worker cycle with exactly three background
+ * responsibilities (the Owner-approved MVP exception — NOT a general daemon):
+ *
+ *   1. catch up transcript lag   (gated by codex_conversation_ingestion)
+ *   2. run the Slice B idempotent reconciliation pass
+ *   3. lease + run one Diagnostician task, then ONE bounded downstream
+ *      consumer cycle through the SHARED host-neutral executor
+ *      (internalization_auto_consumer = workspace execution authority)
+ *
+ * Every step reuses existing authority: catch-up reuses the Slice A/B
+ * ingestion + admission seams, reconciliation reuses
+ * `reconcileGovernanceContinuation`, the diagnostician reuses the
+ * PainSignalBridge lease/runner contract, downstream reuses the same
+ * `runInternalizationConsumerCycle` the OpenClaw auto-consumer runs. No new
+ * task store, no private retry queue, no second scheduler state.
+ *
+ * Correctness under concurrent consumers (OpenClaw auto-consumer + this
+ * worker on one workspace) is owned by the durable Runtime V2 task lease —
+ * never by process-local state.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { computeFeatureFlagsFromConfig, createRuntimeStateHandle, createPainSignalBridge, isRetryWaitBackoffElapsed, PrincipleTreeLedgerAdapter, } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin, loadFeatureFlagFromConfig, reconcileGovernanceContinuation, runInternalizationConsumerCycle, } from '@principles/host-runtime';
+import { catchUpCodexIngestion } from '../ingestion/catch-up.js';
+const WORKER_OWNER = 'companion-worker';
+const DEFAULT_DIAG_CANDIDATE_LIMIT = 5;
+function workerLogger(logger) {
+    return logger ?? {
+        info: () => undefined,
+        warn: () => undefined,
+        error: () => undefined,
+    };
+}
+function directoryExists(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Oldest pending diagnostician first; retry_wait candidates are filtered to
+ * those whose backoff window has ELAPSED, so an old-but-still-waiting task
+ * cannot starve a younger eligible one (review P1). The candidate set stays
+ * bounded (`limit`), and executePendingDiagnosis re-enforces the backoff
+ * window on the chosen task — no double bookkeeping.
+ */
+async function pickDiagnosticianCandidate(stateManager, limit) {
+    const pending = await stateManager.listTasks({ taskKind: 'diagnostician', status: 'pending', orderBy: 'updated_at_asc', limit });
+    const [first] = pending;
+    if (first !== undefined)
+        return first;
+    const retrying = await stateManager.listTasks({ taskKind: 'diagnostician', status: 'retry_wait', orderBy: 'updated_at_asc', limit });
+    for (const candidate of retrying) {
+        if (isRetryWaitBackoffElapsed(candidate.status, candidate.leaseExpiresAt)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Run ONE bounded worker cycle for a canonical workspace. Never throws:
+ * every failure becomes a structured degraded result with a nextAction.
+ */
+export async function runCodexWorkspaceWorkerCycle(options) {
+    const workspaceDir = path.resolve(options.workspaceDir);
+    const logger = workerLogger(options.logger);
+    const emitEvent = options.emitEvent ?? ((_event, _payload) => undefined);
+    const base = { workspaceDir };
+    // Step 1 — Workspace eligibility.
+    if (!directoryExists(workspaceDir)) {
+        return { ...base, mode: 'degraded', reason: 'workspace_missing', nextAction: 'The workspace directory no longer exists; remove it from the install manifest or restore it. No PD state was mutated.' };
+    }
+    const config = loadPdConfigForPlugin(workspaceDir);
+    if (!config.ok) {
+        const [first] = config.errors;
+        return { ...base, mode: 'degraded', reason: `pd_config_invalid:${first?.reason ?? 'unknown'}`, nextAction: first?.nextAction ?? 'Repair .pd/config.yaml.' };
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    if (flags['host.codex']?.enabled !== true) {
+        return { ...base, mode: 'paused', reason: 'host.codex_disabled', nextAction: 'Set features.host.codex.enabled=true in the Workspace .pd/config.yaml to enable Codex PD behavior.' };
+    }
+    const consumerFlag = loadFeatureFlagFromConfig(workspaceDir, 'internalization_auto_consumer', { info: (m) => logger.info(m), warn: (m) => logger.warn(m) });
+    // Step 2 — Catch-up transcript lag (SPEC §13: gated by the ingestion flag,
+    // NOT by the consumer flag; catchUpCodexIngestion re-checks and returns a
+    // zero-I/O skip when ingestion is off).
+    const catchUp = await catchUpCodexIngestion({
+        workspaceDir,
+        env: options.env,
+        now: options.now,
+        port: options.port,
+    });
+    // Step 3 — Slice B idempotent reconciliation (always runs; creates no LLM work).
+    const reconcile = await reconcileGovernanceContinuation({ workspaceDir });
+    // Steps 4–6 — execution authority: internalization_auto_consumer.
+    let diagnostician = null;
+    if (!consumerFlag.enabled) {
+        // paused: execution pause, NOT evidence freeze. Catch-up + reconcile
+        // already ran above; manual CLI remains allowed (SPEC §13).
+        return {
+            ...base,
+            mode: 'paused',
+            reason: 'internalization_auto_consumer_disabled',
+            nextAction: 'Automatic internalization execution is paused for this Workspace; manual commands remain available: pd diagnose, pd runtime internalization run-once.',
+            report: { catchUp, reconcile, diagnostician: null, downstream: null },
+        };
+    }
+    // Step 4 — expired-lease recovery sweep, then Step 5/6: at most one
+    // Diagnostician task via the existing bridge lease/runner contract.
+    try {
+        const handle = await createRuntimeStateHandle({ workspaceDir, readonly: false });
+        try {
+            const sweep = await handle.stateManager.runRecoverySweep();
+            if (sweep.recovered > 0 || sweep.errors.length > 0) {
+                emitEvent('CODEX_WORKER_RECOVERY_SWEEP', JSON.stringify({ recovered: sweep.recovered, failed: sweep.errors.length }));
+            }
+            const candidate = await pickDiagnosticianCandidate(handle.stateManager, options.diagnosticianCandidateLimit ?? DEFAULT_DIAG_CANDIDATE_LIMIT);
+            if (candidate !== null) {
+                const stateDir = path.join(workspaceDir, '.state');
+                const bridge = await createPainSignalBridge({
+                    workspaceDir,
+                    stateDir,
+                    ledgerAdapter: new PrincipleTreeLedgerAdapter({ stateDir }),
+                    owner: WORKER_OWNER,
+                    effectiveConfig: config.effective,
+                    getEnvVar: (name) => process.env[name],
+                });
+                const executed = await bridge.executePendingDiagnosis({ taskId: candidate.taskId });
+                diagnostician = {
+                    taskId: candidate.taskId,
+                    status: executed.status,
+                    ...(executed.message !== undefined ? { message: executed.message.slice(0, 200) } : {}),
+                    ...(executed.errorCategory !== undefined ? { errorCategory: executed.errorCategory } : {}),
+                };
+                // The bridge stays cached per workspace (bounded: one per workspace
+                // per worker process, exactly like the OpenClaw plugin host) — no
+                // per-cycle dispose, so a concurrent cycle can never hit a disposed
+                // bridge. The factory self-disposes losing concurrent constructions.
+            }
+            else {
+                // No eligible candidate, but a retry_wait task may still be inside
+                // its backoff window — report it so the cycle is observable instead
+                // of looking like "nothing pending" (review P1: head-of-line).
+                const waiting = await handle.stateManager.listTasks({ taskKind: 'diagnostician', status: 'retry_wait', orderBy: 'updated_at_asc', limit: 1 });
+                const [oldestWaiting] = waiting;
+                if (oldestWaiting !== undefined && !isRetryWaitBackoffElapsed(oldestWaiting.status, oldestWaiting.leaseExpiresAt)) {
+                    diagnostician = { taskId: oldestWaiting.taskId, status: 'skipped', message: 'retry_wait_pending' };
+                }
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200);
+        return {
+            ...base,
+            mode: 'degraded',
+            reason: `diagnostician_execution_failed:${detail}`,
+            nextAction: 'Inspect the Workspace runtime profile and provider configuration; the task keeps its pending/retry state and no evidence was mutated.',
+            report: { catchUp, reconcile, diagnostician: null, downstream: null },
+        };
+    }
+    // Step 7 — ONE bounded downstream consumer cycle via the shared executor
+    // (same implementation the OpenClaw auto-consumer runs).
+    const downstream = await runInternalizationConsumerCycle(workspaceDir, {
+        owner: WORKER_OWNER,
+        logLabel: 'CodexWorker',
+        logger,
+        emitEvent,
+        // No hostToolCatalog: PD has not declared a Codex tool catalog; a wrong
+        // (OpenClaw) catalog would be worse than none (PRI-630 follow-up).
+    });
+    // Aggregated mode: degraded overrides all (review P1).  Any component
+    // degrading — catch-up, reconciliation, diagnostician or downstream —
+    // surfaces the workspace as degraded, with the highest-priority reason.
+    // A lease_conflict diagnostician failure is contention, not degradation:
+    // another consumer owns the task, which is normal operation.
+    const degradedReason = catchUp.status === 'degraded' ? `catch_up:${catchUp.remainingLagRollouts[0] ?? 'unknown'}`
+        : !reconcile.ok ? `reconcile:${reconcile.reason ?? 'failed'}`
+            : diagnostician?.status === 'failed' && diagnostician.errorCategory !== 'lease_conflict' ? `diagnostician_failed:${diagnostician.message ?? 'max_attempts_exceeded'}`
+                : diagnostician?.status === 'degraded' ? `diagnostician_degraded:${diagnostician.message ?? 'unknown'}`
+                    : downstream.skipReason === 'runtime_config_error' || downstream.skipReason === 'cycle_error' || downstream.skipReason === 'config_malformed' ? `downstream:${downstream.skipReason}`
+                        : undefined;
+    return {
+        ...base,
+        mode: degradedReason !== undefined ? 'degraded' : 'ready',
+        ...(degradedReason !== undefined ? { reason: degradedReason, nextAction: 'Inspect the Workspace .pd/config.yaml runtime profile and the per-step report above; the worker retries automatically on the next cycle.' } : {}),
+        report: { catchUp, reconcile, diagnostician, downstream },
+    };
+}
+/**
+ * SPEC §15 worker mode, evaluated WITHOUT executing anything (no lease, no
+ * LLM, no transcript I/O). `manual_action_required` means no
+ * Companion-registered worker serves this workspace — the manual CLI path
+ * (catch-up / diagnose / run-once) is the recovery route. 'ready' here means
+ * "an automatic worker would run and hold the workspace task leases";
+ * live-worker liveness surfacing belongs to the Slice D health surface.
+ */
+export function computeCodexWorkerStatusMode(input) {
+    const workspaceDir = path.resolve(input.workspaceDir);
+    if (!directoryExists(workspaceDir)) {
+        return { mode: 'degraded', reason: 'workspace_missing', nextAction: 'The workspace directory does not exist; restore it or remove it from the install manifest.' };
+    }
+    const config = loadPdConfigForPlugin(workspaceDir);
+    if (!config.ok) {
+        const [first] = config.errors;
+        return { mode: 'degraded', reason: `pd_config_invalid:${first?.reason ?? 'unknown'}`, nextAction: first?.nextAction ?? 'Repair .pd/config.yaml.' };
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    if (flags['host.codex']?.enabled !== true) {
+        return { mode: 'paused', reason: 'host.codex_disabled', nextAction: 'Set features.host.codex.enabled=true in the Workspace .pd/config.yaml to enable Codex PD behavior.' };
+    }
+    if (flags.internalization_auto_consumer?.enabled !== true) {
+        return { mode: 'paused', reason: 'internalization_auto_consumer_disabled', nextAction: 'Automatic execution is paused; manual commands remain available: pd diagnose, pd runtime internalization run-once.' };
+    }
+    if (!input.registeredInInstallManifest) {
+        return {
+            mode: 'manual_action_required',
+            reason: 'workspace_not_in_install_manifest',
+            nextAction: `No Companion worker is registered for this workspace. Manual path: pd codex ingest catch-up --workspace "${workspaceDir}", then pd diagnose / pd runtime internalization run-once.`,
+        };
+    }
+    return { mode: 'ready' };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Codex CLI host adapter for Principles Disciple — implements HostAdapter interface for OpenAI Codex CLI's stdin/stdout JSON hook model (ADR-0020).",
   "type": "module",
   "main": "./dist/index.js",