@shardflux/cli 0.18.1 → 0.19.0

package/dist/files-mirror.js

@@ -675,8 +675,19 @@ export class FilesMirror {
  * as refs/worktree/shard/seed and in the hub as refs/shard/seed/<name>. Mirrors leave out what it already contains,
  * so the user's own uncommitted edits never show as the conversation's change. Threads on one computer are worktrees
  * of one repository (0.16.0+), so the seed is per worktree; the shared refs/shard/seed of earlier seeds is read, and
- * still written, only in the repository's main worktree.
+ * still written, only in the repository's main worktree. With $4 = background (0.19.1+) the hub push runs detached
+ * in the VM and the script returns once the seed is recorded: the hub is on the project's network volume, where the
+ * push took 6-10 s on every start (staging, coding 37), on the way to the first prompt.
  */
+// It is embedded in single quotes below: never a single quote in it. A blobless partial clone (0.19.0+) pushes only
+// when the hub already has the seed history; otherwise the push would fetch every historic blob first. Its background
+// backfill completes the repository for later pushes.
+const SEED_PUSH = `set -u
+seed=$1; name=$2; hub=$3; cd "$4"
+push=1; if [ "$(git config --bool remote.origin.promisor 2>/dev/null || true)" = true ]; then push=0
+for c in "$seed" "$seed^1"; do o=$(git rev-parse -q --verify "$c^{commit}" 2>/dev/null) && git --git-dir="$hub" cat-file -e "$o^{commit}" 2>/dev/null && push=1 && break; done; fi
+if [ -d "$hub" ] && [ "$push" = 1 ]; then git -c core.hooksPath=/dev/null push -q "$hub" "+$seed:refs/shard/seed/$name" >/dev/null 2>&1 || true; fi
+`;
 export const SEED_SNAPSHOT = `set -eu
 cd "$1"
 main=0; [ "$(git rev-parse --absolute-git-dir)" = "$(git rev-parse --path-format=absolute --git-common-dir)" ] && main=1
@@ -691,13 +702,18 @@ seed=$(GIT_AUTHOR_NAME=Shardflux GIT_AUTHOR_EMAIL=seed@shardflux.dev GIT_COMMITT
 git update-ref refs/worktree/shard/seed "$seed"
 if [ "$main" = 1 ]; then git update-ref refs/shard/seed "$seed"; fi
 fi
-if [ -d "$3" ]; then git -c core.hooksPath=/dev/null push -q "$3" "+$seed:refs/shard/seed/$2" >/dev/null 2>&1 || true; fi
+push='${SEED_PUSH}'
+if [ "\${4:-}" = background ]; then
+  if command -v setsid >/dev/null 2>&1; then (setsid sh -c "$push" shard-seed-push "$seed" "$2" "$3" "$PWD" >/dev/null 2>&1 </dev/null &)
+  else (sh -c "$push" shard-seed-push "$seed" "$2" "$3" "$PWD" >/dev/null 2>&1 </dev/null &); fi
+else sh -c "$push" shard-seed-push "$seed" "$2" "$3" "$PWD"; fi
 printf '%s\n' "$seed"
 `;
 /** Best effort: without a snapshot the folder also lists the start state's own edits. */
 export async function recordSeedSnapshot(ws, c, signal) {
     try {
-        const r = await ws.cell().exec.run(['sh', '-c', SEED_SNAPSHOT, 'shard-seed', c.worktree_path, c.branch.replace(/^shard\//, ''), HUB_PATH], { timeoutMs: 120_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
+        // The hub push runs detached in the VM: it is on the project volume and never on the way to the first prompt.
+        const r = await ws.cell().exec.run(['sh', '-c', SEED_SNAPSHOT, 'shard-seed', c.worktree_path, c.branch.replace(/^shard\//, ''), HUB_PATH, 'background'], { timeoutMs: 120_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
         return r.exitCode === 0 ? r.stdout.trim() : null;
     }
     catch (error) {

package/dist/format.js

@@ -376,7 +376,7 @@ function objectTable(rows, columns) {
     const cols = columns.filter(([k]) => objs.some((o) => k in o));
     return table(cols.map(([, h]) => h), objs.map((o) => cols.map(([k]) => (k === 'percent_used' && typeof o[k] === 'number' ? `${o[k]}%` : scalar(o[k])))));
 }
-const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'exhausted_reason', 'egress_override', 'meters', 'allowances', 'exhausted', 'alert_thresholds', 'spend_cap']);
+const USAGE_KNOWN = new Set(['plan', 'period', 'measurement', 'allowance_exhausted', 'exhausted_reason', 'egress_override', 'meters', 'allowances', 'exhausted', 'alert_thresholds', 'spend_cap', 'gpu']);
 /** Minor units as money (the overage block): `$3.00` for usd, else `3.00 EUR`. A fractional minor amount (a sub-cent rate) keeps its digits. */
 export function capMoney(minor, currency) {
     if (typeof minor !== 'number')
@@ -432,6 +432,39 @@ function spendCapText(cap) {
     }
     return out;
 }
+/** Hours for people: at most two decimals (`25`, `3.25`, `0.2`). */
+const hoursText = (h) => String(Math.round(h * 100) / 100);
+/**
+ * The GPU-hours lines of the summary (0.19.0; `gpu`, SDK 0.25.0): used of included with the overage past them, then,
+ * while the GPU is stopped (cap_state gpu_blocked), why and what brings it back. Workspaces keep running meanwhile.
+ * Nothing without `gpu` (plans without GPU-hours).
+ */
+function gpuLines(gpu, resetsAt) {
+    if (!isObject(gpu) || typeof gpu.used_hours !== 'number')
+        return [];
+    const included = typeof gpu.included_hours === 'number' ? gpu.included_hours : null;
+    let used = included === null ? `${hoursText(gpu.used_hours)} used (the plan includes none)` : `${hoursText(gpu.used_hours)} of ${hoursText(included)} used`;
+    const over = typeof gpu.overage_hours === 'number' ? gpu.overage_hours : 0;
+    if (included !== null && over > 0) {
+        const billed = typeof gpu.billed_overage_hours === 'number' ? gpu.billed_overage_hours : 0;
+        used += `, ${hoursText(over)} past the allowance${billed > 0 ? ` (${hoursText(billed)} billed as overage)` : ''}`;
+    }
+    const rows = [['GPU-hours', used]];
+    if (gpu.cap_state !== 'gpu_blocked')
+        return rows;
+    const resets = resetsAt ? ` (the period resets ${time(resetsAt)})` : '';
+    switch (gpu.blocked_reason) {
+        case 'overage_paused':
+            rows.push(['GPU', 'stopped (overage_paused): workspaces keep running; pay the past-due invoice (shard billing portal --open) and the GPU renders again']);
+            break;
+        case 'spend_cap_reached':
+            rows.push(['GPU', `stopped (spend_cap_reached): workspaces keep running; raise the spend cap (shard billing overage cap <dollars>), or wait for the reset${resets}`]);
+            break;
+        default:
+            rows.push(['GPU', `stopped (allowance_used): workspaces keep running; turn on overage (shard billing overage on --cap <dollars>), upgrade (shard billing plans), or wait for the reset${resets}`]);
+    }
+    return rows;
+}
 /**
  * The usage summary (GET /v1/organizations/{id}/usage/summary): plan, period, measurement
  * freshness, then meters and allowances as tables (cap state `overage` past an allowance while opt-in overage is on),
@@ -464,6 +497,8 @@ export function usageText(summary) {
     if (Array.isArray(s.allowances) && s.allowances.some((a) => isObject(a) && a.cap_state === 'storage_blocked')) {
         head.push(['retained state', 'used up: new workspaces and forks are refused (delete workspaces you no longer need, or upgrade)']);
     }
+    const resetsAt = isObject(s.period) ? [s.period.resets_at, s.period.end].find((t) => typeof t === 'string') : undefined;
+    head.push(...gpuLines(s.gpu, resetsAt));
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
             head.push([k.replace(/_/g, ' '), scalar(v)]);
@@ -1019,7 +1054,7 @@ export function egressVersionTable(rows) {
     return table(['VERSION', 'KIND', 'POLICY', 'BY', 'CREATED'], rows.map((v) => [String(v.version), v.kind, v.kind === 'cleared' ? '-' : egressPolicyLine({ mode: v.mode ?? 'allow_all', rules: v.rules, cidrs: v.cidrs }), `${v.created_by.type}:${v.created_by.id}`, time(v.created_at)]));
 }
 // ---- Overage settings (0.5.1; shard billing overage) -----------------------------------------------------------
-const RATE_UNITS = { ram_gib_hours: 'RAM GiB-hour', cpu_hours: 'CPU-hour' };
+const RATE_UNITS = { ram_gib_hours: 'RAM GiB-hour', cpu_hours: 'CPU-hour', gpu_hours: 'GPU-hour' };
 /**
  * The spend policy's overage settings for people (GET/PUT /v1/organizations/{id}/spend-policy): the state, the spend
  * cap and its bounds, the rates, and the next step. `saved` adds the version the change was saved as.

package/dist/handlers.js

@@ -21,4 +21,6 @@ import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
 import { THREAD_HANDLERS } from "./thread-on-computer.js";
 import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
 import { ACCOUNT_POOL_HANDLERS } from "./account-pool.js";
-export const HANDLERS = { ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { MOVE_HANDLERS } from "./move.js";
+import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
+export const HANDLERS = { ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS, 'agents config-sync': AGENT_CONFIG_HANDLERS['agents config-sync'] };

package/dist/local-sessions.d.ts

@@ -0,0 +1,60 @@
+export type SessionHarness = 'claude' | 'codex';
+export interface LocalSession {
+    harness: SessionHarness;
+    session_id: string;
+    /** The transcript (Claude) or rollout (Codex) file. */
+    file: string;
+    /** The session's working directory, as its transcript records it. */
+    cwd: string;
+    title: string;
+    updated_at: string;
+    bytes: number;
+    /** Where it was started: Claude's entrypoint (cli, claude-desktop, sdk-cli…) or Codex's originator (codex-tui…). */
+    source: string;
+}
+export interface SessionState {
+    /** A process has the session open right now. */
+    running: boolean;
+    /** working: a turn is in progress (never cut off); idle: between turns, or no process is running it. */
+    turn: 'working' | 'idle';
+    pid?: number;
+}
+type Env = Record<string, string | undefined>;
+type Rec = Record<string, unknown>;
+export declare const isSessionId: (id: string) => boolean;
+export declare const claudeConfigDir: (env: Env) => string;
+export declare const codexHome: (env: Env) => string;
+/** Claude Code's folder name under projects/ for a working directory (measured: a 268-character path → 200 + "-1qkjv5"). */
+export declare function claudeProjectName(cwd: string): string;
+/** Records appended after `offset` (whole lines only). */
+export declare function recordsAfter(file: string, offset: number): Rec[];
+/** Whether the transcript's last turn is still running, from its records (see the module comment). */
+export declare function claudeTurnFromRecords(records: Rec[]): 'working' | 'idle';
+export declare function codexTurnFromRecords(records: Rec[]): 'working' | 'idle';
+/** A project's sessions on this computer, newest first: those started in the folder or below it. */
+export declare function listLocalSessions(folder: string, env: Env, options?: {
+    harness?: SessionHarness;
+    limit?: number;
+}): LocalSession[];
+/** One session by id, wherever it was started. */
+export declare function findLocalSession(id: string, env: Env): LocalSession | null;
+/** Whether a turn is running now. A session no process has open is between turns, whatever its last record says. */
+export declare function sessionState(s: Pick<LocalSession, 'harness' | 'session_id' | 'file'>, env: Env, now?: number): SessionState;
+/** Whether someone typed in the local copy after it moved: a new prompt or turn after `offset`. */
+export declare function continuedAfter(s: Pick<LocalSession, 'harness' | 'file'>, offset: number): boolean;
+/**
+ * The transcript as whole lines, cut after its last complete record: a harness may be appending a record while a
+ * move reads it (between turns that is metadata, never part of a turn).
+ */
+export declare function completeRecords(bytes: Buffer): Buffer;
+/**
+ * The session's records with its working directory moved from `from` to `to`: Claude's and Codex's `cwd` fields (and
+ * Codex's workdir and workspace roots). Lines that do not mention `from` keep their exact bytes; message text,
+ * tool output and signed thinking are never changed.
+ */
+export declare function rewriteSessionPaths(bytes: Buffer, from: string, to: string): Buffer;
+/** Where the session's transcript lives under a home folder, relative to it (the VM's and the project space's layout). */
+export declare function homeRelativeTranscript(s: Pick<LocalSession, 'harness' | 'session_id' | 'file'>, cwd: string): string;
+/** The transcript file is a regular file: never follow a link out of the harness's store. */
+export declare function readTranscript(file: string): Buffer;
+export {};

package/dist/local-sessions.js

@@ -0,0 +1,445 @@
+/**
+ * Claude Code and Codex sessions on this computer, for `shard move` (0.19.0+): which ones belong to a project, whether
+ * a turn is running, and their transcripts with paths rewritten for another folder.
+ *
+ * Ground truth (claude 2.1.296, codex 0.160.0; docs/progress/move-to-cloud-evidence/ground-truth.md):
+ * - Claude writes <config>/projects/<folder name>/<session id>.jsonl, the folder name being the working directory with
+ *   every character but letters and digits replaced by "-" (cut at 200, plus a hash, when longer). A running session
+ *   is <config>/sessions/<pid>.json with its sessionId and `status` (busy during a turn, idle between turns). A turn
+ *   ends with a `system`/`turn_duration` record, an interrupt with "[Request interrupted by user…]", and a print-mode
+ *   turn with an assistant message whose stop_reason is end_turn.
+ * - Codex writes <CODEX_HOME>/sessions/YYYY/MM/DD/rollout-<time>-<thread id>.jsonl, first line session_meta (cwd).
+ *   A turn starts with event_msg task_started and ends with task_complete or turn_aborted. While a process has the
+ *   thread open it holds an flock on <CODEX_HOME>/thread-writer-locks/<thread id>.lock.
+ * Claude Desktop's Code tab and the Codex app write to the same stores.
+ */
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const ROLLOUT = /^rollout-\d{4}-\d{2}-\d{2}T[0-9-]+-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
+export const isSessionId = (id) => UUID.test(id);
+export const claudeConfigDir = (env) => env.CLAUDE_CONFIG_DIR || join(env.HOME || homedir(), '.claude');
+export const codexHome = (env) => env.CODEX_HOME || join(env.HOME || homedir(), '.codex');
+/** Java's String.hashCode, which Claude Code uses for the suffix of a long folder name. */
+function javaHash(text) {
+    let h = 0;
+    for (let i = 0; i < text.length; i++)
+        h = (Math.imul(31, h) + text.charCodeAt(i)) | 0;
+    return h;
+}
+/** Claude Code's folder name under projects/ for a working directory (measured: a 268-character path → 200 + "-1qkjv5"). */
+export function claudeProjectName(cwd) {
+    const name = cwd.replace(/[^a-zA-Z0-9]/g, '-');
+    return name.length <= 200 ? name : `${name.slice(0, 200)}-${Math.abs(javaHash(cwd)).toString(36)}`;
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Reading JSONL heads and tails
+function readRange(file, start, length) {
+    const fd = openSync(file, 'r');
+    try {
+        const out = Buffer.alloc(length);
+        let at = 0;
+        while (at < length) {
+            const n = readSync(fd, out, at, length - at, start + at);
+            if (n <= 0)
+                break;
+            at += n;
+        }
+        return out.subarray(0, at);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function parseLines(text) {
+    const out = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const v = JSON.parse(line);
+            if (v && typeof v === 'object' && !Array.isArray(v))
+                out.push(v);
+        }
+        catch { /* a partial line */ }
+    }
+    return out;
+}
+/** The first `max` bytes' complete records. */
+function head(file, max = 256 << 10) {
+    const bytes = readRange(file, 0, max);
+    const text = bytes.toString('utf8');
+    return parseLines(bytes.length < max ? text : text.slice(0, text.lastIndexOf('\n') + 1));
+}
+/** The last `max` bytes' complete records (a cut first line is dropped). */
+function tail(file, size, max = 512 << 10) {
+    const start = Math.max(0, size - max);
+    const text = readRange(file, start, size - start).toString('utf8');
+    return parseLines(start === 0 ? text : text.slice(text.indexOf('\n') + 1));
+}
+/** Records appended after `offset` (whole lines only). */
+export function recordsAfter(file, offset) {
+    const size = statSync(file).size;
+    if (size <= offset)
+        return [];
+    return parseLines(readRange(file, offset, size - offset).toString('utf8'));
+}
+const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const str = (v) => (typeof v === 'string' ? v : '');
+const oneLine = (text, max = 80) => {
+    const line = text.replace(/\s+/g, ' ').trim();
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+};
+// ---------------------------------------------------------------------------------------------------------------
+// Claude
+function claudeText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.map(c => (obj(c).type === 'text' ? str(obj(c).text) : '')).join(' ');
+    return '';
+}
+/** A user record that starts a model turn: a typed prompt, not a tool result, a meta or a local slash command record. */
+function claudePrompt(r) {
+    if (r.type !== 'user' || r.isMeta === true || r.isSidechain === true)
+        return false;
+    const content = obj(r.message).content;
+    if (Array.isArray(content) && content.some(c => obj(c).type === 'tool_result'))
+        return false;
+    const text = claudeText(content).trimStart();
+    return !!text && !text.startsWith('<command-name>') && !text.startsWith('<local-command') && !text.startsWith('[Request interrupted by user');
+}
+/** Whether the transcript's last turn is still running, from its records (see the module comment). */
+export function claudeTurnFromRecords(records) {
+    for (let i = records.length - 1; i >= 0; i--) {
+        const r = records[i];
+        if (r.isSidechain === true)
+            continue;
+        if (r.type === 'system') {
+            if (r.subtype === 'turn_duration')
+                return 'idle';
+            continue;
+        }
+        if (r.type === 'assistant') {
+            const m = obj(r.message);
+            if (r.isApiErrorMessage === true)
+                return 'idle';
+            const blocks = Array.isArray(m.content) ? m.content : [];
+            if (m.stop_reason === 'tool_use' || blocks.some(b => obj(b).type === 'tool_use'))
+                return 'working';
+            return ['end_turn', 'stop_sequence', 'max_tokens', 'refusal'].includes(str(m.stop_reason)) ? 'idle' : 'working';
+        }
+        if (r.type === 'user') {
+            const content = obj(r.message).content;
+            if (Array.isArray(content) && content.some(c => obj(c).type === 'tool_result'))
+                return 'working';
+            if (claudeText(content).trimStart().startsWith('[Request interrupted by user'))
+                return 'idle';
+            return claudePrompt(r) ? 'working' : 'idle';
+        }
+    }
+    return 'idle';
+}
+function claudeSession(file) {
+    const id = basename(file, '.jsonl');
+    if (!UUID.test(id))
+        return null;
+    const st = statSync(file);
+    const first = head(file), last = tail(file, st.size);
+    const prompt = [...first, ...last].find(claudePrompt);
+    if (!prompt)
+        return null;
+    const titled = [...last].reverse().find(r => (r.type === 'custom-title' && str(r.customTitle)) || (r.type === 'ai-title' && str(r.aiTitle)) || (r.type === 'summary' && str(r.summary)));
+    const title = titled ? str(titled.customTitle) || str(titled.aiTitle) || str(titled.summary) : claudeText(obj(prompt.message).content);
+    // Where the session started: its folder (a later `cd` in a tool call moves later records' cwd, not the session).
+    const started = [...first, ...last].find(r => str(r.cwd)) ?? prompt;
+    return { harness: 'claude', session_id: id, file, cwd: str(started.cwd), title: oneLine(title), updated_at: st.mtime.toISOString(), bytes: st.size,
+        source: str(prompt.entrypoint) || 'cli' };
+}
+function claudeProcesses(env) {
+    const dir = join(claudeConfigDir(env), 'sessions');
+    if (!existsSync(dir))
+        return null;
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        if (!/^\d+\.json$/.test(name))
+            continue;
+        try {
+            const r = JSON.parse(readFileSync(join(dir, name), 'utf8'));
+            if (Number.isInteger(r.pid) && r.pid > 0 && typeof r.sessionId === 'string' && alive(r.pid))
+                out.push(r);
+        }
+        catch { /* being rewritten */ }
+    }
+    return out;
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Codex
+function codexPrompt(r) {
+    const p = obj(r.payload);
+    if (r.type !== 'event_msg')
+        return '';
+    if (p.type === 'user_message')
+        return str(p.message);
+    const item = obj(p.item);
+    if (p.type === 'item_completed' && (item.type === 'UserMessage' || item.type === 'userMessage') && Array.isArray(item.content))
+        return item.content.map(c => str(obj(c).text)).join(' ');
+    return '';
+}
+export function codexTurnFromRecords(records) {
+    for (let i = records.length - 1; i >= 0; i--) {
+        const r = records[i], p = obj(r.payload);
+        if (r.type !== 'event_msg')
+            continue;
+        if (p.type === 'task_started')
+            return 'working';
+        if (p.type === 'task_complete' || p.type === 'turn_aborted')
+            return 'idle';
+    }
+    return 'idle';
+}
+function codexSession(file, metaOnly) {
+    const match = ROLLOUT.exec(basename(file));
+    if (!match)
+        return null;
+    const st = statSync(file);
+    const first = head(file);
+    const meta = first.find(r => r.type === 'session_meta');
+    const cwd = str(obj(meta?.payload).cwd);
+    if (!meta || !cwd || (metaOnly && !metaOnly(cwd)))
+        return null;
+    const last = tail(file, st.size);
+    const prompt = [...first, ...last].map(codexPrompt).find(Boolean);
+    if (!prompt)
+        return null;
+    return { harness: 'codex', session_id: match[1], file, cwd, title: oneLine(prompt), updated_at: st.mtime.toISOString(), bytes: st.size,
+        source: str(obj(meta.payload).originator) || 'codex' };
+}
+/** Every rollout file, newest first (one stat each; heads are read only for the ones a caller looks at). */
+function codexRollouts(env) {
+    const root = join(codexHome(env), 'sessions');
+    const out = [];
+    const walk = (dir, depth) => {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(dir, name);
+            if (depth < 3) {
+                if (/^\d+$/.test(name))
+                    walk(path, depth + 1);
+                continue;
+            }
+            if (!ROLLOUT.test(name))
+                continue;
+            try {
+                out.push({ file: path, mtime: statSync(path).mtimeMs });
+            }
+            catch { /* removed meanwhile */ }
+        }
+    };
+    walk(root, 0);
+    return out.sort((a, b) => b.mtime - a.mtime);
+}
+/** perl's flock(LOCK_EX|LOCK_NB) on the thread's writer lock: held while a Codex process has the thread open. */
+function codexRunning(env, id) {
+    const lock = join(codexHome(env), 'thread-writer-locks', `${id}.lock`);
+    if (!existsSync(lock))
+        return false;
+    const r = spawnSync('perl', ['-e', 'use Fcntl qw(:flock); open(my $f, "<", $ARGV[0]) or exit 2; exit(flock($f, LOCK_EX|LOCK_NB) ? 0 : 1)', lock], { stdio: 'ignore', timeout: 5000 });
+    return r.status === 1;
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Listing, finding, state
+const within = (folder) => (cwd) => cwd === folder || cwd.startsWith(folder.endsWith('/') ? folder : `${folder}/`);
+const real = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return path;
+} };
+/** A project's sessions on this computer, newest first: those started in the folder or below it. */
+export function listLocalSessions(folder, env, options = {}) {
+    const root = real(folder), limit = options.limit ?? 10, inside = within(root), out = [];
+    if (options.harness !== 'codex') {
+        const projects = join(claudeConfigDir(env), 'projects'), exact = claudeProjectName(root);
+        let dirs = [];
+        try {
+            dirs = readdirSync(projects).filter(d => d === exact || d.startsWith(`${exact}-`));
+        }
+        catch { /* no Claude sessions */ }
+        const files = [];
+        for (const dir of dirs) {
+            let names;
+            try {
+                names = readdirSync(join(projects, dir));
+            }
+            catch {
+                continue;
+            }
+            for (const name of names)
+                if (name.endsWith('.jsonl')) {
+                    const file = join(projects, dir, name);
+                    try {
+                        files.push({ file, mtime: statSync(file).mtimeMs });
+                    }
+                    catch { /* removed */ }
+                }
+        }
+        let found = 0;
+        for (const { file } of files.sort((a, b) => b.mtime - a.mtime)) {
+            if (found >= limit)
+                break;
+            const s = claudeSession(file);
+            // A folder named like another's prefix ("app" and "app-web") is told apart by the recorded cwd.
+            if (s && inside(real(s.cwd))) {
+                out.push(s);
+                found++;
+            }
+        }
+    }
+    if (options.harness !== 'claude') {
+        let found = 0;
+        for (const { file } of codexRollouts(env)) {
+            if (found >= limit)
+                break;
+            const s = codexSession(file, cwd => inside(real(cwd)));
+            if (s) {
+                out.push(s);
+                found++;
+            }
+        }
+    }
+    return out.sort((a, b) => b.updated_at.localeCompare(a.updated_at));
+}
+/** One session by id, wherever it was started. */
+export function findLocalSession(id, env) {
+    if (!UUID.test(id))
+        return null;
+    const projects = join(claudeConfigDir(env), 'projects');
+    let dirs = [];
+    try {
+        dirs = readdirSync(projects);
+    }
+    catch { /* none */ }
+    for (const dir of dirs) {
+        const file = join(projects, dir, `${id}.jsonl`);
+        if (existsSync(file))
+            return claudeSession(file);
+    }
+    for (const { file } of codexRollouts(env))
+        if (ROLLOUT.exec(basename(file))?.[1] === id)
+            return codexSession(file);
+    return null;
+}
+/** Whether a turn is running now. A session no process has open is between turns, whatever its last record says. */
+export function sessionState(s, env, now = Date.now()) {
+    const size = statSync(s.file).size;
+    if (s.harness === 'claude') {
+        const fromRecords = claudeTurnFromRecords(tail(s.file, size));
+        const processes = claudeProcesses(env);
+        if (processes === null) {
+            // An older Claude Code keeps no session registry: the transcript decides, and a long-silent one has stopped.
+            const quiet = now - statSync(s.file).mtimeMs > 15 * 60_000;
+            return { running: !quiet, turn: quiet ? 'idle' : fromRecords };
+        }
+        const proc = processes.find(p => p.sessionId === s.session_id);
+        if (!proc)
+            return { running: false, turn: 'idle' };
+        return { running: true, pid: proc.pid, turn: proc.status === 'busy' || fromRecords === 'working' ? 'working' : 'idle' };
+    }
+    const running = codexRunning(env, s.session_id);
+    return { running, turn: running ? codexTurnFromRecords(tail(s.file, size)) : 'idle' };
+}
+/** Whether someone typed in the local copy after it moved: a new prompt or turn after `offset`. */
+export function continuedAfter(s, offset) {
+    let records;
+    try {
+        records = recordsAfter(s.file, offset);
+    }
+    catch {
+        return false;
+    }
+    return records.some(r => s.harness === 'claude' ? claudePrompt(r) : !!codexPrompt(r) || (r.type === 'event_msg' && obj(r.payload).type === 'task_started'));
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Moving a transcript
+/**
+ * The transcript as whole lines, cut after its last complete record: a harness may be appending a record while a
+ * move reads it (between turns that is metadata, never part of a turn).
+ */
+export function completeRecords(bytes) {
+    const end = bytes.lastIndexOf(0x0a);
+    return end < 0 ? Buffer.alloc(0) : bytes.subarray(0, end + 1);
+}
+/**
+ * The session's records with its working directory moved from `from` to `to`: Claude's and Codex's `cwd` fields (and
+ * Codex's workdir and workspace roots). Lines that do not mention `from` keep their exact bytes; message text,
+ * tool output and signed thinking are never changed.
+ */
+export function rewriteSessionPaths(bytes, from, to) {
+    if (from === to)
+        return bytes;
+    const needles = [from, JSON.stringify(from).slice(1, -1)];
+    const move = (path) => (path === from || path.startsWith(`${from}/`) ? to + path.slice(from.length) : path);
+    const rewrite = (value) => {
+        if (Array.isArray(value))
+            return value.map(rewrite);
+        if (!value || typeof value !== 'object')
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([key, leaf]) => {
+            if (typeof leaf === 'string' && ['cwd', 'workdir', 'working_directory'].includes(key))
+                return [key, move(leaf)];
+            if (Array.isArray(leaf) && ['workspace_roots', 'runtime_workspace_roots', 'writable_roots'].includes(key))
+                return [key, leaf.map(v => (typeof v === 'string' ? move(v) : rewrite(v)))];
+            return [key, rewrite(leaf)];
+        }));
+    };
+    const lines = bytes.toString('utf8').split('\n');
+    return Buffer.from(lines.map(line => {
+        if (!line || !needles.some(n => line.includes(n)))
+            return line;
+        try {
+            return JSON.stringify(rewrite(JSON.parse(line)));
+        }
+        catch {
+            return line;
+        }
+    }).join('\n'), 'utf8');
+}
+/** Where the session's transcript lives under a home folder, relative to it (the VM's and the project space's layout). */
+export function homeRelativeTranscript(s, cwd) {
+    if (s.harness === 'claude')
+        return join('.claude', 'projects', claudeProjectName(cwd), `${s.session_id}.jsonl`);
+    const parts = s.file.split('/').slice(-4);
+    if (parts.length !== 4 || !/^\d{4}$/.test(parts[0]) || !/^\d{2}$/.test(parts[1]) || !/^\d{2}$/.test(parts[2]))
+        throw new Error('Codex rollout is outside sessions/YYYY/MM/DD.');
+    return join('.codex', 'sessions', ...parts);
+}
+/** The transcript file is a regular file: never follow a link out of the harness's store. */
+export function readTranscript(file) {
+    const fd = openSync(file, 'r');
+    try {
+        if (!fstatSync(fd).isFile())
+            throw new Error(`Session transcript is not a regular file: ${file}`);
+        return readFileSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/main.js

@@ -105,6 +105,8 @@ function hintFor(info, cred, file, command = '') {
         return 'this API has no billing configured: plans cannot be bought here';
     if (info.code === 'allowance_exhausted')
         return allowanceHint(info);
+    if (info.code === 'entitlement_required' && reasonOf(info) === 'not_included')
+        return planHint(info);
     if (info.code === 'quota_exceeded') {
         const quota = quotaHint(info);
         if (quota)
@@ -177,6 +179,16 @@ function allowanceHint(info) {
             return undefined;
     }
 }
+/**
+ * 402 entitlement_required not_included (0.19.0): the plan does not include the feature (the GPU, shared volumes). The
+ * plans that do come from details.required_plans when the API names them (the GPU: Startup or Scale).
+ */
+function planHint(info) {
+    const plans = Array.isArray(info.details?.required_plans) ? info.details.required_plans.filter((p) => typeof p === 'string' && p.length > 0) : [];
+    const names = plans.map((p) => p.charAt(0).toUpperCase() + p.slice(1));
+    const which = names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names[names.length - 1]}` : names[0];
+    return which ? `upgrade to ${which}: shard billing plans` : 'upgrade to a plan that includes it: shard billing plans';
+}
 /**
  * quota_exceeded (0.9.0): the cell gateway's 429 when every workspace the plan allows to work at once is busy (the SDK
  * already retried it after Retry-After), and the API's 403 when the plan's Retained state is used up (new keys and