create-principles-disciple 1.132.3 → 1.132.5

package/codex-adapter/dist/codec/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Codec barrel — input decoder + output encoder for Codex CLI.
+ */
+export { decodeCodexInput, CodexDecoderError, CODEX_EVENT_PRE_TOOL_USE, CODEX_EVENT_POST_TOOL_USE, CODEX_EVENT_USER_PROMPT_SUBMIT, CODEX_EVENT_SESSION_START, CODEX_EVENT_SESSION_END, } from './input-decoder.js';
+export { encodeCodexOutput, codexOutputFieldsAreWhitelisted, CodexEncoderError, } from './output-encoder.js';
+export type { CodexPreToolUseOutput, CodexPostToolUseOutput, CodexUserPromptSubmitOutput, CodexSessionStartOutput, CodexHookOutput, } from './output-encoder.js';

package/codex-adapter/dist/codec/index.js

@@ -0,0 +1,5 @@
+/**
+ * Codec barrel — input decoder + output encoder for Codex CLI.
+ */
+export { decodeCodexInput, CodexDecoderError, CODEX_EVENT_PRE_TOOL_USE, CODEX_EVENT_POST_TOOL_USE, CODEX_EVENT_USER_PROMPT_SUBMIT, CODEX_EVENT_SESSION_START, CODEX_EVENT_SESSION_END, } from './input-decoder.js';
+export { encodeCodexOutput, codexOutputFieldsAreWhitelisted, CodexEncoderError, } from './output-encoder.js';

package/codex-adapter/dist/codec/input-decoder.d.ts

@@ -0,0 +1,13 @@
+import type { HostEvent } from '@principles/core/host';
+export declare const CODEX_EVENT_PRE_TOOL_USE = "PreToolUse";
+export declare const CODEX_EVENT_POST_TOOL_USE = "PostToolUse";
+export declare const CODEX_EVENT_USER_PROMPT_SUBMIT = "UserPromptSubmit";
+export declare const CODEX_EVENT_SESSION_START = "SessionStart";
+export declare const CODEX_EVENT_STOP = "Stop";
+export declare const CODEX_EVENT_SESSION_END = "SessionEnd";
+export declare class CodexDecoderError extends Error {
+    readonly reason: string;
+    readonly nextAction: string;
+    constructor(reason: string, nextAction: string);
+}
+export declare function decodeCodexInput(raw: unknown): HostEvent;

package/codex-adapter/dist/codec/input-decoder.js

@@ -0,0 +1,103 @@
+import { CODEX_INGESTION_MIN_VERSION } from '../ingestion/codex-version.js';
+// Two contract baselines coexist deliberately (G1 probe report §9): the
+// four pre-ingestion events pin their payload contract to codex-cli 0.147.0,
+// while the Stop / ingestion-side fields follow the ingestion baseline
+// (CODEX_INGESTION_MIN_VERSION = 0.148.0). Each message names the baseline
+// that defines it — never mix them.
+const FOUR_EVENT_CONTRACT_VERSION = '0.147.0';
+export const CODEX_EVENT_PRE_TOOL_USE = 'PreToolUse';
+export const CODEX_EVENT_POST_TOOL_USE = 'PostToolUse';
+export const CODEX_EVENT_USER_PROMPT_SUBMIT = 'UserPromptSubmit';
+export const CODEX_EVENT_SESSION_START = 'SessionStart';
+export const CODEX_EVENT_STOP = 'Stop';
+export const CODEX_EVENT_SESSION_END = 'SessionEnd';
+const EVENT_KINDS = new Map([
+    [CODEX_EVENT_PRE_TOOL_USE, 'before_tool_call'],
+    [CODEX_EVENT_POST_TOOL_USE, 'after_tool_call'],
+    [CODEX_EVENT_USER_PROMPT_SUBMIT, 'before_prompt_build'],
+    [CODEX_EVENT_SESSION_START, 'session_start'],
+    [CODEX_EVENT_STOP, 'turn_complete'],
+]);
+export class CodexDecoderError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, nextAction) {
+        super(`Codex input decode failed: ${reason}`);
+        this.reason = reason;
+        this.nextAction = nextAction;
+        this.name = 'CodexDecoderError';
+    }
+}
+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 requiredString(value, key) {
+    const candidate = own(value, key);
+    if (typeof candidate !== 'string' || candidate.trim().length === 0) {
+        throw new CodexDecoderError(`missing or malformed required field "${key}"`, `Use the exact codex-cli ${FOUR_EVENT_CONTRACT_VERSION} ${key} field.`);
+    }
+    return candidate;
+}
+function requiredNullableString(value, key) {
+    if (!Object.hasOwn(value, key))
+        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli ${FOUR_EVENT_CONTRACT_VERSION} ${key} field.`);
+    const candidate = own(value, key);
+    if (candidate !== null && typeof candidate !== 'string') {
+        throw new CodexDecoderError(`malformed required field "${key}"`, `${key} must be a string or null.`);
+    }
+    return candidate;
+}
+function requiredUnknown(value, key) {
+    if (!Object.hasOwn(value, key))
+        throw new CodexDecoderError(`missing required field "${key}"`, `Use the exact codex-cli ${FOUR_EVENT_CONTRACT_VERSION} ${key} field.`);
+    return own(value, key);
+}
+function validateCommon(raw, needsTurn) {
+    const sessionId = requiredString(raw, 'session_id');
+    requiredNullableString(raw, 'transcript_path');
+    const workspaceDir = requiredString(raw, 'cwd');
+    requiredString(raw, 'model');
+    requiredString(raw, 'permission_mode');
+    const turnId = needsTurn ? requiredString(raw, 'turn_id') : undefined;
+    return { workspaceDir, sessionId, ...(turnId ? { turnId } : {}) };
+}
+export function decodeCodexInput(raw) {
+    if (!isRecord(raw))
+        throw new CodexDecoderError('stdin payload is not a JSON object', 'Run this executable only as a Codex command hook.');
+    const eventName = requiredString(raw, 'hook_event_name');
+    const kind = EVENT_KINDS.get(eventName);
+    if (!kind)
+        throw new CodexDecoderError(`unknown hook_event_name "${eventName}"`, 'Configure only PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, or Stop.');
+    const common = validateCommon(raw, kind !== 'session_start');
+    let context;
+    let rawPayload = raw;
+    if (kind === 'before_tool_call' || kind === 'after_tool_call') {
+        const toolName = requiredString(raw, 'tool_name');
+        const toolInput = requiredUnknown(raw, 'tool_input');
+        requiredString(raw, 'tool_use_id');
+        const toolOutput = kind === 'after_tool_call' ? requiredUnknown(raw, 'tool_response') : undefined;
+        context = { ...common, toolName, toolInput, ...(kind === 'after_tool_call' ? { toolOutput } : {}) };
+        rawPayload = { toolInput: { toolName, params: toolInput } };
+    }
+    else if (kind === 'before_prompt_build') {
+        context = { ...common, promptContent: requiredString(raw, 'prompt') };
+    }
+    else if (kind === 'turn_complete') {
+        // Stop is the G1-verified turn-complete event (probe report §2). Its
+        // payload carries stop_hook_active (required boolean); PD consumes the
+        // already-flushed transcript, never last_assistant_message directly.
+        const stopHookActive = own(raw, 'stop_hook_active');
+        if (typeof stopHookActive !== 'boolean') {
+            throw new CodexDecoderError('missing or malformed required field "stop_hook_active"', `Use the exact codex-cli ${CODEX_INGESTION_MIN_VERSION} stop_hook_active field.`);
+        }
+        context = { ...common };
+    }
+    else {
+        context = { ...common, source: requiredString(raw, 'source') };
+    }
+    const source = `codex:${eventName.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}`;
+    return { kind, context, rawPayload, source };
+}

package/codex-adapter/dist/codec/output-encoder.d.ts

@@ -0,0 +1,32 @@
+import type { HostEventResult } from '@principles/core/host';
+type HookName = 'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'SessionStart';
+interface HookSpecificOutput {
+    hookEventName: HookName;
+    permissionDecision?: 'deny';
+    permissionDecisionReason?: string;
+    additionalContext?: string;
+}
+export interface CodexPreToolUseOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export interface CodexPostToolUseOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export interface CodexUserPromptSubmitOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export interface CodexSessionStartOutput {
+    hookSpecificOutput: HookSpecificOutput;
+}
+export type CodexHookOutput = CodexPreToolUseOutput | CodexPostToolUseOutput | CodexUserPromptSubmitOutput | CodexSessionStartOutput;
+export declare class CodexEncoderError extends Error {
+    readonly reason: string;
+    readonly nextAction: string;
+    constructor(reason: string, nextAction: string);
+}
+export declare function encodeCodexOutput(result: HostEventResult, kind: string): CodexHookOutput;
+export declare function codexOutputFieldsAreWhitelisted(output: unknown): {
+    ok: boolean;
+    violators: string[];
+};
+export {};

package/codex-adapter/dist/codec/output-encoder.js

@@ -0,0 +1,51 @@
+export class CodexEncoderError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, nextAction) {
+        super(`Codex output encode failed: ${reason}`);
+        this.reason = reason;
+        this.nextAction = nextAction;
+        this.name = 'CodexEncoderError';
+    }
+}
+function nonEmpty(value) { return typeof value === 'string' && value.trim().length > 0; }
+export function encodeCodexOutput(result, kind) {
+    if (result.modifiedInput !== undefined)
+        throw new CodexEncoderError('modifiedInput is unsupported by the PD Codex adapter', 'Deny or allow the original input.');
+    if (result.additionalContext !== undefined && !nonEmpty(result.additionalContext))
+        throw new CodexEncoderError('additionalContext must be non-empty', 'Drop or populate additionalContext.');
+    const names = new Map([['before_tool_call', 'PreToolUse'], ['after_tool_call', 'PostToolUse'], ['before_prompt_build', 'UserPromptSubmit'], ['session_start', 'SessionStart']]);
+    const hookEventName = names.get(kind);
+    if (!hookEventName)
+        throw new CodexEncoderError(`unknown event kind "${kind}"`, 'Encode only a supported Codex hook event.');
+    if (result.decision === 'deny' && kind !== 'before_tool_call')
+        throw new CodexEncoderError(`deny is unsupported for ${kind}`, 'Return the route-compatible host result.');
+    const hookSpecificOutput = { hookEventName };
+    if (result.decision === 'deny') {
+        if (!nonEmpty(result.reason))
+            throw new CodexEncoderError('deny requires a non-empty reason', 'Supply an operator-readable reason.');
+        hookSpecificOutput.permissionDecision = 'deny';
+        hookSpecificOutput.permissionDecisionReason = result.reason.trim();
+    }
+    else if (result.reason !== undefined) {
+        throw new CodexEncoderError('reason without deny is unsupported', 'Drop reason for a non-deny decision.');
+    }
+    if (result.additionalContext !== undefined)
+        hookSpecificOutput.additionalContext = result.additionalContext;
+    return { hookSpecificOutput };
+}
+const TOP_LEVEL = new Set(['hookSpecificOutput']);
+const NESTED = new Set(['hookEventName', 'permissionDecision', 'permissionDecisionReason', 'additionalContext']);
+export function codexOutputFieldsAreWhitelisted(output) {
+    if (typeof output !== 'object' || output === null || Array.isArray(output))
+        return { ok: false, violators: ['<not-an-object>'] };
+    const top = Object.keys(output).filter((key) => !TOP_LEVEL.has(key));
+    const descriptor = Object.getOwnPropertyDescriptor(output, 'hookSpecificOutput')?.value;
+    if (typeof descriptor !== 'object' || descriptor === null || Array.isArray(descriptor))
+        return { ok: false, violators: [...top, 'hookSpecificOutput'] };
+    const nested = Object.keys(descriptor).filter((key) => !NESTED.has(key)).map((key) => `hookSpecificOutput.${key}`);
+    const name = Object.getOwnPropertyDescriptor(descriptor, 'hookEventName')?.value;
+    if (!['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart'].includes(String(name)))
+        nested.push('hookSpecificOutput.hookEventName');
+    return { ok: top.length + nested.length === 0, violators: [...top, ...nested] };
+}

package/codex-adapter/dist/host-adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CodexHooksHostAdapter — implements HostAdapter for OpenAI Codex CLI (ADR-0020 §2.5)
+ *
+ * Codex CLI spawns `pd-hook.js` as a subprocess for each hook event, writes
+ * the event payload as JSON on stdin, and reads the output as JSON on stdout.
+ * This adapter owns:
+ *   1. Decoding the raw stdin JSON into a unified HostEvent (via codec/input-decoder).
+ *   2. Encoding a unified HostEventResult into Codex's camelCase stdout JSON
+ *      (via codec/output-encoder).
+ *
+ * The adapter does NOT own hook business logic (pain detection, principle
+ * injection, gate enforcement). Those run in the openclaw-plugin/core code and
+ * are invoked by `pd-hook.js` after decodeEvent() and before encodeOutput().
+ *
+ * MVP scope (ADR-0014 / ADR-0020):
+ * - Subscribes to 4 events: before_tool_call, after_tool_call, before_prompt_build, session_start.
+ * - session_end is deferred (observe-only, no MVP-Core activation path uses it).
+ * - hostKind = 'subprocess' (Codex spawns pd-hook.js; OpenClaw is 'inprocess').
+ *
+ * Feature flag: when `host.codex.enabled = false` (default), `pd-hook.js`
+ * short-circuits to `{} + exit 0` before invoking this adapter (rc-9).
+ */
+import type { HostAdapter, HostEvent, HostEventKind, HostEventResult } from '@principles/core/host';
+export declare class CodexHooksHostAdapter implements HostAdapter {
+    readonly hostId = "codex";
+    readonly hostKind: 'subprocess';
+    subscribedEvents(): readonly HostEventKind[];
+    decodeEvent(raw: unknown): HostEvent;
+    encodeOutput(result: HostEventResult, kind: HostEventKind): unknown;
+}

package/codex-adapter/dist/host-adapter.js

@@ -0,0 +1,28 @@
+import { decodeCodexInput, encodeCodexOutput } from './codec/index.js';
+const SUBSCRIBED_EVENTS = [
+    'before_tool_call',
+    'after_tool_call',
+    'before_prompt_build',
+    'session_start',
+    // Stop = turn_complete is the G1-verified turn-complete event (probe
+    // report §2); it drives bounded governance-observation ingestion, not a
+    // dispatch route. session_end stays deferred (SPEC §8: never register both
+    // Stop and SessionEnd for turn completion).
+    'turn_complete',
+];
+export class CodexHooksHostAdapter {
+    hostId = 'codex';
+    hostKind = 'subprocess';
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    subscribedEvents() {
+        return SUBSCRIBED_EVENTS;
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    decodeEvent(raw) {
+        return decodeCodexInput(raw);
+    }
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this
+    encodeOutput(result, kind) {
+        return encodeCodexOutput(result, kind);
+    }
+}

package/codex-adapter/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @principles/codex-adapter — Codex CLI Host Adapter (ADR-0020)
+ *
+ * Implements HostAdapter for OpenAI Codex CLI's stdin/stdout JSON hook model.
+ * This package is INDEPENDENT of `packages/openclaw-plugin/` — the two hosts
+ * have different extension models (Codex: subprocess; OpenClaw: in-process).
+ */
+export { CodexHooksHostAdapter } from './host-adapter.js';
+export { processHookInvocation } from './pd-hook.js';
+export type { PdHookResult } from './pd-hook.js';
+export * from './codec/index.js';
+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, 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/codex-adapter/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @principles/codex-adapter — Codex CLI Host Adapter (ADR-0020)
+ *
+ * Implements HostAdapter for OpenAI Codex CLI's stdin/stdout JSON hook model.
+ * This package is INDEPENDENT of `packages/openclaw-plugin/` — the two hosts
+ * have different extension models (Codex: subprocess; OpenClaw: in-process).
+ */
+export { CodexHooksHostAdapter } from './host-adapter.js';
+export { processHookInvocation } from './pd-hook.js';
+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, 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/codex-adapter/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/codex-adapter/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/codex-adapter/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/codex-adapter/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,
+    };
+}