@kylecheng3146/agent-ops 0.6.0 → 0.7.0

package/dist/runtime/src/office/scene.js

@@ -0,0 +1,168 @@
+/**
+ * Pure snapshot -> scene mapping in tile units. Self-contained on purpose: the
+ * page embeds this exact function with Function.prototype.toString, so it may
+ * not reference imports or module-level values.
+ */
+export function sceneModel(snapshot) {
+    const ROOM_COLS = 72, ROOM_ROWS = 40, OVERVIEW_COLS = 80, OVERVIEW_ROWS = 38;
+    const PHASES = ["planning", "implementing", "verifying", "reviewing", "integrating"];
+    const labels = {
+        planning: "Planning", implementing: "Implementing", verifying: "Verifying", reviewing: "Reviewing", integrating: "Integrating", unknown: "Unassigned"
+    };
+    const areas = {
+        planning: { x: 3, y: 8, width: 17, height: 12, prop: "whiteboard" },
+        implementing: { x: 3, y: 23, width: 29, height: 11, prop: "desk" },
+        verifying: { x: 49, y: 8, width: 20, height: 12, prop: "bench" },
+        reviewing: { x: 38, y: 23, width: 30, height: 11, prop: "table" },
+        integrating: { x: 22, y: 34, width: 25, height: 5, prop: "door" }
+    };
+    const position = (phase, index, count = 1) => {
+        const area = areas[phase] ?? areas.implementing;
+        // Keep every actor inside the phase area, even when a run has many
+        // workers in one phase. Fractional spacing compresses a crowd without
+        // dropping actors or sending them through the room walls.
+        const inset = 2, columns = Math.max(1, Math.min(count, Math.floor((area.width - inset * 2) / 3)));
+        const rows = Math.max(1, Math.ceil(count / columns));
+        const xSpan = Math.max(0, area.width - inset * 2), ySpan = Math.max(0, area.height - inset * 2);
+        const column = index % columns, row = Math.floor(index / columns);
+        return { x: area.x + inset + (columns === 1 ? xSpan * .35 : column * xSpan / (columns - 1)),
+            y: area.y + inset + (rows === 1 ? ySpan * .55 : row * ySpan / (rows - 1)) };
+    };
+    const progressOf = (value) => {
+        if (value === null || typeof value !== "object")
+            return null;
+        const p = value;
+        return { passed: typeof p.passed === "number" ? p.passed : 0, total: typeof p.total === "number" ? p.total : 0,
+            verify: p.verify === "PASS" || p.verify === "FAIL" ? p.verify : null, review: p.review === "PASS" || p.review === "FAIL" ? p.review : null };
+    };
+    const short = (value, limit = 18) => value.length > limit ? value.slice(0, limit - 1) + "…" : value;
+    const optional = (value) => value !== null && typeof value === "object" ? value : {};
+    const boardFor = (progress, status, taskId, pending) => ({
+        passed: progress?.passed ?? 0, total: progress?.total ?? 0,
+        verify: progress?.verify ?? "pending", review: progress?.review ?? "pending", pending, status, taskId
+    });
+    const floors = [];
+    const dialogue = [];
+    const makeAreas = () => PHASES.map(phase => {
+        const area = areas[phase];
+        return { phase, x: area.x, y: area.y, width: area.width, height: area.height, prop: area.prop, label: labels[phase] };
+    });
+    const makeProps = (key) => [
+        { kind: "window", x: 56, y: 1, key: key + ":window" },
+        { kind: "whiteboard", x: 3, y: 10, key: key + ":planning", phase: "planning" },
+        { kind: "desk", x: 5, y: 25, key: key + ":implementing", phase: "implementing" },
+        { kind: "bench", x: 49, y: 10, key: key + ":verifying", phase: "verifying" },
+        { kind: "table", x: 40, y: 25, key: key + ":reviewing", phase: "reviewing" },
+        { kind: "desk", x: 24, y: 35, key: key + ":integrating", phase: "integrating" },
+        { kind: "chair", x: 13, y: 30, key: key + ":chair" },
+        { kind: "shelf", x: 2, y: 29, key: key + ":shelf" },
+        { kind: "shelf", x: 34, y: 20, key: key + ":shelf-middle" },
+        { kind: "plant", x: 2, y: 6, key: key + ":plant-left" },
+        { kind: "plant", x: 22, y: 16, key: key + ":plant-middle" },
+        { kind: "plant", x: 65, y: 6, key: key + ":plant-right" },
+        { kind: "plant", x: 57, y: 34, key: key + ":plant-bottom" },
+        { kind: "door", x: 65, y: 33, key: key + ":door" }
+    ];
+    const makeRun = (run) => {
+        const extra = optional(run);
+        const completedAt = typeof extra.completedAt === "string" ? extra.completedAt : null;
+        const questions = run.questions;
+        const props = makeProps(run.runId);
+        const actors = [];
+        const papers = { [run.runId + ":implementing"]: Math.min(8, run.agents.reduce((sum, agent) => sum + (agent.diff?.files ?? 0), 0)) };
+        let passed = 0, total = 0, verify = null, review = null;
+        run.agents.forEach((agent, index) => {
+            const phase = agent.phase;
+            const p = progressOf(agent.progress);
+            const phaseIndex = actors.filter(actor => actor.phase === phase).length;
+            const phaseCount = run.agents.filter(candidate => candidate.phase === phase).length;
+            const point = position(phase, phaseIndex, phaseCount);
+            if ((phase === "implementing" || phase === "unknown") && phaseIndex > 0) {
+                const deskKey = run.runId + ":desk:" + agent.id;
+                props.push({ kind: "desk", x: point.x - 2, y: point.y - 5, key: deskKey, phase: "implementing", label: short(agent.id) });
+                papers[deskKey] = Math.min(8, agent.diff?.files ?? 0);
+            }
+            passed += p?.passed ?? 0;
+            total += p?.total ?? 0;
+            if (p?.verify === "FAIL")
+                verify = "FAIL";
+            else if (p?.verify === "PASS" && verify === null)
+                verify = "PASS";
+            if (p?.review === "FAIL")
+                review = "FAIL";
+            else if (p?.review === "PASS" && review === null)
+                review = "PASS";
+            actors.push({ key: run.runId + ":" + agent.id, id: agent.id, kind: agent.role, x: point.x, y: point.y, alert: agent.role === "coordinator" && questions.length > 0,
+                label: short(agent.id), status: agent.status, phase, taskId: agent.taskId || "unassigned", progress: p,
+                narration: agent.narration, questionCount: agent.role === "coordinator" ? questions.length : 0, host: "unknown" });
+            dialogue.push(`${run.title}: ${agent.id} ${agent.narration}.`);
+        });
+        run.reviewers.forEach((reviewer, index) => {
+            const reviewerIndex = actors.filter(actor => actor.phase === "reviewing").length;
+            const reviewerCount = run.agents.filter(agent => agent.phase === "reviewing").length + run.reviewers.length;
+            const point = position("reviewing", reviewerIndex, reviewerCount);
+            actors.push({ key: run.runId + ":review:" + reviewer.slot, id: "reviewer " + reviewer.slot, kind: "reviewer", x: point.x, y: point.y, alert: false,
+                label: "reviewer " + reviewer.slot, status: "reviewing", phase: "reviewing", taskId: reviewer.taskId ?? "unassigned",
+                progress: null, narration: "reviewing", questionCount: 0, host: "unknown" });
+        });
+        const rootProgress = { passed, total, verify, review };
+        const taskId = run.agents.find(agent => agent.role === "coordinator")?.taskId ?? "unassigned";
+        if (questions.length > 0)
+            dialogue.push(`${run.title}: waiting for your answer — ${questions[0].prompt}`);
+        return { key: run.runId, sourceIndex: null, kind: "run", title: short(run.title, 34), top: 0, props, actors, phaseAreas: makeAreas(), questions,
+            board: boardFor(rootProgress, run.status, taskId, questions.length), papers, books: { lit: passed, total },
+            clock: run.budget.limitMs > 0 ? run.budget.remainingMs / run.budget.limitMs : 0, phase: run.phase, status: run.status,
+            completedAt, overview: { x: 0, y: 0, width: 0, height: 0 } };
+    };
+    const makeDesk = (desk, index) => {
+        const extra = optional(desk);
+        const phase = extra.phase === "planning" || extra.phase === "implementing" || extra.phase === "verifying" || extra.phase === "reviewing" || extra.phase === "integrating" ? extra.phase : "unknown";
+        const status = typeof extra.status === "string" ? extra.status : desk.narration;
+        const taskId = typeof extra.taskId === "string" && extra.taskId.length > 0 ? extra.taskId : "unassigned";
+        const p = progressOf(extra.progress);
+        const questionsValue = Array.isArray(extra.questions) ? extra.questions : [];
+        const questions = questionsValue.map(value => {
+            const item = optional(value);
+            return { questionId: typeof item.questionId === "string" ? item.questionId : "unknown", prompt: typeof item.prompt === "string" ? item.prompt : "" };
+        });
+        const completedAt = typeof extra.completedAt === "string" ? extra.completedAt : null;
+        const key = "session:" + [desk.sessionId || "unknown", desk.branch || "unknown", desk.name || "session"].join(":");
+        const props = makeProps(key);
+        const point = position(phase, 0, 1);
+        const host = typeof extra.host === "string" ? extra.host : "unknown";
+        const actor = { key: key + ":actor", id: desk.name, kind: "worker", x: point.x, y: point.y, alert: questions.length > 0, label: short(desk.name), status,
+            phase, taskId, progress: p, narration: desk.narration, questionCount: questions.length, host };
+        if (questions.length > 0)
+            dialogue.push(`${desk.name}: waiting for your answer.`);
+        dialogue.push(`${desk.name}: ${desk.narration}.`);
+        return { key, sourceIndex: index, kind: "desk", title: short(desk.name, 34), top: 0, props, actors: [actor], phaseAreas: makeAreas(),
+            board: boardFor(p, status, taskId, questions.length), questions, papers: { [key + ":implementing"]: Math.min(8, desk.diff.files) }, books: { lit: p?.passed ?? 0, total: p?.total ?? 0 },
+            clock: 1, phase, status, completedAt, overview: { x: 0, y: 0, width: 0, height: 0 } };
+    };
+    snapshot.runs.forEach(run => floors.push(makeRun(run)));
+    snapshot.lobby.forEach((desk, index) => floors.push(makeDesk(desk, index)));
+    snapshot.reviews.forEach((review, index) => {
+        const key = "review:" + review.slot + ":" + index;
+        const props = makeProps(key);
+        const point = position("reviewing", 0);
+        const actor = { key: key + ":actor", id: "reviewer " + review.slot, kind: "reviewer", x: point.x, y: point.y, alert: false, label: "reviewer " + review.slot,
+            status: "reviewing", phase: "reviewing", taskId: review.taskId ?? "unassigned", progress: null,
+            narration: "reviewing", questionCount: 0, host: "unknown" };
+        dialogue.push(`Review slot ${review.slot}: ${review.taskId ?? "unassigned"}.`);
+        floors.push({ key, sourceIndex: index, kind: "review", title: "Review slot " + review.slot, top: 0, props, actors: [actor], phaseAreas: makeAreas(), questions: [],
+            board: boardFor(null, "reviewing", review.taskId ?? "unassigned", 0), papers: {}, books: { lit: 0, total: 0 }, clock: 1,
+            phase: "reviewing", status: "reviewing", completedAt: null, overview: { x: 0, y: 0, width: 0, height: 0 } });
+    });
+    if (dialogue.length === 0)
+        dialogue.push("The office is quiet. No agent is at work.");
+    const columns = floors.length === 0 ? 1 : Math.min(floors.length, Math.max(1, Math.ceil(Math.sqrt(floors.length * OVERVIEW_COLS / OVERVIEW_ROWS))));
+    const rows = Math.max(1, Math.ceil(floors.length / columns));
+    const gap = Math.max(0, Math.min(1, (OVERVIEW_COLS - columns) / (columns + 1), (OVERVIEW_ROWS - rows) / (rows + 1)));
+    const cardWidth = Math.max(0.25, (OVERVIEW_COLS - gap * (columns + 1)) / columns);
+    const cardHeight = Math.max(0.25, (OVERVIEW_ROWS - gap * (rows + 1)) / rows);
+    floors.forEach((floor, index) => {
+        const x = gap + (index % columns) * (cardWidth + gap), y = gap + Math.floor(index / columns) * (cardHeight + gap);
+        floor.overview = { x, y, width: cardWidth, height: cardHeight };
+    });
+    return { cols: OVERVIEW_COLS, rows: OVERVIEW_ROWS, roomCols: ROOM_COLS, roomRows: ROOM_ROWS, floors, dialogue };
+}

package/dist/runtime/src/office/server.js

@@ -0,0 +1,139 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { AgentOpsError } from "../fs/paths.js";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+import { officePage } from "./page.js";
+export const OFFICE_IDLE_MS = 10 * 60 * 1000;
+const ACTIVE = new Set(["active", "awaiting-input", "stopping"]);
+export const officeRecordPath = (commonDir) => join(commonDir, "agent-ops", "office.json");
+const officeStartLockPath = (commonDir) => join(commonDir, "agent-ops", "office-start.lock");
+export const officeUrl = (record) => `http://127.0.0.1:${record.port}/?token=${record.token}`;
+function same(a, b) {
+    const left = Buffer.from(a), right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+function send(res, status, type, body, headers = {}) {
+    res.writeHead(status, { "Content-Type": type, "Cache-Control": "no-store", "Referrer-Policy": "no-referrer",
+        "X-Content-Type-Options": "nosniff", "X-Frame-Options": "DENY", ...headers });
+    res.end(body);
+}
+/** Loopback-only, token-gated, GET-only view of the building. */
+export function createOfficeServer(options) {
+    const token = options.token ?? randomBytes(24).toString("base64url");
+    const now = options.now ?? Date.now;
+    const idleMs = options.idleMs ?? OFFICE_IDLE_MS;
+    let lastActive = now();
+    let port = 0;
+    let idle = false;
+    const handle = async (req, res) => {
+        // DNS-rebinding guard: a foreign name resolving to loopback still carries its own Host.
+        if (req.headers.host !== `127.0.0.1:${port}`)
+            return send(res, 421, "text/plain", "Misdirected request\n");
+        if (req.method !== "GET")
+            return send(res, 405, "text/plain", "Method not allowed\n", { Allow: "GET" });
+        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+        if (!same(url.searchParams.get("token") ?? "", token))
+            return send(res, 403, "text/plain", "Forbidden\n");
+        if (url.pathname === "/") {
+            const nonce = randomBytes(16).toString("base64");
+            return send(res, 200, "text/html; charset=utf-8", officePage(nonce), { "Content-Security-Policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; base-uri 'none'; form-action 'none'` });
+        }
+        if (url.pathname === "/snapshot.json")
+            return send(res, 200, "application/json", JSON.stringify(await options.snapshot()));
+        return send(res, 404, "text/plain", "Not found\n");
+    };
+    const server = createServer((req, res) => {
+        handle(req, res).catch(() => { if (!res.headersSent)
+            send(res, 500, "text/plain", "Snapshot unavailable\n");
+        else
+            res.end(); });
+    });
+    return {
+        server, token,
+        listen: async () => await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(0, "127.0.0.1", () => {
+                const address = server.address();
+                port = typeof address === "object" && address !== null ? address.port : 0;
+                resolve(port);
+            });
+        }),
+        tick: async () => {
+            const snapshot = await options.snapshot().catch(() => null);
+            const sessionIsPresent = snapshot?.lobby.some(desk => (desk.sessionActive ?? desk.status === "active") && (desk.completedAt === undefined || desk.completedAt === null)) ?? false;
+            if (snapshot === null || snapshot.runs.some(run => ACTIVE.has(run.status)) || sessionIsPresent)
+                lastActive = now();
+            if (!idle && now() - lastActive >= idleMs) {
+                idle = true;
+                options.onIdle();
+            }
+        },
+        close: async () => await new Promise(resolve => { server.closeAllConnections(); server.close(() => resolve()); })
+    };
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** A recorded server counts only if its process lives and it answers with its own token. */
+export async function readLiveOffice(commonDir) {
+    const source = await readPrivateFile(officeRecordPath(commonDir), commonDir).catch(() => null);
+    if (source === null)
+        return null;
+    try {
+        const record = JSON.parse(source);
+        if (!Number.isSafeInteger(record.pid) || !Number.isSafeInteger(record.port) || typeof record.token !== "string" || !alive(record.pid))
+            return null;
+        const response = await fetch(`http://127.0.0.1:${record.port}/snapshot.json?token=${encodeURIComponent(record.token)}`, { signal: AbortSignal.timeout(2000) });
+        await response.body?.cancel();
+        return response.status === 200 ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Starts serving unless another live server already owns the repository.
+ * Returns null when this process should exit because one is already running.
+ */
+export async function claimOffice(commonDir, office, pid = process.pid) {
+    return await withPrivateFileLock(officeRecordPath(commonDir), commonDir, async () => {
+        if (await readLiveOffice(commonDir) !== null)
+            return null;
+        const record = { pid, port: await office.listen(), token: office.token, startedAt: new Date().toISOString() };
+        await writePrivateFile(officeRecordPath(commonDir), JSON.stringify(record) + "\n", commonDir);
+        return record;
+    });
+}
+/** Reuse the live server, or start one and wait for it to record itself. */
+export async function ensureOffice(commonDir, start, options = {}) {
+    return await withPrivateFileLock(officeStartLockPath(commonDir), commonDir, async () => {
+        const live = await readLiveOffice(commonDir);
+        if (live !== null)
+            return officeUrl(live);
+        await start();
+        const deadline = Date.now() + (options.timeoutMs ?? 10_000);
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, options.pollMs ?? 200));
+            const started = await readLiveOffice(commonDir);
+            if (started !== null)
+                return officeUrl(started);
+        }
+        throw new AgentOpsError("OFFICE_START_FAILED", "The office server did not record itself in time.");
+    });
+}
+/** Drop the record on exit, unless another server has replaced it. */
+export async function releaseOffice(commonDir, record) {
+    await withPrivateFileLock(officeRecordPath(commonDir), commonDir, async () => {
+        const source = await readPrivateFile(officeRecordPath(commonDir), commonDir).catch(() => null);
+        if (source !== null && JSON.parse(source).token === record.token)
+            await rm(officeRecordPath(commonDir), { force: true });
+    });
+}

package/dist/runtime/src/office/sessions.js

@@ -0,0 +1,115 @@
+import { join } from "node:path";
+import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
+export const OFFICE_SESSION_STALE_MS = 30 * 60 * 1000;
+export const OFFICE_SESSION_RETENTION_MS = 2 * 60 * 60 * 1000;
+const OFFICE_SESSION_SCHEMA_VERSION = 1;
+const MAX_SESSIONS = 512;
+const MAX_TEXT = 256;
+const MAX_ROOT = 4_096;
+export const officeSessionsPath = (commonDir) => join(commonDir, "agent-ops", "office-sessions.json");
+function bounded(value, max) {
+    return typeof value === "string" && value.length > 0 && value.length <= max &&
+        !/[\0\r\n]/u.test(value);
+}
+function optional(value, max = MAX_TEXT) {
+    return value === undefined ? undefined : bounded(value, max) ? value : undefined;
+}
+function timestamp(value) {
+    return bounded(value, 64) && Number.isFinite(Date.parse(value));
+}
+function parseRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const item = value;
+    if (item.schemaVersion !== OFFICE_SESSION_SCHEMA_VERSION ||
+        !bounded(item.sessionId, MAX_TEXT) || !bounded(item.harness, MAX_TEXT) ||
+        !bounded(item.root, MAX_ROOT) || !timestamp(item.firstSeenAt) ||
+        !timestamp(item.lastSeenAt) || !["active", "idle"].includes(String(item.status))) {
+        return null;
+    }
+    if (item.completedAt !== undefined && item.completedAt !== null && !timestamp(item.completedAt))
+        return null;
+    const record = {
+        schemaVersion: 1,
+        sessionId: item.sessionId,
+        harness: item.harness,
+        root: item.root,
+        firstSeenAt: item.firstSeenAt,
+        lastSeenAt: item.lastSeenAt,
+        status: item.status,
+        ...(optional(item.agentId) === undefined ? {} : { agentId: optional(item.agentId) }),
+        ...(optional(item.runId) === undefined ? {} : { runId: optional(item.runId) }),
+        ...(optional(item.workerId) === undefined ? {} : { workerId: optional(item.workerId) }),
+        ...(optional(item.taskId) === undefined ? {} : { taskId: optional(item.taskId) }),
+        ...(optional(item.phase) === undefined ? {} : { phase: optional(item.phase) }),
+        ...(optional(item.host) === undefined ? {} : { host: optional(item.host) }),
+        ...(item.completedAt === undefined ? {} : { completedAt: item.completedAt })
+    };
+    return record;
+}
+async function readRecords(commonDir) {
+    const source = await readPrivateFile(officeSessionsPath(commonDir), commonDir).catch(() => null);
+    if (source === null)
+        return [];
+    try {
+        const value = JSON.parse(source);
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return [];
+        const sessions = value.sessions;
+        if (!Array.isArray(sessions))
+            return [];
+        return sessions.slice(0, MAX_SESSIONS).map(parseRecord).filter((record) => record !== null);
+    }
+    catch {
+        return [];
+    }
+}
+function retained(record, now) {
+    const lastSeen = Date.parse(record.lastSeenAt);
+    if (!Number.isFinite(lastSeen))
+        return false;
+    if (record.status === "active") {
+        // ponytail: one TTL handles crashed hook clients; a persistent host heartbeat can replace it if needed.
+        return now - lastSeen <= OFFICE_SESSION_STALE_MS;
+    }
+    const completed = record.completedAt === null || record.completedAt === undefined
+        ? lastSeen
+        : Date.parse(record.completedAt);
+    return Number.isFinite(completed) && now - completed < OFFICE_SESSION_RETENTION_MS;
+}
+function prune(records, now) {
+    return records.filter(record => retained(record, now)).slice(-MAX_SESSIONS);
+}
+export async function readOfficeSessions(commonDir, now = Date.now()) {
+    return prune(await readRecords(commonDir), now);
+}
+export async function recordOfficeSession(options) {
+    if (!bounded(options.sessionId, MAX_TEXT) || !bounded(options.harness, MAX_TEXT) ||
+        !bounded(options.projectRoot, MAX_ROOT) || !bounded(options.commonDir, MAX_ROOT))
+        return;
+    const now = options.now ?? Date.now();
+    const at = new Date(now).toISOString();
+    const path = officeSessionsPath(options.commonDir);
+    await withPrivateFileLock(path, options.commonDir, async () => {
+        const records = prune(await readRecords(options.commonDir), now);
+        const previous = records.find(record => record.sessionId === options.sessionId);
+        const next = {
+            schemaVersion: 1,
+            sessionId: options.sessionId,
+            harness: options.harness,
+            root: options.projectRoot,
+            firstSeenAt: previous?.firstSeenAt ?? at,
+            lastSeenAt: at,
+            status: options.event === "stop" ? "idle" : "active",
+            ...(options.agentId ?? previous?.agentId ? { agentId: options.agentId ?? previous?.agentId } : {}),
+            ...(options.runId ?? previous?.runId ? { runId: options.runId ?? previous?.runId } : {}),
+            ...(options.workerId ?? previous?.workerId ? { workerId: options.workerId ?? previous?.workerId } : {}),
+            ...(options.taskId ?? previous?.taskId ? { taskId: options.taskId ?? previous?.taskId } : {}),
+            ...(options.phase ?? previous?.phase ? { phase: options.phase ?? previous?.phase } : {}),
+            ...(options.host ?? previous?.host ? { host: options.host ?? previous?.host } : {}),
+            ...(options.event === "stop" && previous?.completedAt !== undefined ? { completedAt: previous.completedAt } : {})
+        };
+        const without = records.filter(record => record.sessionId !== options.sessionId);
+        await writePrivateFile(path, JSON.stringify({ schemaVersion: 1, sessions: [...without, next].slice(-MAX_SESSIONS) }) + "\n", options.commonDir);
+    });
+}

package/dist/runtime/src/office/snapshot.js

@@ -0,0 +1,107 @@
+import { activeWallTimeMs } from "../run/scheduler.js";
+const COMPLETED_RETENTION_MS = 2 * 60 * 60 * 1000;
+const LIVE = new Set(["assigned", "starting", "running", "idle", "handing-off", "fenced", "delivered", "blocked"]);
+const PHASES = new Set(["planning", "implementing", "verifying", "reviewing", "integrating", "unknown"]);
+function phaseOf(value) {
+    return value !== undefined && PHASES.has(value) ? value : "unknown";
+}
+/** Decision 8: narration comes from changed paths only. */
+export function narrate(diff) {
+    const path = diff?.recent ?? diff?.paths[0] ?? null;
+    if (path === null)
+        return null;
+    if (path.startsWith("docs/"))
+        return "writing docs";
+    if (path.startsWith("tests/"))
+        return "writing tests";
+    return "editing " + path;
+}
+function quote(text) {
+    return "'" + text.replaceAll("'", "'\\''") + "'";
+}
+/** Pure aggregation of runs, worktrees and review slots into one building. */
+export function buildOfficeSnapshot(input) {
+    const byPath = new Map(input.worktrees.map(w => [w.path, w]));
+    const claimed = new Set();
+    const runs = input.runs.filter(run => !["complete", "failed"].includes(run.status) || input.now - Date.parse(run.updatedAt) < COMPLETED_RETENTION_MS)
+        .map((run) => {
+        const roots = new Set(run.workers.map(w => w.worktree).filter((p) => p !== null));
+        const reviewers = input.reviews.filter(r => r.root !== null && roots.has(r.root)).slice(0, 2);
+        reviewers.forEach(r => claimed.add(r));
+        const usedMs = activeWallTimeMs(run.budget.activeIntervals, input.now);
+        const agents = run.workers.filter(w => w.workerId === run.coordinatorId || LIVE.has(w.status)).map((w) => {
+            const tree = w.worktree === null ? undefined : byPath.get(w.worktree);
+            const phase = w.phase ?? "unknown";
+            return { id: w.workerId, role: w.workerId === run.coordinatorId ? "coordinator" : "worker", status: w.status, phase,
+                taskId: w.taskId, progress: run.tasks.find(t => t.taskId === w.taskId)?.progress ?? null,
+                worktree: tree?.name ?? null, diff: tree?.diff ?? null,
+                narration: narrate(tree?.diff ?? null) ?? (phase === "unknown" ? w.status : phase) };
+        });
+        const questions = run.questions.filter(q => q.answeredAt === null).map(q => ({ questionId: q.questionId, prompt: q.prompt }));
+        return { runId: run.runId, title: run.rootTaskId ?? run.runId,
+            status: run.status, phase: run.phase ?? "unknown",
+            budget: { limitMs: run.budget.limitMs, usedMs, remainingMs: Math.max(0, run.budget.limitMs - usedMs) },
+            questions, agents, reviewers,
+            ...(run.status === "complete" || run.status === "failed" ? { completedAt: run.updatedAt } : {}),
+            commands: [`agent-ops run status ${run.runId}`, `agent-ops run logs ${run.runId}`,
+                ...questions.map(q => `agent-ops run respond ${run.runId} --question-id ${quote(q.questionId)} --answer "..."`),
+                `agent-ops run resume ${run.runId}`, `agent-ops run stop ${run.runId}`] };
+    });
+    const sessions = input.sessions ?? [];
+    const bySession = new Map(sessions.map(session => [session.sessionId, session]));
+    const runIds = new Set(input.runs.map(run => run.runId));
+    const runSessionIds = new Set(input.worktrees.filter(worktree => worktree.runId !== undefined).map(worktree => worktree.sessionId));
+    input.runs.flatMap(run => run.workers).forEach(worker => {
+        runSessionIds.add(worker.ownerSessionId);
+        if (worker.nativeSessionId !== null)
+            runSessionIds.add(worker.nativeSessionId);
+    });
+    const lobby = [];
+    const represented = new Set();
+    for (const worktree of input.worktrees) {
+        if (worktree.runId !== undefined)
+            continue;
+        const session = bySession.get(worktree.sessionId);
+        const completedAt = worktree.completedAt ?? session?.completedAt ?? null;
+        if (completedAt !== null && input.now - Date.parse(completedAt) >= COMPLETED_RETENTION_MS)
+            continue;
+        lobby.push({
+            name: worktree.name,
+            branch: worktree.branch,
+            sessionId: worktree.sessionId,
+            sessionActive: session?.status === "active" && completedAt === null,
+            diff: worktree.diff,
+            narration: narrate(worktree.diff) ?? worktree.phase ?? session?.phase ?? worktree.status ?? session?.status ?? "idle",
+            commands: ["agent-ops worktree list", `agent-ops worktree finish ${quote(worktree.name)}`],
+            ...(worktree.phase === undefined && session?.phase === undefined ? {} : { phase: phaseOf(worktree.phase ?? session?.phase) }),
+            ...(worktree.status === undefined && session?.taskStatus === undefined && session?.status === undefined ? {} : { status: worktree.status ?? session?.taskStatus ?? session?.status }),
+            ...(worktree.taskId === undefined && session?.taskId === undefined ? {} : { taskId: worktree.taskId ?? session?.taskId ?? null }),
+            ...(worktree.progress === undefined && session?.progress === undefined ? {} : { progress: worktree.progress ?? session?.progress ?? null }),
+            ...(completedAt === null && session?.completedAt === undefined ? {} : { completedAt: completedAt ?? session?.completedAt ?? null }),
+            ...(worktree.host === undefined && session?.host === undefined ? {} : { host: worktree.host ?? session?.host }),
+        });
+        represented.add(worktree.sessionId);
+    }
+    for (const session of sessions) {
+        if (represented.has(session.sessionId) || runSessionIds.has(session.sessionId) || (session.runId !== undefined && runIds.has(session.runId)))
+            continue;
+        represented.add(session.sessionId);
+        const completedAt = session.completedAt ?? null;
+        lobby.push({
+            name: session.sessionId,
+            branch: "(no worktree)",
+            sessionId: session.sessionId,
+            sessionActive: session.status === "active" && completedAt === null,
+            diff: { files: 0, insertions: 0, deletions: 0, paths: [], recent: null },
+            narration: session.phase === undefined ? session.taskStatus ?? session.status ?? "idle" : phaseOf(session.phase),
+            commands: [`agent-ops task status --session ${quote(session.sessionId)}`],
+            ...(session.phase === undefined ? {} : { phase: phaseOf(session.phase) }),
+            status: session.taskStatus ?? session.status,
+            ...(session.taskId === undefined ? {} : { taskId: session.taskId }),
+            ...(session.progress === undefined ? {} : { progress: session.progress }),
+            ...(completedAt === null ? {} : { completedAt }),
+            ...(session.host === undefined ? {} : { host: session.host })
+        });
+    }
+    return { generatedAt: new Date(input.now).toISOString(), runs, lobby, reviews: input.reviews.filter(r => !claimed.has(r)) };
+}

package/dist/runtime/src/parallel/guard.js

@@ -36,6 +36,8 @@ export async function canonicalPath(path) {
         }
     }
 }
+/** The gitignored goal file the `run` profile writes in the main checkout. */
+export const RUN_GOAL_FILE = join(".agent-ops", "state", "run-goal.md");
 /**
  * In worktree auto mode the main checkout is shared by every session, so no
  * session writes it directly: each edit belongs in that session's own
@@ -46,9 +48,13 @@ export async function evaluateWorktreeWrite(mainRoot, paths, sessionId,
 /** Creates or reuses this writer's worktree and returns its path. */
 ensureWorktree, 
 /** The subagent making the write, when there is one: it has a worktree of its own. */
-agentId) {
+agentId, 
+/** The `auto-run` capability: `agent-ops run` starts from the main checkout. */
+autoRun = false) {
     for (const path of paths) {
         const target = await canonicalPath(path);
+        if (autoRun && target === join(mainRoot, RUN_GOAL_FILE))
+            continue;
         const inMain = target === mainRoot || target.startsWith(`${mainRoot}${sep}`);
         if (inMain && insideWorktreeDirectory(mainRoot, target) && sessionId !== undefined) {
             // A worktree belongs to the session that made it: writing into another

package/dist/runtime/src/review/slots.js

@@ -62,7 +62,7 @@ export async function withReviewSlot(options, action) {
                     for (;;) {
                         try {
                             await mkdir(path);
-                            await writeFile(join(path, "owner.json"), JSON.stringify({ pid: process.pid, at: Date.now(), token }));
+                            await writeFile(join(path, "owner.json"), JSON.stringify({ ...options.holder, pid: process.pid, at: Date.now(), token }));
                             return true;
                         }
                         catch (error) {

package/dist/runtime/src/run/phase.js

@@ -0,0 +1,37 @@
+/** Move one worker, and the run with it, into a phase. Unknown workers leave the state unchanged. */
+export function withRunPhase(state, workerId, phase) {
+    if (!state.workers.some(w => w.workerId === workerId))
+        return state;
+    return { ...state, phase, workers: state.workers.map(w => w.workerId === workerId ? { ...w, phase } : w) };
+}
+/** Merge the latest verify or review observation into one task node. */
+export function withTaskProgress(state, taskId, update) {
+    return { ...state, tasks: state.tasks.map(t => t.taskId !== taskId ? t :
+            { ...t, progress: { verify: null, review: null, passed: 0, total: 0, ...t.progress, ...update } }) };
+}
+/**
+ * Passed/total criteria from one verify report: a command-backed criterion
+ * passes when every command result passed, a typed one when every replayed
+ * acceptance phase for it passed.
+ */
+export function criteriaProgress(criteria, report) {
+    const results = report.results ?? [];
+    const commandsPass = results.length > 0 && results.every(r => r.status === "PASS");
+    const passed = criteria.filter(c => {
+        if (c.acceptance === undefined)
+            return commandsPass;
+        const rows = (report.acceptance ?? []).filter(r => r.criterionId === c.id);
+        return rows.length > 0 && rows.every(r => r.status === "PASS");
+    }).length;
+    return { passed, total: criteria.length };
+}
+/** Phase writes are display data: a failed write must never fail the proof it describes. */
+export async function recordRunPhase(repository, runId, workerId, phase, progress) {
+    try {
+        await repository.mutate(runId, state => {
+            const moved = withRunPhase(state, workerId, phase);
+            return progress === undefined ? moved : withTaskProgress(moved, progress.taskId, progress.update);
+        });
+    }
+    catch { /* ponytail: display-only; the next transition rewrites it */ }
+}

package/dist/runtime/src/run/service.js

@@ -5,6 +5,7 @@ import { sha256 } from "../fs/hash.js";
 import { AgentOpsError } from "../fs/paths.js";
 import { readPrivateFile, withPrivateFileLock, writePrivateFile } from "../security/permissions.js";
 import { budgetExpired } from "./scheduler.js";
+export const RUN_PHASES = ["planning", "implementing", "verifying", "reviewing", "integrating"];
 /** Writer slots are deliberately bounded; the coordinator may occupy one. */
 export const MAX_ACTIVE_WORKERS = 2;
 const RUN_ID = /^[a-z][a-z0-9-]{7,63}$/u;
@@ -113,6 +114,13 @@ export function assertRunState(value) {
         return invalid("Persisted run state failed identity, budget, or ownership validation.");
     }
     validUsage(state.budget.usage);
+    const phase = (value) => value === undefined || RUN_PHASES.includes(value);
+    const count = (value) => Number.isSafeInteger(value) && value >= 0 && value <= 64;
+    const result = (value) => value === null || value === "PASS" || value === "FAIL";
+    if (!phase(state.phase) || state.workers.some(w => !phase(w.phase)) || state.tasks.some(t => t.progress !== undefined &&
+        (!plain(t.progress) || !result(t.progress.verify) || !result(t.progress.review) || !count(t.progress.passed) ||
+            !count(t.progress.total) || t.progress.passed > t.progress.total)))
+        return invalid("Run phase or task progress is invalid.");
     if (state.policyBinding !== undefined && !validPolicyBinding(state.policyBinding))
         return invalid("Invalid run policy binding.");
     if (state.proofProcess != null && (!plain(state.proofProcess) || !Number.isSafeInteger(state.proofProcess.processId) ||