@netnodeag/kraftwerk 0.75.0 → 0.76.0

package/dist/cli/daemon-control.js

@@ -2,9 +2,10 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, openSync, promises as fs } from "node:fs";
 import path from "node:path";
 import chalk from "chalk";
-import { daemonLogPath, findDaemon, readDaemonFile } from "../core/daemon.js";
+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";
 /**
@@ -42,7 +43,7 @@ const ago = (iso) => {
 };
 async function getJson(port, p) {
     try {
-        const r = await fetch(`http://127.0.0.1:${port}${p}`, { signal: AbortSignal.timeout(2000) });
+        const r = await fetch(`http://127.0.0.1:${port}${p}`, { signal: AbortSignal.timeout(3000) });
         return r.ok ? (await r.json()) : null;
     }
     catch {
@@ -62,10 +63,14 @@ async function tail(n) {
     }
 }
 async function status() {
-    const [running, rec, installed] = await Promise.all([findDaemon(), readDaemonFile(), getPkgVersion()]);
-    const base = { installed, loginItem: daemonLoginItem() !== null, log: daemonLogPath() };
-    if (!running)
+    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;
+    if (found.state === "busy") {
+        return { running: true, busy: true, ...base, pid: found.pid, port: found.port, ...(rec?.version ? { version: rec.version } : {}), ...(rec?.startedAt ? { startedAt: rec.startedAt } : {}) };
+    }
     const [hub, relay] = await Promise.all([
         getJson(running.port, "/api/hub"),
         getJson(running.port, "/api/devices/relay"),
@@ -87,7 +92,12 @@ export async function daemonStatus(opts) {
         console.log(JSON.stringify(s, null, 2));
         process.exit(s.running ? 0 : NOT_RUNNING);
     }
-    if (s.running) {
+    if (s.busy) {
+        const up = ago(s.startedAt);
+        console.log(`${chalk.yellow("●")} kraftwerk daemon ${chalk.yellow("running, but slow to answer")} ${chalk.dim(`pid ${s.pid}, port ${s.port}${up ? `, up ${up}` : ""}${s.version ? `, ${s.version}` : ""}`)}`);
+        console.log(chalk.dim("  its process lives and holds its port — busy (agents at work, a loaded machine); ask again in a moment"));
+    }
+    else if (s.running) {
         const up = ago(s.startedAt);
         const behind = s.version && s.version !== s.installed ? chalk.yellow(` — ${s.installed} is installed: \`kraftwerk daemon restart\``) : "";
         console.log(`${chalk.green("●")} kraftwerk daemon ${chalk.green("running")} ${chalk.dim(`pid ${s.pid}${up ? `, up ${up}` : ""}${s.version ? `, ${s.version}` : ""}`)}${behind}`);
@@ -110,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)
@@ -138,9 +149,10 @@ async function launch(port) {
     return "background";
 }
 export async function startDaemon(opts) {
-    const running = await findDaemon();
-    if (running) {
-        console.log(`${chalk.green("✔")} the daemon already runs ${chalk.dim(`(pid ${running.pid}, http://localhost:${running.port})`)}`);
+    const running = await daemonState();
+    if (running.state !== "stopped") {
+        const busy = running.state === "busy" ? ", busy — slow to answer right now" : "";
+        console.log(`${chalk.green("✔")} the daemon already runs ${chalk.dim(`(pid ${running.pid}, http://localhost:${running.port}${busy})`)}`);
         return;
     }
     const how = await launch(opts.port);
@@ -157,9 +169,10 @@ export async function startDaemon(opts) {
 }
 /** Stop it: its supervisor first (else it would start the daemon again), then wait until it is gone. */
 async function stopRunning() {
-    const [running, rec] = await Promise.all([findDaemon(), readDaemonFile()]);
-    if (!running)
+    const [found, rec] = await Promise.all([daemonState(), readDaemonFile()]);
+    if (found.state === "stopped")
         return false;
+    const running = found;
     const target = rec?.pid === running.pid && alive(rec.supervisor) ? rec.supervisor : running.pid;
     process.kill(target, "SIGTERM");
     const gone = await until(async () => !alive(running.pid) && !alive(target) && (await findDaemon()) === null, 20_000);
@@ -182,9 +195,15 @@ export async function stopDaemon() {
 }
 /** Restart: the running daemon relaunches itself with the current install (its supervisor stays); none running — start one. */
 export async function restartDaemon(opts) {
-    const running = await findDaemon();
-    if (!running)
+    const found = await daemonState();
+    if (found.state === "stopped")
         return startDaemon(opts);
+    if (found.state === "busy") {
+        // It does not answer, so it cannot be asked to relaunch: stopping it is the only way (its agents are interrupted).
+        await stopRunning();
+        return startDaemon(opts);
+    }
+    const running = found;
     // The restart route lives in every workspace (the daemon's root answers machine routes only); any open one will do.
     const hub = await getJson(running.port, "/api/hub");
     const slug = hub?.workspaces?.[0]?.slug;

package/dist/cli/daemon-login.js

@@ -3,7 +3,7 @@ import { existsSync, promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import chalk from "chalk";
-import { daemonLogPath, findDaemon } from "../core/daemon.js";
+import { daemonLogPath, daemonState } from "../core/daemon.js";
 import { selfCommand } from "../core/self-command.js";
 import { tildify } from "../core/instances.js";
 /**
@@ -72,8 +72,8 @@ export async function installDaemon(opts) {
     await fs.writeFile(file, renderPlist([cmd, ...args], env, logPath()));
     // An older version of the item is replaced: unload it first (an error just means it was not loaded).
     spawnSync(launchctl(), ["bootout", `${domain()}/${LAUNCH_LABEL}`], { stdio: "ignore" });
-    const running = await findDaemon();
-    if (running) {
+    const running = await daemonState();
+    if (running.state !== "stopped") {
         // Loading now would start a second daemon, which refuses to run. launchd loads the file at the next login.
         console.log(`${chalk.green("✔")} login item installed: ${chalk.dim(tildify(file))}`);
         console.log(chalk.dim(`  a daemon already runs (pid ${running.pid}); from the next login on, launchd starts it`));

package/dist/cli/daemon.js

@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { DAEMON_PORT, findDaemon, lastOpenRoots, setDaemonVersion, writeDaemonFile } from "../core/daemon.js";
+import { DAEMON_PORT, daemonState, lastOpenRoots, setDaemonVersion, writeDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
 import { startPushWatcher } from "../server/push.js";
@@ -22,9 +22,10 @@ export async function runDaemon(opts) {
         process.env.KRAFTWERK_UI_HOST ||= "0.0.0.0";
     if (process.env.KRAFTWERK_UI_SUPERVISED !== "1")
         return supervise(["daemon", ...(opts.port ? ["--port", opts.port] : [])], "the daemon");
-    const running = await findDaemon();
-    if (running && running.pid !== process.pid) {
-        console.error(chalk.red(`✖ a kraftwerk daemon already runs (pid ${running.pid}, port ${running.port})`));
+    // A busy one counts too: a second daemon would only crash on its port.
+    const running = await daemonState();
+    if (running.state !== "stopped" && running.pid !== process.pid) {
+        console.error(chalk.red(`✖ a kraftwerk daemon already runs (pid ${running.pid}, port ${running.port}${running.state === "busy" ? ", busy right now" : ""})`));
         process.exit(1);
     }
     const port = Number(opts.port ?? process.env.KRAFTWERK_DAEMON_PORT ?? DAEMON_PORT);

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,16 +2,19 @@ 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";
 import { legacyFindings, versionLt } from "./doctor-legacy.js";
 import { listDevices } from "../core/devices.js";
 import { slugClashes } from "../core/instances.js";
-import { findDaemon } from "../core/daemon.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) {
@@ -214,9 +248,10 @@ export async function runDoctor(cwd) {
         report("warn", "KRAFTWERK_UI_TRUST_NETWORK=1", "anyone who reaches the UI over the network uses it without pairing — unset it and pair devices instead (`kraftwerk devices pair`)");
     report("info", devices.length ? `${devices.length} paired device(s)` : "no paired devices", devices.length ? devices.map((d) => d.name).join(", ") : "a phone or another computer can use kraftwerk once paired: `kraftwerk ui --lan`, then `kraftwerk devices pair`");
     // The daemon: whether one runs, and whether it starts at login.
-    const daemon = await findDaemon();
+    const state = await daemonState();
+    const daemon = state.state === "stopped" ? null : state;
     const loginItem = daemonLoginItem();
-    report("info", daemon ? `kraftwerk daemon running on :${daemon.port}` : "no kraftwerk daemon running", loginItem
+    report("info", !daemon ? "no kraftwerk daemon running" : daemon.state === "busy" ? `kraftwerk daemon running on :${daemon.port}, but slow to answer (busy)` : `kraftwerk daemon running on :${daemon.port}`, loginItem
         ? daemon
             ? "starts at login · `kraftwerk daemon status` for more"
             : "starts at login, but not running now · `kraftwerk daemon start`, `kraftwerk daemon logs` says why it stopped"

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