@netnodeag/kraftwerk 0.39.1 → 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
@@ -143,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

@@ -21,8 +21,11 @@ export declare function createChat(opts: {
     /** 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();
@@ -254,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") {
@@ -384,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);
@@ -398,24 +442,46 @@ 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?.();
+                }
             });
         },
     };
@@ -471,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) {
@@ -496,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 () => {
@@ -511,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);

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;
+}>;

package/dist/inspector/diagnose.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { getOutputDir } from "./context.js";
+import { getAgent } from "./agents.js";
+import { getRun } from "./runs.js";
+import { listRoutines } from "./routines.js";
+import { createChat, getChat, postMessage } from "./chat/sessions.js";
+import { chatHref, getNotification, markNotificationsRead } from "./notifications.js";
+const FIX_INSTRUCTIONS = `Work in this order:\n` +
+    `1. Find the root cause. Read the evidence before guessing, and say in plain words what went wrong and where.\n` +
+    `2. Decide whether the fix belongs in the workflow definition (prompts, steps, gates, agent configs), in the project, ` +
+    `or outside (credentials, network, a missing tool). Say which.\n` +
+    `3. If the fix is in the workflow or project files, apply it and show the diff. If it is outside, say exactly what the user must do.\n` +
+    `4. End with how to verify: the command to re-run, and what a good result looks like.`;
+function runPrompt(run) {
+    const phases = run.phases
+        .map((p) => `- ${p.phase} [${p.status}]${p.summary ? `: ${p.summary}` : ""}`)
+        .join("\n");
+    const failedPhase = run.phases.find((p) => p.status === "failed" || p.status === "blocked");
+    return (`Workflow run ${run.id} of "${run.workflow ?? "?"}" ended with status ${run.status}` +
+        (failedPhase ? ` in phase "${failedPhase.phase}" (${failedPhase.status})` : "") +
+        `.\nRequest: ${run.request ?? "(none)"}\n\nPhases:\n${phases || "(none)"}\n\n` +
+        `Please diagnose this run. The evidence is in this folder: trace.jsonl (every event), trigger.log ` +
+        `(process output), and the phase outputs. The workflow definition lives in the project root, which you may edit.\n\n` +
+        FIX_INSTRUCTIONS +
+        `\nRe-run with: KRAFTWERK_YES=1 npx kraftwerk run ${run.workflow ?? "<workflow>"} "${(run.request ?? "").replace(/"/g, '\\"')}"`);
+}
+async function routinePrompt(ref, agentExists) {
+    const routine = (await listRoutines(ref.agent).catch(() => []))
+        .find((r) => r.id === ref.routine);
+    const head = routine
+        ? `The routine "${routine.name}" (schedule ${routine.schedule}) of agent "${ref.agent}" failed.\nIts prompt was:\n"""\n${routine.prompt}\n"""\n`
+        : `A routine (${ref.routine}) of agent "${ref.agent}" failed.\n`;
+    let evidence;
+    if (ref.chatId) {
+        const chat = await getChat(ref.chatId).catch(() => null);
+        const errors = chat?.events.filter((e) => e.type === "error").map((e) => e.message) ?? [];
+        evidence =
+            `The failed session's full event log is ${path.join(getOutputDir(), "chats", ref.chatId, "events.jsonl")} ` +
+                `(one JSON event per line: user_message, text, tool_call, error, turn_end).` +
+                (errors.length ? `\nErrors recorded:\n${errors.map((m) => `- ${m}`).join("\n")}` : "");
+    }
+    else {
+        evidence = agentExists
+            ? `The session could not even start. Check the agent's definition under agents/${ref.agent}/ (agent.yml, routines.yml) and whether its harness is installed and authenticated.`
+            : `The session could not start because agent "${ref.agent}" was not found — check agents/${ref.agent}/agent.yml and the routine in agents/${ref.agent}/routines.yml.`;
+    }
+    return `${head}\n${evidence}\n\nPlease diagnose this failure.\n\n${FIX_INSTRUCTIONS}\nRe-run from the agent page ("run" next to the routine) or wait for the next scheduled time.`;
+}
+/** Where and how the diagnosis chat starts, for a failure item's reference. */
+export async function diagnosePlan(ref, title) {
+    if (ref.kind === "run") {
+        const run = await getRun(ref.runId).catch(() => null);
+        if (!run)
+            return null;
+        return { agent: "claude", scope: { kind: "run", runId: run.id }, title: `🩺 ${title}`, prompt: runPrompt(run) };
+    }
+    const def = await getAgent(ref.agent).catch(() => null);
+    const prompt = await routinePrompt(ref, !!def);
+    // A session that died mid-run: the agent itself looks at its own log.
+    // No session at all (agent or harness broken): the kraftwerk-aware chat.
+    const scope = def && ref.chatId ? { kind: "agent", slug: def.slug } : { kind: "kraftwerk" };
+    return { agent: def && ref.chatId ? def.harness : "claude", scope, title: `🩺 ${title}`, prompt };
+}
+/** Create the chat, send the first message, mark the item read. */
+export async function startDiagnosis(notificationId) {
+    const item = await getNotification(notificationId);
+    if (!item)
+        return { error: "notification not found", status: 404 };
+    if (!item.diagnose)
+        return { error: "nothing to diagnose for this item", status: 409 };
+    const plan = await diagnosePlan(item.diagnose, item.title);
+    if (!plan)
+        return { error: "the run this item refers to is gone", status: 410 };
+    const meta = await createChat({ agent: plan.agent, scope: plan.scope, title: plan.title });
+    const { error } = await postMessage(meta.id, plan.prompt);
+    if (error)
+        return { error, status: 409 };
+    void markNotificationsRead([item.id]);
+    return { chatId: meta.id, href: chatHref(meta) };
+}

package/dist/inspector/git.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
-import { reposRootFor, resolveProject, vibeablesRootFor } from "../config.js";
+import { reposRootFor, resolveProject, vibeablesRootFor, isSafeGitName } from "../config.js";
 import { ENV_FILE } from "../runner/docker.js";
 import { getOutputDir, getProjectRoot } from "./context.js";
 /**
@@ -130,6 +130,19 @@ export async function sshCommandFor(repoRoot) {
 export async function gitNet(args, repoRoot) {
     return git(args, repoRoot, NET_TIMEOUT, { GIT_SSH_COMMAND: await sshCommandFor(repoRoot) });
 }
+/**
+ * Remote/branch names from kraftwerk.yml become git positionals. Config
+ * load and the settings API already refuse dash-led names, but the file is
+ * shared through the workspace repo itself, so the call site checks again
+ * and separates options from positionals.
+ */
+function netArgs(cmd, ...names) {
+    for (const n of names) {
+        if (!isSafeGitName(n))
+            throw new Error(`refusing git name "${n}" (looks like an option)`);
+    }
+    return [...cmd, "--end-of-options", ...names];
+}
 /**
  * Pathspecs are globs by default, so a file called `note[1].md` would not
  * match itself. `:(literal)` turns the pattern off.
@@ -522,7 +535,7 @@ async function fetchNow() {
     const { repo, error } = await openRepo();
     if (!repo)
         return { ok: false, error };
-    const r = await gitNet(["fetch", repo.cfg.remote], repo.repoRoot);
+    const r = await gitNet(netArgs(["fetch"], repo.cfg.remote), repo.repoRoot);
     touched();
     // Only a fetch that worked counts. Stamping the time on a failure would
     // put "fetched 5s ago" next to ahead/behind counts that stopped moving
@@ -550,7 +563,7 @@ async function pullNow() {
     const upstream = (await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], repoRoot)).ok;
     const r = upstream
         ? await gitNet(["pull", "--ff-only"], repoRoot)
-        : await gitNet(["pull", "--ff-only", cfg.remote, head.branch], repoRoot);
+        : await gitNet(netArgs(["pull", "--ff-only"], cfg.remote, head.branch), repoRoot);
     touched();
     if (!r.ok) {
         // git's own non-fast-forward output is a wall of hints. Say the one
@@ -579,7 +592,7 @@ async function pushNow() {
     const upstream = (await git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"], repoRoot)).ok;
     const r = upstream
         ? await gitNet(["push"], repoRoot)
-        : await gitNet(["push", "--set-upstream", cfg.remote, `HEAD:${head.branch}`], repoRoot);
+        : await gitNet(netArgs(["push", "--set-upstream"], cfg.remote, `HEAD:${head.branch}`), repoRoot);
     touched();
     if (!r.ok) {
         lastError = r.stderr || "push failed";