@compaction/cli 0.2.0 → 0.3.1

package/dist/core/auto-apply-ask.js

@@ -0,0 +1,105 @@
+/**
+ * The POST-APPROVAL binary auto-apply ASK (charter 2026-07-04-run-7, lane 5: "binary ask-after-approve,
+ * inferred safest scope").
+ *
+ * WHAT THIS IS: pure logic for the founder's §11a block-4 question — the ONE binary question offered
+ * AFTER a user has ALREADY explicitly approved a compaction in-workflow ("Apply this automatically
+ * next time for this workflow when safety gates pass? [y] yes / [n] no, ask me each time", default no).
+ *
+ * WHAT THIS IS NOT — the rails:
+ *   - It APPLIES NOTHING. Saving a preference records INTENT for a FUTURE gated slice; it never turns
+ *     into an application here (see `auto-apply-gates.ts` — report-only — and `policy-preferences.ts` —
+ *     a store with no apply path). This module does no I/O at all: it returns a DECISION describing
+ *     what the CLI boundary should persist (via `savePolicyPreference`) or skip. It never writes.
+ *   - The offer exists ONLY after an explicit approval already happened. `approvedInWorkflow=false`
+ *     → skip, always.
+ *   - Default is NO. Only an explicit affirmative answer saves anything; `no` / default / anything
+ *     unrecognized saves nothing.
+ *   - Scope is the SAFEST inferred scope: one tool/workflow (+ repo where detectable + policy type),
+ *     NEVER global, NEVER cross-tool. There is NO scope menu — the scope is inferred, never chosen.
+ *     A missing/global/cross-tool tool → the offer is BLOCKED (saves nothing, fail-closed).
+ */
+import { AUTO_APPLY_GATE_NAMES } from "./auto-apply-gates.js";
+import { validatePolicyPreferenceScope } from "./policy-preferences.js";
+/** The exact §11a block-4 binary question. No scope menu — the scope is inferred, never asked. */
+export const AUTO_APPLY_QUESTION_LINES = [
+    "Apply this automatically next time for this workflow when safety gates pass?",
+    "  [y] yes",
+    "  [n] no, ask me each time"
+];
+/** A stored preference records these gate names (the founder's gate list from `auto-apply-gates`). */
+export const AUTO_APPLY_PREFERENCE_GATES_REQUIRED = [...AUTO_APPLY_GATE_NAMES];
+/**
+ * Interpret a raw answer. DEFAULT IS NO: only an explicit `y` / `yes` (case-insensitive, trimmed) is
+ * `yes`; empty, `n`, `no`, undefined, or anything unrecognized is `no`. Never throws.
+ */
+export function interpretAutoApplyAnswer(raw) {
+    if (typeof raw !== "string")
+        return "no";
+    const value = raw.trim().toLowerCase();
+    return value === "y" || value === "yes" ? "yes" : "no";
+}
+/**
+ * Resolve the binary offer into a DECISION. PURE — no I/O, no side effects. Enforces every rail:
+ * offer only after approval; default no; safest inferred scope; never global/cross-tool. Saving is
+ * left to the CLI boundary (`savePolicyPreference`); this never applies anything.
+ */
+export function resolveAutoApplyOffer(input) {
+    if (!input.approvedInWorkflow) {
+        return {
+            action: "skip",
+            reason: "no in-workflow approval happened — the auto-apply offer is only made after an explicit approval"
+        };
+    }
+    if (input.answer !== "yes") {
+        return { action: "skip", reason: "answered no (or default) — nothing saved; Compaction will keep asking each time" };
+    }
+    const tool = input.scope.tool?.trim();
+    const policyType = input.scope.policyType?.trim();
+    const repo = input.scope.repo?.trim();
+    const candidateScope = {
+        tool: tool ?? "",
+        policy_type: policyType ?? "",
+        ...(repo ? { repo } : {})
+    };
+    const { problems } = validatePolicyPreferenceScope(candidateScope);
+    if (problems.length > 0) {
+        return { action: "blocked", problems };
+    }
+    const scope = {
+        tool: candidateScope.tool,
+        policy_type: candidateScope.policy_type,
+        ...(repo ? { repo } : {})
+    };
+    return {
+        action: "save",
+        scope,
+        preference: "auto-when-gates-pass",
+        gatesRequired: [...AUTO_APPLY_PREFERENCE_GATES_REQUIRED]
+    };
+}
+/**
+ * The §11a block-5 saved-preference confirmation (scope · gates · undo hint). Honest: states the
+ * preference is stored and that every FUTURE application would be logged, evidence-labeled, undoable —
+ * it does NOT claim anything was applied. No wall-clock, no content.
+ */
+export function formatSavedPreferenceConfirmation(preference) {
+    const scopeParts = ["this tool", preference.scope.repo ? "this repo" : null, "this policy type"].filter((part) => part !== null);
+    return [
+        "Saved preference:",
+        `Compaction will apply ${preference.scope.policy_type} automatically for`,
+        "this workflow when safety gates pass.",
+        "",
+        `Scope: this workflow only (${scopeParts.join(" · ")}) — never`,
+        "global, never cross-tool. Every automatic application is logged, evidence-labeled,",
+        "and undoable.",
+        "",
+        "Not yet active: no auto-apply engine exists yet — this records your preference only.",
+        "Nothing is applied automatically today.",
+        "",
+        "Review or turn off anytime:",
+        "  compaction policies list",
+        `  compaction policies disable ${preference.id}`
+    ].join("\n");
+}
+//# sourceMappingURL=auto-apply-ask.js.map

package/dist/core/auto-apply-gates.d.ts

@@ -0,0 +1,76 @@
+/**
+ * REPORT-ONLY auto-apply GATE CHECK (charter 2026-07-04-run-7, lane 5: "auto-apply preference model:
+ * ... fail-closed gates scaffold, tests proving OFF by default").
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ * │  THIS MODULE APPLIES NOTHING. It is a PURE, REPORT-ONLY verdict function.                     │
+ * │                                                                                               │
+ * │  `evaluateAutoApplyGates(context)` reads a context object and returns a per-gate pass/fail    │
+ * │  verdict plus an `allPassed` roll-up. That is ALL it does. It:                                 │
+ * │    - imports NOTHING that mutates a session, trace, run record, file, or context;             │
+ * │    - performs NO file I/O, NO network, NO process side effect of any kind;                     │
+ * │    - exports NO apply / execute / mutate / write / run / persist / save function;              │
+ * │    - NEVER invokes the apply engine (src/engine/**) — it does not import it at all.            │
+ * │                                                                                               │
+ * │  A verdict of `allPassed: true` does NOT cause anything to be applied. No caller in this      │
+ * │  cycle turns a verdict into an application — there is no gated auto-apply engine yet. This     │
+ * │  function exists so the FUTURE gated slice has ONE honest, testable place that decides whether │
+ * │  the founder's safety gates are satisfied, and so today's tests can prove auto-apply is OFF.   │
+ * └─────────────────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * FAIL-CLOSED (founder decision, active-loop-charter): every gate defaults to FAILED. A gate passes
+ * ONLY when its context field is EXACTLY boolean `true`. Any missing / undefined / null / unknown /
+ * non-`true` input → that gate is FAILED (never "assumed pass"). `allPassed` requires EVERY gate to
+ * pass — including the `explicit-opt-in` gate — so with an empty or partial context, `allPassed` is
+ * always `false`.
+ *
+ * The gate list mirrors the founder's rule verbatim ("Auto-apply allowed ONLY when: explicit opt-in +
+ * matching scope + original retained + capsule provenance + recoverability pass + threshold + risk
+ * checks + evidence label emitted + rollback path") and the store's `DEFAULT_GATES_REQUIRED`.
+ */
+/** The ordered auto-apply gate names. `explicit-opt-in` is first — it is the whole precondition. */
+export declare const AUTO_APPLY_GATE_NAMES: readonly ["explicit-opt-in", "scope-match", "original-retained", "capsule-provenance", "recoverability-pass", "reduction-threshold", "risk-checks", "evidence-label-emitted", "rollback-path"];
+export type AutoApplyGateName = (typeof AUTO_APPLY_GATE_NAMES)[number];
+/**
+ * The inputs a caller would collect to ask "may this be auto-applied?". EVERY field is optional and
+ * defaults to FAILED — a caller must positively assert each `true`. Nothing here is content; these
+ * are boolean safety facts the (future) gated slice would establish before any application.
+ */
+export interface AutoApplyGateContext {
+    /** An ENABLED `auto-when-gates-pass` preference exists for this exact scope (the opt-in). */
+    explicitOptIn?: boolean;
+    /** The run's inferred scope (tool + repo? + policy type) matches the stored preference's scope. */
+    scopeMatches?: boolean;
+    /** The un-compacted original is retained and locatable. */
+    originalRetained?: boolean;
+    /** Capsule / source-pointer provenance is present for what would change. */
+    capsuleProvenancePresent?: boolean;
+    /** A recoverability check passed (the change can be reversed). */
+    recoverabilityPassed?: boolean;
+    /** The reduction threshold was met (enough avoidable context to be worth applying). */
+    reductionThresholdMet?: boolean;
+    /** Risk checks passed (no risky content class flagged). */
+    riskChecksPassed?: boolean;
+    /** An evidence label was emitted for the change. */
+    evidenceLabelPresent?: boolean;
+    /** A rollback / undo path is present. */
+    rollbackPathPresent?: boolean;
+}
+/** One gate's verdict. `passed` is REPORT-ONLY; `reason` explains a fail (fail-closed) or a pass. */
+export interface AutoApplyGateVerdict {
+    name: AutoApplyGateName;
+    passed: boolean;
+    reason: string;
+}
+/** The whole verdict. `allPassed` is true ONLY when every gate passed. Applies nothing. */
+export interface AutoApplyGateReport {
+    allPassed: boolean;
+    gates: AutoApplyGateVerdict[];
+}
+/**
+ * PURE + REPORT-ONLY. Evaluate the auto-apply safety gates over `context` and return per-gate
+ * verdicts + an `allPassed` roll-up. FAIL-CLOSED: a gate passes ONLY when its field is exactly
+ * `true`; every other value (missing / null / undefined / non-`true`) fails that gate. This function
+ * NEVER applies, mutates, writes, or invokes anything — the returned report is its only effect.
+ */
+export declare function evaluateAutoApplyGates(context?: AutoApplyGateContext): AutoApplyGateReport;

package/dist/core/auto-apply-gates.js

@@ -0,0 +1,113 @@
+/**
+ * REPORT-ONLY auto-apply GATE CHECK (charter 2026-07-04-run-7, lane 5: "auto-apply preference model:
+ * ... fail-closed gates scaffold, tests proving OFF by default").
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────────────────────────┐
+ * │  THIS MODULE APPLIES NOTHING. It is a PURE, REPORT-ONLY verdict function.                     │
+ * │                                                                                               │
+ * │  `evaluateAutoApplyGates(context)` reads a context object and returns a per-gate pass/fail    │
+ * │  verdict plus an `allPassed` roll-up. That is ALL it does. It:                                 │
+ * │    - imports NOTHING that mutates a session, trace, run record, file, or context;             │
+ * │    - performs NO file I/O, NO network, NO process side effect of any kind;                     │
+ * │    - exports NO apply / execute / mutate / write / run / persist / save function;              │
+ * │    - NEVER invokes the apply engine (src/engine/**) — it does not import it at all.            │
+ * │                                                                                               │
+ * │  A verdict of `allPassed: true` does NOT cause anything to be applied. No caller in this      │
+ * │  cycle turns a verdict into an application — there is no gated auto-apply engine yet. This     │
+ * │  function exists so the FUTURE gated slice has ONE honest, testable place that decides whether │
+ * │  the founder's safety gates are satisfied, and so today's tests can prove auto-apply is OFF.   │
+ * └─────────────────────────────────────────────────────────────────────────────────────────────┘
+ *
+ * FAIL-CLOSED (founder decision, active-loop-charter): every gate defaults to FAILED. A gate passes
+ * ONLY when its context field is EXACTLY boolean `true`. Any missing / undefined / null / unknown /
+ * non-`true` input → that gate is FAILED (never "assumed pass"). `allPassed` requires EVERY gate to
+ * pass — including the `explicit-opt-in` gate — so with an empty or partial context, `allPassed` is
+ * always `false`.
+ *
+ * The gate list mirrors the founder's rule verbatim ("Auto-apply allowed ONLY when: explicit opt-in +
+ * matching scope + original retained + capsule provenance + recoverability pass + threshold + risk
+ * checks + evidence label emitted + rollback path") and the store's `DEFAULT_GATES_REQUIRED`.
+ */
+/** The ordered auto-apply gate names. `explicit-opt-in` is first — it is the whole precondition. */
+export const AUTO_APPLY_GATE_NAMES = [
+    "explicit-opt-in",
+    "scope-match",
+    "original-retained",
+    "capsule-provenance",
+    "recoverability-pass",
+    "reduction-threshold",
+    "risk-checks",
+    "evidence-label-emitted",
+    "rollback-path"
+];
+/** Map each gate to the context field it reads and the human reason strings. */
+const GATE_CHECKS = [
+    {
+        name: "explicit-opt-in",
+        read: (c) => c.explicitOptIn,
+        passReason: "an enabled auto-when-gates-pass preference exists for this scope",
+        failReason: "no explicit opt-in — the user has not chosen auto-apply for this scope (default: ask each time)"
+    },
+    {
+        name: "scope-match",
+        read: (c) => c.scopeMatches,
+        passReason: "the run's inferred scope matches the stored preference's scope",
+        failReason: "the run's scope does not match a stored preference (never applies cross-scope)"
+    },
+    {
+        name: "original-retained",
+        read: (c) => c.originalRetained,
+        passReason: "the un-compacted original is retained and locatable",
+        failReason: "the original is not confirmed retained — cannot proceed without a retained original"
+    },
+    {
+        name: "capsule-provenance",
+        read: (c) => c.capsuleProvenancePresent,
+        passReason: "capsule / source-pointer provenance is present",
+        failReason: "capsule / source-pointer provenance is missing"
+    },
+    {
+        name: "recoverability-pass",
+        read: (c) => c.recoverabilityPassed,
+        passReason: "a recoverability check passed",
+        failReason: "the recoverability check did not pass"
+    },
+    {
+        name: "reduction-threshold",
+        read: (c) => c.reductionThresholdMet,
+        passReason: "the reduction threshold was met",
+        failReason: "the reduction threshold was not met"
+    },
+    {
+        name: "risk-checks",
+        read: (c) => c.riskChecksPassed,
+        passReason: "risk checks passed",
+        failReason: "risk checks did not pass"
+    },
+    {
+        name: "evidence-label-emitted",
+        read: (c) => c.evidenceLabelPresent,
+        passReason: "an evidence label was emitted",
+        failReason: "no evidence label was emitted"
+    },
+    {
+        name: "rollback-path",
+        read: (c) => c.rollbackPathPresent,
+        passReason: "a rollback / undo path is present",
+        failReason: "no rollback / undo path is present"
+    }
+];
+/**
+ * PURE + REPORT-ONLY. Evaluate the auto-apply safety gates over `context` and return per-gate
+ * verdicts + an `allPassed` roll-up. FAIL-CLOSED: a gate passes ONLY when its field is exactly
+ * `true`; every other value (missing / null / undefined / non-`true`) fails that gate. This function
+ * NEVER applies, mutates, writes, or invokes anything — the returned report is its only effect.
+ */
+export function evaluateAutoApplyGates(context = {}) {
+    const gates = GATE_CHECKS.map((gate) => {
+        const passed = gate.read(context) === true;
+        return { name: gate.name, passed, reason: passed ? gate.passReason : gate.failReason };
+    });
+    return { allPassed: gates.every((gate) => gate.passed), gates };
+}
+//# sourceMappingURL=auto-apply-gates.js.map

package/dist/core/before-call-activity.d.ts

@@ -0,0 +1,35 @@
+import { type ActivityApprovalStatus, type ActivityEvent } from "./activity-event.js";
+import { type BeforeCallRecommendation, type BeforeCallTool } from "./before-call.js";
+/**
+ * Build ONE content-free before-call activity event. `approvalStatus` records the approval OUTCOME
+ * honestly:
+ * - `"not-required"` — recommendation-only path (nothing was applied, so nothing needed approval).
+ * - `"asked-approved"` (with `applied: true`) — the operator approved a whitelist-safe mutation and the
+ *   compacted input was applied to this call; the original was retained locally (pass `recoveryPointer`).
+ * - `"asked-declined"` — the operator was asked and declined; the original ran unchanged.
+ * - `"not-asked"` (with `notAvailableReason`) — apply was NOT available (ambiguous/unsupported argv, or
+ *   no interactive TTY), so we did not ask; the original ran unchanged.
+ *
+ * Content-free in EVERY arm: only counts, policy id, honest labels, and (when applied) a CONTENT-SAFE
+ * recovery pointer (id/path, NEVER the prompt text) ride on the event. `applied_automatically` is the
+ * literal `false` in every arm — an approved mutation is a MANUAL per-invocation approval, never an
+ * auto-apply.
+ */
+export declare function buildBeforeCallActivityEvent(params: {
+    tool: BeforeCallTool;
+    recommendation: BeforeCallRecommendation;
+    approvalStatus: ActivityApprovalStatus;
+    /** True only for an operator-approved mutation that WAS applied to this call. */
+    applied?: boolean;
+    /** Content-safe recovery pointer (id/path) for an applied mutation — NEVER the prompt text. */
+    recoveryPointer?: string;
+    /** Content-free reason apply was not available (for the `not-asked` arm). */
+    notAvailableReason?: string;
+    /**
+     * Which input boundary was mediated (content-free label, for the honest applied caveat):
+     * - `"prompt-flag"` (default, run-11): the value of a whitelisted value-taking prompt flag (dormant
+     *   for the real tools — no such flag exists).
+     * - `"stdin"` (run-12): the whole stdin prompt STREAM for `codex exec` (the first real apply surface).
+     */
+    boundary?: "prompt-flag" | "stdin";
+}): ActivityEvent;

package/dist/core/before-call-activity.js

@@ -0,0 +1,103 @@
+/**
+ * BEFORE-CALL → metrics-only activity BRIDGE (PUBLIC CLI/SDK code — engine-free, ships in the npm
+ * package). Charter 2026-07-04-run-10. Turns a before-call recommendation + approval outcome into ONE
+ * content-free activity event, reusing the SAME event model (`buildRunCrossSurfaceEvent`) and the SAME
+ * local activity store (#597) as the run-9 measurement bridge — no new store, no new schema.
+ *
+ * Honesty rails (identical spirit to `shim-capture-bridge.ts`):
+ * - Input is a LOCAL-ESTIMATE pre-call (chars/4); output is unavailable-with-reason pre-call for BOTH
+ *   tools (provider usage does not exist until after the call). The tier table structurally rejects a
+ *   provider-reported label here.
+ * - CONTENT-FREE: only token COUNTS (before/after), the policy id, honest labels, and opaque ids ride
+ *   on the event. No prompt/response/message text is ever read into the event.
+ * - Recommendation-only: `applied_automatically` is the literal `false`, auto-apply is OFF
+ *   (`ask-each-time`), recovery `original_retained: true` (the original is never touched), sync
+ *   `local-only`. The compacted input is NEVER applied by this path.
+ */
+import { createHash } from "node:crypto";
+import { createUsageMetadata } from "./usage-metadata.js";
+import { buildRunFlowTokenReport } from "./run-flow-report.js";
+import { buildRunCrossSurfaceEvent } from "./cross-surface-event.js";
+import { computeActivityEventId } from "./activity-event.js";
+import { BEFORE_CALL_REDUCTION_LABEL } from "./before-call.js";
+/** The honest per-tool reason the OUTPUT axis is unavailable at pre-call time. */
+const OUTPUT_UNAVAILABLE_REASON = {
+    codex: "no output tokens exist before the call; provider usage (turn.completed.usage) is only reported after codex runs",
+    cursor: "Cursor emits no provider usage, and no output exists before the call"
+};
+/** A content-free, deterministic run id from the tool + local-estimate counts (never any content). */
+function contentFreeRunId(tool, before, after) {
+    const digest = createHash("sha256").update(`before-call|${tool}|${before}|${after}`).digest("hex");
+    return `before-call-${tool}-${digest.slice(0, 16)}`;
+}
+/**
+ * Build ONE content-free before-call activity event. `approvalStatus` records the approval OUTCOME
+ * honestly:
+ * - `"not-required"` — recommendation-only path (nothing was applied, so nothing needed approval).
+ * - `"asked-approved"` (with `applied: true`) — the operator approved a whitelist-safe mutation and the
+ *   compacted input was applied to this call; the original was retained locally (pass `recoveryPointer`).
+ * - `"asked-declined"` — the operator was asked and declined; the original ran unchanged.
+ * - `"not-asked"` (with `notAvailableReason`) — apply was NOT available (ambiguous/unsupported argv, or
+ *   no interactive TTY), so we did not ask; the original ran unchanged.
+ *
+ * Content-free in EVERY arm: only counts, policy id, honest labels, and (when applied) a CONTENT-SAFE
+ * recovery pointer (id/path, NEVER the prompt text) ride on the event. `applied_automatically` is the
+ * literal `false` in every arm — an approved mutation is a MANUAL per-invocation approval, never an
+ * auto-apply.
+ */
+export function buildBeforeCallActivityEvent(params) {
+    const { tool, recommendation, approvalStatus, applied, recoveryPointer, notAvailableReason } = params;
+    const boundary = params.boundary ?? "prompt-flag";
+    const usage = createUsageMetadata({
+        inputTokens: recommendation.input_tokens_before,
+        providerReportedTokens: false,
+        estimatedTokens: true,
+        limitations: [BEFORE_CALL_REDUCTION_LABEL]
+    });
+    const tokenReport = buildRunFlowTokenReport({ tool, usage, outputStatus: "unavailable" });
+    const base = buildRunCrossSurfaceEvent(tool, {
+        runId: contentFreeRunId(tool, recommendation.input_tokens_before, recommendation.input_tokens_after_estimate),
+        tokenReport,
+        reasons: { output: OUTPUT_UNAVAILABLE_REASON[tool] }
+    });
+    // Honest, content-free per-arm caveats. base.caveats already carries the reduction label.
+    const appliedWhat = boundary === "stdin"
+        ? "the compacted input replaced the stdin prompt STREAM only; every command-line argument ran unchanged"
+        : "the compacted input replaced ONLY the whitelisted prompt argument — every other argument ran unchanged";
+    const armCaveats = applied
+        ? [
+            `before-call compaction APPLIED to this call (operator-approved, per-invocation); ${appliedWhat}`,
+            "the ORIGINAL input was retained LOCAL-ONLY (gitignored, never uploaded) and is recoverable via the " +
+                "content-safe recovery pointer below"
+        ]
+        : notAvailableReason
+            ? [
+                `before-call apply not-available: ${notAvailableReason}`,
+                "the original input ran UNCHANGED (fail-closed); this is recommendation-only for this invocation"
+            ]
+            : [
+                "before-call recommendation-only: nothing was applied to this call; the original input ran unchanged",
+                "to apply a before-call compaction, use the explicit `compaction apply-context` path"
+            ];
+    const activity = {
+        ...base,
+        // The compacted local-estimate is the pre-call INPUT AFTER figure. Realized (applied) or recommended
+        // (un-applied) — either way a LOCAL-ESTIMATE delta, never a saving, never provider-reported.
+        input_after: recommendation.input_tokens_after_estimate,
+        policy_used: recommendation.policy,
+        evidence_level: recommendation.evidence_label,
+        caveats: [...(base.caveats ?? []), ...armCaveats],
+        approval_status: approvalStatus,
+        auto_apply: {
+            // Eligible reflects whether there was avoidable context — but auto-apply stays OFF regardless.
+            // Even an approved mutation is applied_automatically:false (a manual per-invocation approval).
+            eligible: recommendation.has_avoidable_context,
+            preference: "ask-each-time",
+            applied_automatically: false
+        },
+        recovery: recoveryPointer ? { original_retained: true, location: recoveryPointer } : { original_retained: true },
+        sync_status: "local-only"
+    };
+    return { ...activity, activity_event_id: computeActivityEventId(activity) };
+}
+//# sourceMappingURL=before-call-activity.js.map

package/dist/core/before-call-recovery.d.ts

@@ -0,0 +1,19 @@
+/** The gitignored subtree that holds retained originals (local-only). */
+export declare const BEFORE_CALL_RECOVERY_DIRNAME = "before-call-recovery";
+export interface RetainedOriginal {
+    /** Content-free recovery id (random; never derived from content). */
+    recoveryId: string;
+    /** Absolute path to the local-only artifact holding the original prompt. */
+    recoveryPath: string;
+    /** A content-safe pointer suitable for the activity event (id + path — NEVER the prompt text). */
+    pointer: string;
+}
+/**
+ * Retain `original` locally and return a content-safe pointer. Throws if the artifact cannot be
+ * written — the caller treats a throw as "retention failed → do NOT apply, run the original unchanged".
+ * `idFactory` is injectable for deterministic tests; production uses a random UUID.
+ */
+export declare function retainOriginalPrompt(original: string, opts?: {
+    cwd?: string;
+    idFactory?: () => string;
+}): RetainedOriginal;

package/dist/core/before-call-recovery.js

@@ -0,0 +1,46 @@
+/**
+ * LOCAL-ONLY original-prompt retention for an APPROVED before-call mutation (PUBLIC CLI/SDK code —
+ * engine-free). Charter 2026-07-04-run-11 (founder SAFETY decision: "Original retention +
+ * recoverability").
+ *
+ * When — and ONLY when — the operator explicitly approves a whitelist-safe before-call compaction, the
+ * ORIGINAL prompt must remain recoverable. This module writes the original to a LOCAL-ONLY artifact
+ * under `<cwd>/.compaction/before-call-recovery/<id>` and returns a CONTENT-SAFE pointer (the id + the
+ * path). The rails (binding):
+ * - `.compaction/` is gitignored → the artifact is NEVER committed, NEVER uploaded, NEVER synced.
+ * - The recovery id is CONTENT-FREE (random, never derived from the prompt) so the pointer that rides
+ *   on the activity event leaks nothing about the content.
+ * - ONLY this file holds the prompt text. The caller puts the POINTER (not the text) on the activity
+ *   event. The prompt text is never logged.
+ * - If retention cannot be completed for ANY reason, the caller MUST NOT apply the mutation (it runs
+ *   the original command unchanged) — an un-recoverable mutation is never performed.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+/** The gitignored subtree that holds retained originals (local-only). */
+export const BEFORE_CALL_RECOVERY_DIRNAME = "before-call-recovery";
+function recoveryDir(cwd) {
+    return path.join(cwd, ".compaction", BEFORE_CALL_RECOVERY_DIRNAME);
+}
+/**
+ * Retain `original` locally and return a content-safe pointer. Throws if the artifact cannot be
+ * written — the caller treats a throw as "retention failed → do NOT apply, run the original unchanged".
+ * `idFactory` is injectable for deterministic tests; production uses a random UUID.
+ */
+export function retainOriginalPrompt(original, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const recoveryId = (opts.idFactory ?? randomUUID)();
+    const dir = recoveryDir(cwd);
+    mkdirSync(dir, { recursive: true });
+    const recoveryPath = path.join(dir, `${recoveryId}.txt`);
+    // The ORIGINAL prompt text lives ONLY here (local-only, gitignored). Never logged, never uploaded.
+    writeFileSync(recoveryPath, original, "utf8");
+    return {
+        recoveryId,
+        recoveryPath,
+        // Content-safe: id + path only. This is what may ride on the (content-free) activity event.
+        pointer: `before-call-recovery:${recoveryId}`
+    };
+}
+//# sourceMappingURL=before-call-recovery.js.map

package/dist/core/before-call-stdin.d.ts

@@ -0,0 +1,59 @@
+/**
+ * BEFORE-CALL STDIN-BOUNDARY apply PLANNER (PUBLIC CLI/SDK code — engine-free, ships in the npm
+ * package). Charter 2026-07-04-run-12 — the FIRST real before-call mutation surface.
+ *
+ * Run-11 proved the argv route is blocked (Codex + Cursor take bare positional prompts; no value-taking
+ * prompt flag to rewrite). Run-12 uses the OTHER boundary the founder named: stdin. Codex `exec`
+ * documents a first-class stdin prompt path ("if not provided as an argument (or if `-` is used),
+ * instructions are read from stdin"), so when the invocation is `codex exec [flags]` with NO positional
+ * prompt (or a lone `-`), the WHOLE stdin stream IS the prompt — an explicit, unambiguous boundary.
+ *
+ * This module is a PURE decision planner: given the argv, the buffered stdin content, whether a terminal
+ * is available to ask on, and an injectable `decide` callback (the `[y/n/v]` approval), it returns what
+ * the shim should feed the real tool (`compacted` or the `original` stdin) plus the honest activity
+ * outcome. It performs NO terminal I/O, NO file I/O, and NO retention — the command wraps those so the
+ * fail-closed retention rule ("if the original cannot be retained, do NOT apply") stays enforced in one
+ * place and this planner stays trivially testable.
+ *
+ * FAIL-CLOSED (binding): the plan emits `compacted` ONLY when the stdin boundary is provably safe (Codex
+ * `exec`, stdin is the sole prompt), there is avoidable context, a terminal is available, AND `decide`
+ * returns `"apply"`. Every other path emits the ORIGINAL stdin unchanged. No auto-apply, no default yes.
+ */
+import { type BeforeCallRecommendation, type BeforeCallTool, type StdinPromptBoundary } from "./before-call.js";
+import type { ActivityApprovalStatus } from "./activity-event.js";
+/** The approval decision the planner asks for (kept local to avoid a cycle with the precall command). */
+export type StdinApplyChoice = "apply" | "decline";
+export interface StdinApplyPlan {
+    /** The stdin-boundary safety result (Codex `exec`, stdin is the sole prompt → safe). */
+    boundary: StdinPromptBoundary;
+    /** The content-free recommendation — present ONLY when the boundary was safe (so stdin was analyzed). */
+    recommendation?: BeforeCallRecommendation;
+    /** What the shim should feed the real tool. `compacted` ONLY after an explicit approval. */
+    emit: "compacted" | "original";
+    /** The compacted stdin — present ONLY when `emit === "compacted"`. Never persisted to activity. */
+    compacted?: string;
+    /** Honest approval outcome for the activity event. */
+    approvalStatus: ActivityApprovalStatus;
+    /** True ONLY for an operator-approved compaction that will be applied to this call. */
+    applied: boolean;
+    /** Content-free reason apply was not offered/available (for the honest not-asked arm). */
+    notAvailableReason?: string;
+    /** Whether the caller should record ONE activity event (true only when there is something honest to log). */
+    record: boolean;
+}
+/**
+ * Plan the stdin-boundary before-call apply decision (charter run-12). Pure + fully injectable:
+ * - `interactive` is TRUE only when a terminal is available to ask on (the shim passes `[ -t 1 ]`;
+ *   stdin is intentionally piped here, so interactivity is about the terminal, not stdin).
+ * - `decide(rec)` runs the `[y/n/v]` approval (the command drives it over `/dev/tty`; tests inject it).
+ *
+ * The planner NEVER applies without a safe boundary + avoidable context + a terminal + an explicit
+ * `"apply"`. Retention of the original is the COMMAND's responsibility (fail-closed if it fails).
+ */
+export declare function planStdinApply(params: {
+    tool: BeforeCallTool;
+    argv: string[];
+    stdinContent: string;
+    interactive: boolean;
+    decide: (rec: BeforeCallRecommendation) => StdinApplyChoice;
+}): StdinApplyPlan;

package/dist/core/before-call-stdin.js

@@ -0,0 +1,78 @@
+/**
+ * BEFORE-CALL STDIN-BOUNDARY apply PLANNER (PUBLIC CLI/SDK code — engine-free, ships in the npm
+ * package). Charter 2026-07-04-run-12 — the FIRST real before-call mutation surface.
+ *
+ * Run-11 proved the argv route is blocked (Codex + Cursor take bare positional prompts; no value-taking
+ * prompt flag to rewrite). Run-12 uses the OTHER boundary the founder named: stdin. Codex `exec`
+ * documents a first-class stdin prompt path ("if not provided as an argument (or if `-` is used),
+ * instructions are read from stdin"), so when the invocation is `codex exec [flags]` with NO positional
+ * prompt (or a lone `-`), the WHOLE stdin stream IS the prompt — an explicit, unambiguous boundary.
+ *
+ * This module is a PURE decision planner: given the argv, the buffered stdin content, whether a terminal
+ * is available to ask on, and an injectable `decide` callback (the `[y/n/v]` approval), it returns what
+ * the shim should feed the real tool (`compacted` or the `original` stdin) plus the honest activity
+ * outcome. It performs NO terminal I/O, NO file I/O, and NO retention — the command wraps those so the
+ * fail-closed retention rule ("if the original cannot be retained, do NOT apply") stays enforced in one
+ * place and this planner stays trivially testable.
+ *
+ * FAIL-CLOSED (binding): the plan emits `compacted` ONLY when the stdin boundary is provably safe (Codex
+ * `exec`, stdin is the sole prompt), there is avoidable context, a terminal is available, AND `decide`
+ * returns `"apply"`. Every other path emits the ORIGINAL stdin unchanged. No auto-apply, no default yes.
+ */
+import { analyzeBeforeCall, resolveStdinPromptBoundary } from "./before-call.js";
+/**
+ * Plan the stdin-boundary before-call apply decision (charter run-12). Pure + fully injectable:
+ * - `interactive` is TRUE only when a terminal is available to ask on (the shim passes `[ -t 1 ]`;
+ *   stdin is intentionally piped here, so interactivity is about the terminal, not stdin).
+ * - `decide(rec)` runs the `[y/n/v]` approval (the command drives it over `/dev/tty`; tests inject it).
+ *
+ * The planner NEVER applies without a safe boundary + avoidable context + a terminal + an explicit
+ * `"apply"`. Retention of the original is the COMMAND's responsibility (fail-closed if it fails).
+ */
+export function planStdinApply(params) {
+    const { tool, argv, stdinContent, interactive, decide } = params;
+    const boundary = resolveStdinPromptBoundary(tool, argv);
+    if (!boundary.safe) {
+        // stdin is NOT provably the whole prompt → recommendation-only for this invocation; feed the ORIGINAL
+        // stdin unchanged. We do NOT analyze stdin (it may not be the prompt) → nothing honest to log.
+        return {
+            boundary,
+            emit: "original",
+            approvalStatus: "not-asked",
+            applied: false,
+            notAvailableReason: boundary.reason,
+            record: false
+        };
+    }
+    const recommendation = analyzeBeforeCall(tool, stdinContent);
+    if (!recommendation.has_avoidable_context) {
+        // Honest no-op: stdin carries no avoidable duplicated context. Feed the original; no activity noise.
+        return { boundary, recommendation, emit: "original", approvalStatus: "not-required", applied: false, record: false };
+    }
+    if (!interactive) {
+        // Avoidable context exists, but there is no terminal to ask on → NEVER apply without approval.
+        return {
+            boundary,
+            recommendation,
+            emit: "original",
+            approvalStatus: "not-asked",
+            applied: false,
+            notAvailableReason: "no interactive terminal to ask on — apply not offered (fail-closed to the original stdin)",
+            record: true
+        };
+    }
+    const choice = decide(recommendation);
+    if (choice === "apply") {
+        return {
+            boundary,
+            recommendation,
+            emit: "compacted",
+            compacted: recommendation.compacted_input,
+            approvalStatus: "asked-approved",
+            applied: true,
+            record: true
+        };
+    }
+    return { boundary, recommendation, emit: "original", approvalStatus: "asked-declined", applied: false, record: true };
+}
+//# sourceMappingURL=before-call-stdin.js.map