@netnodeag/kraftwerk 0.75.1 → 0.77.0

package/README.md

@@ -296,8 +296,8 @@ fields are optional. `workflows:` sets the workflows root, `output:` the
 run-artifact directory (default `output/`), `knowledge:` the OKF bundle root
 (default `knowledge/`), and `agents:` the agent-definition root (default
 `agents/`). `repos:` turns on the [repositories](#repositories) folder.
-`cloud:` tunes (or turns off) the registration with the
-[kraftwerk cloud](#inspector-in-the-kraftwerk-cloud), which is on by default.
+`cloud: { enabled: false }` leaves the workspace out of this machine's
+record in the [kraftwerk cloud](#this-machine-in-the-kraftwerk-cloud).
 
 `name:` is the title shown in the UI and can change freely. `slug:` is the
 workspace's address on this machine. It defaults to the folder name
@@ -486,38 +486,44 @@ repo. Agent logins made inside the container persist in the `agent-home`
 volume. This is a different image from the `kraftwerk-runner` sandbox
 (`runner/Dockerfile`) used by `run --sandbox`.
 
-### Inspector in the kraftwerk cloud
+### This machine in the kraftwerk cloud
 
 The kraftwerk cloud is the `~/.kraftwerk` registry made reachable over the
-internet: every `kraftwerk ui` registers there when it starts and sends a
-heartbeat while it runs, so you can see from anywhere which of your
-workspaces are up, on which machine, with which agents — and an admin sees
-every instance at once. **This is on by default.** The record carries the
-workspace name, icon and colour, the machine, the root, the version, and
-the agent and channel roster. Registration
-is best-effort: a cloud that is down never affects the UI.
-
-No key goes into kraftwerk.yml. The cloud hands the instance an identity
-(kept under `~/.kraftwerk/cloud/`, so a restart updates the record) and a
-**claim code**, shown under Settings → Cloud in the UI. Sign in at the
-cloud, type the code (or follow the "claim in the cloud" link), and the
-workspace appears under *My instances*; the instance learns about the claim
-with its next heartbeat.
+internet: the daemon (`kraftwerk daemon`) registers **this machine** once
+when it starts and sends a heartbeat while it runs; the workspaces it serves
+ride along as children of that record, so you can see from anywhere which
+of your workspaces are up, and where. **This is on by default.** A
+standalone `kraftwerk ui` never registers. Registration is best-effort: a
+cloud that is down never affects the UI.
+
+The machine's id is its relay id (the key in `~/.kraftwerk/relay.json`,
+created at the daemon's first start with the relay still off), proven with
+the relay secret. Until someone claims the machine it registers
+anonymously: workspace names, slugs and ids only, no paths. Claiming
+happens in the browser — no password passes through the CLI:
+
+```bash
+kraftwerk login --open    # prints (and opens) the claim link and code, waits for the claim
+kraftwerk cloud           # registered? claimed? url, machine id, last heartbeat
+kraftwerk logout          # release the machine; a fresh claim code follows
+kraftwerk cloud off       # turn it off for this machine (the daemon says goodbye); `on [--url]` back on
+```
+
+The claim code is also shown under Settings → Cloud. The switch and the
+cloud's origin live in `~/.kraftwerk/cloud.json` (`{ "enabled": false,
+"url": "…" }`); `KRAFTWERK_CLOUD_URL` in the environment wins (`off` turns
+the feature off — what the test suites set). In kraftwerk.yml, `cloud:` is
+a per-workspace veto only:
 
 ```yaml
 cloud:
-  url: https://srv.kraftwerk-cloud.netnode.cloud   # default
-  interval: 60                                     # seconds between heartbeats (default 60)
-  enabled: false                                   # opt out of the cloud for this workspace
+  enabled: false   # leave this workspace out of the machine's record
 ```
 
-`KRAFTWERK_CLOUD_URL` in the environment wins over the file (`off` turns the
-feature off everywhere — what the test suites set). A server that starts
-unattended and should register under an account without a claim puts an
-account token from the cloud UI into `.env` as `KRAFTWERK_CLOUD_TOKEN`; a
-`token:` key in kraftwerk.yml is refused. `/api/meta` reports the
-connection state and the claim code; `kraftwerk doctor` prints what the
-block will do.
+(`cloud.url` there is deprecated — honored with a warning when the machine
+names no origin — and `cloud.interval` is ignored: the cloud sets the
+cadence.) `/api/meta` and `/api/cloud` report the machine's state and claim
+code; `kraftwerk doctor` prints what happens to the workspace.
 
 ## Projects
 

package/dist/cli/cloud.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerCloudCommands(program: Command): void;

package/dist/cli/cloud.js

@@ -0,0 +1,262 @@
+import { spawn } from "node:child_process";
+import os from "node:os";
+import chalk from "chalk";
+import { CloudError, claimUrlFor, envCloudOff, machineCloud, machineGoodbye, machineHeartbeat, machineRegister, machineUnlink, writeCloudFile, } from "../core/cloud.js";
+import { findDaemon } from "../core/daemon.js";
+import { identityString, readIdentity } from "../core/identity.js";
+import { relayId, fromBase64Url } from "../client/relay.js";
+import { machineCredentials, readRelaySettings } from "../server/relay.js";
+import { getPkgVersion } from "../server/version.js";
+const POLL_MS = 2000;
+async function daemonCloud(port, method, route, body) {
+    const r = await fetch(`http://127.0.0.1:${port}${route}`, {
+        method,
+        headers: body ? { "content-type": "application/json" } : {},
+        ...(body ? { body: JSON.stringify(body) } : {}),
+        signal: AbortSignal.timeout(15_000),
+    });
+    const data = (await r.json().catch(() => ({})));
+    if (!r.ok)
+        throw new Error(data.error ?? `${r.status} from the daemon`);
+    return data;
+}
+const fail = (message, code = 1) => {
+    console.error(chalk.red(`✖ ${message}`));
+    process.exit(code);
+};
+function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+    }
+    catch { }
+}
+/** The machine's id without creating a key: null before the daemon's first start (or `kraftwerk login`). */
+async function machineIdIfAny() {
+    const s = await readRelaySettings();
+    return s ? relayId(fromBase64Url(s.publicKey)) : null;
+}
+async function hello() {
+    const id = await readIdentity();
+    return { name: id.machine, handle: id.handle, hostname: os.hostname(), platform: `${process.platform}-${process.arch}`, version: await getPkgVersion() };
+}
+function printClaim(st) {
+    if (!st.claimCode)
+        return;
+    console.log(`  claim code  ${chalk.bold(st.claimCode)}`);
+    console.log(`  claim link  ${chalk.cyan(st.claimUrl ?? claimUrlFor(st.url, st.claimCode) ?? "")}`);
+}
+async function showStatus(opts) {
+    const [cloud, identity, id, daemon] = await Promise.all([machineCloud(), readIdentity(), machineIdIfAny(), findDaemon()]);
+    const live = daemon ? await daemonCloud(daemon.port, "GET", "/api/cloud").catch(() => null) : null;
+    const out = {
+        enabled: cloud.enabled,
+        url: cloud.url,
+        source: cloud.source,
+        ...(cloud.reason ? { reason: cloud.reason } : {}),
+        machine: identityString(identity),
+        id,
+        daemon: !!daemon,
+        state: live?.state ?? "off",
+        registered: live?.state === "connected",
+        claimed: !!live?.account,
+        account: live?.account ?? null,
+        claimCode: live?.claimCode ?? null,
+        claimUrl: live?.claimUrl ?? null,
+        lastSeen: live?.lastSeen ?? null,
+        interval: live?.interval ?? null,
+        workspaces: live?.workspaces ?? null,
+        ...(live?.error ? { error: live.error } : {}),
+    };
+    if (opts.json)
+        return void console.log(JSON.stringify(out, null, 2));
+    const dot = !cloud.enabled ? chalk.dim("○") : out.claimed ? chalk.green("●") : out.registered ? chalk.yellow("●") : chalk.dim("●");
+    console.log(`${dot} kraftwerk cloud ${cloud.enabled ? chalk.green("on") : chalk.dim("off")} ${chalk.dim(`${cloud.url} (${cloud.source})`)}`);
+    if (!cloud.enabled)
+        console.log(chalk.dim(`  ${cloud.reason}`));
+    console.log(`  machine     ${identityString(identity)} ${chalk.dim(id ?? "no id yet — created at the daemon's first start")}`);
+    if (!cloud.enabled)
+        return;
+    if (!daemon) {
+        console.log(`  state       ${chalk.dim("not reporting — the daemon registers this machine (`kraftwerk daemon start`)")}`);
+        return;
+    }
+    if (!live)
+        return void console.log(`  state       ${chalk.yellow("the daemon did not answer")}`);
+    if (live.state === "error")
+        console.log(`  state       ${chalk.red("error")} ${chalk.dim(live.error ?? "")}`);
+    else if (live.state !== "connected")
+        console.log(`  state       ${live.state}`);
+    else if (live.account)
+        console.log(`  state       ${chalk.green("claimed")} by ${chalk.bold(live.account)}`);
+    else
+        console.log(`  state       ${chalk.yellow("registered, unclaimed")} ${chalk.dim("— `kraftwerk login` claims it")}`);
+    if (live.state === "connected" && !live.account)
+        printClaim(live);
+    if (live.lastSeen)
+        console.log(`  heartbeat   ${new Date(live.lastSeen).toLocaleTimeString()} ${chalk.dim(`every ${live.interval ?? 60}s · ${live.workspaces ?? 0} workspace${live.workspaces === 1 ? "" : "s"} reported`)}`);
+}
+async function setEnabled(enabled, url) {
+    if (url && !/^https?:\/\/[^/?#]+\/?$/.test(url))
+        fail("--url is the cloud's origin, e.g. https://srv.kraftwerk-cloud.netnode.cloud", 2);
+    await writeCloudFile({ enabled, url });
+    const cloud = await machineCloud();
+    const daemon = await findDaemon();
+    // The daemon follows at once (off: goodbye); best-effort — the file is what counts at its next start.
+    const live = daemon ? await daemonCloud(daemon.port, "POST", "/api/cloud", { enabled, ...(url ? { url } : {}) }).catch(() => null) : null;
+    if (!enabled) {
+        console.log(`${chalk.green("✔")} cloud off for this machine ${chalk.dim(daemon ? (live ? "— the daemon said goodbye" : "— the daemon did not answer; it stops reporting at its next start") : "")}`);
+        return;
+    }
+    if (envCloudOff())
+        console.log(chalk.yellow("⚠ KRAFTWERK_CLOUD_URL=off in this environment keeps it off here"));
+    console.log(`${chalk.green("✔")} cloud on for this machine: ${chalk.cyan(cloud.url)}`);
+    if (!daemon)
+        console.log(chalk.dim("  the daemon registers this machine when it runs (`kraftwerk daemon start`); `kraftwerk login` claims it"));
+    else if (live?.state === "connected")
+        console.log(chalk.dim(live.account ? `  registered, claimed by ${live.account}` : "  registered — `kraftwerk login` claims it"));
+    else if (live?.state === "error")
+        console.log(chalk.yellow(`  the cloud did not answer: ${live.error ?? ""} (the daemon retries)`));
+}
+async function session() {
+    const daemon = await findDaemon();
+    if (daemon) {
+        const port = daemon.port;
+        // Off in the daemon (it read cloud.json before `login` turned it on): turning it on registers.
+        let first = true;
+        return {
+            status: async () => {
+                const st = first ? await daemonCloud(port, "POST", "/api/cloud", { enabled: true }) : await daemonCloud(port, "POST", "/api/cloud/sync");
+                first = false;
+                return st;
+            },
+            end: async () => { },
+        };
+    }
+    const cloud = await machineCloud();
+    const version = await getPkgVersion();
+    const creds = await machineCredentials();
+    let registered = false;
+    return {
+        status: async () => {
+            try {
+                const r = registered ? await machineHeartbeat(cloud.url, creds, { version }) : await machineRegister(cloud.url, creds, await hello(), []);
+                registered = true;
+                return { state: "connected", url: cloud.url, account: r.account, claimCode: r.claimCode, claimUrl: claimUrlFor(cloud.url, r.claimCode) };
+            }
+            catch (err) {
+                if (err instanceof CloudError && err.status === 403)
+                    throw new Error(`${cloud.url} refuses this machine's secret (403) — another machine holds this id`);
+                return { state: "error", url: cloud.url, error: err.message };
+            }
+        },
+        // Without a daemon nothing reports afterwards: the record says so now instead of after the grace period.
+        end: async () => {
+            if (registered)
+                await machineGoodbye(cloud.url, creds, version).catch(() => { });
+        },
+    };
+}
+async function login(opts) {
+    if (envCloudOff())
+        fail("KRAFTWERK_CLOUD_URL=off in this environment — unset it to log in", 2);
+    const timeout = Number(opts.timeout ?? 600);
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        fail("--timeout must be a positive number of seconds", 2);
+    const before = await machineCloud();
+    if (!before.enabled) {
+        await writeCloudFile({ enabled: true });
+        console.log(chalk.dim("cloud turned on for this machine (`kraftwerk cloud off` turns it off)"));
+    }
+    const s = await session().catch((err) => fail(err.message));
+    try {
+        let st = await s.status();
+        if (st.state === "off")
+            fail(`the daemon keeps the cloud off: ${st.reason ?? "off"}`);
+        if (st.state !== "connected")
+            fail(`could not reach ${st.url}: ${st.error ?? st.state}`);
+        if (st.account) {
+            console.log(`${chalk.green("✔")} already logged in as ${chalk.bold(st.account)} ${chalk.dim(`(${st.url}) — \`kraftwerk logout\` releases this machine`)}`);
+            return;
+        }
+        if (!st.claimCode)
+            fail(`${st.url} handed out no claim code`);
+        console.log(`Sign in (or sign up) in the browser and claim this machine:`);
+        printClaim(st);
+        if (opts.open && st.claimUrl)
+            openBrowser(st.claimUrl);
+        console.log(chalk.dim(`waiting for the claim … (Ctrl-C stops; the code stays valid)`));
+        const until = Date.now() + timeout * 1000;
+        while (Date.now() < until) {
+            await new Promise((r) => setTimeout(r, Math.min(POLL_MS, Math.max(0, until - Date.now()))));
+            st = await s.status().catch((err) => ({ ...st, state: "error", error: err.message }));
+            if (st.account) {
+                console.log(`${chalk.green("✔")} logged in as ${chalk.bold(st.account)} ${chalk.dim(`— this machine is in your account at ${st.url}`)}`);
+                return;
+            }
+        }
+        fail(`not claimed within ${timeout}s — the code stays valid; \`kraftwerk login\` waits again`);
+    }
+    finally {
+        await s.end();
+    }
+}
+async function logout() {
+    if (envCloudOff())
+        fail("KRAFTWERK_CLOUD_URL=off in this environment", 2);
+    const cloud = await machineCloud();
+    if (!cloud.enabled)
+        fail(`the cloud is off for this machine — ${cloud.reason}`, 2);
+    const daemon = await findDaemon();
+    let st;
+    if (daemon) {
+        st = await daemonCloud(daemon.port, "POST", "/api/cloud/unlink").catch((err) => fail(err.message));
+    }
+    else {
+        const creds = await machineCredentials();
+        const r = await machineUnlink(cloud.url, creds, await getPkgVersion()).catch((err) => fail(err instanceof CloudError && err.status === 404 ? `this machine is not registered at ${cloud.url}` : `${cloud.url}: ${err.message}`));
+        st = { url: cloud.url, claimCode: r.claimCode, claimUrl: claimUrlFor(cloud.url, r.claimCode) };
+    }
+    console.log(`${chalk.green("✔")} logged out — this machine is unclaimed at ${st.url}`);
+    printClaim(st);
+    console.log(chalk.dim("  `kraftwerk login` claims it again"));
+}
+export function registerCloudCommands(program) {
+    const cloud = program
+        .command("cloud")
+        .description("This machine in the kraftwerk cloud: status, on, off (`kraftwerk login` claims it)")
+        .option("--json", "Machine-readable output")
+        .addHelpText("after", `
+The daemon registers this machine once; its open workspaces ride along.
+  kraftwerk cloud                 registered? claimed? url, machine id, last heartbeat
+  kraftwerk cloud on [--url <u>]  turn it on (~/.kraftwerk/cloud.json); the daemon follows at once
+  kraftwerk cloud off             turn it off; the running daemon says goodbye
+  kraftwerk login [--open]        claim this machine into your account (in the browser)
+  kraftwerk logout                release it
+A workspace stays out with \`cloud: { enabled: false }\` in its kraftwerk.yml.`)
+        .action(async (opts) => showStatus(opts));
+    cloud
+        .command("status")
+        .description("Registered? claimed? url, machine id, last heartbeat")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => showStatus({ json: opts.json ?? cloud.opts().json }));
+    cloud
+        .command("on")
+        .description("Turn the cloud on for this machine (the running daemon registers at once)")
+        .option("--url <url>", "The cloud's origin (default: the kraftwerk cloud)")
+        .action(async (opts) => setEnabled(true, opts.url));
+    cloud
+        .command("off")
+        .description("Turn the cloud off for this machine (the running daemon says goodbye)")
+        .action(async () => setEnabled(false));
+    program
+        .command("login")
+        .description("Claim this machine into your kraftwerk cloud account: prints the claim link and code, waits for the claim")
+        .option("--open", "Open the claim link in the browser")
+        .option("--timeout <seconds>", "How long to wait for the claim", "600")
+        .action(async (opts) => login(opts));
+    program
+        .command("logout")
+        .description("Release this machine from its kraftwerk cloud account (a fresh claim code follows)")
+        .action(async () => logout());
+}

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/daemon.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import { DAEMON_PORT, daemonState, lastOpenRoots, setDaemonVersion, writeDaemonFile } from "../core/daemon.js";
 import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
+import { startMachineCloud } from "../server/cloud.js";
 import { startPushWatcher } from "../server/push.js";
 import { applyRelay, relayPush } from "../server/relay.js";
 import { startHub } from "../server/server.js";
@@ -51,6 +52,14 @@ export async function runDaemon(opts) {
         console.log(`  ${chalk.cyan(o.url)} ${chalk.dim(o.name)}${o.aliasPort ? chalk.dim(` · also :${o.aliasPort}`) : ""}`);
     if (!hub.list().length)
         console.log(chalk.dim("  no workspace open yet — `kraftwerk ui` in a workspace folder opens it here"));
+    // The machine in the kraftwerk cloud: registered once, the open workspaces as its children (`kraftwerk cloud`, `kraftwerk login`).
+    const cloud = await startMachineCloud({ version: await getPkgVersion(), workspaces: () => hub.list(), owner: hub });
+    if (cloud.state === "connected") {
+        console.log(`${chalk.green("✔")} Cloud: ${chalk.cyan(cloud.url)} ${chalk.dim(cloud.account ? `(claimed by ${cloud.account})` : `(unclaimed — \`kraftwerk login\` claims this machine)`)}`);
+    }
+    else if (cloud.state === "error") {
+        console.log(`${chalk.yellow("⚠")} Cloud: ${cloud.url} unreachable — ${cloud.error ?? "no answer"} ${chalk.dim("(retrying; nothing else depends on it)")}`);
+    }
     // The relay (`kraftwerk remote on`): devices reach this machine from anywhere, end to end encrypted.
     const relay = await applyRelay(hub.port, await getPkgVersion(), (line) => console.log(chalk.dim(line)));
     // What needs you, pushed to the phones that asked (through the relay, sealed per device).

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,8 @@ 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 { machineCloud } from "../core/cloud.js";
+import { addWorkspaceId, 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 +13,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 +46,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 +104,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,15 +153,47 @@ export async function runDoctor(cwd) {
         else
             report("ok", label, "not inside a git repository");
     }
-    // Cloud manager: registration is best-effort at runtime, so doctor only says what would happen.
-    const cloud = cloudFor(project);
-    if (cloud) {
-        report("ok", `cloud: ${cloud.url}`, cloud.token
-            ? `registers under your kraftwerk account (KRAFTWERK_CLOUD_TOKEN), heartbeat every ${cloud.interval}s`
-            : `on by default — the UI shows a claim code under Settings → Cloud; opt out with cloud.enabled: false`);
+    // 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 {
-        report("info", "cloud: off", process.env.KRAFTWERK_CLOUD_URL?.trim().toLowerCase() === "off" ? "KRAFTWERK_CLOUD_URL=off" : "cloud.enabled: false in kraftwerk.yml");
+        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`);
+        }
+    }
+    // The kraftwerk cloud: the daemon registers the machine; doctor only says what would happen to this workspace.
+    const ymlCloud = project.config.cloud;
+    const cloud = await machineCloud(ymlCloud?.url ? [ymlCloud.url] : []);
+    if (ymlCloud?.enabled === false) {
+        report("info", "cloud: this workspace is left out", "cloud.enabled: false in kraftwerk.yml — the machine's cloud record does not list it");
+    }
+    else if (!cloud.enabled) {
+        report("info", "cloud: off", cloud.reason ?? "");
+    }
+    else {
+        report("ok", `cloud: ${cloud.url}`, "the daemon registers this machine and lists this workspace; `kraftwerk login` claims it, `kraftwerk cloud off` opts out");
+    }
+    if (ymlCloud?.url) {
+        report("warn", "kraftwerk.yml cloud.url is deprecated", cloud.source === "kraftwerk.yml"
+            ? `the cloud is the machine's now — \`kraftwerk cloud on --url ${ymlCloud.url}\`, then remove it from kraftwerk.yml`
+            : `ignored: the machine's cloud is ${cloud.url} (${cloud.source}) — remove it from kraftwerk.yml`);
     }
     const found = project.workflowsRoot ? await discoverWorkflows(cwd) : [];
     if (!project.workflowsRoot) {

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
@@ -28,8 +31,8 @@ skills: ${DATA_DIR}/skills         # workspace skills (shared instruction packag
 #   root: ${DATA_DIR}/repos       # clones land here (git-ignored); a bare \`repos:\` uses repos/ instead
 # vibeables:                      # small apps built live in a chat with a preview pane (uncomment to enable; one folder per app under ${DATA_DIR}/vibeables, versioned with the workspace)
 # projects:                       # goal-scoped folders — brief, systems of record, links to knowledge/vibeables/repos/workflows/agents — that chats work in (uncomment to enable; one folder per project under ${DATA_DIR}/projects)
-# cloud:                          # the kraftwerk cloud is ON BY DEFAULT: \`kraftwerk ui\` registers this workspace there and shows a claim code under Settings → Cloud
-#   enabled: false                # uncomment both lines to keep this workspace out of the cloud (or set KRAFTWERK_CLOUD_URL=off for the whole machine)
+# cloud:                          # the daemon registers this MACHINE with the kraftwerk cloud and lists this workspace (\`kraftwerk login\` claims the machine)
+#   enabled: false                # uncomment both lines to leave this workspace out (\`kraftwerk cloud off\` turns the cloud off for the whole machine)
 `;
 const WORKFLOW_TEMPLATE = `# yaml-language-server: $schema=${SCHEMA_URL}
 name: hello

package/dist/cli/kraftwerk.js

@@ -21,6 +21,8 @@ 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 { registerCloudCommands } from "./cloud.js";
 import { applyDotenv } from "../dotenv.js";
 import { resolveWorkspace } from "../config.js";
 import { registerRoutineCommands } from "./routines.js";
@@ -34,7 +36,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 +47,9 @@ 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 cloud [on|off|status]   this machine in the kraftwerk cloud (the daemon registers it)
+ *   kraftwerk login / logout          claim this machine into your cloud account (in the browser) / release it
+ *   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 +270,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 +304,8 @@ registerDevicesCommands(program);
 registerDaemonCommand(program);
 registerRemoteCommand(program);
 registerJournalCommands(program);
+registerWhoamiCommand(program);
+registerCloudCommands(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<{