create-principles-disciple 1.133.0 → 1.133.1

package/host-runtime/dist/codex-ingestion-consent.js

@@ -0,0 +1,223 @@
+/**
+ * Codex conversation-ingestion consent store — Codex Governance Closure
+ * Slice D (SPEC rev 2 §17; G2A frozen disclosure).
+ *
+ * Persists the Owner's recorded consent decision for enabling
+ * `codex_conversation_ingestion` in ONE workspace to
+ * `<workspace>/.pd/codex-ingestion-consent.json`.
+ *
+ * Authority model (P4): the FEATURE FLAG stays the runtime authority for
+ * whether ingestion runs (the hook gate reads only the flag — consent never
+ * sits on the hot path). This store is the GOVERNANCE RECORD that the flag
+ * may only be enabled THROUGH the disclosed consent flow (G2A); health uses
+ * it to report consent state and to flag `flag_on_without_grant` as a
+ * governance warning. Declining must never flip the flag off by side effect
+ * — the setup flow owns that ordering, not this store.
+ *
+ * Scope: per-workspace (the flag and the transcripts it gates are
+ * workspace-scoped). This file is consent control state — it never contains
+ * any captured conversation text (SPEC §15 "consent state without displaying
+ * captured text").
+ *
+ * Patterns mirror the product-telemetry consent store: missing file is the
+ * normal never-asked case; a malformed file fails loud (rc-3/rc-9) because
+ * silently treating it as "never asked" could re-prompt against a recorded
+ * Owner decision; writes are atomic (temp + rename); unknown/malformed
+ * fields are rejected via guards, never `as` (rc-1/rc-2/rc-5).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { CODEX_INGESTION_DISCLOSURE_VERSION } from './codex-disclosure.js';
+export const CODEX_INGESTION_CONSENT_FILENAME = 'codex-ingestion-consent.json';
+export const CODEX_INGESTION_CONSENT_SCHEMA_VERSION = '2';
+export function getCodexIngestionConsentPath(workspaceDir) {
+    return path.join(path.resolve(workspaceDir), '.pd', CODEX_INGESTION_CONSENT_FILENAME);
+}
+function isDecision(value) {
+    return value === 'granted' || value === 'pending' || value === 'revoked' || value === 'failed';
+}
+function isDecidedVia(value) {
+    return value === 'pd_codex_setup' || value === 'codex_plugin_setup';
+}
+function isNonShortString(value, max) {
+    return typeof value === 'string' && value.length > 0 && value.length <= max;
+}
+function isIsoTimestamp(value) {
+    return isNonShortString(value, 40) && !Number.isNaN(Date.parse(value));
+}
+/**
+ * Read the consent record. ENOENT is the normal never-asked case
+ * (existed=false, record=null). Anything unreadable/malformed fails loud —
+ * degrading to "never asked" could re-prompt or re-enable against the
+ * Owner's recorded decision.
+ */
+export function readCodexIngestionConsent(workspaceDir) {
+    const filePath = getCodexIngestionConsentPath(workspaceDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        const codeValue = typeof error === 'object' && error !== null && Object.hasOwn(error, 'code')
+            ? error.code
+            : undefined;
+        if (codeValue === 'ENOENT') {
+            return { ok: true, existed: false, record: null };
+        }
+        const code = typeof codeValue === 'string' ? codeValue : String(error);
+        return {
+            ok: false,
+            reason: `codex_ingestion_consent_unreadable: ${code.slice(0, 120)}`,
+            nextAction: `Check permissions on ${filePath}`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'codex_ingestion_consent_malformed_json',
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to not_present; the ingestion flag itself is unchanged)`,
+        };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            ok: false,
+            reason: 'codex_ingestion_consent_malformed_shape',
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to not_present; the ingestion flag itself is unchanged)`,
+        };
+    }
+    const obj = parsed;
+    const allowedKeys = ['decision', 'disclosureVersion', 'decidedAt', 'decidedVia', 'failureReason', 'schemaVersion'];
+    const errors = [];
+    for (const key of Object.keys(obj)) {
+        if (!allowedKeys.includes(key))
+            errors.push(`unknown field '${key}'`);
+    }
+    if (!isDecision(obj.decision))
+        errors.push('decision must be pending|granted|revoked|failed');
+    if (!isNonShortString(obj.disclosureVersion, 40))
+        errors.push('disclosureVersion must be a short non-empty string');
+    if (!isIsoTimestamp(obj.decidedAt))
+        errors.push('decidedAt must be a parseable ISO-8601 string');
+    if (!isDecidedVia(obj.decidedVia))
+        errors.push('decidedVia must be pd_codex_setup|codex_plugin_setup');
+    if (obj.failureReason !== undefined && !isNonShortString(obj.failureReason, 200)) {
+        errors.push('failureReason must be a non-empty string (≤200 chars) when present');
+    }
+    if (obj.schemaVersion !== CODEX_INGESTION_CONSENT_SCHEMA_VERSION) {
+        errors.push(`schemaVersion must be '${CODEX_INGESTION_CONSENT_SCHEMA_VERSION}'`);
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            reason: `codex_ingestion_consent_malformed: ${errors.join('; ')}`,
+            nextAction: `Fix or delete ${filePath} (delete = consent returns to not_present; the ingestion flag itself is unchanged)`,
+        };
+    }
+    // Post-validation reconstruction from guard-narrowed fields — no `as` on
+    // the untrusted parsed object (rc-2). The errors check above proves every
+    // guard passes; the re-invoked guards here satisfy the type system the
+    // same way the telemetry consent store does.
+    return {
+        ok: true,
+        existed: true,
+        record: {
+            decision: isDecision(obj.decision) ? obj.decision : 'failed',
+            disclosureVersion: isNonShortString(obj.disclosureVersion, 40) ? obj.disclosureVersion : '',
+            decidedAt: isIsoTimestamp(obj.decidedAt) ? obj.decidedAt : '',
+            decidedVia: isDecidedVia(obj.decidedVia) ? obj.decidedVia : 'pd_codex_setup',
+            ...(isNonShortString(obj.failureReason, 200) && obj.failureReason !== undefined ? { failureReason: obj.failureReason } : {}),
+            schemaVersion: CODEX_INGESTION_CONSENT_SCHEMA_VERSION,
+        },
+    };
+}
+/**
+ * Record an explicit consent decision made AFTER the disclosure was
+ * presented (the setup flow presents the frozen text before calling this).
+ * The flag itself is intentionally untouched — enabling it is the setup
+ * flow's explicit, ordered step.
+ */
+export function recordCodexIngestionConsent(workspaceDir, input) {
+    // Write-side validation mirrors the read-side guards (review round 3): a
+    // record this writer produces must never be rejected by its own reader.
+    const errors = [];
+    if (input.decidedAt !== undefined && !isIsoTimestamp(input.decidedAt))
+        errors.push('decidedAt must be a parseable ISO-8601 string when provided');
+    if (input.decision === 'failed' && (input.failureReason === undefined || input.failureReason.trim().length === 0)) {
+        errors.push('decision=failed requires a non-empty failureReason');
+    }
+    if (input.failureReason !== undefined && input.decision !== 'failed' && input.failureReason.trim().length === 0) {
+        errors.push('failureReason must be non-empty when provided');
+    }
+    if (errors.length > 0) {
+        return {
+            ok: false,
+            reason: 'codex_ingestion_consent_input_invalid: ' + errors.join('; '),
+            nextAction: 'Fix the recordCodexIngestionConsent arguments at the call site.',
+        };
+    }
+    const filePath = getCodexIngestionConsentPath(workspaceDir);
+    const record = {
+        decision: input.decision,
+        disclosureVersion: CODEX_INGESTION_DISCLOSURE_VERSION,
+        decidedAt: input.decidedAt ?? new Date().toISOString(),
+        decidedVia: input.decidedVia,
+        ...(input.failureReason !== undefined ? { failureReason: input.failureReason.slice(0, 200) } : {}),
+        schemaVersion: CODEX_INGESTION_CONSENT_SCHEMA_VERSION,
+    };
+    const dir = path.dirname(filePath);
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        fs.renameSync(tmpPath, filePath);
+        return { ok: true, record };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        try {
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup; the write failure below is the loud signal
+        }
+        return {
+            ok: false,
+            reason: `codex_ingestion_consent_write_failed: ${message.slice(0, 200)}`,
+            nextAction: `Check permissions on ${dir}`,
+        };
+    }
+}
+/**
+ * Combine the consent record with the ingestion flag into the health-surface
+ * state (SPEC §15). Every flag×record combination maps to exactly one
+ * interpretable state — none of them reads as silently healthy:
+ *
+ *   record granted  + flag any      → 'granted'    (activation succeeded)
+ *   record revoked  + flag any      → 'revoked'    (Owner said no; flag-off
+ *                                              path also regularizes the flag)
+ *   record failed   + flag any      → 'failed'     (activation did not land;
+ *                                              failureReason explains why)
+ *   record pending  + flag off      → 'pending'    (decision recorded, activation not yet applied)
+ *   record pending  + flag on       → 'pending'    (activation applied, terminal write pending)
+ *   no record       + flag on       → 'flag_on_without_grant'  (governance warning)
+ *   no record       + flag off      → 'not_present'
+ */
+export function deriveCodexIngestionConsentState(record, ingestionFlagEnabled) {
+    if (record === null) {
+        return ingestionFlagEnabled ? 'flag_on_without_grant' : 'not_present';
+    }
+    switch (record.decision) {
+        case 'granted':
+            return 'granted';
+        case 'revoked':
+            return 'revoked';
+        case 'failed':
+            return 'failed';
+        case 'pending':
+            return 'pending';
+    }
+}

package/host-runtime/dist/codex-legacy-registration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Legacy Codex global-hook registration detection — Codex Governance Closure
+ * Slice D (PRI-625; SPEC rev 2 §17 legacy-installer retirement).
+ *
+ * ONE authority for the "is a PD-owned legacy global registration present"
+ * fact: the pure parser lives in @principles/core/host
+ * (parseLegacyCodexHooksRegistration); this wrapper is the FS edge for
+ * host-runtime consumers (health/setup surfaces). The retired installer uses
+ * the same core parser at its own edge.
+ */
+import { type LegacyCodexRegistration } from '@principles/core/host';
+/**
+ * Detect a PD-owned legacy global hook registration in ~/.codex/hooks.json.
+ * Unreadable/malformed/absent ⇒ detected:false (nothing provably ours to
+ * migrate); the health surface reports the unreadable state separately via
+ * its own hooks.json presence check.
+ */
+export declare function detectLegacyCodexHookRegistration(hooksJsonPathOverride?: string): LegacyCodexRegistration;

package/host-runtime/dist/codex-legacy-registration.js

@@ -0,0 +1,34 @@
+/**
+ * Legacy Codex global-hook registration detection — Codex Governance Closure
+ * Slice D (PRI-625; SPEC rev 2 §17 legacy-installer retirement).
+ *
+ * ONE authority for the "is a PD-owned legacy global registration present"
+ * fact: the pure parser lives in @principles/core/host
+ * (parseLegacyCodexHooksRegistration); this wrapper is the FS edge for
+ * host-runtime consumers (health/setup surfaces). The retired installer uses
+ * the same core parser at its own edge.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import * as path from 'node:path';
+import { parseLegacyCodexHooksRegistration } from '@principles/core/host';
+function getCodexHooksJsonPath() {
+    return path.join(os.homedir(), '.codex', 'hooks.json');
+}
+/**
+ * Detect a PD-owned legacy global hook registration in ~/.codex/hooks.json.
+ * Unreadable/malformed/absent ⇒ detected:false (nothing provably ours to
+ * migrate); the health surface reports the unreadable state separately via
+ * its own hooks.json presence check.
+ */
+export function detectLegacyCodexHookRegistration(hooksJsonPathOverride) {
+    const hooksJsonPath = hooksJsonPathOverride ?? getCodexHooksJsonPath();
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+    }
+    catch {
+        return { detected: false, legacyAsyncPostToolUse: false };
+    }
+    return parseLegacyCodexHooksRegistration(parsed);
+}

package/host-runtime/dist/codex-transcript-locate.d.ts

@@ -0,0 +1,16 @@
+export type CodexTranscriptLookup = {
+    ok: true;
+    transcriptPath: string; /** file size in bytes at lookup time (null when stat fails); lets health compute lag without its own stat call */
+    sizeBytes: number | null;
+} | {
+    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;
+};
+/** rollout-<timestamp>-<uuid>.jsonl — returns the rollout uuid, or null when the name is off-contract. */
+export declare function parseRolloutFileName(fileName: string): string | null;
+/**
+ * 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/host-runtime/dist/codex-transcript-locate.js

@@ -0,0 +1,106 @@
+/**
+ * Codex transcript locator — moved to host-runtime in Slice D (PRI-625):
+ * the §15 health surface must compute per-rollout lag with the SAME locator
+ * the catch-up path uses (one truth for "where is this rollout's transcript"),
+ * and host-runtime cannot import codex-adapter. The adapter re-exports it.
+ *
+ * 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';
+/** 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}$/;
+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();
+}
+/**
+ * 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.' };
+    }
+    const transcriptPath = matches[0];
+    let sizeBytes;
+    try {
+        sizeBytes = fs.statSync(transcriptPath).size;
+    }
+    catch {
+        sizeBytes = null;
+    }
+    return { ok: true, transcriptPath, sizeBytes };
+}

package/host-runtime/dist/codex-worker-status.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Codex worker status-mode semantics — moved to host-runtime in Slice D
+ * (PRI-625): the §15 health surface needs the SAME mode authority in the CLI,
+ * the Console, and the worker itself, and this evaluation only depends on
+ * host-neutral inputs (workspace directory, .pd/config.yaml flags, install
+ * manifest registration). codex-adapter re-exports it for compatibility.
+ *
+ * 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 type CodexWorkerMode = 'ready' | 'manual_action_required' | 'paused' | 'degraded';
+export interface CodexWorkerStatusEvaluation {
+    readonly mode: CodexWorkerMode;
+    readonly reason?: string;
+    readonly nextAction?: string;
+}
+export declare function computeCodexWorkerStatusMode(input: {
+    workspaceDir: string;
+    registeredInInstallManifest: boolean;
+}): CodexWorkerStatusEvaluation;

package/host-runtime/dist/codex-worker-status.js

@@ -0,0 +1,52 @@
+/**
+ * Codex worker status-mode semantics — moved to host-runtime in Slice D
+ * (PRI-625): the §15 health surface needs the SAME mode authority in the CLI,
+ * the Console, and the worker itself, and this evaluation only depends on
+ * host-neutral inputs (workspace directory, .pd/config.yaml flags, install
+ * manifest registration). codex-adapter re-exports it for compatibility.
+ *
+ * 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.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { loadPdConfigForPlugin } from './pd-config.js';
+import { computeFeatureFlagsFromConfig } from '@principles/core/runtime-v2';
+function directoryExists(dir) {
+    try {
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+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/host-runtime/dist/governance-observation-store.d.ts

@@ -6,7 +6,8 @@ export declare const GOVERNANCE_PENDING_TAIL_STALE_MS: number;
 export type GovernanceObservationKind = 'user_turn' | 'assistant_turn' | 'tool_call';
 export type GovernanceObservationSource = 'live_hook' | 'transcript';
 export type GovernanceObservationCompleteness = 'complete' | 'partial';
-export type GovernanceRetentionClass = 'operational' | 'promoted' | 'expired' | 'rolled_back';
+/** `quarantined` (Slice D §15): audited, permanently-invalid row; bodies dropped, metadata kept. */
+export type GovernanceRetentionClass = 'operational' | 'promoted' | 'expired' | 'rolled_back' | 'quarantined';
 export interface GovernanceObservationInput {
     readonly hostKind: 'codex';
     readonly rolloutIdentity: string;
@@ -193,4 +194,79 @@ export type ListGovernanceObservationsResult = {
 } | Degradation;
 export declare function listGovernanceObservations(input: ListGovernanceObservationsInput): ListGovernanceObservationsResult;
 export declare function promoteGovernanceEvidence(input: PromoteGovernanceEvidenceInput): PromoteGovernanceEvidenceResult;
+export interface QuarantineGovernanceObservationArgs {
+    readonly workspaceDir: string;
+    readonly hostKind: 'codex';
+    readonly rolloutIdentity: string;
+    /** governance_observations.id — `pd codex ingest quarantine --record <id>`. */
+    readonly recordId: number;
+    /** Why this record is permanently invalid (bounded, stored verbatim). */
+    readonly reason: string;
+    /** Who ran the quarantine (operator identity string, bounded). */
+    readonly operator: string;
+    /** false = dry run (default contract): report, never mutate. */
+    readonly confirm?: boolean;
+    readonly databaseFactory?: ObservationDatabaseFactory;
+}
+export interface QuarantinedRecordSummary {
+    readonly id: number;
+    readonly kind: string;
+    readonly logicalKey: string;
+    readonly observedAt: string;
+    readonly retentionClass: GovernanceRetentionClass;
+    /** SHA-256 over the row's stored content (hex) — computed the same way for dry runs. */
+    readonly digest: string;
+    /** Bounded neighbor description: `prev=<order|none>;next=<order|none>;record=<order|null>`. */
+    readonly gap: string;
+}
+export type QuarantineGovernanceObservationResult = {
+    ok: true;
+    dryRun: boolean;
+    alreadyQuarantined: boolean;
+    record: QuarantinedRecordSummary;
+} | {
+    ok: false;
+    reason: string;
+    nextAction: string;
+};
+/**
+ * Audited quarantine for a permanently invalid governance observation
+ * (SPEC §15). Dry run is the contract default: without `confirm` the store
+ * reports what WOULD happen and mutates nothing. With `confirm`:
+ *  - bodies (visible_text / sanitized_tool_facts_json) are dropped;
+ *  - retention_class becomes `quarantined` (terminal class — never pruned,
+ *    never promoted);
+ *  - digest, reason, operator, timestamp, and the neighbor gap are recorded;
+ *  - the Codex transcript is never read or touched (this function opens only
+ *    the workspace trajectory.db).
+ * Promoted evidence is refused: Owner-decided evidence leaves only through
+ * the Owner governance cleanup commands.
+ */
+export declare function quarantineGovernanceObservation(args: QuarantineGovernanceObservationArgs): QuarantineGovernanceObservationResult;
+export interface GovernanceObservationStats {
+    readonly operational: number;
+    readonly promoted: number;
+    readonly quarantined: number;
+    readonly terminalOther: number;
+    /** Oldest operational observed_at + retention window — when the next row ages out. */
+    readonly nextExpiryAt: string | null;
+    readonly lastObservationAt: string | null;
+}
+export type ReadGovernanceObservationStatsResult = {
+    ok: true;
+    stats: GovernanceObservationStats;
+} | {
+    ok: false;
+    reason: string;
+    nextAction: string;
+};
+/**
+ * Bounded read-only counts for the §15 health surface. Unknown is reported
+ * as a structured degradation — never silently as zero (§15: unknown is not
+ * reported as healthy).
+ */
+export declare function readGovernanceObservationStats(args: {
+    workspaceDir: string;
+    databaseFactory?: ObservationDatabaseFactory;
+}): ReadGovernanceObservationStatsResult;
 export {};