@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/control/files.js

@@ -0,0 +1,262 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { and, eq, sql } from 'drizzle-orm';
+import { callerResults } from '../storage/caller-results.js';
+import { executions } from '../storage/executions.js';
+import { epics } from '../storage/schema.js';
+import { redact } from '../logging/redact.js';
+import { git } from './epic.js';
+// The reply is bounded: with these it weighs at most about 400 KB, far under the client's 8 MiB line, and says so when it cut.
+export const MAX_FILES_PER_SECTION = 500;
+export const MAX_FILES = 2_000;
+const MAX_SLICES = 100;
+const MAX_PATH = 500;
+const MAX_UNTRACKED_BYTES = 1024 * 1024;
+// a file's diff: past these bytes it is not read, and the rows are cut at the same caps the app draws with
+const MAX_DIFF_BYTES = 4 * 1024 * 1024;
+export const MAX_DIFF_ROWS = 1_000;
+export const MAX_LINE = 2_000;
+/** `git diff --numstat --no-renames -z`: `added<TAB>removed<TAB>path` per record; a binary file counts `-`, taken as 0. */
+function parseNumstat(out) {
+    return out.split('\0').flatMap((record) => {
+        const [, added, removed, path] = /^(\d+|-)\t(\d+|-)\t(.+)$/s.exec(record) ?? [];
+        return path === undefined ? [] : [{ path, added: Number(added) || 0, removed: Number(removed) || 0 }];
+    });
+}
+// a driver or a textconv the repository configures never runs: it is the repository's code, and it would skew the numbers
+const SAFE_DIFF = ['--no-color', '--no-ext-diff', '--no-textconv', '--no-renames'];
+const numstat = (card) => {
+    const out = git(card.cwd, [...card.guard, 'diff', '--numstat', ...SAFE_DIFF, '-z', ...card.range, '--']);
+    return out === null ? null : parseNumstat(out);
+};
+/**
+ * `-c` options that keep a worktree's own code from running while it is read: diffing a worktree hashes its edited files through
+ * the clean filter (or the long-running `process`) its attributes name, and refreshes through the fsmonitor hook. Every filter the
+ * config defines is emptied and not required, so git reads the bytes as they are.
+ */
+function guardOf(cwd) {
+    const keys = (git(cwd, ['config', '--list', '--name-only']) ?? '').split('\n');
+    const filters = new Set(keys.flatMap((key) => (/^filter\.(.+)\.(?:clean|smudge|process|required)$/i.exec(key)?.[1] ?? [])));
+    return ['-c', 'core.fsmonitor=false', ...[...filters].flatMap((name) => ['clean=', 'smudge=', 'process=', 'required=false'].flatMap((set) => ['-c', `filter.${name}.${set}`]))];
+}
+/** An untracked file as `files` counts it: its text, or why it has none. A symlink is not followed: it could point anywhere. */
+function readUntracked(cwd, path) {
+    try {
+        const file = join(cwd, path);
+        const stat = lstatSync(file);
+        if (stat.isFile() === false)
+            return 'binary';
+        if (stat.size > MAX_UNTRACKED_BYTES)
+            return 'too-big';
+        const bytes = readFileSync(file);
+        return bytes.includes(0) ? 'binary' : bytes.toString('utf8');
+    }
+    catch {
+        return 'gone'; // between the listing and the read: the agent is working
+    }
+}
+const lineCount = (text) => text.split('\n').length - 1 + (text.length > 0 && text.endsWith('\n') === false ? 1 : 0);
+const untrackedPaths = (card) => (git(card.cwd, [...card.guard, 'ls-files', '--others', '--exclude-standard', '-z']) ?? '').split('\0').filter(Boolean).slice(0, MAX_FILES);
+/** New files a lane has not added yet: no diff exists for them, so lines are counted; a binary or big file counts 0. */
+function untracked(card) {
+    return untrackedPaths(card).map((path) => {
+        const text = readUntracked(card.cwd, path);
+        return { path, added: text === 'binary' || text === 'too-big' || text === 'gone' ? 0 : lineCount(text), removed: 0 };
+    });
+}
+/** The base the pull request will have: the remote's HEAD, then the usual names; null when the clone has none of them. */
+function defaultBase(cwd) {
+    const refs = new Set((git(cwd, ['for-each-ref', '--format=%(refname)', 'refs/remotes/origin', 'refs/heads/main', 'refs/heads/master']) ?? '').split('\n'));
+    return ['refs/remotes/origin/HEAD', 'refs/remotes/origin/main', 'refs/remotes/origin/master', 'refs/heads/main', 'refs/heads/master'].find((ref) => refs.has(ref)) ?? null;
+}
+/** A folder resolved through symlinks, or null when it is gone. */
+function real(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** Whether `list` (`git worktree list --porcelain` of the engine's clone) lists `workspace` (a real path), both sides compared by real path. */
+function listedByGit(list, workspace) {
+    return list.split('\n').some((line) => line.startsWith('worktree ') && real(line.slice('worktree '.length)) === workspace);
+}
+/**
+ * The lanes of an epic: `git worktree list` entries named `<epic worktree>--lane-<N>` beside it, with a slice branch checked out
+ * (a detached one is a free lane and has no work). Nothing outside the epic's own folder is inspected.
+ */
+function lanes(list, workspace) {
+    const parent = real(dirname(workspace));
+    const prefix = `${basename(workspace)}--lane-`;
+    return list.split('\n\n').flatMap((block) => {
+        const lines = block.split('\n');
+        const path = lines.find((l) => l.startsWith('worktree '))?.slice('worktree '.length);
+        const number = path === undefined ? '' : basename(path).slice(prefix.length);
+        if (path === undefined || basename(path).startsWith(prefix) === false || /^\d{1,2}$/.test(number) === false)
+            return [];
+        if (lines.some((l) => l.startsWith('branch refs/heads/')) === false || existsSync(path) === false)
+            return [];
+        return real(dirname(path)) === parent ? [{ lane: Number(number), path }] : [];
+    }).sort((a, b) => a.lane - b.lane);
+}
+/**
+ * Every card of an epic and where git is asked over which range: a lane's worktree against its fork point, the epic worktree
+ * over `<sha>^1..<sha>` of a merged slice, and over the two heads of a fix round. `filesOf` counts over it and `fileDiff` diffs over it,
+ * so the two cannot drift apart. null for an unknown epic, 'none' for one whose worktree git does not list for the engine's clone.
+ */
+function cardsOf(db, reposDir, repo, issue, executionId) {
+    const epic = db.select().from(epics).where(and(eq(epics.repo, repo), eq(epics.issue, issue))).get();
+    if (epic === undefined)
+        return null;
+    const workspace = epic.workspace === null ? null : real(epic.workspace);
+    // the folder comes from the database, but it is only read when git lists it for the engine's clone of the repo; asked once per request
+    if (workspace === null)
+        return 'none';
+    const list = git(join(reposDir, repo), ['worktree', 'list', '--porcelain']); // null: no clone yet
+    if (list === null || listedByGit(list, workspace) === false)
+        return 'none';
+    const branch = git(workspace, ['symbolic-ref', '--short', 'HEAD'])?.trim();
+    if (branch === undefined || branch === '')
+        return 'none';
+    const head = `refs/heads/${branch}`;
+    const base = defaultBase(workspace);
+    const cards = [];
+    const runs = db
+        .select({ run: executions, result: callerResults.result })
+        .from(executions)
+        .leftJoin(callerResults, eq(callerResults.executionId, executions.executionId))
+        .where(eq(executions.epicId, epic.id))
+        .orderBy(sql `executions.rowid`)
+        .all();
+    const rounds = [];
+    let reviewed = null;
+    for (const { run, result } of runs) {
+        if (result === null || run.stage === 'ship')
+            continue;
+        const parsed = JSON.parse(result);
+        if (run.stage === 'review')
+            reviewed = parsed.outcome === 'needs_human' ? null : parsed.pr.headSha;
+        else if (parsed.outcome === 'completed' && reviewed !== null && (executionId === undefined || executionId === run.executionId)) {
+            rounds.unshift({ id: run.executionId, kind: 'session', title: `Fix, round ${run.round ?? '?'}`, cwd: workspace, range: [reviewed, parsed.pr.headSha], guard: [] });
+        }
+    }
+    if (executionId === undefined) {
+        for (const { lane, path } of lanes(list, workspace)) {
+            const fork = git(path, ['merge-base', head, 'HEAD'])?.trim();
+            if (fork)
+                cards.push({ id: `lane-${lane}`, kind: 'lane', title: `Lane ${lane}`, cwd: path, range: [fork], guard: guardOf(path) });
+        }
+        if (base !== null) {
+            const merges = git(workspace, ['log', '--first-parent', '--merges', `--max-count=${MAX_SLICES}`, '--format=%H%x00%s', `${base}..${head}`]) ?? '';
+            for (const line of merges.split('\n')) {
+                const [sha = '', subject = ''] = line.split('\0');
+                // GitHub's own merge subject: `Merge pull request #<pr> from <owner>/<namespace>/<slice number>-<slug>`
+                const [, pr, slice] = /^Merge pull request #(\d+) from [^/]+\/.+\/(\d+)-[^/]+$/.exec(subject) ?? [];
+                if (slice !== undefined)
+                    cards.push({ id: `slice-${slice}`, kind: 'merged', title: `Slice #${slice} (PR #${pr})`, cwd: workspace, range: [`${sha}^1`, sha], guard: [] });
+            }
+        }
+    }
+    cards.push(...rounds);
+    return { workspace, head, base, cards };
+}
+/**
+ * The files an epic changed, from git and never from GitHub: the lanes' work so far (against the fork point, uncommitted work included),
+ * each merged slice (the first-parent merge commits on the epic branch), each fix round (between the heads of its review and its fix),
+ * and the epic branch against the default branch as `total`. An epic without a worktree git lists has nothing to show: empty, not an error.
+ * With `executionId`, only that fix round.
+ * ponytail: nothing is cached, git is asked on every request (tens of ms); cache a few seconds if the app ever polls faster.
+ */
+export function filesOf(db, reposDir, repo, issue, executionId) {
+    const found = cardsOf(db, reposDir, repo, issue, executionId);
+    if (found === null)
+        return null;
+    if (found === 'none')
+        return { sections: [], total: null, truncated: false };
+    const { workspace, head, base } = found;
+    const drafts = found.cards.flatMap((card) => {
+        const rows = numstat(card);
+        return rows === null ? [] : [{ ...card, rows: card.kind === 'lane' ? [...rows, ...untracked(card)] : rows }];
+    });
+    // a file two lanes touch says so in both
+    const laneFiles = new Map(drafts.filter((d) => d.kind === 'lane').map((d) => [d.id, new Set(d.rows.map((r) => r.path))]));
+    let left = MAX_FILES;
+    let truncated = false;
+    const sections = drafts.map(({ id, kind, title, rows }) => {
+        const kept = rows.filter((r) => r.path.length <= MAX_PATH).slice(0, Math.min(MAX_FILES_PER_SECTION, left));
+        left -= kept.length;
+        truncated ||= kept.length < rows.length;
+        return {
+            id, kind, title,
+            added: rows.reduce((sum, r) => sum + r.added, 0),
+            removed: rows.reduce((sum, r) => sum + r.removed, 0),
+            files: kept.map(({ path, added, removed }) => ({ path, added, removed, alsoIn: kind === 'lane' ? [...laneFiles].filter(([other, set]) => other !== id && set.has(path)).map(([other]) => other) : [] })),
+        };
+    });
+    const all = base === null ? null : numstat({ cwd: workspace, range: [`${base}...${head}`], guard: [] });
+    const total = all === null ? null : { files: all.length, added: all.reduce((sum, r) => sum + r.added, 0), removed: all.reduce((sum, r) => sum + r.removed, 0) };
+    return { sections, total, truncated };
+}
+/** The diff text of one file over a range; past the byte cap, the whole lines read so far and `cut`. Nothing the repository configures runs: no driver, no textconv. */
+function diffText({ cwd, range, guard }, path) {
+    try {
+        const text = execFileSync('git', [...guard, 'diff', ...SAFE_DIFF, '-U3', ...range, '--', `:(literal)${path}`], { cwd, encoding: 'utf8', timeout: 5_000, maxBuffer: MAX_DIFF_BYTES, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' }, stdio: ['ignore', 'pipe', 'pipe'] });
+        return { text, cut: false };
+    }
+    catch (error) {
+        if (error.code === 'ENOBUFS') {
+            const partial = String(error.stdout ?? '');
+            return { text: partial.slice(0, partial.lastIndexOf('\n') + 1), cut: true }; // the last line may be half read
+        }
+        throw new Error('git diff failed in an epic worktree', { cause: error }); // the server logs it and answers `internal error`
+    }
+}
+/**
+ * The edited fragments of one file of a card: the hunks with three lines of context, an '@' row with git's header before each.
+ * null for an unknown epic or card, or a path that is not in the card's own file list: that list is the allowlist, so a pathspec,
+ * a `..` or a NUL byte never reaches git. A lane's untracked file is read as `files` counts it, every line a '+'.
+ * Redacted as a whole, then cut at MAX_DIFF_ROWS and MAX_LINE.
+ */
+export function fileDiff(db, reposDir, repo, issue, section, path) {
+    const found = cardsOf(db, reposDir, repo, issue);
+    const card = found === null || found === 'none' ? undefined : found.cards.find((c) => c.id === section);
+    if (card === undefined || path.length > MAX_PATH)
+        return null;
+    let out;
+    let cut = false;
+    if (numstat(card)?.some((r) => r.path === path) === true) {
+        ({ text: out, cut } = diffText(card, path));
+    }
+    else if (card.kind === 'lane' && untrackedPaths(card).includes(path)) {
+        const text = readUntracked(card.cwd, path);
+        if (text === 'binary' || text === 'too-big')
+            return { rows: [], truncated: false, note: text };
+        const count = text === 'gone' ? 0 : lineCount(text);
+        if (text === 'gone' || count === 0)
+            return { rows: [], truncated: false, note: 'no-changes' };
+        // the diff git would show once the file is added
+        out = `@@ -0,0 +1${count === 1 ? '' : `,${count}`} @@\n` + text.split('\n').slice(0, count).map((line) => `+${line}`).join('\n') + '\n';
+    }
+    else {
+        return null;
+    }
+    const all = redact(out).split('\n');
+    const first = all.findIndex((line) => line.startsWith('@@'));
+    if (first < 0)
+        return { rows: [], truncated: false, note: /^Binary files /m.test(out) ? 'binary' : 'no-changes' };
+    let truncated = cut;
+    const rows = all.slice(first).flatMap((line) => {
+        const hunk = /^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@/.exec(line);
+        if (hunk !== null)
+            return [{ sign: '@', text: hunk[0] }];
+        const sign = line[0];
+        if (sign !== '+' && sign !== '-' && sign !== ' ')
+            return []; // ``, and the last empty line
+        truncated ||= line.length - 1 > MAX_LINE;
+        return [{ sign, text: line.slice(1, MAX_LINE + 1) }];
+    });
+    truncated ||= rows.length > MAX_DIFF_ROWS;
+    return { rows: rows.slice(0, MAX_DIFF_ROWS), truncated, note: null };
+}

package/dist/control/replies.js

@@ -0,0 +1 @@
+export {};

package/dist/control/server.js

@@ -0,0 +1,237 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { createScopedLogger } from '@ashulab/universal-logger';
+import { z } from 'zod';
+import { controlSocketIn } from '../config/engine-places.js';
+import { optionNamePattern } from '../config/schema.js';
+import { ResumeRefused } from '../orchestration/resume-refused.js';
+const log = createScopedLogger('control');
+const MAX_LINE_BYTES = 16 * 1024;
+const MAX_SOCKET_PATH_BYTES = 103; // macOS: sun_path holds 104 with its terminator
+/** Measured in bytes, never left to Node: 22.22.0 truncates a longer path and binds a mangled name, 24 to 26 throw EINVAL. */
+export function socketPathFits(path) {
+    const bytes = Buffer.byteLength(path);
+    return { fits: bytes <= MAX_SOCKET_PATH_BYTES, bytes };
+}
+const id = z.number().int().positive();
+const repo = z
+    .string()
+    .max(200)
+    .regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/)
+    .refine((value) => value.split('/').every((part) => part !== '.' && part !== '..'));
+const issue = z.number().int().positive();
+const optionName = z.string().regex(optionNamePattern);
+// An allowlist: any other command, field or type is rejected before anything acts on it.
+export const request = z.union([
+    z.strictObject({ id, cmd: z.enum(['snapshot', 'pause', 'resume', 'checkNow', 'stop']) }),
+    z.strictObject({ id, cmd: z.literal('tail'), executionId: z.uuid(), lines: z.number().int().min(1).max(500) }),
+    z.strictObject({ id, cmd: z.literal('sessions'), repo, issue }),
+    z.strictObject({ id, cmd: z.literal('events'), executionId: z.uuid(), after: z.number().int().min(0).optional(), limit: z.number().int().min(1).max(200) }),
+    z.strictObject({ id, cmd: z.literal('epic'), repo, issue }),
+    z.strictObject({ id, cmd: z.literal('files'), repo, issue, executionId: z.uuid().optional() }),
+    z.strictObject({ id, cmd: z.literal('fileDiff'), repo, issue, section: z.string().min(1).max(100), path: z.string().min(1).max(500) }),
+    z.strictObject({ id, cmd: z.literal('availableRepos'), page: z.int().min(1).max(100).optional() }),
+    z.strictObject({ id, cmd: z.literal('resumeEpic'), repo, issue, author: optionName.optional(), reviewer: optionName.optional() }),
+    z.strictObject({ id, cmd: z.literal('chooseOptions'), repo, issue, author: optionName.optional(), reviewer: optionName.optional() }),
+]);
+// src/control and dist/control both sit two folders under the package root.
+export const version = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
+/** pause, resume, checkNow and tail. Like the panel's keys, a check is started and not waited for: its failure is the engine's to report. */
+function control(command, controls) {
+    try {
+        if (command.cmd === 'tail')
+            return { id: command.id, ok: true, data: controls.logs(command.executionId, command.lines) };
+        if (command.cmd === 'checkNow')
+            void Promise.resolve(controls.poll()).catch((error) => log.error('check now failed', error));
+        else
+            void Promise.resolve(controls.setPaused(command.cmd === 'pause')).catch((error) => log.error(`${command.cmd} failed`, error));
+        return { id: command.id, ok: true };
+    }
+    catch (error) {
+        log.error(`${command.cmd} failed`, error);
+        return { id: command.id, ok: false, error: 'internal error' };
+    }
+}
+/** The reply to one line; a promise for the requests that wait on GitHub. */
+function answer(line, snapshot, controls, stopAfterReply) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return { id: null, ok: false, error: 'invalid JSON' };
+    }
+    const parsed = request.safeParse(value);
+    if (parsed.success === false) {
+        // the id is echoed only when it is a valid one, so the client can match the error
+        const given = typeof value === 'object' && value !== null ? id.safeParse(value.id) : null;
+        return { id: given?.success ? given.data : null, ok: false, error: 'invalid request' };
+    }
+    if (parsed.data.cmd === 'snapshot') {
+        try {
+            return { id: parsed.data.id, ok: true, data: snapshot() };
+        }
+        catch (error) {
+            log.error('snapshot failed', error);
+            return { id: parsed.data.id, ok: false, error: 'internal error' };
+        }
+    }
+    if (parsed.data.cmd === 'sessions' || parsed.data.cmd === 'epic') {
+        const { id: replyId, cmd, repo, issue } = parsed.data;
+        try {
+            const reply = controls[cmd](repo, issue);
+            return reply === null ? { id: replyId, ok: false, error: 'unknown epic' } : { id: replyId, ok: true, data: reply };
+        }
+        catch (error) {
+            log.error(`${cmd} failed`, error);
+            return { id: replyId, ok: false, error: 'internal error' };
+        }
+    }
+    if (parsed.data.cmd === 'files') {
+        const { id: replyId, repo, issue, executionId } = parsed.data;
+        try {
+            const reply = controls.files(repo, issue, executionId);
+            return reply === null ? { id: replyId, ok: false, error: 'unknown epic' } : { id: replyId, ok: true, data: reply };
+        }
+        catch (error) {
+            log.error('files failed', error);
+            return { id: replyId, ok: false, error: 'internal error' };
+        }
+    }
+    if (parsed.data.cmd === 'fileDiff') {
+        const { id: replyId, repo, issue, section, path } = parsed.data;
+        try {
+            const reply = controls.fileDiff(repo, issue, section, path);
+            // never git's own message: it can name more of the machine than the client should see
+            return reply === null ? { id: replyId, ok: false, error: 'unknown file' } : { id: replyId, ok: true, data: reply };
+        }
+        catch (error) {
+            log.error('fileDiff failed', error);
+            return { id: replyId, ok: false, error: 'internal error' };
+        }
+    }
+    if (parsed.data.cmd === 'availableRepos') {
+        const { id: replyId, page } = parsed.data;
+        // never the reason in the reply: gh's own message can carry more than the client should see
+        return Promise.resolve()
+            .then(() => controls.availableRepos(page ?? 1))
+            .then((data) => ({ id: replyId, ok: true, data }), (error) => {
+            log.error('availableRepos failed', error);
+            return { id: replyId, ok: false, error: 'github unavailable' };
+        });
+    }
+    if (parsed.data.cmd === 'resumeEpic') {
+        const { id: replyId, repo, issue, author, reviewer } = parsed.data;
+        return Promise.resolve()
+            .then(() => controls.resumeEpic(repo, issue, { author, reviewer }))
+            .then(() => ({ id: replyId, ok: true }), (error) => {
+            if (error instanceof ResumeRefused)
+                return { id: replyId, ok: false, error: error.reason };
+            log.error('resumeEpic failed', error);
+            return { id: replyId, ok: false, error: 'internal error' };
+        });
+    }
+    if (parsed.data.cmd === 'chooseOptions') {
+        const { id: replyId, repo, issue, author, reviewer } = parsed.data;
+        return Promise.resolve()
+            .then(() => controls.chooseOptions(repo, issue, { author, reviewer }))
+            .then(() => ({ id: replyId, ok: true }), (error) => {
+            if (error instanceof ResumeRefused)
+                return { id: replyId, ok: false, error: error.reason };
+            log.error('chooseOptions failed', error);
+            return { id: replyId, ok: false, error: 'internal error' };
+        });
+    }
+    if (parsed.data.cmd === 'events') {
+        const { id: replyId, executionId, after, limit } = parsed.data;
+        try {
+            const reply = controls.events(executionId, after ?? 0, limit);
+            return reply === null ? { id: replyId, ok: false, error: 'unknown execution' } : { id: replyId, ok: true, data: reply };
+        }
+        catch (error) {
+            log.error('events failed', error);
+            return { id: replyId, ok: false, error: 'internal error' };
+        }
+    }
+    if (parsed.data.cmd !== 'stop')
+        return control(parsed.data, controls);
+    stopAfterReply();
+    return { id: parsed.data.id, ok: true };
+}
+/**
+ * Opens `control.sock` in the engine's state folder: newline-delimited JSON, a hello on connect and one reply per request. The caller
+ * must hold the instance lock: that is what makes any socket file already there a leftover of a crash, safe to replace.
+ * A path that does not fit, or a socket that cannot open, is logged and Carrier goes on without it. `close()` is synchronous and removes the file.
+ */
+export async function startControlServer({ stateDir, snapshot, startedAt, controls, stop }) {
+    const path = controlSocketIn(stateDir);
+    const { fits, bytes } = socketPathFits(path);
+    if (fits === false) {
+        log.warn(`control socket not opened: ${path} is ${bytes} bytes, the limit is ${MAX_SOCKET_PATH_BYTES}; use a shorter Carrier folder`);
+        return { close: () => { } };
+    }
+    const sockets = new Set();
+    const hello = { event: 'hello', protocol: 1, pid: process.pid, startedAt, version, capabilities: ['sessions', 'events', 'epic', 'files', 'fileDiff', 'availableRepos', 'availableReposPaged', 'resumeEpic', 'agentOptions'] };
+    const send = (socket, message, written) => void socket.write(`${JSON.stringify(message)}\n`, written);
+    const server = createServer((socket) => {
+        sockets.add(socket);
+        socket.setEncoding('utf8');
+        // a client that goes away mid-write is routine, not a failure
+        socket.on('error', (error) => log.debug('control connection error', error));
+        socket.on('close', () => sockets.delete(socket));
+        send(socket, hello);
+        let pending = '';
+        // replies leave in the order the requests came, also when one of them waits on GitHub
+        let replies = Promise.resolve();
+        socket.on('data', (chunk) => {
+            pending += chunk;
+            for (let end = pending.indexOf('\n'); end >= 0; end = pending.indexOf('\n')) {
+                const line = pending.slice(0, end);
+                pending = pending.slice(end + 1);
+                if (Buffer.byteLength(line) > MAX_LINE_BYTES)
+                    return tooLong(socket);
+                // `stop`: the reply is flushed first, then the shared shutdown runs and ends with the connection closing
+                let afterReply;
+                const stopAfterReply = () => void (afterReply = () => void stop().catch((error) => log.error('stop failed', error)));
+                const reply = answer(line, snapshot, controls, stopAfterReply);
+                replies = replies.then(async () => {
+                    const message = await reply;
+                    if (socket.destroyed === false)
+                        send(socket, message, afterReply);
+                });
+            }
+            if (Buffer.byteLength(pending) > MAX_LINE_BYTES)
+                tooLong(socket);
+        });
+    });
+    const tooLong = (socket) => {
+        socket.removeAllListeners('data'); // nothing more is read from this client
+        socket.end(`${JSON.stringify({ id: null, ok: false, error: 'line too long' })}\n`);
+    };
+    server.on('error', (error) => log.error('control socket error', error));
+    const close = () => {
+        server.close();
+        for (const socket of sockets)
+            socket.destroy();
+        rmSync(path, { force: true });
+    };
+    try {
+        rmSync(path, { force: true });
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            // bind is synchronous: with this umask the file is born 0600, and the umask is back before anything else runs
+            const umask = process.umask(0o177);
+            try {
+                server.listen(path, resolve);
+            }
+            finally {
+                process.umask(umask);
+            }
+        });
+    }
+    catch (error) {
+        log.error('control socket not opened', error);
+        return { close: () => { } };
+    }
+    return { close };
+}

package/dist/control/sessions.js

@@ -0,0 +1,68 @@
+import { and, desc, eq, sql } from 'drizzle-orm';
+import { executions } from '../storage/executions.js';
+import { epics } from '../storage/schema.js';
+import { configDirVariable } from '../harnesses/names.js';
+import { redact } from '../logging/redact.js';
+import { callerResults } from '../storage/caller-results.js';
+const MAX_SUMMARY = 1500;
+const MAX_EVIDENCE = 600;
+const MAX_REASON = 600;
+const MAX_FAILURE_DETAIL = 300;
+/** Text an agent wrote: redacted first, so a token is never cut into something the patterns no longer match, then cut. */
+const safe = (text, max) => redact(text).slice(0, max);
+function resultOf(raw) {
+    if (raw === null)
+        return null;
+    const parsed = JSON.parse(raw);
+    return {
+        outcome: parsed.outcome,
+        summary: safe(parsed.summary, MAX_SUMMARY),
+        verification: parsed.outcome === 'completed' ? { ci: parsed.verification.ci, evidence: safe(parsed.verification.evidence, MAX_EVIDENCE) } : null,
+        reason: parsed.outcome === 'needs_human' ? safe(parsed.reason, MAX_REASON) : null,
+    };
+}
+function failureOf(row) {
+    if (row.failureKind === null)
+        return null;
+    const { failureKind: kind, failureDetail, exitCode, signal, hostFreeMemMb, hostLoad } = row;
+    return { kind, detail: safe(failureDetail ?? '', MAX_FAILURE_DETAIL), exitCode, signal, hostFreeMemMb, hostLoad };
+}
+/** The folders the environment really sets, as the agents inherit them: a harness whose variable is unset has no entry, not its default folder. */
+export const inheritedConfigDirs = (env = process.env) => Object.fromEntries(Object.entries(configDirVariable).flatMap(([harness, variable]) => (env[variable] ? [[harness, env[variable]]] : [])));
+/** The agent an execution ran with: its own row, or the epic's frozen configuration for a row written before it was recorded. */
+export function agentOf(row, config) {
+    const frozen = config?.agents[row.stage === 'review' ? 'reviewer' : 'author'];
+    return {
+        harness: (row.harness ?? frozen?.harness ?? 'claude'),
+        model: row.model ?? frozen?.model ?? '',
+        provider: row.harness === null ? (frozen?.provider ?? null) : row.provider,
+    };
+}
+/**
+ * Every execution of an epic, newest first; null for an epic the engine does not know.
+ * A session has a descriptor only once it is not running and its id and folder are known (ADR 0007); `configDir` is the folder the execution that wrote it ran with: its option's, else the engine environment's (`inherited`).
+ */
+export function sessionsOf(db, repo, issue, inherited = {}) {
+    const epic = db.select({ id: epics.id, config: epics.config }).from(epics).where(and(eq(epics.repo, repo), eq(epics.issue, issue))).get();
+    if (epic === undefined)
+        return null;
+    const rows = db
+        .select({ row: executions, result: callerResults.result })
+        .from(executions)
+        .leftJoin(callerResults, eq(callerResults.executionId, executions.executionId))
+        .where(eq(executions.epicId, epic.id))
+        .orderBy(desc(executions.startedAt), sql `executions.rowid desc`)
+        .all();
+    return {
+        sessions: rows.map(({ row, result }) => {
+            const role = row.stage === 'review' ? 'reviewer' : 'author';
+            const agent = agentOf(row, epic.config);
+            const harness = agent.harness;
+            const configDir = row.configDir ?? inherited[harness];
+            const resume = row.status === 'running' || row.sessionId === null || row.workspace === null
+                ? null
+                : { harness, sessionId: row.sessionId, cwd: row.workspace, ...(configDir !== undefined && { configDir }) };
+            return { executionId: row.executionId, stage: row.stage, role, round: row.round, agent, status: row.status, startedAt: row.startedAt, finishedAt: row.finishedAt, resume, result: resultOf(result), failure: failureOf(row) };
+        }),
+    };
+}