@shardflux/cli 0.18.1 → 0.19.1

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

package/dist/move.d.ts

@@ -0,0 +1,44 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import type { Conversation } from './conversations.js';
+import type { LocalSession, SessionHarness, SessionState } from './local-sessions.js';
+type Env = Record<string, string | undefined>;
+/** The project a folder belongs to: its Git repository's top, or the folder itself. */
+export declare function projectRoot(folder: string): string;
+export declare function chooseSession(values: Values, env: Env, folder: string): LocalSession;
+/** Until the session's turn has ended: a running turn is never cut off. */
+export declare function waitForTurnEnd(ctx: Pick<Ctx, 'io' | 'json' | 'signal'>, s: LocalSession, env: Env, pollMs?: number): Promise<SessionState>;
+type MoveCell = Pick<ReturnType<Workspace['cell']>, 'exec' | 'files'>;
+/**
+ * The session's transcript in the conversation's VM: at its native path (where the harness resumes it) and, when the
+ * project space is mounted, as the conversation's durable copy with the same checkpoint metadata the guest writes
+ * (transcripts/<id>/meta.json), so the session survives the VM from its first minute.
+ */
+export declare function placeTranscript(cell: MoveCell, c: Pick<Conversation, 'id' | 'harness' | 'worktree_path'>, s: LocalSession, bytes: Buffer, folder: string, signal?: AbortSignal): Promise<{
+    native: string;
+    durable: boolean;
+}>;
+export declare function moveSession(ctx: Ctx, values: Values): Promise<number>;
+/** `shard move --list`: this project's sessions on this computer, and where each moved one continues. */
+export declare function listMovable(ctx: Pick<Ctx, 'store' | 'apiUrl'>, values: Values, env: Env, now?: number): {
+    folder: string;
+    sessions: {
+        harness: SessionHarness;
+        session_id: string;
+        title: string;
+        updated_at: string;
+        source: string;
+        cwd: string;
+        running: boolean;
+        turn: "working" | "idle";
+        moved: {
+            conversation_id: string;
+            key: string;
+            moved_at: string;
+            diverged: boolean;
+        } | null;
+    }[];
+};
+export declare const MOVE_HANDLERS: Record<string, Handler>;
+export {};