@wjarka/cezarion 0.14.8 → 0.14.9-dev.1004

package/dist/server/server.js

@@ -1,6 +1,6 @@
 import { DelegationService } from '../delegation/service.js';
 import { delegationFailure } from '../delegation/routes.js';
-import { workerEmptyRequestSchema, runRelationshipsSchema, runDelegationSummarySchema } from '../contract/index.js';
+import { CLIENT_REQUEST_VARIANTS_ERROR, workerEmptyRequestSchema, runRelationshipsSchema, runDelegationSummarySchema } from '../contract/index.js';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { AutomationStore } from '../automations/store.js';
@@ -17,9 +17,10 @@ import { serve } from '@hono/node-server';
 import { bodyLimit } from 'hono/body-limit';
 import { streamSSE } from 'hono/streaming';
 import { jsonZodValidator, paramZodValidator, queryZodValidator } from './validators.js';
+import { deliverOnce, TaskWebhooks } from '../runs/webhook.js';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { z } from 'zod';
-import { repoPullInputSchema, pinRunInputSchema, githubSearchQuerySchema, setWorkspaceUiStateInputSchema, } from '../contract/index.js';
+import { repoPullInputSchema, pinRunInputSchema, notifyRunInputSchema, githubSearchQuerySchema, setWorkspaceUiStateInputSchema, } from '../contract/index.js';
 // A contract VALUE, like `workspaceUiStateSchema` in workspace/migrations.ts — the request
 // schema this route validates with is the same one the client compiles against.
 import { MODEL_DISCOVERY_RUNNERS, attachmentInputSchema, attachmentFileParamSchema, modelDiscoveryRunnerSchema, openProjectInSchema, runnerDiscoversModels, updateProjectInputSchema, } from '../contract/index.js';
@@ -41,10 +42,14 @@ import { appendHandoffHeartbeat, handoffProgressExcerpt, readHandoff } from '../
 import { markStarted, onTodosChanged, readTodos, removeTodo, todoTaskText } from '../todos.js';
 import { HistoryCursorError, deriveRunContextEvents, readEventsAfterLiveCursor, readRunHistoryPage, validateLiveCursor, } from '../runs/event-history.js';
 import { readRunIndexFromDisk } from '../runs/run-index.js';
+import { clientRequestHash } from '../runs/client-request.js';
 import { ColdRepoHandles } from './cold-repo-handles.js';
 import { isV2WireEventType } from '../runs/ui-event-sink.js';
 import { runEventsQuerySchema, runHistoryQuerySchema, runIdParamSchema, } from '../contract/index.js';
 import { resolveAttachmentPath } from '../workflows/attachment-path.js';
+import { artifactParamsSchema, fileLinkQuerySchema } from '../contract/index.js';
+import { artifactDirectory, listArtifacts, readArtifact } from '../artifacts/store.js';
+import { artifactPreview, loadFileLink, rasterMime } from '../artifacts/resolve.js';
 import { isUntouchedCancelledRun, toPastedContent } from '../workflows/run.js';
 import { removeWorktree, worktreeDiff, worktreeDiffStat, worktreeSizeBytes } from '../git-worktree.js';
 import { isReclaimable, reclaimWorktrees } from '../runs/retention.js';
@@ -64,7 +69,7 @@ import { defaultAgentProfile, listAgentProfiles, profileDirState, resolveProfile
 import { PROFILE_CAPABLE_PROVIDERS, profileEnv, supportsProfiles } from '../core/agent-profiles.js';
 import { quoteExecutable, withEnvPrefix } from '../core/shell-env.js';
 import { resolveCursorExecutable } from '../core/cursor-model-catalog.js';
-import { allocateProjectSlug, listProjects, normalizeProjectTags, probeProjectStatus, registerProject, removeProject, shouldRegisterProject, } from '../workspace/projects.js';
+import { allocateProjectSlug, listProjects, normalizeProjectTags, probeProjectStatus, toProjectListEntry, registerProject, removeProject, shouldRegisterProject, } from '../workspace/projects.js';
 import { mergeWriteWorkspaceUiState, readWorkspaceUiState } from '../workspace/ui-state.js';
 import { checkoutRepo } from './checkout.js';
 import { ProjectContextError, ProjectContexts } from './project-context.js';
@@ -72,6 +77,8 @@ import { reviewGateEnabled } from '../runs/review-gate.js';
 import { readUiState, uiStatePath } from '../ui-state.js';
 import { agentHomePaths, expandTilde } from '../paths.js';
 import { isLoopbackHostHeader, normalizeHostname, resolveCapabilities } from './capabilities.js';
+import { applicationUpdateInputSchema } from '../contract/index.js';
+import { ApplicationUpdateConflictError, ApplicationUpdateFailureError } from '../application-update/service.js';
 import { createSocketHub } from './ws.js';
 import { browseDirectory, isInsideBrowseRoot, isLexicallyInsideBrowseRoot, resolveBrowseRoot } from './fs-browse.js';
 import { parseRemote, resolveForge } from './forge/index.js';
@@ -304,9 +311,16 @@ const startRunSchema = z
     // audit trail survives the composer detour. Bounded like every other
     // string here; a todo id is a short generated key.
     todoId: z.string().min(1).max(200, 'must be at most 200 characters').optional(),
+    // Idempotent start (#504): the same id and payload answer 200 with the existing run.
+    clientRequestId: z.string().uuid().optional(),
+    // Task webhook opt-in (#589). Absent = off; not part of the idempotency hash.
+    notify: z.boolean().optional(),
 })
     .refine((b) => Boolean(b.workflow) !== Boolean(b.steps), {
     message: 'provide either "workflow" or "steps", not both',
+})
+    .refine((b) => !(b.clientRequestId && (b.variants ?? 1) > 1), {
+    message: CLIENT_REQUEST_VARIANTS_ERROR,
 });
 const pickSchema = z.object({
     runId: z.string().min(1),
@@ -811,6 +825,11 @@ export function createApp(deps) {
         automationStore: deps.automationStore ?? AutomationStore.open(bootDataDir),
         launchKey: ensureLaunchKey(bootDataDir), // bookmarklet auto-start secret (spec 011)
     };
+    // The task webhook (#589): attached before any recovery — the boot store by `index.ts`, lazy
+    // projects through `prepareManager` below. Attaching is idempotent, so the calls here only
+    // cover an app built without boot's wiring (tests, embedded servers).
+    const taskWebhooks = deps.taskWebhooks ?? new TaskWebhooks({ fetch: deps.taskWebhookFetch, origin: '' });
+    taskWebhooks.attach(bootContext);
     // Non-boot projects build lazily on first scoped request; their managers
     // count against the same workspace semaphore as the boot manager (step 2.5).
     const contexts = deps.contexts ?? new ProjectContexts({
@@ -821,7 +840,10 @@ export function createApp(deps) {
             return listProjects(selector);
         },
         semaphore: deps.semaphore,
-        prepareManager: project => deps.delegation?.attachProject(project),
+        prepareManager: (project) => {
+            taskWebhooks.attach(project);
+            return deps.delegation?.attachProject(project);
+        },
     });
     // Workspace-level SSE bus (step 2.8) — the registry mutators and the
     // checkout flow (Phase 4) emit here; /api/workspace/events relays.
@@ -845,6 +867,17 @@ export function createApp(deps) {
     }
     contexts.onStoreCreated((store) => providerRuntimeAuth.watch(store));
     contexts.onContextBuilt((ctx) => providerRuntimeAuth.watch(ctx.store));
+    // Injected contexts (tests) skip `prepareManager`; attach those when they are built.
+    for (const id of contexts.ids()) {
+        const ctx = contexts.peek(id);
+        if (ctx)
+            taskWebhooks.attach(ctx);
+    }
+    contexts.onContextBuilt((ctx) => taskWebhooks.attach(ctx));
+    const projectRegistryEntry = async (projectId) => {
+        const id = projectId === 'default' ? await resolveBootProject() : projectId;
+        return (await loadWorkspaceConfig()).projects.find((entry) => entry.id === id);
+    };
     const app = new Hono();
     // Reject oversized request bodies before they reach any handler (#429). GETs
     // and SSE carry no body, so this only ever gates the mutating routes.
@@ -1088,6 +1121,9 @@ export function createApp(deps) {
             // the key as always-present, which is a shape no client ever receives. The contract schema
             // says `.optional()`, and contract-parity.test.ts holds the two together.
             ...(update?.latest !== undefined ? { latestVersion: update.latest } : {}),
+            ...(deps.applicationUpdate ? { applicationUpdate: caps.localHandoff
+                    ? deps.applicationUpdate.snapshot()
+                    : { status: 'idle', supported: false, message: 'Update this installation manually.' } } : {}),
             // Health is CORS-open and, in hosted mode, reachable off the loopback —
             // so any site/host that reads it would learn the developer's absolute
             // checkout path and username (#431). Local mode keeps the full path (the
@@ -1163,6 +1199,10 @@ export function createApp(deps) {
         })();
         return healthInFlight;
     };
+    deps.applicationUpdate?.onStateChange?.(() => {
+        healthCache = undefined;
+        void refreshHealth();
+    });
     // The read the GET and the topic snapshot share. On the live server (a hub is
     // injected) it answers from cache instantly and revalidates behind the
     // response; without a hub — a bare app in tests — there is no refresher
@@ -2039,7 +2079,7 @@ export function createApp(deps) {
         const parsed = { data: c.req.valid('json') };
         // `default` is the boot alias the cockpit is allowed to use everywhere else.
         const id = raw === 'default' ? await resolveBootProject() : raw;
-        const { maxParallel, tags } = parsed.data;
+        const { maxParallel, tags, webhook } = parsed.data;
         // Read-first (mirroring DELETE, server.ts:1252-1258): a well-formed but
         // unknown id must 404 WITHOUT rewriting the config — otherwise it would both
         // do a needless full-config tmp+rename and, on a read-only home, surface the
@@ -2081,6 +2121,16 @@ export function createApp(deps) {
                     else
                         entry.tags = normalized;
                 }
+                if (webhook !== undefined) {
+                    // The token is write-only (#589): the form never has it back, so an omitted token
+                    // keeps the stored one and only `''` clears it.
+                    if (webhook === null)
+                        delete entry.webhook;
+                    else {
+                        const token = webhook.token === undefined ? entry.webhook?.token : webhook.token || undefined;
+                        entry.webhook = { url: webhook.url, ...(token ? { token } : {}) };
+                    }
+                }
                 updated = entry;
             });
         }
@@ -2096,7 +2146,41 @@ export function createApp(deps) {
         // `PUT /api/workspace/config` fires for a workspace-cap change.
         await deps.semaphore?.refresh();
         const body = {
-            project: { ...updated, ...(await probeProjectStatus(updated.root)) },
+            project: toProjectListEntry(updated, await probeProjectStatus(updated.root)),
+        };
+        return c.json(body);
+    })
+        // "Send test" (#589): one `task.test` delivery to the STORED webhook, now, with the timeout
+        // the real deliveries use and no retries — the settings page wants the answer, not a queue.
+        // Refused in single-project mode like every other registry edit route.
+        .post('/projects/:projectId/webhook/test', async (c) => {
+        if (capabilities().singleProject) {
+            return c.json(singleProjectRefusal('editing projects'), 409);
+        }
+        const raw = c.req.param('projectId');
+        if (!projectIdSchema.safeParse(raw).success) {
+            return c.json({ error: `unknown project: ${raw}` }, 404);
+        }
+        const entry = await projectRegistryEntry(raw).catch(() => undefined);
+        if (!entry)
+            return c.json({ error: `unknown project: ${raw}` }, 404);
+        if (!entry.webhook)
+            return c.json({ error: NO_WEBHOOK_ERROR }, 400);
+        const payload = {
+            event: 'task.test',
+            deliveryId: randomUUID(),
+            projectId: entry.id,
+            occurredAt: new Date().toISOString(),
+        };
+        if (process.env.CEZ_DRY_RUN === '1') {
+            const body = { ok: true, dryRun: true };
+            return c.json(body);
+        }
+        const result = await deliverOnce(entry.webhook, payload, { fetch: deps.taskWebhookFetch });
+        const body = {
+            ok: result.ok,
+            ...(result.status === undefined ? {} : { status: result.status }),
+            ...(result.error === undefined ? {} : { error: result.error }),
         };
         return c.json(body);
     })
@@ -2232,7 +2316,7 @@ export function createApp(deps) {
         let project;
         try {
             const entry = await registerProject(requested, source);
-            project = { ...entry, ...(await probeProjectStatus(entry.root)) };
+            project = toProjectListEntry(entry, await probeProjectStatus(entry.root));
         }
         catch (err) {
             // e.g. a read-only home — nothing was persisted (atomic tmp+rename).
@@ -2342,6 +2426,32 @@ export function createApp(deps) {
             throw error;
         }
     });
+    // Workspace-level, server-selected target and executable. The empty JSON body is strict.
+    const applicationUpdateRoutes = new Hono()
+        .post('/workspace/application-update/apply', jsonZodValidator(applicationUpdateInputSchema), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json({ error: 'Application updates require a local cockpit.' }, 409);
+        if (!deps.applicationUpdate)
+            return c.json({ error: 'Application update is unavailable.' }, 409);
+        try {
+            return c.json({ state: await deps.applicationUpdate.apply() });
+        }
+        catch (error) {
+            return c.json({ error: error instanceof ApplicationUpdateConflictError || error instanceof ApplicationUpdateFailureError ? error.message : 'Application update preparation failed.' }, error instanceof ApplicationUpdateConflictError ? 409 : error instanceof ApplicationUpdateFailureError ? error.status : 500);
+        }
+    })
+        .post('/workspace/application-update/restart', jsonZodValidator(applicationUpdateInputSchema), async (c) => {
+        if (!capabilities().localHandoff)
+            return c.json({ error: 'Application updates require a local cockpit.' }, 409);
+        if (!deps.applicationUpdate)
+            return c.json({ error: 'Application update is unavailable.' }, 409);
+        try {
+            return c.json({ state: await deps.applicationUpdate.restart() });
+        }
+        catch (error) {
+            return c.json({ error: error instanceof ApplicationUpdateConflictError ? error.message : 'Application restart is unavailable.' }, error instanceof ApplicationUpdateConflictError ? 409 : 500);
+        }
+    });
     // ---- GUI clone (multi-project spec, step 4.3) ----------------------------
     // "Add project → Clone from GitHub": clone into the checkout root, then
     // register the result through `registerFolder` above (same guards, same
@@ -2891,7 +3001,7 @@ export function createApp(deps) {
         automationsChanged();
         return c.body(null, 204);
     })
-        .post('/automations/:id/enable', (c) => {
+        .post('/automations/:id/enable', async (c) => {
         const store = c.get('project').automationStore;
         const current = store.get(c.req.param('id'));
         if (!current)
@@ -2905,7 +3015,7 @@ export function createApp(deps) {
             cursor: { timestamp: baselineAt },
             nextCheckAt: new Date(Date.now() + automation.intervalSeconds * 1_000).toISOString(),
         });
-        store.appendLog({ automationId: automation.id, revision: automation.revision, result: 'baseline', reason: 'Enabled from a current-time baseline; existing records were not launched.' });
+        await store.appendLog({ automationId: automation.id, revision: automation.revision, result: 'baseline', reason: 'Enabled from a current-time baseline; existing records were not launched.' });
         emitAutomationChange(c.get('project'), automation.id, automation.revision);
         automationsChanged();
         return c.json({ automation });
@@ -3044,6 +3154,7 @@ export function createApp(deps) {
     };
     // ---- chained family: runs lifecycle + artifacts (project-scoped) ----
     const delegationService = deps.delegation?.service ?? new DelegationService();
+    delegationService.setDiscovery({ models: modelCatalog, providers: providerStatus });
     const runsRoutes = new Hono()
         .get('/runs', (c) => c.json(c.get('project').store.listRuns().map(run => withUsage(run))))
         .get('/runs/:id/relationships', paramZodValidator(runIdParamSchema), queryZodValidator(workerEmptyRequestSchema), (c) => {
@@ -3105,6 +3216,34 @@ export function createApp(deps) {
         const { store } = c.get('project');
         const run = store.setPinned(c.req.valid('param').id, c.req.valid('json').pinned !== false);
         return run ? c.json(run) : c.json({ error: 'not found' }, 404);
+    })
+        // Task webhook opt-in for one run (#589), valid in every state — handing a finished task to a
+        // bot for follow-up is a real case. Turning it on sends one `task.subscribed` delivery with
+        // the note; the note never reaches the agent session. Either direction leaves a durable
+        // `handoff` event so the thread shows when and why. Idempotent: repeating `true` with a
+        // new note is how "Send a note…" works.
+        .post('/runs/:id/notify', paramZodValidator(runIdParamSchema), jsonZodValidator(notifyRunInputSchema), async (c) => {
+        const project = c.get('project');
+        const { id } = c.req.valid('param');
+        const { notify, message } = c.req.valid('json');
+        if (!project.store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        if (notify) {
+            const entry = await projectRegistryEntry(project.id).catch(() => undefined);
+            if (!entry?.webhook)
+                return c.json({ error: NO_WEBHOOK_ERROR }, 400);
+        }
+        const run = project.store.updateRun(id, { notify: notify ? true : undefined });
+        if (!run)
+            return c.json({ error: 'not found' }, 404);
+        project.store.appendEvent(id, {
+            type: 'handoff',
+            notify,
+            ...(message === undefined ? {} : { message }),
+        });
+        if (notify)
+            taskWebhooks.attach(project).subscribed(id, message);
+        return c.json(run);
     })
         // The per-task off switch for that resume (the workspace setting is Settings → Resources).
         // Idempotent: a run with nothing pending answers 200 too, because "this task will not
@@ -3131,8 +3270,21 @@ export function createApp(deps) {
         return run ? c.json(run) : c.json({ error: 'not found' }, 404);
     })
         .post('/runs', jsonZodValidator(startRunSchema), async (c) => {
-        const { root: repoRoot, dataDir, manager } = c.get('project');
+        const { root: repoRoot, dataDir, manager, store } = c.get('project');
         const parsed = { data: c.req.valid('json') };
+        const clientRequest = parsed.data.clientRequestId
+            ? { id: parsed.data.clientRequestId, hash: clientRequestHash(parsed.data) }
+            : undefined;
+        // A retry only retrieves a persisted result: mutable start prerequisites (workflow,
+        // provider, account and model policy) must not invalidate an already accepted request.
+        if (clientRequest) {
+            const existing = store.findRunByClientRequestId(clientRequest.id);
+            if (existing) {
+                if (existing.clientRequestHash !== clientRequest.hash)
+                    return c.json({ error: 'request id payload conflict' }, 409);
+                return c.json(existing, 200);
+            }
+        }
         if (agentModelsLocked(repoRoot) &&
             (parsed.data.model?.trim() || parsed.data.effort?.trim())) {
             return c.json({ error: AGENT_MODELS_LOCKED_ERROR }, 409);
@@ -3168,9 +3320,15 @@ export function createApp(deps) {
             if ('error' in account)
                 return c.json({ error: account.error }, 400);
         }
+        // Task webhook (#589): an explicit `true` on a project with no webhook is refused, so a
+        // bot learns in one round trip. `cez task start`'s implicit default never sends it there.
+        if (parsed.data.notify === true && !(await projectRegistryEntry(c.get('project').id).catch(() => undefined))?.webhook) {
+            return c.json({ error: NO_WEBHOOK_ERROR }, 400);
+        }
         const images = parsed.data.images?.map(toPastedContent);
         const input = {
             task: parsed.data.task,
+            notify: parsed.data.notify,
             model: parsed.data.model,
             effort: parsed.data.effort,
             runner: parsed.data.runner,
@@ -3186,6 +3344,18 @@ export function createApp(deps) {
             // CEZ_TODOS_FILE alike (RunManager.agentEnv).
             generateFollowups: capabilities().followups ? parsed.data.generateFollowups : false,
         };
+        if (clientRequest) {
+            // Recheck after every await: concurrent first requests may both miss the early lookup.
+            // The manager's lookup and create are synchronous, so exactly one can create (#504).
+            const result = manager.startRunIdempotent(workflow, input, clientRequest);
+            if ('conflict' in result)
+                return c.json({ error: 'request id payload conflict' }, 409);
+            if (!result.created)
+                return c.json(result.run, 200);
+            if (parsed.data.todoId)
+                await noteTodoStarted(dataDir, parsed.data.todoId, result.run.id);
+            return c.json(result.run, 201);
+        }
         const variants = parsed.data.variants ?? 1;
         if (variants > 1) {
             // Variants live in worktrees — without git there's nothing to isolate
@@ -3703,6 +3873,70 @@ export function createApp(deps) {
         if (!result.ok)
             return c.json({ error: result.error }, 409);
         return c.json(result.commit);
+    })
+        .get('/runs/:id/file-link', paramZodValidator(artifactParamsSchema.omit({ artifactId: true })), queryZodValidator(fileLinkQuerySchema), async (c) => {
+        const { root, dataDir, store } = c.get('project');
+        const run = store.getRun(c.req.valid('param').id);
+        if (!run)
+            return c.json({ error: 'not found' }, 404);
+        const query = c.req.valid('query');
+        const loaded = await loadFileLink({ dataDir, runId: run.id, projectRoot: root, workingDirectory: run.worktreePath ?? root, path: query.path });
+        if (query.raw === '1') {
+            if (!loaded.imageBytes || loaded.preview.type !== 'file')
+                return c.json({ error: 'Only bounded raster images can be served inline.' }, 409);
+            return c.body(new Uint8Array(loaded.imageBytes).buffer, 200, {
+                'content-type': rasterMime(loaded.preview.path), 'x-content-type-options': 'nosniff',
+                'content-security-policy': "default-src 'none'; sandbox", 'cache-control': 'private, no-store',
+            });
+        }
+        return c.json(loaded.preview);
+    })
+        .get('/runs/:id/artifacts', paramZodValidator(artifactParamsSchema.omit({ artifactId: true })), async (c) => {
+        const { dataDir, store } = c.get('project');
+        const id = c.req.valid('param').id;
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        return c.json({ artifacts: await listArtifacts(artifactDirectory(dataDir, id), id) });
+    })
+        .get('/runs/:id/artifacts/:artifactId', paramZodValidator(artifactParamsSchema), async (c) => {
+        const { dataDir, store } = c.get('project');
+        const { id, artifactId } = c.req.valid('param');
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        const entry = await readArtifact(artifactDirectory(dataDir, id), id, artifactId);
+        if (!entry)
+            return c.json({ error: 'Published file is missing or unavailable.' }, 404);
+        return c.json(artifactPreview(entry.metadata, entry.bytes));
+    })
+        .get('/runs/:id/artifacts/:artifactId/download', paramZodValidator(artifactParamsSchema), async (c) => {
+        const { dataDir, store } = c.get('project');
+        const { id, artifactId } = c.req.valid('param');
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        const entry = await readArtifact(artifactDirectory(dataDir, id), id, artifactId);
+        if (!entry)
+            return c.json({ error: 'Published file is missing or unavailable.' }, 404);
+        return c.body(new Uint8Array(entry.bytes).buffer, 200, {
+            'content-type': 'application/octet-stream', 'x-content-type-options': 'nosniff',
+            'content-disposition': `attachment; filename="${entry.metadata.name.replace(/[^A-Za-z0-9._-]/g, '_')}"`,
+            'content-security-policy': "default-src 'none'; sandbox", 'cache-control': 'private, no-store',
+        });
+    })
+        .get('/runs/:id/artifacts/:artifactId/image', paramZodValidator(artifactParamsSchema), async (c) => {
+        const { dataDir, store } = c.get('project');
+        const { id, artifactId } = c.req.valid('param');
+        if (!store.getRun(id))
+            return c.json({ error: 'not found' }, 404);
+        const entry = await readArtifact(artifactDirectory(dataDir, id), id, artifactId);
+        if (!entry)
+            return c.json({ error: 'Published file is missing or unavailable.' }, 404);
+        const mime = rasterMime(entry.metadata.name);
+        if (!mime)
+            return c.json({ error: 'Only raster images can be served inline.' }, 409);
+        return c.body(new Uint8Array(entry.bytes).buffer, 200, {
+            'content-type': mime, 'x-content-type-options': 'nosniff',
+            'content-security-policy': "default-src 'none'; sandbox", 'cache-control': 'private, no-store',
+        });
     })
         // Files tab: directory listing (path omitted or a dir) or file content
         // (size-capped, binary flagged). Traversal-safe — readWorktreePath rejects
@@ -4052,7 +4286,10 @@ export function createApp(deps) {
         // The keep-limit the panel reports is the one the enforcer will actually
         // apply — inherited from the workspace default when this repo sets none.
         const keep = await resolveWorktreeRetention(repoRoot);
-        const runs = store.listRuns().filter((r) => r.worktreePath && existsSync(r.worktreePath));
+        const allRuns = store.listRuns();
+        // Listing is on-disk dirs only; parent liveness for #575 uses the full store
+        // so a live `worktree: false` parent is not treated as gone (#570 honesty).
+        const runs = allRuns.filter((r) => r.worktreePath && existsSync(r.worktreePath));
         const worktrees = await Promise.all(runs.map(async (r) => ({
             runId: r.id,
             title: r.title ?? r.id,
@@ -4061,7 +4298,7 @@ export function createApp(deps) {
             // POSIX `du` — degrades to null (Windows / du missing / error); never blocks.
             sizeBytes: await worktreeSizeBytes(r.worktreePath),
             finishedAt: r.finishedAt ?? null,
-            reclaimable: isReclaimable(r),
+            reclaimable: isReclaimable(r, allRuns),
         })));
         // Total is null when any size degraded, so the panel never shows a wrong sum.
         const totalBytes = worktrees.some((w) => w.sizeBytes === null)
@@ -5080,6 +5317,7 @@ export function createApp(deps) {
         .route('/', projectsRoutes)
         .route('/', agentProfilesRoutes)
         .route('/', skillsUpdateRoutes)
+        .route('/', applicationUpdateRoutes)
         .route('/', workspaceConfigRoutes)
         .route('/', fsBrowseRoutes)
         .route('/', automationChecksRoutes)
@@ -5110,6 +5348,13 @@ export function createApp(deps) {
     routed.get('*', (c) => serveShell(c) ?? c.notFound());
     return routed;
 }
+/** The host a thread link names (#589): the bound one, or loopback for a wildcard bind. */
+function taskWebhookHost(bindHost) {
+    if (!bindHost || bindHost === '0.0.0.0' || bindHost === '::')
+        return '127.0.0.1';
+    return bindHost.includes(':') ? `[${bindHost}]` : bindHost;
+}
+const NO_WEBHOOK_ERROR = 'this project has no task webhook — set one in Settings → General → Task webhook, or start without notify';
 export function startServer(deps, port) {
     const workspaceEvents = deps.workspaceEvents ?? new WorkspaceEventBus();
     const skillsUpdate = deps.skillsUpdate ?? new SkillsUpdateService({ invalidateCatalog: refreshTeamSkills });
@@ -5119,11 +5364,15 @@ export function startServer(deps, port) {
     const automationCoordinator = new AutomationCoordinator({ listProjects });
     const bootProjectId = deps.bootProjectId ?? 'default';
     const bootAutomationStore = automationCoordinator.store(bootProjectId, deps.repoRoot);
+    const taskWebhooks = deps.taskWebhooks ?? new TaskWebhooks({ fetch: deps.taskWebhookFetch });
     const sharedContexts = deps.contexts ?? new ProjectContexts({
         listProjects,
         semaphore: deps.semaphore,
         automationStore: (projectId, root) => automationCoordinator.store(projectId, root),
-        prepareManager: project => deps.delegation?.attachProject(project),
+        prepareManager: (project) => {
+            taskWebhooks.attach(project);
+            return deps.delegation?.attachProject(project);
+        },
     });
     // #801: GitHub automations are opt-in. Off, the flag must remove the BEHAVIOR and not merely
     // the UI — no scheduler, no GitHub polling, no launched runs — so every entry point into the
@@ -5133,6 +5382,7 @@ export function startServer(deps, port) {
     let rescheduleAutomations = () => { };
     const app = createApp({
         ...deps,
+        taskWebhooks,
         contexts: sharedContexts,
         automationStore: bootAutomationStore,
         workspaceEvents,
@@ -5146,7 +5396,28 @@ export function startServer(deps, port) {
     // hosted/VPS deployment (which also flips CEZ_REMOTE to gate the local-handoff endpoints) —
     // src/index.ts never passes it, so the loopback guarantee holds for the normal CLI.
     const server = serve({
-        fetch: app.fetch,
+        fetch: async (request, env) => {
+            const result = await app.fetch(request, env);
+            if (request.method === 'POST' && new URL(request.url).pathname === '/api/v1/workspace/application-update/restart'
+                && result.status === 200) {
+                // Arming is server-owned. A connected caller must receive the complete
+                // acknowledgement before shutdown; a caller that already disconnected
+                // cannot leave its explicitly requested, armed restart stranded.
+                const response = env.outgoing;
+                const handoff = () => {
+                    response.off('finish', handoff);
+                    response.off('close', handoff);
+                    deps.applicationUpdate?.afterResponse?.();
+                };
+                if (response.destroyed)
+                    handoff();
+                else {
+                    response.once('finish', handoff);
+                    response.once('close', handoff);
+                }
+            }
+            return result;
+        },
         port,
         hostname: deps.bindHost ?? '127.0.0.1',
     });
@@ -5239,7 +5510,30 @@ export function startServer(deps, port) {
     });
     server.once('close', () => { unsubscribe(); coordinator.stop(); automationScheduler.stop(); sharedContexts.disposeAll(); void deps.delegation?.close(); });
     socketHub.attach(server, (req) => verifyWsUpgrade(req, deps.bindHost));
-    return server;
+    const shutdownForRestart = async () => {
+        sharedContexts.disposeAll(); // flush every built secondary project before old process exits
+        deps.store.flush();
+        socketHub.close();
+        await deps.delegation?.close();
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+            if ('closeAllConnections' in server)
+                server.closeAllConnections();
+        });
+    };
+    // The task webhook's thread links name the port the listener BOUND (#594 review): `--port 0`
+    // asks for an ephemeral one, so the requested number is not an address. Deliveries queue
+    // behind this, so none goes out before it is set.
+    const setTaskWebhookOrigin = () => {
+        const address = server.address();
+        const bound = address && typeof address === 'object' ? address.port : port;
+        taskWebhooks.setOrigin(`http://${taskWebhookHost(deps.bindHost)}:${bound}`);
+    };
+    if (server.listening)
+        setTaskWebhookOrigin();
+    else
+        server.once('listening', setTaskWebhookOrigin);
+    return Object.assign(server, { shutdownForRestart });
 }
 /**
  * The WebSocket twin of the `/api/*` request-origin guard (#426), applied