@a-t-h-i/bot-lobby 0.6.18 → 0.6.20

package/README.md

@@ -20,7 +20,7 @@ Questionnaire and web tools are included; don't also install extensions register
 2. Answer the oracle's questions and approve its proposal, or use Plan to agree on a task first.
 3. Follow the agents in Lobby; configure models, effort and time limits in Settings.
 
-The Project selector switches among already-running, authorized project lobbies on one localhost origin.
+The project switcher (top left, `P`) switches among already-running, authorized project lobbies on one localhost origin.
 Upgrading? Reattach older temporary files; previews and attachments are now isolated per project.
 
 Small self-contained changes can route to Quick fix. `--task` forces a task;
@@ -52,6 +52,8 @@ Browser navigation is ignored while typing, composing with an IME or using an ov
 | `j` / `k` | Next / previous selectable list row |
 | `g` then a letter | Jump to a named tab (mapping below) |
 | `/` | Focus the current tab's search, when available |
+| `p` | Open the project switcher |
+| `d` | Switch between light and dark |
 | `?`, `Alt+H` | Shortcut help |
 | `Esc` | Close the top overlay or cancel a pending navigation prefix |
 | `Alt+S` | Settings |
@@ -59,6 +61,22 @@ Browser navigation is ignored while typing, composing with an IME or using an ov
 | `Alt+A` / `Alt+T` | Fold / expand Activity / Thinking |
 | `Ctrl+S` | Save the plan on Plan |
 
+Every action button prints its key (`Archive E`, `Delete Del`) and the key works while the list or
+the detail has focus (press `Esc` first to leave the message box). Keys that cannot be undone ask first;
+in that question `Y` confirms and `Esc` keeps.
+
+| Page | Keys |
+| --- | --- |
+| Tasks | `e` archive, `r` restore, `a` auto mode, `Delete` delete |
+| Saved plan | `s` start here, `n` new session, `Delete` discard |
+| Plan | `a` answer questions, `r` retry, `Ctrl+S` save, `n` new plan |
+| Quick fix | `r` run anyway, `t` make it a task, `c` cancel |
+| Git | `r` refresh, `v` review, `q` Jev's read, `x` stop the review |
+| Issues | `r` refresh |
+| Knowledge | `e` edit, `a` add, `c` comment, `f` edit the file, `Delete` delete |
+| Excalidraw | `r` reveal, `c` copy, `o` open, `w` let agents draw, `t` check, `Delete` remove |
+| Sessions | `m` move here, `s` stop, `b` back to the Lobby |
+
 `g` mapping: `l` Lobby, `p` Plan, `t` Tasks, `i` Issues, `u` Git,
 `s` Sessions, `n` Knowledge, `q` Quick fix, `m` Metrics, `e` Settings, `x` Excalidraw.
 Configured Alt/Ctrl actions are rebindable through `lobby.keys`; defaults live in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a-t-h-i/bot-lobby",
-  "version": "0.6.18",
+  "version": "0.6.20",
   "description": "Structured multi-agent software engineering orchestrator for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/src/ask/relay.ts

@@ -9,7 +9,7 @@
 import { previewRoot } from "../state/previews.ts";
 import { isAbsolute, join, resolve } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { MAX_OPTIONS, MAX_QUESTIONS, type AskQuestion, type AskResult, type Asker } from "./types.ts";
+import { validHtmlPreview, MAX_OPTIONS, MAX_QUESTIONS, type AskQuestion, type AskResult, type Asker } from "./types.ts";
 
 /** Env flag the master sets for a subagent that may ask the user. */
 export const ASK_ENV = "BOT_LOBBY_ASK";
@@ -51,6 +51,7 @@ const text = (value: unknown): value is string => typeof value === "string";
 function asQuestion(value: unknown): AskQuestion | undefined {
   const raw = value as Partial<AskQuestion> | null;
   if (!raw || !text(raw.question) || !text(raw.header) || !Array.isArray(raw.options)) return undefined;
+  if (raw.options.some((option) => option?.htmlPreview !== undefined && !validHtmlPreview(option.htmlPreview))) return undefined;
   const options = raw.options
     .filter((option) => option && text(option.label))
     .slice(0, MAX_OPTIONS)
@@ -59,6 +60,7 @@ function asQuestion(value: unknown): AskQuestion | undefined {
       ...(text(option.description) ? { description: option.description } : {}),
       ...(text(option.preview) ? { preview: option.preview } : {}),
       ...(text(option.image) ? { image: option.image } : {}),
+      ...(validHtmlPreview(option.htmlPreview) ? { htmlPreview: option.htmlPreview } : {}),
     }));
   if (options.length === 0) return undefined;
   return { question: raw.question, header: raw.header, options, ...(raw.multiSelect === true ? { multiSelect: true } : {}) };

package/src/ask/tool.ts

@@ -12,11 +12,19 @@ import { Type } from "typebox";
 import { isSubagentProcess } from "../pi/quiet.ts";
 import { askUser } from "./web.ts";
 import { relayAsker, relayEnabled } from "./relay.ts";
-import { ASK_TOOL, isImagePath, MAX_HEADER, MAX_LABEL, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, RESERVED, type AskQuestion, type AskResult, type Asker } from "./types.ts";
+import { ASK_TOOL, isImagePath, validHtmlPreview, MAX_PREVIEW_HTML, MAX_PREVIEW_CSS, MAX_HEADER, MAX_LABEL, MAX_OPTIONS, MAX_QUESTIONS, MIN_OPTIONS, RESERVED, type AskQuestion, type AskResult, type Asker } from "./types.ts";
+
+import { detectProjectRoot } from "../state/project.ts";
+import { ownedTask } from "../state/persistence.ts";
+import { withBlockingRequest } from "../state/blocking-requests.ts";
 
 export { ASK_TOOL };
 
 const OptionSchema = Type.Object({
+  htmlPreview: Type.Optional(Type.Object({
+    html: Type.String({ maxLength: MAX_PREVIEW_HTML }),
+    css: Type.Optional(Type.String({ maxLength: MAX_PREVIEW_CSS })),
+  }, { additionalProperties: false })),
   label: Type.String({ maxLength: MAX_LABEL, description: `The option as the user sees and picks it: 1-5 words, at most ${MAX_LABEL} characters.` }),
   description: Type.Optional(Type.String({ description: "What choosing it means: its trade-offs or consequences. Markdown." })),
   preview: Type.Optional(Type.String({ description: "Markdown shown beside the options while this one is focused: a mockup, a code snippet, a diagram, a config. Only when seeing it helps the user compare." })),
@@ -58,6 +66,7 @@ export function invalidQuestions(questions: readonly AskQuestion[]): string | un
       if (RESERVED.has(label)) return `${at}: "${option.label}" is kept for the user's own answer; leave it out`;
       if (labels.has(label)) return `${at} has two options labelled "${option.label}"`;
       if (option.image?.trim() && !isImagePath(option.image)) return `${at}: the image for "${option.label}" must be a .png, .jpg, .gif or .webp file`;
+      if (option.htmlPreview !== undefined && !validHtmlPreview(option.htmlPreview)) return `${at}: invalid static HTML/CSS preview`;
       labels.add(label);
     }
   }
@@ -96,7 +105,7 @@ export function answerSummary(questions: readonly AskQuestion[], result: AskResu
  * Register `ask_user_question` in this pi session; in a subagent only when
  * the master relays its questions. `ask` is swappable for tests.
  */
-export function registerAskTool(pi: ExtensionAPI, ask?: Asker): void {
+export function registerAskTool(pi: ExtensionAPI, ask?: Asker, configDir = ".pi"): void {
   const subagent = isSubagentProcess();
   if (subagent && !relayEnabled()) return;
   const asker = ask ?? (subagent ? relayAsker : askUser);
@@ -113,7 +122,13 @@ export function registerAskTool(pi: ExtensionAPI, ask?: Asker): void {
       const questions = (params as { questions: AskQuestion[] }).questions;
       const invalid = invalidQuestions(questions);
       if (invalid) throw new Error(`${invalid}.`);
-      const result = await asker(questions, ctx, signal, "oracle");
+      // A context without a cwd or session cannot be attributed to a task, so the ask runs untracked.
+      const root = ctx.cwd ? detectProjectRoot(ctx.cwd, configDir) : undefined;
+      const sessionId = ctx.sessionManager?.getSessionId();
+      const task = subagent || !root || !sessionId ? undefined : ownedTask(root, configDir, sessionId);
+      const tracked = task && root && sessionId ? { root, configDir, taskId: task.id, sessionId } : undefined;
+      const run = () => asker(questions, ctx, signal, "oracle");
+      const result = tracked ? await withBlockingRequest(tracked, run) : await run();
       return { content: [{ type: "text", text: answerSummary(questions, result) }], details: result };
     },
     renderCall(args, theme) {

package/src/ask/types.ts

@@ -16,6 +16,8 @@ export const MIN_OPTIONS = 2;
 export const MAX_OPTIONS = 4;
 export const MAX_HEADER = 16;
 export const MAX_LABEL = 60;
+export const MAX_PREVIEW_HTML = 100_000;
+export const MAX_PREVIEW_CSS = 50_000;
 
 /** The row under every question's options where the user writes their own answer. */
 export const OWN_ANSWER = "Type something.";
@@ -25,6 +27,8 @@ export const RESERVED = new Set(["other", OWN_ANSWER.toLowerCase(), "next"]);
 
 export interface AskOption {
   label: string;
+  /** Explicit static HTML/CSS; never inferred from Markdown. */
+  htmlPreview?: { html: string; css?: string };
   description?: string;
   /** Markdown shown beside the options while this one is focused. */
   preview?: string;
@@ -32,6 +36,14 @@ export interface AskOption {
   image?: string;
 }
 
+export function validHtmlPreview(value: unknown): value is NonNullable<AskOption["htmlPreview"]> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const preview = value as Record<string, unknown>;
+  return Object.keys(preview).every((key) => key === "html" || key === "css")
+    && typeof preview.html === "string" && preview.html.length <= MAX_PREVIEW_HTML
+    && (preview.css === undefined || (typeof preview.css === "string" && preview.css.length <= MAX_PREVIEW_CSS));
+}
+
 export interface AskQuestion {
   question: string;
   /** A short chip naming the question (a topic, or who asks it). */

package/src/ask/web.ts

@@ -8,7 +8,7 @@
 import { isAbsolute, resolve } from "node:path";
 import { currentWebServer } from "../webui/server.ts";
 import { promptHub } from "../lobby/prompt-hub.ts";
-import type { AskAnswer, AskQuestion, AskResult, Asker } from "./types.ts";
+import { validHtmlPreview, type AskAnswer, type AskQuestion, type AskResult, type Asker } from "./types.ts";
 
 let availability: (() => boolean) | undefined;
 
@@ -43,6 +43,7 @@ function readResult(value: unknown): AskResult | undefined {
 
 /** The questionnaire in the page. */
 export const askUser: Asker = async (questions, ctx, signal, from) => {
+  if (questions.some((question) => question.options.some((option) => option.htmlPreview !== undefined && !validHtmlPreview(option.htmlPreview)))) throw new Error("Invalid static HTML/CSS preview");
   if (questions.length === 0 || !canAsk()) return { answers: [], cancelled: true };
   const outcome = await promptHub.ask("questionnaire", from ?? "oracle", { questions: withAbsoluteImages(questions, ctx.cwd) }, signal ? { signal } : undefined);
   return (outcome.how === "answered" ? readResult(outcome.value) : undefined) ?? { answers: [], cancelled: true };

package/src/delivery/checks.ts

@@ -0,0 +1,37 @@
+import type { DeliveryChecksState } from "./types.ts";
+import { api, object, pages, type DeliveryContext } from "./transport.ts";
+
+export interface Check { name: string; state: "passing" | "failing" | "pending" }
+export interface Checks { state: DeliveryChecksState; entries: Check[]; reason?: string }
+function checkRun(raw: unknown, sha: string): Check {
+  const row = object(raw);
+  if (typeof row.name !== "string" || !row.name || row.head_sha !== sha) throw new Error("Stale or malformed check run; refresh review.");
+  if (!["queued", "in_progress", "completed", "waiting", "requested", "pending"].includes(String(row.status))) throw new Error("Unknown check status.");
+  if (row.status !== "completed") return { name: row.name, state: "pending" };
+  if (!["success", "neutral", "skipped", "failure", "cancelled", "timed_out", "action_required", "stale", "startup_failure"].includes(String(row.conclusion))) throw new Error("Unknown check conclusion.");
+  return { name: row.name, state: ["success", "neutral", "skipped"].includes(String(row.conclusion)) ? "passing" : "failing" };
+}
+function status(raw: unknown): Check {
+  const row = object(raw);
+  if (typeof row.context !== "string" || !row.context || !["success", "pending", "failure", "error"].includes(String(row.state))) throw new Error("Malformed commit status.");
+  return { name: row.context, state: row.state === "success" ? "passing" : row.state === "pending" ? "pending" : "failing" };
+}
+async function statuses(ctx: DeliveryContext, repo: string, sha: string): Promise<Check[]> {
+  const combined = object(await api(ctx, `repos/${repo}/commits/${sha}/status`));
+  if (combined.sha !== sha || !Number.isInteger(combined.total_count) || !Array.isArray(combined.statuses) || !["success", "pending", "failure"].includes(String(combined.state))) throw new Error("Malformed combined statuses.");
+  const rows = await pages(ctx, `repos/${repo}/commits/${sha}/statuses`);
+  // GitHub lists newest first; older results for the same context are superseded.
+  const latest = new Map<string, Check>();
+  for (const raw of rows) { const entry = status(raw); if (!latest.has(entry.name)) latest.set(entry.name, entry); }
+  if (latest.size !== combined.total_count) throw new Error("Statuses changed during lookup; refresh review.");
+  return [...latest.values()];
+}
+export async function readChecks(ctx: DeliveryContext, repo: string, sha: string): Promise<Checks> {
+  try {
+    const runs = await pages(ctx, `repos/${repo}/commits/${sha}/check-runs`, "check_runs");
+    const entries = [...runs.map((raw) => checkRun(raw, sha)), ...await statuses(ctx, repo, sha)];
+    entries.sort((a, b) => a.name.localeCompare(b.name) || a.state.localeCompare(b.state));
+    const state = entries.some((v) => v.state === "failing") ? "failing" : entries.some((v) => v.state === "pending") ? "pending" : entries.length ? "passing" : "absent";
+    return { state, entries };
+  } catch (error) { return { state: /[Ss]tale/.test((error as Error).message) ? "stale" : "unavailable", entries: [], reason: (error as Error).message }; }
+}

package/src/delivery/lock.ts

@@ -0,0 +1,78 @@
+import { constants, closeSync, fsyncSync, ftruncateSync, openSync, readFileSync, realpathSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export interface LockIdentity { taskId: string; projectRoot: string; configDir: string; operationId: string }
+export interface LockOwner { token: string; pid: number; identity?: LockIdentity }
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException).code !== "ESRCH"; }
+}
+function owner(path: string): LockOwner | undefined {
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return; throw error; }
+  try {
+    const value = JSON.parse(readFileSync(fd, "utf8")) as LockOwner;
+    if (!Number.isInteger(value.pid) || value.pid <= 0 || typeof value.token !== "string" || !value.token) throw new Error("Invalid delivery lock owner.");
+    return value;
+  } finally { closeSync(fd); }
+}
+function removeOwned(path: string, token: string): void {
+  if (owner(path)?.token === token) unlinkSync(path);
+}
+export type DeliveryLock = (() => void) & { setOperation(id: string): void };
+function update(path: string, token: string, operationId: string): void {
+  const fd = openSync(path, constants.O_RDWR | constants.O_NOFOLLOW);
+  try {
+    const value = JSON.parse(readFileSync(fd, "utf8")) as LockOwner;
+    if (value.token !== token) throw new Error("Delivery lock ownership changed.");
+    if (!value.identity) return;
+    value.identity.operationId = operationId;
+    const text = JSON.stringify(value);
+    writeSync(fd, text, 0, "utf8"); ftruncateSync(fd, Buffer.byteLength(text)); fsyncSync(fd);
+  } finally { closeSync(fd); }
+}
+function create(path: string, identity?: LockIdentity): DeliveryLock {
+  const token = randomUUID();
+  const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  try { writeFileSync(fd, JSON.stringify({ token, pid: process.pid, identity })); fsyncSync(fd); }
+  finally { closeSync(fd); }
+  return Object.assign(() => removeOwned(path, token), { setOperation: (id: string) => update(path, token, id) });
+}
+function marker(path: string): void {
+  const previous = owner(path);
+  if (!previous) return;
+  if (alive(previous.pid)) throw new Error("Delivery recovery is busy; wait and retry.");
+  // A dead marker performed no publishing. Its token must still match before removal.
+  removeOwned(path, previous.token);
+}
+/** Synchronous normal claims remain useful for callers that do not authorize recovery. */
+export function acquireDeliveryLock(repository: string, identity?: LockIdentity): DeliveryLock {
+  const path = join(realpathSync(repository), "dev-house-delivery-main.lock");
+  if (owner(`${path}.recovery`)) throw new Error("Delivery recovery is busy; wait and retry.");
+  try { const release = create(path, identity); if (owner(`${path}.recovery`)) { release(); throw new Error("Delivery recovery is busy."); } return release; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    const previous = owner(path);
+    throw new Error(previous && alive(previous.pid) ? "Delivery is busy for this repository/main; wait and refresh." : "Interrupted delivery lock requires read-only recovery.");
+  }
+}
+async function reclaim(path: string, previous: LockOwner, recover: (owner: LockOwner) => Promise<void>): Promise<void> {
+  const release = create(`${path}.recovery`, previous.identity);
+  try {
+    const current = owner(path);
+    if (current?.token !== previous.token || alive(current.pid)) throw new Error("Delivery owner changed; retry without recovery.");
+    await recover(current);
+    if (owner(path)?.token !== previous.token) throw new Error("Delivery owner changed during recovery.");
+    removeOwned(path, previous.token);
+  } finally { release(); }
+}
+/** Reconciliation is read-only; no request can bypass the exclusive recovery marker. */
+export async function recoverDeliveryLock(repository: string, identity: LockIdentity | undefined, recover: (owner: LockOwner) => Promise<void>): Promise<DeliveryLock> {
+  const path = join(realpathSync(repository), "dev-house-delivery-main.lock");
+  marker(`${path}.recovery`);
+  const previous = owner(path);
+  if (previous && !alive(previous.pid)) await reclaim(path, previous, recover);
+  return acquireDeliveryLock(repository, identity);
+}

package/src/delivery/merge.ts

@@ -0,0 +1,44 @@
+import { mkdtempSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import type { DeliveryOperation, DeliveryResult } from "./types.ts";
+import { command, type DeliveryContext } from "./transport.ts";
+import { refreshMain, sha } from "./source.ts";
+import type { SaveStage } from "./pr.ts";
+
+async function ancestor(ctx: DeliveryContext, source: string, target: string): Promise<boolean> {
+  const result = await ctx.exec("git", ["merge-base", "--is-ancestor", source, target], { cwd: ctx.cwd, timeout: 20_000 });
+  if (result.code !== 0 && result.code !== 1) throw new Error("Remote ancestry cannot be verified; restore repository access before retrying.");
+  return result.code === 0;
+}
+export async function reconcileMerge(ctx: DeliveryContext, op: DeliveryOperation): Promise<DeliveryResult | undefined> {
+  const remote = await refreshMain(ctx);
+  if (await ancestor(ctx, op.mergeCommit ?? op.sourceCommit, remote)) return { action: "merge_main", commit: op.mergeCommit ?? op.sourceCommit };
+}
+async function integrate(ctx: DeliveryContext, op: DeliveryOperation, save: SaveStage): Promise<void> {
+  const directory = mkdtempSync(join(realpathSync(op.repository!), "dev-house-integration-"));
+  const path = join(directory, "worktree");
+  op.integrationPath = path; op.stage = "integrating"; save();
+  await command(ctx, "git", ["worktree", "add", "--detach", path, op.targetCommit!]);
+  const isolated = { ...ctx, cwd: path };
+  try { await mergeCommit(isolated, op, save); }
+  finally { await command(ctx, "git", ["worktree", "remove", "--force", path]); }
+}
+async function mergeCommit(ctx: DeliveryContext, op: DeliveryOperation, save: SaveStage): Promise<void> {
+  try { await command(ctx, "git", ["merge", "--ff", "--no-edit", op.sourceCommit]); }
+  catch { await command(ctx, "git", ["merge", "--abort"]); throw new Error("Isolated merge failed (conflict, hooks or identity). Resolve the task branch and refresh review; main was not pushed."); }
+  op.mergeCommit = sha(await command(ctx, "git", ["rev-parse", "HEAD^{commit}"]));
+  op.stage = "merged"; save();
+}
+export async function publishMerge(ctx: DeliveryContext, op: DeliveryOperation, save: SaveStage, verify: () => Promise<void>): Promise<DeliveryResult> {
+  const existing = await reconcileMerge(ctx, op);
+  if (existing) return existing;
+  if (!op.mergeCommit) await integrate(ctx, op, save);
+  await verify();
+  if (await refreshMain(ctx) !== op.targetCommit) throw new Error("Remote main changed. Preserve the recorded merge and refresh review for a fresh explicit approval; no push was attempted.");
+  op.stage = "pushing_main"; save();
+  try { await command(ctx, "git", ["push", "origin", `${op.mergeCommit}:refs/heads/main`]); }
+  catch (error) { const result = await reconcileMerge(ctx, op); if (result) return result; throw error; }
+  const result = await reconcileMerge(ctx, op);
+  if (!result) throw new Error("Main push cannot be verified; retry reconciliation after remote access recovers.");
+  return result;
+}

package/src/delivery/operations.ts

@@ -0,0 +1,134 @@
+import { randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Task } from "../schemas/task.ts";
+import type { Delivery, DeliveryAction, DeliveryOperation, DeliveryResult } from "./types.ts";
+import { refreshReview, validateReview } from "./review.ts";
+import { command, type DeliveryContext } from "./transport.ts";
+import { readSource } from "./source.ts";
+import { recoverDeliveryLock, type LockIdentity, type LockOwner } from "./lock.ts";
+import { matchingPull, publishPull } from "./pr.ts";
+import { publishMerge, reconcileMerge } from "./merge.ts";
+
+export interface DeliveryRequest { reviewId: string; action: DeliveryAction; confirmMain?: boolean }
+export interface DeliveryStore {
+  load(): Task; save(task: Task): void;
+  identity?: { projectRoot: string; configDir: string };
+  recoveryStore?(identity: LockIdentity): DeliveryStore;
+}
+function approved(task: Task, request: DeliveryRequest): Delivery {
+  if (task.state !== "completed") throw new Error("Only completed work can be delivered.");
+  if (request.action === "merge_main" && request.confirmMain !== true) throw new Error("Explicit confirmation is required: direct merge updates and pushes main.");
+  return validateReview(task, request.reviewId);
+}
+function intent(delivery: Delivery, action: DeliveryAction): DeliveryOperation {
+  if (!delivery.sourceCommit || !delivery.targetCommit || !delivery.repository || !delivery.remote || !delivery.fingerprint) throw new Error("Review lacks a complete source/main identity. Refresh before delivery.");
+  return { id: randomUUID(), action, repository: delivery.repository, remote: delivery.remote, sourceBranch: delivery.sourceBranch,
+    sourceCommit: delivery.sourceCommit, targetCommit: delivery.targetCommit, target: "main", fingerprint: delivery.fingerprint,
+    reviewId: delivery.reviewId, stage: "intent", startedAt: new Date().toISOString() };
+}
+async function refreshed(task: Task, ctx: DeliveryContext): Promise<Delivery> {
+  const copy = structuredClone(task);
+  delete copy.delivery!.operation; delete copy.delivery!.result;
+  copy.delivery!.status = "pending_approval";
+  return refreshReview(copy, ctx);
+}
+async function verify(task: Task, op: DeliveryOperation, ctx: DeliveryContext): Promise<void> {
+  const source = await readSource(task, ctx);
+  if (source.commit !== op.sourceCommit || source.branch !== op.sourceBranch || source.remote !== op.remote || source.repository !== op.repository) throw new Error("Reviewed source or remote changed. Restore it or refresh review; no further publishing was attempted.");
+}
+async function verifySnapshot(task: Task, op: DeliveryOperation, ctx: DeliveryContext): Promise<void> {
+  await verify(task, op, ctx);
+  const next = await refreshed(task, ctx);
+  if (next.fingerprint !== op.fingerprint || next.blocked[op.action]) throw new Error("Source, main, checks or repository rules changed during delivery. Refresh review and explicitly approve again.");
+}
+function success(task: Task, result: DeliveryResult, store: DeliveryStore): Delivery {
+  const delivery = task.delivery!;
+  delivery.status = "successful"; delivery.result = result; delete delivery.error;
+  delivery.operation!.stage = "verified";
+  delivery.operation!.pullNumber = result.pullNumber; delivery.operation!.pullUrl = result.pullUrl;
+  store.save(task); return delivery;
+}
+async function reconcile(task: Task, ctx: DeliveryContext): Promise<DeliveryResult | undefined> {
+  const op = task.delivery!.operation!;
+  const common = realpathSync(resolve(ctx.cwd, await command(ctx, "git", ["rev-parse", "--git-common-dir"])));
+  const remote = await command(ctx, "git", ["remote", "get-url", "origin"]);
+  if (common !== op.repository || remote !== op.remote) throw new Error("Approved repository or remote changed; restore it before reconciliation.");
+  return op.action === "create_pr" ? matchingPull(ctx, op) : reconcileMerge(ctx, op);
+}
+async function prepare(task: Task, request: DeliveryRequest, ctx: DeliveryContext, store: DeliveryStore, operationId: string): Promise<boolean> {
+  const old = task.delivery!;
+  const next = await refreshed(task, ctx);
+  if (next.reviewId !== request.reviewId || next.fingerprint !== old.fingerprint) {
+    next.operation = old.operation; next.error = "Review changed. Inspect refreshed source, main and verification and choose an action again. Recorded operations require reconciliation before replacement.";
+    task.delivery = next; store.save(task); return false;
+  }
+  if (next.blocked[request.action]) throw new Error(next.blocked[request.action]);
+  task.delivery = next; next.previousOperations = old.previousOperations;
+  next.operation = reapprove(old, next, request.action, operationId);
+  task.delivery.status = "in_progress"; delete task.delivery.error;
+  store.save(task); return true;
+}
+function reapprove(old: Delivery, next: Delivery, action: DeliveryAction, operationId: string): DeliveryOperation {
+  const op = old.operation;
+  if (op?.action === action && op.fingerprint === next.fingerprint) return { ...op, reviewId: next.reviewId };
+  if (op) next.previousOperations = [...(old.previousOperations ?? []), { ...op, stage: "superseded_not_delivered" }].slice(-10);
+  return { ...intent(next, action), id: operationId === op?.id ? randomUUID() : operationId };
+}
+async function trustedRecovery(owner: LockOwner, ctx: DeliveryContext, store: DeliveryStore): Promise<{ task: Task; recovery: DeliveryStore }> {
+  if (!owner.identity || !store.recoveryStore) throw new Error("Interrupted owner lacks a trusted recovery identity; recovery is blocked.");
+  const recovery = store.recoveryStore(owner.identity);
+  const root = realpathSync(owner.identity.projectRoot);
+  const recordedCommon = realpathSync(resolve(root, await command({ ...ctx, cwd: root }, "git", ["rev-parse", "--git-common-dir"])));
+  const common = realpathSync(resolve(ctx.cwd, await command(ctx, "git", ["rev-parse", "--git-common-dir"])));
+  if (recordedCommon !== common) throw new Error("Interrupted owner's canonical repository does not match this target.");
+  const task = recovery.load();
+  if (task.id !== owner.identity.taskId) throw new Error("Interrupted task identity mismatch.");
+  const op = task.delivery?.operation;
+  if (op && op.id !== owner.identity.operationId && !task.delivery!.previousOperations?.some((previous) => previous.id === owner.identity!.operationId && previous.stage === "superseded_not_delivered")) throw new Error("Interrupted operation identity changed; recovery is blocked.");
+  return { task, recovery };
+}
+async function recoverOwner(owner: LockOwner, ctx: DeliveryContext, store: DeliveryStore): Promise<void> {
+  const { task, recovery } = await trustedRecovery(owner, ctx, store);
+  if (!task.delivery?.operation) return;
+  try {
+    const result = await reconcile(task, ctx);
+    if (result) { success(task, result, recovery); return; }
+    task.delivery!.status = "recoverable_failure";
+    task.delivery!.error = "Interrupted operation reconciled without delivery; explicitly approve the current review to retry.";
+    recovery.save(task);
+  } catch (error) {
+    task.delivery!.status = "recoverable_failure"; task.delivery!.error = (error as Error).message;
+    recovery.save(task); throw error;
+  }
+}
+async function execute(task: Task, request: DeliveryRequest, ctx: DeliveryContext, store: DeliveryStore, operationId: string): Promise<Delivery> {
+  if (task.delivery?.status === "successful") return task.delivery;
+  const delivery = approved(task, request);
+  try {
+    if (delivery.operation) { const result = await reconcile(task, ctx); if (result) return success(task, result, store); }
+    if (!await prepare(task, request, ctx, store, operationId)) return task.delivery!;
+    const op = task.delivery!.operation!;
+    const save = () => store.save(task);
+    const check = () => verifySnapshot(task, op, ctx);
+    const result = op.action === "create_pr" ? await publishPull(ctx, op, save, check) : await publishMerge(ctx, op, save, check);
+    return success(task, result, store);
+  } catch (error) {
+    task.delivery!.status = task.delivery!.operation ? "recoverable_failure" : "pending_approval";
+    task.delivery!.error = (error as Error).message; store.save(task); return task.delivery!;
+  }
+}
+/** Explicit API only. Lock covers refresh, approval, durable intent, reconciliation and side effects. */
+export async function deliver(request: DeliveryRequest, ctx: DeliveryContext, store: DeliveryStore): Promise<Delivery> {
+  const common = realpathSync(resolve(ctx.cwd, await command(ctx, "git", ["rev-parse", "--git-common-dir"])));
+  const task = store.load();
+  const operationId = task.delivery?.operation?.id ?? randomUUID();
+  const identity = store.identity && { ...store.identity, taskId: task.id, operationId };
+  const release = await recoverDeliveryLock(common, identity, (owner) => recoverOwner(owner, ctx, store));
+  const lockedStore = { ...store, save: (value: Task) => {
+    store.save(value);
+    if (value.delivery?.operation) release.setOperation(value.delivery.operation.id);
+  } };
+  try { return await execute(store.load(), request, ctx, lockedStore, operationId); }
+  finally { release(); }
+}

package/src/delivery/pr.ts

@@ -0,0 +1,40 @@
+import type { DeliveryOperation, DeliveryResult } from "./types.ts";
+import { command, object, type DeliveryContext } from "./transport.ts";
+import { sha } from "./source.ts";
+
+export type SaveStage = () => void;
+export async function matchingPull(ctx: DeliveryContext, op: DeliveryOperation): Promise<DeliveryResult | undefined> {
+  const text = await command(ctx, "gh", ["pr", "list", "--state", "all", "--head", op.sourceBranch!, "--base", "main", "--limit", "1000", "--json", "number,url,state,headRefOid,headRefName,baseRefName"]);
+  const rows: unknown = JSON.parse(text);
+  if (!Array.isArray(rows) || rows.length >= 1000) throw new Error("PR reconciliation is incomplete; inspect repository PRs before retrying.");
+  const matches = rows.map(object).filter((row) => row.headRefOid === op.sourceCommit && row.headRefName === op.sourceBranch && row.baseRefName === "main");
+  if (matches.length > 1) throw new Error("Multiple matching PRs; reconcile them manually before retrying.");
+  const row = matches[0];
+  if (!row) return undefined;
+  if (row.state === "CLOSED") throw new Error("Matching PR was closed without merging; reopen it or explicitly review a new source commit.");
+  if (!["OPEN", "MERGED"].includes(String(row.state)) || !Number.isInteger(row.number) || typeof row.url !== "string" || !/^https:\/\/github\.com\//.test(row.url)) throw new Error("Malformed matching PR; verify its state manually.");
+  return { action: "create_pr", pullNumber: Number(row.number), pullUrl: row.url };
+}
+async function remoteBranch(ctx: DeliveryContext, branch: string): Promise<string | undefined> {
+  const output = await command(ctx, "git", ["ls-remote", "--heads", "origin", `refs/heads/${branch}`]);
+  if (!output) return undefined;
+  const [commit, ref] = output.split(/\s+/);
+  if (ref !== `refs/heads/${branch}`) throw new Error("Unexpected remote branch identity.");
+  return sha(commit!);
+}
+export async function publishPull(ctx: DeliveryContext, op: DeliveryOperation, save: SaveStage, verify: () => Promise<void>): Promise<DeliveryResult> {
+  const existing = await matchingPull(ctx, op);
+  if (existing) return existing;
+  if (await remoteBranch(ctx, op.sourceBranch!) !== op.sourceCommit) {
+    try { await command(ctx, "git", ["push", "origin", `${op.sourceCommit}:refs/heads/${op.sourceBranch}`]); }
+    catch (error) { if (await remoteBranch(ctx, op.sourceBranch!) !== op.sourceCommit) throw error; }
+  }
+  if (await remoteBranch(ctx, op.sourceBranch!) !== op.sourceCommit) throw new Error("Task branch push could not be verified; preserve work and retry after remote access recovers.");
+  op.stage = "branch_pushed"; save();
+  await verify();
+  try { await command(ctx, "gh", ["pr", "create", "--head", op.sourceBranch!, "--base", "main", "--title", `Completed work: ${op.sourceBranch}`, "--body", `Explicit delivery of reviewed commit ${op.sourceCommit}.`]); }
+  catch (error) { const found = await matchingPull(ctx, op); if (found) return found; throw error; }
+  const result = await matchingPull(ctx, op);
+  if (!result) throw new Error("PR creation response was not verified; refresh/retry to reconcile before creating another PR.");
+  return result;
+}

package/src/delivery/review.ts

@@ -0,0 +1,90 @@
+import { createHash, randomUUID } from "node:crypto";
+import type { Task } from "../schemas/task.ts";
+import { completionBlockers } from "../master/decisions.ts";
+import { pendingApprovals } from "../workflow/approvals.ts";
+import { qaRequired } from "../workflow/track.ts";
+import type { Delivery } from "./types.ts";
+import { readSource, refreshMain, type Source } from "./source.ts";
+import { readChecks, type Checks } from "./checks.ts";
+import { readRules, type Rules } from "./rules.ts";
+import type { DeliveryContext } from "./transport.ts";
+
+export function localVerified(task: Task): boolean {
+  return task.state === "completed" && !task.qaWaiver && completionBlockers(task, pendingApprovals(task).length).length === 0
+    && (!qaRequired(task) || task.qaVerdict === "pass");
+}
+export function newDelivery(task: Task, project: string): Delivery {
+  return { status: "pending_approval", reviewId: randomUUID(), project, sourceBranch: task.git?.branch ?? "unavailable",
+    target: "main", reviewedAt: new Date().toISOString(), blocked: { create_pr: "Refresh review to verify the task source.", merge_main: "Refresh review to verify source, main, checks and repository rules." } };
+}
+export async function completionReview(task: Task, project: string, ctx: DeliveryContext): Promise<Delivery> {
+  const delivery = newDelivery(task, project);
+  try { const source = await readSource(task, ctx); applySource(delivery, source); delete delivery.blocked.create_pr; }
+  catch (error) { delivery.error = (error as Error).message; delivery.blocked = { create_pr: delivery.error, merge_main: delivery.error }; }
+  return delivery;
+}
+function applySource(delivery: Delivery, source: Source): void {
+  delivery.repository = source.repository;
+  delivery.remote = source.remote;
+  delivery.sourceBranch = source.branch;
+  delivery.sourceCommit = source.commit;
+}
+function mergeReason(checks: Checks, rules: Rules, verified: boolean): string | undefined {
+  if (!rules.known || rules.blocked) return rules.blocked;
+  if (["unavailable", "stale", "pending", "failing"].includes(checks.state)) return checks.reason ?? `Checks are ${checks.state}. Resolve them and refresh review, then choose Merge again.`;
+  const missing = rules.required.filter((name) => !checks.entries.some((entry) => entry.name === name && entry.state === "passing"));
+  if (missing.length) return `Required checks missing or not passing: ${missing.join(", ")}. Run them and refresh review.`;
+  if (!verified) return "Local completion/QA verification is not passing. Obtain a QA pass; a waiver is not delivery verification.";
+  if (checks.state === "absent" && rules.required.length) return "Required repository checks are absent. Run them before merging.";
+}
+function semantic(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(semantic).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).filter(([key]) => !/(?:_at|url|^id$|node_id)$/.test(key))
+    .sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, semantic(item)]));
+}
+function fingerprint(value: unknown): string { return createHash("sha256").update(JSON.stringify(semantic(value))).digest("hex"); }
+async function preflight(task: Task, delivery: Delivery, ctx: DeliveryContext): Promise<unknown> {
+  const source = await readSource(task, ctx);
+  applySource(delivery, source);
+  delete delivery.blocked.create_pr;
+  const sourceCtx = { ...ctx, cwd: source.cwd };
+  try { delivery.targetCommit = await refreshMain(sourceCtx); }
+  catch (error) { delivery.blocked.create_pr = "Target main is unavailable. Restore remote access and main, then refresh review."; throw error; }
+  const checks = await readChecks(sourceCtx, source.github, source.commit);
+  const rules = await readRules(sourceCtx, source.github);
+  const verified = localVerified(task);
+  delivery.verification = { checks: checks.state, summary: checks.reason ?? `Remote checks: ${checks.state}. Local completion/QA: ${verified ? "passing" : "not verified"}.`, localVerified: verified, requiredChecks: rules.required, rulesKnown: rules.known };
+  const reason = mergeReason(checks, rules, verified);
+  delivery.blocked.merge_main = reason;
+  if (!reason) delete delivery.blocked.merge_main;
+  return { source, main: delivery.targetCommit, checks, rules, verified };
+}
+/** Read-only preflight apart from fetching the remote tracking ref; never publishes. */
+export async function refreshReview(task: Task, ctx: DeliveryContext): Promise<Delivery> {
+  if (!task.delivery) throw new Error("This historical task has no delivery review; no retroactive approval was created.");
+  if (["successful", "in_progress"].includes(task.delivery.status)) return task.delivery;
+  const delivery = structuredClone(task.delivery);
+  delete delivery.error;
+  delivery.blocked.create_pr = "Task source could not be verified. Restore its clean branch and refresh review.";
+  delete delivery.verification;
+  delete delivery.targetCommit;
+  let snapshot: unknown;
+  try { snapshot = await preflight(task, delivery, ctx); }
+  catch (error) { delivery.error = (error as Error).message; delivery.blocked.merge_main = delivery.error; snapshot = { source: delivery.sourceCommit, main: delivery.targetCommit, error: delivery.error }; }
+  const next = fingerprint(snapshot);
+  if (delivery.fingerprint !== next) { delivery.reviewId = randomUUID(); delivery.status = "pending_approval"; delivery.reviewedAt = new Date().toISOString(); }
+  delivery.fingerprint = next;
+  task.delivery = delivery;
+  return delivery;
+}
+export function deferReview(task: Task, reviewId: string): Delivery {
+  const delivery = validateReview(task, reviewId);
+  if (delivery.operation || ["successful", "in_progress"].includes(delivery.status)) throw new Error("Delivery already started or succeeded; reconcile it before deferring.");
+  delivery.status = "deferred";
+  return delivery;
+}
+export function validateReview(task: Task, reviewId: string): Delivery {
+  if (!task.delivery || task.delivery.reviewId !== reviewId) throw new Error("Review changed. Refresh and review the new source, main and verification before choosing an action.");
+  return task.delivery;
+}