@khorsheed/dsh-local-agent-claude-code 0.1.0-rc.6

package/lib/types/records.js

@@ -0,0 +1,687 @@
+/**
+ * Claude Code session records adapter: scans the scoped home's `projects/`
+ * session files (one JSONL per session under `projects/<cwd-slug>/`, the
+ * slug being the workspace path with separators replaced by dashes), plus
+ * the transcript model read-back ({@link readClaudeTranscriptModel}) the
+ * model broker's `lastObserved` backstop runs on. The
+ * slug is a LOSSY encoding of the cwd — different paths can collide on the
+ * same slug — so the listed cwd always comes from the file CONTENT (the
+ * first `user` event's `cwd` field), never from the directory name. Only the
+ * head of each file is read — the first user event carries the id, cwd, and
+ * timestamp the listing needs; the rest of the file (conversation) is not
+ * parsed. Files are append-only with torn-tail tolerance, and contents are
+ * always untrusted input.
+ * @module @khorsheed/dsh-local-agent-claude-code/records
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+/** Session files live under this directory inside the scoped home. */
+const PROJECTS_ROOT = 'projects';
+/** Bound on the head prefix read from one session file. */
+const HEAD_BYTES = 64 * 1024;
+/**
+ * Bound on the tail read when extracting a transcript's model. Assistant
+ * lines are frequent, so the last window almost always names one; a bigger
+ * conversation is never read whole.
+ */
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+/** Cap on project directories the transcript reads scan. */
+const TRANSCRIPT_SCAN_DIRS = 200;
+/** Cap on transcript files the harness-level newest-scan stats. */
+const TRANSCRIPT_SCAN_FILES = 500;
+/** Cap on sidechain (`agent-*.jsonl`) candidates inspected for one session id. */
+const TRANSCRIPT_SIDECHAIN_FILES = 100;
+/** How many newest transcripts the harness-level read tries before giving up. */
+const TRANSCRIPT_NEWEST_TRIES = 3;
+/** Test-swappable process exec (the keychain read goes through `security`). */
+export const internals = {
+    exec: promisify(execFile),
+};
+/**
+ * The scoped `.claude.json`'s modification stamp (epoch ms), undefined when
+ * absent. A completed login rewrites this file, so the stamp distinguishes a
+ * fresh login from a leftover marker (a revoked token's record lingers).
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the marker's mtime, or undefined when no scoped config exists.
+ */
+export async function claudeCredentialStamp(homeDir) {
+    try {
+        return (await stat(join(homeDir, '.claude.json'))).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The keychain entry name current claude uses for a non-default config dir:
+ * the bare name belongs to `~/.claude`, other dirs get a path-hash suffix.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the macOS keychain service name holding the OAuth credential.
+ */
+function keychainService(homeDir) {
+    const hash = createHash('sha256').update(homeDir).digest('hex').slice(0, 8);
+    return `Claude Code-credentials-${hash}`;
+}
+/**
+ * Whether a credential blob is USABLE: the token record nests under
+ * `claudeAiOauth`, and a blob whose access AND refresh tokens are both empty
+ * is a shell. macOS keeps historical items under the same service (an early
+ * claude wrote an `acct=unknown` placeholder with blank tokens and
+ * `expiresAt: 0`), and mirroring one into the credentials file makes every
+ * delegation report "OAuth session expired and could not be refreshed" —
+ * indistinguishable from a real expiry while login looks successful. A
+ * non-empty token is the bar for mirroring a blob or keeping a file.
+ * @param text - the raw credential JSON.
+ * @returns true when the blob carries a non-empty token.
+ */
+function credentialUsable(text) {
+    try {
+        const parsed = JSON.parse(text);
+        const oauth = parsed.claudeAiOauth;
+        return (typeof oauth?.accessToken === 'string' && oauth.accessToken !== '')
+            || (typeof oauth?.refreshToken === 'string' && oauth.refreshToken !== '');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A `security dump-keychain` timedate as epoch ms; undefined when the shape is
+ * not recognized (the item then sorts as oldest).
+ *
+ * The shape that matters is the COMPACT Zulu stamp `20260916040855Z`, because
+ * that is what the tool actually prints — with the attribute's trailing NUL
+ * rendered as a literal `\000` after the closing digit, so the match must not
+ * anchor at the end. Only the spaced `2026-09-01 02:03:04 +0000` form was
+ * parsed before, which no `security` build was observed to emit: every item
+ * fell to the `?? 0` default, the newest-first sort over all-equal keys
+ * degenerated to the dump's own order (a stable sort), and
+ * `readKeychainCredential` returned whichever usable item the dump happened to
+ * list first. A scoped home that had been logged in twice then kept serving the
+ * SUPERSEDED credential — the fresh login sat unread in the keychain while the
+ * runtime ran on a generation whose refresh token was already spent. The
+ * spaced form is still accepted in case some build does emit it.
+ * @param text - the quoted timedate string from the dump.
+ * @returns the epoch milliseconds, or undefined.
+ */
+function keychainTimestamp(text) {
+    const trimmed = text.trim();
+    const compact = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})Z/.exec(trimmed);
+    if (compact !== null) {
+        const at = (index) => Number(compact[index]);
+        const ms = Date.UTC(at(1), at(2) - 1, at(3), at(4), at(5), at(6));
+        return Number.isFinite(ms) ? ms : undefined;
+    }
+    const spaced = /^(\d{4})-(\d{2})-(\d{2}) (\d{2}):(\d{2}):(\d{2}) ([+-])(\d{2})(\d{2})$/.exec(trimmed);
+    if (spaced === null)
+        return undefined;
+    const part = (index) => Number(spaced[index]);
+    const offsetMinutes = (part(8) * 60 + part(9)) * (spaced[7] === '+' ? 1 : -1);
+    const ms = Date.UTC(part(1), part(2) - 1, part(3), part(4), part(5), part(6)) - offsetMinutes * 60_000;
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/**
+ * Every account holding an item under the service, newest write first. macOS
+ * allows SEVERAL items per service, and an unscoped `find-generic-password
+ * -w` returns the FIRST match — which can be a historical empty shell (see
+ * `credentialUsable`) — so the sync enumerates instead of trusting the first
+ * hit. The dump prints metadata only (no secrets); a failing dump or a parse
+ * miss yields an empty list, and the caller then falls back to the unscoped
+ * read.
+ * @param service - the keychain service name.
+ * @returns the accounts, newest modification first.
+ */
+async function keychainItems(service) {
+    let stdout;
+    try {
+        ({ stdout } = await internals.exec('security', ['dump-keychain']));
+    }
+    catch {
+        return [];
+    }
+    const items = [];
+    let svce;
+    let acct;
+    let mdat = 0;
+    const flush = () => {
+        if (svce === service && acct !== undefined)
+            items.push({ acct, mdat });
+        svce = undefined;
+        acct = undefined;
+        mdat = 0;
+    };
+    for (const line of stdout.split('\n')) {
+        // Each item block opens with its `keychain:` header line.
+        if (line.startsWith('keychain:')) {
+            flush();
+            continue;
+        }
+        const trimmed = line.trim();
+        const svceMatch = /^"svce"<blob>="(.*)"$/.exec(trimmed);
+        if (svceMatch !== null) {
+            svce = svceMatch[1];
+            continue;
+        }
+        const acctMatch = /^"acct"<blob>="(.*)"$/.exec(trimmed);
+        if (acctMatch !== null) {
+            acct = acctMatch[1];
+            continue;
+        }
+        const mdatMatch = /^"mdat"<timedate>=0x[0-9a-fA-F]+\s+"(.*)"$/.exec(trimmed);
+        if (mdatMatch !== null)
+            mdat = keychainTimestamp(mdatMatch[1] ?? '') ?? 0;
+    }
+    flush();
+    return items.sort((a, b) => b.mdat - a.mdat);
+}
+/**
+ * One keychain read: the item for `acct` when given, else the first match.
+ * Returns the raw blob only when it is USABLE (non-empty token); anything
+ * else — missing item, unreadable payload, an empty shell — is undefined.
+ * @param service - the keychain service name.
+ * @param acct - the account to read, or undefined for the unscoped first match.
+ * @returns the credential blob, or undefined.
+ */
+async function readKeychainEntry(service, acct) {
+    try {
+        const args = ['find-generic-password', '-s', service];
+        if (acct !== undefined)
+            args.push('-a', acct);
+        args.push('-w');
+        const { stdout } = await internals.exec('security', args);
+        const blob = stdout.trim();
+        return credentialUsable(blob) ? blob : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The usable credential blob for this scoped home, or undefined. Every
+ * account under the service is tried newest-write-first and the first
+ * non-empty token wins; when enumeration itself is unavailable (not macOS, a
+ * failing dump) the legacy unscoped read still runs, held to the same
+ * non-empty-token bar.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the credential blob, or undefined when nothing usable is stored.
+ */
+async function readKeychainCredential(homeDir) {
+    const service = keychainService(homeDir);
+    const items = await keychainItems(service);
+    for (const item of items) {
+        const blob = await readKeychainEntry(service, item.acct);
+        if (blob !== undefined)
+            return blob;
+    }
+    // An enumerated-but-all-empty service has no fallback worth trying.
+    return items.length > 0 ? undefined : readKeychainEntry(service, undefined);
+}
+/**
+ * The stored credential's expiry (epoch ms), read from the USABLE macOS
+ * keychain item for this scoped home (see `readKeychainCredential`);
+ * undefined when no usable item exists or it carries no expiry (presence
+ * alone then decides, as before). The READ side takes the LATER of the
+ * access-token and refresh-token expiries: the CLI refreshes on use, so a
+ * live refresh token means the credential still works.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the expiry, or undefined when unknown.
+ */
+async function readCredentialExpiry(homeDir) {
+    const blob = await readKeychainCredential(homeDir);
+    return blob === undefined ? undefined : credentialFileExpiry(blob);
+}
+/**
+ * The ACCESS-token expiry (epoch ms) of a credential blob — the freshness key
+ * the sync compares the two stores on. Deliberately not
+ * {@link credentialFileExpiry}: that one answers "is this credential still
+ * usable" and takes the LATER of the two expiries, so two generations of one
+ * grant share a refresh expiry and compare equal. A refresh always mints a
+ * later ACCESS expiry, which is exactly what tells the generations apart.
+ * @param text - the raw credential JSON.
+ * @returns the access-token expiry, or undefined when absent or unparseable.
+ */
+function credentialAccessExpiry(text) {
+    try {
+        const access = JSON.parse(text).claudeAiOauth?.expiresAt;
+        return typeof access === 'number' ? access : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Reconcile the keychain credential with `<homeDir>/.credentials.json`,
+ * NEWER WINS. Claude 2.1.236 on macOS WRITES the scoped login to the hashed
+ * keychain entry but READS the credentials file at runtime (the same
+ * write/read split as the Linux #47661 bug) — a login that lands only in the
+ * keychain still answers "Not logged in", so the file has to be kept current.
+ *
+ * The file is not this process's private mirror, though: a containerized
+ * round bind-mounts this very directory read-write (the unit has no keychain,
+ * so the CLI inside it reads and writes the file), and the pre-spawn sync runs
+ * against the HOST path moments before the unit reads it through the mount.
+ * An unconditional mirror therefore makes this function the one participant
+ * that can move the credential chain BACKWARD: it hands the next run a refresh
+ * token the other writer already spent, the endpoint rejects it, and the CLI
+ * answers by CLEARING the file — which logs the instance out, because that
+ * file is the instance's credential. So the keychain blob is written only when
+ * it is not older than the file's. Undefined expiry on either side keeps the
+ * pre-newer-wins behavior (the keychain writes), and a file that is not USABLE
+ * never wins.
+ *
+ * Only a USABLE blob (non-empty token, see `readKeychainCredential`) is
+ * mirrored; with none in the keychain, a file holding an empty-token shell —
+ * debris from an earlier first-match read, or a cleared credential — is
+ * REMOVED, so the runtime says "Not logged in" instead of the misleading
+ * "OAuth session expired". Idempotent and content-compare before write.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param log - warn channel for the two decisions that used to be silent.
+ * @returns true when a usable credential is in the file after the call.
+ */
+export async function syncClaudeCredentialFile(homeDir, log) {
+    const file = join(homeDir, '.credentials.json');
+    let existing;
+    try {
+        existing = await readFile(file, 'utf8');
+    }
+    catch {
+        // Absent or unreadable: the keychain decides alone.
+    }
+    const fileUsable = existing !== undefined && credentialUsable(existing);
+    const blob = await readKeychainCredential(homeDir);
+    if (blob === undefined) {
+        // A usable file with nothing in the keychain is the only credential there
+        // is (a Linux host stores nowhere else) — left exactly as it stands.
+        if (existing !== undefined && !fileUsable)
+            await rm(file, { force: true });
+        return fileUsable;
+    }
+    if (existing !== undefined && existing.trim() === blob)
+        return true;
+    if (fileUsable) {
+        const fileExpiry = credentialAccessExpiry(existing);
+        const blobExpiry = credentialAccessExpiry(blob);
+        if (fileExpiry !== undefined && blobExpiry !== undefined && fileExpiry > blobExpiry) {
+            // The other writer is ahead. Said out loud because it is rare, because
+            // it is the signature of a containerized round having rotated the grant,
+            // and because reconstructing the previous occurrence took a file mtime
+            // and a pilot log. Expiries only — never token material.
+            log?.(`local-agent-claude-code: ${homeDir}/.credentials.json is AHEAD of the keychain`
+                + ` (file access expiry ${new Date(fileExpiry).toISOString()},`
+                + ` keychain ${new Date(blobExpiry).toISOString()}) — keeping the file;`
+                + ' something else refreshed this grant (a containerized round mounts this directory read-write)');
+            return true;
+        }
+    }
+    if (existing !== undefined && !fileUsable) {
+        log?.(`local-agent-claude-code: ${homeDir}/.credentials.json held a cleared credential`
+            + ' (both tokens empty) and is being restored from the keychain'
+            + ` (access expiry ${new Date(credentialAccessExpiry(blob) ?? 0).toISOString()});`
+            + ' if the next round fails to authenticate, this grant was already spent and the scope needs a fresh login');
+    }
+    await writeFile(file, blob, { mode: 0o600 });
+    return true;
+}
+/**
+ * The expiry (epoch ms) from a `.credentials.json` payload; the token record
+ * nests under `claudeAiOauth`. Returns the LATER of the access-token and
+ * refresh-token expiries — the CLI refreshes on use, so a live refresh token
+ * keeps the credential usable past the access expiry. Undefined when
+ * absent/unparseable.
+ * @param text - the file contents.
+ * @returns the expiry, or undefined.
+ */
+function credentialFileExpiry(text) {
+    try {
+        const parsed = JSON.parse(text);
+        const access = parsed.claudeAiOauth?.expiresAt;
+        const refresh = parsed.claudeAiOauth?.refreshTokenExpiresAt;
+        const accessMs = typeof access === 'number' ? access : undefined;
+        const refreshMs = typeof refresh === 'number' ? refresh : undefined;
+        if (accessMs === undefined && refreshMs === undefined)
+            return undefined;
+        return Math.max(accessMs ?? 0, refreshMs ?? 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether the scoped home holds usable Claude Code credentials: the scoped
+ * `.claude.json` carries an `oauthAccount` record once a device-code login
+ * has completed, AND the keychain credential is not past its stored expiry
+ * (when the expiry is readable — a server-side REVOCATION is not visible
+ * locally; providers report those through `localAgent.reportAuthFailure`).
+ * The real credential lives in the macOS keychain under a hashed entry
+ * (`Claude Code-credentials-<sha256(path)[:8]>`, hashed from the config-dir
+ * path) or in the default `~/.claude/.credentials.json` on Linux (upstream
+ * bug #47661: `CLAUDE_CONFIG_DIR` does not isolate the credentials file
+ * there — it writes the scoped dir but READS the default home, so Linux
+ * credentials may exist even when the scoped home has none). Spawning the
+ * CLI to probe auth is avoided; the platform differences are documented in
+ * the README.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param log - warn channel handed to the credential reconcile below.
+ * @returns true when a completed login is recorded and not locally expired.
+ */
+export async function claudeAuthenticated(homeDir, log) {
+    // The runtime reads `.credentials.json` first (claude 2.1.236 writes the
+    // keychain but reads the file) — and a CLI run refreshes the KEYCHAIN copy
+    // without touching the file, so reconcile keychain↔file before judging, or a
+    // refreshed credential still reads expired. Newer wins: this probe runs on
+    // every status read and every readiness check, so an unconditional mirror
+    // here would undo a containerized round's refresh just as surely as the
+    // spawn sites would.
+    await syncClaudeCredentialFile(homeDir, log);
+    let fileExpiry;
+    let filePresent = false;
+    try {
+        const text = await readFile(join(homeDir, '.credentials.json'), 'utf8');
+        fileExpiry = credentialFileExpiry(text);
+        filePresent = true;
+    }
+    catch {
+        // No credentials file: fall through to the keychain-backed check.
+    }
+    if (filePresent)
+        return fileExpiry === undefined || fileExpiry > Date.now();
+    let text;
+    try {
+        text = await readFile(join(homeDir, '.claude.json'), 'utf8');
+    }
+    catch (error) {
+        // No scoped config yet: not authenticated.
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    let config;
+    try {
+        config = JSON.parse(text);
+    }
+    catch {
+        // A torn or malformed config reads as not authenticated.
+        return false;
+    }
+    if (config.oauthAccount === undefined || config.oauthAccount === null)
+        return false;
+    // Presence established; refuse a credential past its stored expiry. A
+    // server-side revocation is not locally visible — that path reports through
+    // the delegation's 401/403, not this probe.
+    const expiry = await readCredentialExpiry(homeDir);
+    return expiry === undefined || expiry > Date.now();
+}
+/**
+ * Parse the head of a session file for the listing fields. The first `user`
+ * event carries `sessionId`, `cwd`, and `timestamp`; its `cwd` is the only
+ * trustworthy workspace source (the directory slug is lossy). Unknown or
+ * malformed values yield an undefined record rather than failing the list.
+ * @param text - the raw session file head (only the head is read).
+ * @returns the record, or undefined when no user event is found.
+ */
+export function projectRecord(text) {
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line === '')
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event.type !== 'user')
+            continue;
+        if (typeof event.sessionId !== 'string' || event.sessionId === '')
+            return undefined;
+        if (typeof event.cwd !== 'string')
+            return undefined;
+        const record = { id: event.sessionId, workDir: event.cwd };
+        const startedAt = typeof event.timestamp === 'string' ? Date.parse(event.timestamp) : undefined;
+        if (startedAt !== undefined && Number.isFinite(startedAt))
+            record.startedAt = startedAt;
+        return record;
+    }
+    return undefined;
+}
+/**
+ * Read the scoped home's session files. The listing walks the projects
+ * directory and reads each jsonl head; a torn or malformed file is skipped
+ * rather than failing the whole list.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the parsed records, empty when no sessions exist yet.
+ */
+export async function listClaudeSessions(homeDir) {
+    const records = [];
+    let projectDirs;
+    try {
+        projectDirs = await readdir(join(homeDir, PROJECTS_ROOT));
+    }
+    catch (error) {
+        // No projects root yet: nothing to list.
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    for (const projectDir of projectDirs) {
+        let files;
+        try {
+            files = await readdir(join(homeDir, PROJECTS_ROOT, projectDir));
+        }
+        catch {
+            continue;
+        }
+        for (const name of files) {
+            if (!name.endsWith('.jsonl'))
+                continue;
+            try {
+                // Only the head matters; read a bounded prefix rather than the whole
+                // (potentially long) conversation log.
+                const handle = await open(join(homeDir, PROJECTS_ROOT, projectDir, name), 'r');
+                let text;
+                try {
+                    const buffer = Buffer.alloc(HEAD_BYTES);
+                    const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
+                    text = buffer.subarray(0, bytesRead).toString('utf8');
+                }
+                finally {
+                    await handle.close();
+                }
+                const record = projectRecord(text);
+                if (record !== undefined)
+                    records.push(record);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return records;
+}
+/**
+ * Extract the model one transcript names, reading its TAIL (bounded, never
+ * the whole conversation) from the newest line backward: the first line
+ * carrying a model wins — the top-level `model` of the stream-json init
+ * event's shape, or the nested `message.model` of an assistant line. Newest
+ * first because a session's later rounds may run a different model than its
+ * first, and "what ran last" is the question the caller asks. A torn final
+ * line is skipped, never failed on.
+ * @param path - the transcript file.
+ * @returns the model identifier, or undefined when the window names none.
+ */
+async function transcriptFileModel(path) {
+    let text;
+    try {
+        const handle = await open(path, 'r');
+        try {
+            const { size } = await handle.stat();
+            const length = Math.min(size, TRANSCRIPT_TAIL_BYTES);
+            const buffer = Buffer.alloc(length);
+            const { bytesRead } = await handle.read(buffer, 0, length, Math.max(0, size - length));
+            text = buffer.subarray(0, bytesRead).toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const lines = text.split('\n');
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index].trim();
+        if (line === '')
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof event.model === 'string' && event.model !== '')
+            return event.model;
+        if (typeof event.message?.model === 'string' && event.message.model !== '')
+            return event.message.model;
+    }
+    return undefined;
+}
+/** The project directories under one scoped home, capped; empty on any failure. */
+async function projectDirs(homeDir) {
+    try {
+        return (await readdir(join(homeDir, PROJECTS_ROOT))).slice(0, TRANSCRIPT_SCAN_DIRS);
+    }
+    catch {
+        return [];
+    }
+}
+/** The jsonl file names inside one project directory; empty on any failure. */
+async function projectFiles(homeDir, projectDir) {
+    try {
+        return (await readdir(join(homeDir, PROJECTS_ROOT, projectDir))).filter(name => name.endsWith('.jsonl'));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Whether a sidechain (`agent-*.jsonl`) transcript belongs to one session:
+ * its head lines carry the PARENT session's id (`isSidechain: true`). Only
+ * the bounded head is read.
+ */
+async function sidechainSessionMatches(path, cliSessionId) {
+    let text;
+    try {
+        const handle = await open(path, 'r');
+        try {
+            const buffer = Buffer.alloc(HEAD_BYTES);
+            const { bytesRead } = await handle.read(buffer, 0, HEAD_BYTES, 0);
+            text = buffer.subarray(0, bytesRead).toString('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return false;
+    }
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line === '')
+            continue;
+        try {
+            if (JSON.parse(line).sessionId === cliSessionId)
+                return true;
+        }
+        catch {
+            continue;
+        }
+    }
+    return false;
+}
+/**
+ * The model a member's OWN CLI transcript names — the history backstop for
+ * the broker's `lastObserved` when no delegation record observed one (every
+ * member whose rounds predate the live-settle report). The live-settle
+ * channel remains primary (the record's `observedModel` wins when present);
+ * this reader only answers "what did this session last run" from the CLI's
+ * own files, read-only — nothing is backfilled into `delegations.jsonl`.
+ *
+ * Location rule: with `cliSessionId`, the main transcript
+ * `projects/<cwd-slug>/<cliSessionId>.jsonl` (found by NAME across the
+ * project dirs — the slug is lossy, so it is never computed); when it is
+ * absent, a sidechain `agent-*.jsonl` whose head names the session id
+ * (bounded candidate count) answers instead. Without `cliSessionId` (the
+ * settings card's memberless read), the NEWEST transcript across the
+ * projects tree (mtime, bounded dir/file scan) answers; a newest file that
+ * names no model yields to the next, up to a few tries. Every failure —
+ * missing tree, unreadable file, no model in the read window — is
+ * `undefined`, never a throw.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param cliSessionId - the delegation record's CLI session id, when the
+ *   member's own transcript is wanted.
+ * @returns the model identifier, or undefined.
+ */
+export async function readClaudeTranscriptModel(homeDir, cliSessionId) {
+    if (cliSessionId !== undefined) {
+        let main;
+        const sidechains = [];
+        for (const projectDir of await projectDirs(homeDir)) {
+            for (const name of await projectFiles(homeDir, projectDir)) {
+                if (name === `${cliSessionId}.jsonl` && main === undefined) {
+                    main = join(homeDir, PROJECTS_ROOT, projectDir, name);
+                    continue;
+                }
+                if (name.startsWith('agent-') && sidechains.length < TRANSCRIPT_SIDECHAIN_FILES) {
+                    sidechains.push(join(homeDir, PROJECTS_ROOT, projectDir, name));
+                }
+            }
+        }
+        // The main transcript answers first; a main file that names no model in
+        // its tail window yields to the sidechains.
+        if (main !== undefined) {
+            const model = await transcriptFileModel(main);
+            if (model !== undefined)
+                return model;
+        }
+        // A sidechain sharing the session id is the only other place the
+        // session's model is written (e.g. the round ran as a Task subagent, or
+        // the main file is too sparse to name one).
+        for (const path of sidechains) {
+            if (await sidechainSessionMatches(path, cliSessionId)) {
+                const model = await transcriptFileModel(path);
+                if (model !== undefined)
+                    return model;
+            }
+        }
+        return undefined;
+    }
+    // Harness level: the newest transcript in the tree speaks for the harness.
+    const candidates = [];
+    let scanned = 0;
+    for (const projectDir of await projectDirs(homeDir)) {
+        for (const name of await projectFiles(homeDir, projectDir)) {
+            if (scanned >= TRANSCRIPT_SCAN_FILES)
+                break;
+            scanned += 1;
+            const path = join(homeDir, PROJECTS_ROOT, projectDir, name);
+            try {
+                candidates.push({ path, mtimeMs: (await stat(path)).mtimeMs });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (const candidate of candidates.slice(0, TRANSCRIPT_NEWEST_TRIES)) {
+        const model = await transcriptFileModel(candidate.path);
+        if (model !== undefined)
+            return model;
+    }
+    return undefined;
+}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Claude Delegation",
+    "description": "Delegate coding tasks to local Claude Code with live answers."
+  }
+}