@compaction/cli 0.2.0 → 0.3.1

package/dist/core/shim-capture-bridge.js

@@ -0,0 +1,88 @@
+/**
+ * Shim → metrics-only activity BRIDGE (PUBLIC CLI/SDK code — engine-free, ships in the npm package).
+ *
+ * This is the exact analogue of the run-8 from-hook → activity bridge (`appendClaudeCodeHookActivity`
+ * in `src/cli/commands/capture-claude-code.ts`), reused verbatim in shape for the Codex/Cursor PATH
+ * shims (charter 2026-07-04-run-9): parse CONTENT-FREE usage → build the honest per-field token report
+ * → build the cross-surface event → wrap as a measure-only activity event → append ONE line to the
+ * local activity store. THIS is what makes a subsequent `codex exec --json` / `cursor-agent …
+ * --output-format json` run appear in `compaction activity` with NO manual import.
+ *
+ * Honesty (identical rails to the reused parsers/validators):
+ * - Codex: provider-reported tokens from `turn.completed.usage` when present, else
+ *   unavailable-with-reason — never invented, never a silent zero.
+ * - Cursor: LOCAL-ESTIMATE only (chars/4); NEVER provider-reported; output unavailable-with-reason
+ *   when the `result` field is not separable. The cross-surface tier table structurally rejects a
+ *   provider-reported label on the `cursor` surface.
+ * - CONTENT-FREE: only token COUNTS + honest source labels + opaque ids ride on the event. No
+ *   prompt/response/message text is ever read into the event (the raw output is parsed for usage
+ *   fields only, and for Cursor the prompt is counted, never stored).
+ * - Measurement only: approval "not-required", auto-apply OFF (not eligible, ask-each-time,
+ *   applied_automatically false), recovery original_retained=false, sync "local-only".
+ * - Deterministic id → the store DEDUPES a re-parse of the same run (same state = one event).
+ */
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { normalizeCodexExecEvents, CODEX_UNKNOWN_MODEL } from "./codex-capture.js";
+import { normalizeCursorAgentOutput } from "./cursor-capture.js";
+import { buildRunFlowTokenReport } from "./run-flow-report.js";
+import { buildRunCrossSurfaceEvent } from "./cross-surface-event.js";
+import { buildMeasureOnlyActivityEvent } from "./activity-event.js";
+import { appendActivityEvent, DEFAULT_ACTIVITY_DIRECTORY } from "./activity-store.js";
+/** A content-free, deterministic run id from opaque ids + token counts (never any content). */
+function contentFreeRunId(prefix, parts) {
+    const digest = createHash("sha256").update(parts.map((p) => String(p ?? "")).join("|")).digest("hex");
+    return `${prefix}-${digest.slice(0, 16)}`;
+}
+/** The activity directory under a given cwd (mirrors the from-hook bridge: cwd-scoped). */
+function activityDirFor(cwd) {
+    return cwd ? path.join(cwd, ".compaction", "activity") : DEFAULT_ACTIVITY_DIRECTORY;
+}
+const CODEX_MISSING_USAGE_REASON = "the captured codex exec output carried no turn.completed.usage block (provider usage unavailable — not invented)";
+/**
+ * Bridge a captured `codex exec --json` output copy into ONE metrics-only activity event.
+ * `surface: "codex"`, `provider: "openai"`; provider-reported tokens where usage existed, else
+ * unavailable-with-reason. Content-free + best-effort: a local failure is returned as an unappended
+ * result, never thrown, so it can never break the transparent shim.
+ */
+export async function bridgeCodexShimActivity(input) {
+    const norm = normalizeCodexExecEvents({ captureId: "shim", rawOutput: input.rawOutput });
+    const usage = norm.usageMetadata;
+    const present = norm.tokenMetadataStatus === "present";
+    const tokenReport = buildRunFlowTokenReport({ tool: "codex", usage, outputStatus: present ? "present" : "unavailable" });
+    const threadId = norm.trace.id && !norm.trace.id.startsWith("trace_codex_") ? norm.trace.id : undefined;
+    const runId = contentFreeRunId("codex-shim", [threadId, usage.input_tokens, usage.output_tokens, usage.cache_read_input_tokens]);
+    const event = buildRunCrossSurfaceEvent("codex", {
+        runId,
+        tokenReport,
+        reasons: present ? {} : { input: CODEX_MISSING_USAGE_REASON, output: CODEX_MISSING_USAGE_REASON },
+        ...(usage.model && usage.model !== CODEX_UNKNOWN_MODEL ? { modelLabel: usage.model } : {})
+    });
+    const eventWithSession = threadId ? { ...event, session_id: threadId } : event;
+    const activityEvent = buildMeasureOnlyActivityEvent(eventWithSession, { original_retained: false });
+    const result = await appendActivityEvent(activityEvent, activityDirFor(input.cwd));
+    return { result, tokenMetadataStatus: norm.tokenMetadataStatus };
+}
+/**
+ * Bridge a captured Cursor headless output copy into ONE metrics-only activity event.
+ * `surface: "cursor"`, `provider: "cursor"`; LOCAL-ESTIMATE only (NEVER provider-reported), output
+ * unavailable-with-reason when the result is not separable. `commandParts` (the ORIGINAL invocation)
+ * lets input be locally estimated from the prompt (counted, never stored). Content-free, best-effort.
+ */
+export async function bridgeCursorShimActivity(input) {
+    const norm = normalizeCursorAgentOutput({ captureId: "shim", rawOutput: input.rawOutput, commandParts: input.commandParts });
+    const usage = norm.usageMetadata;
+    const tokenReport = buildRunFlowTokenReport({ tool: "cursor", usage, outputStatus: norm.outputStatus });
+    const sessionId = norm.trace.id && !norm.trace.id.startsWith("trace_cursor_") ? norm.trace.id : undefined;
+    const runId = contentFreeRunId("cursor-shim", [sessionId, usage.input_tokens, usage.output_tokens]);
+    const event = buildRunCrossSurfaceEvent("cursor", {
+        runId,
+        tokenReport,
+        reasons: { input: norm.inputUnavailableReason, output: norm.outputUnavailableReason }
+    });
+    const eventWithSession = sessionId ? { ...event, session_id: sessionId } : event;
+    const activityEvent = buildMeasureOnlyActivityEvent(eventWithSession, { original_retained: false });
+    const result = await appendActivityEvent(activityEvent, activityDirFor(input.cwd));
+    return { result, inputStatus: norm.inputStatus, outputStatus: norm.outputStatus };
+}
+//# sourceMappingURL=shim-capture-bridge.js.map

package/dist/core/skill-injection-policy.d.ts

@@ -0,0 +1,72 @@
+import { SKILL_INJECTION_POLICY_NAME, type PolicyMiddlewareStateCapsule, type SkillInjectionProvenance } from "./policy-types.js";
+import type { AgentTrace, StateCapsule, TraceMessage } from "./types.js";
+export { SKILL_INJECTION_POLICY_NAME };
+export type { SkillInjectionProvenance };
+/**
+ * APPROVAL-REQUIRED rung of the role:user skill-injection compaction policy.
+ *
+ * SCOPE (per docs/design/skill-injection-compaction-policy.md §1–§5, approval-required rung):
+ * This module builds the byte-identical, same-skill `role:user` skill-injection compaction
+ * candidates and their state capsules. It is the SECOND, separately-named compaction policy
+ * (`repeated_skill_injection_to_state_capsule`). It NEVER runs by default: `applyCompactionPolicy`
+ * only invokes it when `compactSkillInjections === true`, which is set ONLY on explicit approval
+ * in the existing approve/apply loop (optimization-approval.ts). There is NO auto-apply path.
+ *
+ * Byte-identical-only boundary (design §2): the dedup key is the report-only detector's exact
+ * `skill:normalizeExactContent(content)` key. Near-identical (same skill, divergent trailing
+ * `ARGUMENTS:`) produces a DIFFERENT key and can NEVER be compacted. No prefix/fuzzy matching.
+ *
+ * Provenance (design §5 / Q2): the capture step prefixes SUBAGENT message ids `<agentId>-<uuid>`,
+ * but ROOT-agent injections carry a bare UUID (no encoded agent id). So every compacted skill
+ * injection's capsule carries an ADDITIVE `skillInjectionProvenance` field recording the owning
+ * agent id (parsed from the id prefix, or "root" when absent) AND the replaced copy's trace
+ * position — so a consumer can reconstruct per-agent / per-position receipt even for the bare-UUID
+ * root copies. This is additive metadata on the capsule; it does NOT change the AgentTrace /
+ * TraceSource / TraceMessage schema.
+ */
+/**
+ * A skill-injection compaction candidate: a later byte-identical copy to be replaced by a
+ * `whole_message` state capsule pointing at the FIRST copy of its `skill:exactContent` group.
+ */
+export interface SkillInjectionCompactionCandidate {
+    skillName: string;
+    firstCopyMessage: TraceMessage;
+    firstCopyIndex: number;
+    replacedMessage: TraceMessage;
+    replacedIndex: number;
+    replacedTokens: number;
+}
+/**
+ * Recover the owning agent id of a captured message. Subagent message ids are prefixed
+ * `<agentId>-<uuid>` by the claude-code adapter; root-agent ids are bare UUIDs (no prefix).
+ * Returns "root" with recovered=false when no agent prefix is present.
+ */
+export declare function owningAgentIdForMessage(message: TraceMessage): {
+    owningAgentId: string;
+    recoveredFromPrefix: boolean;
+};
+/**
+ * Find byte-identical, same-skill later skill-injection copies (design §1/§2). First occurrence
+ * of each `skill:exactContent` group is retained; each later exact-key copy is a candidate.
+ * Pure: returns candidates; never mutates the trace.
+ */
+export declare function findSkillInjectionCompactionCandidates(trace: AgentTrace): SkillInjectionCompactionCandidate[];
+/**
+ * Build `whole_message` state capsules for skill-injection candidates, mirroring the tool-output
+ * policy's capsule shape (`PolicyMiddlewareStateCapsule`) and reusing the same SourcePointer /
+ * provenance machinery. Each capsule additionally carries the §5 `skillInjectionProvenance`.
+ */
+export declare function createSkillInjectionCapsules(trace: AgentTrace, candidates: SkillInjectionCompactionCandidate[], baseCapsule: Pick<StateCapsule, "retainedFacts" | "openQuestions" | "safetyNotes">, idOffset?: number): PolicyMiddlewareStateCapsule[];
+/**
+ * Rollback / recovery (design §Q5): re-expand a skill-injection capsule's first-copy pointer to
+ * restore the original later-copy content. Because the bytes are byte-identical by construction,
+ * the restored content equals the retained first copy. Returns the restored content, or null when
+ * the pointer no longer resolves (which a safety check would already have failed).
+ */
+export declare function restoreCompactedSkillInjectionContent(originalTrace: AgentTrace, capsule: PolicyMiddlewareStateCapsule): string | null;
+/**
+ * Round-trip rollback (design §Q5): given the compacted messages and the skill-injection capsules,
+ * restore the ORIGINAL trace messages by re-expanding each capsule pointer back to the first-copy
+ * bytes. Asserts byte-for-byte recovery of the later copies. Pure; returns a restored message list.
+ */
+export declare function rollbackSkillInjectionCompaction(originalTrace: AgentTrace, compactedMessages: TraceMessage[], capsules: PolicyMiddlewareStateCapsule[]): TraceMessage[];

package/dist/core/skill-injection-policy.js

@@ -0,0 +1,183 @@
+import { contentHash } from "./content-hash.js";
+import { estimateTextTokens } from "./token-estimator.js";
+import { isSkillInjection, parseSkillName } from "./skill-injection-detector.js";
+import { SKILL_INJECTION_POLICY_NAME } from "./policy-types.js";
+// Re-export the public policy-name + provenance type (now owned by ./policy-types.js) so existing
+// consumers that import them from this module keep working unchanged.
+export { SKILL_INJECTION_POLICY_NAME };
+/**
+ * Mirrors the report-only detector's normalization (trailing whitespace only). Internal
+ * whitespace is preserved so near-identical bodies produce DIFFERENT keys. This MUST match
+ * skill-injection-detector.ts `normalizeExactContent` exactly — the same hard safety boundary.
+ */
+function normalizeExactContent(content) {
+    return content.replace(/\s+$/, "");
+}
+/**
+ * Recover the owning agent id of a captured message. Subagent message ids are prefixed
+ * `<agentId>-<uuid>` by the claude-code adapter; root-agent ids are bare UUIDs (no prefix).
+ * Returns "root" with recovered=false when no agent prefix is present.
+ */
+export function owningAgentIdForMessage(message) {
+    // A bare UUID has the canonical 8-4-4-4-12 hex form. Anything with an extra leading
+    // `<prefix>-` segment before a trailing UUID is a subagent-prefixed id.
+    const uuid = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+    const bareUuid = new RegExp(`^${uuid}$`);
+    if (bareUuid.test(message.id)) {
+        return { owningAgentId: "root", recoveredFromPrefix: false };
+    }
+    const prefixed = message.id.match(new RegExp(`^(.+)-${uuid}$`));
+    if (prefixed) {
+        return { owningAgentId: prefixed[1], recoveredFromPrefix: true };
+    }
+    // Non-UUID id forms (e.g. test fixtures or `<session>-<n>` ids): not an agent-encoded id.
+    return { owningAgentId: "root", recoveredFromPrefix: false };
+}
+/**
+ * Find byte-identical, same-skill later skill-injection copies (design §1/§2). First occurrence
+ * of each `skill:exactContent` group is retained; each later exact-key copy is a candidate.
+ * Pure: returns candidates; never mutates the trace.
+ */
+export function findSkillInjectionCompactionCandidates(trace) {
+    const candidates = [];
+    const firstByKey = new Map();
+    trace.messages.forEach((message, index) => {
+        if (!isSkillInjection(message)) {
+            return;
+        }
+        const skillName = parseSkillName(message.content);
+        if (skillName === null) {
+            return;
+        }
+        const key = `${skillName}:${normalizeExactContent(message.content)}`;
+        const first = firstByKey.get(key);
+        if (!first) {
+            firstByKey.set(key, { message, index });
+            return;
+        }
+        candidates.push({
+            skillName,
+            firstCopyMessage: first.message,
+            firstCopyIndex: first.index,
+            replacedMessage: message,
+            replacedIndex: index,
+            replacedTokens: estimateTextTokens(message.content)
+        });
+    });
+    return candidates;
+}
+function sourceExcerptPreview(content) {
+    const normalized = content.trim().replace(/\s+/g, " ");
+    return normalized.length > 160 ? `${normalized.slice(0, 157)}...` : normalized;
+}
+function createSourcePointer(trace, message, messageIndex) {
+    return {
+        traceId: trace.id,
+        messageId: message.id,
+        messageIndex,
+        contentSha256: contentHash(message.content)
+    };
+}
+function createCapsuleText(skillName, sourcePointer, replacedTokens) {
+    return [
+        `[state capsule: ${SKILL_INJECTION_POLICY_NAME}]`,
+        `A byte-identical repeat of the ${skillName} skill injection was compacted before this model call.`,
+        `First-copy pointer: trace=${sourcePointer.traceId} message=${sourcePointer.messageId} index=${sourcePointer.messageIndex} sha256=${sourcePointer.contentSha256}.`,
+        `The original instruction body is byte-identical to the first copy and is retained locally at that pointer for audit and replay.`,
+        `Estimated raw duplicate input tokens replaced: ${replacedTokens}.`
+    ].join("\n");
+}
+/**
+ * Build `whole_message` state capsules for skill-injection candidates, mirroring the tool-output
+ * policy's capsule shape (`PolicyMiddlewareStateCapsule`) and reusing the same SourcePointer /
+ * provenance machinery. Each capsule additionally carries the §5 `skillInjectionProvenance`.
+ */
+export function createSkillInjectionCapsules(trace, candidates, baseCapsule, idOffset = 0) {
+    return candidates.map((candidate, index) => {
+        const sourcePointer = createSourcePointer(trace, candidate.firstCopyMessage, candidate.firstCopyIndex);
+        const owning = owningAgentIdForMessage(candidate.replacedMessage);
+        const provenance = {
+            skillName: candidate.skillName,
+            owningAgentId: owning.owningAgentId,
+            owningAgentIdRecoveredFromPrefix: owning.recoveredFromPrefix,
+            replacedMessagePosition: candidate.replacedIndex,
+            replacedMessageId: candidate.replacedMessage.id,
+            firstCopyPosition: candidate.firstCopyIndex,
+            firstCopyMessageId: candidate.firstCopyMessage.id
+        };
+        const capsule = {
+            id: `skill_injection_capsule_${idOffset + index + 1}`,
+            // The capsule's policyName is the SECOND policy name. The shared type widens to a
+            // string union via SupportedCompactionPolicyName (see policy-middleware.ts).
+            policyName: SKILL_INJECTION_POLICY_NAME,
+            traceId: trace.id,
+            sourcePointer,
+            compactedMessageIds: [candidate.replacedMessage.id],
+            replacementMode: "whole_message",
+            sourceExcerptPreview: sourceExcerptPreview(candidate.firstCopyMessage.content),
+            originalPayloadTokenCount: estimateTextTokens(candidate.firstCopyMessage.content),
+            text: createCapsuleText(candidate.skillName, sourcePointer, candidate.replacedTokens),
+            retainedFacts: baseCapsule.retainedFacts,
+            openQuestions: baseCapsule.openQuestions,
+            safetyNotes: [
+                ...baseCapsule.safetyNotes,
+                `Byte-identical ${candidate.skillName} skill injection ${candidate.replacedMessage.id} (position ${candidate.replacedIndex}, owning agent ${provenance.owningAgentId}) replaced with a state capsule pointing at first copy ${candidate.firstCopyMessage.id}.`
+            ],
+            skillInjectionProvenance: provenance
+        };
+        return capsule;
+    });
+}
+/**
+ * Rollback / recovery (design §Q5): re-expand a skill-injection capsule's first-copy pointer to
+ * restore the original later-copy content. Because the bytes are byte-identical by construction,
+ * the restored content equals the retained first copy. Returns the restored content, or null when
+ * the pointer no longer resolves (which a safety check would already have failed).
+ */
+export function restoreCompactedSkillInjectionContent(originalTrace, capsule) {
+    const pointer = capsule.sourcePointer;
+    const atIndex = originalTrace.messages[pointer.messageIndex];
+    const firstCopy = atIndex?.id === pointer.messageId
+        ? atIndex
+        : originalTrace.messages.find((message) => message.id === pointer.messageId);
+    if (!firstCopy) {
+        return null;
+    }
+    if (contentHash(firstCopy.content) !== pointer.contentSha256) {
+        return null;
+    }
+    return firstCopy.content;
+}
+/**
+ * Round-trip rollback (design §Q5): given the compacted messages and the skill-injection capsules,
+ * restore the ORIGINAL trace messages by re-expanding each capsule pointer back to the first-copy
+ * bytes. Asserts byte-for-byte recovery of the later copies. Pure; returns a restored message list.
+ */
+export function rollbackSkillInjectionCompaction(originalTrace, compactedMessages, capsules) {
+    const restoredById = new Map();
+    for (const capsule of capsules) {
+        const restored = restoreCompactedSkillInjectionContent(originalTrace, capsule);
+        if (restored === null) {
+            continue;
+        }
+        for (const compactedId of capsule.compactedMessageIds) {
+            restoredById.set(compactedId, restored);
+        }
+    }
+    return compactedMessages.map((message) => {
+        const restored = restoredById.get(message.id);
+        if (restored === undefined) {
+            return message;
+        }
+        const metadata = message.metadata ? { ...message.metadata } : undefined;
+        if (metadata && "compaction" in metadata) {
+            delete metadata.compaction;
+        }
+        return {
+            ...message,
+            content: restored,
+            metadata: metadata && Object.keys(metadata).length > 0 ? metadata : undefined
+        };
+    });
+}
+//# sourceMappingURL=skill-injection-policy.js.map

package/dist/core/spend-attribution.js

@@ -39,7 +39,7 @@ function unavailableOptimizationDelta() {
 export async function loadEngineOptimizationDeltaProvider() {
     try {
         const [{ applyCompactionPolicy }, { createRecommendation }, { createSafetyReport }] = await Promise.all([
-            import("../engine/policy-middleware.js"),
+            import("./policy-middleware.js"),
             import("../engine/recommendation.js"),
             import("./safety-report.js")
         ]);

package/dist/core/token-accounting.d.ts

@@ -1,4 +1,4 @@
-import type { PolicyMiddlewareResult } from "../engine/policy-middleware.js";
+import type { PolicyMiddlewareResult } from "./policy-middleware.js";
 import type { AgentTrace } from "./types.js";
 /**
  * Token & cost accounting surface (Strong-MVP Track D).

package/dist/core/tool-shim.d.ts

@@ -0,0 +1,129 @@
+/** The tools this run can shim. `cursor` installs a shim named `cursor-agent` (the installed binary). */
+export type ShimTool = "codex" | "cursor";
+/** Per-tool shim config: the on-disk shim name, the capture surface, and the measurable-form detector. */
+interface ShimToolConfig {
+    /** The executable name the shim must masquerade as (what the user actually types / PATH resolves). */
+    shimName: string;
+    /** The `compaction capture <captureTool> --from-shim` subcommand the shim calls (content-free). */
+    captureTool: "codex" | "cursor";
+    /** Whether the shim forwards the ORIGINAL args to the capture bridge (Cursor needs them for the
+     *  local-estimate INPUT count; Codex reads usage from output alone, so it does not). */
+    forwardArgs: boolean;
+}
+export declare const SHIM_TOOLS: Readonly<Record<ShimTool, ShimToolConfig>>;
+/** Marker line embedded in every generated shim: how verify + uninstall confirm the file is OURS. */
+export declare const SHIM_MARKER = "COMPACTION_SHIM";
+export interface ShimEnv {
+    COMPACTION_SHIM_DIR?: string;
+    COMPACTION_HOME?: string;
+    HOME?: string;
+    PATH?: string;
+    SHELL?: string;
+}
+/** The Compaction home directory: `COMPACTION_HOME` or `<home>/.compaction`. */
+export declare function resolveCompactionHome(env?: ShimEnv): string;
+/** The Compaction-owned shim directory: `COMPACTION_SHIM_DIR`, else `<compaction-home>/shims`. */
+export declare function resolveShimDir(env?: ShimEnv): string;
+export declare function shimPathFor(tool: ShimTool, env?: ShimEnv): string;
+/**
+ * First executable named `name` on `PATH`, skipping any directory in `excludeDirs` (the shim dir).
+ * Returns the absolute path or `undefined`. Used at INSTALL time to record the real binary before the
+ * shim can shadow it, and to detect "tool not installed" (never shim a command that does not exist).
+ */
+export declare function resolveExecutableOnPath(name: string, env?: ShimEnv, excludeDirs?: string[]): string | undefined;
+/**
+ * Generate the transparent capturing shim script for `tool`, baking in the resolved absolute
+ * `realBin` path. The script: (1) execs the real binary with all args + inherited stdio + preserved
+ * exit code; (2) for the measurable batch form ONLY, runs a FAIL-OPEN, CONTENT-FREE before-call
+ * recommendation step (`compaction precall`; recommendation-only — it never mutates the input), then
+ * tees stdout to a temp copy and calls the content-free capture bridge, then deletes the temp;
+ * (3) passes everything else through untouched.
+ */
+export declare function generateShimScript(tool: ShimTool, realBin: string): string;
+/** Does the file at `shimPath` look like a Compaction shim (marker present)? Content-free identity. */
+export declare function fileIsCompactionShim(shimPath: string): boolean;
+export interface ShimVerification {
+    tool: ShimTool;
+    /** The path the shim WOULD live at. */
+    shimPath: string;
+    /** Whether the shim FILE exists on disk (installed), independent of PATH. */
+    installed: boolean;
+    /** What the shim NAME resolves to on the CURRENT PATH (first match), or undefined. */
+    resolvedPath?: string;
+    /** TRUE only when the shim name resolves to OUR shim file on PATH — the sole basis for "active". */
+    onPath: boolean;
+    /** TRUE only when installed AND resolves to our shim on PATH. NEVER claim connected without this. */
+    active: boolean;
+    /** The exact one line to prepend to PATH to activate the shim (shown when not-yet-active). */
+    exportLine: string;
+    /** The shim directory. */
+    shimDir: string;
+}
+/** The exact PATH line the user adds (or `--write-shell-config` appends) to activate the shim dir. */
+export declare function shimExportLine(env?: ShimEnv): string;
+/**
+ * Resolve-verify whether the shim for `tool` is ACTIVE: the shim file exists AND the tool name
+ * resolves to that shim on the current PATH (the shim dir is on PATH ahead of the real binary).
+ */
+export declare function verifyShimActive(tool: ShimTool, env?: ShimEnv): ShimVerification;
+export type InstallShimStatus = "installed-active" | "installed-not-on-path" | "already-active" | "no-real-binary" | "verify-failed";
+export interface InstallShimResult {
+    tool: ShimTool;
+    status: InstallShimStatus;
+    shimName: string;
+    shimDir: string;
+    shimPath: string;
+    /** The absolute real-binary path recorded in the shim (present unless status is no-real-binary). */
+    realBin?: string;
+    /** The resolve-verification AFTER install. */
+    verification: ShimVerification;
+    /** The exact PATH line to add when not-yet-active. */
+    exportLine: string;
+}
+export interface InstallShimOptions {
+    now?: () => string;
+}
+/**
+ * Install the shim for `tool`: resolve the real binary (excluding our shim dir so it can never point
+ * at itself), write the shim script + a real-path record, then RE-READ the shim file to confirm it
+ * landed with the marker and the recorded real path, and finally resolve-verify PATH activation. The
+ * caller may only present "connected" for `installed-active` / `already-active` — never for
+ * `installed-not-on-path` (print the export line) or `verify-failed` (nothing is claimed).
+ */
+export declare function installToolShim(tool: ShimTool, env?: ShimEnv, options?: InstallShimOptions): InstallShimResult;
+export type UninstallShimStatus = "removed" | "not-installed";
+export interface UninstallShimResult {
+    tool: ShimTool;
+    status: UninstallShimStatus;
+    shimPath: string;
+    /** Whether a shell-rc backup was restored (see `removeShellConfigPathLine`). */
+    shellConfigRestored?: string;
+}
+/** Remove the shim file + its record entry (reversible: the real binary was never touched). */
+export declare function uninstallToolShim(tool: ShimTool, env?: ShimEnv): UninstallShimResult;
+/** Pick the user's shell rc file from $SHELL (zsh → ~/.zshrc, else ~/.bashrc). Content-free. */
+export declare function resolveShellRcPath(env?: ShimEnv): string;
+export interface WriteShellConfigResult {
+    status: "appended" | "already-present" | "no-rc-file-created";
+    rcPath: string;
+    backupPath?: string;
+    exportLine: string;
+}
+/**
+ * Append the shim PATH line to the user's shell rc — ONLY when the caller passes an explicit
+ * `--write-shell-config` gesture. A `.compaction.bak` backup is written FIRST (reversible), the block
+ * is clearly marked, and the append is idempotent (already-present → no change). Never overwrites.
+ */
+export declare function writeShellConfigPathLine(env?: ShimEnv): WriteShellConfigResult;
+export interface RemoveShellConfigResult {
+    status: "removed" | "not-present" | "no-rc-file";
+    rcPath: string;
+    backupRestored?: string;
+}
+/**
+ * Reverse `writeShellConfigPathLine`: strip the marked block from the rc file. If a
+ * `.compaction.bak` backup exists it is restored verbatim (the fully reversible path); otherwise the
+ * marked block is removed in place.
+ */
+export declare function removeShellConfigPathLine(env?: ShimEnv): RemoveShellConfigResult;
+export {};