@principles/codex-adapter 0.2.3 → 0.2.5

package/dist/ingestion/ingestion.js

@@ -93,7 +93,7 @@ function ingestTranscriptDelta({ fallbackRootSessionId, canonicalPath, identity,
     if (offset > window.fileSize) {
         // The file shrank below the committed cursor: replaced or truncated —
         // never guess; hold the checkpoint and degrade explicitly.
-        return { status: 'degraded', reason: 'checkpoint_inconsistent', nextAction: 'the transcript is shorter than the committed checkpoint; run the audited recovery/quarantine path once available or re-ingest from a fresh rollout.', warnings: [] };
+        return { status: 'degraded', reason: 'checkpoint_inconsistent', nextAction: 'the transcript is shorter than the committed checkpoint; quarantine the stale rollout records via `pd codex ingest quarantine` or re-ingest from a fresh rollout.', warnings: [] };
     }
     const byteBoundReached = offset + window.bytes.length < window.fileSize;
     const decoded = decodeTranscriptWindow({
@@ -120,7 +120,7 @@ function ingestTranscriptDelta({ fallbackRootSessionId, canonicalPath, identity,
     }
     const degradations = [];
     if (decoded.stop.kind === 'malformed') {
-        degradations.push({ reason: 'transcript_record_malformed', ...(decoded.stop.ordinal !== null ? { ordinal: decoded.stop.ordinal } : {}), nextAction: 'the record is stable-invalid; run the audited quarantine command once available (Slice D). Later records remain as lag.' });
+        degradations.push({ reason: 'transcript_record_malformed', ...(decoded.stop.ordinal !== null ? { ordinal: decoded.stop.ordinal } : {}), nextAction: 'the record is stable-invalid; quarantine this record via `pd codex ingest quarantine` (dry-run default). Later records remain as lag.' });
     }
     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.' });
@@ -164,7 +164,7 @@ function ingestTranscriptDelta({ fallbackRootSessionId, canonicalPath, identity,
         return {
             status: 'degraded',
             reason: 'transcript_record_malformed',
-            nextAction: 'the record is stable-invalid; run the audited quarantine command once available (Slice D). Later records remain as lag.',
+            nextAction: 'the record is stable-invalid; quarantine this record via `pd codex ingest quarantine` (dry-run default). Later records remain as lag.',
             warnings,
         };
     }

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

@@ -1,13 +1,8 @@
-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`.
+ * Codex transcript locator — Slice D (PRI-625) moved the implementation to
+ * @principles/host-runtime (codex-transcript-locate) so the §15 health
+ * service computes per-rollout lag with the SAME locator the catch-up path
+ * uses. This module re-exports it for compatibility with existing importers.
  */
-export declare function locateCodexTranscriptByRolloutIdentity(codexHome: string, rolloutIdentity: string): CodexTranscriptLookup;
+export { locateCodexTranscriptByRolloutIdentity, parseRolloutFileName } from '@principles/host-runtime';
+export type { CodexTranscriptLookup } from '@principles/host-runtime';

package/dist/ingestion/transcript-locate.js

@@ -1,75 +1,7 @@
 /**
- * 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).
+ * Codex transcript locator — Slice D (PRI-625) moved the implementation to
+ * @principles/host-runtime (codex-transcript-locate) so the §15 health
+ * service computes per-rollout lag with the SAME locator the catch-up path
+ * uses. This module re-exports it for compatibility with existing importers.
  */
-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] };
-}
+export { locateCodexTranscriptByRolloutIdentity, parseRolloutFileName } from '@principles/host-runtime';

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

@@ -20,6 +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;
+import { parseRolloutFileName } from '@principles/host-runtime';
+export { parseRolloutFileName };
 export declare function validateCodexTranscriptPath(transcriptPath: string, codexHome: string): TranscriptPathValidation;

package/dist/ingestion/transcript-path.js

@@ -16,27 +16,10 @@
 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();
-}
+// PRI-625 Slice D: the rollout filename contract has ONE implementation,
+// moved to @principles/host-runtime with the transcript locator.
+import { parseRolloutFileName } from '@principles/host-runtime';
+export { parseRolloutFileName };
 function isAbsolutePath(value) {
     return path.isAbsolute(value);
 }

package/dist/pd-hook.js

@@ -3,6 +3,7 @@ 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';
@@ -117,7 +118,7 @@ export async function processHookInvocation(rawStdin, _env = process.env, cwd =
         const ingestionDiagnostics = ingestionEnabled
             ? await runConversationIngestion({ rawPayload: parsed, kind: event.kind, workspaceDir: resolution.workspaceDir, env: _env })
             : [];
-        const result = await createProductionHostRuntime({ hostKind: 'codex' }).dispatch(event);
+        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 };
     }

package/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/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/dist/worker/workspace-worker.d.ts

@@ -45,15 +45,4 @@ export interface CodexWorkerStatusEvaluation {
     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;
+export { computeCodexWorkerStatusMode } from '@principles/host-runtime';

package/dist/worker/workspace-worker.js

@@ -24,8 +24,9 @@
 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, } from '@principles/host-runtime';
+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) {
@@ -194,11 +195,24 @@ export async function runCodexWorkspaceWorkerCycle(options) {
     }
     // 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).
     });
@@ -220,37 +234,7 @@ export async function runCodexWorkspaceWorkerCycle(options) {
         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' };
-}
+// Slice D (PRI-625): the mode authority moved to host-runtime so the CLI and
+// Console §15 health surfaces share ONE semantics with the worker. Re-exported
+// here for compatibility with every existing importer.
+export { computeCodexWorkerStatusMode } from '@principles/host-runtime';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/codex-adapter",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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",