@newrelic/preflight 1.17.0 → 1.18.0

package/dist/data/pricing-overlay/README.md

@@ -0,0 +1,58 @@
+# Pricing overlay
+
+`pricing.json` fills gaps in the vendored `src/shared/pricing-data.ts` table
+for model IDs a platform reports that the vendored table doesn't resolve —
+confirmed live via `PricingTable.resolve()`'s four resolution paths (exact /
+alias / forward-prefix / reverse-prefix). It's applied automatically at
+startup (`applyPricingOverlay()` in `src/metrics/pricing-overlay.ts`) unless
+a user has configured their own custom pricing file, and is gap-fill-only:
+`applyGapFilledOverlay()` drops any entry that already resolves against the
+vendored table instead of overriding it, so it can never silently mask a
+correction made upstream.
+
+It's currently empty (`{}`). This isn't tied to any one platform — add an
+entry here whenever you hit a real model ID that Preflight resolves to `$0`
+cost because the vendored table doesn't have it yet, regardless of which
+platform surfaced it.
+
+## Adding an entry
+
+1. Find the model's real per-token rate from a source you can cite — the
+   vendor's own pricing page where one exists, or (for models only listed
+   through a specific platform, e.g. one a coding assistant surfaces that
+   the underlying model vendor doesn't itself document standalone) that
+   platform's own published pricing page. Note your source and the date you
+   checked it in your commit or PR description — pricing pages change
+   without much notice.
+2. Add the entry to `pricing.json`, matching the `ModelPricing` shape
+   (`src/shared/pricing.ts`). Only add IDs confirmed missing from the
+   vendored table — never duplicate or "correct" an existing vendored entry
+   here; that needs a fix upstream, in whatever repo maintains
+   `src/shared/pricing-data.ts` for you.
+3. `contextWindow` is a non-billing-critical best-effort default (not used
+   in `calculateCost()`'s pricing math, only validated as a positive
+   integer) — it's fine to estimate it if you can't verify it precisely.
+
+This file is exactly the place to add an entry if you can't push directly to
+wherever the vendored table's source lives (e.g. an external contributor) —
+a maintainer with access can upstream it later, and the collision guard
+above makes that safe even if the sync lags.
+
+## Known, unavoidable limitation
+
+Inherited from `ModelPricing`'s shape, which this overlay reuses as-is — not
+fixable here without a schema change upstream: `ModelPricing` has no tiered
+cache-read field, so a model whose cached-input rate is _higher_ at its
+long-context tier than at its default tier can't have that modeled — the
+base (lower) cache rate would apply at every tier. If you hit this, note it
+explicitly as a comment on the entry.
+
+## Interaction with a user's own custom pricing file
+
+If a user sets `NEW_RELIC_AI_CUSTOM_PRICING_FILE` (or `customPricingFile` in
+`~/.newrelic-preflight/config.json`) — for _any_ reason, even one unrelated
+to this overlay — it's not applied at all. `initPricing()` always replaces
+the full table from `DEFAULT_PRICING_TABLE`; it never merges a user's file
+with this overlay. A user relying on both a custom pricing entry and one of
+the gap-fill models here should add the model they need from `pricing.json`
+into their own custom pricing file instead.

package/dist/data/pricing-overlay/pricing.json

@@ -0,0 +1 @@
+{}

package/dist/deploy/data-paths.d.ts

@@ -1,6 +1,6 @@
 /**
  * Resolve the directory containing bundled data files (alerts/, dashboards/,
- * or copilot-pricing/ JSON definitions).
+ * or pricing-overlay/ JSON definitions).
  *
  * The deploy modules ship as `dist/deploy/*.js` after TypeScript build, with
  * data files copied into `dist/data/<name>/` by the postbuild step (see
@@ -17,8 +17,8 @@
  *
  * Throws if no candidate exists — the deploy commands cannot run without the
  * underlying data files. Callers for whom the data is optional (e.g. the
- * copilot-pricing overlay, unlike alerts/dashboards which are required for
- * their own commands) must wrap this in a try/catch and degrade gracefully.
+ * pricing overlay, unlike alerts/dashboards which are required for their own
+ * commands) must wrap this in a try/catch and degrade gracefully.
  */
-export declare function resolveDataDir(name: 'alerts' | 'dashboards' | 'copilot-pricing'): string;
+export declare function resolveDataDir(name: 'alerts' | 'dashboards' | 'pricing-overlay'): string;
 //# sourceMappingURL=data-paths.d.ts.map

package/dist/deploy/data-paths.js

@@ -2,7 +2,7 @@ import { existsSync, realpathSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 /**
  * Resolve the directory containing bundled data files (alerts/, dashboards/,
- * or copilot-pricing/ JSON definitions).
+ * or pricing-overlay/ JSON definitions).
  *
  * The deploy modules ship as `dist/deploy/*.js` after TypeScript build, with
  * data files copied into `dist/data/<name>/` by the postbuild step (see
@@ -19,8 +19,8 @@ import { dirname, resolve } from 'node:path';
  *
  * Throws if no candidate exists — the deploy commands cannot run without the
  * underlying data files. Callers for whom the data is optional (e.g. the
- * copilot-pricing overlay, unlike alerts/dashboards which are required for
- * their own commands) must wrap this in a try/catch and degrade gracefully.
+ * pricing overlay, unlike alerts/dashboards which are required for their own
+ * commands) must wrap this in a try/catch and degrade gracefully.
  */
 export function resolveDataDir(name) {
     const rawPath = process.argv[1] ?? process.cwd();

package/dist/hooks/session-resolver.d.ts

@@ -68,6 +68,17 @@ export declare function resolveFromJobDir(claudeJobDir: string | null | undefine
  * only checks whether the PID is alive, and a recycled PID always is.
  */
 export declare function resolveFromBreadcrumb(storagePath: string, ppid: number | undefined, processStartMs?: number): string | null;
+/**
+ * Sanitize a cwd into the single filename segment used both by the collector's
+ * `writeCwdBreadcrumb()` (session-by-cwd breadcrumb) and by Claude Code's own
+ * transcript-directory naming under `~/.claude/projects/`: backslash, forward
+ * slash, and colon each become `-`. Must stay identical to
+ * `collector-script.ts` so both sides derive the same filename independently.
+ * Colons are stripped so a Windows drive letter (e.g. `C:`) never survives into
+ * a filename where `path.resolve()` on win32 would reinterpret it as a
+ * drive-relative component and read/write outside the intended directory.
+ */
+export declare function sanitizeCwdForFilename(cwd: string): string;
 /**
  * Try to resolve the session_id synchronously from the cwd breadcrumb file.
  * Fallback for platforms where the PPID breadcrumb never matches (see the
@@ -131,4 +142,127 @@ export declare function isSyntheticSessionId(id: string | null | undefined): boo
  * double-counting) should check this, not `isSyntheticSessionId`.
  */
 export declare function isUnscopedAggregatorSessionId(id: string | null | undefined): boolean;
+/** Where a resolved session name came from, most trusted first. */
+export type SessionNameSource = 'user' | 'ai-title' | 'auto' | 'cwd';
+/**
+ * The naming-relevant fields read out of `CLAUDE_JOB_DIR/state.json`.
+ * `sessionId`/`name`/`nameSource` are labels; `intent` is CONTENT.
+ */
+export interface JobState {
+    /** Full session UUID, from the explicit `sessionId` field or `linkScanPath`. */
+    readonly sessionId: string | null;
+    /** Human-readable title Claude Code wrote for the job. */
+    readonly name: string | null;
+    /** Whether a human named it (`user`) or Claude auto-generated it (`auto`). */
+    readonly nameSource: 'user' | 'auto' | null;
+    /**
+     * SENSITIVE (CONTENT): the job's first user prompt. Populated ONLY when
+     * `readJobState` is called with `{ recordContent: true }`; otherwise null,
+     * so the sensitive field is off by construction rather than by convention.
+     * Because `recordContent` is force-disabled under highSecurity upstream
+     * (never bypass), passing `config.recordContent` keeps intent null in high
+     * security mode automatically. Even when populated it is returned verbatim,
+     * so any consumer MUST still pass it through `redactSensitive()` before it
+     * reaches a log, NR event, tool response, or persisted file. Phase-1 wiring
+     * reads `name`/`nameSource` only and never requests or forwards `intent`.
+     */
+    readonly intent: string | null;
+}
+/**
+ * Read the naming fields from `CLAUDE_JOB_DIR/state.json`. Sibling to
+ * `resolveFromJobDir` (whose `string | null` contract is unchanged) — returns
+ * null when there is no readable state file. `sessionId` prefers an explicit
+ * `sessionId` field, falling back to the UUID embedded in `linkScanPath`.
+ *
+ * The sensitive `intent` (first-prompt CONTENT) is populated ONLY when
+ * `options.recordContent === true`; it is null otherwise. This gates the
+ * content field by construction (mirroring `DecisionTracker`'s `recordContent`
+ * gate) so a future consumer that copies the `name`/`nameSource` wiring cannot
+ * leak prompt content by simply reading `.intent`. Pass `config.recordContent`
+ * (already force-disabled under highSecurity) to stay compliant; the `name`/
+ * `nameSource` display labels are never gated.
+ */
+export declare function readJobState(claudeJobDir: string | null | undefined, options?: {
+    readonly recordContent?: boolean;
+}): JobState | null;
+/**
+ * Scan `text` (a suffix of a transcript JSONL file) for the LAST `ai-title`
+ * record and return its `aiTitle` (raw, unredacted — the caller redacts).
+ * `firstFragmentComplete` must be true only when `text` begins exactly at a
+ * file/line boundary; otherwise the substring before the first newline is a
+ * partial line whose start lies in an earlier, unread region and is skipped.
+ * Scanning newest-first means the first match is the file's last `ai-title`.
+ */
+export declare function findLastAiTitleInText(text: string, firstFragmentComplete: boolean): string | null;
+/**
+ * Read the last `ai-title` from a session's transcript JSONL, redacted.
+ * Locates the transcript by matching `<sessionId>.jsonl` under any project slug
+ * (see `findTranscriptPath` — robust to Claude Code's cwd-slug scheme). Reads
+ * BOUNDED — reverse-scans the file's tail one chunk at a time up to
+ * `TRANSCRIPT_TITLE_MAX_SCAN_BYTES`, never slurping the whole file. Returns null
+ * on any miss (no file, no title, bad sessionId) and never throws.
+ *
+ * @param projectsDir Override for `~/.claude/projects` (test seam).
+ */
+export declare function readTranscriptTitle(input: {
+    readonly projectsDir?: string;
+    readonly sessionId: string;
+}): string | null;
+/**
+ * Directory basenames too generic to serve as a session label. Single source
+ * of truth for the guard `SessionTracker`'s streaming cwd fallback also uses. A
+ * degenerate startup cwd yields no authoritative `cwd` name (step 4 falls
+ * through to null), leaving the tracker's streaming fallback free to upgrade to
+ * a better name from a later tool call's cwd.
+ */
+export declare const DEGENERATE_NAMES: ReadonlySet<string>;
+/** Inputs to the pure `resolveSessionName` precedence decision. */
+export interface ResolveSessionNameInputs {
+    /** Parsed background-job state, from `readJobState` (null if none). */
+    readonly jobState?: JobState | null;
+    /** Last transcript `ai-title`, from `readTranscriptTitle` (null if none). */
+    readonly transcriptTitle?: string | null;
+    /** Working directory, for the basename fallback. */
+    readonly cwd?: string | null;
+}
+/** A resolved session name plus which source produced it. */
+export interface SessionNameResult {
+    readonly name: string;
+    readonly source: SessionNameSource;
+}
+/**
+ * Pure precedence decision for a session's display name (first hit wins):
+ *   1. state.json `name` where `nameSource === 'user'`  → `user`
+ *   2. transcript last `ai-title`                        → `ai-title`
+ *   3. state.json `name` where `nameSource === 'auto'`   → `auto`
+ *   4. basename(cwd), unless degenerate                  → `cwd`
+ *   5. null
+ * Does no IO and gates on nothing: callers pass already-read values and redact
+ * the returned name at each sink.
+ */
+export declare function resolveSessionName(inputs: ResolveSessionNameInputs): SessionNameResult | null;
+/**
+ * Trust rank of a session-name source; LOWER is more trusted. Mirrors
+ * `resolveSessionName`'s precedence exactly: `user`(0) > `ai-title`(1) >
+ * `auto`(2) > `cwd`(3). Used to decide whether a freshly re-resolved name may
+ * replace the one already in place (see `shouldReplaceSessionName`).
+ */
+export declare function sessionNameSourceRank(source: SessionNameSource): number;
+/**
+ * Whether a re-resolved name from `next` should replace a name currently
+ * sourced from `current`. Freshness re-resolution (Phase 2) re-reads Claude
+ * Code's name sources at persist/shutdown time so a refined `ai-title` — or a
+ * name a human later assigns — supersedes the first-prompt guess.
+ *
+ * Replaces only when `next` is at least as trusted as `current`
+ * (`rank(next) <= rank(current)`): an equal-or-better source wins (which also
+ * picks up refined text for the SAME source, e.g. an updated `ai-title`),
+ * while a strictly-less-trusted source is refused. That refusal is the
+ * load-bearing invariant: a `user`-sourced name is NEVER downgraded to
+ * `auto`/`cwd`, even if the job-state file that supplied it later disappears
+ * and re-resolution would otherwise fall through to the transcript title or
+ * the cwd basename. A `null` current source (session not yet named) always
+ * accepts.
+ */
+export declare function shouldReplaceSessionName(current: SessionNameSource | null, next: SessionNameSource): boolean;
 //# sourceMappingURL=session-resolver.d.ts.map

package/dist/hooks/session-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-resolver.d.ts","sourceRoot":"","sources":["../../src/hooks/session-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAeH,uEAAuE;AACvE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAExD,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,eAAe,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC9F;AAOD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CA8BxF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,cAAc,GAAE,MAA6C,GAC5D,MAAM,GAAG,IAAI,CA+Bf;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAoB1F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,sBAAsB,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC9D,OAAO,CAAC,MAAM,CAAC,CAuGjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,sBAAsB,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAC9D,OAAO,CAAC,MAAM,CAAC,CA2CjB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAG3E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAGpF"}
+{"version":3,"file":"session-resolver.d.ts","sourceRoot":"","sources":["../../src/hooks/session-resolver.ts"],"names":[],"mappings":"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"}

package/dist/hooks/session-resolver.js

@@ -26,10 +26,11 @@
  * tool handlers should report "session_id not yet resolved" rather than make
  * one up.
  */
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync, openSync, readSync, closeSync, constants as fsConstants, } from 'node:fs';
 import { resolve, basename } from 'node:path';
 import { homedir } from 'node:os';
 import { createLogger } from '../shared/index.js';
+import { redactSensitive } from '../config.js';
 const logger = createLogger('session-resolver');
 const SESSION_ID_RE = /^[a-zA-Z0-9_-]{1,128}$/;
 const DEFAULT_STORAGE_DIR = resolve(homedir(), '.newrelic-preflight');
@@ -37,10 +38,12 @@ const POLL_SCHEDULE_MS = [100, 200, 500, 1000, 2000];
 const STEADY_POLL_MS = 2000;
 const WARN_AFTER_MS = 60_000;
 /**
- * Try to resolve the session_id synchronously from `CLAUDE_JOB_DIR/state.json`.
- * Returns the validated session_id or null.
+ * Read and JSON-parse `<claudeJobDir>/state.json`, returning the parsed object
+ * or null on any failure (missing dir, unreadable, invalid JSON, non-object).
+ * Shared by `resolveFromJobDir` and `readJobState` so both derive from one
+ * read; neither's public contract changes.
  */
-export function resolveFromJobDir(claudeJobDir) {
+function readAndParseJobState(claudeJobDir) {
     if (!claudeJobDir || typeof claudeJobDir !== 'string')
         return null;
     const statePath = resolve(claudeJobDir, 'state.json');
@@ -64,18 +67,30 @@ export function resolveFromJobDir(claudeJobDir) {
     }
     if (parsed === null || typeof parsed !== 'object')
         return null;
-    const linkScanPath = parsed.linkScanPath;
+    return parsed;
+}
+/**
+ * Extract the session UUID from a `linkScanPath` value: the basename minus its
+ * extension, validated against `SESSION_ID_RE` so a path-traversing value is
+ * never accepted. Returns null when absent or invalid.
+ */
+function sessionIdFromLinkScanPath(linkScanPath) {
     if (typeof linkScanPath !== 'string' || linkScanPath.length === 0)
         return null;
-    // The session UUID is the basename minus its extension. Validate against
-    // the same character class used everywhere else so we never accept a
-    // path-traversing value.
     const file = basename(linkScanPath);
     const dot = file.lastIndexOf('.');
     const sid = dot > 0 ? file.slice(0, dot) : file;
-    if (!SESSION_ID_RE.test(sid))
+    return SESSION_ID_RE.test(sid) ? sid : null;
+}
+/**
+ * Try to resolve the session_id synchronously from `CLAUDE_JOB_DIR/state.json`.
+ * Returns the validated session_id or null.
+ */
+export function resolveFromJobDir(claudeJobDir) {
+    const parsed = readAndParseJobState(claudeJobDir);
+    if (!parsed)
         return null;
-    return sid;
+    return sessionIdFromLinkScanPath(parsed.linkScanPath);
 }
 /**
  * Try to resolve the session_id synchronously from the PPID breadcrumb file.
@@ -123,6 +138,19 @@ export function resolveFromBreadcrumb(storagePath, ppid, processStartMs = Date.n
         return null;
     return sid;
 }
+/**
+ * Sanitize a cwd into the single filename segment used both by the collector's
+ * `writeCwdBreadcrumb()` (session-by-cwd breadcrumb) and by Claude Code's own
+ * transcript-directory naming under `~/.claude/projects/`: backslash, forward
+ * slash, and colon each become `-`. Must stay identical to
+ * `collector-script.ts` so both sides derive the same filename independently.
+ * Colons are stripped so a Windows drive letter (e.g. `C:`) never survives into
+ * a filename where `path.resolve()` on win32 would reinterpret it as a
+ * drive-relative component and read/write outside the intended directory.
+ */
+export function sanitizeCwdForFilename(cwd) {
+    return cwd.replace(/[\\/:]/g, '-');
+}
 /**
  * Try to resolve the session_id synchronously from the cwd breadcrumb file.
  * Fallback for platforms where the PPID breadcrumb never matches (see the
@@ -131,12 +159,7 @@ export function resolveFromBreadcrumb(storagePath, ppid, processStartMs = Date.n
 export function resolveFromCwd(storagePath, cwd) {
     if (typeof cwd !== 'string' || cwd.length === 0)
         return null;
-    // Same sanitization scheme as the collector's writeCwdBreadcrumb() /
-    // getTranscriptPath() — must stay identical so both sides derive the same
-    // filename independently. Colons are stripped too (unlike
-    // getTranscriptPath) so a Windows drive letter never survives into the
-    // filename — see the matching comment in writeCwdBreadcrumb().
-    const sanitizedCwd = cwd.replace(/[\\/:]/g, '-');
+    const sanitizedCwd = sanitizeCwdForFilename(cwd);
     const breadcrumbPath = resolve(storagePath, 'session-by-cwd', `${sanitizedCwd}.txt`);
     if (!existsSync(breadcrumbPath))
         return null;
@@ -354,4 +377,248 @@ export function isUnscopedAggregatorSessionId(id) {
         return false;
     return id.startsWith('local-') || id.startsWith('proxy-');
 }
+/**
+ * Read the naming fields from `CLAUDE_JOB_DIR/state.json`. Sibling to
+ * `resolveFromJobDir` (whose `string | null` contract is unchanged) — returns
+ * null when there is no readable state file. `sessionId` prefers an explicit
+ * `sessionId` field, falling back to the UUID embedded in `linkScanPath`.
+ *
+ * The sensitive `intent` (first-prompt CONTENT) is populated ONLY when
+ * `options.recordContent === true`; it is null otherwise. This gates the
+ * content field by construction (mirroring `DecisionTracker`'s `recordContent`
+ * gate) so a future consumer that copies the `name`/`nameSource` wiring cannot
+ * leak prompt content by simply reading `.intent`. Pass `config.recordContent`
+ * (already force-disabled under highSecurity) to stay compliant; the `name`/
+ * `nameSource` display labels are never gated.
+ */
+export function readJobState(claudeJobDir, options) {
+    const parsed = readAndParseJobState(claudeJobDir);
+    if (!parsed)
+        return null;
+    const sessionId = typeof parsed.sessionId === 'string' && SESSION_ID_RE.test(parsed.sessionId)
+        ? parsed.sessionId
+        : sessionIdFromLinkScanPath(parsed.linkScanPath);
+    const name = typeof parsed.name === 'string' && parsed.name.length > 0 ? parsed.name : null;
+    const nameSource = parsed.nameSource === 'user' || parsed.nameSource === 'auto' ? parsed.nameSource : null;
+    const intent = options?.recordContent === true && typeof parsed.intent === 'string' && parsed.intent.length > 0
+        ? parsed.intent
+        : null;
+    return { sessionId, name, nameSource, intent };
+}
+// Bounded transcript reads: scan at most this many bytes back from EOF, one
+// chunk at a time, to find the last `ai-title`. A degenerate huge transcript
+// with no title in its tail costs at most MAX_SCAN_BYTES of IO, never the
+// whole file.
+const TRANSCRIPT_TITLE_CHUNK_BYTES = 64 * 1024;
+const TRANSCRIPT_TITLE_MAX_SCAN_BYTES = 1024 * 1024;
+/**
+ * Scan `text` (a suffix of a transcript JSONL file) for the LAST `ai-title`
+ * record and return its `aiTitle` (raw, unredacted — the caller redacts).
+ * `firstFragmentComplete` must be true only when `text` begins exactly at a
+ * file/line boundary; otherwise the substring before the first newline is a
+ * partial line whose start lies in an earlier, unread region and is skipped.
+ * Scanning newest-first means the first match is the file's last `ai-title`.
+ */
+export function findLastAiTitleInText(text, firstFragmentComplete) {
+    const parts = text.split('\n');
+    for (let i = parts.length - 1; i >= 0; i--) {
+        if (i === 0 && !firstFragmentComplete)
+            break; // partial leading line — its start is unread
+        const line = parts[i];
+        if (line.length === 0)
+            continue;
+        // Cheap pre-filter: `ai-title` records are rare, so skip JSON.parse unless
+        // the marker is present at all.
+        if (!line.includes('"ai-title"'))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (parsed.type === 'ai-title' &&
+            typeof parsed.aiTitle === 'string' &&
+            parsed.aiTitle.length > 0) {
+            return parsed.aiTitle;
+        }
+    }
+    return null;
+}
+/**
+ * Locate a session's transcript file under `<projectsDir>/<slug>/<sessionId>.jsonl`.
+ *
+ * Claude Code names each project subdirectory with a slug derived from the cwd,
+ * but that scheme is NOT the same as our breadcrumb `sanitizeCwdForFilename`
+ * (Claude Code also replaces `.` — so `/repo/.claude/wt` becomes
+ * `-repo--claude-wt`). Rather than mirror an undocumented slug scheme that can
+ * drift, we exploit the fact that a session id is a UUID — globally unique
+ * across every project slug — and find the one subdirectory that contains
+ * `<sessionId>.jsonl`. Returns the first match, or null.
+ */
+function findTranscriptPath(projectsDir, sessionId) {
+    const fileName = `${sessionId}.jsonl`;
+    let entries;
+    try {
+        entries = readdirSync(projectsDir);
+    }
+    catch (err) {
+        logger.debug('projects dir unreadable', { error: String(err) });
+        return null;
+    }
+    for (const entry of entries) {
+        const candidate = resolve(projectsDir, entry, fileName);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Read the last `ai-title` from a session's transcript JSONL, redacted.
+ * Locates the transcript by matching `<sessionId>.jsonl` under any project slug
+ * (see `findTranscriptPath` — robust to Claude Code's cwd-slug scheme). Reads
+ * BOUNDED — reverse-scans the file's tail one chunk at a time up to
+ * `TRANSCRIPT_TITLE_MAX_SCAN_BYTES`, never slurping the whole file. Returns null
+ * on any miss (no file, no title, bad sessionId) and never throws.
+ *
+ * @param projectsDir Override for `~/.claude/projects` (test seam).
+ */
+export function readTranscriptTitle(input) {
+    const { sessionId } = input;
+    if (!SESSION_ID_RE.test(sessionId))
+        return null;
+    const projectsDir = input.projectsDir ?? resolve(homedir(), '.claude', 'projects');
+    const transcriptPath = findTranscriptPath(projectsDir, sessionId);
+    if (transcriptPath === null)
+        return null;
+    let fd;
+    let size;
+    try {
+        size = statSync(transcriptPath).size;
+        if (size === 0)
+            return null;
+        fd = openSync(transcriptPath, fsConstants.O_RDONLY);
+    }
+    catch (err) {
+        logger.debug('transcript unreadable', { error: String(err) });
+        return null;
+    }
+    try {
+        let pos = size;
+        // Accumulate raw chunks and decode the contiguous tail as ONE buffer each
+        // iteration, so a multi-byte UTF-8 sequence straddling a 64KB chunk
+        // boundary is decoded intact — decoding each chunk in isolation would
+        // corrupt a straddling character to U+FFFD on both sides.
+        const chunks = [];
+        while (pos > 0 && size - pos < TRANSCRIPT_TITLE_MAX_SCAN_BYTES) {
+            const chunkSize = Math.min(TRANSCRIPT_TITLE_CHUNK_BYTES, pos);
+            pos -= chunkSize;
+            const buffer = Buffer.alloc(chunkSize);
+            const bytesRead = readSync(fd, buffer, 0, chunkSize, pos);
+            chunks.unshift(bytesRead === chunkSize ? buffer : buffer.subarray(0, bytesRead));
+            const acc = Buffer.concat(chunks).toString('utf-8');
+            // `pos === 0` means `acc` now starts at the file head, so its first line
+            // is complete; otherwise the leading fragment is partial and skipped.
+            const title = findLastAiTitleInText(acc, pos === 0);
+            if (title !== null)
+                return redactSensitive(title);
+        }
+        return null;
+    }
+    catch (err) {
+        logger.debug('transcript read failed', { error: String(err) });
+        return null;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Directory basenames too generic to serve as a session label. Single source
+ * of truth for the guard `SessionTracker`'s streaming cwd fallback also uses. A
+ * degenerate startup cwd yields no authoritative `cwd` name (step 4 falls
+ * through to null), leaving the tracker's streaming fallback free to upgrade to
+ * a better name from a later tool call's cwd.
+ */
+export const DEGENERATE_NAMES = new Set([
+    'tmp',
+    'temp',
+    'var',
+    'usr',
+    'opt',
+    'home',
+    '.',
+    '..',
+    '',
+]);
+/**
+ * Pure precedence decision for a session's display name (first hit wins):
+ *   1. state.json `name` where `nameSource === 'user'`  → `user`
+ *   2. transcript last `ai-title`                        → `ai-title`
+ *   3. state.json `name` where `nameSource === 'auto'`   → `auto`
+ *   4. basename(cwd), unless degenerate                  → `cwd`
+ *   5. null
+ * Does no IO and gates on nothing: callers pass already-read values and redact
+ * the returned name at each sink.
+ */
+export function resolveSessionName(inputs) {
+    const jobState = inputs.jobState ?? null;
+    if (jobState && jobState.nameSource === 'user' && jobState.name) {
+        return { name: jobState.name, source: 'user' };
+    }
+    if (inputs.transcriptTitle && inputs.transcriptTitle.length > 0) {
+        return { name: inputs.transcriptTitle, source: 'ai-title' };
+    }
+    if (jobState && jobState.nameSource === 'auto' && jobState.name) {
+        return { name: jobState.name, source: 'auto' };
+    }
+    const cwd = inputs.cwd;
+    if (typeof cwd === 'string' && cwd.length > 0) {
+        const base = basename(cwd);
+        if (base.length > 0 && !DEGENERATE_NAMES.has(base.toLowerCase())) {
+            return { name: base, source: 'cwd' };
+        }
+    }
+    return null;
+}
+/**
+ * Trust rank of a session-name source; LOWER is more trusted. Mirrors
+ * `resolveSessionName`'s precedence exactly: `user`(0) > `ai-title`(1) >
+ * `auto`(2) > `cwd`(3). Used to decide whether a freshly re-resolved name may
+ * replace the one already in place (see `shouldReplaceSessionName`).
+ */
+export function sessionNameSourceRank(source) {
+    switch (source) {
+        case 'user':
+            return 0;
+        case 'ai-title':
+            return 1;
+        case 'auto':
+            return 2;
+        case 'cwd':
+            return 3;
+    }
+}
+/**
+ * Whether a re-resolved name from `next` should replace a name currently
+ * sourced from `current`. Freshness re-resolution (Phase 2) re-reads Claude
+ * Code's name sources at persist/shutdown time so a refined `ai-title` — or a
+ * name a human later assigns — supersedes the first-prompt guess.
+ *
+ * Replaces only when `next` is at least as trusted as `current`
+ * (`rank(next) <= rank(current)`): an equal-or-better source wins (which also
+ * picks up refined text for the SAME source, e.g. an updated `ai-title`),
+ * while a strictly-less-trusted source is refused. That refusal is the
+ * load-bearing invariant: a `user`-sourced name is NEVER downgraded to
+ * `auto`/`cwd`, even if the job-state file that supplied it later disappears
+ * and re-resolution would otherwise fall through to the transcript title or
+ * the cwd basename. A `null` current source (session not yet named) always
+ * accepts.
+ */
+export function shouldReplaceSessionName(current, next) {
+    if (current === null)
+        return true;
+    return sessionNameSourceRank(next) <= sessionNameSourceRank(current);
+}
 //# sourceMappingURL=session-resolver.js.map