papilot 0.7.0 → 0.8.1

package/src/server/review.ts

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { ENGINE } from './paths.ts';
 import type { Task } from '../shared.ts';
 
-export interface ReviewClient { url: string; token: string; get<T = any>(route: string): Promise<T>; post<T = any>(route: string, body?: unknown): Promise<T> }
+export interface ReviewClient { url: string; token: string; get<T = any>(route: string): Promise<T>; post<T = any>(route: string, body?: unknown, timeout?: number): Promise<T> }
 let modulePromise: Promise<{ connect: (root: string) => Promise<ReviewClient> }> | null = null;
 export function reviewClient(root: string): Promise<ReviewClient> {
   modulePromise ??= import(pathToFileURL(path.join(ENGINE, 'src/client.ts')).href);
@@ -34,15 +34,16 @@ export function annotateReviewState(value: unknown, tasks: readonly Task[]): unk
   else if (task.status === 'building') decisionLock = 'Wait for the PDF build before accepting, rejecting, or undoing changes. You can still add comments.';
   else if (['running', 'waiting_input', 'queued'].includes(task.status)) decisionLock = 'Pause this task in Papilot before accepting, rejecting, or undoing changes. You can still add comments.';
   else if (task.pendingReview) decisionLock = 'Wait for the current review action before accepting, rejecting, or undoing changes. You can still add comments.';
+  else if (task.reconciliation && (!task.reconciliation.ready || Number(state.round) <= task.reconciliation.round)) decisionLock = 'Wait for the merge suggestion before changing review decisions.';
   else if (task.delivery?.pending) decisionLock = 'Retry the pending delivery before changing review decisions.';
-  // Changes the task has committed are in the manuscript too.
-  return { ...state, decisionLock, commentLock, ...(task ? { workspace: { status: task.status, unsent: task.review?.unsent ?? 0, comments: task.review?.comments ?? 0, accepted: task.review?.files?.length || (task.committed || task.delivery?.pending ? 1 : 0), ...(task.deferred ? { deferred: true, destination: task.delivery?.pending ? undefined : task.delivery?.mode } : {}) } } : {}) };
+  // Task-branch commits from older versions still need manuscript application.
+  return { ...state, decisionLock, commentLock, ...(task ? { workspace: { ...(task.reconciliation ? { merging: true } : {}), status: task.status, unsent: task.review?.unsent ?? 0, comments: task.review?.comments ?? 0, accepted: task.review?.files?.length || (task.committed || task.delivery?.pending || task.delivery?.mode === 'branch' ? 1 : 0), ...(task.deferred ? { deferred: true, destination: task.delivery?.pending ? undefined : task.delivery?.mode } : {}) } } : {}) };
 }
 
 export function allowedReviewRoute(route: string, method: string): boolean {
   if (route.includes('..') || route.includes('\\')) return false;
-  if (method === 'GET') return route === '/' || /^\/(assets|fonts)\/[\w./-]+$/.test(route) || /^\/files\/[a-z0-9-]+\/\d+\/[\w.-]+\.(svg|png)$/.test(route) || /^\/api\/tasks(?:\/[a-z0-9-]+(?:\/(?:state|rounds\/\d+(?:\/effects\/c\d+)?))?)?$/.test(route);
-  return method === 'POST' && /^\/api\/tasks\/[a-z0-9-]+\/(decide|undo|note)$/.test(route);
+  if (method === 'GET') return route === '/' || /^\/(assets|fonts)\/[\w./-]+$/.test(route) || /^\/files\/[a-z0-9-]+\/\d+\/[\w.-]+\.(svg|png)$/.test(route) || /^\/api\/tasks(?:\/[a-z0-9-]+(?:\/(?:state|rounds\/\d+(?:\/effects\/c\d+|\/references)?))?)?$/.test(route);
+  return method === 'POST' && /^\/api\/tasks\/[a-z0-9-]+\/(decide|undo|note|rounds\/\d+\/references\/confirm)$/.test(route);
 }
 export function rewriteReviewJson(value: any, prefix: string): any {
   if (Array.isArray(value)) return value.map(v => rewriteReviewJson(v, prefix));

package/src/server/skills.ts

@@ -3,6 +3,8 @@ import path from 'node:path';
 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/; ~/.papilot/skills/ adds the author's
@@ -33,14 +35,9 @@ export function skillFiles(dir: string): { id: string; file: string; folder?: st
 
 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[] {
@@ -67,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

@@ -11,6 +11,7 @@ import { Changes } from './changes.ts';
 import { buildApp, gitQueue } from './app.ts';
 import { Updates } from './updates.ts';
 import { readJson } from '../../bin/installation.mjs';
+import { desktopDemo } from './desktop-demo.ts';
 
 const problem = accountProblem(ACCOUNT_ORIGIN, ACCOUNT_PORT, PORT, PUBLIC_ORIGIN);
 if (problem) { console.error(problem); process.exit(1); }
@@ -18,20 +19,30 @@ 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 desktop = process.env.PAPILOT_DESKTOP === '1';
+if (desktop) await desktopDemo(ROOT, DATA, store, workspace, manuscripts).catch(error => console.error('Could not prepare the demo paper:', error));
+const updates = new Updates({ root: ROOT, data: DATA, version: VERSION, port: PORT,
+  ...(desktop ? { supported: false, downloadUrl: 'https://github.com/PapilotAI/papilot/releases/latest' } : {}),
+  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 } })];
+const localListener = { kind: 'local' as const, port: PORT, publicOrigin: PUBLIC_ORIGIN, owner: OWNER };
+const apps = [await buildApp({ ...shared, listener: localListener })];
 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 });
+const localUrl = await apps[0].listen({ host: '127.0.0.1', port: PORT }).catch(error => {
+  if (!desktop || error.code !== 'EADDRINUSE') throw error;
+  return apps[0].listen({ host: '127.0.0.1', port: 0 });
+});
+// Desktop requests an OS-assigned port. Keep Host/Origin checks exact after bind.
+localListener.port = Number(new URL(localUrl).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})` : ''}`);
+console.log(`Papilot is running at ${localUrl}${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()) {
@@ -49,3 +60,7 @@ function shutdown() {
   setTimeout(() => process.exit(0), 2500).unref();
 }
 for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, shutdown);
+if (desktop && process.send) {
+  process.on('disconnect', shutdown);
+  process.send({ type: 'papilot:ready', url: localUrl });
+}

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';
@@ -16,6 +17,7 @@ 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);
@@ -23,6 +25,7 @@ export class Store extends EventEmitter {
       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);`);
   }
@@ -39,7 +42,7 @@ export class Store extends EventEmitter {
     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']) this.db.prepare(`DELETE FROM ${table} WHERE task_id IN (SELECT id FROM tasks WHERE project_id=?)`).run(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);
     });
@@ -51,6 +54,12 @@ export class Store extends EventEmitter {
   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'); }
+  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;
@@ -69,10 +78,19 @@ export class Store extends EventEmitter {
       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(() => {
@@ -80,7 +98,7 @@ export class Store extends EventEmitter {
       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

@@ -1,9 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import net from 'node:net';
-import { spawn } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
 import { createRequire } from 'node:module';
-import { readJson, stableVersion } from '../../bin/installation.mjs';
+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'),
@@ -52,7 +56,54 @@ export async function probeInstallation(root: string, version: string, stage: st
     }
   }
 }
+// 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');

package/src/server/update-worker.ts

@@ -5,10 +5,10 @@ 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 { readJson, stableVersion, writeJson } from '../../bin/installation.mjs';
+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; previousRoot: string; previousVersion: string; data: string; port: number; parent: number; service: boolean }, ready = () => process.send?.('ready'), attempts = 100) {
+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');
@@ -32,10 +32,10 @@ export async function restartRelease(job: { id: string; root: string; version: s
     }
   };
   try {
-    if (!stableVersion(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.');
+    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, id: job.id, phase: 'pending', pid: process.pid, previous });
+    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.');
@@ -47,11 +47,11 @@ export async function restartRelease(job: { id: string; root: string; version: s
       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, id: job.id, phase: 'starting', pid: process.pid, previous });
+    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, id: job.id, phase: 'active' });
+        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;
       }

package/src/server/updates.ts

@@ -2,25 +2,40 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { newerVersion, readJson, stableVersion, writeJson } from '../../bin/installation.mjs';
+import { devRevision, newerVersion, readJson, stableVersion, writeJson } from '../../bin/installation.mjs';
 import { installRelease, loaderFor, npmCli } from './update-install.ts';
-import type { UpdateStatus } from '../shared.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; } };
-export async function latestRelease(): Promise<string> {
-  const response = await fetch('https://registry.npmjs.org/papilot/latest', { signal: AbortSignal.timeout(10000), redirect: 'error', headers: { Accept: 'application/json' } });
+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.');
-  const pkg = JSON.parse(text);
+  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 {
+  downloadUrl?: string;
   root: string; data: string; version: string; port: number;
   busy: () => boolean; shutdown: () => void;
-  latest?: () => Promise<string>; install?: (data: string, version: string) => Promise<string>;
+  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;
@@ -35,8 +50,11 @@ export class Updates {
   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 = options.downloadUrl ? 'stable' : 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 };
@@ -45,14 +63,16 @@ export class Updates {
     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 {
+    if (this.options.downloadUrl) return { currentVersion: this.options.version, latestVersion: null, phase: 'idle', checkedAt: null, error: null, canUpdate: false, channel: 'stable', downloadUrl: this.options.downloadUrl };
     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 };
+    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.options.downloadUrl) return;
     if (this.state.phase !== 'failed') void this.check();
     this.timer = setInterval(() => {
       if (this.state.phase === 'waiting') void this.activate();
@@ -64,24 +84,39 @@ export class Updates {
     this.state = { ...this.state, ...patch };
     writeJson(this.file, { ...this.state, pid: process.pid });
   }
+  setChannel(channel: unknown) {
+    if (this.options.downloadUrl) 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;
+    this.change({ latestVersion: null, checkedAt: null, phase: 'idle', error: null });
+    return this.check();
+  }
   check(): Promise<UpdateStatus> {
+    if (this.options.downloadUrl) return Promise.resolve(this.snapshot());
     if (this.checking) return this.checking;
     if (activePhases.has(this.state.phase)) return Promise.resolve(this.snapshot());
     this.change({ phase: 'checking' });
-    this.checking = (this.options.latest || latestRelease)().then(version => {
-      if (!stableVersion(version)) throw new Error('Invalid release version.');
-      if (!this.closed && !activePhases.has(this.state.phase)) this.change({ latestVersion: version, checkedAt: Date.now(), error: null, phase: newerVersion(version, this.options.version) ? 'available' : 'idle' });
+    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 && !activePhases.has(this.state.phase)) this.change({ phase: this.state.latestVersion && newerVersion(this.state.latestVersion, this.options.version) ? 'available' : 'idle', checkedAt: Date.now(), error: 'Could not check for updates. Try again when connected.' });
+      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(() => { this.checking = null; });
+    }).finally(() => { if (this.checking === checking) this.checking = null; });
+    this.checking = checking;
     return this.checking;
   }
   install(version: unknown) {
+    if (this.options.downloadUrl) throw new Error('Download desktop updates from GitHub Releases.');
     if (activePhases.has(this.state.phase)) return this.snapshot();
     if (!this.state.canUpdate) throw new Error('npm is unavailable to Papilot.');
-    if (!stableVersion(version) || version !== this.state.latestVersion || !newerVersion(version, this.options.version)) throw new Error('Check for a newer release before updating.');
+    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.');
@@ -105,7 +140,7 @@ export class Updates {
   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, previousRoot: this.options.root, previousVersion: this.options.version, data: this.options.data, port: this.options.port, parent: process.pid,
+    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'] });