@netnodeag/kraftwerk 0.75.1 → 0.76.0

package/dist/cli/daemon-control.js

@@ -5,6 +5,7 @@ import chalk from "chalk";
 import { daemonLogPath, daemonState, findDaemon, readDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
 import { selfCommand } from "../core/self-command.js";
+import { localIdentity } from "../core/identity.js";
 import { getPkgVersion } from "../server/version.js";
 import { daemonLoginItem, startLoginItem } from "./daemon-login.js";
 /**
@@ -62,8 +63,8 @@ async function tail(n) {
     }
 }
 async function status() {
-    const [found, rec, installed] = await Promise.all([daemonState(), readDaemonFile(), getPkgVersion()]);
-    const base = { installed, loginItem: daemonLoginItem() !== null, log: daemonLogPath() };
+    const [found, rec, installed, identity] = await Promise.all([daemonState(), readDaemonFile(), getPkgVersion(), localIdentity()]);
+    const base = { installed, loginItem: daemonLoginItem() !== null, log: daemonLogPath(), identity };
     if (found.state === "stopped")
         return { running: false, ...base };
     const running = found;
@@ -119,6 +120,7 @@ export async function daemonStatus(opts) {
             console.log(chalk.dim(`  last trouble in the log: ${crash.trim().slice(0, 200)}`));
         console.log(chalk.dim("  `kraftwerk daemon start` starts it in the background"));
     }
+    console.log(chalk.dim(`  identity: ${s.identity} · routines with runs_on: ${s.identity} fire here (\`kraftwerk whoami\`)`));
     console.log(chalk.dim(`  login item: ${s.loginItem ? "starts at login" : "not installed (`kraftwerk daemon install` starts it at login)"}`));
     console.log(chalk.dim(`  log: ${tildify(s.log)} · \`kraftwerk daemon logs -f\` follows it`));
     if (!s.running)

package/dist/cli/doctor.d.ts

@@ -1 +1,3 @@
-export declare function runDoctor(cwd: string): Promise<void>;
+export declare function runDoctor(cwd: string, opts?: {
+    fix?: boolean;
+}): Promise<void>;

package/dist/cli/doctor.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { cloudFor, ignoreEntryFor, isDir, reposRootFor, resolveWorkspace, workspaceSlug } from "../config.js";
+import { addWorkspaceId, cloudFor, ignoreEntryFor, isDir, reposRootFor, resolveWorkspace, workspaceSlug } from "../config.js";
 import { discoverWorkflows } from "../discover.js";
 import { missingEnv } from "../yaml.js";
 import { applyDotenv, DOTENV_FILE } from "../dotenv.js";
@@ -12,6 +12,9 @@ import { slugClashes } from "../core/instances.js";
 import { daemonState } from "../core/daemon.js";
 import { daemonLoginItem } from "./daemon-login.js";
 import { readRelaySettings } from "../server/relay.js";
+import { readIdentity, identityString } from "../core/identity.js";
+import { adoptUnassigned, runnerFindings } from "../core/routines.js";
+import { setDefaultWorkspace, Workspace } from "../core/workspace.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -42,7 +45,7 @@ function cliVersion(command) {
         return undefined;
     return (r.stdout || r.stderr).trim().split("\n")[0];
 }
-export async function runDoctor(cwd) {
+export async function runDoctor(cwd, opts = {}) {
     let failures = 0;
     // Runtime.
     const [major] = process.versions.node.split(".").map(Number);
@@ -100,6 +103,12 @@ export async function runDoctor(cwd) {
         report("ok", `${path.basename(project.configPath)} well-formed`, keys.length ? keys.map((k) => `${k}: ${show(cfg[k])}`).join(", ") : "empty — defaults apply");
         if (!cfg.name)
             report("info", "name not set in kraftwerk.yml", "inspector header falls back to the folder name");
+        if (cfg.id)
+            report("ok", `workspace id: ${cfg.id}`);
+        else if (opts.fix)
+            report("ok", `workspace id: ${await addWorkspaceId(project.configPath)}`, `added to ${path.basename(project.configPath)} — commit it`);
+        else
+            report("warn", "no workspace id in kraftwerk.yml", "the same workspace on every clone is known by it — `kraftwerk doctor --fix` adds one");
         for (const key of ["workflows", "knowledge", "agents", "output"]) {
             const value = cfg[key];
             if (!value)
@@ -143,6 +152,31 @@ export async function runDoctor(cwd) {
         else
             report("ok", label, "not inside a git repository");
     }
+    // Routine runners: a routine fires only on the machine its runs_on names.
+    setDefaultWorkspace(new Workspace({ root: project.root, outputDir: project.outputDir }));
+    const me = identityString(await readIdentity());
+    const runners = await runnerFindings().catch(() => ({ unassigned: [], retired: [] }));
+    const names = (rs) => rs.map((r) => `${r.agent}/${r.id}`).join(", ");
+    if (!runners.unassigned.length && !runners.retired.length) {
+        report("ok", `routines: runner identity ${me}`, "every enabled routine names its runner");
+    }
+    else if (opts.fix) {
+        const r = await adoptUnassigned({ retired: true });
+        report("ok", `${r.adopted.length} routine(s) now run here (${me})`, names(r.adopted));
+        if (r.commit?.ok)
+            report("ok", `committed ${r.files.join(", ")}`, "push so the other clones see who runs them");
+        else if (r.commit)
+            report("warn", `written, not committed: ${r.commit.error}`, `commit ${r.files.join(", ")} yourself`);
+    }
+    else {
+        if (runners.unassigned.length) {
+            report("warn", `${runners.unassigned.length} enabled routine(s) have no runner — they fire nowhere`, `${names(runners.unassigned)} · \`kraftwerk doctor --fix\` (or \`kraftwerk routines adopt\`) runs them here: ${me}`);
+        }
+        for (const old of [...new Set(runners.retired.map((r) => r.from))]) {
+            const these = runners.retired.filter((r) => r.from === old);
+            report("warn", `${these.length} routine(s) name the retired identity ${old}`, `${names(these)} · \`kraftwerk doctor --fix\` moves them to ${me} and commits`);
+        }
+    }
     // Cloud manager: registration is best-effort at runtime, so doctor only says what would happen.
     const cloud = cloudFor(project);
     if (cloud) {

package/dist/cli/init.js

@@ -1,7 +1,7 @@
 import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import chalk from "chalk";
-import { CONFIG_SCHEMA_URL, gitignoreHas, SCHEMA_URL } from "../config.js";
+import { CONFIG_SCHEMA_URL, gitignoreHas, newWorkspaceId, SCHEMA_URL } from "../config.js";
 import { DOTENV_FILE } from "../dotenv.js";
 import { initBundle, writeConcept } from "../okf.js";
 /**
@@ -9,12 +9,15 @@ import { initBundle, writeConcept } from "../okf.js";
  * command: kraftwerk.yml (root marker + config), a kraftwerk-data/ tree with
  * a runnable example workflow, a starter agent ("max"), a demo
  * knowledge bundle, and an output ignore entry. Everything is idempotent:
- * existing files are left untouched and reported.
+ * existing files are left untouched and reported. A new kraftwerk.yml gets
+ * a fresh workspace id (`id: ws_…`); an existing one is not touched —
+ * `kraftwerk doctor --fix` adds an id to a file that has none.
  */
 const DATA_DIR = "kraftwerk-data";
 const configTemplate = (name) => `# yaml-language-server: $schema=${CONFIG_SCHEMA_URL}
 # kraftwerk project config — also marks the project root for the CLI.
 # All fields optional. Docs: https://github.com/NETNODEAG/kraftwerk
+id: ${newWorkspaceId()}   # this workspace's identity on every machine and clone — commit it, keep it (a copy of this workspace needs a new one)
 name: ${JSON.stringify(name)}   # display name, shown in the inspector header + browser tab
 # slug: my-team   # this workspace's address on this machine (my-team.localhost); default: the folder name
 icon: "⚡"   # emoji shown as the inspector favicon

package/dist/cli/kraftwerk.js

@@ -21,6 +21,7 @@ import { registerDevicesCommands } from "./devices.js";
 import { registerDaemonCommand } from "./daemon.js";
 import { registerRemoteCommand } from "./remote.js";
 import { registerJournalCommands } from "./journal.js";
+import { registerWhoamiCommand } from "./whoami.js";
 import { applyDotenv } from "../dotenv.js";
 import { resolveWorkspace } from "../config.js";
 import { registerRoutineCommands } from "./routines.js";
@@ -34,7 +35,8 @@ import { runUi } from "./ui.js";
  *   kraftwerk run [workflow] [text]   run one (prompts interactively if omitted)
  *   kraftwerk runs [show <id>]        inspect past runs from their traces
  *   kraftwerk knowledge ...           Knowledge: OKF bundles (list/get/put/verify/...)
- *   kraftwerk routines ...            per-agent scheduled prompts (list/add/remove/enable/run)
+ *   kraftwerk routines ...            per-agent scheduled prompts (list/add/remove/enable/run/adopt)
+ *   kraftwerk whoami                  this machine's identity (handle@machine), the runner routines name
  *   kraftwerk ui                      start the inspector web UI (localhost:1981)
  *   kraftwerk workspaces ...          known workspaces on this machine (list/start/stop/forget)
  *   kraftwerk projects ...            goal-scoped project folders (list/create/show/link/log/remove)
@@ -44,7 +46,7 @@ import { runUi } from "./ui.js";
  *   kraftwerk trash ...               what was deleted: list, restore, purge, empty
  *   kraftwerk devices ...             paired devices: list, pair one, revoke one
  *   kraftwerk daemon                  the machine's kraftwerk: every open workspace at <slug>.localhost
- *   kraftwerk doctor                  preflight: harness CLIs, docker, workflows, env
+ *   kraftwerk doctor [--fix]          preflight: harness CLIs, docker, workflows, env, routine runners
  *   kraftwerk validate [paths...]     validate without executing
  *
  * Workflows are auto-discovered under src/workflows/ (or workflows/), from
@@ -265,9 +267,10 @@ program
 });
 program
     .command("doctor")
-    .description("Preflight: harness CLIs, docker, workflows, declared environment variables")
-    .action(async () => {
-    await runDoctor(process.cwd());
+    .description("Preflight: harness CLIs, docker, workflows, declared environment variables, routine runners, workspace id")
+    .option("--fix", "Apply the fixes doctor offers: run unassigned routines here, move routines off a retired identity (both committed), add a workspace id")
+    .action(async (opts) => {
+    await runDoctor(process.cwd(), { fix: !!opts.fix });
 });
 const runs = program
     .command("runs")
@@ -298,6 +301,7 @@ registerDevicesCommands(program);
 registerDaemonCommand(program);
 registerRemoteCommand(program);
 registerJournalCommands(program);
+registerWhoamiCommand(program);
 program
     .command("ui")
     .description("Start the inspector web UI for this project's runs and workflows")

package/dist/cli/routines.d.ts

@@ -3,7 +3,8 @@ import type { Command } from "commander";
  * `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 declare function initContext(): Promise<{

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"];
@@ -70,6 +71,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 +100,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"],
@@ -71,6 +72,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 +101,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)
@@ -165,6 +166,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;
     /**
@@ -209,6 +216,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 +259,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)
@@ -174,7 +176,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 +215,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 +275,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)`);
         }

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