@netnodeag/kraftwerk 0.75.1 → 0.77.0

package/dist/cli/routines.js

@@ -3,13 +3,14 @@ import path from "node:path";
 import chalk from "chalk";
 import { resolveWorkspace } from "../config.js";
 import { setDefaultWorkspace, Workspace } from "../core/workspace.js";
-import { deleteRoutine, listRoutines, routineStatuses, saveRoutine, } from "../core/routines.js";
+import { adoptUnassigned, deleteRoutine, listRoutines, routineStatuses, saveRoutine, } from "../core/routines.js";
 import { getAgent, listAgents } from "../core/agents.js";
 /**
  * `kraftwerk routines` — CLI surface over per-agent scheduled prompts
  * (agents/<slug>/routines.yml). Definition CRUD works directly on the
  * files; `run` fires through the running inspector server, because the
- * session (chat) and the scheduler live there.
+ * session (chat) and the scheduler live there. `adopt` makes this machine
+ * the runner (runs_on) of every unassigned routine and commits routines.yml.
  */
 /** Point the inspector context at this project so agent/routine paths resolve. */
 export async function initContext() {
@@ -37,11 +38,19 @@ const fmtTime = (iso) => {
     const p = (n) => String(n).padStart(2, "0");
     return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
 };
+function runnerLabel(r) {
+    if (r.runner === "here")
+        return chalk.green("runs here");
+    if (r.runner === "unassigned")
+        return chalk.yellow("unassigned");
+    return r.retired ? chalk.yellow(`runs on ${r.runsOn} (retired)`) : chalk.dim(`runs on ${r.runsOn}`);
+}
 function routineLine(r) {
     const state = r.enabled ? chalk.green("on ") : chalk.dim("off");
     const flags = r.lastError ? ` ${chalk.red(`error: ${r.lastError}`)}` : "";
     return (`  ${chalk.cyan(r.id.padEnd(24))} ${state} ${r.schedule.padEnd(14)} ` +
         chalk.dim(`next ${fmtTime(r.nextRunAt).padEnd(17)} last ${fmtTime(r.lastRunAt)}`) +
+        ` ${runnerLabel(r)}` +
         flags);
 }
 export function registerRoutineCommands(program) {
@@ -86,6 +95,7 @@ export function registerRoutineCommands(program) {
         .option("--file <path>", "Read the prompt from a file")
         .option("--id <id>", "Routine id (default: derived from the name)")
         .option("--disabled", "Create it switched off")
+        .option("--runs-on <identity>", "The machine that fires it, handle@machine (default: this one for a new routine, unchanged for an update)")
         .action(async (agent, opts) => {
         await initContext();
         await requireAgent(agent);
@@ -103,12 +113,16 @@ export function registerRoutineCommands(program) {
                 schedule: opts.schedule,
                 prompt,
                 enabled: !opts.disabled,
+                ...(opts.runsOn !== undefined ? { runsOn: opts.runsOn } : {}),
             });
             const verb = existing.has(routine.id) ? "updated" : "created";
             console.log(`${chalk.green("✔")} ${verb} ${chalk.cyan(`${agent}/${routine.id}`)} ` +
                 chalk.dim(`(${routine.schedule}${routine.enabled ? "" : ", disabled"})`));
-            if (routine.enabled) {
-                console.log(chalk.dim("  fires from the inspector server — make sure `kraftwerk ui` is running."));
+            if (!routine.runsOn) {
+                console.log(chalk.yellow("  unassigned: it fires nowhere until a machine runs it (`kraftwerk routines adopt`)."));
+            }
+            else if (routine.enabled) {
+                console.log(chalk.dim(`  fires from the inspector server on ${routine.runsOn} — make sure \`kraftwerk ui\` runs there.`));
             }
         }
         catch (err) {
@@ -148,6 +162,28 @@ export function registerRoutineCommands(program) {
             console.log(`${chalk.green("✔")} ${chalk.cyan(`${agent}/${id}`)} ${verb}d`);
         });
     }
+    routines
+        .command("adopt")
+        .description("Run these here: every enabled routine without runs_on gets this machine's identity; routines.yml is committed")
+        .option("--retired", "Also move routines that name a retired identity of this machine (see `kraftwerk whoami`)")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        await initContext();
+        const r = await adoptUnassigned({ retired: !!opts.retired });
+        if (opts.json)
+            return void console.log(JSON.stringify(r, null, 2));
+        if (!r.adopted.length) {
+            console.log(`${chalk.green("✔")} nothing to adopt — every enabled routine has a runner ${chalk.dim(`(this machine: ${r.runsOn})`)}`);
+            return;
+        }
+        for (const a of r.adopted) {
+            console.log(`${chalk.green("✔")} ${chalk.cyan(`${a.agent}/${a.id}`)} runs on ${r.runsOn}${a.from ? chalk.dim(` (was ${a.from})`) : ""}`);
+        }
+        if (r.commit?.ok)
+            console.log(chalk.dim(`  committed ${r.files.join(", ")} — push so the other clones see it`));
+        else
+            console.log(chalk.yellow(`  written, not committed: ${r.commit?.error ?? "unknown error"} — commit ${r.files.join(", ")} yourself`));
+    });
     routines
         .command("run")
         .description("Fire a routine now (opens a session via the running `kraftwerk ui` server)")

package/dist/cli/whoami.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+/**
+ * `kraftwerk whoami` — this machine's identity (~/.kraftwerk/identity.json):
+ * the handle, the machine name, and `handle@machine`, which routines name in
+ * `runs_on:` so only one clone of a workspace fires them. `--handle` /
+ * `--machine` rename; the old pair is kept in `previous`, and doctor offers
+ * to move routines that still name it.
+ */
+export declare function registerWhoamiCommand(program: Command): void;

package/dist/cli/whoami.js

@@ -0,0 +1,48 @@
+import chalk from "chalk";
+import { identityPartError, identityString, readIdentity, setIdentity } from "../core/identity.js";
+/**
+ * `kraftwerk whoami` — this machine's identity (~/.kraftwerk/identity.json):
+ * the handle, the machine name, and `handle@machine`, which routines name in
+ * `runs_on:` so only one clone of a workspace fires them. `--handle` /
+ * `--machine` rename; the old pair is kept in `previous`, and doctor offers
+ * to move routines that still name it.
+ */
+export function registerWhoamiCommand(program) {
+    program
+        .command("whoami")
+        .description("This machine's identity (handle@machine) — the runner routines name in runs_on; --handle / --machine rename it")
+        .option("--handle <handle>", "Set your handle (lowercase letters, digits, . _ -)")
+        .option("--machine <machine>", "Set this machine's name (lowercase letters, digits, . _ -)")
+        .option("--json", "Machine-readable output")
+        .addHelpText("after", `
+A routine fires only on the machine whose identity its runs_on names:
+  kraftwerk whoami                      print handle, machine and handle@machine
+  kraftwerk whoami --machine studio     rename this machine (the old pair is kept as previous)
+  kraftwerk routines adopt              make this machine the runner of every unassigned routine`)
+        .action(async (opts) => {
+        const before = identityString(await readIdentity());
+        for (const label of ["handle", "machine"]) {
+            const v = opts[label];
+            const err = v === undefined ? undefined : identityPartError(label, v);
+            if (err) {
+                console.error(chalk.red(err));
+                process.exit(2);
+            }
+        }
+        const changing = opts.handle !== undefined || opts.machine !== undefined;
+        const id = changing ? await setIdentity({ handle: opts.handle, machine: opts.machine }) : await readIdentity();
+        const now = identityString(id);
+        if (opts.json)
+            return void console.log(JSON.stringify({ handle: id.handle, machine: id.machine, identity: now, previous: id.previous }, null, 2));
+        if (changing && before !== now)
+            console.log(`${chalk.green("✔")} ${chalk.dim(before)} → ${chalk.cyan(now)}`);
+        console.log(`handle:   ${id.handle}`);
+        console.log(`machine:  ${id.machine}`);
+        console.log(`identity: ${chalk.cyan(now)}`);
+        if (id.previous.length)
+            console.log(chalk.dim(`previous: ${id.previous.join(", ")}`));
+        if (changing && before !== now) {
+            console.log(chalk.dim(`  routines that name ${before} no longer fire here — \`kraftwerk doctor --fix\` moves them to ${now}`));
+        }
+    });
+}

package/dist/client/routes.d.ts

@@ -1,6 +1,7 @@
 /** Route name → [method, path pattern, and "raw" (answers a stream or a file) or "upload" (sends file bytes): both HTTP only]. */
 export declare const ROUTES: {
     readonly "agents.addJournal": readonly ["POST", "/api/agents/:slug/journal"];
+    readonly "agents.adoptRoutine": readonly ["POST", "/api/agents/:slug/routines/:id/adopt"];
     readonly "agents.archive": readonly ["POST", "/api/agents/:slug/archive"];
     readonly "agents.create": readonly ["POST", "/api/agents"];
     readonly "agents.delete": readonly ["DELETE", "/api/agents/:slug"];
@@ -44,6 +45,10 @@ export declare const ROUTES: {
     readonly "chats.setVibeable": readonly ["POST", "/api/chats/:id/vibeable"];
     readonly "chats.steer": readonly ["POST", "/api/chats/:id/steer"];
     readonly "chats.stopTask": readonly ["POST", "/api/chats/:id/task-stop"];
+    readonly "cloud.set": readonly ["POST", "/api/cloud"];
+    readonly "cloud.status": readonly ["GET", "/api/cloud"];
+    readonly "cloud.sync": readonly ["POST", "/api/cloud/sync"];
+    readonly "cloud.unlink": readonly ["POST", "/api/cloud/unlink"];
     readonly "devices.code": readonly ["POST", "/api/devices/code"];
     readonly "devices.dropPush": readonly ["DELETE", "/api/devices/push"];
     readonly "devices.list": readonly ["GET", "/api/devices"];
@@ -70,6 +75,7 @@ export declare const ROUTES: {
     readonly "hub.close": readonly ["POST", "/api/hub/close"];
     readonly "hub.list": readonly ["GET", "/api/hub"];
     readonly "hub.open": readonly ["POST", "/api/hub/open"];
+    readonly "identity.get": readonly ["GET", "/api/identity"];
     readonly "knowledge.concept": readonly ["GET", "/api/knowledge/:bundle/concept"];
     readonly "knowledge.create": readonly ["POST", "/api/knowledge"];
     readonly "knowledge.delete": readonly ["DELETE", "/api/knowledge/:bundle"];
@@ -98,6 +104,7 @@ export declare const ROUTES: {
     readonly "repos.list": readonly ["GET", "/api/repos"];
     readonly "repos.remove": readonly ["DELETE", "/api/repos/:slug"];
     readonly "repos.update": readonly ["POST", "/api/repos/:slug/update"];
+    readonly "routines.adopt": readonly ["POST", "/api/routines/adopt"];
     readonly "routines.list": readonly ["GET", "/api/routines"];
     readonly "runs.decide": readonly ["POST", "/api/runs/:id/decision"];
     readonly "runs.delete": readonly ["DELETE", "/api/runs/:id"];

package/dist/client/routes.js

@@ -2,6 +2,7 @@
 /** Route name → [method, path pattern, and "raw" (answers a stream or a file) or "upload" (sends file bytes): both HTTP only]. */
 export const ROUTES = {
     "agents.addJournal": ["POST", "/api/agents/:slug/journal"],
+    "agents.adoptRoutine": ["POST", "/api/agents/:slug/routines/:id/adopt"],
     "agents.archive": ["POST", "/api/agents/:slug/archive"],
     "agents.create": ["POST", "/api/agents"],
     "agents.delete": ["DELETE", "/api/agents/:slug"],
@@ -45,6 +46,10 @@ export const ROUTES = {
     "chats.setVibeable": ["POST", "/api/chats/:id/vibeable"],
     "chats.steer": ["POST", "/api/chats/:id/steer"],
     "chats.stopTask": ["POST", "/api/chats/:id/task-stop"],
+    "cloud.set": ["POST", "/api/cloud"],
+    "cloud.status": ["GET", "/api/cloud"],
+    "cloud.sync": ["POST", "/api/cloud/sync"],
+    "cloud.unlink": ["POST", "/api/cloud/unlink"],
     "devices.code": ["POST", "/api/devices/code"],
     "devices.dropPush": ["DELETE", "/api/devices/push"],
     "devices.list": ["GET", "/api/devices"],
@@ -71,6 +76,7 @@ export const ROUTES = {
     "hub.close": ["POST", "/api/hub/close"],
     "hub.list": ["GET", "/api/hub"],
     "hub.open": ["POST", "/api/hub/open"],
+    "identity.get": ["GET", "/api/identity"],
     "knowledge.concept": ["GET", "/api/knowledge/:bundle/concept"],
     "knowledge.create": ["POST", "/api/knowledge"],
     "knowledge.delete": ["DELETE", "/api/knowledge/:bundle"],
@@ -99,6 +105,7 @@ export const ROUTES = {
     "repos.list": ["GET", "/api/repos"],
     "repos.remove": ["DELETE", "/api/repos/:slug"],
     "repos.update": ["POST", "/api/repos/:slug/update"],
+    "routines.adopt": ["POST", "/api/routines/adopt"],
     "routines.list": ["GET", "/api/routines"],
     "runs.decide": ["POST", "/api/runs/:id/decision"],
     "runs.delete": ["DELETE", "/api/runs/:id"],

package/dist/config.d.ts

@@ -9,6 +9,7 @@
  *
  * All fields are optional — a valid kraftwerk.yml may be empty:
  *
+ *   id: ws_k3f9x2m7q1          # the workspace's identity across machines and clones (committed; `kraftwerk init` writes it)
  *   name: my-project           # display name (inspector header, "environment")
  *   icon: "⚡"                  # emoji shown as inspector favicon
  *   color: "#c2410c"           # accent for this workspace in the switcher (default: derived from the root)
@@ -33,11 +34,10 @@
   *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  *   projects:                  # goal-scoped folders (brief, systems of record, links) that chats work in (absent = off, bare key = on)
  *     root: kraftwerk-data/projects   # one folder per project, part of the workspace. Default: kraftwerk-data/projects
- *   cloud:                     # kraftwerk cloud manager — ON BY DEFAULT, `enabled: false` opts out
- *     url: https://srv.kraftwerk-cloud.netnode.cloud   # where the cloud answers (default). KRAFTWERK_CLOUD_URL env wins; "off" disables
- *     interval: 60             # seconds between heartbeats. Default: 60
- *   # No key here: the cloud hands the instance its identity and a claim code (Settings → Cloud in the UI);
- *   # a server that should register under an account unattended puts KRAFTWERK_CLOUD_TOKEN into .env.
+ *   cloud:                     # the machine's kraftwerk cloud record lists this workspace — `enabled: false` leaves it out
+ *     enabled: false           # a per-workspace veto; the machine's switch is `kraftwerk cloud on|off` (~/.kraftwerk/cloud.json)
+ *   # No key here: the daemon registers the MACHINE (its relay id) and `kraftwerk login` claims it.
+ *   # `url` and `interval` are deprecated: the cloud's origin is the machine's (cloud.json / KRAFTWERK_CLOUD_URL).
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export declare const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -122,35 +122,23 @@ export declare const PROJECTS_DEFAULT_ROOT = "kraftwerk-data/projects";
 /** Absolute projects root when the feature is on, undefined otherwise. */
 export declare function projectsRootFor(project: ResolvedWorkspace): string | undefined;
 /**
- * Cloud manager: the kraftwerk cloud is ~/.kraftwerk made reachable over
- * the internet — a registry of instances across machines. Every inspector
- * registers on start and heartbeats while it runs, so the cloud's global
- * view shows this workspace, where it runs, and whether it is live; the
- * user claims it into their account with the code the UI shows. On by
- * default: an absent block is the same as a bare one, `enabled: false`
- * opts out, and so does KRAFTWERK_CLOUD_URL=off in the environment (what
- * the tests and CI set). No credential lives in kraftwerk.yml — the
- * identity comes from the cloud, and an account token for unattended
- * servers is KRAFTWERK_CLOUD_TOKEN in .env.
+ * kraftwerk.yml `cloud:` — since the cloud knows machines (core/cloud.ts,
+ * server/cloud.ts), this block only vetoes: `enabled: false` leaves the
+ * workspace out of the machine's reports. The machine's switch and the
+ * cloud's origin are ~/.kraftwerk/cloud.json (`kraftwerk cloud on|off`) and
+ * KRAFTWERK_CLOUD_URL. `url` is still honored for one release (with a
+ * warning) when the machine names none; `interval` is ignored — the cloud
+ * sets the cadence.
  */
 export interface CloudConfig {
-    /** false turns the feature off. Default: true. */
+    /** false leaves this workspace out of the machine's cloud record. Default: true. */
     enabled?: boolean;
-    /** Origin of the cloud manager. Default: https://srv.kraftwerk-cloud.netnode.cloud */
+    /** @deprecated The machine's (cloud.json / KRAFTWERK_CLOUD_URL); used only when the machine names none. */
     url?: string;
-    /** Seconds between heartbeats. Default: 60 (the cloud may raise it). */
+    /** @deprecated Ignored: the cloud sets the heartbeat interval. */
     interval?: number;
 }
 export declare const CLOUD_DEFAULT_URL = "https://srv.kraftwerk-cloud.netnode.cloud";
-export declare const CLOUD_DEFAULT_INTERVAL = 60;
-export interface CloudSettings {
-    url: string;
-    interval: number;
-    /** KRAFTWERK_CLOUD_TOKEN from the environment (.env), when set. */
-    token?: string;
-}
-/** The effective cloud settings when the feature is on; undefined when kraftwerk.yml or the environment turned it off. */
-export declare function cloudFor(project: ResolvedWorkspace): CloudSettings | undefined;
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export declare function ignoreEntryFor(projectRoot: string, dir: string): string | undefined;
 /** True when .gitignore text already covers the entry (with or without a leading or trailing slash). */
@@ -165,6 +153,12 @@ export interface SwitcherEntry {
     icon?: string;
 }
 export interface WorkspaceConfig {
+    /**
+     * The workspace's identity wherever it is cloned: `ws_` + 10 base36
+     * characters, committed with kraftwerk.yml. Unlike the slug (an address on
+     * one machine) it is the same on every clone. Nothing reads it yet.
+     */
+    id?: string;
     /** Display name of the project ("environment"), shown in the inspector header. */
     name?: string;
     /**
@@ -199,7 +193,7 @@ export interface WorkspaceConfig {
     vibeables?: VibeablesConfig;
     /** Projects: goal-scoped folders the chats work in. Absent = off. */
     projects?: ProjectsConfig;
-    /** kraftwerk cloud manager this instance registers with. Absent = on with defaults; `enabled: false` opts out. */
+    /** The machine's cloud record lists this workspace. Absent = listed; `enabled: false` leaves it out. */
     cloud?: CloudConfig;
 }
 export interface ResolvedWorkspace {
@@ -209,6 +203,8 @@ export interface ResolvedWorkspace {
     config: WorkspaceConfig;
     /** Absolute path of the config file, if one exists. */
     configPath?: string;
+    /** kraftwerk.yml `id`, when set. */
+    id?: string;
     /** Absolute workflows root, if one exists. */
     workflowsRoot?: string;
     /** Absolute run-artifact directory (may not exist yet). */
@@ -250,3 +246,14 @@ export declare function workspaceSlug(ws: {
         slug?: string;
     };
 }): string;
+/** A workspace id: `ws_` and 10 lowercase base36 characters. */
+export declare const WORKSPACE_ID_RE: RegExp;
+/** A fresh workspace id for kraftwerk.yml. */
+export declare function newWorkspaceId(): string;
+/**
+ * Give an existing kraftwerk.yml an id, textually: one line inserted after
+ * the leading comments, the rest of the file byte for byte as it was (a
+ * re-serialised YAML document would lose the comments people keep there).
+ * Returns the id, or the one already there.
+ */
+export declare function addWorkspaceId(configPath: string): Promise<string>;

package/dist/config.js

@@ -1,4 +1,5 @@
-import { readFile, stat } from "node:fs/promises";
+import { randomInt } from "node:crypto";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { parse } from "yaml";
@@ -13,6 +14,7 @@ import { parse } from "yaml";
  *
  * All fields are optional — a valid kraftwerk.yml may be empty:
  *
+ *   id: ws_k3f9x2m7q1          # the workspace's identity across machines and clones (committed; `kraftwerk init` writes it)
  *   name: my-project           # display name (inspector header, "environment")
  *   icon: "⚡"                  # emoji shown as inspector favicon
  *   color: "#c2410c"           # accent for this workspace in the switcher (default: derived from the root)
@@ -37,11 +39,10 @@ import { parse } from "yaml";
   *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  *   projects:                  # goal-scoped folders (brief, systems of record, links) that chats work in (absent = off, bare key = on)
  *     root: kraftwerk-data/projects   # one folder per project, part of the workspace. Default: kraftwerk-data/projects
- *   cloud:                     # kraftwerk cloud manager — ON BY DEFAULT, `enabled: false` opts out
- *     url: https://srv.kraftwerk-cloud.netnode.cloud   # where the cloud answers (default). KRAFTWERK_CLOUD_URL env wins; "off" disables
- *     interval: 60             # seconds between heartbeats. Default: 60
- *   # No key here: the cloud hands the instance its identity and a claim code (Settings → Cloud in the UI);
- *   # a server that should register under an account unattended puts KRAFTWERK_CLOUD_TOKEN into .env.
+ *   cloud:                     # the machine's kraftwerk cloud record lists this workspace — `enabled: false` leaves it out
+ *     enabled: false           # a per-workspace veto; the machine's switch is `kraftwerk cloud on|off` (~/.kraftwerk/cloud.json)
+ *   # No key here: the daemon registers the MACHINE (its relay id) and `kraftwerk login` claims it.
+ *   # `url` and `interval` are deprecated: the cloud's origin is the machine's (cloud.json / KRAFTWERK_CLOUD_URL).
  */
 /** Stable, versionless URL of the workflow JSON schema (editor validation). */
 export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
@@ -96,19 +97,6 @@ export function projectsRootFor(project) {
     return path.resolve(project.root, p.root ?? PROJECTS_DEFAULT_ROOT);
 }
 export const CLOUD_DEFAULT_URL = "https://srv.kraftwerk-cloud.netnode.cloud";
-export const CLOUD_DEFAULT_INTERVAL = 60;
-/** The effective cloud settings when the feature is on; undefined when kraftwerk.yml or the environment turned it off. */
-export function cloudFor(project) {
-    const c = project.config.cloud ?? {};
-    const envUrl = process.env.KRAFTWERK_CLOUD_URL?.trim();
-    if (c.enabled === false || envUrl?.toLowerCase() === "off")
-        return undefined;
-    return {
-        url: (envUrl || c.url || CLOUD_DEFAULT_URL).replace(/\/+$/, ""),
-        interval: c.interval ?? CLOUD_DEFAULT_INTERVAL,
-        token: process.env.KRAFTWERK_CLOUD_TOKEN?.trim() || undefined,
-    };
-}
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
     const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
@@ -174,7 +162,7 @@ export async function resolveWorkspace(cwd) {
             const { config, legacyKeys } = loaded;
             const workflowsRoot = await findWorkflowsDir(dir, config.workflows);
             if (!bare || (workflowsRoot && path.resolve(workflowsRoot) === bare.workflowsRoot)) {
-                return { root: dir, config, configPath, workflowsRoot, outputDir: path.resolve(dir, config.output ?? "output"), ...(legacyKeys.length ? { legacyKeys } : {}) };
+                return { root: dir, config, configPath, ...(config.id ? { id: config.id } : {}), workflowsRoot, outputDir: path.resolve(dir, config.output ?? "output"), ...(legacyKeys.length ? { legacyKeys } : {}) };
             }
             return bare;
         }
@@ -213,7 +201,37 @@ export function slugFromFolder(folder) {
 export function workspaceSlug(ws) {
     return ws.config.slug ?? slugFromFolder(path.basename(ws.root));
 }
-const KNOWN_KEYS = ["name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "cloud"];
+/** A workspace id: `ws_` and 10 lowercase base36 characters. */
+export const WORKSPACE_ID_RE = /^ws_[a-z0-9]{10}$/;
+/** A fresh workspace id for kraftwerk.yml. */
+export function newWorkspaceId() {
+    const alphabet = "0123456789abcdefghijklmnopqrstuvwxyz";
+    let id = "ws_";
+    for (let i = 0; i < 10; i++)
+        id += alphabet[randomInt(alphabet.length)];
+    return id;
+}
+/**
+ * Give an existing kraftwerk.yml an id, textually: one line inserted after
+ * the leading comments, the rest of the file byte for byte as it was (a
+ * re-serialised YAML document would lose the comments people keep there).
+ * Returns the id, or the one already there.
+ */
+export async function addWorkspaceId(configPath) {
+    const text = await readFile(configPath, "utf8");
+    const existing = /^id:\s*["']?(ws_[a-z0-9]{10})["']?\s*(#.*)?$/m.exec(text);
+    if (existing)
+        return existing[1];
+    const id = newWorkspaceId();
+    const line = `id: ${id}   # this workspace's identity on every machine and clone — commit it, keep it`;
+    const lines = text.split("\n");
+    const first = lines.findIndex((l) => !/^\s*(#|$)/.test(l));
+    // Nothing but comments (or nothing at all): the id goes at the end.
+    const out = first === -1 ? `${text.replace(/\n*$/, text.trim() ? "\n" : "")}${line}\n` : [...lines.slice(0, first), line, ...lines.slice(first)].join("\n");
+    await writeFile(configPath, out);
+    return id;
+}
+const KNOWN_KEYS = ["id", "name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "cloud"];
 /**
  * Keys an older kraftwerk understood and this one ignores, so the files
  * that still carry them keep loading: `public:` and `tunnel:` (the
@@ -243,6 +261,9 @@ async function loadConfig(configPath) {
         if (!known.includes(key)) {
             throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);
         }
+        if (key === "id" && (typeof config[key] !== "string" || !WORKSPACE_ID_RE.test(config[key]))) {
+            throw new Error(`${path.basename(configPath)}: id must be "ws_" followed by 10 lowercase letters or digits (like ws_k3f9x2m7q1), got ${JSON.stringify(config[key])} — delete the line and run \`kraftwerk doctor --fix\` for a fresh one`);
+        }
         if (key === "slug" && (typeof config[key] !== "string" || !SLUG_RE.test(config[key]))) {
             throw new Error(`${path.basename(configPath)}: slug must be lowercase letters, digits and dashes, starting with a letter or digit (at most 63)`);
         }
@@ -302,7 +323,7 @@ function validateCloud(configPath, value) {
     const c = value;
     for (const key of Object.keys(c)) {
         if (key === "token") {
-            throw new Error(`${file}: cloud.token does not belong in kraftwerk.yml — put KRAFTWERK_CLOUD_TOKEN into .env (and only for unattended servers; a workspace with a UI is claimed with its code)`);
+            throw new Error(`${file}: cloud.token does not belong in kraftwerk.yml — the cloud knows the machine, and \`kraftwerk login\` claims it`);
         }
         if (!["enabled", "url", "interval"].includes(key)) {
             throw new Error(`${file}: cloud.${key} is unknown (allowed: enabled, url, interval)`);

package/dist/core/attention.d.ts

@@ -1,9 +1,13 @@
+import { type RunnerRef } from "./routines.js";
 /**
  * What needs you: every place where work is stuck on a human, with whose it
  * is. Two sources: requests waiting in a live chat (an approval, a question
  * — the agent cannot go on until someone answers) and failures nobody has
  * looked at yet (a routine or a workflow run that ended badly; unread
  * failure notifications). Oldest first: what waits longest comes first.
+ * A third, about setup rather than one piece of work: routines nobody runs
+ * (enabled, no runs_on) and routines naming an identity this machine has
+ * retired — both fire nowhere until someone assigns them a runner.
  *
  * The inspector builds everything urgent from this one list: the counts on
  * the rail, the "needs you" part of the bell, the tab title and "next",
@@ -29,7 +33,8 @@ export interface AttentionOwner {
 export interface AttentionItem {
     /** The request id (live requests) or the notification id (failures). */
     id: string;
-    kind: "approval" | "question" | "failed";
+    /** runner: routines without a runner, or naming a retired identity of this machine (see routines.ts). */
+    kind: "approval" | "question" | "failed" | "runner";
     /** What is asked, or what went wrong. */
     title: string;
     /** The session it sits in. */
@@ -41,6 +46,8 @@ export interface AttentionItem {
     owner: AttentionOwner;
     /** Failures: the notification to mark read once the item was opened. */
     notificationId?: string;
+    /** runner items: the routines concerned; `from` is the retired identity they name. */
+    routines?: RunnerRef[];
 }
 export interface AttentionView {
     items: AttentionItem[];

package/dist/core/attention.js

@@ -2,11 +2,13 @@ import { listAgents } from "./agents.js";
 import { waitingRequests } from "./chat/sessions.js";
 import { chatHref, listNotifications } from "./notifications.js";
 import { listProjects } from "./projects.js";
+import { runnerFindings } from "./routines.js";
 export async function listAttention() {
-    const [agents, projects, notes] = await Promise.all([
+    const [agents, projects, notes, runners] = await Promise.all([
         listAgents().catch(() => []),
         listProjects().catch(() => ({ projects: [] })),
         listNotifications().catch(() => ({ items: [] })),
+        runnerFindings().catch(() => ({ unassigned: [], retired: [] })),
     ]);
     const agentOf = (slug) => {
         const a = agents.find((x) => x.slug === slug);
@@ -65,6 +67,40 @@ export async function listAttention() {
             notificationId: n.id,
         };
     });
-    const items = [...waiting, ...failed].sort((a, b) => a.since.localeCompare(b.since));
+    // One item per problem, not per routine: the fix ("run these here") is one action for all of them.
+    const since = runners.since ?? new Date(0).toISOString();
+    // The fix lives on an agent profile's routines panel (/agents/<slug>/info — /agents/<slug> redirects
+    // to a chat). Routines of one agent: that profile and its rail entry; of several: the first agent's
+    // profile, whose banner adopts across the whole workspace.
+    const placed = (these) => {
+        const slugs = [...new Set(these.map((r) => r.agent))];
+        return slugs.length === 1
+            ? { href: `/agents/${slugs[0]}/info`, owner: { agent: agentOf(slugs[0]) } }
+            : { href: `/agents/${slugs[0]}/info`, owner: {} };
+    };
+    const runner = [];
+    const n = runners.unassigned.length;
+    if (n) {
+        runner.push({
+            id: "runner:unassigned",
+            kind: "runner",
+            title: `${n} routine${n === 1 ? " has" : "s have"} no runner — ${n === 1 ? "it fires" : "they fire"} nowhere until a machine runs ${n === 1 ? "it" : "them"}`,
+            since,
+            ...placed(runners.unassigned),
+            routines: runners.unassigned,
+        });
+    }
+    for (const old of [...new Set(runners.retired.map((r) => r.from))]) {
+        const these = runners.retired.filter((r) => r.from === old);
+        runner.push({
+            id: `runner:retired:${old}`,
+            kind: "runner",
+            title: `${these.length} routine${these.length === 1 ? " names" : "s name"} a retired identity ${old} — reassign`,
+            since,
+            ...placed(these),
+            routines: these,
+        });
+    }
+    const items = [...waiting, ...failed, ...runner].sort((a, b) => a.since.localeCompare(b.since));
     return { items };
 }