@netnodeag/kraftwerk 0.66.0 → 0.68.0

package/README.md

@@ -65,11 +65,12 @@ foreground; Ctrl-C stops it. That is all most people need.
 
 **Several workspaces: `kraftwerk daemon`.** With more than one workspace,
 run one kraftwerk for all of them instead of a server and a port each.
-Start the daemon once and leave it running (a terminal tab, or a login
-item):
+Start the daemon once and leave it running, or let your Mac start it at
+login:
 
 ```bash
 kraftwerk daemon                       # the machine's kraftwerk, on http://localhost:1980
+kraftwerk daemon install               # or: start it at login from now on (macOS; `uninstall` undoes it)
 
 cd ~/work/team-blau && kraftwerk ui    # opens this workspace in the daemon:
                                        #   http://team-blau.localhost:1980
@@ -87,7 +88,10 @@ reaches the same workspace. `http://localhost:1980` lists what is open.
 A workspace with a `port:` of its own is served there too, so old links
 keep working. The daemon remembers what was open and opens it again when it
 starts (after a reboot or an update). Each workspace still runs on its own
-inside it, with its own `.env`, routines, git sync and chats.
+inside it, with its own `.env`, routines, git sync and chats. The
+workspace menu in the header switches between them, and starts a stopped
+one right in the daemon. The Kraftwerk desktop app starts the daemon for
+you when it opens.
 `kraftwerk ui` hands the workspace to the daemon whenever one is running;
 `kraftwerk ui --standalone` starts a server of its own anyway.
 
@@ -95,7 +99,9 @@ inside it, with its own `.env`, routines, git sync and chats.
 or `kraftwerk daemon --lan`) and kraftwerk also listens on your network.
 Anyone who opens it there gets a pairing screen, nothing else, until you
 pair that device: `kraftwerk devices pair` on this machine prints a
-one-time code (see [Inspector on your phone](#inspector-on-your-phone-paired-devices)).
+one-time code. A paired device reaches the daemon's workspaces at
+`/w/<slug>/` on the address it used, and the workspace menu links them
+that way (see [Inspector on your phone](#inspector-on-your-phone-paired-devices)).
 
 **What to do first in the inspector.** Talk to **Ralv**, the workspace's
 general chat, in plain words: it knows what is in the workspace and helps
@@ -225,6 +231,7 @@ kraftwerk runs                          # past runs from output/*/trace.jsonl; r
 kraftwerk knowledge                     # Knowledge: OKF bundles (list/get/put/verify/search/...)
 kraftwerk ui                            # start this workspace: http://localhost:1981 (or open it in the daemon); --port, --lan, --standalone
 kraftwerk daemon                        # one kraftwerk for every open workspace: http://<slug>.localhost:1980; --port, --lan
+kraftwerk daemon install                # start the daemon at login (macOS LaunchAgent); `daemon uninstall` removes it
 kraftwerk workspaces                    # every workspace on this machine; workspaces start|stop|forget <ref>
 kraftwerk devices                       # paired devices (a phone, another computer); devices pair|revoke
 kraftwerk projects                      # goal-scoped project folders; projects create|show|link|log|remove
@@ -286,8 +293,14 @@ workspace's inspector gets its own `.env`, not the other one's. The file is
 never synced (it is on the workspace git's deny list and in the .gitignore
 `kraftwerk init` writes); `kraftwerk doctor` lists the names it loaded.
 
-`switcher:` links other kraftwerk workspaces from the inspector header. The
-workspace name becomes a dropdown listing them:
+The workspace name in the inspector header is the **workspace menu**. It
+lists every workspace this machine knows. Running ones open with a click,
+and a stopped one starts from its row (in the daemon, when one runs). Each
+link uses the address you opened this page with: `<slug>.localhost` on this
+machine, `/w/<slug>/` from a paired device on the network, the path form
+when you are in it.
+`switcher:` adds workspaces kraftwerk cannot discover, such as one on
+another machine:
 
 ```yaml
 switcher:
@@ -371,8 +384,12 @@ follows to author the workflow folder and validate and smoke it with this CLI.
 
 ### Inspector on your phone (paired devices)
 
-`kraftwerk ui --lan` also listens on your network and prints the addresses
-(for example `http://192.168.1.20:1981`). Anyone who opens one gets a
+`kraftwerk ui --lan` (or `kraftwerk daemon --lan`) also listens on your
+network and prints the addresses (for example `http://192.168.1.20:1981`).
+On the daemon, a device opens a workspace at `/w/<slug>/` on that address
+(`http://192.168.1.20:1980/w/team-blau/`), because `<slug>.localhost` only
+works on this machine. The daemon's own address lists them, and the
+workspace menu links the others the same way. Anyone who opens one gets a
 pairing screen, nothing else. To let a device in, make a one-time code on
 the machine kraftwerk runs on, with `kraftwerk devices pair` or settings →
 devices → pair a device, and enter it on the device. The code works once,

package/dist/cli/daemon-login.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `kraftwerk daemon install` / `uninstall`: the daemon as a macOS login item
+ * (a LaunchAgent), so it runs after a reboot without a terminal or the
+ * desktop app. launchd starts the same `kraftwerk daemon` a terminal would —
+ * this node, this install — with the PATH of the shell that installed it,
+ * because launchd's own PATH would not find the agents (claude, codex, pi).
+ * The daemon's supervisor restarts it after a self-update; launchd only
+ * starts it at login.
+ */
+export declare const LAUNCH_LABEL = "ch.netnode.kraftwerk.daemon";
+/** The LaunchAgent: `program` at login, `env` set, output appended to `log`. */
+export declare function renderPlist(program: string[], env: Record<string, string>, log: string): string;
+export declare function installDaemon(opts: {
+    port?: string;
+}): Promise<void>;
+export declare function uninstallDaemon(): Promise<void>;
+/** For doctor: whether the login item is installed. */
+export declare const daemonLoginItem: () => string | null;

package/dist/cli/daemon-login.js

@@ -0,0 +1,104 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { findDaemon } from "../core/daemon.js";
+import { selfCommand } from "../core/self-command.js";
+import { tildify } from "../core/instances.js";
+/**
+ * `kraftwerk daemon install` / `uninstall`: the daemon as a macOS login item
+ * (a LaunchAgent), so it runs after a reboot without a terminal or the
+ * desktop app. launchd starts the same `kraftwerk daemon` a terminal would —
+ * this node, this install — with the PATH of the shell that installed it,
+ * because launchd's own PATH would not find the agents (claude, codex, pi).
+ * The daemon's supervisor restarts it after a self-update; launchd only
+ * starts it at login.
+ */
+export const LAUNCH_LABEL = "ch.netnode.kraftwerk.daemon";
+const plistPath = () => path.join(os.homedir(), "Library", "LaunchAgents", `${LAUNCH_LABEL}.plist`);
+const logPath = () => path.join(os.homedir(), ".kraftwerk", "logs", "daemon.log");
+/** A stand-in launchctl (tests); the real one otherwise. */
+const launchctl = () => process.env.KRAFTWERK_LAUNCHCTL || "launchctl";
+const domain = () => `gui/${os.userInfo().uid}`;
+const xml = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]);
+/** The LaunchAgent: `program` at login, `env` set, output appended to `log`. */
+export function renderPlist(program, env, log) {
+    const strings = (xs) => xs.map((x) => `\t\t<string>${xml(x)}</string>`).join("\n");
+    const vars = Object.entries(env)
+        .map(([k, v]) => `\t\t<key>${xml(k)}</key>\n\t\t<string>${xml(v)}</string>`)
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>Label</key>
+\t<string>${LAUNCH_LABEL}</string>
+\t<key>ProgramArguments</key>
+\t<array>
+${strings(program)}
+\t</array>
+\t<key>EnvironmentVariables</key>
+\t<dict>
+${vars}
+\t</dict>
+\t<key>WorkingDirectory</key>
+\t<string>${xml(os.homedir())}</string>
+\t<key>RunAtLoad</key>
+\t<true/>
+\t<key>StandardOutPath</key>
+\t<string>${xml(log)}</string>
+\t<key>StandardErrorPath</key>
+\t<string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+}
+function requireMac() {
+    if (process.platform !== "darwin") {
+        console.error(chalk.red("✖ a login item is macOS only for now — run `kraftwerk daemon` from your system's startup instead"));
+        process.exit(2);
+    }
+}
+export async function installDaemon(opts) {
+    requireMac();
+    const { cmd, args } = selfCommand(["daemon", ...(opts.port ? ["--port", opts.port] : [])]);
+    const env = { PATH: process.env.PATH ?? "/usr/bin:/bin" };
+    if (process.env.KRAFTWERK_DAEMON_PORT && !opts.port)
+        env.KRAFTWERK_DAEMON_PORT = process.env.KRAFTWERK_DAEMON_PORT;
+    const file = plistPath();
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.mkdir(path.dirname(logPath()), { recursive: true });
+    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) {
+        // 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`));
+        return;
+    }
+    const r = spawnSync(launchctl(), ["bootstrap", domain(), file], { encoding: "utf8" });
+    if (r.status !== 0) {
+        console.error(chalk.red(`✖ launchctl bootstrap failed: ${(r.stderr || r.stdout || "").trim() || `exit ${r.status}`}`));
+        console.error(chalk.dim(`  the file is in place (${tildify(file)}) and loads at the next login`));
+        process.exit(1);
+    }
+    console.log(`${chalk.green("✔")} login item installed and started: ${chalk.dim(tildify(file))}`);
+    console.log(chalk.dim(`  log: ${tildify(logPath())} · \`kraftwerk daemon uninstall\` removes it`));
+}
+export async function uninstallDaemon() {
+    requireMac();
+    const file = plistPath();
+    if (!existsSync(file)) {
+        console.log(chalk.dim("No login item installed."));
+        return;
+    }
+    // Unloading stops the daemon launchd started; one started from a terminal keeps running.
+    spawnSync(launchctl(), ["bootout", `${domain()}/${LAUNCH_LABEL}`], { stdio: "ignore" });
+    await fs.rm(file, { force: true });
+    console.log(`${chalk.green("✔")} login item removed ${chalk.dim(`(${tildify(file)})`)}`);
+}
+/** For doctor: whether the login item is installed. */
+export const daemonLoginItem = () => (existsSync(plistPath()) ? plistPath() : null);

package/dist/cli/daemon.js

@@ -4,6 +4,7 @@ import { tildify } from "../core/instances.js";
 import { networkUrls } from "../server/bind.js";
 import { startHub } from "../server/server.js";
 import { ensureBuilt, supervise } from "./ui.js";
+import { installDaemon, uninstallDaemon } from "./daemon-login.js";
 /**
  * `kraftwerk daemon` — the machine's kraftwerk: one process serving every
  * open workspace, each at `<slug>.localhost:<port>` (and its own port, when
@@ -49,12 +50,26 @@ export async function runDaemon(opts) {
         console.log(`${chalk.green("✔")} On your network: ${lan.map((u) => chalk.cyan(u)).join(", ")} ${chalk.dim("(add /w/<slug>/; devices pair first)")}`);
 }
 export function registerDaemonCommand(program) {
-    program
+    const daemon = program
         .command("daemon")
-        .description("Run the machine's kraftwerk: one process serving every open workspace at <slug>.localhost")
+        .description("Run the machine's kraftwerk: one process serving every open workspace at <slug>.localhost; install it as a login item")
         .option("--port <port>", `Port (default: KRAFTWERK_DAEMON_PORT, else ${DAEMON_PORT})`)
         .option("--lan", "Listen on the network too, for paired devices")
         .action(async (opts) => {
         await runDaemon(opts);
     });
+    daemon
+        .command("install")
+        .description("Start the daemon at login (macOS LaunchAgent), and now unless one runs")
+        .option("--port <port>", `Port (default: KRAFTWERK_DAEMON_PORT, else ${DAEMON_PORT})`)
+        .action(async (opts) => {
+        // `--port` after `install` is taken by `daemon` itself, which has the same option.
+        await installDaemon({ port: opts.port ?? daemon.opts().port });
+    });
+    daemon
+        .command("uninstall")
+        .description("Remove the login item (stops a daemon launchd started)")
+        .action(async () => {
+        await uninstallDaemon();
+    });
 }

package/dist/cli/doctor.js

@@ -9,6 +9,8 @@ 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 { daemonLoginItem } from "./daemon-login.js";
 const ICONS = {
     ok: chalk.green("✔"),
     warn: chalk.yellow("⚠"),
@@ -210,6 +212,16 @@ export async function runDoctor(cwd) {
     if (process.env.KRAFTWERK_UI_TRUST_NETWORK === "1")
         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 loginItem = daemonLoginItem();
+    report("info", daemon ? `kraftwerk daemon running on :${daemon.port}` : "no kraftwerk daemon running", loginItem
+        ? "starts at login (`kraftwerk daemon uninstall` removes that)"
+        : process.platform === "darwin"
+            ? "`kraftwerk daemon install` starts it at login"
+            : daemon
+                ? undefined
+                : "`kraftwerk daemon` serves every workspace in one process");
     // Legacy: what older versions left behind, and what still runs or is installed at one.
     for (const f of await legacyFindings(project, pkg.version))
         report(f.level, f.label, f.detail);

package/dist/core/instances.d.ts

@@ -53,6 +53,8 @@ export interface WorkspaceEntry {
     color?: string;
     /** True when the name comes from kraftwerk.yml, false when it is just the folder name. */
     named?: boolean;
+    /** Its slug (kraftwerk.yml `slug`, else the folder name): how a daemon addresses it. */
+    slug?: string;
     live: boolean;
     root?: string;
     /** Root with ~ for the home dir — what the UI prints. */

package/dist/core/instances.js

@@ -335,7 +335,7 @@ export async function forgetWorkspace(root) {
  * so without this check a stale record would wear its parent's identity.
  */
 async function describeRoot(root) {
-    const fallback = { name: path.basename(root), named: false, port: 1981, exists: false };
+    const fallback = { name: path.basename(root), named: false, slug: slugFromFolder(path.basename(root)), port: 1981, exists: false };
     if (!(await isDir(root)))
         return fallback;
     try {
@@ -345,6 +345,7 @@ async function describeRoot(root) {
         return {
             name: project.config.name ?? path.basename(project.root),
             named: !!project.config.name,
+            slug: workspaceSlug(project),
             icon: project.config.icon || undefined,
             color: project.config.color || undefined,
             port: project.config.port ?? 1981,
@@ -396,11 +397,12 @@ export async function discoverWorkspaces() {
                 icon: running.icon,
                 color: running.color ?? d?.color,
                 named: running.named ?? d?.named,
+                slug: running.slug ?? recordSlug(p),
                 live: true,
                 exists: true,
             };
         }
-        return { ...base, name: d.name, url: `http://localhost:${d.port}`, icon: d.icon, color: d.color, named: d.named, live: false, exists: d.exists };
+        return { ...base, name: d.name, url: `http://localhost:${d.port}`, icon: d.icon, color: d.color, named: d.named, slug: d.slug, live: false, exists: d.exists };
     }))).concat(await Promise.all(live
         .filter((i) => !consumed.has(i))
         .map(async (i) => ({
@@ -409,6 +411,7 @@ export async function discoverWorkspaces() {
         icon: i.icon,
         color: i.color,
         named: i.named,
+        slug: i.slug,
         live: true,
         root: i.root,
         rootLabel: i.root ? tildify(i.root) : undefined,
@@ -461,6 +464,7 @@ export async function listWorkspacesDetailed() {
             icon: d.icon,
             color: d.color,
             named: d.named,
+            slug: d.slug,
             url: mine.url,
             live: true,
             root: me,

package/dist/core/search.d.ts

@@ -14,6 +14,8 @@ export interface WorkspaceAgents {
     icon?: string;
     /** Where the workspace's UI lives — hits link to `${url}/#/agents/<slug>`. */
     url: string;
+    /** Its slug: how a daemon addresses it. */
+    slug?: string;
     /** Project root (what /api/projects/start takes for a stopped workspace). */
     root?: string;
     /** The instance answering this request: hits navigate in place. */

package/dist/core/search.js

@@ -26,6 +26,7 @@ export async function searchAgents() {
         name: w.name,
         icon: w.icon,
         url: w.url,
+        slug: w.slug,
         root: w.root,
         current: false,
         live: w.live,

package/dist/server/api/index.d.ts

@@ -481,7 +481,11 @@ export declare const routes: (Route<"agents.addJournal", {
     runs: import("../../core/runs.js").RunListItem[];
 }, "/api/runs", undefined> | Route<"runs.stop", {
     stopped: boolean;
-}, "/api/runs/:id/stop", undefined> | Route<"search.agents", import("../../core/search.js").AgentSearch, "/api/search/agents", undefined> | Route<"server.restart", {
+}, "/api/runs/:id/stop", undefined> | Route<"search.agents", {
+    workspaces: (import("../../core/search.js").WorkspaceAgents & {
+        here?: true;
+    })[];
+}, "/api/search/agents", undefined> | Route<"server.restart", {
     ok: boolean;
 }, "/api/restart", undefined> | Route<"settings.get", import("../../core/settings.js").SettingsView, "/api/settings", undefined> | Route<"settings.save", import("../../core/settings.js").SettingsView, "/api/settings", z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
@@ -577,7 +581,12 @@ export declare const routes: (Route<"agents.addJournal", {
     ok: boolean;
 }, "/api/workspaces/forget", z.ZodObject<{
     root: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>> | Route<"workspaces.list", import("../../core/instances.js").WorkspaceDetail[], "/api/workspaces", undefined> | Route<"workspaces.start", import("./router.js").Reply<import("../../core/instances.js").StartResult>, "/api/workspaces/start", z.ZodObject<{
+}, z.core.$strip>> | Route<"workspaces.list", (import("../../core/instances.js").WorkspaceDetail & {
+    here?: true;
+})[], "/api/workspaces", undefined> | Route<"workspaces.start", import("./router.js").Reply<import("../../core/instances.js").StartResult & {
+    slug?: string;
+    here?: true;
+}>, "/api/workspaces/start", z.ZodObject<{
     root: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>> | Route<"workspaces.stop", import("./router.js").Reply<{
     ok: boolean;

package/dist/server/api/workspace.d.ts

@@ -1,4 +1,10 @@
 import * as z from "zod";
+import { type StartResult } from "../../core/instances.js";
+/** A start's answer; `here` (with its slug) when the hub answering serves it now. */
+type StartReply = StartResult & {
+    slug?: string;
+    here?: true;
+};
 /** The workspace itself: identity and features, settings, the other workspaces, updates. */
 export declare const workspaceRoutes: (import("./router.js").Route<"meta.get", {
     workspaceName: string;
@@ -26,7 +32,11 @@ export declare const workspaceRoutes: (import("./router.js").Route<"meta.get", {
     publicUrl: string;
     cloud: import("../cloud.js").CloudStatus;
     switcher: import("../../config.js").SwitcherEntry[];
-}, "/api/meta", undefined> | import("./router.js").Route<"search.agents", import("../../core/search.js").AgentSearch, "/api/search/agents", undefined> | import("./router.js").Route<"server.restart", {
+}, "/api/meta", undefined> | import("./router.js").Route<"search.agents", {
+    workspaces: (import("../../core/search.js").WorkspaceAgents & {
+        here?: true;
+    })[];
+}, "/api/search/agents", undefined> | import("./router.js").Route<"server.restart", {
     ok: boolean;
 }, "/api/restart", undefined> | import("./router.js").Route<"settings.get", import("../../core/settings.js").SettingsView, "/api/settings", undefined> | import("./router.js").Route<"settings.save", import("../../core/settings.js").SettingsView, "/api/settings", z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
@@ -91,7 +101,9 @@ export declare const workspaceRoutes: (import("./router.js").Route<"meta.get", {
     ok: boolean;
 }, "/api/workspaces/forget", z.ZodObject<{
     root: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>> | import("./router.js").Route<"workspaces.list", import("../../core/instances.js").WorkspaceDetail[], "/api/workspaces", undefined> | import("./router.js").Route<"workspaces.start", import("./router.js").Reply<import("../../core/instances.js").StartResult>, "/api/workspaces/start", z.ZodObject<{
+}, z.core.$strip>> | import("./router.js").Route<"workspaces.list", (import("../../core/instances.js").WorkspaceDetail & {
+    here?: true;
+})[], "/api/workspaces", undefined> | import("./router.js").Route<"workspaces.start", import("./router.js").Reply<StartReply>, "/api/workspaces/start", z.ZodObject<{
     root: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>> | import("./router.js").Route<"workspaces.stop", import("./router.js").Reply<{
     ok: boolean;
@@ -100,3 +112,4 @@ export declare const workspaceRoutes: (import("./router.js").Route<"meta.get", {
     root: z.ZodOptional<z.ZodString>;
     url: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>)[];
+export {};

package/dist/server/api/workspace.js

@@ -1,10 +1,11 @@
 import path from "node:path";
 import * as z from "zod";
-import { resolveWorkspace, slugFromFolder, workspaceSlug } from "../../config.js";
+import { absolutePath, resolveWorkspace, slugFromFolder, workspaceSlug } from "../../config.js";
 import { disposeAllBackends } from "../../core/chat/sessions.js";
 import { cloudStatus } from "../cloud.js";
 import { workspaceRoot } from "../../core/context.js";
 import { discoverWorkspaces, forgetWorkspace, listWorkspacesDetailed, startWorkspace, stopWorkspace, tildify } from "../../core/instances.js";
+import { currentHub } from "../hub-context.js";
 import { searchAgents } from "../../core/search.js";
 import { getSettings, saveSettings } from "../../core/settings.js";
 import { canSelfUpdate, startUpdate, updateStatus } from "../../core/update.js";
@@ -32,6 +33,26 @@ const SettingsFields = z.looseObject({
     vibeables: RootBlock.optional(),
     projects: RootBlock.optional(),
 });
+/**
+ * Mark the workspaces the hub answering this request serves — or, a daemon,
+ * would serve once started (it opens a stopped one next to the others, at
+ * <slug>.localhost:<its port>) — as `here`. The UI links those in the form
+ * the page itself was reached by: a paired phone on the network cannot
+ * resolve <slug>.localhost, so it gets /w/<slug>/ on the address it used.
+ */
+function placeInHub(entries) {
+    const hub = currentHub();
+    const served = new Set(hub.list().map((o) => o.root));
+    return entries.map((e) => {
+        if (!e.root || !e.slug)
+            return e;
+        if (served.has(e.root))
+            return { ...e, here: true };
+        if (hub.daemon && !e.live && e.exists !== false)
+            return { ...e, here: true, url: `http://${e.slug}.localhost:${hub.port}` };
+        return e;
+    });
+}
 /** The workspace itself: identity and features, settings, the other workspaces, updates. */
 export const workspaceRoutes = [
     // ?probe=1 marks a discovery probe from another instance: answer identity
@@ -42,7 +63,7 @@ export const workspaceRoutes = [
         const name = ws?.config.name ?? (ws ? path.basename(ws.root) : "");
         const root = ws?.root ?? workspaceRoot();
         const manual = ws?.config.switcher ?? [];
-        const discovered = c.query.get("probe") === "1" ? [] : await discoverWorkspaces();
+        const discovered = c.query.get("probe") === "1" ? [] : placeInHub(await discoverWorkspaces());
         // Manual switcher entries keep their configured name/icon; discovered
         // workspaces that duplicate one (same url, running) only contribute
         // the live flag. Stopped workspaces never collide — they carry a root,
@@ -89,12 +110,23 @@ export const workspaceRoutes = [
     }),
     route({ name: "settings.get", method: "GET", path: "/api/settings", summary: "kraftwerk.yml, parsed, with resolved paths" }, async () => getSettings()),
     route({ name: "settings.save", method: "PUT", path: "/api/settings", summary: "write the UI-editable subset of kraftwerk.yml", errors: 400, body: SettingsFields }, async (c) => saveSettings((await c.body()))),
-    route({ name: "workspaces.list", method: "GET", path: "/api/workspaces", summary: "every known workspace incl. this one, with state and counts" }, async () => listWorkspacesDetailed()),
+    route({ name: "workspaces.list", method: "GET", path: "/api/workspaces", summary: "every known workspace incl. this one, with state and counts" }, async () => placeInHub(await listWorkspacesDetailed())),
     // Launches `kraftwerk ui` for a known workspace as a detached process (the switcher's Start button).
     route({ name: "workspaces.start", method: "POST", path: "/api/workspaces/start", summary: "start a known workspace {root}", errors: 400, body: z.object({ root: z.string().optional() }) }, async (c) => {
         const { root } = await c.body();
         if (!root)
             fail(400, "root required");
+        // A daemon opens it itself, next to the workspace asking.
+        const hub = currentHub();
+        if (hub.daemon) {
+            try {
+                const o = await hub.open(absolutePath(root));
+                return reply(200, { ok: true, url: o.url, slug: o.slug, here: true, live: true, pid: process.pid });
+            }
+            catch (err) {
+                return reply(409, { ok: false, error: err.message });
+            }
+        }
         const result = await startWorkspace(root);
         return reply(result.ok ? 200 : 409, result);
     }),
@@ -102,6 +134,13 @@ export const workspaceRoutes = [
         const target = await c.body();
         if (!target.root && !target.url)
             fail(400, "root or url required");
+        // One the hub answering serves (not the one asking): closed right here.
+        const hub = currentHub();
+        const open = target.root ? hub.list().find((o) => o.root === absolutePath(target.root)) : undefined;
+        if (hub.daemon && open && open.root !== workspaceRoot()) {
+            await hub.close(open.root);
+            return reply(200, { ok: true });
+        }
         const result = await stopWorkspace(target);
         return reply(result.ok ? 200 : 409, result);
     }),
@@ -111,7 +150,7 @@ export const workspaceRoutes = [
             fail(400, "root required");
         return { ok: await forgetWorkspace(root) };
     }),
-    route({ name: "search.agents", method: "GET", path: "/api/search/agents", summary: "active agents and channels of every reachable workspace (⌘K)" }, async () => searchAgents()),
+    route({ name: "search.agents", method: "GET", path: "/api/search/agents", summary: "active agents and channels of every reachable workspace (⌘K)" }, async () => searchAgents().then((r) => ({ workspaces: placeInHub(r.workspaces) }))),
     route({ name: "update.check", method: "GET", path: "/api/update-check", summary: "the latest version on the npm registry" }, async () => {
         const name = await getPkgName();
         const current = await getDiskVersion();

package/dist/server/server.d.ts

@@ -25,6 +25,8 @@ export interface OpenWorkspace {
     /** Its own port too (kraftwerk.yml `port`), when the hub listens there for it — old links keep working. */
     aliasPort?: number;
     ws: Workspace;
+    /** Its instance file being written (see openNow): closing waits for it, so no file lands after the close. */
+    registered?: Promise<void>;
 }
 /**
  * One HTTP server serving workspaces by slug (see target.ts): a daemon

package/dist/server/server.js

@@ -1,5 +1,6 @@
 import { promises as fs } from "node:fs";
 import http from "node:http";
+import net from "node:net";
 import path from "node:path";
 import { setDefaultWorkspace, Workspace } from "../core/workspace.js";
 import { cloudGoodbye, cloudGoodbyeAll, startCloudSync, stopCloudSync } from "./cloud.js";
@@ -167,19 +168,52 @@ function installExitHandlers() {
         unregisterInstance();
     });
 }
-const listen = (server, port) => new Promise((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(port, INSPECTOR_HOST, () => {
-        server.off("error", reject);
-        const addr = server.address();
-        resolve(typeof addr === "object" && addr ? addr.port : port);
+/**
+ * Listen on `port`. On the default bind (127.0.0.1) the same port on ::1
+ * feeds the same server: macOS resolves localhost and <slug>.localhost to
+ * ::1 first, and a client that does not fall back to IPv4 (a native app's
+ * HTTP library) would find nothing there. Best effort — without IPv6, or
+ * with ::1:port taken, it stays IPv4 only, as before.
+ */
+async function listen(server, port) {
+    const bound = await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, INSPECTOR_HOST, () => {
+            server.off("error", reject);
+            const addr = server.address();
+            resolve(typeof addr === "object" && addr ? addr.port : port);
+        });
+    });
+    if (INSPECTOR_HOST !== "127.0.0.1")
+        return bound;
+    const twin = net.createServer((socket) => server.emit("connection", socket));
+    const ok = await new Promise((resolve) => {
+        twin.once("error", () => resolve(false));
+        twin.listen(bound, "::1", () => resolve(true));
     });
-});
-/** A small page at a daemon's own address: the open workspaces, each a link. */
-function hubPage(res, open) {
+    if (!ok)
+        return bound;
+    twin.on("error", () => { });
+    // Closing the server stops the twin from taking connections at once (its "close" event waits for open ones).
+    const close = server.close.bind(server);
+    server.close = ((cb) => {
+        twin.close();
+        return close(cb);
+    });
+    return bound;
+}
+/**
+ * A small page at a daemon's own address: the open workspaces, each a link —
+ * <slug>.localhost on this machine, the path form on the address a paired
+ * device used (it cannot resolve <slug>.localhost).
+ */
+function hubPage(req, res, open) {
     const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+    // Behind a proxy on this machine the browser's name is the forwarded one.
+    const host = hostnameOf(forwardedHost(req) ?? req.headers.host ?? "");
+    const local = LOOPBACK_NAMES.has(host) || host.endsWith(".localhost");
     const rows = open.length
-        ? open.map((o) => `<li><a href="${esc(o.url)}/">${esc(o.name)}</a> <code>${esc(o.slug)}</code></li>`).join("")
+        ? open.map((o) => `<li><a href="${esc(local ? `${o.url}/` : `/w/${o.slug}/`)}">${esc(o.name)}</a> <code>${esc(o.slug)}</code></li>`).join("")
         : "<li>No workspace is open. Run <code>kraftwerk ui</code> in a workspace folder.</li>";
     res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
     res.end(`<!doctype html><meta charset="utf-8"><title>kraftwerk</title><style>body{font:15px/1.6 system-ui,sans-serif;max-width:640px;margin:48px auto;padding:0 16px;color:#1b1b1f}code{color:#46464f}</style><h1>kraftwerk</h1><ul>${rows}</ul>`);
@@ -226,7 +260,7 @@ export async function startHub(opts) {
             }
             // A daemon's own address lists its workspaces; anywhere else, the web UI's shell (public: an unpaired browser needs it to pair).
             if (!open && (url.pathname === "/" || url.pathname === "/index.html"))
-                return hubPage(res, [...bySlug.values()]);
+                return hubPage(req, res, [...bySlug.values()]);
             await serveStatic(res, opts.staticDir, url.pathname);
         }
         catch (err) {
@@ -354,7 +388,7 @@ export async function startHub(opts) {
             startRoutineScheduler();
             startGitSync();
             // Best-effort, in the background: none of them may hold up (or, failing, break) the open.
-            void registerInstance(entry.aliasPort ?? port, abs, opts.daemon ? { hub: true, slug, url: entry.url } : {}).catch(() => { });
+            entry.registered = registerInstance(entry.aliasPort ?? port, abs, opts.daemon ? { hub: true, slug, url: entry.url } : {}).catch(() => { });
             void registerWorkspace(abs).catch(() => { });
             void startCloudSync(entry.url, version).catch(() => { });
         }));
@@ -385,6 +419,7 @@ export async function startHub(opts) {
             await cloudGoodbye();
             stopCloudSync();
         }));
+        await entry.registered;
         unregisterInstance(abs);
         markWorkspaceStopped(abs);
         entry.ws.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netnodeag/kraftwerk",
-  "version": "0.66.0",
+  "version": "0.68.0",
   "description": "Open-source agentic workspace for teams — where people and AI agents get work done together: agents (Claude Code, Codex, Pi), skills, shared knowledge, repeatable workflows, and deterministic verification",
   "keywords": [
     "agents",