@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/app-server/workspace.js

@@ -0,0 +1,1098 @@
+import { spawn } from 'node:child_process';
+import { createReadStream } from 'node:fs';
+import { opendir, open, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { StringDecoder } from 'node:string_decoder';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { runRecordPath, runRecordsDirectory, sessionHasOpenRun } from '../run-records.js';
+import { validSavedSession } from '../sessions.js';
+import { listBundles } from '../extensions.js';
+/**
+ * Inspection of a workspace and of this installation's run records.
+ *
+ * Only one function here (`checkoutBranch`) changes anything, and it changes the branch the working
+ * tree is on — never its contents. Everything else answers a panel in the desktop client: paths from
+ * the client are resolved inside the workspace root and refused when they leave it, so a crafted
+ * request cannot read arbitrary files through the engine.
+ */
+/** The same skip list the agent's `list_files` tool uses, so the tree matches what the agent sees. */
+const SKIP_NAMES = new Set(['.git', 'node_modules', '.andorracode']);
+const MAX_TREE_ENTRIES = 5_000;
+const MAX_TREE_DEPTH = 12;
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_DIFF_BYTES = 2 * 1024 * 1024;
+/** Enough for a working tree of ordinary size; a repository past this is reported as cut. */
+const MAX_STATUS_BYTES = 8 * 1024 * 1024;
+const GIT_TIMEOUT_MS = 15_000;
+const MAX_RUNS = 200;
+const MAX_RUN_EVENTS = 5_000;
+/** How many session snapshots may be opened to title a page of runs; the newest are examined. */
+const MAX_SESSION_SCAN = 500;
+function message(error) { return error instanceof Error ? error.message : String(error); }
+function inside(root, target) {
+    const suffix = relative(root, target);
+    return suffix === '' || (!isAbsolute(suffix) && suffix !== '..' && !suffix.startsWith(`..${sep}`));
+}
+/**
+ * Resolve a client-supplied relative path inside the workspace, without following the final component.
+ *
+ * The containment check is the same lexical one `resolveInside` starts with; what is left out is the
+ * canonicalization, for the callers that need the name the client chose rather than the file it points
+ * at (a Git pathspec, for one).
+ */
+export async function resolveLexicalInside(root, name) {
+    if (name !== undefined && (typeof name !== 'string' || name.length > 4096 || name.includes('\0')))
+        throw new Error('A workspace path must be a string of up to 4096 characters');
+    const candidate = resolve(root, name === undefined || name === '' ? '.' : name);
+    if (!inside(root, candidate))
+        throw new Error('The path is outside the project');
+    return candidate;
+}
+/**
+ * Resolve a client-supplied relative path inside the workspace.
+ *
+ * The lexical check runs before `realpath`, so a path that escapes through `..` never reaches the
+ * filesystem, and the canonical check runs after, so a symlink or junction that leaves the
+ * workspace is refused even when its name looked local.
+ */
+export async function resolveInside(root, name) {
+    if (name !== undefined && (typeof name !== 'string' || name.length > 4096 || name.includes('\0')))
+        throw new Error('A workspace path must be a string of up to 4096 characters');
+    const candidate = resolve(root, name === undefined || name === '' ? '.' : name);
+    if (!inside(root, candidate))
+        throw new Error('The path is outside the project');
+    const canonical = await realpath(candidate).catch((error) => {
+        if (error.code === 'ENOENT')
+            return candidate;
+        throw error;
+    });
+    if (!inside(root, canonical))
+        throw new Error('The path is outside the project');
+    return canonical;
+}
+export async function workspaceRoot(value) {
+    if (typeof value !== 'string' || !value.trim() || value.length > 4096 || value.includes('\0'))
+        throw new Error('A project folder path is required');
+    const root = await realpath(resolve(value)).catch(() => { throw new Error('The project folder does not exist'); });
+    if (!(await stat(root)).isDirectory())
+        throw new Error('The project path is not a folder');
+    return root;
+}
+/**
+ * List one directory level or a bounded subtree.
+ *
+ * A tree panel asks for one level at a time, so the default walk stops at the requested directory
+ * and only the opt-in deep form recurses; either way directories come before files and both sort
+ * by name, which keeps a level stable between refreshes.
+ */
+export async function readTree(root, options = {}) {
+    const start = await resolveInside(root, options.path);
+    const deep = options.depth !== undefined;
+    const maxDepth = deep ? Math.max(1, Math.min(MAX_TREE_DEPTH, Number.isSafeInteger(options.depth) ? options.depth : MAX_TREE_DEPTH)) : 1;
+    const entries = [];
+    let truncated = false;
+    const walk = async (directory, depth) => {
+        const found = [];
+        for await (const entry of await opendir(directory)) {
+            if (entry.isSymbolicLink() || SKIP_NAMES.has(entry.name))
+                continue;
+            // The bound is applied while reading the directory, not after: a folder with far more children
+            // than this cap would otherwise be accumulated and sorted in full before the cap could apply,
+            // and a stat per file would make listing a large generated directory very slow. Sizes are not
+            // reported for that reason; nothing in the client renders them.
+            if (entries.length + found.length >= MAX_TREE_ENTRIES) {
+                truncated = true;
+                break;
+            }
+            const path = join(directory, entry.name);
+            const name = relative(root, path).split(sep).join('/');
+            if (entry.isDirectory())
+                found.push({ name: entry.name, path: name, type: 'directory' });
+            else if (entry.isFile())
+                found.push({ name: entry.name, path: name, type: 'file' });
+        }
+        found.sort((left, right) => left.type === right.type ? left.name.localeCompare(right.name) : left.type === 'directory' ? -1 : 1);
+        for (const child of found) {
+            if (entries.length >= MAX_TREE_ENTRIES) {
+                truncated = true;
+                return;
+            }
+            entries.push(child);
+            if (child.type === 'directory' && depth < maxDepth)
+                await walk(join(directory, child.name), depth + 1);
+        }
+    };
+    await walk(start, 1);
+    return { path: relative(root, start).split(sep).join('/'), entries, truncated };
+}
+/**
+ * Read one text file with a byte cap.
+ *
+ * The cap is enforced on the read, not after it: stat gives the size, and a large file is read
+ * through a bounded handle so opening a multi-gigabyte artifact cannot allocate it in full just to
+ * hand back its first half megabyte. Binary detection keeps a NUL byte from reaching a text view.
+ */
+export async function readWorkspaceFile(root, name) {
+    const path = await resolveInside(root, name);
+    const info = await stat(path);
+    if (!info.isFile())
+        throw new Error('Only files can be opened');
+    const handle = await open(path, 'r');
+    try {
+        const buffer = Buffer.alloc(Math.min(info.size, MAX_FILE_BYTES + 1));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        const head = buffer.subarray(0, bytesRead);
+        const binary = head.subarray(0, Math.min(head.length, 8000)).includes(0);
+        // The cap can fall inside a multi-byte character, which no character encoding can represent
+        // faithfully; the decoder keeps the incomplete tail out of the text instead of ending the preview
+        // with a replacement character. A file within the cap is unaffected: its bytes are complete.
+        const content = new StringDecoder('utf8').write(head.subarray(0, MAX_FILE_BYTES));
+        return { content: binary ? '' : content, truncated: info.size > MAX_FILE_BYTES, binary, size: info.size };
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Working-tree status through the `git` executable.
+ *
+ * Startup metadata deliberately avoids running workspace-controlled helpers; a user-opened Changes
+ * panel is the opposite case, where the repository's own Git is the authority and the call is
+ * explicit. Arguments are fixed (no shell, no interpolation) and the call is time bounded.
+ *
+ * Paths come from `-z` output rather than the default: porcelain quotes names containing non-ASCII
+ * or control characters in C style, and a client that treated the quoted form as a path could not
+ * open the file it names. With `-z` each record is NUL terminated and renames carry the source in a
+ * following field, so no path has to be decoded.
+ */
+export async function gitStatus(root, options = {}) {
+    let collected;
+    try {
+        // Streamed and capped, like the diff path: `execFile` fails the whole call once a repository's
+        // status passes its buffer, and the catch below would then report a large generated tree as not
+        // being a repository at all. A capped read is reported as such instead.
+        collected = await collectCapped('git', ['-C', root, 'status', '--porcelain=v1', '-z', '--branch', '--untracked-files=all'], options.maxBytes ?? MAX_STATUS_BYTES, GIT_TIMEOUT_MS);
+    }
+    catch {
+        // Git that cannot be started, a timeout, or an unreadable tree are all "no changes to show"; the
+        // panel says so rather than failing the request.
+        return { repository: false, files: [] };
+    }
+    // A capped read was killed rather than exited, so its code says nothing about the repository: the
+    // records it did collect are a partial listing, which the flag reports. Only a command that ran to a
+    // nonzero exit is a folder with nothing to show.
+    if (!collected.truncated && collected.code !== 0)
+        return { repository: false, files: [] };
+    {
+        const records = collected.text.split('\0');
+        // A capped read can end in the middle of a record, so the last one is dropped rather than parsed
+        // into a path with no file behind it; the flag tells the pane the list is incomplete.
+        if (collected.truncated)
+            records.pop();
+        const files = [];
+        let branch;
+        for (let index = 0; index < records.length; index++) {
+            const record = records[index];
+            if (!record)
+                continue;
+            if (record.startsWith('## ')) {
+                const header = record.slice(3).replace(/\s+\[.+\]$/, '');
+                branch = header.split('...')[0].trim() || undefined;
+                continue;
+            }
+            if (record.length < 4)
+                continue;
+            const index_ = record.slice(0, 1).trim(), worktree = record.slice(1, 2).trim();
+            // A rename or copy entry names the destination here and the source in the next record.
+            const renamed = index_ === 'R' || index_ === 'C';
+            files.push({ path: record.slice(3), index: index_, worktree });
+            if (renamed)
+                index++;
+        }
+        return { repository: true, branch, files, truncated: collected.truncated };
+    }
+}
+/** Which Git failures mean "there is nothing to compare" rather than "this could not be read". */
+const NOTHING_TO_COMPARE = /not a git repository|bad revision 'HEAD'|ambiguous argument 'HEAD'|does not have any commits/i;
+/** Which of those mean the comparison has no first commit to name, which `--cached` can still answer. */
+const NO_FIRST_COMMIT = /bad revision 'HEAD'|ambiguous argument 'HEAD'|does not have any commits/i;
+/** The first line of a Git diagnostic, for an error a person can act on. */
+function firstLine(text) { return text.trim().split('\n')[0]?.slice(0, 200) ?? ''; }
+/** How many branch names one answer carries; a repository past this is listed up to the bound. */
+const MAX_BRANCHES = 1_000;
+const MAX_BRANCH_BYTES = 256 * 1024;
+const MAX_BRANCH_NAME_CHARS = 200;
+/**
+ * The local branches of a repository, and the one the working tree is on.
+ *
+ * `refs/heads` is read directly rather than through `git branch`, whose listing in a detached HEAD
+ * also contains a pseudo-entry naming the commit — a name no client could check out. The branch the
+ * working tree is on is asked separately because a detached HEAD has none, and "absent from the
+ * listing" would otherwise be indistinguishable from a branch that only does not exist yet.
+ * Remote-tracking refs are left out: landing on one needs a tracking decision — which local branch
+ * follows it — that this request cannot express.
+ */
+export async function listBranches(root) {
+    let collected;
+    try {
+        // `:lstrip=2` removes the fixed `refs/heads/` prefix instead of asking for an abbreviation:
+        // `:short` has to stay unambiguous, so a repository with a tag of the same name would list
+        // `heads/foo`, and checking that name out later would land on the tag rather than the branch.
+        collected = await collectCapped('git', ['-C', root, 'for-each-ref', '--format=%(refname:lstrip=2)', 'refs/heads'], MAX_BRANCH_BYTES, GIT_TIMEOUT_MS);
+    }
+    catch {
+        // Git that cannot be started, a timeout, and an unreadable folder all read as "nothing to offer".
+        return { repository: false, branches: [] };
+    }
+    // A capped read was killed rather than exited, so its code says nothing about the repository: the
+    // names it did collect are a prefix of the listing, which the flag reports. Only a command that ran
+    // to a nonzero exit is a folder with no branches to show.
+    if (!collected.truncated && collected.code !== 0)
+        return { repository: false, branches: [] };
+    const records = collected.text.split('\n');
+    // A capped read can end in the middle of a name, so the last record is dropped rather than offered
+    // as a branch that does not exist.
+    if (collected.truncated)
+        records.pop();
+    const branches = [];
+    let listed = 0;
+    for (const record of records) {
+        if (!record)
+            continue;
+        listed++;
+        if (branches.length < MAX_BRANCHES)
+            branches.push(record);
+    }
+    // `-q` makes a detached HEAD an empty answer with a nonzero exit rather than a diagnostic; a Git
+    // that cannot be started at all is the same absence, and the listing above already answered.
+    // The full ref is read and the prefix stripped by hand: `--short` has to stay unambiguous, so with
+    // a tag of the same name it answers `heads/feature/one` — a name that would then neither match the
+    // listing below nor be a branch the caller can switch to.
+    const head = await collectCapped('git', ['-C', root, 'symbolic-ref', '-q', 'HEAD'], 4 * 1024, GIT_TIMEOUT_MS).catch(() => undefined);
+    const current = head && head.code === 0 ? head.text.trim().replace(/^refs\/heads\//, '') || undefined : undefined;
+    return {
+        repository: true,
+        ...(current === undefined ? {} : { current }),
+        branches,
+        ...(collected.truncated || listed > branches.length ? { truncated: true } : {}),
+    };
+}
+/**
+ * Switch the working tree to a branch, creating it when asked.
+ *
+ * The name is a Git ref name and Git judges it, after the cases that would make it mean something
+ * other than the branch typed are refused here: a leading dash would reach the command as an option,
+ * and `@{` is resolved by `check-ref-format --branch` against the reflog — a way to name a different
+ * branch than the one in the request. Nothing else about the name is guessed; Git's own refusal is
+ * what the caller reports, because it names the reason (no such branch, a working tree that would
+ * lose changes) better than a rule kept in sync here could.
+ */
+export async function checkoutBranch(root, options) {
+    if (typeof options.branch !== 'string')
+        throw new Error('A branch name must be a string');
+    const name = options.branch.trim();
+    if (!name || name.length > MAX_BRANCH_NAME_CHARS)
+        throw new Error(`A branch name must be 1 to ${MAX_BRANCH_NAME_CHARS} characters`);
+    if (name.startsWith('-') || name.includes('@{') || /\s/.test(name))
+        throw new Error(`Not a valid branch name: ${name}`);
+    const checked = await collectCapped('git', ['-C', root, 'check-ref-format', '--branch', name], 4 * 1024, GIT_TIMEOUT_MS);
+    if (checked.code !== 0)
+        throw new Error(firstLine(checked.failure) || `Not a valid branch name: ${name}`);
+    // `switch` cannot restore paths, and `--no-guess` refuses to invent a local branch from a
+    // remote-tracking one: plain `checkout <name>` selects its path-restoration mode when no branch
+    // matches, which exits successfully after discarding unstaged changes to a path of that name and
+    // would leave this function reporting a branch switch that never happened.
+    const switched = await collectCapped('git', ['-C', root, 'switch', '--no-guess', ...(options.create === true ? ['-c'] : []), name], 64 * 1024, GIT_TIMEOUT_MS);
+    if (switched.code !== 0)
+        throw new Error(firstLine(switched.failure) || 'The branch could not be checked out');
+    return { branch: name };
+}
+/**
+ * A diff for one path or the whole tree.
+ *
+ * `base` names what the diff is taken against: the working tree alone (unstaged changes, Git's
+ * default) or `head`, which is what a per-file view wants because it includes staged and unstaged
+ * changes together. Untracked files have no diff at all and are read as content by the client.
+ */
+export async function gitDiff(root, options = {}) {
+    // The pathspec keeps the name that was asked for. `resolveInside` follows the final component with
+    // `realpath`, which is what a *read* needs — a link that leaves the project must be refused — but a
+    // diff is addressed by Git: canonicalizing a tracked symlink would ask for its target's diff, which
+    // usually reads as "no changes", instead of the change to the link itself.
+    const target = options.path !== undefined && options.path !== '' ? relative(root, await resolveLexicalInside(root, options.path)).split(sep).join('/') || '.' : undefined;
+    const head = options.base === 'head' && options.staged !== true;
+    // `--no-ext-diff` covers an external *diff* driver; a diff driver's `textconv` command is a separate
+    // helper that Git runs by default, and it is a configured program run with this process's privileges.
+    const args = ['-C', root, 'diff', '--no-color', '--no-ext-diff', '--no-textconv', ...(options.staged === true ? ['--staged'] : head ? ['HEAD'] : []), ...(target === undefined ? [] : ['--', target])];
+    // The diff is streamed and the collection stops at the cap: `execFile`'s buffer would reject a
+    // large-but-valid diff before this code could truncate it, reporting a readable change as
+    // unreadable, and collecting it whole would hold the entire diff in memory.
+    let collected = await collectCapped('git', args, MAX_DIFF_BYTES, GIT_TIMEOUT_MS).catch((error) => {
+        // A Git that cannot be started reads as nothing to compare, exactly as it did before it was
+        // streamed; a timeout is reported, because an empty answer would say a changed file has no changes.
+        if (/ENOENT/.test(message(error)))
+            return { text: '', truncated: false, code: 0, failure: '' };
+        throw error;
+    });
+    if (head && !collected.truncated && collected.code !== 0 && NO_FIRST_COMMIT.test(collected.failure)) {
+        // A repository whose first commit has not happened has no HEAD to compare against, and Git offers
+        // `--cached` there: it shows the staged snapshot the Changes list is already displaying. Without
+        // this, opening a staged file in a fresh repository read as "no changes".
+        const staged = args.filter(argument => argument !== 'HEAD');
+        staged.splice(staged.indexOf('--no-ext-diff') + 1, 0, '--cached');
+        collected = await collectCapped('git', staged, MAX_DIFF_BYTES, GIT_TIMEOUT_MS);
+    }
+    if (collected.truncated)
+        return { diff: collected.text, truncated: true };
+    // "Not a repository" and "no commits yet" are empty comparisons; any other nonzero exit is a real
+    // failure, and returning its empty stdout would tell the Code view that a changed file has no changes.
+    if (collected.code !== 0 && !NOTHING_TO_COMPARE.test(collected.failure)) {
+        throw new Error(`The Git output could not be read${collected.failure ? `: ${firstLine(collected.failure)}` : ''}`);
+    }
+    return { diff: collected.code === 0 ? collected.text : '', truncated: false };
+}
+/**
+ * The timestamp of a journal's first event.
+ *
+ * The first line is `graph.started`, which serializes the whole pinned graph, so it can be far larger
+ * than a small fixed prefix: the read continues to the first newline, up to a bound at which a single
+ * record stops being credible. A record that still cannot be parsed has its timestamp extracted by
+ * pattern, since the rest of that payload is not wanted here.
+ */
+async function firstEventTime(journal) {
+    const LIMIT = 256 * 1024;
+    const CHUNK = 16 * 1024;
+    let handle;
+    try {
+        handle = await open(journal, 'r');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        let text = '';
+        let position = 0;
+        while (position < LIMIT && !text.includes('\n')) {
+            const buffer = Buffer.alloc(CHUNK);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            if (bytesRead === 0)
+                break;
+            position += bytesRead;
+            text += buffer.subarray(0, bytesRead).toString('utf8');
+        }
+        const first = text.split('\n')[0].trim();
+        if (!first)
+            return undefined;
+        try {
+            const event = JSON.parse(first);
+            if (typeof event.time === 'string')
+                return event.time;
+        }
+        catch { /* Fall through to the pattern below. */ }
+        return /"time":"([^"]+)"/.exec(first)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Run a command, keeping at most `cap` bytes of its standard output.
+ *
+ * Exported for the streaming test: the split it guards against is a property of pipe reads, which a
+ * test can only produce by driving this collector directly. Rejection is reserved for a command that
+ * never ran or never finished; what it exited with is the caller's business, because the same exit is
+ * an empty answer for one command and a real failure for another.
+ */
+export function collectCapped(program, args, cap, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(program, args, { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        // A pipe delivers bytes, and a multi-byte character can be divided between two reads: decoding
+        // each chunk on its own would replace both halves with replacement characters, corrupting the file
+        // contents and paths the Code view shows even though Git emitted valid UTF-8. One decoder per
+        // stream carries the unfinished character over to the chunk that completes it.
+        const stdout = new StringDecoder('utf8');
+        const stderr = new StringDecoder('utf8');
+        let text = '';
+        let bytes = 0;
+        let truncated = false;
+        let failure = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`The Git output could not be read: it did not finish in ${Math.round(timeoutMs / 1000)} seconds`));
+        }, timeoutMs);
+        timer.unref?.();
+        const finish = (code) => {
+            clearTimeout(timer);
+            // Flush the decoder unless the tail was cut: a stream that ended mid-character has nothing more
+            // coming, while a cap that cut one has deliberately dropped those bytes.
+            if (!truncated)
+                text += stdout.end();
+            resolve({ text, truncated, code, failure });
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (truncated)
+                return;
+            if (bytes + chunk.length > cap) {
+                // The cap is a byte count and it is applied before decoding, so the retained text cannot
+                // exceed it. A character the boundary cuts in half is left to the decoder rather than shown
+                // as a replacement character; the output is marked truncated either way.
+                text += stdout.write(chunk.subarray(0, Math.max(0, cap - bytes)));
+                truncated = true;
+                // Nothing more is wanted: stop the producer instead of reading a large output to the end.
+                child.kill();
+                return;
+            }
+            bytes += chunk.length;
+            text += stdout.write(chunk);
+        });
+        child.stderr?.on('data', (chunk) => { failure += stderr.write(chunk); });
+        child.once('error', error => {
+            clearTimeout(timer);
+            reject(new Error(`Could not run ${program}: ${error.message}`));
+        });
+        child.once('close', code => { finish(code); });
+    });
+}
+/**
+ * The newest `keep` entries of a directory, by modification time.
+ *
+ * Directory order is arbitrary, so a cap applied before timestamps are read can hide a just-written
+ * file behind older ones. The scan runs at bounded concurrency and retains only `keep` entries, so a
+ * directory with tens of thousands of files costs a fixed number of in-flight stats and fixed memory.
+ */
+async function newestByMtime(folder, names, keep) {
+    const newest = [];
+    let next = 0;
+    const worker = async () => {
+        while (next < names.length) {
+            const name = names[next++];
+            const info = await stat(join(folder, name)).catch(() => undefined);
+            if (!info)
+                continue;
+            const position = newest.findIndex(entry => entry.info.mtimeMs < info.mtimeMs);
+            if (position === -1) {
+                if (newest.length < keep)
+                    newest.push({ name, info });
+            }
+            else {
+                newest.splice(position, 0, { name, info });
+                if (newest.length > keep)
+                    newest.pop();
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(8, names.length) }, worker));
+    return newest;
+}
+/**
+ * Map run identity to the session turn that produced it, so a run list can name its task.
+ *
+ * Only the runs in `wanted` are looked up, and only the newest session files are opened, stopping as
+ * soon as every one of them is titled: a long-lived installation accumulates a snapshot per resumed
+ * task, each carrying accumulated history, and parsing the whole archive to title a page of runs
+ * would make opening the Runs view grow with everything the installation has ever done.
+ */
+async function runTitles(directory, wanted) {
+    const titles = new Map();
+    if (!wanted.size)
+        return titles;
+    const folder = join(directory, 'sessions');
+    let names;
+    try {
+        names = await readdir(folder);
+    }
+    catch {
+        return titles;
+    }
+    const newest = await newestByMtime(folder, names.filter(name => name.endsWith('.json')), MAX_SESSION_SCAN);
+    for (const { name } of newest) {
+        if (titles.size >= wanted.size)
+            break;
+        try {
+            const record = JSON.parse(await readFile(join(folder, name), 'utf8'));
+            if (!validSavedSession(record))
+                continue;
+            for (const turn of record.history ?? []) {
+                // A continued turn is labelled by the message that continued it: the turn's own task is the
+                // stopped attempt's, so the Runs view and the search haystack would otherwise repeat the old
+                // prompt instead of the words the user last sent. The transcript's rule, applied to titles.
+                if (turn.runId && wanted.has(turn.runId) && !titles.has(turn.runId))
+                    titles.set(turn.runId, { task: turn.direction ?? turn.task, session: record });
+            }
+        }
+        catch { /* One damaged session must not hide the other runs. */ }
+    }
+    return titles;
+}
+/** How deep a session's parent chain is walked to find the record that produced a run. */
+const MAX_LINEAGE_WALK = 64;
+/**
+ * The session that first produced a run, starting from a record that merely carries its turn.
+ *
+ * Continuation forks copy their parent's whole history, so an ancestor's run is commonly found in a
+ * newer child first — and a record's timestamp cannot tell the two apart, because a later save of
+ * the old session moves it the other way. `parentId` is the link that can: a record's own history
+ * is the only one that produced its turns, a fork merely inherits them, so walking up while the
+ * parent still carries the turn ends at the session that ran it. Taking the first match instead
+ * would attribute the run to a descendant — and `View trajectory` on the original would report that
+ * it has no run at all.
+ */
+async function originatingSession(directory, candidate, runId, cache) {
+    const carries = (record) => (record.history ?? []).some(turn => turn.runId === runId);
+    let origin = candidate;
+    const visited = new Set([candidate.id]);
+    // A damaged record can name a parent chain that loops back on itself; the set breaks that, and
+    // the depth cap keeps one listing from turning a pathological chain into unbounded reads.
+    for (let depth = 0; depth < MAX_LINEAGE_WALK && origin.parentId !== undefined; depth += 1) {
+        const parentId = origin.parentId;
+        if (visited.has(parentId))
+            break;
+        visited.add(parentId);
+        if (!cache.has(parentId)) {
+            cache.set(parentId, await readFile(join(directory, 'sessions', `${parentId}.json`), 'utf8')
+                .then(text => JSON.parse(text))
+                .catch(() => undefined));
+        }
+        const parent = cache.get(parentId);
+        if (parent === undefined || !validSavedSession(parent) || !carries(parent))
+            break;
+        origin = parent;
+    }
+    return origin;
+}
+export async function listRuns(directory, limit) {
+    const bound = Number.isSafeInteger(limit) && limit > 0 ? Math.min(MAX_RUNS, limit) : 50;
+    const runs = runRecordsDirectory(directory);
+    let names;
+    try {
+        names = await readdir(runs);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    // Bodies are read only for the newest records, and titles only for those runs. The runs folder
+    // also holds resume claims and node checkpoints; only the `.json` result records are runs, and
+    // the legacy `.checkpoint.json` spelling is filtered too so an old file never shows as a second
+    // run of an id that never ran.
+    const stamped = await newestByMtime(runs, names.filter(name => name.endsWith('.json') && !name.endsWith('.checkpoint.json')), bound);
+    const records = await Promise.all(stamped.map(async ({ name, info }) => {
+        try {
+            const value = JSON.parse(await readFile(join(runs, name), 'utf8'));
+            const id = typeof value.id === 'string' ? value.id : name.slice(0, -5);
+            const usage = (value.usage ?? {});
+            // The result file is written when the run finishes, so its timestamp is an end time. The
+            // journal's first event is the start, which is what a duration is measured from.
+            const startedAt = await firstEventTime(join(runs, `${id}.jsonl`)) ?? info.mtime.toISOString();
+            return {
+                id, status: String(value.status ?? 'unknown'), graph: String(typeof value.graph === 'object' && value.graph ? value.graph.id ?? 'default' : value.graph ?? 'default'),
+                provider: String(value.provider ?? ''), model: String(value.model ?? ''),
+                startedAt, updatedAt: info.mtime.toISOString(),
+                usage: { inputTokens: usage.inputTokens ?? 0, outputTokens: usage.outputTokens ?? 0, requests: usage.requests ?? 0, ...(usage.cacheRead === undefined ? {} : { cacheRead: usage.cacheRead }), ...(usage.cacheWrite === undefined ? {} : { cacheWrite: usage.cacheWrite }) },
+                toolCalls: typeof value.toolCalls === 'number' ? value.toolCalls : 0,
+                ...(typeof value.sessionId === 'string' ? { sessionId: value.sessionId } : {}),
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    const selected = records.filter((value) => value !== undefined)
+        .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt));
+    const titles = await runTitles(directory, new Set(selected.map(run => run.id)));
+    // One walk cache for the whole listing: two legacy runs of one lineage share their ancestor reads.
+    const lineage = new Map();
+    return await Promise.all(selected.map(async (run) => {
+        const title = titles.get(run.id);
+        // Older records may not name their session; the session history does, which is also where the
+        // task title comes from. A record that names its own session is taken at its word — the fill is
+        // for records written before the field existed, and those get their owner from the lineage's
+        // originating record rather than from whichever copy of the history the scan reached first.
+        if (title === undefined)
+            return run;
+        if (run.sessionId !== undefined)
+            return { ...run, task: title.task };
+        const origin = await originatingSession(directory, title.session, run.id, lineage);
+        return { ...run, task: title.task, sessionId: origin.id };
+    }));
+}
+/**
+ * Bytes read per backward pass while looking for a journal's newest events.
+ *
+ * The slice a client wants is the end of the file, and a run can write a journal far larger than
+ * that slice: reading it forward to keep the last five thousand lines would cost latency, disk, and
+ * JSON parsing proportional to the whole file for every open of the run's detail. Blocks are read
+ * backwards from the end and concatenated as bytes, so a multi-byte character split across a block
+ * boundary is decoded once, after the window is assembled.
+ */
+const JOURNAL_TAIL_BLOCK_BYTES = 256 * 1024;
+/**
+ * How many bytes of a journal's tail are assembled at most.
+ *
+ * The event count alone is not a bound: a tool event may carry up to 24,000 characters, so five
+ * thousand of them approach 120 MB of reads, concatenation, and parsing for one open of a run's
+ * detail. A byte budget is what keeps the work proportional to what a client can display, and a
+ * window that stops here is reported as truncated like any other.
+ */
+const JOURNAL_TAIL_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * The newest `limit` lines of a journal, read from the end of the file.
+ *
+ * Returns the parsed lines in file order, plus whether older lines exist beyond the window. At most
+ * one block is read past what the limit needs, so the work follows the slice, not the file.
+ */
+async function readJournalTail(path, limit) {
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        const { size } = await handle.stat();
+        const blocks = [];
+        let position = size;
+        // Newlines seen in what has been read so far, which is what says whether the window already
+        // covers more lines than the limit.
+        let newlines = 0;
+        let bytes = 0;
+        while (position > 0 && newlines <= limit && bytes < JOURNAL_TAIL_MAX_BYTES) {
+            const length = Math.min(JOURNAL_TAIL_BLOCK_BYTES, position);
+            position -= length;
+            const block = Buffer.allocUnsafe(length);
+            const { bytesRead } = await handle.read(block, 0, length, position);
+            blocks.unshift(block.subarray(0, bytesRead));
+            bytes += bytesRead;
+            for (const byte of block.subarray(0, bytesRead))
+                if (byte === 0x0a)
+                    newlines += 1;
+        }
+        const text = Buffer.concat(blocks).toString('utf8');
+        const lines = text.split('\n');
+        // The window starts mid-file unless it reached byte zero, so its first line is a fragment of a
+        // line whose beginning was not read; it is not an event.
+        if (position > 0)
+            lines.shift();
+        return { lines, truncated: position > 0 || newlines > limit };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return { lines: [], truncated: false };
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+/**
+ * Read one run's result and its journal.
+ *
+ * The slice returned is the *newest* part of the journal, because that is what a detail view is read
+ * for — the run's latest activity, with tool calls whose results arrived, rather than the opening
+ * events of a run whose outcome the record already reports. Reading starts at the end of the file, so
+ * a journal larger than the cap costs what the slice needs and not what the file holds, and
+ * `truncated` says older events exist beyond it so a client can label the slice instead of presenting
+ * it as the whole journal.
+ */
+export async function readRun(directory, id) {
+    const path = runRecordPath(directory, id, 'json');
+    const result = JSON.parse(await readFile(path, 'utf8'));
+    const journal = runRecordPath(directory, id, 'jsonl');
+    const { lines, truncated } = await readJournalTail(journal, MAX_RUN_EVENTS);
+    const events = [];
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            continue;
+        } // A torn final line is not a client error.
+    }
+    // The window may hold one block more than the limit, and a journal whose lines are short can hold
+    // many: the newest entries are the ones that stay.
+    return { result, events: events.slice(-MAX_RUN_EVENTS), truncated };
+}
+/**
+ * Where one run's stored result record lives, and whether it holds a finished trajectory.
+ *
+ * Saving a trajectory as JSON and showing it in the file manager both need the file itself rather than its
+ * contents, and this home is the only thing that knows where its records go — so the answer is the engine's
+ * own path plus whether it is actually there. A run whose record was never written, or has since been
+ * deleted, is answered with `exists: false` rather than a throw: "there is nothing to save yet" is a control
+ * the client holds back, not a failure it reports. The id is validated by the same rule every other run read
+ * uses, so a crafted id cannot name a file outside this home's `runs` directory.
+ *
+ * A running attempt's open record answers `exists: false` as well. The record is written the moment the run
+ * starts and finalization rewrites it in place, so its presence is not a trajectory being finished — a copy
+ * taken mid-rewrite can be half of two records. The stat alone used to call that file exportable; reading it
+ * is what lets the answer match what the document is.
+ */
+export async function runRecordFile(directory, id) {
+    // Resolved before it is answered: a home spelled relative to this process's working directory makes
+    // record paths only that process can use, and the shell that copies and reveals them is a different one.
+    const path = resolve(runRecordPath(directory, id, 'json'));
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EISDIR')
+            return { path, exists: false };
+        throw error;
+    }
+    try {
+        if (JSON.parse(raw).status === 'running')
+            return { path, exists: false };
+    }
+    catch {
+        // Unparsable bytes are a record caught mid-rewrite: not a document to offer, whichever run owns it.
+        return { path, exists: false };
+    }
+    return { path, exists: true };
+}
+/**
+ * Where a session's trajectory log lives — the per-session mirror of `runs.files`.
+ *
+ * A session trajectory is append-only, but an independent shell read while the engine is
+ * appending a large JSONL line can end mid-record. Withhold the export action while an open-run
+ * claim exists for this session, including a live run in another engine. Finalization flushes
+ * the trajectory before clearing the claim, so a finished session becomes available only after
+ * all its records are written. The shell additionally guards snapshots against an append that
+ * begins after this lookup. Missing files return `exists: false`; genuine I/O failures surface
+ * to the caller so it can keep the unrelated run-record controls usable.
+ */
+export async function sessionTrajectoryFile(directory, id) {
+    if (typeof id !== 'string' || id.trim() !== id || !/^[\w-]{1,64}$/.test(id))
+        throw new Error('Invalid session id');
+    // Resolved before it is answered, for the same reason the run record path is: the shell that
+    // copies and reveals the file is a different process from this one.
+    const path = resolve(join(directory, 'trajectories', `${id}.jsonl`));
+    try {
+        const info = await stat(path);
+        if (!info.isFile())
+            return { path, exists: false };
+        if (await sessionHasOpenRun(directory, id))
+            return { path, exists: false };
+        return { path, exists: true };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EISDIR')
+            return { path, exists: false };
+        throw error;
+    }
+}
+/** How many records one page of a session's trajectory log carries. */
+const MAX_TRAJECTORY_PAGE_RECORDS = 500;
+/**
+ * How much record data one page carries.
+ *
+ * Every model request repeats the whole conversation history, so a page measured in records alone
+ * would carry the same prompt again and again and grow with the square of the session's length.
+ * The bound is under what a linked machine's relay carries, so a page always fits the transport.
+ */
+const MAX_TRAJECTORY_PAGE_BYTES = 8 * 1024 * 1024;
+/**
+ * How much one record may carry.
+ *
+ * A record larger than this is carried as a marker instead of its own content: a page has to fit
+ * the transport that carries it, and one record must not be able to make a page that no transport
+ * will take.
+ */
+const MAX_TRAJECTORY_RECORD_BYTES = 4 * 1024 * 1024;
+/** How much of the log one read may scan. */
+const MAX_TRAJECTORY_SCAN_BYTES = 256 * 1024 * 1024;
+/**
+ * A record's own fields, without the three the log writes on every line.
+ *
+ * The session id is the log's own name and says nothing about the record, and the type and time are
+ * lifted out so a reader can address them without digging through the payload.
+ */
+function normalizeTrajectoryRecord(record) {
+    const data = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (key === 'type' || key === 'time' || key === 'sessionId')
+            continue;
+        data[key] = value;
+    }
+    return { type: record.type, time: typeof record.time === 'string' ? record.time : '', data };
+}
+/**
+ * A record, with its content held to what a page may carry.
+ *
+ * A record larger than the page's own bound is carried as a marker: the reader is told a record of
+ * that size was there, and the log stays readable and the cursor still moves.
+ */
+function boundedRecord(record, size) {
+    const bounded = normalizeTrajectoryRecord(record);
+    if (size <= MAX_TRAJECTORY_RECORD_BYTES)
+        return bounded;
+    bounded.data = {
+        oversized: true,
+        bytes: size,
+        note: 'The record is larger than a page can carry, so only its size is shown.',
+    };
+    return bounded;
+}
+/** How much of a line's head is kept, to read the type and the time the line was written with. */
+const MAX_TRAJECTORY_LINE_HEAD_BYTES = 4 * 1024;
+/**
+ * A log's lines, read without holding a line that is over the bound.
+ *
+ * `readline` hands a reader the whole line at once, so a log holding one enormous record would
+ * have that record materialised before anything could refuse it. The bytes are counted as they
+ * stream by, and a line over the bound is measured and dropped rather than held whole: the reader
+ * is told how big the line was, and the log stays readable.
+ */
+async function* readTrajectoryLines(stream) {
+    /** The bytes of the line being read, while it is small enough to hold. */
+    let held = [];
+    let heldBytes = 0;
+    /** The head of the line: the type and the time are written first, and they are all that is kept. */
+    let head = '';
+    /** The size of the line being read. */
+    let size = 0;
+    let oversized = false;
+    /** Take a piece of the line being read. */
+    const take = (segment) => {
+        size += segment.length;
+        if (head.length < MAX_TRAJECTORY_LINE_HEAD_BYTES) {
+            head += segment.toString('utf8', 0, Math.min(segment.length, MAX_TRAJECTORY_LINE_HEAD_BYTES - head.length));
+        }
+        if (oversized)
+            return;
+        heldBytes += segment.length;
+        if (heldBytes > MAX_TRAJECTORY_RECORD_BYTES) {
+            oversized = true;
+            held = [];
+            return;
+        }
+        held.push(segment);
+    };
+    /** The line as it stands; the next one starts empty. */
+    const takeLine = () => {
+        const line = { text: oversized ? '' : Buffer.concat(held).toString('utf8'), head, size, oversized };
+        held = [];
+        heldBytes = 0;
+        head = '';
+        size = 0;
+        oversized = false;
+        return line;
+    };
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        let start = 0;
+        for (let index = 0; index < buffer.length; index += 1) {
+            if (buffer[index] !== 0x0a)
+                continue;
+            take(buffer.subarray(start, index));
+            yield takeLine();
+            start = index + 1;
+        }
+        const tail = buffer.subarray(start);
+        if (tail.length > 0)
+            take(tail);
+    }
+    // A last line the writer never ended is a torn record: the log is read while it is being
+    // appended to, and a record that is not terminated was not finished. It is left out rather than
+    // read as a record that may be removed a moment later.
+}
+/**
+ * A record too large to carry, told from the head of its line.
+ *
+ * The log writes the type and the time first, so the head of an enormous line still says what it
+ * was. A line that does not say is reported as an oversized record of its own.
+ */
+function oversizedRecord(head, size) {
+    const type = /^\s*\{\s*"type"\s*:\s*"([^"]*)"/.exec(head)?.[1] ?? 'oversized';
+    const time = /^\s*\{\s*"type"\s*:\s*"[^"]*"\s*,\s*"time"\s*:\s*"([^"]*)"/.exec(head)?.[1] ?? '';
+    return { type, time, data: { oversized: true, bytes: size, note: 'The record is larger than a page can carry, so only its size is shown.' } };
+}
+/**
+ * Read one page of a session's trajectory log.
+ *
+ * The log is the session's own debug file: every run and every resume appends to it, so it holds the
+ * whole conversation — each prompt, each model call, each runtime event, in the order they happened.
+ * A client reads it the way it reads a long document, one page at a time, and the page says how much
+ * of the log it did not carry so the reader can say so rather than present a slice as the whole.
+ *
+ * The records are read in the order the log wrote them, from the beginning: a debugging reader wants
+ * the first prompt as much as the last one. The scan continues past the page to count what the log
+ * holds, so the reader can say "record 200 of 3,412" instead of guessing.
+ *
+ * The page's position in the log is a **line**, and the page answers with the line the next one
+ * starts at. A reader that asked for a page past the end of what one read can cover is answered
+ * from where the last page stopped rather than from the beginning, so the rest of a long log stays
+ * reachable page by page.
+ *
+ * A log that is still being appended to is read as it stands. The engine never rewrites one, so a
+ * record that is half-written is a torn line and is skipped rather than guessed at.
+ *
+ * `folder` names which of the home's logs to read: the engine's `trajectories`, or the
+ * `browser-trajectories` the CLI's browser workspace records its own runs to.
+ */
+export async function readSessionTrajectory(directory, id, offset, limit, folder = 'trajectories') {
+    const path = resolve(join(directory, folder, `${id}.jsonl`));
+    const start = typeof offset === 'number' && Number.isInteger(offset) && offset > 0 ? offset : 0;
+    const wanted = typeof limit === 'number' && Number.isInteger(limit) && limit > 0
+        ? Math.min(limit, MAX_TRAJECTORY_PAGE_RECORDS) : MAX_TRAJECTORY_PAGE_RECORDS;
+    const records = [];
+    let total = 0;
+    let carried = 0;
+    let scanned = 0;
+    let line = 0;
+    /** The line the next page starts at: the line after the last record this page carries. */
+    let next = start;
+    /** The records the log holds past the page. */
+    let after = 0;
+    let full = false;
+    let truncated = false;
+    let exists = true;
+    try {
+        const stream = createReadStream(path);
+        try {
+            for await (const entry of readTrajectoryLines(stream)) {
+                line += 1;
+                const size = entry.size;
+                // The budget covers the tail the reader asked for, not the way to it: a page past the
+                // budget is still served, because the way to it has to be read either way. A budget that
+                // stopped the scan before the cursor would leave the rest of the log unreachable.
+                /**
+                 * Carry a record too large to hold as its size.
+                 *
+                 * The log stays readable and the cursor still moves, and the line was never held whole.
+                 */
+                const carryOversized = () => {
+                    total += 1;
+                    if (line <= start)
+                        return;
+                    if (full) {
+                        after += 1;
+                        return;
+                    }
+                    if (records.length > 0 && carried + size > MAX_TRAJECTORY_PAGE_BYTES) {
+                        full = true;
+                        after += 1;
+                        return;
+                    }
+                    carried += size;
+                    records.push(oversizedRecord(entry.head, size));
+                    next = line;
+                    if (records.length >= wanted)
+                        full = true;
+                };
+                if (line > start) {
+                    scanned += size;
+                    if (scanned > MAX_TRAJECTORY_SCAN_BYTES) {
+                        // The scan stopped here. The cursor moves past the line it stopped at, so the next
+                        // read starts after it instead of asking for the same place for ever. A record too
+                        // large to hold is still told about, so a large model request does not disappear.
+                        if (entry.oversized)
+                            carryOversized();
+                        truncated = true;
+                        if (records.length === 0)
+                            next = line;
+                        break;
+                    }
+                }
+                if (entry.oversized) {
+                    carryOversized();
+                    continue;
+                }
+                const raw = entry.text;
+                if (!raw.trim())
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    continue;
+                } // A torn line is not a record.
+                if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                    continue;
+                const record = parsed;
+                if (typeof record.type !== 'string')
+                    continue;
+                total += 1;
+                // Before the cursor the log is only counted, and past the page it is only counted: the
+                // reader asked for a window, and the count is what tells it how much it left out.
+                if (line <= start)
+                    continue;
+                if (full) {
+                    after += 1;
+                    continue;
+                }
+                // A record larger than the page budget still goes on the page: a page that carried
+                // nothing would leave the reader asking for the same offset for ever.
+                if (records.length > 0 && carried + size > MAX_TRAJECTORY_PAGE_BYTES) {
+                    full = true;
+                    after += 1;
+                    continue;
+                }
+                carried += size;
+                records.push(boundedRecord(record, size));
+                next = line;
+                if (records.length >= wanted)
+                    full = true;
+            }
+        }
+        finally {
+            stream.destroy();
+        }
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EISDIR')
+            exists = false;
+        else
+            throw error;
+    }
+    return {
+        path, exists, offset: start, nextOffset: next, count: records.length, total, records,
+        // The log holds more past this page when the scan found records there, or when the scan
+        // stopped before it could say.
+        hasMore: after > 0 || truncated,
+        truncated,
+    };
+}
+/**
+ * One line describing a configured MCP server, without anything that authenticates it.
+ *
+ * A stdio command line can carry `--token <value>` and an HTTP URL can carry a query string; both are
+ * permitted by the configuration schema, and both reach this renderer's Settings view. Only the
+ * command itself and the URL's scheme, host, and path are reported, matching the deliberate omission
+ * of MCP environment and header values.
+ */
+export function summarizeMcpServer(server) {
+    if (server.transport === 'stdio')
+        return server.command;
+    try {
+        const url = new URL(server.url);
+        return `${url.protocol}//${url.host}${url.pathname}`;
+    }
+    catch {
+        return '';
+    }
+}
+/** Installed skills, plugins, and configured MCP servers. Secrets in env/headers are never included. */
+export async function listExtensions(config, signal, directory) {
+    const map = (entry) => ({ id: entry.id, name: entry.name, description: entry.description, enabled: entry.enabled, ...(entry.unavailable ? { unavailable: true } : {}), ...(entry.repository ? { repository: entry.repository } : {}), ...(entry.relativePath === undefined ? {} : { relativePath: entry.relativePath }), ...(entry.command ? { command: entry.command } : {}) });
+    // Discovery stops at its own bound, and the notice it produces is the only thing that says so: a
+    // client that showed the list without it would present a capped catalogue as the whole installation.
+    const notices = [];
+    const [skills, plugins] = await Promise.all([
+        listBundles('skills', config, { signal, notices, directory }),
+        listBundles('plugins', config, { signal, notices, directory }),
+    ]);
+    return {
+        skills: skills.map(map), plugins: plugins.map(map),
+        mcpServers: Object.entries(config.mcpServers ?? {}).map(([id, server]) => ({
+            id, transport: server.transport, enabled: server.enabled !== false,
+            summary: summarizeMcpServer(server),
+        })),
+        notices,
+    };
+}