sidekick-shared 0.28.2 → 0.29.0

package/dist/stateFile.d.ts

@@ -23,6 +23,20 @@ export interface StateFileQuotaWindow {
     utilization: number;
     /** ISO timestamp when the window resets; empty when unknown. */
     resetsAt: string;
+    /**
+     * Present (true) only when the plan has no such window — e.g. Claude Ultra
+     * has no five-hour limit. `utilization`/`resetsAt` are then 0/''.
+     */
+    absent?: boolean;
+}
+/** An extra usage meter beyond the two headline windows, e.g. a Fable weekly cap. */
+export interface StateFileQuotaLimit {
+    /** Server meter kind, e.g. `weekly_scoped`. */
+    kind: string;
+    /** Display label, e.g. `7-Day (Fable)`. */
+    label: string;
+    utilization: number;
+    resetsAt: string;
 }
 export interface StateFileQuota {
     fiveHour: StateFileQuotaWindow;
@@ -34,6 +48,10 @@ export interface StateFileQuota {
     capturedAt: string | null;
     ageMs: number | null;
     freshness: 'fresh' | 'aging' | 'stale' | null;
+    /** Subscription plan name when known, e.g. `Ultra`. Omitted when unknown. */
+    planLabel?: string;
+    /** Extra meters (per-model weekly caps and similar). Omitted when there are none. */
+    extraLimits?: StateFileQuotaLimit[];
 }
 export interface StateFileAccount {
     providerId: 'claude-code' | 'codex';

package/dist/stateFile.js

@@ -131,14 +131,29 @@ function quotaToStateFile(quota, now = Date.now()) {
             freshness ??= (0, quota_1.classifyQuotaFreshness)(ageMs);
         }
     }
+    const extraLimits = (0, quota_1.extraQuotaRows)(quota).map((row) => ({
+        kind: row.kind,
+        label: row.label,
+        utilization: row.utilization,
+        resetsAt: row.resetsAt,
+    }));
     return {
-        fiveHour: { utilization: quota.fiveHour.utilization, resetsAt: quota.fiveHour.resetsAt },
-        sevenDay: { utilization: quota.sevenDay.utilization, resetsAt: quota.sevenDay.resetsAt },
+        fiveHour: stateFileWindow(quota.fiveHour),
+        sevenDay: stateFileWindow(quota.sevenDay),
         source: quota.source ?? null,
         capturedSource: quota.capturedSource ?? null,
         capturedAt: quota.capturedAt ?? null,
         ageMs,
         freshness,
+        ...(quota.planLabel ? { planLabel: quota.planLabel } : {}),
+        ...(extraLimits.length > 0 ? { extraLimits } : {}),
+    };
+}
+function stateFileWindow(window) {
+    return {
+        utilization: window.utilization,
+        resetsAt: window.resetsAt,
+        ...(window.absent ? { absent: true } : {}),
     };
 }
 /** Project a billing block onto the state-file shape (totals only). */

package/dist/statusline/claudeStatuslinePayload.d.ts

@@ -74,9 +74,10 @@ export interface QuotaFromStatuslineOptions {
     /** Capture time; defaults to now. */
     now?: Date;
     /**
-     * A previously known quota (typically the persisted snapshot). Windows the
-     * payload omits are carried over from it, since Claude Code drops a window
-     * from the document once its reset time has passed.
+     * A previously known quota (typically the persisted snapshot). A window the
+     * payload omits is carried over from it while the fallback window has not
+     * reset yet, or when the fallback marks it `absent` (the plan has no such
+     * window, e.g. Ultra's missing five-hour limit).
      */
     fallback?: QuotaState | null;
 }

package/dist/statusline/claudeStatuslinePayload.js

@@ -119,14 +119,26 @@ function parseClaudeStatuslinePayload(text) {
         raw,
     };
 }
-function toWindow(live, fallback) {
+/**
+ * Claude Code leaves a window out of the document once its reset has passed,
+ * and always for a window the plan does not have (Ultra has no five-hour
+ * limit). A fallback is carried over only while it can still be current: an
+ * `absent` marker from an earlier API read, or a window that has not reset yet.
+ * An expired fallback would otherwise be re-saved as a fresh sample forever.
+ */
+function toWindow(live, fallback, nowMs) {
     if (live) {
         return {
             utilization: Math.max(0, live.usedPercentage),
             resetsAt: new Date(live.resetsAt * 1000).toISOString(),
         };
     }
-    return fallback ?? { utilization: 0, resetsAt: '' };
+    if (fallback?.absent)
+        return { utilization: 0, resetsAt: '', absent: true };
+    const fallbackResetMs = fallback ? Date.parse(fallback.resetsAt) : NaN;
+    if (fallback && Number.isFinite(fallbackResetMs) && fallbackResetMs > nowMs)
+        return fallback;
+    return { utilization: 0, resetsAt: '' };
 }
 /**
  * Build a `QuotaState` from the official rate-limit block. Returns `null`
@@ -141,8 +153,8 @@ function quotaFromStatuslinePayload(payload, options = {}) {
     const now = options.now ?? new Date();
     const fallback = options.fallback ?? undefined;
     return {
-        fiveHour: toWindow(limits.fiveHour, fallback?.fiveHour),
-        sevenDay: toWindow(limits.sevenDay, fallback?.sevenDay),
+        fiveHour: toWindow(limits.fiveHour, fallback?.fiveHour, now.getTime()),
+        sevenDay: toWindow(limits.sevenDay, fallback?.sevenDay, now.getTime()),
         available: true,
         providerId: 'claude-code',
         source: 'statusline',

package/dist/statusline/formatter.d.ts

@@ -23,6 +23,11 @@ export declare function selectStatuslineAccount(input: StatuslineInput): Statusl
  * One-line status. Segments, in order, each omitted when unknown:
  * `acct:<label> · 5h 42% resets 14:00 · ~1h20m left · 7d 61% · (2h ago) · ctx 37% · $0.42 · cache 92%`
  *
+ * Plans without a five-hour window (Claude Ultra) lead with the weekly window
+ * instead: `acct:<label> · 7d 17% resets Fri 01:00 · ~2d3h left · …`. Window
+ * labels follow the reported window length, so a Codex weekly primary window
+ * reads `7d`, not `5h`.
+ *
  * The age segment appears only for cached quota older than five minutes, so
  * a snapshot from yesterday can no longer read like a live figure.
  */

package/dist/statusline/formatter.js

@@ -27,6 +27,11 @@ function selectStatuslineAccount(input) {
  * One-line status. Segments, in order, each omitted when unknown:
  * `acct:<label> · 5h 42% resets 14:00 · ~1h20m left · 7d 61% · (2h ago) · ctx 37% · $0.42 · cache 92%`
  *
+ * Plans without a five-hour window (Claude Ultra) lead with the weekly window
+ * instead: `acct:<label> · 7d 17% resets Fri 01:00 · ~2d3h left · …`. Window
+ * labels follow the reported window length, so a Codex weekly primary window
+ * reads `7d`, not `5h`.
+ *
  * The age segment appears only for cached quota older than five minutes, so
  * a snapshot from yesterday can no longer read like a live figure.
  */
@@ -41,20 +46,35 @@ function formatStatusline(input) {
     if (!quota?.available) {
         return joinSegments([`acct:${account}`, 'quota unavailable', ...liveSegments]);
     }
-    const utilization = clampPercent(quota.fiveHour.utilization);
-    const reset = formatReset(quota.fiveHour.resetsAt, now);
-    const eta = estimateWindowEta(quota, now);
-    const segments = [`acct:${account}`, `5h ${Math.round(utilization)}% resets ${reset}`];
+    const first = describeWindow(quota.fiveHour, '5h', quota_1.FIVE_HOUR_WINDOW_MS);
+    const second = describeWindow(quota.sevenDay, '7d', quota_1.SEVEN_DAY_WINDOW_MS);
+    // Lead with the first window whenever the plan has it (even idle); fall back
+    // to the second window when the first does not exist for this plan.
+    const leadWithFirst = (0, quota_1.quotaWindowApplies)(quota.fiveHour) || !(0, quota_1.quotaWindowHasData)(quota.sevenDay);
+    const lead = leadWithFirst ? first : second;
+    const segments = [`acct:${account}`, formatLeadSegment(lead, now)];
+    const eta = estimateWindowEta(lead, quota.capturedAt, now);
     if (eta != null)
         segments.push(`~${formatMinutes(eta)} left`);
-    if (quota.sevenDay.resetsAt && quota.sevenDay.utilization > 0) {
-        segments.push(`7d ${Math.round(clampPercent(quota.sevenDay.utilization))}%`);
+    if (leadWithFirst && (0, quota_1.quotaWindowHasData)(quota.sevenDay) && quota.sevenDay.utilization > 0) {
+        segments.push(`${second.label} ${Math.round(clampPercent(quota.sevenDay.utilization))}%`);
     }
     if (quota.freshness && quota.freshness !== 'fresh') {
         segments.push(`(${(0, quota_1.formatQuotaAge)(quota.ageMs)})`);
     }
     return joinSegments([...segments, ...liveSegments]);
 }
+function describeWindow(window, label, defaultMs) {
+    const windowMs = typeof window.windowMs === 'number' && Number.isFinite(window.windowMs) && window.windowMs > 0
+        ? window.windowMs
+        : defaultMs;
+    return { label: (0, quota_1.quotaWindowShortLabel)(window.windowMs, label), window, windowMs };
+}
+function formatLeadSegment(lead, now) {
+    const percent = `${lead.label} ${Math.round(clampPercent(lead.window.utilization))}%`;
+    const reset = formatReset(lead.window.resetsAt, now);
+    return reset ? `${percent} resets ${reset}` : percent;
+}
 function formatLiveSegments(live) {
     if (!live)
         return [];
@@ -80,22 +100,25 @@ function formatCost(value) {
         return value.toFixed(1);
     return value.toFixed(2);
 }
-function estimateWindowEta(quota, now) {
-    const resetAt = Date.parse(quota.fiveHour.resetsAt);
+function estimateWindowEta(lead, capturedAtIso, now) {
+    const { window, windowMs } = lead;
+    if (window.absent)
+        return null;
+    const resetAt = Date.parse(window.resetsAt);
     if (!Number.isFinite(resetAt))
         return null;
     const nowMs = now.getTime();
     if (resetAt <= nowMs)
         return null;
-    const capturedAt = quota.capturedAt ? Date.parse(quota.capturedAt) : now.getTime();
+    const capturedAt = capturedAtIso ? Date.parse(capturedAtIso) : now.getTime();
     const sampleAt = Number.isFinite(capturedAt) ? capturedAt : now.getTime();
     if (sampleAt >= resetAt)
         return null;
-    const elapsedMinutes = (sampleAt - (resetAt - quota_1.FIVE_HOUR_WINDOW_MS)) / 60_000;
-    if (elapsedMinutes <= 0 || quota.fiveHour.utilization <= 0)
+    const elapsedMinutes = (sampleAt - (resetAt - windowMs)) / 60_000;
+    if (elapsedMinutes <= 0 || window.utilization <= 0)
         return null;
-    const burnRate = quota.fiveHour.utilization / elapsedMinutes;
-    const eta = (0, BurnRateCalculator_1.estimateTimeToQuota)(quota.fiveHour.utilization, 100, burnRate);
+    const burnRate = window.utilization / elapsedMinutes;
+    const eta = (0, BurnRateCalculator_1.estimateTimeToQuota)(window.utilization, 100, burnRate);
     const minutesUntilReset = (resetAt - nowMs) / 60_000;
     return eta !== null && eta < minutesUntilReset ? eta : null;
 }
@@ -107,20 +130,36 @@ function compactLabel(value) {
 function clampPercent(value) {
     return Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : 0;
 }
-function formatReset(value, fallback) {
+/**
+ * Reset time as `HH:MM`, or `Fri 01:00` when it is more than a day away.
+ * Returns '' for an empty or unparseable value — never the current time.
+ */
+function formatReset(value, now) {
+    if (!value)
+        return '';
     const reset = new Date(value);
-    const date = Number.isNaN(reset.getTime()) ? fallback : reset;
-    return new Intl.DateTimeFormat(undefined, {
+    if (Number.isNaN(reset.getTime()))
+        return '';
+    const time = new Intl.DateTimeFormat(undefined, {
         hour: '2-digit',
         minute: '2-digit',
         hour12: false,
-    }).format(date);
+    }).format(reset);
+    if (reset.getTime() - now.getTime() <= 86_400_000)
+        return time;
+    const weekday = new Intl.DateTimeFormat(undefined, { weekday: 'short' }).format(reset);
+    return `${weekday} ${time}`;
 }
 function formatMinutes(value) {
     const minutes = Math.max(0, Math.round(value));
     if (minutes < 60)
         return `${minutes}min`;
     const hours = Math.floor(minutes / 60);
+    if (hours >= 48) {
+        const days = Math.floor(hours / 24);
+        const remainderHours = hours % 24;
+        return remainderHours ? `${days}d${remainderHours}h` : `${days}d`;
+    }
     const remainder = minutes % 60;
     return remainder ? `${hours}h${remainder}m` : `${hours}h`;
 }

package/dist/statusline/index.d.ts

@@ -2,14 +2,14 @@ export { getActiveAccountStatus } from '../accountStatus';
 export type { ActiveAccountStatus, ActiveAccountStatusOptions, ActiveProviderAccountStatus, } from '../accountStatus';
 export { readQuotaSnapshot, writeQuotaSnapshot } from '../quotaSnapshots';
 export type { QuotaSnapshotProviderId } from '../quotaSnapshots';
-export { appendQuotaHistorySample, getWorkspaceIdFromPath } from '../quotaHistory';
+export { appendQuotaHistorySample, getWorkspaceIdFromPath, quotaHistoryWindow, } from '../quotaHistory';
 export type { QuotaHistorySample } from '../quotaHistory';
-export { classifyQuotaFreshness, formatQuotaAge } from '../quota';
-export type { QuotaFreshness, QuotaState } from '../quota';
+export { classifyQuotaFreshness, formatQuotaAge, quotaWindowApplies, quotaWindowHasData, quotaWindowShortLabel, } from '../quota';
+export type { QuotaFreshness, QuotaState, QuotaWindow } from '../quota';
 export { BurnRateCalculator, estimateTimeToQuota } from './BurnRateCalculator';
 export { formatStatusline, selectStatuslineAccount } from './formatter';
 export type { StatuslineInput, StatuslineSelection } from './formatter';
 export { parseClaudeStatuslinePayload, quotaFromStatuslinePayload, } from './claudeStatuslinePayload';
 export type { ClaudeStatuslinePayload, ClaudeStatuslineRateLimitWindow, QuotaFromStatuslineOptions, } from './claudeStatuslinePayload';
 export { STATE_FILE_NAME, STATE_FILE_SCHEMA_VERSION, billingBlockToStateFile, getStateFilePath, quotaToStateFile, readStateFile, writeStateFile, } from '../stateFile';
-export type { SidekickStateFile, SidekickStateInput, StateFileAccount, StateFileBillingBlock, StateFileContext, StateFileQuota, StateFileQuotaWindow, StateFileSession, StateFileWriter, WriteStateFileOptions, } from '../stateFile';
+export type { SidekickStateFile, SidekickStateInput, StateFileAccount, StateFileBillingBlock, StateFileContext, StateFileQuota, StateFileQuotaLimit, StateFileQuotaWindow, StateFileSession, StateFileWriter, WriteStateFileOptions, } from '../stateFile';

package/dist/statusline/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.quotaFromStatuslinePayload = exports.parseClaudeStatuslinePayload = exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.formatQuotaAge = exports.classifyQuotaFreshness = exports.getWorkspaceIdFromPath = exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
+exports.writeStateFile = exports.readStateFile = exports.quotaToStateFile = exports.getStateFilePath = exports.billingBlockToStateFile = exports.STATE_FILE_SCHEMA_VERSION = exports.STATE_FILE_NAME = exports.quotaFromStatuslinePayload = exports.parseClaudeStatuslinePayload = exports.selectStatuslineAccount = exports.formatStatusline = exports.estimateTimeToQuota = exports.BurnRateCalculator = exports.quotaWindowShortLabel = exports.quotaWindowHasData = exports.quotaWindowApplies = exports.formatQuotaAge = exports.classifyQuotaFreshness = exports.quotaHistoryWindow = exports.getWorkspaceIdFromPath = exports.appendQuotaHistorySample = exports.writeQuotaSnapshot = exports.readQuotaSnapshot = exports.getActiveAccountStatus = void 0;
 var accountStatus_1 = require("../accountStatus");
 Object.defineProperty(exports, "getActiveAccountStatus", { enumerable: true, get: function () { return accountStatus_1.getActiveAccountStatus; } });
 var quotaSnapshots_1 = require("../quotaSnapshots");
@@ -9,9 +9,13 @@ Object.defineProperty(exports, "writeQuotaSnapshot", { enumerable: true, get: fu
 var quotaHistory_1 = require("../quotaHistory");
 Object.defineProperty(exports, "appendQuotaHistorySample", { enumerable: true, get: function () { return quotaHistory_1.appendQuotaHistorySample; } });
 Object.defineProperty(exports, "getWorkspaceIdFromPath", { enumerable: true, get: function () { return quotaHistory_1.getWorkspaceIdFromPath; } });
+Object.defineProperty(exports, "quotaHistoryWindow", { enumerable: true, get: function () { return quotaHistory_1.quotaHistoryWindow; } });
 var quota_1 = require("../quota");
 Object.defineProperty(exports, "classifyQuotaFreshness", { enumerable: true, get: function () { return quota_1.classifyQuotaFreshness; } });
 Object.defineProperty(exports, "formatQuotaAge", { enumerable: true, get: function () { return quota_1.formatQuotaAge; } });
+Object.defineProperty(exports, "quotaWindowApplies", { enumerable: true, get: function () { return quota_1.quotaWindowApplies; } });
+Object.defineProperty(exports, "quotaWindowHasData", { enumerable: true, get: function () { return quota_1.quotaWindowHasData; } });
+Object.defineProperty(exports, "quotaWindowShortLabel", { enumerable: true, get: function () { return quota_1.quotaWindowShortLabel; } });
 var BurnRateCalculator_1 = require("./BurnRateCalculator");
 Object.defineProperty(exports, "BurnRateCalculator", { enumerable: true, get: function () { return BurnRateCalculator_1.BurnRateCalculator; } });
 Object.defineProperty(exports, "estimateTimeToQuota", { enumerable: true, get: function () { return BurnRateCalculator_1.estimateTimeToQuota; } });

package/dist/statusline/payload.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `sidekick-shared/statusline/payload` — the pure Claude Code status-line
+ * stdin parser on its own, for hosts with a tight bundle budget that render
+ * their own line. Loads no account, credential, quota-snapshot, or network
+ * code (the full `sidekick-shared/statusline` entry does).
+ *
+ * @module statusline/payload
+ */
+export { parseClaudeStatuslinePayload, quotaFromStatuslinePayload, } from './claudeStatuslinePayload';
+export type { ClaudeStatuslinePayload, ClaudeStatuslineRateLimitWindow, QuotaFromStatuslineOptions, } from './claudeStatuslinePayload';

package/dist/statusline/payload.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * `sidekick-shared/statusline/payload` — the pure Claude Code status-line
+ * stdin parser on its own, for hosts with a tight bundle budget that render
+ * their own line. Loads no account, credential, quota-snapshot, or network
+ * code (the full `sidekick-shared/statusline` entry does).
+ *
+ * @module statusline/payload
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quotaFromStatuslinePayload = exports.parseClaudeStatuslinePayload = void 0;
+var claudeStatuslinePayload_1 = require("./claudeStatuslinePayload");
+Object.defineProperty(exports, "parseClaudeStatuslinePayload", { enumerable: true, get: function () { return claudeStatuslinePayload_1.parseClaudeStatuslinePayload; } });
+Object.defineProperty(exports, "quotaFromStatuslinePayload", { enumerable: true, get: function () { return claudeStatuslinePayload_1.quotaFromStatuslinePayload; } });

package/dist/testing/credentialGuard.d.ts

@@ -15,6 +15,20 @@ export interface CredentialGuardOptions {
     blockedBinaries?: string[];
     /** Extra real paths to protect, besides the Claude, Codex, and Sidekick homes. */
     protectedPaths?: string[];
+    /**
+     * Home overrides to keep instead of unsetting, for a suite that points one
+     * at its own fixture before the guard installs. Accepts only the variables
+     * the guard unsets: `CLAUDE_CONFIG_DIR`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`,
+     * `CODEX_HOME`, and `SIDEKICK_CONFIG_DIR`.
+     *
+     * Install throws, before changing anything, for any other name, or when a
+     * preserved value is, contains, or lies inside a real protected location:
+     * the real home's `.claude`, `.claude.json`, and `.codex`, the default
+     * Sidekick config dir, or a `protectedPaths` entry. Symlinks are resolved
+     * first. The guard cannot tell a real store kept elsewhere from a fixture,
+     * so preserve only paths the suite created. Blank values are kept unchecked.
+     */
+    preserveEnv?: readonly string[];
 }
 /**
  * Installs the guard once per process and returns it; later calls return the

package/dist/testing/credentialGuard.js

@@ -46,7 +46,8 @@ exports.installCredentialGuard = installCredentialGuard;
  * - `HOME` (and the Windows equivalents) point at a per-process temp dir,
  *   removed on exit, and the home overrides (`CLAUDE_CONFIG_DIR`,
  *   `CLAUDE_SECURESTORAGE_CONFIG_DIR`, `CODEX_HOME`, `SIDEKICK_CONFIG_DIR`)
- *   are unset, so every `os.homedir()`-derived path is isolated structurally;
+ *   are unset (unless named in `preserveEnv` and pointed at a fixture), so
+ *   every `os.homedir()`-derived path is isolated structurally;
  * - the real `child_process` module object is patched, which reaches both ESM
  *   named imports (after `syncBuiltinESMExports`) and CommonJS code loaded
  *   through native `require`; per-file `vi.mock('child_process')` factories
@@ -64,6 +65,13 @@ const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const GUARD_KEY = '__sidekickCredentialGuard';
 const DEFAULT_BLOCKED_BINARIES = ['security', 'claude', 'codex'];
+/** Home overrides the guard unsets; only these can be preserved. */
+const SCRUBBED_ENV = [
+    'CLAUDE_CONFIG_DIR',
+    'CLAUDE_SECURESTORAGE_CONFIG_DIR',
+    'CODEX_HOME',
+    'SIDEKICK_CONFIG_DIR',
+];
 const CHILD_PROCESS_FUNCTIONS = [
     'spawn',
     'spawnSync',
@@ -111,6 +119,8 @@ function installCredentialGuard(options = {}) {
     // os.userInfo() reads the passwd entry, so it still names the real home
     // after HOME is redirected below.
     const realHome = os.userInfo().homedir;
+    // Validated before any side effect, so a refused install changes nothing.
+    const preserved = checkPreservedEnv(options, realHome, realFs);
     const testHome = realFs.mkdtempSync(path.join(os.tmpdir(), 'sidekick-test-home-'));
     const removeTestHome = realFs.rmSync.bind(realFs);
     process.once('exit', () => {
@@ -139,10 +149,9 @@ function installCredentialGuard(options = {}) {
     process.env.USERPROFILE = testHome;
     process.env.APPDATA = path.join(testHome, 'AppData', 'Roaming');
     process.env.LOCALAPPDATA = path.join(testHome, 'AppData', 'Local');
-    delete process.env.CLAUDE_CONFIG_DIR;
-    delete process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
-    delete process.env.CODEX_HOME;
-    delete process.env.SIDEKICK_CONFIG_DIR;
+    for (const name of SCRUBBED_ENV)
+        if (!preserved.has(name))
+            delete process.env[name];
     const protectedRoots = path.resolve(realHome) === path.resolve(testHome)
         ? []
         : [
@@ -244,6 +253,79 @@ function installCredentialGuard(options = {}) {
     globalThis[GUARD_KEY] = state;
     return state;
 }
+/** The `preserveEnv` names, after refusing unknown names and unsafe values. */
+function checkPreservedEnv(options, realHome, realFs) {
+    const preserved = new Set();
+    for (const name of options.preserveEnv ?? []) {
+        if (!SCRUBBED_ENV.includes(name)) {
+            throw new Error(`installCredentialGuard: preserveEnv accepts only ${SCRUBBED_ENV.join(', ')}; got ${JSON.stringify(name)}.`);
+        }
+        preserved.add(name);
+    }
+    if (preserved.size === 0)
+        return preserved;
+    const roots = [
+        path.join(realHome, '.claude'),
+        path.join(realHome, '.claude.json'),
+        path.join(realHome, '.codex'),
+        path.join(realHome, '.config', 'sidekick'),
+        // The Windows default config dir, read before HOME and APPDATA move.
+        ...(process.platform === 'win32' && process.env.APPDATA
+            ? [path.join(process.env.APPDATA, 'sidekick')]
+            : []),
+        ...(options.protectedPaths ?? []),
+    ];
+    for (const name of preserved) {
+        const value = process.env[name]?.trim();
+        if (!value)
+            continue;
+        const hit = protectedLocation(value, roots, realFs);
+        if (hit) {
+            throw new Error(`installCredentialGuard: preserveEnv ${name}=${value} reaches the real protected location ${hit}. Point it at a temporary fixture instead.`);
+        }
+    }
+    return preserved;
+}
+/** The root `target` equals, contains, or lies inside, comparing plain and symlink-resolved paths. */
+function protectedLocation(target, roots, realFs) {
+    // Case-insensitive by default on macOS and Windows; folding can only over-refuse.
+    const fold = process.platform === 'darwin' || process.platform === 'win32';
+    const normal = (value) => {
+        const resolved = path.resolve(value);
+        return fold ? resolved.toLowerCase() : resolved;
+    };
+    const within = (parent, child) => child === parent || child.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+    const related = (a, b) => within(a, b) || within(b, a);
+    // Plain paths first, so an obviously unsafe value never reaches the filesystem.
+    const plain = normal(target);
+    for (const root of roots)
+        if (related(normal(root), plain))
+            return root;
+    const real = normal(realpathOfNearest(target, realFs));
+    for (const root of roots) {
+        const realRoot = normal(realpathOfNearest(root, realFs));
+        if (related(realRoot, real) || related(normal(root), real) || related(realRoot, plain))
+            return root;
+    }
+    return null;
+}
+/** `realpath` of the nearest existing ancestor, with the missing tail re-appended. */
+function realpathOfNearest(target, realFs) {
+    let current = path.resolve(target);
+    let tail = [];
+    for (;;) {
+        try {
+            return path.join(realFs.realpathSync.native(current), ...tail);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(target);
+            tail = [path.basename(current), ...tail];
+            current = parent;
+        }
+    }
+}
 /**
  * The real module object of a Node built-in: `process.getBuiltinModule`
  * (Node 20.16+), or `require` in CommonJS on older Node.

package/dist/toolCallOrigins.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Locates the session record that issued each of a set of tool calls, by id.
+ *
+ * Given Claude Code `tool_use` ids (`toolu_…`) and/or Codex `call_id`s, finds
+ * the session file, session id and time of each call, plus the ordinal of the
+ * human prompt the call answered, so a downstream record (an edit, a commit)
+ * can be tied back to the prompt that caused it. Scope, listing, session keys
+ * and ordinals are the ones `collectPromptHistory()` uses, so results join
+ * directly with prompt-history entries.
+ *
+ * Cost: one listing of the workspace-scoped session files (`since` prunes by
+ * modification time), then a streaming pass over each candidate file in which
+ * a line is only parsed when it contains one of the wanted ids. Claude Code
+ * subagent transcripts of each session are searched too. Stops as soon as
+ * every id is found. Prompt ordinals are read only for files that matched.
+ *
+ * Node-only: reads session files.
+ *
+ * @module toolCallOrigins
+ */
+import { type PromptHistoryProvider } from './promptHistory';
+export interface FindToolCallOriginsOptions {
+    /** Tool-call ids to locate: Claude `tool_use` ids and/or Codex `call_id`s. */
+    ids: Iterable<string>;
+    /** Workspace roots that scope the search (as for `collectPromptHistory`). */
+    workspacePaths: string[];
+    /** Also search the roots' git worktree siblings. Default true. */
+    includeWorktrees?: boolean;
+    /** Only session files modified at or after this instant. */
+    since?: Date;
+    /** Default both. */
+    providers?: PromptHistoryProvider[];
+    /** Stops between files and lines; the promise rejects with the signal's reason. */
+    signal?: AbortSignal;
+}
+export interface ToolCallOrigin {
+    provider: PromptHistoryProvider;
+    /**
+     * Session whose prompt history `afterOrdinal` counts in: the session itself,
+     * or its parent for a subagent or fork (Claude subagent transcripts live
+     * under the parent; a Codex subagent or fork has its own rollout, named in
+     * `subagent.agentId` / `filePath`, and no prompts of its own).
+     */
+    sessionId: string;
+    /** Same key `collectPromptHistory()` reports for that session's file. */
+    sessionKey: string;
+    /** File the call was recorded in (a subagent transcript for subagent calls). */
+    filePath: string;
+    /** ISO timestamp of the record that issued the call. */
+    timestamp: string;
+    /**
+     * Ordinal of the last human prompt at or before the call, in the session's
+     * prompt history; null when the call precedes every prompt or the session
+     * has none (e.g. a Codex subagent whose parent was not found in scope).
+     */
+    afterOrdinal: number | null;
+    toolName?: string;
+    /** Set when a subagent issued the call. */
+    subagent?: {
+        agentId: string;
+        parentSessionId: string;
+    };
+}
+/**
+ * Finds where each tool call was issued. Ids that are not found are absent
+ * from the result. When an id appears more than once (a forked or resumed
+ * session can replay history), the earliest record wins, and a session's own
+ * record wins over a fork's copy at the same instant.
+ */
+export declare function findToolCallOrigins(options: FindToolCallOriginsOptions): Promise<Map<string, ToolCallOrigin>>;