@netnodeag/kraftwerk 0.39.0 → 0.40.0

package/README.md

@@ -385,10 +385,35 @@ session, errors) lives in `<output>/routines-state.json`.
 The inspector server runs the scheduler in-process, so there is no external
 cron to set up. Every due routine opens a fresh session for the agent, posts
 the prompt, and shows up in the sessions sidebar titled "⏰ <name>". Routine
-sessions run unattended, so tool-permission requests are auto-approved, with
-the request and approval pair left in the thread as an audit trail. Give
-routine prompts the same trust you would give a `KRAFTWERK_YES=1` workflow
-run. Manage routines on the agent page, where you can create, edit and
+sessions run unattended in the harness's own permission mode — your
+configured claude default (`auto` or `acceptEdits`; plain `default` is lifted
+to `acceptEdits`, `bypassPermissions` is never used) or codex's sandboxed
+`agent` preset (never full access). Edits inside the project need no
+approval, and the harness keeps deciding what still needs a human — shell
+commands, network, files outside the project. Kraftwerk never answers those for you.
+The question waits in the thread, the routine row and the agent card show
+"needs approval", and you allow or deny when you look; "allow always" is
+remembered by the harness so the same routine stops asking. A request nobody
+answers within 30 minutes is declined and the routine ends with a summary of
+what it could not do.
+
+The bell in the top bar collects what happened while you were away: a
+session waiting for approval, a routine that finished (with the first lines
+of its summary) or failed, a workflow run started from the inspector that
+ended. The unread count sits on the bell and in front of the tab title, so a
+background tab reads "(2) …"; click an item to jump there. Failure items
+carry a "diagnose" button: it opens a chat where the failure is best
+understood — the run folder for a failed workflow run, a fresh session of the
+same agent for a routine that died mid-run, the kraftwerk-aware chat for a
+routine that could not start — and sends a first message that names the
+failure, points at the evidence (trace, logs, the failed session's events)
+and asks for root cause, fix and how to re-run. Allow browser
+notifications once (the bell offers it) and each new item also shows as a
+system notification while any inspector tab is open. Items live in
+`output/notifications.json`; `GET /api/notifications` lists them,
+`POST /api/notifications/read` marks them, `DELETE /api/notifications` clears.
+
+Manage routines on the agent page, where you can create, edit and
 delete them, toggle enabled, hit "run now", and jump to the last run's
 session. Schedules missed while the server is down are skipped, not replayed.
 

package/dist/config.d.ts

@@ -42,6 +42,13 @@ export declare const CONFIG_FILENAMES: string[];
  * skills) plus kraftwerk.yml itself. Commit and push stay manual; the
  * interval only fetches, and pulls when `autosync` allows it.
  */
+/**
+ * A remote or branch name kraftwerk will hand to git as a positional
+ * argument. Git reads a leading dash as an option ("--upload-pack=<cmd>"
+ * runs a command), so such values are refused wherever they enter — config
+ * load, settings API — and the git calls add --end-of-options as well.
+ */
+export declare function isSafeGitName(value: string): boolean;
 export interface GitConfig {
     /** false keeps the block but turns the feature off. Default: true. */
     enabled?: boolean;

package/dist/config.js

@@ -41,6 +41,21 @@ export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk
 export const CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/kraftwerk.schema.json";
 export const CONFIG_FILENAMES = ["kraftwerk.yml", "kraftwerk.yaml"];
 const WORKFLOW_ROOT_CANDIDATES = ["src/workflows", "workflows"];
+/**
+ * Git sync for the workspace. The synced paths are not configurable: they
+ * are the roots this file already declares (workflows, knowledge, agents,
+ * skills) plus kraftwerk.yml itself. Commit and push stay manual; the
+ * interval only fetches, and pulls when `autosync` allows it.
+ */
+/**
+ * A remote or branch name kraftwerk will hand to git as a positional
+ * argument. Git reads a leading dash as an option ("--upload-pack=<cmd>"
+ * runs a command), so such values are refused wherever they enter — config
+ * load, settings API — and the git calls add --end-of-options as well.
+ */
+export function isSafeGitName(value) {
+    return value.length > 0 && !value.startsWith("-") && !/[\s\x00-\x1f]/.test(value);
+}
 /** Where clones land when `repos.root` is not set. */
 export const REPOS_DEFAULT_ROOT = "repos";
 /**
@@ -240,6 +255,9 @@ function validateGit(configPath, value) {
         if (g[key] !== undefined && (typeof g[key] !== "string" || !g[key].trim())) {
             throw new Error(`${file}: git.${key} must be a non-empty string`);
         }
+        if (typeof g[key] === "string" && !isSafeGitName(g[key].trim())) {
+            throw new Error(`${file}: git.${key} must be a plain name (no leading "-", no whitespace)`);
+        }
     }
     if (g.interval !== undefined && (typeof g.interval !== "number" || !Number.isInteger(g.interval) || g.interval < 0)) {
         throw new Error(`${file}: git.interval must be a whole number of seconds (0 disables the timer)`);

package/dist/inspector/chat/acp.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { fileURLToPath } from "node:url";
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, RequestError, } from "@agentclientprotocol/sdk";
+import { unattendedMode } from "./permissions.js";
 /**
  * ACP-backed chat: spawn an adapter (claude-agent-acp / codex-acp) as a
  * subprocess, speak Agent Client Protocol over its stdio, and translate
@@ -59,6 +60,12 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
             stderr = stderr.slice(-20_000);
     });
     let dead = false;
+    // Without a listener a failed spawn (cwd gone, node missing) is an
+    // unhandled 'error' event that takes the whole inspector down.
+    child.on("error", (err) => {
+        dead = true;
+        hooks.emit({ type: "error", message: `could not start the ${agent} agent: ${err.message}` });
+    });
     child.on("close", (code) => {
         dead = true;
         if (code !== 0 && code !== null) {
@@ -137,6 +144,22 @@ export async function startAcpBackend(agent, cwd, hooks, tuning = {}) {
             : {}),
     });
     const sessionId = session.sessionId;
+    if (tuning.unattended) {
+        // Nobody is watching: keep the harness's configured mode unless it is
+        // one that never asks (see unattendedMode). The harness keeps deciding
+        // which calls reach a human; kraftwerk only rules out "never ask".
+        const modeId = unattendedMode(agent, session.modes?.currentModeId);
+        if (modeId) {
+            // A mode the adapter does not offer must not kill the session: the
+            // harness default applies, and the thread shows why.
+            await conn.setSessionMode({ sessionId, modeId }).catch((err) => {
+                hooks.emit({
+                    type: "error",
+                    message: `could not select the ${modeId} mode for this unattended session (${err.message}) — the ${agent} default applies`,
+                });
+            });
+        }
+    }
     return {
         async prompt(text) {
             if (dead)

package/dist/inspector/chat/backend.d.ts

@@ -31,6 +31,12 @@ export interface BackendTuning {
     skillDirs?: string[];
     /** claude: extra directories the session may work in (e.g. project root for run chats). */
     addDirs?: string[];
+    /**
+     * Nobody is watching this session live (routine runs). The backend selects
+     * the harness's own hands-off permission mode — the harness keeps deciding
+     * what still needs a human; kraftwerk never answers for one.
+     */
+    unattended?: boolean;
 }
 export interface ChatBackend {
     /** Send one user message; resolves with the stop reason at turn end. */

package/dist/inspector/chat/permissions.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Permission requests for sessions nobody is watching live (routine runs).
+ *
+ * The harness (claude / codex) decides which tool calls need a human; a
+ * request reaching kraftwerk means the harness already judged the action
+ * worth asking about. Kraftwerk never answers on the human's behalf — it
+ * holds the question in the thread, flags the session as waiting, and gives
+ * the human this long to look. When nobody does, the request is declined
+ * so the routine can end with a clear summary instead of hanging forever.
+ */
+export declare const UNATTENDED_PERMISSION_TIMEOUT_MS: number;
+export interface PermissionOption {
+    optionId: string;
+    name: string;
+    kind?: string;
+}
+/**
+ * The option that declines a request without ending the turn: the adapter's
+ * `reject_once` (ACP kinds are allow_once / allow_always / reject_once /
+ * reject_always). null cancels the tool call outright when no reject option
+ * is offered — never an "allow".
+ */
+export declare function declineOption(options: PermissionOption[]): string | null;
+/** Human-readable timeout for prompts and thread notes. */
+export declare function unattendedTimeoutLabel(ms?: number): string;
+/**
+ * Session mode for an unattended (routine) session, given the mode the
+ * harness opened with (its configured default). Returns the mode to switch
+ * to, or null to keep the current one. The harness stays the judge of what
+ * needs a human; this only rules out the two presets that never ask —
+ * claude bypassPermissions and codex agent-full-access — and lifts claude's
+ * plain "default" (ask for every edit) to acceptEdits so a routine can write
+ * inside the project without stalling. claude's "auto" mode (its own
+ * classifier decides) and acceptEdits are kept as they are.
+ */
+export declare function unattendedMode(agent: "claude" | "codex", current: string | undefined): string | null;

package/dist/inspector/chat/permissions.js

@@ -0,0 +1,42 @@
+/**
+ * Permission requests for sessions nobody is watching live (routine runs).
+ *
+ * The harness (claude / codex) decides which tool calls need a human; a
+ * request reaching kraftwerk means the harness already judged the action
+ * worth asking about. Kraftwerk never answers on the human's behalf — it
+ * holds the question in the thread, flags the session as waiting, and gives
+ * the human this long to look. When nobody does, the request is declined
+ * so the routine can end with a clear summary instead of hanging forever.
+ */
+export const UNATTENDED_PERMISSION_TIMEOUT_MS = 30 * 60_000;
+/**
+ * The option that declines a request without ending the turn: the adapter's
+ * `reject_once` (ACP kinds are allow_once / allow_always / reject_once /
+ * reject_always). null cancels the tool call outright when no reject option
+ * is offered — never an "allow".
+ */
+export function declineOption(options) {
+    const reject = options.find((o) => o.kind === "reject_once") ??
+        options.find((o) => o.kind?.startsWith("reject"));
+    return reject?.optionId ?? null;
+}
+/** Human-readable timeout for prompts and thread notes. */
+export function unattendedTimeoutLabel(ms = UNATTENDED_PERMISSION_TIMEOUT_MS) {
+    const min = Math.round(ms / 60_000);
+    return min === 1 ? "1 minute" : `${min} minutes`;
+}
+/**
+ * Session mode for an unattended (routine) session, given the mode the
+ * harness opened with (its configured default). Returns the mode to switch
+ * to, or null to keep the current one. The harness stays the judge of what
+ * needs a human; this only rules out the two presets that never ask —
+ * claude bypassPermissions and codex agent-full-access — and lifts claude's
+ * plain "default" (ask for every edit) to acceptEdits so a routine can write
+ * inside the project without stalling. claude's "auto" mode (its own
+ * classifier decides) and acceptEdits are kept as they are.
+ */
+export function unattendedMode(agent, current) {
+    if (agent === "codex")
+        return current === "agent-full-access" || !current ? "agent" : null;
+    return current === "auto" || current === "acceptEdits" ? null : "acceptEdits";
+}

package/dist/inspector/chat/sessions.d.ts

@@ -1,14 +1,31 @@
 import type { ChatAgentId, ChatMeta, ChatScope, StoredChatEvent } from "./types.js";
 /** Server shutdown: no agent subprocess may outlive the inspector. */
 export declare function disposeAllBackends(): void;
+/**
+ * "## Vibeable" block: the chat has an app folder open in the preview pane.
+ * The agent works inside that folder, and everything it saves is what the
+ * user sees next — so the block spells out how the preview runs and what
+ * the sandbox rules out.
+ */
+export declare function vibeableContext(slug: string, cwd: string): Promise<string>;
+/**
+ * The folder the agent is actually spawned in. A vibeable that was removed
+ * leaves meta.cwd pointing nowhere; spawning there fails, so fall back to
+ * the scope's default while keeping meta.vibeable — the context then tells
+ * the agent the folder is gone instead of pretending it is there.
+ */
+export declare function effectiveCwd(meta: ChatMeta): Promise<string>;
 export declare function createChat(opts: {
     agent: ChatAgentId;
     scope: ChatScope;
     /** Preset title (e.g. routine runs); otherwise the first message names the chat. */
     title?: string;
 }): Promise<ChatMeta>;
+/** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
+export declare function chatAwaitingApproval(id: string): boolean;
 export declare function listChats(): Promise<Array<ChatMeta & {
     busy: boolean;
+    awaitingApproval: boolean;
 }>>;
 export declare function getChat(id: string): Promise<{
     meta: ChatMeta;

package/dist/inspector/chat/sessions.js

@@ -10,8 +10,45 @@ import { listRepos } from "../repos.js";
 import { resolveVibeable, vibeableStatus, VIBEABLE_CONFIG_FILE } from "../vibeables.js";
 import { startAcpBackend } from "./acp.js";
 import { startPiBackend } from "./pi.js";
+import { UNATTENDED_PERMISSION_TIMEOUT_MS, declineOption, unattendedTimeoutLabel } from "./permissions.js";
+import { chatHref, dismissKey, pushNotification } from "../notifications.js";
 import { appendEvent, listChatMetas, newChatId, readEvents, readMeta, safeChatDir, writeMeta, } from "./store.js";
 const states = new Map();
+/** Routine-fired sessions: nobody is expected to be watching live. */
+const isUnattended = (scope) => scope.kind === "agent" && !!scope.routine;
+/** Diagnose handle for a failed routine session (only called for unattended agent scopes). */
+function routineRef(meta) {
+    const scope = meta.scope;
+    if (scope.kind !== "agent" || !scope.routine)
+        return undefined;
+    return { kind: "routine", agent: scope.slug, routine: scope.routine, chatId: meta.id };
+}
+/** How the bell names a chat: its title ("⏰ Morning digest"), else the agent, else "chat". */
+function chatLabel(meta) {
+    if (meta.title)
+        return meta.title;
+    return meta.scope.kind === "agent" ? meta.scope.slug : "chat";
+}
+/** Text of the agent's final message (or last error) after `afterSeq`, for a notification body. */
+function lastEventText(state, afterSeq, type) {
+    const parts = [];
+    for (const e of state.events) {
+        if (e.seq <= afterSeq)
+            continue;
+        if (e.type === "user_message")
+            parts.length = 0;
+        if (type === "text" && e.type === "text")
+            parts.push(e.text);
+        if (type === "error" && e.type === "error")
+            parts.push(e.message);
+    }
+    const text = parts.join("").trim();
+    if (!text)
+        return undefined;
+    // Agents end with the summary: keep the last paragraph(s), the bell clips the rest.
+    const paras = text.split(/\n{2,}/).filter((p) => p.trim());
+    return paras.slice(-2).join("\n\n");
+}
 /** Kill a chat's agent subprocess; the next message spawns a fresh one. */
 function dropBackend(state) {
     state.backend?.dispose();
@@ -175,9 +212,21 @@ async function reposContext() {
  * user sees next — so the block spells out how the preview runs and what
  * the sandbox rules out.
  */
-async function vibeableContext(slug) {
-    const st = await vibeableStatus(slug).catch(() => null);
+export async function vibeableContext(slug, cwd) {
+    let st = null;
+    let failure = "";
+    try {
+        st = await vibeableStatus(slug);
+    }
+    catch (err) {
+        failure = err.message;
+    }
     if (!st) {
+        if (/are off/.test(failure)) {
+            return (`## Vibeable: ${slug}\nThis chat had the vibeable "${slug}" open, but vibeables have since been switched off in this ` +
+                `workspace's settings. Its folder still exists at ${cwd} and is your working directory; there is no preview pane any ` +
+                `more. Work in the folder if the user asks, and mention that the feature is off.`);
+        }
         return `## Vibeable\nThis chat had the vibeable "${slug}" open in its preview pane, but its folder is gone. Tell the user; do not recreate it unasked.`;
     }
     const dev = st.dev;
@@ -195,11 +244,12 @@ async function vibeableContext(slug) {
         `How the preview runs:\n` +
         `- Static mode (default): the inspector serves the folder directly at /vibeables/${slug}/ — index.html is the entry; plain HTML, CSS and ` +
         `JavaScript with no build step. Use relative URLs (./app.js, not /app.js). ES modules and CDN imports (https://esm.sh/<pkg>) work. ` +
-        `The static preview is a sandboxed document: no localStorage, no cookies, no calls into the inspector's own /api. Keep state in memory, ` +
-        `or move to dev mode when it must persist.\n` +
+        `The preview is a sandboxed document in both modes: no localStorage, no cookies, no calls into the inspector's own /api. Keep state in ` +
+        `memory, or move to dev mode and persist through your own server.\n` +
         `- Dev mode: when the app needs a build tool, a backend or a database, write ${VIBEABLE_CONFIG_FILE} with \`dev: <command>\` ` +
         `(e.g. \`npm run dev\`, \`node server.js\`, \`python3 -m http.server $PORT\`). kraftwerk starts it inside the folder with PORT in the ` +
-        `environment and the pane embeds that server; the command must listen on $PORT (or declare \`port:\` when it cannot). Optional ` +
+        `environment and the pane reaches it through /vibeables/${slug}/ on the inspector (BASE_PATH holds that prefix — a dev server that ` +
+        `emits absolute URLs, like Vite, must use it as its base); the command must listen on $PORT (or declare \`port:\` when it cannot). Optional ` +
         `\`dir:\` picks the folder for static mode (e.g. dist). The app brings its own backend and storage — a small node server writing JSON ` +
         `files, SQLite, an external API — nothing of that is provided by kraftwerk.\n\n` +
         `Rules: the folder is part of this workspace and versioned with it — do not run git yourself, the user reviews and commits from the ` +
@@ -241,8 +291,12 @@ async function baseScopeContext(scope, agent) {
             `say so and suggest which agent or tool fits better.` +
             (scope.routine
                 ? `\n\nThis session was started automatically by your scheduled routine "${scope.routine}" — ` +
-                    `nobody may be watching live. Complete the task autonomously (tool permissions are ` +
-                    `auto-approved) and end with a clear, self-contained summary of what you did and found.`
+                    `nobody may be watching live. Complete the task autonomously. Edits inside the project ` +
+                    `need no approval; anything your harness asks about (shell commands, network, files ` +
+                    `outside the project) is shown to a human who may look later — say in one line why you ` +
+                    `need it, then continue with what you can. A request nobody answers within ` +
+                    `${unattendedTimeoutLabel()} is declined: report what you could not do and why, do ` +
+                    `not retry it another way. End with a clear, self-contained summary of what you did and found.`
                 : ""));
     }
     if (scope.kind === "knowledge") {
@@ -346,7 +400,7 @@ async function scopeContext(meta) {
     const [base, repos, vibe, skills] = await Promise.all([
         baseScopeContext(scope, agent),
         scope.kind === "agent" || scope.kind === "kraftwerk" ? reposContext() : Promise.resolve(""),
-        meta.vibeable ? vibeableContext(meta.vibeable) : Promise.resolve(""),
+        meta.vibeable ? vibeableContext(meta.vibeable, meta.cwd) : Promise.resolve(""),
         availableSkills(scope),
     ]);
     return [base, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
@@ -371,6 +425,9 @@ async function backendTuning(meta) {
     // A vibeable session works inside the app folder for the same reason.
     if ((scope.kind === "run" || meta.vibeable) && agent === "claude")
         tuning.addDirs = [getProjectRoot()];
+    // Routine runs: never a harness mode that skips asking (see unattendedMode in permissions.ts).
+    if (isUnattended(scope))
+        tuning.unattended = true;
     // pi loads skills only when told: hand it every visible skill folder.
     if (agent === "pi") {
         const skills = await availableSkills(scope);
@@ -385,28 +442,51 @@ async function ensureBackend(state) {
     const hooks = {
         emit: (ev) => void emit(state, ev),
         askPermission: (title, options) => {
-            // Routine-triggered sessions run unattended: auto-approve, but keep
-            // the request/resolution pair in the thread as an audit trail.
-            const scope = state.meta.scope;
-            if (scope.kind === "agent" && scope.routine) {
-                const allow = options.find((o) => o.kind?.startsWith("allow")) ?? options[0];
-                const requestId = randomUUID();
-                emit(state, { type: "permission_request", requestId, title, options });
-                emit(state, { type: "permission_resolved", requestId, optionId: allow?.optionId ?? null });
-                return Promise.resolve(allow?.optionId ?? null);
-            }
+            // The harness already judged this call worth asking about, so the
+            // question always goes to a human — routine sessions included. The
+            // request stays pending in the thread (and the chat/routine show as
+            // waiting) until someone answers. Unattended sessions get a deadline:
+            // an unanswered request is declined, never approved, so the routine
+            // can wrap up with a summary instead of hanging.
             return new Promise((resolve) => {
                 const requestId = randomUUID();
+                const notifyKey = `approval:${state.meta.id}:${requestId}`;
+                let deadline;
                 state.pendingPermissions.set(requestId, (optionId) => {
+                    if (deadline)
+                        clearTimeout(deadline);
                     state.pendingPermissions.delete(requestId);
                     emit(state, { type: "permission_resolved", requestId, optionId });
+                    void dismissKey(notifyKey);
                     resolve(optionId);
                 });
                 emit(state, { type: "permission_request", requestId, title, options });
+                // The bell: a question is waiting. Answered -> the item goes away again.
+                void pushNotification({
+                    kind: "approval",
+                    key: notifyKey,
+                    title: `${chatLabel(state.meta)} needs approval`,
+                    body: title,
+                    href: chatHref(state.meta),
+                });
+                if (isUnattended(state.meta.scope)) {
+                    deadline = setTimeout(() => {
+                        const pending = state.pendingPermissions.get(requestId);
+                        if (!pending)
+                            return;
+                        emit(state, {
+                            type: "error",
+                            message: `nobody answered this permission request within ${unattendedTimeoutLabel()} — declined (unattended routine session)`,
+                        });
+                        pending(declineOption(options));
+                    }, UNATTENDED_PERMISSION_TIMEOUT_MS);
+                    deadline.unref?.();
+                }
             });
         },
     };
-    const { agent, cwd } = state.meta;
+    const { agent } = state.meta;
+    const cwd = await effectiveCwd(state.meta);
     const tuning = await backendTuning(state.meta);
     state.backend =
         agent === "pi"
@@ -420,6 +500,18 @@ async function ensureBackend(state) {
 /* ---------- public API (used by server.ts) ---------- */
 /** Where a chat's agent runs when no vibeable is open: the run folder for run chats, else the project root. */
 const defaultCwd = (scope) => (scope.kind === "run" ? safeRunDir(scope.runId) : getProjectRoot());
+/**
+ * The folder the agent is actually spawned in. A vibeable that was removed
+ * leaves meta.cwd pointing nowhere; spawning there fails, so fall back to
+ * the scope's default while keeping meta.vibeable — the context then tells
+ * the agent the folder is gone instead of pretending it is there.
+ */
+export async function effectiveCwd(meta) {
+    const st = await fs.stat(meta.cwd).catch(() => null);
+    if (st?.isDirectory())
+        return meta.cwd;
+    return defaultCwd(meta.scope);
+}
 export async function createChat(opts) {
     const cwd = defaultCwd(opts.scope);
     const now = new Date().toISOString();
@@ -445,11 +537,16 @@ export async function createChat(opts) {
     });
     return meta;
 }
+/** A permission request is waiting for a human in this chat (live state only — a restart drops it with the backend). */
+export function chatAwaitingApproval(id) {
+    return (states.get(id)?.pendingPermissions.size ?? 0) > 0;
+}
 export async function listChats() {
     const metas = await listChatMetas();
     return metas.map((m) => ({
         ...(states.get(m.id)?.meta ?? m),
         busy: states.get(m.id)?.busy ?? false,
+        awaitingApproval: chatAwaitingApproval(m.id),
     }));
 }
 export async function getChat(id) {
@@ -470,7 +567,7 @@ export async function postMessage(id, text) {
         state.meta.title = text.replace(/\s+/g, " ").trim().slice(0, 80);
         void writeMeta(state.meta).catch(() => { });
     }
-    emit(state, { type: "user_message", text });
+    const turnStart = emit(state, { type: "user_message", text }).seq;
     // The turn runs in the background; the HTTP request returns immediately
     // and the browser follows along on the SSE stream.
     void (async () => {
@@ -485,13 +582,31 @@ export async function postMessage(id, text) {
             const stopReason = await backend.prompt(promptText);
             emit(state, { type: "turn_end", stopReason });
             // Routine sessions are one-shot and unattended: release the agent
-            // process as soon as the turn ends instead of waiting for the reaper.
-            const scope = state.meta.scope;
-            if (scope.kind === "agent" && scope.routine)
+            // process as soon as the turn ends instead of waiting for the reaper,
+            // and tell the bell how it went.
+            if (isUnattended(state.meta.scope)) {
                 dropBackend(state);
+                const failed = state.events.some((e) => e.seq > turnStart && e.type === "error");
+                void pushNotification({
+                    kind: failed ? "routine_failed" : "routine_done",
+                    title: `${chatLabel(state.meta)} ${failed ? "ended with an error" : "finished"}`,
+                    body: failed ? lastEventText(state, turnStart, "error") : lastEventText(state, turnStart, "text"),
+                    href: chatHref(state.meta),
+                    ...(failed ? { diagnose: routineRef(state.meta) } : {}),
+                });
+            }
         }
         catch (err) {
             emit(state, { type: "error", message: err.message });
+            if (isUnattended(state.meta.scope)) {
+                void pushNotification({
+                    kind: "routine_failed",
+                    title: `${chatLabel(state.meta)} failed`,
+                    body: err.message,
+                    href: chatHref(state.meta),
+                    diagnose: routineRef(state.meta),
+                });
+            }
             // A failed turn may mean a dead subprocess; drop it so the next
             // message spawns a fresh agent (thread history stays on disk).
             dropBackend(state);
@@ -513,10 +628,11 @@ export async function setChatVibeable(id, slug) {
     const state = await loadState(id);
     if (!state)
         return { error: "not found", status: 404 };
+    const busyError = { error: "agent is still working — wait for the turn to finish", status: 409 };
     if (state.busy)
-        return { error: "agent is still working — wait for the turn to finish", status: 409 };
+        return busyError;
+    let dir = null;
     if (slug) {
-        let dir;
         try {
             dir = (await resolveVibeable(slug)).dir;
         }
@@ -524,6 +640,13 @@ export async function setChatVibeable(id, slug) {
             const msg = err.message;
             return { error: msg, status: /^no vibeable/.test(msg) ? 404 : /are off/.test(msg) ? 409 : 400 };
         }
+    }
+    // A message may have started a turn during the await above; its backend
+    // was spawned in the old cwd, so refuse rather than relabel it. From here
+    // on nothing yields until cwd, vibeable and backend agree.
+    if (state.busy)
+        return busyError;
+    if (slug && dir) {
         state.meta.vibeable = slug;
         state.meta.cwd = dir;
     }
@@ -532,9 +655,9 @@ export async function setChatVibeable(id, slug) {
         state.meta.cwd = defaultCwd(state.meta.scope);
     }
     state.meta.updatedAt = new Date().toISOString();
-    await writeMeta(state.meta);
     dropBackend(state);
     state.needsContext = true;
+    await writeMeta(state.meta);
     return { meta: state.meta };
 }
 export async function resolvePermission(id, requestId, optionId) {

package/dist/inspector/diagnose.d.ts

@@ -0,0 +1,32 @@
+import type { ChatAgentId, ChatScope } from "./chat/types.js";
+import { type DiagnoseRef } from "./notifications.js";
+/**
+ * "Diagnose" on a failure item in the bell: open a chat in the place that
+ * knows most about the failure and hand it a first message that asks for
+ * root cause and a fix.
+ *
+ *   workflow run failed  -> run chat (cwd = run folder, project root granted)
+ *   routine session died -> a fresh session of the same agent, pointed at the
+ *                           failed session's event log
+ *   routine could not start -> kraftwerk-aware chat (the agent/harness setup is the problem)
+ *
+ * The prompt is built here, at click time, so it reflects the run's final
+ * state, and the chat shows it as the user's own first message — nothing
+ * hidden.
+ */
+export interface DiagnosePlan {
+    agent: ChatAgentId;
+    scope: ChatScope;
+    title: string;
+    prompt: string;
+}
+/** Where and how the diagnosis chat starts, for a failure item's reference. */
+export declare function diagnosePlan(ref: DiagnoseRef, title: string): Promise<DiagnosePlan | null>;
+/** Create the chat, send the first message, mark the item read. */
+export declare function startDiagnosis(notificationId: string): Promise<{
+    chatId: string;
+    href: string;
+} | {
+    error: string;
+    status: number;
+}>;