create-principles-disciple 1.132.2 → 1.132.4

package/codex-adapter/dist/ingestion/transcript-path.js

@@ -0,0 +1,87 @@
+/**
+ * Codex transcript path authorization (Codex Governance Closure SPEC rev 2
+ * §9; Slice A SPEC §11).
+ *
+ * The ONLY valid transcript source is the path explicitly supplied by the
+ * authenticated Codex hook — never a scan of `$CODEX_HOME/sessions`, never a
+ * "latest session" guess. Validation covers the real repository/OS path
+ * model: absolute path, `..` traversal rejection, canonical (realpath)
+ * normalization, containment under the resolved Codex home's `sessions`
+ * root at segment boundaries, symlink/junction escape rejection (realpath
+ * collapses them; containment is checked on the canonical form), and a
+ * regular-file requirement. The rollout identity — one physical transcript,
+ * distinct from the root session id (G1 §4 subagent/fork traps) — is the
+ * uuid embedded in the Codex rollout file name.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalizePath } from './codex-home.js';
+const UUID_HEX = /^[0-9a-fA-F]+$/;
+function isHex(value) {
+    return UUID_HEX.test(value);
+}
+/** rollout-<timestamp>-<uuid>.jsonl — returns the rollout uuid, or null when the name is off-contract. */
+export function parseRolloutFileName(fileName) {
+    if (!fileName.startsWith('rollout-') || !fileName.endsWith('.jsonl'))
+        return null;
+    const stem = fileName.slice('rollout-'.length, -'.jsonl'.length);
+    const parts = stem.split('-');
+    if (parts.length < 6)
+        return null; // at least one timestamp segment + the five uuid groups
+    const [a, b, c, d, e] = parts.slice(-5);
+    if (a === undefined || b === undefined || c === undefined || d === undefined || e === undefined)
+        return null;
+    if (a.length !== 8 || b.length !== 4 || c.length !== 4 || d.length !== 4 || e.length !== 12)
+        return null;
+    if (!isHex(a) || !isHex(b) || !isHex(c) || !isHex(d) || !isHex(e))
+        return null;
+    return parts.slice(-5).join('-').toLowerCase();
+}
+function isAbsolutePath(value) {
+    return path.isAbsolute(value);
+}
+function hasParentTraversal(value) {
+    return value.split(/[\\/]+/).includes('..');
+}
+function isContained(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+export function validateCodexTranscriptPath(transcriptPath, codexHome) {
+    if (!isAbsolutePath(transcriptPath) || hasParentTraversal(transcriptPath)) {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'Codex must supply an absolute transcript_path without traversal segments.' };
+    }
+    const fileName = path.basename(transcriptPath);
+    const rolloutIdentity = parseRolloutFileName(fileName);
+    if (rolloutIdentity === null) {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript file name does not match the Codex rollout contract (rollout-<timestamp>-<uuid>.jsonl).' };
+    }
+    let canonicalHome;
+    let canonicalPath;
+    try {
+        // Canonicalize both sides to the final long form: Node's JS realpath
+        // preserves 8.3 short-name segments while payloads carry long forms.
+        canonicalHome = canonicalizePath(codexHome);
+        canonicalPath = canonicalizePath(transcriptPath);
+    }
+    catch {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript path (or the Codex home) does not resolve to an existing location.' };
+    }
+    // realpath collapses symlinks/junctions; checking containment on the
+    // canonical form rejects escapes that traverse links out of the sessions root.
+    if (!isContained(path.join(canonicalHome, 'sessions'), canonicalPath)) {
+        return { ok: false, reason: 'transcript_path_outside_codex_home', nextAction: 'the transcript is not inside the resolved CODEX_HOME sessions root; refusing to read outside the authenticated Codex home.' };
+    }
+    let stats;
+    try {
+        stats = fs.statSync(canonicalPath);
+    }
+    catch {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript file disappeared during validation.' };
+    }
+    if (!stats.isFile()) {
+        return { ok: false, reason: 'transcript_path_invalid', nextAction: 'the transcript path is not a regular file.' };
+    }
+    const identity = { dev: stats.dev, ino: Number(stats.ino), size: stats.size, mtimeMs: stats.mtimeMs };
+    return { ok: true, canonicalPath, rolloutIdentity: rolloutIdentity.toLowerCase(), identity };
+}

package/codex-adapter/dist/pd-hook.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+type EnvMap = Record<string, string | undefined>;
+export interface PdHookResult {
+    stdout: unknown;
+    exitCode: number;
+    stderr: string[];
+}
+export declare function processHookInvocation(rawStdin: string, _env?: EnvMap, cwd?: string): Promise<PdHookResult>;
+export {};

package/codex-adapter/dist/pd-hook.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { createProductionHostRuntime, loadPdConfigForPlugin, resolveNearestPdWorkspace } from '@principles/host-runtime';
+import { CODEX_TOOL_SEMANTICS } from './tool-semantics.js';
+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);
+    const boundedNextAction = nextAction.replace(/\s+/g, ' ').trim().slice(0, MAX_DIAGNOSTIC);
+    return `[PD] status=degraded reason=${boundedReason} nextAction=${boundedNextAction}`;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message.slice(0, MAX_DIAGNOSTIC) : 'unknown_error';
+}
+// Bounded governance-observation ingestion (Codex Governance Closure Slice
+// 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). 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 [];
+    const diagnostics = [];
+    try {
+        const outcome = ingestCodexConversation(rawPayload, kind, { workspaceDir, env });
+        if (outcome.status === 'degraded') {
+            diagnostics.push(diagnostic(outcome.reason, outcome.nextAction));
+        }
+        else {
+            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) {
+        diagnostics.push(diagnostic(`codex_ingestion_unexpected:${errorMessage(error)}`, 'Retry the next Codex turn; if it repeats, inspect PD stderr and the Workspace trajectory database.'));
+    }
+    return diagnostics;
+}
+export async function processHookInvocation(rawStdin, _env = process.env, cwd = process.cwd()) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawStdin);
+    }
+    catch (error) {
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(`stdin_json_invalid:${errorMessage(error)}`, 'Verify Codex invokes the PD hook with one JSON object.')] };
+    }
+    const adapter = new CodexHooksHostAdapter();
+    let event;
+    try {
+        event = adapter.decodeEvent(parsed);
+    }
+    catch (error) {
+        const reason = error instanceof CodexDecoderError ? error.reason : `decode_threw:${errorMessage(error)}`;
+        const nextAction = error instanceof CodexDecoderError ? error.nextAction : 'Inspect the Codex 0.147 hook payload.';
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(reason, nextAction)] };
+    }
+    // Codex 0.147 supplies the invocation cwd. It is the authoritative starting
+    // point; a process-global environment variable can otherwise route one
+    // Workspace's hook into another Workspace's business state.
+    const requestedCwd = event.context.workspaceDir || cwd;
+    const resolution = resolveNearestPdWorkspace(requestedCwd);
+    if (!resolution.ok)
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(resolution.reason, resolution.nextAction)] };
+    event = { ...event, context: { ...event.context, workspaceDir: resolution.workspaceDir } };
+    const config = loadPdConfigForPlugin(resolution.workspaceDir);
+    if (!config.ok) {
+        const [first] = config.errors;
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(first?.reason ?? 'pd_config_invalid', first?.nextAction ?? 'Repair .pd/config.yaml.')] };
+    }
+    const { flags } = computeFeatureFlagsFromConfig(config.effective);
+    if (flags['host.codex']?.enabled !== true) {
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic('host.codex_disabled', 'Set features.host.codex.enabled=true in the selected Workspace to enable PD.')] };
+    }
+    const ingestionEnabled = flags.codex_conversation_ingestion?.enabled === true;
+    if (event.kind === 'turn_complete') {
+        // Stop is the turn-complete ingestion trigger (G1 §2): no dispatch route,
+        // and Codex's Stop output schema has no hookSpecificOutput — the neutral
+        // result is exactly `{}` on stdout (runtime contract: "PD emits empty
+        // stdout on Stop"). Flag-off preserves the zero-transcript-read invariant
+        // and emits ONE bounded structured feature_disabled fact per completed
+        // turn on stderr — never stdout, and never on the per-tool events (that
+        // would be per-event noise).
+        const stderr = ingestionEnabled
+            ? 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 };
+    }
+    try {
+        if (event.kind === 'session_start') {
+            const health = await createProductionHostRuntime({ hostKind: 'codex' }).health(resolution.workspaceDir);
+            if (!health.ok)
+                return { stdout: {}, exitCode: 0, stderr: [diagnostic(health.reason ?? 'runtime_unhealthy', health.nextAction ?? 'Inspect the Workspace runtime.')] };
+            return { stdout: adapter.encodeOutput({ decision: 'allow', source: event.source }, 'session_start'), exitCode: 0, stderr: [] };
+        }
+        const ingestionDiagnostics = ingestionEnabled
+            ? await runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
+            : [];
+        const result = await createProductionHostRuntime({ hostKind: 'codex', toolSemantics: CODEX_TOOL_SEMANTICS }).dispatch(event);
+        const stderr = [...(result.warnings ?? []).slice(0, 16).map((warning) => diagnostic(warning, 'Inspect PD Workspace state and retry; the hook failed open.')), ...ingestionDiagnostics];
+        return { stdout: adapter.encodeOutput(result, event.kind), exitCode: 0, stderr };
+    }
+    catch (error) {
+        const reason = error instanceof CodexEncoderError ? error.reason : `runtime_failed:${errorMessage(error)}`;
+        const nextAction = error instanceof CodexEncoderError ? error.nextAction : 'Inspect PD Workspace state and retry; the hook failed open.';
+        return { stdout: {}, exitCode: 0, stderr: [diagnostic(reason, nextAction)] };
+    }
+}
+async function main() {
+    let raw;
+    try {
+        raw = readFileSync(0, 'utf8');
+    }
+    catch (error) {
+        process.stderr.write(`${diagnostic(`stdin_read_failed:${errorMessage(error)}`, 'Run the hook from Codex with JSON stdin.')}\n`);
+        process.stdout.write('{}\n');
+        return;
+    }
+    let result;
+    try {
+        result = await processHookInvocation(raw);
+    }
+    catch (error) {
+        // Fail-open belt for an unexpected pre-dispatch throw (e.g. a workspace
+        // resolution race): Codex must still receive exactly one JSON object on
+        // stdout and a bounded diagnostic on stderr — never a bare crash.
+        process.stderr.write(`${diagnostic(`hook_pipeline_unexpected:${errorMessage(error)}`, 'Retry the tool call; if it repeats, inspect PD stderr and the Workspace .pd/config.yaml state.')}\n`);
+        result = { stdout: {}, exitCode: 0, stderr: [] };
+    }
+    for (const line of result.stderr)
+        process.stderr.write(`${line}\n`);
+    process.stdout.write(`${JSON.stringify(result.stdout)}\n`);
+    process.exitCode = result.exitCode;
+}
+const [, entry] = process.argv;
+if (entry && import.meta.url === pathToFileURL(entry).href)
+    void main();

package/codex-adapter/dist/tool-semantics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Codex Tool Semantic Declaration — PRI-634-F R2 (review P1-2)
+ *
+ * PURPOSE: the Codex host layer of the Tool Semantic Registry. Codex names
+ * its shell tool `Bash` (capitalized — evidenced by the codex-adapter
+ * integration fixtures), which the core baseline's lowercase `bash` never
+ * matches: rules generated against the baseline name could pass replay and
+ * never fire on a real Codex event.
+ *
+ * EVIDENCE BOUND: this declaration contains only names with in-repo
+ * evidence — the installer's hook matcher `Bash|apply_patch`
+ * (create-principles-disciple/src/installers/codex-host-installer.ts:203,
+ * locked by codex-plugin-bundle.test.ts). Extending it with the remaining
+ * Codex tool surface is tracked as PRI-657 — a wrong guess would be worse
+ * than a gap (the reliability check rejects undeclared names, forcing
+ * correct names).
+ */
+import { type ToolSemanticMappingV1, type ToolSemanticRegistry } from '@principles/core/runtime-v2';
+export declare const CODEX_TOOL_SEMANTIC_MAPPINGS: readonly ToolSemanticMappingV1[];
+export declare const CODEX_TOOL_SEMANTICS: ToolSemanticRegistry;

package/codex-adapter/dist/tool-semantics.js

@@ -0,0 +1,27 @@
+/**
+ * Codex Tool Semantic Declaration — PRI-634-F R2 (review P1-2)
+ *
+ * PURPOSE: the Codex host layer of the Tool Semantic Registry. Codex names
+ * its shell tool `Bash` (capitalized — evidenced by the codex-adapter
+ * integration fixtures), which the core baseline's lowercase `bash` never
+ * matches: rules generated against the baseline name could pass replay and
+ * never fire on a real Codex event.
+ *
+ * EVIDENCE BOUND: this declaration contains only names with in-repo
+ * evidence — the installer's hook matcher `Bash|apply_patch`
+ * (create-principles-disciple/src/installers/codex-host-installer.ts:203,
+ * locked by codex-plugin-bundle.test.ts). Extending it with the remaining
+ * Codex tool surface is tracked as PRI-657 — a wrong guess would be worse
+ * than a gap (the reliability check rejects undeclared names, forcing
+ * correct names).
+ */
+import { buildToolSemanticRegistry } from '@principles/core/runtime-v2';
+export const CODEX_TOOL_SEMANTIC_MAPPINGS = Object.freeze([
+    { rawToolName: 'Bash', canonicalKind: 'execute' },
+    { rawToolName: 'apply_patch', canonicalKind: 'write' },
+]);
+const built = buildToolSemanticRegistry(CODEX_TOOL_SEMANTIC_MAPPINGS);
+if (!built.ok) {
+    throw new Error(`[PD] Codex tool semantic declaration is invalid: ${built.errors.join('; ')}`);
+}
+export const CODEX_TOOL_SEMANTICS = built.registry;

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

@@ -0,0 +1,59 @@
+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;
+        /** PRI-638 P1-C: recovery action for capability-disabled pauses. */
+        readonly nextAction?: 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/codex-adapter/dist/worker/workspace-worker.js

@@ -0,0 +1,270 @@
+/**
+ * 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, resolveDiagnosticianCapability, } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin, loadFeatureFlagFromConfig, reconcileGovernanceContinuation, runInternalizationConsumerCycle, saveHostToolDeclaration, } from '@principles/host-runtime';
+import { catchUpCodexIngestion } from '../ingestion/catch-up.js';
+import { CODEX_TOOL_SEMANTIC_MAPPINGS, CODEX_TOOL_SEMANTICS } from '../tool-semantics.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) });
+    // PRI-638 P1-C: the Diagnostician capability gate is resolved from the same
+    // canonical authority the runtime factory uses. An Owner-disabled agent is
+    // an intentional governance state: the worker must NOT pick pending tasks,
+    // must NOT invoke any runner (provider calls = 0), must NOT report the
+    // workspace degraded, and must keep catch-up / reconciliation / downstream
+    // running. Pending tasks stay untouched and resume on a later cycle after
+    // the Owner re-enables the agent.
+    const capability = resolveDiagnosticianCapability(config.effective);
+    const diagnosticianDisabled = !capability.available;
+    // 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 (diagnosticianDisabled) {
+        // PRI-638 P1-C: intentional governance pause. No candidate picking, no
+        // provider call, no degraded mode. The rest of the cycle (downstream)
+        // continues below; pending tasks resume once the Owner re-enables.
+        diagnostician = {
+            taskId: '',
+            status: 'skipped',
+            message: 'capability_disabled',
+            nextAction: capability.available ? undefined : capability.nextAction,
+        };
+    }
+    else 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 },
+        };
+    }
+    else {
+        // Step 4 — expired-lease recovery sweep, then Step 5/6: at most one
+        // Diagnostician task via the existing bridge lease/runner contract.
+        // (Reached only when the Diagnostician capability is enabled AND the
+        // consumer flag is on — an intentional capability pause never reaches
+        // candidate picking or any provider call.)
+        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).
+    // PRI-634-F R2: persist the Codex tool declaration (workspace provenance
+    // for host-neutral consumers) and thread the registry into the cycle so
+    // activation-gate replay resolves Codex tool semantics (Bash, not bash).
+    const declared = saveHostToolDeclaration(workspaceDir, {
+        version: 1,
+        hostKind: 'codex',
+        mappings: CODEX_TOOL_SEMANTIC_MAPPINGS,
+        declaredAt: new Date().toISOString(),
+    });
+    if (!declared.ok) {
+        logger.warn?.(`[PD:CodexWorker] Failed to persist Codex tool declaration: ${declared.reason} — host-neutral consumers will not find it (rc-9)`);
+    }
+    const downstream = await runInternalizationConsumerCycle(workspaceDir, {
+        owner: WORKER_OWNER,
+        logLabel: 'CodexWorker',
+        logger,
+        emitEvent,
+        toolSemantics: CODEX_TOOL_SEMANTICS,
+        // 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' };
+}