instar 1.3.1350 → 1.3.1351

package/dist/core/ClaudeBinaryRetainer.d.ts

@@ -0,0 +1,186 @@
+export interface RetainedClaudeBinaryConfig {
+    /** Off switch. Absent = ON (the leak is the default-on failure). */
+    enabled?: boolean;
+    /** Directory holding `<version>/claude`. Default: `<projectDir>/.instar/state/claude-bin`. */
+    dir?: string;
+    /**
+     * A non-current version directory is a prune candidate only once it has
+     * not been used to launch anything for this long (default 6 h). This covers
+     * the window between "resolve picked a path" and "the process exec'd it".
+     */
+    pruneGraceMs?: number;
+}
+export declare const DEFAULT_PRUNE_GRACE_MS: number;
+export declare const RETAINED_BINARY_NAME = "claude";
+export declare const LAST_USED_MARKER = ".last-used";
+export declare const SOURCE_MANIFEST = "source.json";
+export type RetainFallbackReason = 'disabled' | 'source-missing' | 'source-unreadable' | 'not-a-file' | 'script-not-retained' | 'not-claude-binary' | 'retained-mismatch' | 'copy-failed';
+export interface RetainResolution {
+    /** The path to LAUNCH. */
+    path: string;
+    source: 'retained' | 'original';
+    /** Version string when it could be read; null when a fingerprint key was used. */
+    version: string | null;
+    /** The version-directory key (`2.1.299`, `2.1.299-247931696`, `fp-…`). */
+    key: string | null;
+    /** The path as configured (what we were asked to launch). */
+    sourcePath: string;
+    /** The real file the configured path points at right now. */
+    sourceRealPath: string | null;
+    /** How the version was read. */
+    versionVia: 'package-json' | 'version-flag' | 'fingerprint' | null;
+    /** True when THIS call made the copy (a new version landed). */
+    copied: boolean;
+    reason?: RetainFallbackReason;
+    detail?: string;
+    at: string;
+}
+export interface RetainedVersionEntry {
+    key: string;
+    path: string;
+    version: string | null;
+    sizeBytes: number | null;
+    copiedAt: string | null;
+    lastUsedAt: string | null;
+    current: boolean;
+}
+export interface PruneResult {
+    at: string;
+    checked: number;
+    removed: string[];
+    keptCurrent: string[];
+    keptInUse: string[];
+    keptRecent: string[];
+    keptUnknown: string[];
+    errors: string[];
+    skipped?: 'no-current-key' | 'disabled' | 'dir-missing';
+}
+export interface RetainerStatus {
+    enabled: boolean;
+    dir: string;
+    pruneGraceMs: number;
+    current: {
+        key: string;
+        version: string | null;
+        path: string;
+    } | null;
+    lastResolution: RetainResolution | null;
+    lastError: {
+        at: string;
+        message: string;
+    } | null;
+    counters: {
+        resolutions: number;
+        retained: number;
+        copies: number;
+        fallbacks: number;
+    };
+    retained: RetainedVersionEntry[];
+    lastPrune: PruneResult | null;
+}
+export interface ClaudeBinaryRetainerOptions {
+    dir: string;
+    enabled?: boolean;
+    pruneGraceMs?: number;
+    /** Test seam: count of live processes mapping `file` (null = cannot tell). */
+    liveMappers?: (file: string) => Promise<number | null>;
+    /** Test seam: run `<bin> --version` and return stdout. */
+    versionProbe?: (bin: string) => string;
+    /** Test seam: the copy primitive. */
+    copyFile?: (src: string, dst: string) => void;
+    now?: () => number;
+    log?: {
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+        info: (msg: string) => void;
+    };
+}
+/**
+ * Is the retainer ON for this process? Production default is ON (absent =
+ * on — the leak is the default-on failure). Under a test runner (VITEST set)
+ * the default is OFF: dozens of SessionManager tests pin the launch argv
+ * byte-for-byte against a configured claude path that happens to EXIST on a
+ * developer's Mac and not on CI, so a host-dependent default would make the
+ * same test pass on one machine and fail on another. An EXPLICIT
+ * `enabled: true` always wins (the retainer's own tests set it), and an
+ * explicit `false` always wins.
+ */
+export declare function resolveRetainerEnabled(configured: boolean | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function sanitizeVersionKey(version: string | null | undefined): string | null;
+/**
+ * Read the Claude Code version for a resolved real executable path.
+ *  1. `../package.json` of the bin dir (the npm layout:
+ *     `…/claude-code/bin/claude.exe` → `…/claude-code/package.json`), or a
+ *     sibling `package.json`.
+ *  2. `<bin> --version` (the native installer lays the binary down as
+ *     `~/.local/share/claude/versions/<ver>` with no package.json).
+ */
+export declare function readClaudeVersion(realPath: string, versionProbe?: (bin: string) => string): {
+    version: string | null;
+    via: 'package-json' | 'version-flag' | null;
+};
+/** Resolve a bare command name through PATH; absolute/relative paths pass through. */
+export declare function locateExecutable(configured: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Only a path that is plainly a Claude Code install is retained: the file is
+ * named `claude` / `claude.exe`, or a path component is the npm package dir
+ * (`claude-code`, `@anthropic-ai`), the native-installer dir (`claude`), or
+ * `.claude`. Component-exact so an unrelated directory whose NAME merely
+ * contains "claude" (a tmp dir, a project) does not qualify.
+ */
+export declare function looksLikeClaudeInstall(realPath: string): boolean;
+/**
+ * Count live processes mapping `file`. Linux: scan `/proc/*\/exe` (no
+ * subprocess). Elsewhere: `lsof -t -- <file>` (exit 1 + empty output = none).
+ * Returns null whenever the answer is not trustworthy — the caller KEEPS.
+ */
+export declare function defaultLiveMappers(file: string): Promise<number | null>;
+export declare class ClaudeBinaryRetainer {
+    readonly dir: string;
+    readonly enabled: boolean;
+    readonly pruneGraceMs: number;
+    private readonly liveMappers;
+    private readonly versionProbe;
+    private readonly copyFile;
+    private readonly now;
+    private readonly log;
+    private currentKey;
+    private currentVersion;
+    private lastResolution;
+    private lastError;
+    private lastPrune;
+    private counters;
+    /** Version-read cache keyed on the source file's identity, so the (slow,
+     *  synchronous) `--version` fallback for a package.json-less layout runs
+     *  once per installed build, not once per spawn. */
+    private versionCache;
+    private pruneInFlight;
+    constructor(opts: ClaudeBinaryRetainerOptions);
+    /** The default retain dir for an agent: under its gitignored state dir. */
+    static defaultDir(projectDir: string): string;
+    /**
+     * Resolve the path to launch for `configuredPath`. Synchronous; copies only
+     * when a new version is seen. Never throws — every failure is a fallback
+     * to the original path with a reason.
+     */
+    resolve(configuredPath: string): RetainResolution;
+    private accept;
+    private copyInto;
+    private removeTmp;
+    private touchLastUsed;
+    /** The directory this process has most recently launched from (null = never resolved). */
+    current(): {
+        key: string;
+        version: string | null;
+        path: string;
+    } | null;
+    listRetained(): RetainedVersionEntry[];
+    /**
+     * Remove retained versions that are not current, have not been used within
+     * the grace window, and that NO live process maps. "Cannot tell" keeps.
+     */
+    prune(): Promise<PruneResult>;
+    private pruneOnce;
+    status(): RetainerStatus;
+}
+//# sourceMappingURL=ClaudeBinaryRetainer.d.ts.map

package/dist/core/ClaudeBinaryRetainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClaudeBinaryRetainer.d.ts","sourceRoot":"","sources":["../../src/core/ClaudeBinaryRetainer.ts"],"names":[],"mappings":"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"}