papilot 0.6.0 → 0.8.0

package/src/server/skills.ts

@@ -1,47 +1,57 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { DATA, ROOT } from './paths.ts';
+import os from 'node:os';
+import { ROOT } from './paths.ts';
 import type { Skill } from '../shared.ts';
+import { isSkillIcon } from '../skill-icons.ts';
+import { skillMetadata, skillInstructions } from '../skill-metadata.ts';
 
 // Skills are Markdown instructions an author runs with "/" in the composer.
-// Papilot ships some in skills/; the data folder's skills/ adds the author's
+// Papilot ships some in skills/; ~/.papilot/skills/ adds the author's
 // own for every paper, and a paper's .papilot/skills/ its own. A later source
 // replaces an earlier skill with the same name. Each skill is <name>.md, or a
 // folder with a SKILL.md (the Agent Skills layout) whose other files the
 // agent may read. Front matter gives its name, description, composer hint
 // and order.
 export interface SkillFile extends Skill { body: string; folder?: string; order: number }
-const NAME = /^[a-z0-9][a-z0-9-]{0,47}$/;
+export const SKILL_NAME = /^[a-z0-9][a-z0-9-]{0,47}$/;
+// Global authoring tools belong to the user, independently of the database or
+// a temporary demo's PAPILOT_DATA directory.
+export const skillRoots = { builtin: path.join(ROOT, 'skills'), user: path.join(os.homedir(), '.papilot', 'skills') };
+
+// Both the composer and the library address the same files, including legacy
+// <name>.md files. New skills use the portable <name>/SKILL.md layout.
+export function skillFiles(dir: string): { id: string; file: string; folder?: string }[] {
+  let entries: fs.Dirent[];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  return entries.sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
+    const id = entry.name.replace(/\.md$/i, '').toLowerCase();
+    if (!SKILL_NAME.test(id)) return [];
+    const folder = path.join(dir, entry.name);
+    return entry.isDirectory() ? [{ id, file: path.join(folder, 'SKILL.md'), folder }]
+      : entry.isFile() && /\.md$/i.test(entry.name) ? [{ id, file: folder }] : [];
+  });
+}
 
 export function parseSkill(text: string, id: string, source: Skill['source'], folder?: string): SkillFile | null {
   text = text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
-  const header = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(text), fields: Record<string, string> = {};
-  for (const line of header?.[1].split('\n') || []) {
-    const field = /^([A-Za-z-]+):\s*(.*)$/.exec(line);
-    if (field) fields[field[1].toLowerCase()] = field[2].trim().replace(/^(['"])(.*)\1$/, '$2');
-  }
-  const body = text.slice(header ? header[0].length : 0).trim().slice(0, 20000);
+  const fields = skillMetadata(text), body = skillInstructions(text).trim().slice(0, 20000);
   if (!body) return null;
-  return { id, name: (fields.name || id).slice(0, 60), description: (fields.description || '').slice(0, 300), hint: (fields.hint || '').slice(0, 200), source, body, ...(folder ? { folder } : {}), order: fields.order && Number.isFinite(Number(fields.order)) ? Number(fields.order) : 1000 };
+  return { id, name: (fields.name || id).slice(0, 60), description: (fields.description || '').slice(0, 300), hint: (fields.hint || '').slice(0, 200), ...(isSkillIcon(fields.icon) ? { icon: fields.icon } : {}), source, body, ...(fields.output === 'annotations' ? { output: 'annotations' as const } : {}), ...(folder ? { folder } : {}), order: fields.order && Number.isFinite(Number(fields.order)) ? Number(fields.order) : 1000 };
 }
 
 function read(dir: string, source: Skill['source']): SkillFile[] {
-  let entries: fs.Dirent[];
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
   const found: SkillFile[] = [];
-  for (const entry of entries) {
-    const id = entry.name.replace(/\.md$/i, '').toLowerCase();
-    if (!NAME.test(id)) continue;
+  for (const { id, file, folder } of skillFiles(dir)) {
     try {
-      const skill = entry.isDirectory() ? parseSkill(fs.readFileSync(path.join(dir, entry.name, 'SKILL.md'), 'utf8'), id, source, path.join(dir, entry.name))
-        : entry.isFile() && /\.md$/i.test(entry.name) ? parseSkill(fs.readFileSync(path.join(dir, entry.name), 'utf8'), id, source) : null;
+      const skill = parseSkill(fs.readFileSync(file, 'utf8'), id, source, folder);
       if (skill) found.push(skill);
     } catch { /* A folder without a readable SKILL.md is not a skill. */ }
   }
   return found;
 }
 
-export function loadSkills(paper?: string, roots = { builtin: path.join(ROOT, 'skills'), user: path.join(DATA, 'skills') }): SkillFile[] {
+export function loadSkills(paper?: string, roots = skillRoots): SkillFile[] {
   const skills = new Map<string, SkillFile>();
   const sources: [string, Skill['source']][] = [[roots.builtin, 'builtin'], [roots.user, 'user'], ...(paper ? [[path.join(paper, '.papilot', 'skills'), 'paper'] as [string, Skill['source']]] : [])];
   for (const [dir, source] of sources) for (const skill of read(dir, source)) skills.set(skill.id, skill);
@@ -54,4 +64,4 @@ export function findSkill(paper: string, id: string) {
   return skill;
 }
 
-export const listedSkill = ({ id, name, description, hint, source }: SkillFile): Skill => ({ id, name, description, hint, source });
+export const listedSkill = ({ id, name, description, hint, source, icon, output }: SkillFile): Skill => ({ id, name, description, hint, source, ...(icon ? { icon } : {}), ...(output ? { output } : {}) });

package/src/server/start.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { Store } from './store.ts';
+import { Workspace } from './workspace.ts';
+import { Accounts } from './accounts.ts';
+import { ROOT, DATA, PORT, PUBLIC_ORIGIN, OWNER, VERSION, ACCOUNT_ORIGIN, ACCOUNT_PORT } from './paths.ts';
+import { accountHsts, accountProblem } from './security.ts';
+import { Manuscripts } from './manuscript.ts';
+import { Changes } from './changes.ts';
+import { buildApp, gitQueue } from './app.ts';
+import { Updates } from './updates.ts';
+import { readJson } from '../../bin/installation.mjs';
+
+const problem = accountProblem(ACCOUNT_ORIGIN, ACCOUNT_PORT, PORT, PUBLIC_ORIGIN);
+if (problem) { console.error(problem); process.exit(1); }
+const store = new Store(path.join(DATA, 'papilot.sqlite'));
+const workspace = new Workspace(store);
+const accounts = new Accounts(store, ACCOUNT_ORIGIN || null);
+const manuscripts = new Manuscripts(), changes = new Changes();
+const updates = new Updates({ root: ROOT, data: DATA, version: VERSION, port: PORT, busy: () => workspace.busyForUpdate || manuscripts.busyForUpdate || changes.busyForUpdate, shutdown: () => shutdown() });
+const activation = readJson(path.join(DATA, 'updates/active.json'));
+const updateInstance = typeof activation?.root === 'string' && fs.existsSync(activation.root) && fs.realpathSync(activation.root) === fs.realpathSync(ROOT) ? activation.id : undefined;
+const shared = {
+  store, workspace, accounts, manuscripts, changes, updates, updateInstance, csrf: randomBytes(32).toString('base64url'), serialGit: gitQueue(),
+  dist: fs.existsSync(path.join(ROOT, 'dist/index.html')) ? path.join(ROOT, 'dist') : null, version: VERSION,
+};
+const apps = [await buildApp({ ...shared, listener: { kind: 'local', port: PORT, publicOrigin: PUBLIC_ORIGIN, owner: OWNER } })];
+if (ACCOUNT_ORIGIN) apps.push(await buildApp({ ...shared, listener: { kind: 'account', origin: ACCOUNT_ORIGIN, hsts: accountHsts(ACCOUNT_ORIGIN, PUBLIC_ORIGIN) } }));
+
+await apps[0].listen({ host: '127.0.0.1', port: PORT });
+if (apps[1]) await apps[1].listen({ host: '127.0.0.1', port: ACCOUNT_PORT });
+store.recover();
+console.log(`Papilot is running at http://127.0.0.1:${PORT}${PUBLIC_ORIGIN ? `\nRemote: ${PUBLIC_ORIGIN}` : ''}${ACCOUNT_ORIGIN ? `\nSign-in for invited people: ${ACCOUNT_ORIGIN} (forwarded to 127.0.0.1:${ACCOUNT_PORT})` : ''}`);
+if (!process.env.PAPILOT_UPDATE_PROBE) { void workspace.connect(); updates.start(); }
+// Recompute cached feedback counts, including decisions from before this restart.
+for (const task of store.tasks()) {
+  if (task.status === 'building') {
+    store.updateTask(task.id, { status: 'interrupted', error: 'The server restarted during the PDF build. Check the review and rebuild it if needed.' });
+    void workspace.refresh(task.id);
+  } else if (task.review?.round && task.status !== 'deleting') void workspace.refresh(task.id);
+}
+// Expired invites and sessions are removed as they lapse.
+setInterval(() => accounts.purge(), 3600000).unref();
+let shuttingDown = false;
+function shutdown() {
+  if (shuttingDown) return; shuttingDown = true; updates.close(); workspace.close();
+  void Promise.all(apps.map(app => app.close())).finally(() => { store.close(); process.exit(0); });
+  setTimeout(() => process.exit(0), 2500).unref();
+}
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, shutdown);

package/src/server/store.ts

@@ -1,3 +1,4 @@
+import type { ReviewSnapshot } from './ai-review.ts';
 import { DatabaseSync } from 'node:sqlite';
 import { EventEmitter } from 'node:events';
 import fs from 'node:fs';
@@ -6,7 +7,7 @@ import type { Annotation, Project, Task, Run, TimelineItem } from '../shared.ts'
 
 export class Store extends EventEmitter {
   db: DatabaseSync;
-  constructor(file: string) {
+  constructor(public readonly file: string) {
     super();
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     this.db = new DatabaseSync(file);
@@ -16,12 +17,15 @@ export class Store extends EventEmitter {
       CREATE TABLE IF NOT EXISTS runs(id TEXT PRIMARY KEY, task_id TEXT NOT NULL, request_key TEXT UNIQUE NOT NULL, status TEXT NOT NULL, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS items(id TEXT PRIMARY KEY, task_id TEXT NOT NULL, created INTEGER NOT NULL, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS deleted_tasks(id TEXT PRIMARY KEY, deleted INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS ai_review_inputs(task_id TEXT PRIMARY KEY, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS annotations(id TEXT PRIMARY KEY, project_id TEXT NOT NULL, data TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS attachments(id TEXT PRIMARY KEY, project_id TEXT NOT NULL, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS users(id TEXT PRIMARY KEY, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS credentials(id TEXT PRIMARY KEY, user_id TEXT NOT NULL, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS invites(token_hash TEXT PRIMARY KEY, user_id TEXT NOT NULL, expires INTEGER NOT NULL, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS sessions(token_hash TEXT PRIMARY KEY, id TEXT UNIQUE NOT NULL, user_id TEXT NOT NULL, expires INTEGER NOT NULL, data TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS members(project_id TEXT NOT NULL, user_id TEXT NOT NULL, PRIMARY KEY(project_id, user_id));
+      CREATE TABLE IF NOT EXISTS migrations(key TEXT PRIMARY KEY, done INTEGER NOT NULL);
       CREATE INDEX IF NOT EXISTS task_items ON items(task_id,created);
       CREATE INDEX IF NOT EXISTS task_runs ON runs(task_id,status);`);
   }
@@ -33,32 +37,68 @@ export class Store extends EventEmitter {
   task(id: string) { const row = this.db.prepare('SELECT data FROM tasks WHERE id=?').get(id) as { data: string } | undefined; if (!row) throw new Error('Task not found.'); return JSON.parse(row.data) as Task; }
   projectByPath(p: string) { return this.projects().find(project => project.path === p); }
   saveProject(p: Project) { this.db.prepare('INSERT INTO projects VALUES(?,?,?) ON CONFLICT(id) DO UPDATE SET path=excluded.path,data=excluded.data').run(p.id, p.path, JSON.stringify(p)); this.emit('change'); }
+  removeProject(id: string) {
+    this.project(id);
+    this.transaction(() => {
+      // Only Papilot records are removed. Never finish review tasks or touch their files.
+      this.db.prepare('INSERT OR IGNORE INTO deleted_tasks SELECT id, ? FROM tasks WHERE project_id=?').run(Date.now(), id);
+      for (const table of ['items', 'runs', 'ai_review_inputs']) this.db.prepare(`DELETE FROM ${table} WHERE task_id IN (SELECT id FROM tasks WHERE project_id=?)`).run(id);
+      for (const table of ['tasks', 'annotations', 'members']) this.db.prepare(`DELETE FROM ${table} WHERE project_id=?`).run(id);
+      this.db.prepare('DELETE FROM projects WHERE id=?').run(id);
+    });
+    this.emit('change');
+  }
   saveTask(t: Task) { t.updatedAt = Date.now(); this.db.prepare('INSERT INTO tasks VALUES(?,?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data').run(t.id, t.projectId, JSON.stringify(t)); this.emit('change'); return t; }
   updateTask(id: string, update: Partial<Task>) { return this.saveTask({ ...this.task(id), ...update }); }
   saveRun(r: Run) { this.db.prepare('INSERT INTO runs VALUES(?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET status=excluded.status,data=excluded.data').run(r.id, r.taskId, r.requestKey, r.status, JSON.stringify(r)); this.emit('change'); }
   runByKey(key: string) { const row = this.db.prepare('SELECT data FROM runs WHERE request_key=?').get(key) as { data: string } | undefined; return row ? JSON.parse(row.data) as Run : undefined; }
   items(taskId: string) { return (this.db.prepare('SELECT data FROM items WHERE task_id=? ORDER BY created,rowid').all(taskId) as { data: string }[]).map(r => JSON.parse(r.data) as TimelineItem); }
   saveItem(item: TimelineItem) { this.db.prepare('INSERT INTO items VALUES(?,?,?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data').run(item.id, item.taskId, item.createdAt, JSON.stringify(item)); this.emit('change'); }
-  annotations(projectId: string) { return (this.db.prepare('SELECT data FROM annotations WHERE project_id=? ORDER BY rowid').all(projectId) as { data: string }[]).map(r => JSON.parse(r.data) as Annotation); }
+  saveReviewInput(taskId: string, snapshot: ReviewSnapshot) { this.db.prepare('INSERT INTO ai_review_inputs VALUES(?,?) ON CONFLICT(task_id) DO UPDATE SET data=excluded.data').run(taskId, JSON.stringify(snapshot)); }
+  reviewInput(taskId: string): ReviewSnapshot {
+    const row = this.db.prepare('SELECT data FROM ai_review_inputs WHERE task_id=?').get(taskId) as { data: string } | undefined;
+    if (!row) throw new Error('The PDF snapshot for this review is unavailable. Start a new AI review.');
+    return JSON.parse(row.data);
+  }
+  annotations(projectId: string) { return (this.db.prepare('SELECT data FROM annotations WHERE project_id=? ORDER BY rowid').all(projectId) as { data: string }[]).map(r => JSON.parse(r.data) as Annotation).filter(note => note.deletedAt === undefined); }
+  annotation(projectId: string, id: string) {
+    const row = this.db.prepare('SELECT data FROM annotations WHERE id=? AND project_id=?').get(id, projectId) as { data: string } | undefined;
+    if (!row) throw new Error('Note not found.');
+    return JSON.parse(row.data) as Annotation;
+  }
   saveAnnotation(a: Annotation) { this.db.prepare('INSERT INTO annotations VALUES(?,?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data').run(a.id, a.projectId, JSON.stringify(a)); this.emit('change'); return a; }
-  deleteAnnotation(projectId: string, id: string) { this.db.prepare('DELETE FROM annotations WHERE id=? AND project_id=?').run(id, projectId); this.emit('change'); }
+  deleteAnnotation(projectId: string, id: string) {
+    const note = this.annotation(projectId, id);
+    if (note.taskId) throw new Error('This note has already been sent.');
+    this.saveAnnotation({ ...note, deletedAt: note.deletedAt ?? Date.now() });
+  }
   taskDeleted(id: string) { return Boolean(this.db.prepare('SELECT 1 FROM deleted_tasks WHERE id=?').get(id)); }
   deleteTask(id: string) {
     this.transaction(() => {
       this.db.prepare('INSERT INTO deleted_tasks VALUES(?,?) ON CONFLICT(id) DO NOTHING').run(id, Date.now());
       this.db.prepare('DELETE FROM items WHERE task_id=?').run(id);
       this.db.prepare('DELETE FROM runs WHERE task_id=?').run(id);
+      this.db.prepare('DELETE FROM ai_review_inputs WHERE task_id=?').run(id);
       this.db.prepare('DELETE FROM tasks WHERE id=?').run(id);
     });
     this.emit('change');
   }
+  // Runs a one-off change the first time this database sees its key.
+  migrate(key: string, fn: () => void) {
+    this.transaction(() => {
+      if (this.db.prepare('SELECT 1 FROM migrations WHERE key=?').get(key)) return;
+      fn();
+      this.db.prepare('INSERT INTO migrations VALUES(?,?)').run(key, Date.now());
+    });
+  }
   transaction<T>(fn: () => T): T { this.db.exec('BEGIN IMMEDIATE'); try { const result = fn(); this.db.exec('COMMIT'); return result; } catch (e) { this.db.exec('ROLLBACK'); throw e; } }
   recover() {
     this.transaction(() => {
+      for (const t of this.tasks().filter(t => t.titleGeneration === 'pending')) this.updateTask(t.id, { titleGeneration: 'failed' });
       for (const t of this.tasks().filter(t => t.status === 'deleting')) this.updateTask(t.id, { error: 'The server restarted during deletion. Retry deletion to confirm cleanup.' });
       for (const t of this.tasks().filter(t => t.pendingReview)) this.updateTask(t.id, { status: 'uncertain', error: 'The server restarted before a review action was confirmed. Select Check status before continuing.' });
       for (const r of this.runs().filter(r => r.status === 'running')) this.saveRun({ ...r, status: 'interrupted', finishedAt: Date.now() });
-      for (const t of this.tasks().filter(t => ['running', 'waiting_input'].includes(t.status))) this.updateTask(t.id, { status: 'interrupted', turnId: null, error: 'The server restarted and interrupted the previous turn. Continue in the same conversation.' });
+      for (const t of this.tasks().filter(t => ['running', 'waiting_input'].includes(t.status) || (t.mode === 'review' && t.status === 'building'))) this.updateTask(t.id, { status: 'interrupted', turnId: null, error: 'The server restarted and interrupted the previous turn. Continue in the same conversation.' });
     });
   }
   close() { this.db.close(); }

package/src/server/update-install.ts

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import net from 'node:net';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
+import { devRevision, readJson, stableVersion } from '../../bin/installation.mjs';
+
+export const DEV_REPOSITORY = 'https://github.com/PapilotAI/papilot.git';
+const git = async (args: string[], cwd: string) => (await promisify(execFile)('git', args, { cwd, timeout: 120000, maxBuffer: 1024 * 1024, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })).stdout.trim();
+
+export function npmCli(env = process.env, executable = process.execPath) {
+  const candidates = [env.npm_execpath, path.join(path.dirname(executable), '../lib/node_modules/npm/bin/npm-cli.js'), path.join(path.dirname(executable), 'node_modules/npm/bin/npm-cli.js'),
+    ...(env.PATH || '').split(path.delimiter).map(dir => path.join(dir, 'npm'))];
+  for (const candidate of candidates) {
+    if (!candidate) continue;
+    try { const real = fs.realpathSync(candidate); if (real.endsWith('npm-cli.js')) return real; } catch { /* next installation */ }
+  }
+  throw new Error('npm is unavailable to Papilot.');
+}
+export const loaderFor = (root: string) => createRequire(path.join(root, 'package.json')).resolve('tsx/esm');
+export function runInstall(args: string[], cwd: string, log: number, timeout = 600000) {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn(process.execPath, [npmCli(), ...args], { cwd, env: { ...process.env, PATH: path.dirname(process.execPath) + path.delimiter + (process.env.PATH || '') }, stdio: ['ignore', log, log] });
+    const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('The update download timed out.')); }, timeout);
+    child.once('error', error => { clearTimeout(timer); reject(error); });
+    child.once('exit', code => { clearTimeout(timer); code === 0 ? resolve() : reject(new Error('The new version could not be installed. Check the connection and available disk space, then retry.')); });
+  });
+}
+export async function health(port: number, version: string, instance?: string) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(1500), redirect: 'error' });
+    const value = await response.json();
+    return response.ok && value.name === 'Papilot' && value.version === version && (!instance || value.updateInstance === instance);
+  } catch { return false; }
+}
+export const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+export async function probeInstallation(root: string, version: string, stage: string, log: number) {
+  const server = net.createServer();
+  await new Promise<void>((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const port = (server.address() as net.AddressInfo).port;
+  await new Promise<void>(resolve => server.close(() => resolve()));
+  const child = spawn(process.execPath, ['--import', loaderFor(root), path.join(root, 'src/server/main.ts')], {
+    cwd: root, env: { ...process.env, PAPILOT_DATA: path.join(stage, 'probe'), PAPILOT_PORT: String(port), PAPILOT_PUBLIC_ORIGIN: '', PAPILOT_ACCOUNT_ORIGIN: '', PAPILOT_UPDATE_PROBE: '1' }, stdio: ['ignore', log, log],
+  });
+  let ended = false, error: Error | undefined;
+  child.once('error', e => { error = e; ended = true; }); child.once('exit', () => { ended = true; });
+  try {
+    for (let i = 0; i < 40 && !ended; i++) { if (await health(port, version)) return; await sleep(250); }
+    throw error || new Error('The new version did not pass its startup check. Your current version is still running.');
+  } finally {
+    if (!ended) {
+      child.kill('SIGTERM');
+      for (let i = 0; i < 30 && !ended; i++) await sleep(100);
+      if (!ended) child.kill('SIGKILL');
+    }
+  }
+}
+// Resolve main during discovery, then fetch that exact commit. Building in a
+// managed directory keeps the running installation and any source checkout intact.
+export async function prepareDev(root: string, version: string, log: number, run = runInstall, checkout = git) {
+  const revision = devRevision(version);
+  if (!revision) throw new Error('Invalid development version.');
+  await checkout(['init', '--quiet'], root);
+  await checkout(['-c', 'core.hooksPath=/dev/null', 'fetch', '--depth=1', DEV_REPOSITORY, revision], root);
+  await checkout(['-c', 'core.hooksPath=/dev/null', 'checkout', '--detach', 'FETCH_HEAD'], root);
+  if (await checkout(['rev-parse', 'HEAD'], root) !== revision) throw new Error('The development checkout does not match the requested commit.');
+  const pkg = readJson(path.join(root, 'package.json'));
+  if (pkg?.name !== 'papilot' || !stableVersion(pkg.version) || `${pkg.version}-dev.${revision}` !== version) throw new Error('The development checkout does not match the requested version.');
+  const flags = ['--ignore-scripts', '--no-audit', '--no-fund'];
+  // Test-only tools can exclude a Node version that supports the application.
+  // Build first, then enforce engine compatibility for the retained runtime.
+  await run(['ci', '--include=dev', '--engine-strict=false', ...flags], root, log);
+  const engine = path.join(root, 'vendor/latex-review');
+  await run(['ci', '--include=dev', '--engine-strict=false', ...flags], engine, log);
+  // Only this installed snapshot gets a dev version; the repository stays unchanged.
+  fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify({ ...pkg, version }, null, 2) + '\n');
+  await run(['run', 'build'], engine, log);
+  await run(['run', 'build'], root, log);
+  for (const cwd of [root, engine]) {
+    // npm 10 checks even omitted dev dependencies under --engine-strict, so they
+    // are hidden while pruning. The manifest is then restored: the launcher and
+    // the agents read the tested Codex and Claude SDK versions from it.
+    const manifest = path.join(cwd, 'package.json'), original = fs.readFileSync(manifest, 'utf8');
+    const { devDependencies: _, ...runtime } = JSON.parse(original);
+    fs.writeFileSync(manifest, JSON.stringify(runtime, null, 2) + '\n');
+    try { await run(['prune', '--omit=dev', '--engine-strict', ...flags], cwd, log); }
+    finally { fs.writeFileSync(manifest, original); }
+  }
+}
+async function installDev(data: string, version: string) {
+  const releases = path.join(data, 'updates/releases'); fs.mkdirSync(releases, { recursive: true, mode: 0o700 });
+  const space = fs.statfsSync(releases);
+  if (space.bavail * space.bsize < 2 * 1024 ** 3) throw new Error('The dev build needs at least 2 GB of free disk space. Free some space and retry.');
+  const stage = fs.mkdtempSync(path.join(releases, 'dev-')), root = path.join(stage, 'papilot');
+  fs.mkdirSync(root);
+  const log = fs.openSync(path.join(data, 'updates/install.log'), 'a', 0o600);
+  try {
+    await prepareDev(root, version, log);
+    await probeInstallation(root, version, stage, log);
+    return root;
+  } catch (error) { fs.rmSync(stage, { recursive: true, force: true }); throw error; }
+  finally { fs.closeSync(log); }
+}
+export async function installRelease(data: string, version: string) {
+  if (devRevision(version)) return installDev(data, version);
+  if (!stableVersion(version)) throw new Error('Invalid release version.');
+  const releases = path.join(data, 'updates/releases'); fs.mkdirSync(releases, { recursive: true, mode: 0o700 });
+  const stage = fs.mkdtempSync(path.join(releases, version + '-')), root = path.join(stage, 'node_modules/papilot');
+  const log = fs.openSync(path.join(data, 'updates/install.log'), 'a', 0o600);
+  try {
+    const flags = ['--registry=https://registry.npmjs.org', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--engine-strict'];
+    await runInstall(['install', '--prefix', stage, '--save-exact', ...flags, `papilot@${version}`], stage, log);
+    const pkg = readJson(path.join(root, 'package.json'));
+    if (pkg?.name !== 'papilot' || pkg.version !== version) throw new Error('The downloaded package does not match the requested release.');
+    for (const file of ['dist/index.html', 'src/server/start.ts', 'src/server/main.ts', 'bin/papilot.mjs', 'vendor/latex-review/package-lock.json']) {
+      if (!fs.existsSync(path.join(root, file))) throw new Error('The downloaded release is incomplete.');
+    }
+    await runInstall(['ci', '--prefix', path.join(root, 'vendor/latex-review'), ...flags], stage, log);
+    await probeInstallation(root, version, stage, log);
+    return root;
+  } catch (error) { fs.rmSync(stage, { recursive: true, force: true }); throw error; }
+  finally { fs.closeSync(log); }
+}

package/src/server/update-worker.ts

@@ -0,0 +1,78 @@
+// Detached before the old server stops. This file stays in the old release,
+// so a broken download cannot remove the code needed to roll back.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { devRevision, readJson, releaseVersion, writeJson } from '../../bin/installation.mjs';
+import { health, loaderFor, sleep } from './update-install.ts';
+
+export async function restartRelease(job: { id: string; root: string; version: string; channel?: 'stable' | 'dev'; previousRoot: string; previousVersion: string; data: string; port: number; parent: number; service: boolean }, ready = () => process.send?.('ready'), attempts = 100) {
+  const folder = path.join(job.data, 'updates'), activeFile = path.join(folder, 'active.json'), statusFile = path.join(folder, 'status.json'), lock = path.join(folder, 'install.lock');
+  const previous = readJson(activeFile), status = readJson(statusFile) || {};
+  const database = path.join(job.data, 'papilot.sqlite'), backup = path.join(folder, 'before-update.sqlite');
+  const service = `gui/${process.getuid?.()}/local.papilot`, domain = `gui/${process.getuid?.()}`;
+  const plist = path.join(os.homedir(), 'Library/LaunchAgents/local.papilot.plist');
+  const alive = (pid: number) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+  const launchctl = (...args: string[]) => spawnSync('launchctl', args, { stdio: 'ignore', timeout: 15000 });
+  let child: ChildProcess | undefined, parentStopped = false, backedUp = false;
+  const launch = (root: string) => {
+    if (job.service) { if (launchctl('bootstrap', domain, plist).status !== 0) throw new Error('Could not restart the background service.'); return; }
+    const log = fs.openSync(path.join(folder, 'server.log'), 'a', 0o600);
+    child = spawn(process.execPath, ['--import', loaderFor(root), path.join(root, 'src/server/main.ts')], { cwd: root, detached: true, env: { ...process.env, PAPILOT_DATA: job.data, PAPILOT_PORT: String(job.port) }, stdio: ['ignore', log, log] });
+    child.on('error', () => {}); child.unref(); fs.closeSync(log);
+  };
+  const stopCandidate = async () => {
+    if (job.service) launchctl('bootout', service);
+    else if (child?.pid) {
+      child.kill('SIGTERM');
+      for (let i = 0; i < 40 && alive(child.pid); i++) await sleep(100);
+      if (alive(child.pid)) child.kill('SIGKILL');
+    }
+  };
+  try {
+    if (!releaseVersion(job.version) || (job.channel && (job.channel === 'dev') !== Boolean(devRevision(job.version))) || !fs.realpathSync(job.root).startsWith(fs.realpathSync(path.join(folder, 'releases')) + path.sep) || readJson(path.join(job.root, 'package.json'))?.version !== job.version) throw new Error('Invalid update activation.');
+    writeJson(lock, { pid: process.pid });
+    writeJson(statusFile, { ...status, phase: 'restarting', pid: process.pid });
+    writeJson(activeFile, { root: job.root, version: job.version, channel: job.channel, id: job.id, phase: 'pending', pid: process.pid, previous });
+    ready();
+    for (let i = 0; i < 150 && alive(job.parent); i++) await sleep(100);
+    if (alive(job.parent)) throw new Error('Papilot did not finish shutting down.');
+    parentStopped = true;
+    if (job.service) launchctl('bootout', service);
+    if (fs.existsSync(database)) {
+      fs.copyFileSync(database, backup); backedUp = true;
+      // Forced shutdown may leave committed SQLite pages in the WAL.
+      if (fs.existsSync(database + '-wal')) fs.copyFileSync(database + '-wal', backup + '-wal');
+      else fs.rmSync(backup + '-wal', { force: true });
+    }
+    writeJson(activeFile, { root: job.root, version: job.version, channel: job.channel, id: job.id, phase: 'starting', pid: process.pid, previous });
+    launch(job.root);
+    for (let i = 0; i < attempts; i++) {
+      if (await health(job.port, job.version, job.id)) {
+        writeJson(activeFile, { root: job.root, version: job.version, channel: job.channel, id: job.id, phase: 'active' });
+        writeJson(statusFile, { ...status, phase: 'updated', currentVersion: job.version, error: null, pid: process.pid });
+        return;
+      }
+      await sleep(300);
+    }
+    throw new Error('The new version did not restart successfully.');
+  } catch (error) {
+    if (parentStopped) await stopCandidate();
+    if (previous) writeJson(activeFile, previous); else fs.rmSync(activeFile, { force: true });
+    if (parentStopped && backedUp) {
+      for (const suffix of ['-wal', '-shm']) fs.rmSync(database + suffix, { force: true });
+      fs.copyFileSync(backup, database);
+      if (fs.existsSync(backup + '-wal')) fs.copyFileSync(backup + '-wal', database + '-wal');
+    }
+    writeJson(statusFile, { ...status, phase: 'failed', checkedAt: Date.now(), error: `${error instanceof Error ? error.message : 'The update failed.'} The previous version has been restored.`, pid: process.pid });
+    if (parentStopped) launch(job.previousRoot);
+  } finally { fs.rmSync(lock, { force: true }); }
+}
+
+if (process.argv[1] && fs.existsSync(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url))) {
+  const job = readJson(process.argv[2]);
+  if (!job) throw new Error('Missing update restart job.');
+  await restartRelease(job);
+}

package/src/server/updates.ts

@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+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 type { UpdateChannel, UpdateStatus } from '../shared.ts';
+
+const activePhases = new Set(['installing', 'waiting', 'restarting']);
+export const alive = (pid: number) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+async function releaseInfo(url: string, fetcher: typeof fetch) {
+  const response = await fetcher(url, { signal: AbortSignal.timeout(10000), redirect: 'error', headers: { Accept: 'application/json', 'User-Agent': 'Papilot' } });
+  if (!response.ok) throw new Error('Could not check for updates.');
+  const text = await response.text();
+  if (text.length > 256000) throw new Error('Invalid release information.');
+  return JSON.parse(text);
+}
+export async function latestRelease(channel: UpdateChannel = 'stable', fetcher = fetch): Promise<string> {
+  if (channel === 'dev') {
+    const commit = await releaseInfo('https://api.github.com/repos/PapilotAI/papilot/git/ref/heads/main', fetcher);
+    const revision = commit.object?.sha;
+    if (!/^[a-f0-9]{40}$/.test(revision)) throw new Error('Invalid development revision.');
+    const pkg = await releaseInfo(`https://raw.githubusercontent.com/PapilotAI/papilot/${revision}/package.json`, fetcher);
+    if (pkg.name !== 'papilot' || !stableVersion(pkg.version)) throw new Error('Invalid development version.');
+    return `${pkg.version}-dev.${revision}`;
+  }
+  const pkg = await releaseInfo('https://registry.npmjs.org/papilot/latest', fetcher);
+  if (pkg.name !== 'papilot' || !stableVersion(pkg.version)) throw new Error('Invalid release information.');
+  return pkg.version;
+}
+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 {
+  root: string; data: string; version: string; port: number;
+  busy: () => boolean; shutdown: () => void;
+  latest?: (channel: UpdateChannel) => Promise<string>; install?: (data: string, version: string) => Promise<string>;
+  restart?: (root: string, version: string) => Promise<void>; supported?: boolean;
+}
+// Both HTTP listeners share one updater. Downloads do not interrupt editing;
+// only the short activation window refuses new work and waits for quiescence.
+export class Updates {
+  private state: UpdateStatus;
+  private checking: Promise<UpdateStatus> | null = null;
+  private operation: Promise<void> | null = null;
+  private prepared = '';
+  private inFlight = 0;
+  private timer?: NodeJS.Timeout;
+  private closed = false;
+  private file: string;
+  private lock: string;
+  private channel: UpdateChannel;
+  constructor(private options: Options) {
+    this.file = path.join(options.data, '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 = preference === 'dev' || preference === 'stable' ? preference : devRevision(options.version) ? 'dev' : 'stable';
+    let supported = options.supported ?? true;
+    if (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 = 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.' });
+  }
+  snapshot(): UpdateStatus {
+    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;
+    return { currentVersion, latestVersion, phase, checkedAt, error, canUpdate, channel: this.channel };
+  }
+  get restarting() { return this.snapshot().phase === 'restarting'; }
+  enter() { this.inFlight++; let released = false; return () => { if (!released) { released = true; this.inFlight--; } }; }
+  start() {
+    if (this.state.phase !== 'failed') void this.check();
+    this.timer = setInterval(() => {
+      if (this.state.phase === 'waiting') void this.activate();
+      else if (!activePhases.has(this.state.phase) && Date.now() - (this.state.checkedAt || 0) > 6 * 3600000) void this.check();
+    }, 2000); this.timer.unref();
+  }
+  close() { this.closed = true; clearInterval(this.timer); }
+  private change(patch: Partial<UpdateStatus>) {
+    this.state = { ...this.state, ...patch };
+    writeJson(this.file, { ...this.state, pid: process.pid });
+  }
+  setChannel(channel: unknown) {
+    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;
+    this.change({ latestVersion: null, checkedAt: null, phase: 'idle', error: null });
+    return this.check();
+  }
+  check(): Promise<UpdateStatus> {
+    if (this.checking) return this.checking;
+    if (activePhases.has(this.state.phase)) return Promise.resolve(this.snapshot());
+    this.change({ phase: 'checking' });
+    const channel = this.channel;
+    const checking = (this.options.latest || latestRelease)(channel).then(version => {
+      if (!validTarget(version, channel)) throw new Error('Invalid release version.');
+      if (!this.closed && this.checking === checking && !activePhases.has(this.state.phase)) this.change({ latestVersion: version, checkedAt: Date.now(), error: null, phase: available(version, this.options.version, channel) ? 'available' : 'idle' });
+      return this.snapshot();
+    }).catch(() => {
+      if (!this.closed && this.checking === checking && !activePhases.has(this.state.phase)) this.change({ phase: this.state.latestVersion && available(this.state.latestVersion, this.options.version, channel) ? 'available' : 'idle', checkedAt: Date.now(), error: 'Could not check for updates. Try again when connected.' });
+      return this.snapshot();
+    }).finally(() => { if (this.checking === checking) this.checking = null; });
+    this.checking = checking;
+    return this.checking;
+  }
+  install(version: unknown) {
+    if (activePhases.has(this.state.phase)) return this.snapshot();
+    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 });
+    const previous = readJson(this.lock);
+    if (previous && alive(previous.pid)) throw new Error('Another Papilot instance is already updating.');
+    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 });
+    this.operation = (this.options.install || installRelease)(this.options.data, version).then(root => {
+      if (this.closed) return;
+      this.prepared = root; this.change({ phase: 'waiting' });
+      return this.activate();
+    }).catch(error => { this.change({ phase: 'failed', error: error instanceof Error ? error.message : 'The update failed.' }); this.release(); }).finally(() => { this.operation = null; });
+    return this.snapshot();
+  }
+  // Public for deterministic tests; the periodic tick calls this in production.
+  async activate() {
+    if (this.closed || this.state.phase !== 'waiting' || !this.prepared || this.inFlight || this.options.busy()) return;
+    this.change({ phase: 'restarting' });
+    try { await (this.options.restart || this.restart.bind(this))(this.prepared, this.state.latestVersion!); }
+    catch (error) { this.change({ phase: 'failed', error: error instanceof Error ? error.message : 'Could not restart Papilot.' }); this.release(); }
+  }
+  private release() { const lock = readJson(this.lock); if (lock?.pid === process.pid) fs.rmSync(this.lock, { force: true }); }
+  private restart(root: string, version: string) {
+    const folder = path.dirname(this.file), job = path.join(folder, 'restart.json');
+    writeJson(job, { id: randomUUID(), root, version, channel: this.channel, previousRoot: this.options.root, previousVersion: this.options.version, data: this.options.data, port: this.options.port, parent: process.pid,
+      service: process.env.PAPILOT_SERVICE_MANAGER === 'launchd' || process.env.XPC_SERVICE_NAME === 'local.papilot' });
+    const log = fs.openSync(path.join(folder, 'restart.log'), 'a', 0o600);
+    const child = spawn(process.execPath, ['--import', loaderFor(this.options.root), path.join(this.options.root, 'src/server/update-worker.ts'), job], { cwd: this.options.root, env: process.env, detached: true, stdio: ['ignore', log, log, 'ipc'] });
+    fs.closeSync(log);
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => { child.kill(); reject(new Error('The update restart helper did not start.')); }, 10000);
+      child.once('error', error => { clearTimeout(timer); reject(error); });
+      child.once('exit', code => { clearTimeout(timer); reject(new Error(`The update restart helper stopped (${code}).`)); });
+      child.once('message', message => {
+        if (message !== 'ready') return;
+        clearTimeout(timer); child.disconnect(); child.unref(); resolve(); this.options.shutdown();
+      });
+    });
+  }
+}