@fapost/jig-ui 0.1.0-next.9 → 0.1.0

package/dist/board/columns.js

@@ -0,0 +1,29 @@
+/** The board's order: what waits for the person first, then what moves, what is done, what is not begun, what is set aside. */
+const COLUMNS = [
+    { id: 'needs-you', title: 'Needs you' },
+    { id: 'in-progress', title: 'In progress' },
+    { id: 'ready', title: 'Ready' },
+    { id: 'backlog', title: 'Backlog' },
+    { id: 'paused', title: 'Paused' },
+];
+/** Where a task stands, from Jig's state alone; the first rule that fits wins. */
+export function columnOf(task) {
+    if (task.paused)
+        return 'paused';
+    if (!task.started)
+        return 'backlog';
+    if (task.gate === 'waiting' || task.gate === 'changed' || task.autopilot === 'stopped')
+        return 'needs-you';
+    if (task.status === 'ready')
+        return 'ready';
+    return 'in-progress';
+}
+/** The column a task sits in, with its title. */
+export function placeOf(task) {
+    const id = columnOf(task);
+    return { id, title: COLUMNS.find((c) => c.id === id)?.title ?? id };
+}
+/** The board: every column, in a fixed order, its cards in the order Jig listed them. Computed on every read, never stored. */
+export function columns(tasks) {
+    return COLUMNS.map((c) => ({ ...c, cards: tasks.filter((t) => columnOf(t) === c.id) }));
+}

package/dist/http/app.js

@@ -4,6 +4,8 @@ import { isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { columns, placeOf } from '../board/columns.js';
 import { RegistryUnreadable } from '../source/project-source.js';
 import { localOnly, tokenAccess } from './access.js';
 /**
@@ -17,6 +19,8 @@ export function readPackageVersion() {
 }
 /** The built page: `dist/web`, next to `dist/http` where this file runs when published. */
 export const DEFAULT_WEB_ROOT = fileURLToPath(new URL('../web', import.meta.url));
+/** How often an idle stream sends a comment, so a closed tab is noticed and its subscription ends. */
+const PING_MS = 30_000;
 const refuse = (c, status, code, message) => c.json({ error: { code, message } }, status);
 /** The path the person typed, absolute; `~/` stands for their home. */
 function absolute(path) {
@@ -37,6 +41,31 @@ export function createApp({ port, token, source, version = readPackageVersion(),
     });
     app.get('/api/instance', (c) => c.json({ version }));
     app.get('/api/workspace', async (c) => c.json({ projects: await source.workspace() }));
+    app.get('/api/projects/:id/board', async (c) => {
+        const id = c.req.param('id');
+        const read = await source.tasks(id);
+        if (read === undefined)
+            return refuse(c, 404, 'not-connected', 'No connected project has this id.');
+        if (read.state !== 'ready')
+            return c.json({ board: read });
+        return c.json({ board: { id, state: 'ready', columns: columns(read.tasks), finished: read.finished } });
+    });
+    app.get('/api/projects/:id/tasks/:task', async (c) => {
+        const read = await source.task(c.req.param('id'), c.req.param('task'));
+        if (read === undefined)
+            return refuse(c, 404, 'not-connected', 'No connected project has this id.');
+        if (read.state !== 'ready')
+            return c.json({ task: read });
+        if (read.task === null)
+            return refuse(c, 404, 'not-found', 'This project has no live task with this id.');
+        return c.json({ task: { state: 'ready', ...read.task, column: placeOf(read.task) } });
+    });
+    app.get('/api/projects/:id/specs', async (c) => {
+        const read = await source.specs(c.req.param('id'));
+        if (read === undefined)
+            return refuse(c, 404, 'not-connected', 'No connected project has this id.');
+        return c.json({ specs: read });
+    });
     app.post('/api/projects', async (c) => {
         const body = await c.req.json().catch(() => undefined);
         const path = absolute(body?.path);
@@ -53,6 +82,18 @@ export function createApp({ port, token, source, version = readPackageVersion(),
         }
         return c.body(null, 204);
     });
+    // A signal, not data: the page re-fetches what it shows (adr-20261014-project-source-port-keeps-hosting-open).
+    app.get('/api/events', (c) => streamSSE(c, async (stream) => {
+        const unsubscribe = source.subscribe(({ id, revision }) => {
+            void stream.writeSSE({ event: 'changed', data: JSON.stringify({ project: id, revision }) });
+        });
+        stream.onAbort(unsubscribe);
+        while (!stream.aborted) {
+            await stream.sleep(PING_MS);
+            if (!stream.aborted)
+                await stream.write(': ping\n\n');
+        }
+    }));
     app.all('/api/*', (c) => c.json({ error: 'not found' }, 404));
     if (existsSync(join(webRoot, 'index.html'))) {
         app.use('/*', serveStatic({ root: webRoot }));

package/dist/jig/client.js

@@ -7,6 +7,16 @@ const run = promisify(execFile);
 export const MIN_JIG_VERSION = '0.29.0';
 const SCRIPT = join('.ai', 'scripts', 'jig');
 const TIMEOUT_MS = 10_000;
+/** The directory whose changes may change what Jig reports: the main checkout's `.ai/`. */
+export const watchDir = (root) => join(root, '.ai');
+/**
+ * True for a path under `.ai/` (with `/` separators) that Jig writes while it only reads — its
+ * records of what it is doing under `runtime/` — so a change there is no sign of a change, and
+ * watching it would make every read trigger the next. `runtime/revision/` is where the clone's
+ * revision rises on each Jig write, and stays a sign. Jig names no such path in its contract
+ * (Jig 0.29.0, found by watching which files its reads touch).
+ */
+export const writtenByReads = (path) => (path === 'runtime' || path.startsWith('runtime/')) && !path.startsWith('runtime/revision');
 /**
  * The bash that runs `.ai/scripts/jig`. On Windows it is Git's, found next to git itself
  * (`<git>/mingw64/libexec/git-core` → `<git>/bin/bash.exe`): a `bash` on PATH may be WSL's.
@@ -117,13 +127,119 @@ export async function readStatus(root, platform = process.platform) {
     };
 }
 const STATUSES = new Set(['active', 'ready', 'consolidated', 'abandoned']);
-const isTaskSummary = (v) => isObject(v) && isString(v.id) && isString(v.status) && STATUSES.has(v.status) && typeof v.paused === 'boolean';
-/** The project's live tasks (`jig task list --json`, finished ones left out). */
+/** Jig's action ids this Jig UI knows; Jig may add ids without raising `schema`, and a consumer ignores those. */
+const ACTIONS = new Set(['start', 'pause', 'resume', 'approve-gate', 'answer-stop', 'set-class', 'ship', 'close', 'abandon', 'reopen']);
+const nullableStrings = (v, keys) => keys.every((k) => isNullableString(v[k]));
+const isGate = (v) => v === null || (isObject(v) && isString(v.state) && isNullableString(v.by));
+const isAutopilot = (v) => v === null || (isObject(v) && isString(v.state) && nullableStrings(v, ['mode', 'stage', 'stage_at', 'stop_reason', 'stop_at', 'phase']));
+const isPullRequest = (v) => v === null || (isObject(v) && isString(v.url) && nullableStrings(v, ['state', 'ci', 'fetched_at']));
+const isWorktree = (v) => v === null || (isObject(v) && typeof v.uncommitted === 'number');
+const isAction = (v) => isObject(v) && isString(v.id) && isString(v.command) && typeof v.offered === 'boolean' && isNullableString(v.reason);
+const isTaskRow = (v) => isObject(v) &&
+    isString(v.id) &&
+    isString(v.status) &&
+    STATUSES.has(v.status) &&
+    nullableStrings(v, ['class', 'issue', 'goal', 'created_at', 'updated_at', 'branch']) &&
+    typeof v.knowledge_consolidated === 'boolean' &&
+    typeof v.paused === 'boolean' &&
+    isString(v.base_branch) &&
+    isWorktree(v.worktree) &&
+    isGate(v.gate) &&
+    isAutopilot(v.autopilot) &&
+    isPullRequest(v.pull_request) &&
+    Array.isArray(v.housekeeping_flags) &&
+    v.housekeeping_flags.every(isString) &&
+    Array.isArray(v.actions) &&
+    v.actions.every(isAction);
+function summary(t) {
+    const { gate, autopilot: run, pull_request: pr } = t;
+    return {
+        id: t.id,
+        class: t.class,
+        status: t.status,
+        issue: t.issue,
+        goal: t.goal,
+        knowledgeConsolidated: t.knowledge_consolidated,
+        paused: t.paused,
+        createdAt: t.created_at,
+        updatedAt: t.updated_at,
+        branch: t.branch,
+        baseBranch: t.base_branch,
+        worktree: t.worktree && { uncommitted: t.worktree.uncommitted },
+        gate: gate && { state: gate.state, by: gate.by },
+        autopilot: run && {
+            state: run.state,
+            mode: run.mode,
+            stage: run.stage,
+            stageAt: run.stage_at,
+            stopReason: run.stop_reason,
+            stopAt: run.stop_at,
+            phase: run.phase,
+        },
+        pullRequest: pr && { url: pr.url, state: pr.state, ci: pr.ci, fetchedAt: pr.fetched_at },
+        housekeepingFlags: [...t.housekeeping_flags],
+        actions: t.actions.filter((a) => ACTIONS.has(a.id)).map(({ id, command, offered, reason }) => ({ id, command, offered, reason })),
+    };
+}
+/** The project's live tasks (`jig task list --json`) and how many finished ones it left out. */
 export async function readTasks(root, platform = process.platform) {
     const { revision, data } = await readJson(root, ['task', 'list'], platform);
-    if (!Array.isArray(data.tasks) || !data.tasks.every(isTaskSummary))
+    if (!Array.isArray(data.tasks) || !data.tasks.every(isTaskRow) || typeof data.hidden !== 'number')
+        throw new JigShapeError();
+    return { revision, tasks: data.tasks.map(summary), hidden: data.hidden };
+}
+const isCount = (v) => Number.isInteger(v) && v >= 0;
+const isProgress = (v) => isObject(v) && isCount(v.done) && isCount(v.total) && isCount(v.filed) && isCount(v.fog);
+const isItem = (v) => isObject(v) && isString(v.text) && typeof v.checked === 'boolean' && isNullableString(v.task) && typeof v.fog === 'boolean';
+const isPhase = (v) => isObject(v) &&
+    isProgress(v) &&
+    (v.phase === null || isCount(v.phase)) &&
+    isNullableString(v.title) &&
+    Array.isArray(v.items) &&
+    v.items.every(isItem);
+const isEpic = (v) => v === null ||
+    (isObject(v) &&
+        isString(v.branch) &&
+        (v.state === 'open' || v.state === 'finished') &&
+        typeof v.checked_out === 'boolean' &&
+        typeof v.missing === 'boolean' &&
+        isNullableString(v.ref));
+const isSpecRow = (v) => isObject(v) &&
+    isString(v.id) &&
+    isNullableString(v.title) &&
+    Array.isArray(v.missing_files) &&
+    v.missing_files.every(isString) &&
+    isNullableString(v.release) &&
+    isEpic(v.epic) &&
+    (v.progress === null || isProgress(v.progress)) &&
+    Array.isArray(v.phases) &&
+    v.phases.every(isPhase);
+const progress = ({ done, total, filed, fog }) => ({ done, total, filed, fog });
+/** The project's specs (`jig spec list --json`), in Jig's order. */
+export async function readSpecs(root, platform = process.platform) {
+    const { data } = await readJson(root, ['spec', 'list'], platform);
+    if (!Array.isArray(data.specs) || !data.specs.every(isSpecRow))
         throw new JigShapeError();
-    return { revision, tasks: data.tasks.map(({ id, status, paused }) => ({ id, status, paused })) };
+    return data.specs.map((s) => ({
+        id: s.id,
+        title: s.title,
+        missingFiles: [...s.missing_files],
+        release: s.release,
+        epic: s.epic && {
+            branch: s.epic.branch,
+            state: s.epic.state,
+            checkedOut: s.epic.checked_out,
+            missing: s.epic.missing,
+            fetched: s.epic.ref?.startsWith('refs/remotes/') === true,
+        },
+        progress: s.progress && progress(s.progress),
+        phases: s.phases.map((p) => ({
+            ...progress(p),
+            phase: p.phase,
+            title: p.title,
+            items: p.items.map(({ text, checked, task, fog }) => ({ text, checked, task, fog })),
+        })),
+    }));
 }
 /** True when `version` is at least the minimum Jig UI reads. */
 export function supports(version, minimum = MIN_JIG_VERSION) {

package/dist/main.js

@@ -6,7 +6,8 @@ import { DEFAULT_PORT, parseCliArgs } from './args.js';
 import { createApp, readPackageVersion } from './http/app.js';
 import { openBrowser } from './open-browser.js';
 import { configDir } from './registry/config-dir.js';
-import { probeInstance, readInstance, removeInstance, writeInstance } from './registry/instance.js';
+import { connectThrough, probeInstance, readInstance, removeInstance, writeInstance } from './registry/instance.js';
+import { mainCheckout } from './source/checkout.js';
 import { localSource } from './source/local.js';
 const HOST = '127.0.0.1';
 const HELP = `Usage: jig-ui [options]
@@ -21,12 +22,40 @@ function fail(message) {
     console.error(message);
     process.exit(1);
 }
-const link = ({ port, token }) => `http://${HOST}:${port}/?token=${token}`;
-async function show(info, open, dir) {
-    console.log(`Open it at ${link(info)}`);
-    if (open && !(await openBrowser(link(info), dir)))
+// The token swap redirects to `/` with no fragment, so the browser keeps this one: the board opens.
+const link = ({ port, token }, project) => `http://${HOST}:${port}/?token=${token}${project ? `#/projects/${project}` : ''}`;
+async function show(info, open, dir, project) {
+    console.log(`Open it at ${link(info, project)}`);
+    if (open && !(await openBrowser(link(info, project), dir)))
         console.log('Could not open a browser; open the link above.');
 }
+/** The folder this command runs in, as a checkout to connect: a worktree stands for its clone's main checkout. */
+async function here() {
+    const checkout = await mainCheckout(process.cwd());
+    if (checkout.kind === 'main')
+        return { path: checkout.root, worktree: false };
+    // A bare clone's worktree has no main checkout: nothing to connect, said as outside a project.
+    if (checkout.kind === 'worktree' && checkout.main)
+        return { path: checkout.main, worktree: true };
+    return undefined;
+}
+/**
+ * Connects the folder through the instance and returns the project's id. Outside a Jig project it says
+ * nothing: the command then only starts, as it always did.
+ */
+async function connectHere(info, place) {
+    if (!place)
+        return undefined;
+    const result = await connectThrough(info, place.path);
+    if ('id' in result) {
+        const what = place.worktree ? `the main checkout of this worktree, ${place.path}` : place.path;
+        console.log(result.created ? `Connected ${result.id}: ${what}.` : `${result.id} is connected: ${what}.`);
+        return result.id;
+    }
+    if (result.code !== 'not-a-repository' && result.code !== 'no-jig')
+        console.log(`Could not connect this folder: ${result.message}`);
+    return undefined;
+}
 /** The instance recorded in the config directory, if it still answers with its token. */
 async function runningInstance(dir) {
     const info = await readInstance(dir);
@@ -56,13 +85,14 @@ export async function main() {
     }
     const { port, open } = command;
     const dir = configDir(process.env, process.platform, homedir());
+    const place = await here();
     const running = await runningInstance(dir);
     if (running) {
         console.log(`Jig UI is already running on port ${running.port}.`);
         // ponytail: a --port equal to the default is indistinguishable from no flag; no note then.
         if (port !== running.port && port !== DEFAULT_PORT)
             console.log(`--port ${port} is ignored.`);
-        await show(running, open, dir);
+        await show(running, open, dir, await connectHere(running, place));
         return;
     }
     const version = readPackageVersion();
@@ -71,7 +101,7 @@ export async function main() {
         void (async () => {
             await writeInstance(dir, { port, token, pid: process.pid, version });
             console.log(`Jig UI ${version} is running at http://${HOST}:${port}/`);
-            await show({ port, token }, open, dir);
+            await show({ port, token }, open, dir, await connectHere({ port, token }, place));
             console.log('Press Ctrl+C to stop.');
         })().catch((error) => fail(`Could not start: ${error instanceof Error ? error.message : String(error)}`));
     });
@@ -83,7 +113,7 @@ export async function main() {
             if (!winner)
                 fail(`Port ${port} is already in use. Stop the other process or choose another port with --port.`);
             console.log(`Jig UI is already running on port ${winner.port}.`);
-            await show(winner, open, dir);
+            await show(winner, open, dir, await connectHere(winner, place));
             process.exit(0);
         });
     });

package/dist/node-version.js

@@ -8,7 +8,6 @@ export function checkNodeVersion(version) {
     }
     return {
         ok: false,
-        message: 'Jig UI needs Node.js ' + MINIMUM_NODE_MAJOR + ' or later, but this is ' + version +
-            '. Install a newer Node.js and run it again.',
+        message: 'Jig UI needs Node.js ' + MINIMUM_NODE_MAJOR + ' or later, but this is ' + version + '. Install a newer Node.js and run it again.',
     };
 }

package/dist/registry/instance.js

@@ -48,3 +48,24 @@ export async function probeInstance(info, timeoutMs = 1000) {
         return false;
     }
 }
+/** Asks the instance to connect `path`, as the page does: the instance owns the registry, so no second process writes it. */
+export async function connectThrough(info, path, timeoutMs = 15_000) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${info.port}/api/projects`, {
+            method: 'POST',
+            headers: { cookie: `${cookieName(info.port)}=${info.token}`, 'content-type': 'application/json' },
+            body: JSON.stringify({ path }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        // A failure the instance did not foresee answers in plain text.
+        const body = (await res.json().catch(() => ({})));
+        if (body.project)
+            return { id: body.project.id, created: res.status === 201 };
+        if (typeof body.error === 'object')
+            return body.error;
+        return { code: 'unexpected', message: `Jig UI answered ${res.status}.` };
+    }
+    catch (error) {
+        return { code: 'unreachable', message: error instanceof Error ? error.message : String(error) };
+    }
+}

package/dist/source/checkout.js

@@ -21,5 +21,23 @@ export async function mainCheckout(path) {
     const [top, own, common] = stdout.trim().split(/\r?\n/);
     if (!top || !own || !common)
         return { kind: 'not-a-repository' };
-    return (await realpath(own)) === (await realpath(common)) ? { kind: 'main', root: await realpath(top) } : { kind: 'worktree' };
+    if ((await realpath(own)) === (await realpath(common)))
+        return { kind: 'main', root: await realpath(top) };
+    return { kind: 'worktree', main: await mainWorktree(path) };
+}
+/**
+ * The main working tree, which `git worktree list` names first — not `dirname(--git-common-dir)`, which
+ * misses for a worktree of a submodule. A bare clone's first entry is the repository itself.
+ */
+async function mainWorktree(path) {
+    try {
+        const { stdout } = await run('git', ['worktree', 'list', '--porcelain'], { cwd: path, timeout: 10_000 });
+        const [first, second] = stdout.split(/\r?\n/);
+        if (!first?.startsWith('worktree ') || second === 'bare')
+            return null;
+        return await realpath(first.slice('worktree '.length));
+    }
+    catch {
+        return null;
+    }
 }

package/dist/source/local.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
-import { JigRefusal, JigShapeError, jigVersion, MIN_JIG_VERSION, readStatus, readTasks, supports } from '../jig/client.js';
+import { JigRefusal, JigShapeError, jigVersion, MIN_JIG_VERSION, readSpecs, readStatus, readTasks, supports, watchDir, writtenByReads, } from '../jig/client.js';
 import { addProject, readProjects, removeProject } from '../registry/projects.js';
+import { watchTree } from '../watch/watch.js';
 import { mainCheckout } from './checkout.js';
 /** Jig's version in the checkout: `null` when Jig is there but names no version Jig UI can read. */
 async function version(root) {
@@ -32,8 +33,46 @@ function count(tasks) {
         ready: tasks.filter((t) => t.status === 'ready' && !t.paused).length,
     };
 }
-/** Reads a connected project; one below the minimum Jig, or gone, is not read any further. */
-async function view({ id, path }) {
+/** A live task as a board's card shows it. */
+const card = (t) => ({
+    id: t.id,
+    class: t.class,
+    status: t.status,
+    goal: t.goal,
+    paused: t.paused,
+    started: t.branch !== null,
+    gate: t.gate?.state ?? null,
+    autopilot: t.autopilot?.state ?? null,
+    pullRequest: t.pullRequest,
+});
+/** A live task in full; where its worktree is was never read, and an action Jig refuses is left out. */
+const details = (t, attention) => ({
+    ...card(t),
+    issue: t.issue,
+    branch: t.branch,
+    baseBranch: t.baseBranch,
+    createdAt: t.createdAt,
+    updatedAt: t.updatedAt,
+    knowledgeConsolidated: t.knowledgeConsolidated,
+    worktree: t.worktree,
+    gateBy: t.gate?.by ?? null,
+    run: t.autopilot && {
+        mode: t.autopilot.mode,
+        stage: t.autopilot.stage,
+        stageAt: t.autopilot.stageAt,
+        stopReason: t.autopilot.stopReason,
+        stopAt: t.autopilot.stopAt,
+        phase: t.autopilot.phase,
+    },
+    housekeepingFlags: t.housekeepingFlags,
+    actions: t.actions.filter((a) => a.offered).map(({ id, command }) => ({ id, command })),
+    attention: attention.filter((a) => a.tasks.includes(t.id)),
+});
+/**
+ * Runs `read` on a connected project whose Jig Jig UI reads; a project gone, below the minimum, or
+ * refusing the read comes back as its state instead.
+ */
+async function reading({ id, path }, read) {
     if (!existsSync(path))
         return { id, state: 'unavailable', reason: 'missing' };
     const v = await version(path);
@@ -42,15 +81,7 @@ async function view({ id, path }) {
     if (v === null || !supports(v))
         return { id, state: 'unsupported', jigVersion: v, minimum: MIN_JIG_VERSION };
     try {
-        const [status, { tasks }] = await Promise.all([readStatus(path), readTasks(path)]);
-        return {
-            id,
-            state: 'ready',
-            jigVersion: v,
-            counts: count(tasks),
-            attention: status.attention,
-            housekeepingStale: status.housekeepingStale,
-        };
+        return await read(path, v);
     }
     catch (error) {
         if (error instanceof JigShapeError)
@@ -59,21 +90,188 @@ async function view({ id, path }) {
         return { id, state: 'unreadable', code: error instanceof JigRefusal ? error.code : 'failed' };
     }
 }
-/** The local adapter: the registry in the config directory, and Jig run in each main checkout. */
-export function localSource(configDir) {
+async function readProject(project) {
+    const read = await reading(project, async (root, jigVersion) => {
+        const [status, list, specs] = await Promise.all([readStatus(root), readTasks(root), readSpecs(root)]);
+        return { status, list, specs, jigVersion };
+    });
+    if (!('list' in read))
+        return { view: read, tasks: read, details: [], specs: read, revision: null };
+    const { status, list, specs, jigVersion } = read;
+    // Jig's live list holds active and ready tasks only.
+    const live = list.tasks.filter((t) => t.status === 'active' || t.status === 'ready');
+    return {
+        view: {
+            id: project.id,
+            state: 'ready',
+            jigVersion,
+            counts: count(list.tasks),
+            attention: status.attention,
+            housekeepingStale: status.housekeepingStale,
+        },
+        tasks: { state: 'ready', tasks: live.map(card), finished: list.hidden },
+        details: live.map((t) => details(t, status.attention)),
+        specs: { state: 'ready', specs },
+        revision: list.revision,
+    };
+}
+/** A read that may have caught Jig mid-write: worth one more try before it is believed. */
+const torn = (read) => read.view.state === 'unreadable' || read.view.state === 'incompatible';
+/**
+ * The local adapter: the registry in the config directory, Jig run in each main checkout, and a
+ * Watcher on each project's `.ai/` while someone listens. Then reads are served from what the
+ * watch last read, and a change is signalled only when a new read differs from it.
+ */
+export function localSource(configDir, { rescanMs = 60_000, quietMs, maxWaitMs } = {}) {
+    const entries = new Map();
+    const listeners = new Set();
+    let rescan;
+    /** Counts the times following started; a read that finishes after a stop belongs to none. */
+    let session = 0;
+    const following = () => rescan !== undefined;
+    const entryOf = (project) => {
+        let entry = entries.get(project.id);
+        if (!entry)
+            entries.set(project.id, (entry = { project, held: false, dirty: false }));
+        return entry;
+    };
+    /** Keeps what was shown over one torn read; otherwise the read is what the project shows. */
+    function settle(entry, read) {
+        if (torn(read) && entry.shown && !torn(entry.shown) && !entry.held) {
+            entry.held = true;
+            return;
+        }
+        entry.held = false;
+        entry.shown = read;
+        entry.readIn = following() ? session : undefined;
+    }
+    /** Reads the project again — one read at a time — and signals when what it shows changed. */
+    function refresh(entry) {
+        if (entry.reading) {
+            entry.dirty = true;
+            return entry.reading;
+        }
+        entry.reading = (async () => {
+            do {
+                entry.dirty = false;
+                const before = JSON.stringify(entry.shown);
+                settle(entry, await readProject(entry.project));
+                if (following() && entries.get(entry.project.id) === entry && JSON.stringify(entry.shown) !== before) {
+                    signal({ id: entry.project.id, revision: entry.shown?.revision ?? null });
+                }
+            } while (entry.dirty);
+        })().finally(() => (entry.reading = undefined));
+        return entry.reading;
+    }
+    function signal(change) {
+        for (const listener of listeners)
+            listener(change);
+    }
+    /** What the project shows: from the watch while following, read through Jig otherwise. */
+    async function shown(project) {
+        const entry = entryOf(project);
+        if (!(following() && entry.shown && entry.readIn === session))
+            await (entry.reading ?? refresh(entry));
+        return entry.shown;
+    }
+    function follow(entry) {
+        if (entry.watch?.open)
+            return;
+        entry.watch = watchTree(watchDir(entry.project.path), {
+            ignore: writtenByReads,
+            onChange: () => void refresh(entry),
+            quietMs,
+            maxWaitMs,
+        });
+    }
+    /**
+     * Follows every registered project and reads it again; forgets one no longer registered, such as
+     * one a read in flight brought back after its disconnect.
+     */
+    async function sweep() {
+        // An unreadable registry is the page's to show, through its own read.
+        const projects = await readProjects(configDir).catch(() => undefined);
+        if (!projects || !following())
+            return;
+        const ids = new Set(projects.map((p) => p.id));
+        for (const [id, entry] of entries) {
+            if (ids.has(id))
+                continue;
+            entry.watch?.close();
+            entries.delete(id);
+        }
+        for (const project of projects) {
+            const entry = entryOf(project);
+            follow(entry); // a watcher that failed, or a directory that came back
+            void refresh(entry);
+        }
+    }
+    function start() {
+        session++;
+        rescan = setInterval(() => void sweep(), rescanMs);
+        rescan.unref();
+        void sweep();
+    }
+    /** Stops following; what was read while following may be old by the next subscribe, so it goes. */
+    function stop() {
+        clearInterval(rescan);
+        rescan = undefined;
+        for (const entry of entries.values()) {
+            entry.watch?.close();
+            entry.watch = undefined;
+            entry.shown = undefined;
+            entry.held = false;
+        }
+    }
     return {
         async workspace() {
-            return Promise.all((await readProjects(configDir)).map(view));
+            return Promise.all((await readProjects(configDir)).map(async (p) => (await shown(p)).view));
         },
         async connect(path) {
             const found = await connectable(path);
             if ('code' in found)
                 return found;
             const { project, created } = await addProject(configDir, found.root);
-            return { project: await view(project), created };
+            const entry = entryOf(project);
+            if (following())
+                follow(entry);
+            await refresh(entry);
+            return { project: entry.shown.view, created };
+        },
+        async tasks(id) {
+            const project = (await readProjects(configDir)).find((p) => p.id === id);
+            return project && (await shown(project)).tasks;
+        },
+        async task(id, taskId) {
+            const project = (await readProjects(configDir)).find((p) => p.id === id);
+            if (!project)
+                return undefined;
+            const read = await shown(project);
+            if (read.tasks.state !== 'ready')
+                return read.tasks;
+            return { state: 'ready', task: read.details.find((t) => t.id === taskId) ?? null };
+        },
+        async specs(id) {
+            const project = (await readProjects(configDir)).find((p) => p.id === id);
+            return project && (await shown(project)).specs;
+        },
+        async disconnect(id) {
+            if (!(await removeProject(configDir, id)))
+                return false;
+            entries.get(id)?.watch?.close();
+            entries.delete(id);
+            if (following())
+                signal({ id, revision: null });
+            return true;
         },
-        disconnect(id) {
-            return removeProject(configDir, id);
+        subscribe(listener) {
+            listeners.add(listener);
+            if (!following())
+                start();
+            return () => {
+                if (listeners.delete(listener) && listeners.size === 0)
+                    stop();
+            };
         },
     };
 }