myshell-tools 3.0.0 → 3.2.0

package/dist/infra/credentials.d.ts

@@ -17,7 +17,33 @@
  */
 export interface Credentials {
     claudeOauthToken?: string;
+    claudeTokenCapturedAt?: string;
+}
+export interface ClaudeTokenStatus {
+    /** ISO string of when the token was saved. */
+    readonly capturedAt: string;
+    /** ISO string of the computed expiry (capturedAt + lifetimeDays). */
+    readonly expiresAt: string;
+    /** Whole days remaining until expiry (floor). 0 when expiring today, negative when expired. */
+    readonly daysLeft: number;
+    /** True when daysLeft <= 0. */
+    readonly expired: boolean;
+    /** True when 0 < daysLeft <= warnWithinDays. */
+    readonly nearExpiry: boolean;
 }
+/**
+ * Compute token lifetime status from a stored ISO capture timestamp.
+ *
+ * Pure — no I/O, no Date.now() inside. Pass `nowMs` for deterministic testing.
+ * Never throws.
+ *
+ * @param capturedAtIso  - ISO string stored at save time, or undefined/null.
+ * @param nowMs          - Current epoch-ms (e.g. Date.now() from the caller).
+ * @param lifetimeDays   - Total token lifetime in days (default 365).
+ * @param warnWithinDays - Warn when this many days or fewer remain (default 14).
+ * @returns Status object, or null when capturedAtIso is missing or unparseable.
+ */
+export declare function claudeTokenStatus(capturedAtIso: string | undefined, nowMs: number, lifetimeDays?: number, warnWithinDays?: number): ClaudeTokenStatus | null;
 /**
  * Load stored credentials. Never throws — missing or corrupt files return `{}`.
  */
@@ -51,8 +77,17 @@ export declare function claudeEnv(baseEnv: NodeJS.ProcessEnv, token: string | nu
 /**
  * Persist the Claude OAuth token atomically to
  * `~/.myshell-tools/credentials.json` with restrictive permissions (0o600).
+ *
+ * Records `claudeTokenCapturedAt` (ISO timestamp) so the token's age can be
+ * tracked for expiry warnings.
  */
 export declare function saveClaudeToken(token: string, homeDir?: string): Promise<void>;
+/**
+ * Load the ISO timestamp recorded when the Claude OAuth token was last saved.
+ * Returns `undefined` when no token has been saved, or when the stored value
+ * is missing from an older credential file. Never throws.
+ */
+export declare function loadClaudeTokenCapturedAt(homeDir?: string): Promise<string | undefined>;
 /**
  * Remove the stored Claude OAuth token. Writes the file back without the
  * token key so any future credential fields are preserved.

package/dist/infra/credentials.js

@@ -19,6 +19,40 @@ import { mkdir, readFile, chmod } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { atomicWrite } from './atomic.js';
+/**
+ * Compute token lifetime status from a stored ISO capture timestamp.
+ *
+ * Pure — no I/O, no Date.now() inside. Pass `nowMs` for deterministic testing.
+ * Never throws.
+ *
+ * @param capturedAtIso  - ISO string stored at save time, or undefined/null.
+ * @param nowMs          - Current epoch-ms (e.g. Date.now() from the caller).
+ * @param lifetimeDays   - Total token lifetime in days (default 365).
+ * @param warnWithinDays - Warn when this many days or fewer remain (default 14).
+ * @returns Status object, or null when capturedAtIso is missing or unparseable.
+ */
+export function claudeTokenStatus(capturedAtIso, nowMs, lifetimeDays = 365, warnWithinDays = 14) {
+    try {
+        if (capturedAtIso === undefined || capturedAtIso === null || capturedAtIso.length === 0) {
+            return null;
+        }
+        const capturedMs = new Date(capturedAtIso).getTime();
+        if (!Number.isFinite(capturedMs)) {
+            return null;
+        }
+        const lifetimeMs = lifetimeDays * 24 * 60 * 60 * 1000;
+        const expiresMs = capturedMs + lifetimeMs;
+        const expiresAt = new Date(expiresMs).toISOString();
+        const msLeft = expiresMs - nowMs;
+        const daysLeft = Math.floor(msLeft / (24 * 60 * 60 * 1000));
+        const expired = daysLeft <= 0;
+        const nearExpiry = !expired && daysLeft <= warnWithinDays;
+        return { capturedAt: capturedAtIso, expiresAt, daysLeft, expired, nearExpiry };
+    }
+    catch {
+        return null;
+    }
+}
 // ---------------------------------------------------------------------------
 // Path helpers (pure)
 // ---------------------------------------------------------------------------
@@ -46,6 +80,9 @@ function parseCredentials(raw) {
         if (typeof obj['claudeOauthToken'] === 'string' && obj['claudeOauthToken'].length > 0) {
             result.claudeOauthToken = obj['claudeOauthToken'];
         }
+        if (typeof obj['claudeTokenCapturedAt'] === 'string' && obj['claudeTokenCapturedAt'].length > 0) {
+            result.claudeTokenCapturedAt = obj['claudeTokenCapturedAt'];
+        }
         return result;
     }
     catch {
@@ -114,6 +151,9 @@ export function claudeEnv(baseEnv, token) {
 /**
  * Persist the Claude OAuth token atomically to
  * `~/.myshell-tools/credentials.json` with restrictive permissions (0o600).
+ *
+ * Records `claudeTokenCapturedAt` (ISO timestamp) so the token's age can be
+ * tracked for expiry warnings.
  */
 export async function saveClaudeToken(token, homeDir) {
     const home = homeDir ?? homedir();
@@ -124,7 +164,11 @@ export async function saveClaudeToken(token, homeDir) {
     await mkdir(dir, { recursive: true, mode: 0o700 });
     // Load existing credentials so we only replace the token key, preserving others.
     const existing = await loadCredentials(homeDir);
-    const updated = { ...existing, claudeOauthToken: token };
+    const updated = {
+        ...existing,
+        claudeOauthToken: token,
+        claudeTokenCapturedAt: new Date().toISOString(),
+    };
     // atomicWrite with mode 0o600 guarantees the temp file is never more permissive
     // than the final destination — no world-readable window before the rename.
     await atomicWrite(path, JSON.stringify(updated, null, 2), 0o600);
@@ -137,6 +181,20 @@ export async function saveClaudeToken(token, homeDir) {
         // Cross-platform best-effort only — never throws
     }
 }
+/**
+ * Load the ISO timestamp recorded when the Claude OAuth token was last saved.
+ * Returns `undefined` when no token has been saved, or when the stored value
+ * is missing from an older credential file. Never throws.
+ */
+export async function loadClaudeTokenCapturedAt(homeDir) {
+    try {
+        const creds = await loadCredentials(homeDir);
+        return creds.claudeTokenCapturedAt;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Remove the stored Claude OAuth token. Writes the file back without the
  * token key so any future credential fields are preserved.

package/dist/infra/credentials.js.map

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

package/dist/infra/health.d.ts

@@ -0,0 +1,57 @@
+/**
+ * src/infra/health.ts — Self-health evaluation for myshell-tools.
+ *
+ * The product goal is "it just works": the user should never run a diagnostic
+ * command. Instead the control panel evaluates its own environment health at
+ * startup and surfaces a short, actionable warning ONLY when something is
+ * actually wrong. No problems → nothing shown (silence == healthy).
+ *
+ * This module covers the diagnostics that are NOT already visible elsewhere in
+ * the UI: Node version, state-directory writability, and pricing-table
+ * staleness. Provider install/auth status and Claude-token expiry are already
+ * rendered in the header, so they are intentionally not duplicated here.
+ *
+ * `evaluateHealth` is PURE (no I/O) so it is trivially testable. The one piece
+ * that needs I/O — probing whether the state directory is writable — is a
+ * separate function the caller runs once at startup and feeds in.
+ */
+type HealthSeverity = 'warn' | 'error';
+export interface HealthIssue {
+    /** Stable identifier for the issue (useful for tests and de-duplication). */
+    readonly id: string;
+    readonly severity: HealthSeverity;
+    /** One-line, human-readable message that already includes the fix. */
+    readonly message: string;
+}
+export interface HealthInputs {
+    /** process.version, e.g. "v20.20.0". */
+    readonly nodeVersion: string;
+    /** Whether the .myshell-tools state directory could be written to. */
+    readonly stateWritable: boolean;
+    /** Whether the bundled pricing seed is past its staleness window. */
+    readonly pricingStale: boolean;
+    /** Minimum supported Node major version (defaults to 20). */
+    readonly minNodeMajor?: number;
+}
+/**
+ * Parse the major version from a Node version string ("v20.20.0" → 20).
+ * Returns null when the string can't be parsed (so callers can skip the check
+ * rather than emit a bogus warning). Pure; never throws.
+ */
+export declare function nodeMajor(version: string): number | null;
+/**
+ * Evaluate environment health and return the issues worth surfacing.
+ *
+ * Pure — takes a snapshot of inputs and returns zero or more issues, most
+ * severe first (errors before warnings). An empty array means "all healthy,
+ * show nothing".
+ */
+export declare function evaluateHealth(inputs: HealthInputs): HealthIssue[];
+/**
+ * Probe whether the .myshell-tools state directory under `cwd` is writable.
+ *
+ * Creates the directory if needed, writes and removes a temp file. Returns true
+ * on success, false on any I/O error. Never throws.
+ */
+export declare function probeStateWritable(cwd: string): Promise<boolean>;
+export {};

package/dist/infra/health.js

@@ -0,0 +1,96 @@
+/**
+ * src/infra/health.ts — Self-health evaluation for myshell-tools.
+ *
+ * The product goal is "it just works": the user should never run a diagnostic
+ * command. Instead the control panel evaluates its own environment health at
+ * startup and surfaces a short, actionable warning ONLY when something is
+ * actually wrong. No problems → nothing shown (silence == healthy).
+ *
+ * This module covers the diagnostics that are NOT already visible elsewhere in
+ * the UI: Node version, state-directory writability, and pricing-table
+ * staleness. Provider install/auth status and Claude-token expiry are already
+ * rendered in the header, so they are intentionally not duplicated here.
+ *
+ * `evaluateHealth` is PURE (no I/O) so it is trivially testable. The one piece
+ * that needs I/O — probing whether the state directory is writable — is a
+ * separate function the caller runs once at startup and feeds in.
+ */
+import { mkdir, writeFile, rm, access } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+/**
+ * Parse the major version from a Node version string ("v20.20.0" → 20).
+ * Returns null when the string can't be parsed (so callers can skip the check
+ * rather than emit a bogus warning). Pure; never throws.
+ */
+export function nodeMajor(version) {
+    const m = /^v?(\d+)\./.exec(version.trim());
+    if (m === null)
+        return null;
+    const n = parseInt(m[1] ?? '', 10);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Evaluate environment health and return the issues worth surfacing.
+ *
+ * Pure — takes a snapshot of inputs and returns zero or more issues, most
+ * severe first (errors before warnings). An empty array means "all healthy,
+ * show nothing".
+ */
+export function evaluateHealth(inputs) {
+    const minMajor = inputs.minNodeMajor ?? 20;
+    const issues = [];
+    // State directory not writable — the most serious: nothing persists.
+    if (!inputs.stateWritable) {
+        issues.push({
+            id: 'state-not-writable',
+            severity: 'error',
+            message: "Can't write to the .myshell-tools state directory — conversations and " +
+                'cost tracking will not be saved. Check the directory permissions.',
+        });
+    }
+    // Node below the supported floor — the compiled CLI targets Node >= minMajor.
+    const major = nodeMajor(inputs.nodeVersion);
+    if (major !== null && major < minMajor) {
+        issues.push({
+            id: 'node-too-old',
+            severity: 'warn',
+            message: `Node ${inputs.nodeVersion} is below the supported v${minMajor} — upgrade Node if you hit errors.`,
+        });
+    }
+    // Stale pricing seed — cost estimates may drift; updating refreshes them.
+    if (inputs.pricingStale) {
+        issues.push({
+            id: 'pricing-stale',
+            severity: 'warn',
+            message: 'Cost estimates may be out of date — update to refresh them: npm install -g myshell-tools@latest',
+        });
+    }
+    return issues;
+}
+// ---------------------------------------------------------------------------
+// I/O probe (run once at startup; result fed into evaluateHealth)
+// ---------------------------------------------------------------------------
+/**
+ * Probe whether the .myshell-tools state directory under `cwd` is writable.
+ *
+ * Creates the directory if needed, writes and removes a temp file. Returns true
+ * on success, false on any I/O error. Never throws.
+ */
+export async function probeStateWritable(cwd) {
+    const stateDir = join(cwd, '.myshell-tools');
+    const probe = join(stateDir, '.health-probe');
+    try {
+        await mkdir(stateDir, { recursive: true });
+        await writeFile(probe, '');
+        await rm(probe, { force: true });
+        await access(stateDir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/infra/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/infra/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA2BjC,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,MAAM,QAAQ,GAAG,MAAM,CAAC,YAAY,IAAI,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,qEAAqE;IACrE,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,oBAAoB;YACxB,QAAQ,EAAE,OAAO;YACjB,OAAO,EACL,wEAAwE;gBACxE,mEAAmE;SACtE,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,cAAc;YAClB,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,QAAQ,MAAM,CAAC,WAAW,4BAA4B,QAAQ,oCAAoC;SAC5G,CAAC,CAAC;IACL,CAAC;IAED,0EAA0E;IAC1E,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC;YACV,EAAE,EAAE,eAAe;YACnB,QAAQ,EAAE,MAAM;YAChB,OAAO,EACL,iGAAiG;SACpG,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,kEAAkE;AAClE,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAW;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC9C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC3B,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjC,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/infra/insights.d.ts

@@ -18,6 +18,11 @@ export interface SpendSummary {
     readonly totalUsd: number;
     /** Total number of ledger entries (calls). */
     readonly calls: number;
+    /** Real tokens (input + output) used today (UTC). The transparent primary
+     *  signal — measured, not an estimate, unlike the USD figures. */
+    readonly todayTokens: number;
+    /** Real tokens (input + output) used across all time. */
+    readonly totalTokens: number;
     /** Per-provider breakdown keyed by ProviderId string. */
     readonly byProvider: Record<string, {
         readonly usd: number;
@@ -64,3 +69,12 @@ export declare function providerHealth(entries: LedgerEntry[]): ProviderHealth[]
  * @param n - Amount in US dollars (may be 0).
  */
 export declare function formatUsd(n: number): string;
+/**
+ * Format a token count compactly: 942 → "942", 12_400 → "12.4k", 3_000_000 → "3M".
+ *
+ * Tokens are REAL measured values (unlike the USD estimates), so this is the
+ * primary live signal. Pure; never throws. Negative/NaN inputs clamp to "0".
+ *
+ * @param n - Token count.
+ */
+export declare function formatTokens(n: number): string;

package/dist/infra/insights.js

@@ -22,11 +22,16 @@ export function summarizeSpend(entries, nowIso) {
     const todayDate = nowIso.slice(0, 10); // 'YYYY-MM-DD'
     let todayUsd = 0;
     let totalUsd = 0;
+    let todayTokens = 0;
+    let totalTokens = 0;
     const byProvider = {};
     for (const entry of entries) {
         totalUsd += entry.usd;
+        const entryTokens = entry.inputTokens + entry.outputTokens;
+        totalTokens += entryTokens;
         if (entry.timestamp.slice(0, 10) === todayDate) {
             todayUsd += entry.usd;
+            todayTokens += entryTokens;
         }
         const existing = byProvider[entry.provider];
         if (existing !== undefined) {
@@ -41,6 +46,8 @@ export function summarizeSpend(entries, nowIso) {
         todayUsd,
         totalUsd,
         calls: entries.length,
+        todayTokens,
+        totalTokens,
         byProvider,
     };
 }
@@ -102,4 +109,28 @@ export function providerHealth(entries) {
 export function formatUsd(n) {
     return '$' + n.toFixed(4);
 }
+// ---------------------------------------------------------------------------
+// formatTokens
+// ---------------------------------------------------------------------------
+/**
+ * Format a token count compactly: 942 → "942", 12_400 → "12.4k", 3_000_000 → "3M".
+ *
+ * Tokens are REAL measured values (unlike the USD estimates), so this is the
+ * primary live signal. Pure; never throws. Negative/NaN inputs clamp to "0".
+ *
+ * @param n - Token count.
+ */
+export function formatTokens(n) {
+    if (!Number.isFinite(n) || n <= 0)
+        return '0';
+    if (n < 1000)
+        return String(Math.round(n));
+    if (n < 1_000_000) {
+        const k = n / 1000;
+        // One decimal, but drop a trailing ".0" (12000 → "12k", 12400 → "12.4k").
+        return (Number.isInteger(k) ? String(k) : k.toFixed(1)) + 'k';
+    }
+    const m = n / 1_000_000;
+    return (Number.isInteger(m) ? String(m) : m.toFixed(1)) + 'M';
+}
 //# sourceMappingURL=insights.js.map

package/dist/infra/insights.js.map

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

package/dist/interface/menu.d.ts

@@ -24,6 +24,9 @@ import type { Provider, ProviderId, SandboxLevel } from '../providers/port.js';
 import type { OutputSink } from './render.js';
 import type { LoginMethod } from '../commands/login.js';
 import type { UpdateCheckResult } from '../infra/update-check.js';
+import type { ClaudeTokenStatus } from '../infra/credentials.js';
+import { claudeTokenStatus } from '../infra/credentials.js';
+import type { HealthIssue } from '../infra/health.js';
 export interface MenuContext {
     readonly version: string;
     readonly clock: Clock;
@@ -92,6 +95,30 @@ export interface MenuContext {
      * Used only for the opt-in auto-update path.
      */
     readonly relaunch?: () => Promise<number>;
+    /**
+     * Optional pre-computed Claude token lifetime status for testing. When provided,
+     * `startMenu` uses this instead of loading from disk, allowing tests to drive
+     * the token-expiry header warning without touching the filesystem.
+     *
+     * Pass `null` explicitly to suppress any token warning; omit (undefined) to
+     * trigger the real disk read via `loadClaudeTokenCapturedAt`.
+     */
+    readonly claudeTokenInfo?: ClaudeTokenStatus | null;
+    /**
+     * Optional override for npx-context detection (testing). When provided,
+     * `startMenu` uses this instead of inspecting `process.argv[1]`, so tests can
+     * drive the "running under npx" warning + auto-update suppression without a
+     * real npx cache path. Omit (undefined) to trigger the real detection.
+     */
+    readonly runningUnderNpx?: boolean;
+    /**
+     * Pre-computed environment health issues (Node version, state-dir writable,
+     * pricing staleness) surfaced automatically below the header — only when a
+     * problem exists. Computed once at startup by cli.ts (the diagnostics don't
+     * change in-session) so the user never has to run a separate health command.
+     * Omit/empty → nothing is shown.
+     */
+    readonly healthIssues?: readonly HealthIssue[];
 }
 /**
  * Parse a yes/no answer from a raw input line, with a configurable default.
@@ -150,6 +177,35 @@ export declare function defaultAliasHint(shell: string | undefined, platform: st
  * All arithmetic is pure — no Date, no Math.random.
  */
 export declare function relativeTime(thenMs: number, nowMs: number): string;
+/**
+ * Build the short version-status suffix shown next to the version number in the
+ * header title — so the user always knows, at a glance, whether they are current.
+ *
+ * Pure — no I/O. Returns a leading-space string ready to append to the title:
+ *   - update available + known latest → ` → 3.1.0 available`
+ *   - up to date (latest known, no update) → ` (latest)`
+ *   - check failed / offline (latest unknown) → `` (claim nothing)
+ *
+ * @param updateInfo - Result of the update check, or undefined when not run.
+ */
+export declare function versionStatusLabel(updateInfo?: UpdateCheckResult): string;
+/**
+ * Detect whether myshell-tools is running via `npx` rather than a global install.
+ *
+ * Pure — takes the running script path (process.argv[1]) and the environment.
+ * npx executes packages from a cache directory containing a `_npx` segment
+ * (e.g. ~/.npm/_npx/<hash>/node_modules/myshell-tools/dist/cli.js), so the
+ * presence of that segment in the script path is the reliable signal. Handles
+ * both POSIX and Windows separators. Never throws.
+ *
+ * Why it matters: self-update runs `npm install -g`, which an npx invocation
+ * will ignore on the next run (npx re-serves its own cache). So under npx we
+ * skip silent auto-update and instead tell the user to install globally.
+ *
+ * @param scriptPath - The running script path (typically process.argv[1]).
+ * @param env        - Environment to read npm_* hints from.
+ */
+export declare function isRunningUnderNpx(scriptPath: string | undefined, env: NodeJS.ProcessEnv): boolean;
 /**
  * Build the header box lines (provider status) from real EnvironmentStatus.
  * Returns string[] safe to pass as the `lines` arg to box().
@@ -159,14 +215,23 @@ export declare function relativeTime(thenMs: number, nowMs: number): string;
  *   ⚠️  when ps.installed && !ps.authenticated  (append " not signed in")
  *   ❌  when !ps.installed                       (append install command)
  * Plan label appended when ps.plan is non-null (e.g. " (Max x5)").
+ *
+ * @param claudeToken - Optional pre-computed token lifetime status. When the token
+ *   is near expiry or expired, ONE concise warning line is appended. Computed by
+ *   the caller (startMenu) so this function stays pure and I/O-free.
  */
-export declare function renderHeaderLines(env: EnvironmentStatus, _version: string): string[];
+export declare function renderHeaderLines(env: EnvironmentStatus, _version: string, claudeToken?: ReturnType<typeof claudeTokenStatus>): string[];
 /**
- * Render the budget/spend status line shown beneath the provider header.
+ * Render the activity status line shown beneath the provider header.
+ *
+ * This is a SUBSCRIPTION tool, not an API-key tool — per-token dollar figures
+ * don't map to flat subscription billing and read as misleading bloat, so the
+ * always-on line shows REAL, measured signals only: task count and tokens. The
+ * estimated-dollar view lives on-demand in `myshell-tools cost`, clearly
+ * captioned there as an API-equivalent (not your actual bill).
  *
- * Uses real numbers only — all values come from the SpendSummary which is
- * derived from `readLedger`. No digit-% literals appear in this function; it
- * shows dollar amounts only.
+ * Uses real numbers only — all values come from the SpendSummary derived from
+ * `readLedger`. No digit-% literals appear here.
  *
  * @param spend - Output of summarizeSpend() over real ledger entries.
  * @param color - When false, no ANSI escape codes are emitted.