@netnodeag/kraftwerk 0.64.0 → 0.66.0

package/dist/config.js

@@ -16,6 +16,7 @@ import { parse } from "yaml";
  *   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)
+ *   slug: team-blau            # this workspace's address (team-blau.localhost); default: the folder name
  *   port: 1981                 # port `kraftwerk ui` listens on
  *   workflows: src/workflows   # workflows root, relative to the file
  *   output: output             # run-artifact directory, relative to the file
@@ -36,12 +37,6 @@ import { parse } from "yaml";
   *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
  *   projects:                  # goal-scoped folders (brief, systems of record, links) that chats work in (absent = off, bare key = on)
  *     root: kraftwerk-data/projects   # one folder per project, part of the workspace. Default: kraftwerk-data/projects
- *   public: https://kw.example.com   # hostname the inspector is reached at through a tunnel or reverse proxy
- *   tunnel:                    # Cloudflare Tunnel run by `kraftwerk ui` (absent = off, bare key = on)
- *     name: kraftwerk          # locally-managed tunnel (cloudflared tunnel create); absent: TUNNEL_TOKEN env, dashboard-managed
- *     access:                  # verify the Cloudflare Access login on every request that arrives via `public`
- *       team: acme             # Zero Trust team name (https://<team>.cloudflareaccess.com)
- *       aud: 4714c135…         # Application Audience tag of the Access application
  *   cloud:                     # kraftwerk cloud manager — ON BY DEFAULT, `enabled: false` opts out
  *     url: https://srv.kraftwerk-cloud.netnode.cloud   # where the cloud answers (default). KRAFTWERK_CLOUD_URL env wins; "off" disables
  *     interval: 60             # seconds between heartbeats. Default: 60
@@ -114,34 +109,6 @@ export function cloudFor(project) {
         token: process.env.KRAFTWERK_CLOUD_TOKEN?.trim() || undefined,
     };
 }
-/** The public hostname (lowercase, no port) when `public` is set, undefined otherwise. */
-export function publicHostFor(project) {
-    return project.config.public ? parsePublic(project.config.public)?.hostname : undefined;
-}
-/** The public origin ("https://kw.example.com") when `public` is set, undefined otherwise. */
-export function publicUrlFor(project) {
-    return project.config.public ? parsePublic(project.config.public)?.origin : undefined;
-}
-/** The tunnel block when the feature is on, undefined otherwise. */
-export function tunnelFor(project) {
-    const t = project.config.tunnel;
-    if (!t || t.enabled === false)
-        return undefined;
-    return t;
-}
-/** "kw.example.com" or "https://kw.example.com[:port]" → its URL; undefined when it is neither. */
-export function parsePublic(value) {
-    const text = value.trim();
-    try {
-        const url = new URL(/^https?:\/\//i.test(text) ? text : `https://${text}`);
-        if (!url.hostname || url.pathname !== "/" || url.search || url.hash || url.username)
-            return undefined;
-        return url;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** A directory as a .gitignore entry: relative, forward slashes, no trailing slash; undefined outside the root. */
 export function ignoreEntryFor(projectRoot, dir) {
     const rel = path.relative(projectRoot, path.resolve(projectRoot, dir)).split(path.sep).join("/");
@@ -201,12 +168,13 @@ export async function resolveWorkspace(cwd) {
         const configPath = await findConfigFile(dir);
         if (configPath) {
             // Above a bare candidate an unreadable kraftwerk.yml is someone else's problem.
-            const config = bare ? await loadConfig(configPath).catch(() => null) : await loadConfig(configPath);
-            if (!config)
+            const loaded = bare ? await loadConfig(configPath).catch(() => null) : await loadConfig(configPath);
+            if (!loaded)
                 return bare;
+            const { config, legacyKeys } = loaded;
             const workflowsRoot = await findWorkflowsDir(dir, config.workflows);
             if (!bare || (workflowsRoot && path.resolve(workflowsRoot) === bare.workflowsRoot)) {
-                return { root: dir, config, configPath, workflowsRoot, outputDir: path.resolve(dir, config.output ?? "output") };
+                return { root: dir, config, configPath, workflowsRoot, outputDir: path.resolve(dir, config.output ?? "output"), ...(legacyKeys.length ? { legacyKeys } : {}) };
             }
             return bare;
         }
@@ -227,7 +195,32 @@ export async function resolveWorkspace(cwd) {
 }
 /** @deprecated Renamed: a kraftwerk.yml root is a workspace (projects are the folders inside). Use `resolveWorkspace`. */
 export const resolveProject = resolveWorkspace;
-const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "public", "tunnel", "cloud"];
+/** A workspace slug: a DNS label, so `<slug>.localhost` is a valid host name. */
+const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+/** A folder name as a slug: "Team Blau (2024)" → "team-blau-2024". */
+export function slugFromFolder(folder) {
+    const s = folder
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 63)
+        .replace(/-+$/, "");
+    return s || "workspace";
+}
+/** The workspace's slug: kraftwerk.yml `slug`, else its folder name made into one. */
+export function workspaceSlug(ws) {
+    return ws.config.slug ?? slugFromFolder(path.basename(ws.root));
+}
+const KNOWN_KEYS = ["name", "slug", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "cloud"];
+/**
+ * Keys an older kraftwerk understood and this one ignores, so the files
+ * that still carry them keep loading: `public:` and `tunnel:` (the
+ * Cloudflare Tunnel, removed in 0.65). Dropped before validation, so they
+ * never reach the rest of the code; doctor names them (`legacyKeys`).
+ */
+const LEGACY_KEYS = ["public", "tunnel"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -237,16 +230,22 @@ async function loadConfig(configPath) {
         throw new Error(`${path.basename(configPath)}: unreadable YAML: ${err.message}`);
     }
     if (raw === null || raw === undefined)
-        return {};
+        return { config: {}, legacyKeys: [] };
     if (typeof raw !== "object" || Array.isArray(raw)) {
         throw new Error(`${path.basename(configPath)}: expected a mapping (${KNOWN_KEYS.join(", ")})`);
     }
     const config = raw;
+    const legacyKeys = LEGACY_KEYS.filter((key) => key in config);
+    for (const key of legacyKeys)
+        delete config[key];
     const known = KNOWN_KEYS;
     for (const key of Object.keys(config)) {
         if (!known.includes(key)) {
             throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);
         }
+        if (key === "slug" && (typeof config[key] !== "string" || !SLUG_RE.test(config[key]))) {
+            throw new Error(`${path.basename(configPath)}: slug must be lowercase letters, digits and dashes, starting with a letter or digit (at most 63)`);
+        }
         if (key === "port") {
             if (typeof config[key] !== "number" || !Number.isInteger(config[key])) {
                 throw new Error(`${path.basename(configPath)}: port must be an integer`);
@@ -283,16 +282,6 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateRootBlock(configPath, "projects", config[key]);
         }
-        else if (key === "public") {
-            if (typeof config[key] !== "string" || !parsePublic(config[key])) {
-                throw new Error(`${path.basename(configPath)}: public must be a hostname or https URL like "https://kw.example.com"`);
-            }
-        }
-        else if (key === "tunnel") {
-            if (config[key] === null)
-                config[key] = {};
-            validateTunnel(configPath, config[key]);
-        }
         else if (key === "cloud") {
             if (config[key] === null)
                 config[key] = {};
@@ -302,49 +291,7 @@ async function loadConfig(configPath) {
             throw new Error(`${path.basename(configPath)}: ${key} must be a string`);
         }
     }
-    const tunnel = config.tunnel;
-    if (tunnel && tunnel.enabled !== false && !config.public) {
-        throw new Error(`${path.basename(configPath)}: tunnel needs public: the hostname the tunnel routes to`);
-    }
-    return config;
-}
-/** tunnel: { enabled?, name?, access?: { team, aud } } */
-function validateTunnel(configPath, value) {
-    const file = path.basename(configPath);
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new Error(`${file}: tunnel must be a mapping (enabled, name, access)`);
-    }
-    const t = value;
-    for (const key of Object.keys(t)) {
-        if (!["enabled", "name", "access"].includes(key)) {
-            throw new Error(`${file}: tunnel.${key} is unknown (allowed: enabled, name, access)`);
-        }
-    }
-    if (t.enabled !== undefined && typeof t.enabled !== "boolean") {
-        throw new Error(`${file}: tunnel.enabled must be true or false`);
-    }
-    // The name is handed to cloudflared as a positional argument.
-    if (t.name !== undefined && (typeof t.name !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(t.name))) {
-        throw new Error(`${file}: tunnel.name must be a plain tunnel name (letters, digits, ".", "_", "-")`);
-    }
-    if (t.access !== undefined) {
-        if (typeof t.access !== "object" || t.access === null || Array.isArray(t.access)) {
-            throw new Error(`${file}: tunnel.access must be a mapping (team, aud)`);
-        }
-        const a = t.access;
-        for (const key of Object.keys(a)) {
-            if (!["team", "aud"].includes(key)) {
-                throw new Error(`${file}: tunnel.access.${key} is unknown (allowed: team, aud)`);
-            }
-        }
-        // The team becomes a hostname (<team>.cloudflareaccess.com).
-        if (typeof a.team !== "string" || !/^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/i.test(a.team)) {
-            throw new Error(`${file}: tunnel.access.team must be the Zero Trust team name (the subdomain of cloudflareaccess.com)`);
-        }
-        if (typeof a.aud !== "string" || !/^[a-f0-9]{64}$/i.test(a.aud)) {
-            throw new Error(`${file}: tunnel.access.aud must be the 64-character Application Audience tag`);
-        }
-    }
+    return { config: config, legacyKeys };
 }
 /** cloud: { enabled?, url?, interval? } */
 function validateCloud(configPath, value) {

package/dist/core/chat/context.js

@@ -375,7 +375,7 @@ async function baseScopeContext(scope, agent) {
  * Every chat renders in the inspector UI, so agents should know two things:
  * replies are markdown, and run artifacts are addressable over the
  * inspector's own file endpoint (relative URLs keep working wherever the
- * inspector is reachable — localhost, LAN, tunnel).
+ * inspector is reachable — localhost, LAN, a reverse proxy).
  */
 const RENDERING_BLOCK = `## Chat rendering\n` +
     `Your replies render as markdown in the inspector chat: headings, lists, tables, code blocks, ` +

package/dist/core/chat/pi.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { workspaceEnv } from "../env.js";
 const clip = (raw) => {
     const oneLine = String(raw ?? "").replace(/\s+/g, " ").trim();
     return oneLine.length > 120 ? `${oneLine.slice(0, 120)}…` : oneLine;
@@ -23,7 +24,7 @@ export function startPiBackend(cwd, hooks, tuning = {}) {
                 const proc = spawn("pi", ["-p", "--mode", "json", "--session-id", sessionId, ...tuningArgs], {
                     cwd,
                     stdio: ["pipe", "pipe", "pipe"],
-                    env: process.env,
+                    env: workspaceEnv(),
                 });
                 child = proc;
                 proc.stdin.write(text);

package/dist/core/chat/sessions.d.ts

@@ -1,7 +1,7 @@
 import type { Attachment, ChatAgentId, ChatMeta, ChatScope, ElicitationAnswer, StoredChatEvent } from "./types.js";
 import { type Channel } from "../channels.js";
 export { agentFilesContext, agentJournalContext, agentVibeablesContext, vibeableContext } from "./context.js";
-export { disposeAllBackends } from "./state.js";
+export { disposeAllBackends, disposeWorkspaceBackends } from "./state.js";
 /**
  * The folder the agent is actually spawned in. A vibeable that was removed
  * leaves meta.cwd pointing nowhere; spawning there fails, so fall back to

package/dist/core/chat/sessions.js

@@ -12,7 +12,7 @@ import { expandSkillInvocation, scopeContext } from "./context.js";
 import { ensureBackend } from "./seats.js";
 import { MAIN, chatLabel, chatStates, dropBackend, dropSeat, emit, forgetFailedResume, isBusy, isUnattended, lastEventText, loadState, mainSeat, newSeat, ownerLabel, routineRef } from "./state.js";
 export { agentFilesContext, agentJournalContext, agentVibeablesContext, vibeableContext } from "./context.js";
-export { disposeAllBackends } from "./state.js";
+export { disposeAllBackends, disposeWorkspaceBackends } from "./state.js";
 /**
  * Chats: what the API does with them — create, post, steer, answer, fork,
  * rename, delete, subscribe. The pieces live beside it: the live state and

package/dist/core/chat/state.d.ts

@@ -77,5 +77,7 @@ export declare function forgetFailedResume(state: ChatState, seat: Seat): void;
 export declare function dropBackend(state: ChatState): void;
 /** Server shutdown: no agent subprocess may outlive the inspector. */
 export declare function disposeAllBackends(): void;
+/** The current workspace's agent processes end (the workspace closes); transcripts stay on disk. */
+export declare function disposeWorkspaceBackends(): void;
 export declare function loadState(id: string): Promise<ChatState | null>;
 export declare function emit(state: ChatState, ev: ChatEvent, from?: Author): StoredChatEvent;

package/dist/core/chat/state.js

@@ -134,6 +134,11 @@ export function disposeAllBackends() {
     for (const [ws, states] of chatStates.entries())
         ws.run(() => states.forEach((state) => dropBackend(state)));
 }
+/** The current workspace's agent processes end (the workspace closes); transcripts stay on disk. */
+export function disposeWorkspaceBackends() {
+    for (const state of chatStates().values())
+        dropBackend(state);
+}
 export async function loadState(id) {
     const existing = chatStates().get(id);
     if (existing)

package/dist/core/daemon.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The machine's kraftwerk daemon: one process (`kraftwerk daemon`) serving
+ * every open workspace, each by its slug (`<slug>.localhost:<port>`,
+ * `/w/<slug>/`). It writes ~/.kraftwerk/daemon.json while it runs, so the CLI
+ * (`kraftwerk ui`) and other kraftwerks (the switcher's start/stop) hand
+ * workspaces to it instead of starting a server of their own. The file
+ * outlives the daemon on purpose: it lists what was open, and the next start
+ * (a reboot, a self-update) opens it again. Whether a daemon runs is told by
+ * asking it (findDaemon), never by the file alone.
+ */
+export declare const DAEMON_PORT = 1980;
+export declare function writeDaemonFile(port: number, open: string[]): Promise<void>;
+/** What the last daemon served, to open again; [] without a file. */
+export declare function lastOpenRoots(): Promise<string[]>;
+/** The running daemon (its file, and a hub that answers on its port), or null. */
+export declare function findDaemon(): Promise<{
+    pid: number;
+    port: number;
+} | null>;
+/** Ask the daemon to open or close a workspace (this machine's request: local trust). */
+export declare function daemonCall<T>(port: number, verb: "open" | "close", root: string): Promise<{
+    ok: boolean;
+    status: number;
+    data: T & {
+        error?: string;
+    };
+}>;

package/dist/core/daemon.js

@@ -0,0 +1,61 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * The machine's kraftwerk daemon: one process (`kraftwerk daemon`) serving
+ * every open workspace, each by its slug (`<slug>.localhost:<port>`,
+ * `/w/<slug>/`). It writes ~/.kraftwerk/daemon.json while it runs, so the CLI
+ * (`kraftwerk ui`) and other kraftwerks (the switcher's start/stop) hand
+ * workspaces to it instead of starting a server of their own. The file
+ * outlives the daemon on purpose: it lists what was open, and the next start
+ * (a reboot, a self-update) opens it again. Whether a daemon runs is told by
+ * asking it (findDaemon), never by the file alone.
+ */
+export const DAEMON_PORT = 1980;
+const daemonFile = () => path.join(os.homedir(), ".kraftwerk", "daemon.json");
+const startedAt = new Date().toISOString();
+export async function writeDaemonFile(port, open) {
+    await fs.mkdir(path.dirname(daemonFile()), { recursive: true });
+    const tmp = `${daemonFile()}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify({ pid: process.pid, port, startedAt, open }));
+    await fs.rename(tmp, daemonFile());
+}
+/** What the last daemon served, to open again; [] without a file. */
+export async function lastOpenRoots() {
+    try {
+        const rec = JSON.parse(await fs.readFile(daemonFile(), "utf8"));
+        return Array.isArray(rec.open) ? rec.open.filter((r) => typeof r === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/** The running daemon (its file, and a hub that answers on its port), or null. */
+export async function findDaemon() {
+    let rec;
+    try {
+        rec = JSON.parse(await fs.readFile(daemonFile(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    try {
+        // Every kraftwerk server answers /api/hub; only the daemon says it is one (a standalone `kraftwerk ui` may sit on that port now).
+        const r = await fetch(`http://127.0.0.1:${rec.port}/api/hub`, { signal: AbortSignal.timeout(800) });
+        const body = r.ok ? (await r.json()) : null;
+        return body?.daemon === true ? { pid: rec.pid, port: rec.port } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Ask the daemon to open or close a workspace (this machine's request: local trust). */
+export async function daemonCall(port, verb, root) {
+    const r = await fetch(`http://127.0.0.1:${port}/api/hub/${verb}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ root }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    return { ok: r.ok, status: r.status, data: (await r.json().catch(() => ({}))) };
+}

package/dist/core/devices.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Paired devices: other machines — a phone's browser, a native app, a
+ * second laptop — that may use this machine's kraftwerk without being on
+ * it. One pairing covers every workspace here (the store is per machine,
+ * ~/.kraftwerk/devices.json), like the daemon will.
+ *
+ * Pairing: someone on this machine creates a short-lived one-time code
+ * (`kraftwerk devices pair`, or settings in the web UI); the device trades
+ * it for its token (POST /api/pair). Tokens are 32 random bytes; the store
+ * keeps only their SHA-256, so the file leaks nothing that grants access.
+ * Revoking a device deletes its hash: the token stops working at once.
+ */
+export interface Device {
+    id: string;
+    name: string;
+    createdAt: string;
+    lastSeenAt?: string;
+}
+/** How long a pairing code works. */
+export declare const PAIR_CODE_TTL_MS: number;
+/** A new one-time pairing code, valid for PAIR_CODE_TTL_MS. Shown once; the store keeps its hash. */
+export declare function createPairCode(): Promise<{
+    code: string;
+    expiresAt: string;
+}>;
+/** Trade a pairing code for a device token. The code works once; a wrong or expired one is refused without saying which. */
+export declare function redeemPairCode(code: string, name: string): Promise<{
+    token: string;
+    device: Device;
+}>;
+/** The device a token belongs to, or null. Notes when it was last seen (at most once a minute). */
+export declare function deviceForToken(token: string): Promise<Device | null>;
+export declare function listDevices(): Promise<Device[]>;
+/** Unpair a device: its token stops working at once. */
+export declare function revokeDevice(id: string): Promise<boolean>;

package/dist/core/devices.js

@@ -0,0 +1,156 @@
+import { createHash, randomBytes, randomInt } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** How long a pairing code works. */
+export const PAIR_CODE_TTL_MS = 10 * 60_000;
+/** No 0/O, 1/I/L: a code is read off one screen and typed into another. */
+const CODE_ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+const CODE_LENGTH = 8;
+const TOKEN_PREFIX = "kwd_";
+/** lastSeenAt is written at most this often per device. */
+const SEEN_EVERY_MS = 60_000;
+const storeFile = () => path.join(os.homedir(), ".kraftwerk", "devices.json");
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+/** Codes compare case- and separator-insensitively: "abcd-efgh" is ABCDEFGH. */
+const normalizeCode = (code) => code.toUpperCase().replace(/[^A-Z0-9]/g, "");
+/** The store as last read, with the file's mtime: every request checks a token, so the file is re-read only when it changed. */
+let cached = null;
+async function read() {
+    const file = storeFile();
+    const st = await fs.stat(file).catch(() => null);
+    if (!st)
+        return { devices: [], codes: [] };
+    if (cached && cached.mtimeMs === st.mtimeMs)
+        return cached.store;
+    try {
+        const raw = JSON.parse(await fs.readFile(file, "utf8"));
+        const store = { devices: Array.isArray(raw.devices) ? raw.devices : [], codes: Array.isArray(raw.codes) ? raw.codes : [] };
+        cached = { mtimeMs: st.mtimeMs, store };
+        return store;
+    }
+    catch {
+        return { devices: [], codes: [] };
+    }
+}
+async function write(store) {
+    const file = storeFile();
+    const now = Date.now();
+    store.codes = store.codes.filter((c) => Date.parse(c.expiresAt) > now);
+    // Write-then-rename, owner-only: hashes grant nothing, but names and times are nobody else's business.
+    // A temp name per write: two writes in flight must not rename each other's file.
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(store, null, 2), { mode: 0o600 });
+    await fs.rename(tmp, file);
+    cached = null;
+}
+const LOCK_STALE_MS = 10_000;
+let chain = Promise.resolve();
+/**
+ * Change the store: read it fresh, apply `change`, write it — one change at
+ * a time across every process on the machine (the servers of each workspace
+ * and the CLI share the file). In-process changes queue; across processes an
+ * O_EXCL lock file does, taken over when its holder died (older than 10 s).
+ */
+function update(change) {
+    const run = chain.then(async () => {
+        const file = storeFile();
+        const lock = `${file}.lock`;
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        for (let attempt = 0;; attempt++) {
+            try {
+                await (await fs.open(lock, "wx")).close();
+                break;
+            }
+            catch (err) {
+                if (err.code !== "EEXIST")
+                    throw err;
+                const st = await fs.stat(lock).catch(() => null);
+                if (st && Date.now() - st.mtimeMs > LOCK_STALE_MS)
+                    await fs.rm(lock, { force: true });
+                else if (attempt > 200)
+                    throw new Error("the device store is locked — try again");
+                else
+                    await new Promise((r) => setTimeout(r, 25));
+            }
+        }
+        try {
+            cached = null;
+            const store = await read();
+            const result = change(store);
+            await write(store);
+            return result;
+        }
+        finally {
+            await fs.rm(lock, { force: true });
+        }
+    });
+    chain = run.catch(() => { });
+    return run;
+}
+const view = ({ tokenHash: _h, ...d }) => d;
+/** A new one-time pairing code, valid for PAIR_CODE_TTL_MS. Shown once; the store keeps its hash. */
+export async function createPairCode() {
+    let code = "";
+    for (let i = 0; i < CODE_LENGTH; i++)
+        code += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+    const expiresAt = new Date(Date.now() + PAIR_CODE_TTL_MS).toISOString();
+    await update((store) => store.codes.push({ codeHash: sha256(code), expiresAt }));
+    return { code: `${code.slice(0, 4)}-${code.slice(4)}`, expiresAt };
+}
+/** Trade a pairing code for a device token. The code works once; a wrong or expired one is refused without saying which. */
+export async function redeemPairCode(code, name) {
+    const hash = sha256(normalizeCode(code));
+    const token = TOKEN_PREFIX + randomBytes(32).toString("base64url");
+    const device = {
+        id: randomBytes(6).toString("hex"),
+        name: name.trim().slice(0, 60) || "device",
+        createdAt: new Date().toISOString(),
+        tokenHash: sha256(token),
+    };
+    const redeemed = await update((store) => {
+        const now = Date.now();
+        const i = store.codes.findIndex((c) => c.codeHash === hash && Date.parse(c.expiresAt) > now);
+        if (i < 0)
+            return false;
+        store.codes.splice(i, 1);
+        store.devices.push(device);
+        return true;
+    });
+    if (!redeemed)
+        throw new Error("invalid or expired pairing code");
+    return { token, device: view(device) };
+}
+/** The device a token belongs to, or null. Notes when it was last seen (at most once a minute). */
+export async function deviceForToken(token) {
+    if (!token.startsWith(TOKEN_PREFIX))
+        return null;
+    const store = await read();
+    const hash = sha256(token);
+    const device = store.devices.find((d) => d.tokenHash === hash);
+    if (!device)
+        return null;
+    const now = Date.now();
+    if (!device.lastSeenAt || now - Date.parse(device.lastSeenAt) > SEEN_EVERY_MS) {
+        const seen = new Date(now).toISOString();
+        // Applied to the store as it is now, not to the copy read above: a pairing in between must survive.
+        await update((fresh) => {
+            const d = fresh.devices.find((x) => x.id === device.id);
+            if (d)
+                d.lastSeenAt = seen;
+        }).catch(() => { });
+        return view({ ...device, lastSeenAt: seen });
+    }
+    return view(device);
+}
+export async function listDevices() {
+    return (await read()).devices.map(view);
+}
+/** Unpair a device: its token stops working at once. */
+export async function revokeDevice(id) {
+    return update((store) => {
+        const before = store.devices.length;
+        store.devices = store.devices.filter((d) => d.id !== id);
+        return store.devices.length < before;
+    });
+}

package/dist/core/env.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The environment a workspace's processes run with: this process's, plus
+ * the workspace's own `.env` (dotenv.ts for the precedence — a value set in
+ * the shell wins, unless an earlier kraftwerk process injected it from a
+ * `.env`). Everything a workspace spawns — agents, workflow runs, app dev
+ * servers, git — takes its environment from here, never from process.env
+ * directly: one process may serve several workspaces, and one team's
+ * `.env` must not reach another's agents.
+ *
+ * With one workspace per process the CLI has already applied that
+ * workspace's `.env` to process.env, so the result is the same as before.
+ */
+/** Read `<root>/.env` (parsed, not applied); {} without one. Read when a workspace is served — a changed file applies on restart, as before. */
+export declare function readWorkspaceDotenv(root: string): Record<string, string>;
+/** The current workspace's environment (outside any workspace: process.env). */
+export declare function workspaceEnv(): NodeJS.ProcessEnv;

package/dist/core/env.js

@@ -0,0 +1,45 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { DOTENV_FILE, DOTENV_MARKER, parseDotenv } from "../dotenv.js";
+import { currentWorkspace } from "./workspace.js";
+/**
+ * The environment a workspace's processes run with: this process's, plus
+ * the workspace's own `.env` (dotenv.ts for the precedence — a value set in
+ * the shell wins, unless an earlier kraftwerk process injected it from a
+ * `.env`). Everything a workspace spawns — agents, workflow runs, app dev
+ * servers, git — takes its environment from here, never from process.env
+ * directly: one process may serve several workspaces, and one team's
+ * `.env` must not reach another's agents.
+ *
+ * With one workspace per process the CLI has already applied that
+ * workspace's `.env` to process.env, so the result is the same as before.
+ */
+/** Read `<root>/.env` (parsed, not applied); {} without one. Read when a workspace is served — a changed file applies on restart, as before. */
+export function readWorkspaceDotenv(root) {
+    try {
+        return parseDotenv(readFileSync(path.join(root, DOTENV_FILE), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** The current workspace's environment (outside any workspace: process.env). */
+export function workspaceEnv() {
+    let dotenv;
+    try {
+        dotenv = currentWorkspace().env;
+    }
+    catch {
+        return { ...process.env };
+    }
+    const env = { ...process.env };
+    const injected = new Set((process.env[DOTENV_MARKER] ?? "").split(",").filter(Boolean));
+    // What another workspace's .env put into this process is not this workspace's.
+    for (const key of injected)
+        if (!(key in dotenv))
+            delete env[key];
+    for (const [key, value] of Object.entries(dotenv))
+        if (!process.env[key] || injected.has(key))
+            env[key] = value;
+    return env;
+}

package/dist/core/git.d.ts

@@ -146,3 +146,5 @@ export declare function gitPush(): Promise<{
  * out) before the next one starts, or a short interval piles up processes.
  */
 export declare function startGitSync(): void;
+/** Stop the current workspace's background sync (the workspace closes). A tick in flight finishes, then stops. */
+export declare function stopGitSync(): void;