papilot 0.8.4 → 0.8.6

package/src/server/updates.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { devRevision, newerVersion, readJson, stableVersion, writeJson } from '../../bin/installation.mjs';
-import { installRelease, loaderFor, npmCli } from './update-install.ts';
+import { download, installLayer, installRelease, loaderFor, npmCli, type DesktopLayer } from './update-install.ts';
 import type { UpdateChannel, UpdateStatus } from '../shared.ts';
 
 const activePhases = new Set(['installing', 'waiting', 'restarting']);
@@ -31,28 +31,41 @@ export async function latestManifest(channel: UpdateChannel = 'stable', fetcher
 }
 export const latestRelease = async (channel: UpdateChannel = 'stable', fetcher = fetch) => (await latestManifest(channel, fetcher)).version as string;
 export const DESKTOP_RELEASES = 'https://github.com/PapilotAI/papilot/releases';
-// npm can be published before desktop builds finish. Only advertise releases
-// with an uploaded installer for this OS and CPU, and link to that exact release.
-export async function latestDesktopRelease(platform = process.platform, arch = process.arch, fetcher = fetch) {
-  const releases = await releaseInfo('https://api.github.com/repos/PapilotAI/papilot/releases?per_page=100', fetcher, 4 * 1024 * 1024);
-  if (!Array.isArray(releases)) throw new Error('Invalid release information.');
-  let latest: { version: string; downloadUrl: string } | null = null;
-  for (const release of releases) {
-    const version = typeof release.tag_name === 'string' ? release.tag_name.replace(/^v/, '') : '';
-    if (release.draft !== false || release.prerelease !== false || !stableVersion(version) || !Array.isArray(release.assets)) continue;
-    const names = platform === 'darwin' && ['arm64', 'x64'].includes(arch) ? [`Papilot-${version}-mac-${arch}.dmg`, `Papilot-${version}-mac-${arch}.zip`]
-      : platform === 'linux' && ['arm64', 'x64'].includes(arch) ? [`Papilot-${version}-linux-${arch === 'x64' ? 'x86_64' : arch}.AppImage`, `Papilot-${version}-linux-${arch === 'x64' ? 'amd64' : arch}.deb`] : [];
-    if (!release.assets.some((asset: any) => asset.state === 'uploaded' && asset.size > 0 && names.includes(asset.name))) continue;
-    if (!latest || newerVersion(version, latest.version)) latest = { version, downloadUrl: `${DESKTOP_RELEASES}/tag/${release.tag_name}` };
-  }
-  return latest;
+// Nightly builds of main replace the assets of this one prerelease.
+export const DESKTOP_DEV_TAG = 'desktop-dev';
+// Release downloads, not the rate-limited REST API. The smoke test serves
+// them locally.
+const desktopDownloads = () => (process.env.PAPILOT_DESKTOP_UPDATE_SOURCE ? process.env.PAPILOT_DESKTOP_UPDATE_SOURCE.replace(/\/+$/, '') + '/PapilotAI/papilot/releases' : DESKTOP_RELEASES);
+export interface DesktopRelease { version: string; downloadUrl: string; layer?: DesktopLayer }
+// desktop.json (written by scripts/desktop-layer.mjs, uploaded after every
+// other asset of its release) names the version, its update layer and the
+// installer shell that layer runs on. Stable: the latest release. Dev: the
+// latest nightly build of main. The layer is offered only to that shell.
+export async function latestDesktopRelease(fetcher = fetch, channel: UpdateChannel = 'stable', fingerprint = ''): Promise<DesktopRelease | null> {
+  const folder = channel === 'dev' ? `download/${DESKTOP_DEV_TAG}` : 'latest/download';
+  let manifest: any;
+  try {
+    const bytes = await download(`${desktopDownloads()}/${folder}/desktop.json`, fetcher, 64 * 1024, true);
+    if (!bytes) return null;
+    manifest = JSON.parse(bytes.toString('utf8'));
+  } catch { throw new Error('Could not check for updates.'); }
+  const version = manifest?.version;
+  if (manifest?.format !== 1 || (channel === 'dev' ? !devRevision(version) : !stableVersion(version))) throw new Error('Invalid release information.');
+  const tag = channel === 'dev' ? DESKTOP_DEV_TAG : `v${version}`, layer = manifest.layer;
+  const usable = fingerprint && manifest.fingerprint === fingerprint && typeof layer?.name === 'string' && /^papilot-app-[\w.-]+\.tgz$/.test(layer.name)
+    && Number.isSafeInteger(layer.size) && layer.size > 0 && /^[a-f0-9]{64}$/.test(layer.sha256);
+  return { version, downloadUrl: `${DESKTOP_RELEASES}/tag/${tag}`,
+    ...(usable ? { layer: { url: `${desktopDownloads()}/download/${tag}/${layer.name}`, size: layer.size, sha256: layer.sha256 } } : {}) };
 }
 const validTarget = (version: unknown, channel: UpdateChannel): version is string => channel === 'dev' ? Boolean(devRevision(version)) : stableVersion(version);
 const available = (next: string, current: string, channel: UpdateChannel) => validTarget(next, channel)
   && (channel === 'dev' || devRevision(current) ? next !== current : newerVersion(next, current));
 interface Options {
   desktop?: boolean;
-  latestDesktop?: () => Promise<{ version: string; downloadUrl: string } | null>;
+  // A packaged desktop app: its bundled server and shell fingerprint.
+  bundle?: { root: string; version: string; fingerprint: string };
+  latestDesktop?: (channel: UpdateChannel) => Promise<DesktopRelease | null>;
+  installLayer?: (data: string, version: string, layer: DesktopLayer, bundle: { root: string; fingerprint: string }) => Promise<string>;
   root: string; data: string; version: string; port: number;
   busy: () => boolean; shutdown: () => void;
   latest?: (channel: UpdateChannel) => Promise<string | Record<string, any>>; install?: (data: string, version: string) => Promise<string>;
@@ -70,15 +83,23 @@ export class Updates {
   private file: string;
   private lock: string;
   private channel: UpdateChannel;
-  private downloadUrl = DESKTOP_RELEASES;
+  private channelFile: string;
+  // Desktop: the release page when the update needs a new installer.
+  private downloadUrl?: string;
+  private target: DesktopRelease | null = null;
+  // Only packaged desktop apps install layers; the development app links to releases.
+  private layers: boolean;
   constructor(private options: Options) {
-    this.file = path.join(options.data, options.desktop ? 'updates/desktop/status.json' : 'updates/status.json'); this.lock = path.join(options.data, 'updates/install.lock');
-    const preference = readJson(path.join(options.data, 'updates/channel.json'))?.channel;
-    this.channel = options.desktop ? 'stable' : preference === 'dev' || preference === 'stable' ? preference : devRevision(options.version) ? 'dev' : 'stable';
-    let supported = options.desktop ? false : options.supported ?? true;
+    const folder = path.join(options.data, options.desktop ? 'updates/desktop' : 'updates');
+    this.file = path.join(folder, 'status.json'); this.lock = path.join(folder, 'install.lock'); this.channelFile = path.join(folder, 'channel.json');
+    this.layers = Boolean(options.desktop && options.bundle?.fingerprint);
+    if (options.desktop && !this.layers) this.downloadUrl = DESKTOP_RELEASES;
+    const preference = readJson(this.channelFile)?.channel;
+    this.channel = options.desktop && !this.layers ? 'stable' : preference === 'dev' || preference === 'stable' ? preference : devRevision(options.version) ? 'dev' : 'stable';
+    let supported = options.desktop ? this.layers : options.supported ?? true;
     if (!options.desktop && options.supported === undefined) try { npmCli(); } catch { supported = false; }
     this.state = { currentVersion: options.version, latestVersion: null, phase: 'idle', checkedAt: null, error: null, canUpdate: supported };
-    const saved = options.desktop ? null : readJson(this.file);
+    const saved = options.desktop && !this.layers ? null : readJson(this.file);
     if (saved && ['failed', 'updated', 'installing', 'waiting', 'restarting'].includes(saved.phase)) this.state = { ...this.state, ...saved, currentVersion: options.version, canUpdate: supported };
     if (saved && activePhases.has(saved.phase) && !alive(saved.pid)) this.change({ phase: 'failed', checkedAt: Date.now(), error: 'The update was interrupted. Your current installation is still available; retry the update.' });
   }
@@ -86,8 +107,8 @@ export class Updates {
     const saved = readJson(this.file);
     if (saved && activePhases.has(this.state.phase) && ['updated', 'failed'].includes(saved.phase)) this.state = { ...this.state, ...saved, currentVersion: this.options.version };
     const { currentVersion, latestVersion, phase, checkedAt, error, canUpdate } = this.state, desktop = this.options.desktop;
-    if (desktop) return { currentVersion, latestVersion, phase, checkedAt, error, channel: 'stable', canUpdate: false, downloadUrl: this.downloadUrl };
-    return { currentVersion, latestVersion, phase, checkedAt, error, canUpdate, channel: this.channel };
+    if (desktop && !this.layers) return { currentVersion, latestVersion, phase, checkedAt, error, canUpdate: false, downloadUrl: this.downloadUrl };
+    return { currentVersion, latestVersion, phase, checkedAt, error, canUpdate, channel: this.channel, ...(this.downloadUrl ? { downloadUrl: this.downloadUrl } : {}) };
   }
   get restarting() { return this.snapshot().phase === 'restarting'; }
   enter() { this.inFlight++; let released = false; return () => { if (!released) { released = true; this.inFlight--; } }; }
@@ -104,13 +125,14 @@ export class Updates {
     writeJson(this.file, { ...this.state, pid: process.pid });
   }
   setChannel(channel: unknown) {
-    if (this.options.desktop) throw new Error('Download desktop updates from GitHub Releases.');
+    if (this.options.desktop && !this.layers) throw new Error('Download desktop updates from GitHub Releases.');
     if (channel !== 'stable' && channel !== 'dev') throw new Error('Choose a valid update channel.');
     if (activePhases.has(this.state.phase)) throw new Error('Wait for the current update to finish before changing channels.');
     if (channel === this.channel) return this.check();
     this.channel = channel;
-    writeJson(path.join(this.options.data, 'updates/channel.json'), { channel });
-    this.checking = null;
+    writeJson(this.channelFile, { channel });
+    this.checking = null; this.target = null;
+    if (this.layers) this.downloadUrl = undefined;
     this.change({ latestVersion: null, checkedAt: null, phase: 'idle', error: null });
     return this.check();
   }
@@ -119,12 +141,12 @@ export class Updates {
     if (activePhases.has(this.state.phase)) return Promise.resolve(this.snapshot());
     this.change({ phase: 'checking' });
     const channel = this.channel;
-    const discovery = this.options.desktop ? (this.options.latestDesktop || latestDesktopRelease)() : (this.options.latest || latestManifest)(channel);
+    const discovery = this.options.desktop ? this.desktopRelease(channel) : (this.options.latest || latestManifest)(channel);
     const checking = discovery.then(found => {
       const manifest = typeof found === 'string' ? { version: found } : found;
       if (!manifest && this.options.desktop) {
-        if (!this.closed && this.checking === checking) {
-          this.downloadUrl = DESKTOP_RELEASES;
+        if (!this.closed && this.checking === checking && !activePhases.has(this.state.phase)) {
+          this.target = null; this.downloadUrl = this.layers ? undefined : DESKTOP_RELEASES;
           this.change({ latestVersion: null, checkedAt: Date.now(), error: null, phase: 'idle' });
         }
         return this.snapshot();
@@ -133,7 +155,12 @@ export class Updates {
       if (!validTarget(version, channel)) throw new Error('Invalid release version.');
       if (!this.closed && this.checking === checking && !activePhases.has(this.state.phase)) {
         const newer = available(version, this.options.version, channel);
-        if (this.options.desktop) this.downloadUrl = manifest!.downloadUrl;
+        if (this.options.desktop) {
+          const release = manifest as DesktopRelease, bundled = version === this.options.bundle?.version;
+          // A layer for this shell, or the installer's own server, installs in place.
+          this.target = this.layers && newer && (release.layer || bundled) ? release : null;
+          this.downloadUrl = this.layers ? newer && !this.target ? release.downloadUrl : undefined : release.downloadUrl;
+        }
         this.change({ latestVersion: version, checkedAt: Date.now(), error: null, phase: newer ? 'available' : 'idle' });
       }
       return this.snapshot();
@@ -144,9 +171,23 @@ export class Updates {
     this.checking = checking;
     return this.checking;
   }
+  private desktopRelease(channel: UpdateChannel) {
+    return (this.options.latestDesktop || (channel => latestDesktopRelease(fetch, channel, this.options.bundle?.fingerprint)))(channel);
+  }
+  // A retry after a restart finds the release again; the check that offered it
+  // happened in the previous process.
+  private async desktopLayer(version: string) {
+    const bundle = this.options.bundle!;
+    if (version === bundle.version) return bundle.root;
+    let release = this.target;
+    if (release?.version !== version) release = await this.desktopRelease(this.channel);
+    if (release?.version !== version || !release.layer) throw new Error('Check for a newer release before updating.');
+    return (this.options.installLayer || installLayer)(this.options.data, version, release.layer, bundle);
+  }
   install(version: unknown) {
-    if (this.options.desktop) throw new Error('Download desktop updates from GitHub Releases.');
+    if (this.options.desktop && !this.layers) throw new Error('Download desktop updates from GitHub Releases.');
     if (activePhases.has(this.state.phase)) return this.snapshot();
+    if (this.options.desktop && this.downloadUrl) throw new Error('Download desktop updates from GitHub Releases.');
     if (!this.state.canUpdate) throw new Error('npm is unavailable to Papilot.');
     if (!validTarget(version, this.channel) || version !== this.state.latestVersion || !available(version, this.options.version, this.channel)) throw new Error('Check for a newer release before updating.');
     fs.mkdirSync(path.dirname(this.lock), { recursive: true, mode: 0o700 });
@@ -155,7 +196,9 @@ export class Updates {
     if (previous) fs.rmSync(this.lock);
     const fd = fs.openSync(this.lock, 'wx', 0o600); fs.writeFileSync(fd, JSON.stringify({ pid: process.pid })); fs.closeSync(fd);
     this.change({ phase: 'installing', error: null });
-    void (this.options.install || installRelease)(this.options.data, version).then(root => {
+    // Returning to the installer's own version needs no download.
+    const installing = this.options.desktop ? this.desktopLayer(version) : (this.options.install || installRelease)(this.options.data, version);
+    void installing.then(root => {
       if (this.closed) return;
       this.prepared = root; this.change({ phase: 'waiting' });
       return this.activate();

package/src/server/workspace.ts

@@ -12,7 +12,7 @@ import { Codex, RpcResponseError } from './codex.ts';
 import { AGENT_NAMES, AntigravityAgent, ClaudeAgent, GlmAgent, type AgentRuntime } from './agents.ts';
 import { ACP_PROFILES, AcpAgent } from './acp.ts';
 import { CursorAgent } from './cursor.ts';
-import { reviewClient, taskRoute, confirmedReviewResponse, type ReviewClient } from './review.ts';
+import { reviewClient, reviewConnectionError, taskRoute, confirmedReviewResponse, type ReviewClient } from './review.ts';
 import { VERSION } from './paths.ts';
 import { prepareRepository } from './imports.ts';
 import { findSkill, type SkillFile } from './skills.ts';
@@ -668,6 +668,7 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   async reconcile(taskId: string) {
     const task = this.store.task(taskId);
     if (task.status === 'deleting') throw new Error('Retry deletion to confirm this task was removed.');
+    if (task.pendingBuild && !task.pendingReview) { void this.resumeBuild(taskId); return this.store.task(taskId); }
     if (task.status !== 'uncertain') return task;
     if (task.pendingReview) return this.reconcileReview(task);
     const run = this.active.get(taskId) || this.store.runs().find(r => r.id === task.pendingRunId && r.taskId === taskId);
@@ -752,40 +753,100 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
     if (this.reviewWrites.has(taskId)) throw new Error('Wait for the current review action before building a review.');
     if (this.publishing.has(taskId) || (!automatic && (BUSY.has(task.status) || task.status === 'queued'))) throw new Error('This task is busy. Wait for it to finish or pause it first.');
     this.publishing.add(taskId);
-    this.store.updateTask(taskId, { status: 'building', error: null });
-    return this.buildReview(task, Boolean(after && !after.requestKey.startsWith(BUILD_FIX)), after?.id).finally(() => { this.publishing.delete(taskId); this.schedule(); });
+    const runs = this.store.runs().filter(run => run.taskId === taskId && run.status === 'completed' && (run.reviewRound === 0 || (run.reviewRound === undefined && run.id === after?.id))).map(run => run.id);
+    this.store.updateTask(taskId, { status: 'building', error: null, pendingBuild: { requestId: randomUUID(), runs, sendBack: Boolean(after && !after.requestKey.startsWith(BUILD_FIX)), restarts: 0 } });
+    return this.buildReview(task).finally(() => { this.publishing.delete(taskId); this.schedule(); });
   }
-  private async buildReview(task: Task, sendBack: boolean, after?: string) {
+  // Resume a persisted job, including jobs saved by versions before pendingBuild.
+  async resumeBuild(taskId: string) {
+    const task = this.store.task(taskId);
+    if (this.closing || this.publishing.has(taskId) || task.mode === 'review' || task.pendingReview || this.active.has(taskId)
+      || !['building', 'failed', 'interrupted', 'uncertain'].includes(task.status)) return false;
+    let pending = task.pendingBuild;
+    if (!pending) {
+      const job = task.review?.job;
+      if (!job?.id || !['running', 'queued'].includes(job.status)
+        || (task.status !== 'building' && !/fetch failed|server restarted during the PDF build/i.test(task.error || ''))) return false;
+      pending = { requestId: randomUUID(), job: job.id, runs: this.store.runs().filter(run => run.taskId === taskId && run.status === 'completed' && run.reviewRound === 0).map(run => run.id), sendBack: false, restarts: 0 };
+    }
+    this.publishing.add(taskId);
+    this.store.updateTask(taskId, { status: 'building', error: null, pendingBuild: pending });
+    try { await this.buildReview(task, true); }
+    finally { this.publishing.delete(taskId); this.schedule(); }
+    return true;
+  }
+  private async buildReview(task: Task, resume = false) {
     const taskId = task.id;
-    const unlinked = this.store.runs().filter(run => run.taskId === taskId && run.status === 'completed' && (run.reviewRound === 0 || (run.reviewRound === undefined && run.id === after))).map(run => run.id);
+    let pending = this.store.task(taskId).pendingBuild!;
+    let client: ReviewClient | undefined;
+    let reuse = resume;
+    // Only connection failures are retried. Every submission has a persisted key,
+    // so losing its response cannot submit a second build.
+    const request = async <T>(work: (client: ReviewClient) => Promise<T>, submitting = false): Promise<T> => {
+      for (let attempt = 0; ; attempt++) {
+        if (this.closing) throw new Error();
+        try {
+          client ??= await this.connectReview(this.store.project(task.projectId).path, reuse);
+          const value = await work(client);
+          if (this.closing) throw new Error();
+          return value;
+        } catch (error) {
+          if (this.closing || !reviewConnectionError(error) || attempt >= 3) throw error;
+          console.warn('PDF comparison connection interrupted:', task.name, pending.job || pending.requestId, error);
+          client = undefined; reuse = !submitting;
+          await delay(1500 * 2 ** attempt);
+        }
+      }
+    };
     try {
-      const client = await this.connectReview(this.store.project(task.projectId).path);
-      const job = await client.post(`${taskRoute(task.name)}/publish`, {});
       for (;;) {
         if (this.closing) return;
-        const current = await client.get(`/api/jobs/${job.job}`);
-        const summary = await client.get(taskRoute(task.name));
-        this.store.updateTask(taskId, { review: { ...this.store.task(taskId).review, state: summary.state, round: summary.round, counts: summary.counts, job: current } });
+        if (!pending.job) {
+          // New writes require our engine version, which understands request IDs.
+          // Read-only recovery may have connected to an older installed engine.
+          client = undefined; reuse = false;
+          const job = await request(client => client.post<{ job: string }>(`${taskRoute(task.name)}/publish`, { requestId: pending.requestId }), true);
+          pending = { ...pending, job: job.job };
+          this.store.updateTask(taskId, { pendingBuild: pending });
+        }
+        const current = await request(client => client.get(`/api/jobs/${pending.job}`));
+        const summary = await request(client => client.get(taskRoute(task.name)));
+        this.store.updateTask(taskId, { review: { ...this.store.task(taskId).review, state: summary.state, round: summary.round, counts: summary.counts, job: { ...current, id: pending.job } } });
         if (current.status === 'done' || current.status === 'completed' || current.status === 'succeeded') {
           // Freeze the result round for these instructions. Later follow-ups
           // have their own results and cannot silently replace these links.
-          for (const run of this.store.runs().filter(run => unlinked.includes(run.id))) this.store.saveRun({ ...run, reviewRound: current.outcome === 'empty' || current.outcome === 'unchanged' ? null : current.round ?? summary.round ?? null });
+          this.store.transaction(() => {
+            for (const run of this.store.runs().filter(run => pending.runs.includes(run.id))) this.store.saveRun({ ...run, reviewRound: current.outcome === 'empty' || current.outcome === 'unchanged' ? null : current.round ?? summary.round ?? null });
+            this.store.updateTask(taskId, { status: this.store.runs().some(r => r.taskId === taskId && r.status === 'queued') ? 'queued' : 'reviewing', error: null, pendingBuild: null });
+          });
           break;
         }
         if (current.status === 'failed') {
+          if (current.error === 'The review server restarted during the build.' && pending.restarts < 1) {
+            pending = { ...pending, job: undefined, requestId: randomUUID(), restarts: pending.restarts + 1 };
+            this.store.updateTask(taskId, { pendingBuild: pending });
+            continue;
+          }
           const failure: BuildFailure = { error: current.error || 'PDF build failed.', details: current.details || [], ...(current.log ? { log: current.log } : {}) };
           // Instructions the author queued meanwhile go first; the build after them sends any error that remains.
-          if (sendBack && FIXABLE.test(failure.error) && await this.enqueue(taskId, '', BUILD_FIX + job.job, false, { build: failure }).then(() => true, () => false)) {
-            this.store.updateTask(taskId, { status: 'queued', error: null });
+          if (pending.sendBack && FIXABLE.test(failure.error) && await this.enqueue(taskId, '', BUILD_FIX + pending.job, false, { build: failure }).then(() => true, () => false)) {
+            this.store.updateTask(taskId, { status: 'queued', error: null, pendingBuild: null });
             return;
           }
           throw new Error([failure.error, ...failure.details].join('\n'));
         }
         await delay(1500);
       }
-      this.store.updateTask(taskId, { status: this.store.runs().some(r => r.taskId === taskId && r.status === 'queued') ? 'queued' : 'reviewing', error: null });
       await this.refresh(taskId);
-    } catch (e) { this.store.updateTask(taskId, { status: 'failed', error: errorText(e) }); }
+    } catch (e) {
+      if (this.closing) return;
+      if (reviewConnectionError(e)) {
+        console.warn('PDF comparison recovery pending:', task.name, pending.job || pending.requestId, e);
+        this.store.updateTask(taskId, { status: 'uncertain', pendingBuild: pending,
+          error: 'The PDF comparison service could not be reached. Your edits are saved. Select Check status to recover the existing build.' });
+      }
+      else this.store.updateTask(taskId, { status: 'failed', pendingBuild: null, error: errorText(e) });
+    }
   }
   private finishAiReview(task: Task, run: Run, turnId: string) {
     try {

package/src/shared.ts

@@ -19,7 +19,8 @@ export interface UpdateStatus {
 // unsent counts review updates the agent has not received; comments are the
 // ones that ask for a revision. files are the manuscript files this task's
 // accepted changes touched since its last commit, relative to the repository root.
-export interface ReviewSummary { state: string; round: number | null; counts: Record<string, number>; unsent?: number; comments?: number; files?: string[]; next?: string; job?: { phase: string; status: string; error?: string; details?: string[] } | null }
+export interface ReviewSummary { state: string; round: number | null; counts: Record<string, number>; unsent?: number; comments?: number; files?: string[]; next?: string; job?: { id?: string; phase: string; status: string; error?: string; details?: string[] } | null }
+export interface PendingBuild { requestId: string; job?: string; runs: string[]; sendBack: boolean; restarts: number }
 export interface PendingReview { route: string; body: Record<string, unknown>; previousStatus: TaskStatus }
 export interface TaskCommitReview { token: string; files: string[]; diff: string }
 export interface TaskReconciliation {
@@ -44,6 +45,8 @@ export interface Task {
   error: string | null; review: ReviewSummary | null;
   pauseVersion?: number; pendingRunId?: string | null;
   pendingReview?: PendingReview | null;
+  // Persist before submission so reconnects resume the same build and run links.
+  pendingBuild?: PendingBuild | null;
   // The task's last commit from its review, and the accepted text it included.
   committed?: { hash: string; accepted: string; at: number; pushed?: boolean } | null;
 }
@@ -113,7 +116,8 @@ export interface Person { id: string; name: string; role: 'owner' | 'member'; jo
 export interface Device { id: string; kind: 'passkey' | 'session'; label: string; createdAt: number; lastUsedAt: number | null }
 export interface People { origin: string | null; people: Person[] }
 // staged: the index has changes to this file; unstaged: the working tree has more.
-export interface GitFile { path: string; status: string; staged: boolean; unstaged: boolean; lines?: [number, number]; from?: string }
+// index is the staged status where it differs from status, which is the working tree's when it has changes.
+export interface GitFile { path: string; status: string; staged: boolean; unstaged: boolean; lines?: [number, number]; from?: string; index?: string }
 // merging is a merge in progress, with the files whose conflict markers remain.
 export interface GitStatus { branch: string | null; upstream: string | null; ahead: number; behind: number; files: GitFile[]; head: { hash: string; subject: string; date: number } | null; remote?: boolean; merging?: { message: string; conflicts: string[] } | null }
 export interface GitDiff { path: string; diff: string; truncated: boolean }
@@ -122,7 +126,8 @@ export interface GitWorktree {
   locked?: string; prunable?: string; status: GitStatus | null; error?: string;
   taskId?: string;
 }
-export interface GitGraphCommit { hash: string; parents: string[]; subject: string; author: string; date: number; refs: string[] }
+// refs are local branches; remote branches and tags are listed apart, as an editor's graph shows them.
+export interface GitGraphCommit { hash: string; parents: string[]; subject: string; author: string; date: number; refs: string[]; remotes?: string[]; tags?: string[] }
 export interface GitOverview { worktrees: GitWorktree[]; commits: GitGraphCommit[]; truncated: boolean }
 // A running compilation, from latexmk's output: its step, the TeX pass, and
 // the pages typeset in that pass against the last known page count.