@netnodeag/kraftwerk 0.48.0 → 0.49.0

package/dist/cli/workspaces.js

@@ -0,0 +1,149 @@
+import path from "node:path";
+import chalk from "chalk";
+import { absolutePath } from "../config.js";
+import Table from "cli-table3";
+import { discoverWorkspaces, forgetWorkspace, startWorkspace, stopWorkspace, tildify, } from "../inspector/instances.js";
+/**
+ * `kraftwerk workspaces` — every workspace that ever ran the inspector on this
+ * machine (~/.kraftwerk/workspaces), joined with what is running right now.
+ * The answer to "where did I start that UI, and how do I get it back":
+ *
+ *   kraftwerk workspaces                 list: name, root, running/stopped
+ *   kraftwerk workspaces start <ref>     relaunch `kraftwerk ui` in that root, detached
+ *   kraftwerk workspaces stop <ref>      SIGTERM a running UI (also ones started in a terminal)
+ *   kraftwerk workspaces forget <ref>    drop the record (the folder stays)
+ *
+ * <ref> is a workspace name, the root's folder name, the root path, or a
+ * port / localhost:port for running instances that recorded no root.
+ */
+export const fmtAgo = (iso) => {
+    if (!iso)
+        return "—";
+    const s = Math.max(0, (Date.now() - Date.parse(iso)) / 1000);
+    if (s < 90)
+        return "just now";
+    if (s < 5400)
+        return `${Math.round(s / 60)} min ago`;
+    if (s < 129600)
+        return `${Math.round(s / 3600)} h ago`;
+    return `${Math.round(s / 86400)} d ago`;
+};
+/**
+ * Running → its url. Not running: "stopped" after a clean shutdown, "died"
+ * when the last start has no matching stop (killed, crashed, terminal
+ * closed) — the case this command exists for.
+ */
+const status = (e) => {
+    if (e.live)
+        return chalk.green(`● ${e.url.replace(/^https?:\/\//, "")}`);
+    if (e.exists === false)
+        return chalk.red("path missing");
+    const clean = !!e.lastStopped && !!e.lastStarted && e.lastStopped >= e.lastStarted;
+    return clean ? chalk.dim("stopped") : chalk.yellow("died");
+};
+/** Match a ref against known workspaces; `needRoot` excludes rootless live instances (start/forget need a root). */
+async function resolveRef(ref, needRoot = true) {
+    const all = (await discoverWorkspaces()).filter((e) => e.root || !needRoot);
+    const abs = absolutePath(ref);
+    const port = /^\d+$/.test(ref) ? `http://localhost:${ref}` : `http://${ref.replace(/^https?:\/\//, "")}`;
+    const hits = all.filter((e) => e.root === abs ||
+        e.root === ref ||
+        e.name === ref ||
+        (e.root && path.basename(e.root) === ref) ||
+        e.url === port);
+    if (hits.length === 1)
+        return hits[0];
+    if (hits.length === 0) {
+        console.error(chalk.red(`No known workspace "${ref}". See \`kraftwerk workspaces\`.`));
+        process.exit(2);
+    }
+    console.error(chalk.red(`"${ref}" is ambiguous — use the root path or port:`));
+    for (const h of hits)
+        console.error(`  ${h.root ?? h.url}`);
+    process.exit(2);
+}
+export function registerWorkspaceCommands(program) {
+    const workspaces = program
+        .command("workspaces")
+        .description("Known kraftwerk workspaces on this machine: list, start a stopped UI, stop a running one, forget");
+    workspaces
+        .command("list", { isDefault: true })
+        .description("List known workspaces with their root and whether the UI is running")
+        .option("--json", "Machine-readable output")
+        .action(async (opts) => {
+        const entries = await discoverWorkspaces();
+        if (opts.json) {
+            console.log(JSON.stringify(entries, null, 2));
+            return;
+        }
+        if (entries.length === 0) {
+            console.log(chalk.dim("No workspaces known yet — `kraftwerk ui` registers the current one."));
+            return;
+        }
+        const table = new Table({
+            head: ["workspace", "root", "status", "last started"].map((h) => chalk.bold(h)),
+            wordWrap: true,
+            colWidths: [22, 48, 24, 14],
+        });
+        for (const e of entries) {
+            table.push([
+                `${e.icon ? e.icon + " " : ""}${chalk.cyan(e.name)}`,
+                e.rootLabel ?? chalk.dim("(no root recorded)"),
+                status(e),
+                fmtAgo(e.lastStarted),
+            ]);
+        }
+        console.log(table.toString());
+    });
+    workspaces
+        .command("start")
+        .description("Relaunch the UI of a stopped workspace (detached; logs in ~/.kraftwerk/logs)")
+        .argument("<ref>", "Workspace name, folder name, or root path")
+        .action(async (ref) => {
+        const entry = await resolveRef(ref);
+        if (entry.live) {
+            console.log(`${chalk.green("✔")} ${entry.name} already running: ${chalk.cyan(entry.url)}`);
+            return;
+        }
+        const r = await startWorkspace(entry.root);
+        if (!r.ok) {
+            console.error(chalk.red(`Could not start ${entry.name}: ${r.error}`));
+            if (r.log)
+                console.error(chalk.dim(`log: ${tildify(r.log)}`));
+            process.exit(1);
+        }
+        console.log(`${chalk.green("✔")} ${entry.name} ${r.live ? "running" : "starting"}: ${chalk.cyan(r.url)}` +
+            chalk.dim(` (pid ${r.pid}${r.log ? `, log ${tildify(r.log)}` : ""})`));
+    });
+    workspaces
+        .command("stop")
+        .description("Stop a running UI (SIGTERM to its server; works for terminal-started ones too)")
+        .argument("<ref>", "Workspace name, folder name, root path, or port")
+        .action(async (ref) => {
+        const entry = await resolveRef(ref, false);
+        if (!entry.live) {
+            console.log(chalk.dim(`${entry.name} is not running.`));
+            return;
+        }
+        const r = await stopWorkspace({ root: entry.root, url: entry.url });
+        if (!r.ok) {
+            console.error(chalk.red(`Could not stop ${entry.name}: ${r.error}`));
+            process.exit(1);
+        }
+        console.log(`${chalk.green("✔")} ${entry.name} stopped ${chalk.dim(`(${entry.url.replace(/^https?:\/\//, "")})`)}`);
+    });
+    workspaces
+        .command("forget")
+        .description("Remove a workspace from the registry (its folder is untouched)")
+        .argument("<ref>", "Workspace name, folder name, or root path")
+        .action(async (ref) => {
+        const entry = await resolveRef(ref);
+        if (await forgetWorkspace(entry.root)) {
+            console.log(`${chalk.green("✔")} forgot ${entry.name} (${entry.rootLabel})`);
+        }
+        else {
+            console.error(chalk.red(`No record for ${entry.root}`));
+            process.exit(1);
+        }
+    });
+}

package/dist/config.d.ts

@@ -29,7 +29,9 @@
  *   repos:                     # git repositories the agents work on (absent = off, bare key = on)
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
- *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
+  *     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
@@ -102,6 +104,23 @@ export interface VibeablesConfig {
 export declare const VIBEABLES_DEFAULT_ROOT = "kraftwerk-data/vibeables";
 /** Absolute vibeables root when the feature is on, undefined otherwise. */
 export declare function vibeablesRootFor(project: Project): string | undefined;
+/**
+ * Projects: a goal with everything the agents need to reach it in one
+ * folder — a brief, the systems of record where the truth lives, and links
+ * to the workspace's knowledge, vibeables, repositories, workflows and
+ * agents. Each is one folder under the root; part of the workspace and
+ * synced by the workspace git like agents and knowledge.
+ */
+export interface ProjectsConfig {
+    /** false keeps the block but turns the feature off. Default: true. */
+    enabled?: boolean;
+    /** Where the projects live, relative to the project root. Default: kraftwerk-data/projects */
+    root?: string;
+}
+/** Where projects live when `projects.root` is not set. */
+export declare const PROJECTS_DEFAULT_ROOT = "kraftwerk-data/projects";
+/** Absolute projects root when the feature is on, undefined otherwise. */
+export declare function projectsRootFor(project: Project): string | undefined;
 /**
  * Cloudflare Access in front of the public hostname. Access puts a login
  * page on the hostname at Cloudflare's edge and hands the origin a signed
@@ -183,6 +202,8 @@ export interface ProjectConfig {
     repos?: ReposConfig;
     /** Vibeables: apps built live in a chat. Absent = off. */
     vibeables?: VibeablesConfig;
+    /** Projects: goal-scoped folders the chats work in. Absent = off. */
+    projects?: ProjectsConfig;
     /**
      * Hostname the inspector is reached at through a tunnel or reverse proxy,
      * e.g. "https://kw.example.com". The loopback bind then answers requests

package/dist/config.js

@@ -33,7 +33,9 @@ import { parse } from "yaml";
  *   repos:                     # git repositories the agents work on (absent = off, bare key = on)
  *     root: kraftwerk-data/repos   # where clones land, relative to the file. Default: repos
  *   vibeables:                 # small apps built live in a chat, rendered in the inspector (absent = off, bare key = on)
- *     root: apps               # one folder per app, part of the workspace. Default: kraftwerk-data/vibeables
+  *     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
@@ -84,6 +86,15 @@ export function vibeablesRootFor(project) {
         return undefined;
     return path.resolve(project.root, v.root ?? VIBEABLES_DEFAULT_ROOT);
 }
+/** Where projects live when `projects.root` is not set. */
+export const PROJECTS_DEFAULT_ROOT = "kraftwerk-data/projects";
+/** Absolute projects root when the feature is on, undefined otherwise. */
+export function projectsRootFor(project) {
+    const p = project.config.projects;
+    if (!p || p.enabled === false)
+        return undefined;
+    return path.resolve(project.root, p.root ?? PROJECTS_DEFAULT_ROOT);
+}
 /** 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;
@@ -187,7 +198,7 @@ export async function resolveProject(cwd) {
     const root = gitFallback ?? start;
     return { root, config: {}, outputDir: path.join(root, "output") };
 }
-const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "public", "tunnel"];
+const KNOWN_KEYS = ["name", "icon", "color", "port", "workflows", "output", "knowledge", "agents", "skills", "switcher", "git", "repos", "vibeables", "projects", "public", "tunnel"];
 async function loadConfig(configPath) {
     let raw;
     try {
@@ -238,6 +249,11 @@ async function loadConfig(configPath) {
                 config[key] = {};
             validateRootBlock(configPath, "vibeables", config[key]);
         }
+        else if (key === "projects") {
+            if (config[key] === null)
+                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"`);
@@ -353,7 +369,7 @@ function validateGit(configPath, value) {
     }
 }
 /**
- * `repos` and `vibeables` share one shape: { enabled?, root? }. The root
+ * `repos`, `vibeables` and `projects` share one shape: { enabled?, root? }. The root
  * must never be the project itself or anything outside it — it is what
  * remove/delete operate under, and what the workspace git may stage.
  */

package/dist/inspector/agents.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { parse, stringify } from "yaml";
 import { resolveProject } from "../config.js";
 import { getProjectRoot } from "./context.js";
-import { syncProjectAgents } from "./instances.js";
+import { syncWorkspaceAgents } from "./instances.js";
 /**
  * Agents: persistent agents, defined on the filesystem. Each one
  * is one folder under the project's agents/ root:
@@ -88,7 +88,7 @@ export async function listAgents() {
     // palettes. Awaited so a read that follows a save sees the record updated;
     // it only writes when the roster changed.
     await resolveProject(getProjectRoot())
-        .then((p) => syncProjectAgents(p.root, list.filter((a) => !a.archived).map(toSummary)))
+        .then((p) => syncWorkspaceAgents(p.root, list.filter((a) => !a.archived).map(toSummary)))
         .catch(() => { });
     return list;
 }

package/dist/inspector/channels.d.ts

@@ -3,7 +3,7 @@
  * channel where the coworkers are agents. The definition is git-tracked
  * with the workspace so the whole team sees the same channels:
  *
- *   channels/<slug>/channel.yml   # name, purpose, members (agent slugs), responder, maxHops
+ *   channels/<slug>/channel.yml   # name, purpose, members (agent slugs), responder, maxHops, project
  *
  * The transcript itself is a chat (scope { kind: "channel", slug }) under
  * <output>/chats/, run-state like every other chat. sessions.ts gives each
@@ -22,6 +22,13 @@ export interface Channel {
     responder?: string;
     /** Agent-to-agent handovers allowed per human message. */
     maxHops: number;
+    /**
+     * The project this channel works in (a slug under the projects root):
+     * every member gets the project's brief, state, records and links as
+     * context, and the channel lists under the project. Set when a project
+     * chat gets its first coworker; see convertChatToChannel.
+     */
+    project?: string;
 }
 /** What the ⌘K palette needs of a channel (and what the project registry records). */
 export type ChannelSummary = Pick<Channel, "slug" | "name" | "purpose">;
@@ -39,6 +46,8 @@ export interface SaveChannelInput {
     /** Agent slug, or "" / null to clear. */
     responder?: string | null;
     maxHops?: number;
+    /** Project slug, or "" / null to detach. */
+    project?: string | null;
 }
 /** Create (no slug: derived from the name) or update a channel definition. */
 export declare function saveChannel(input: SaveChannelInput): Promise<Channel>;

package/dist/inspector/channels.js

@@ -4,7 +4,7 @@ import { parse, stringify } from "yaml";
 import { getProjectRoot } from "./context.js";
 import { resolveProject } from "../config.js";
 import { listAgents, safeAgentSlug, slugFromName } from "./agents.js";
-import { syncProjectChannels } from "./instances.js";
+import { syncWorkspaceChannels } from "./instances.js";
 export const toChannelSummary = (c) => ({
     slug: c.slug,
     name: c.name,
@@ -21,6 +21,7 @@ export function safeChannelSlug(slug) {
         throw new Error(`invalid channel slug "${slug}"`);
     return slug;
 }
+const PROJECT_SLUG_RE = /^[a-z0-9][a-z0-9-]{0,48}$/;
 function normalize(slug, raw) {
     const members = Array.isArray(raw.members) ? [...new Set(raw.members.map(String))] : [];
     const responder = typeof raw.responder === "string" && members.includes(raw.responder) ? raw.responder : undefined;
@@ -32,6 +33,7 @@ function normalize(slug, raw) {
         members,
         ...(responder ? { responder } : {}),
         maxHops: hops,
+        ...(typeof raw.project === "string" && PROJECT_SLUG_RE.test(raw.project) ? { project: raw.project } : {}),
     };
 }
 export async function listChannels() {
@@ -49,7 +51,7 @@ export async function listChannels() {
     const list = channels.filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
     // Like the agent roster: the registry copy feeds other instances' palettes.
     await resolveProject(getProjectRoot())
-        .then((p) => syncProjectChannels(p.root, list.map(toChannelSummary)))
+        .then((p) => syncWorkspaceChannels(p.root, list.map(toChannelSummary)))
         .catch(() => { });
     return list;
 }
@@ -100,6 +102,12 @@ export async function saveChannel(input) {
                 throw new Error("maxHops must be a whole number");
             })()
         : existing?.maxHops ?? DEFAULT_MAX_HOPS;
+    let project = existing?.project;
+    if (input.project !== undefined) {
+        if (input.project && !PROJECT_SLUG_RE.test(input.project))
+            throw new Error(`invalid project name "${input.project}"`);
+        project = input.project || undefined;
+    }
     const channel = {
         slug,
         name,
@@ -113,6 +121,7 @@ export async function saveChannel(input) {
         members,
         ...(responder ? { responder } : {}),
         maxHops,
+        ...(project ? { project } : {}),
     };
     const dir = path.join(await channelsRoot(), slug);
     await fs.mkdir(dir, { recursive: true });

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

@@ -44,9 +44,14 @@ export declare function postMessage(id: string, text: string, opts?: {
 /** The chat that holds a channel's transcript; created on first use. */
 export declare function ensureChannelChat(channel: Channel): Promise<ChatMeta>;
 /**
- * "Add a coworker" to an agent session: the chat becomes the channel's
- * transcript. The agent keeps its process and memory — it has seen every
- * message so far — and learns the channel rules with its next prompt.
+ * "Add a coworker": the chat becomes the channel's transcript.
+ *
+ * From an agent session, the agent keeps its process and memory — it has
+ * seen every message so far — and learns the channel rules with its next
+ * prompt. From a project chat, the project assistant has no agent identity
+ * to keep, so its process goes; the members join with the whole transcript
+ * (a fresh seat starts at seq 0) and the project's context, and the chat
+ * stays listed under the project through meta.project.
  */
 export declare function convertChatToChannel(chatId: string, channel: Channel): Promise<{
     error?: string;

package/dist/inspector/chat/sessions.js

@@ -8,6 +8,7 @@ import { listWorkflows } from "../workflows.js";
 import { getAgent, listAgents } from "../agents.js";
 import { listRepos } from "../repos.js";
 import { resolveVibeable, vibeableStatus, VIBEABLE_CONFIG_FILE } from "../vibeables.js";
+import { getProject, projectContext } from "../projects.js";
 import { deleteAgentSession, listAgentSessions, startAcpBackend } from "./acp.js";
 import { startPiBackend } from "./pi.js";
 import { UNATTENDED_PERMISSION_TIMEOUT_MS, declineOption, unattendedTimeoutLabel } from "./permissions.js";
@@ -401,6 +402,11 @@ async function baseScopeContext(scope, agent) {
                     `not retry it another way. End with a clear, self-contained summary of what you did and found.`
                 : ""));
     }
+    if (scope.kind === "project") {
+        // Everything the project gathered — brief, state, records, links — plus
+        // how to keep it current; see projects.ts for the block.
+        return projectContext(scope.slug, `kraftwerk-chat/${agent}`);
+    }
     if (scope.kind === "knowledge") {
         const { root, bundles } = await knowledgeIndex().catch(() => ({ root: "", bundles: [] }));
         const bundleLines = bundles
@@ -502,14 +508,16 @@ async function scopeContext(meta, seat) {
     const agent = seat.harness;
     // The repositories block reads every clone from git, so it runs alongside
     // the rest instead of adding its spawns to the first prompt's latency.
-    const [base, repos, vibe, skills, channel] = await Promise.all([
+    const [base, repos, vibe, skills, channel, project] = await Promise.all([
         baseScopeContext(scope, agent),
         scope.kind === "agent" || scope.kind === "kraftwerk" ? reposContext() : Promise.resolve(""),
         meta.vibeable ? vibeableContext(meta.vibeable, meta.cwd) : Promise.resolve(""),
         availableSkills(scope),
         meta.scope.kind === "channel" ? channelContext(meta.scope.slug, seat.key) : Promise.resolve(""),
+        // A channel that works in a project: every member reads the project too, as a member, not as its assistant.
+        meta.scope.kind === "channel" && meta.project ? projectContext(meta.project, `${seat.key}/${agent}`, { member: true }) : Promise.resolve(""),
     ]);
-    return [base, channel, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
+    return [base, channel, project, repos, vibe, RENDERING_BLOCK, skillsBlock(skills)].filter(Boolean).join("\n\n");
 }
 /** The channel block a member agent gets once per process: who is here, how turns work, how to hand over. */
 async function channelContext(slug, self) {
@@ -554,6 +562,14 @@ async function backendTuning(meta, seat) {
         if (agent === "claude" && def?.skills)
             tuning.skills = def.skills;
     }
+    // Project chats carry the project's model/effort the same way.
+    if (scope.kind === "project") {
+        const def = await getProject(scope.slug).catch(() => null);
+        if (def?.model)
+            tuning.model = def.model;
+        if (def?.effort)
+            tuning.effort = def.effort;
+    }
     // Run chats live in the run folder — grant claude the project root so
     // project-level skills and files stay reachable.
     // A vibeable session works inside the app folder for the same reason.
@@ -944,34 +960,57 @@ export async function ensureChannelChat(channel) {
     const existing = metas.find((m) => m.scope.kind === "channel" && m.scope.slug === channel.slug);
     if (existing)
         return states.get(existing.id)?.meta ?? existing;
-    return createChat({ agent: "claude", scope: { kind: "channel", slug: channel.slug }, title: channel.name });
+    const meta = await createChat({ agent: "claude", scope: { kind: "channel", slug: channel.slug }, title: channel.name });
+    if (channel.project) {
+        meta.project = channel.project;
+        await writeMeta(meta);
+    }
+    return meta;
 }
 /**
- * "Add a coworker" to an agent session: the chat becomes the channel's
- * transcript. The agent keeps its process and memory — it has seen every
- * message so far — and learns the channel rules with its next prompt.
+ * "Add a coworker": the chat becomes the channel's transcript.
+ *
+ * From an agent session, the agent keeps its process and memory — it has
+ * seen every message so far — and learns the channel rules with its next
+ * prompt. From a project chat, the project assistant has no agent identity
+ * to keep, so its process goes; the members join with the whole transcript
+ * (a fresh seat starts at seq 0) and the project's context, and the chat
+ * stays listed under the project through meta.project.
  */
 export async function convertChatToChannel(chatId, channel) {
     const state = await loadState(chatId);
     if (!state)
         return { error: "chat not found" };
     const scope = state.meta.scope;
-    if (scope.kind !== "agent")
-        return { error: "only an agent session can become a channel" };
-    if (!channel.members.includes(scope.slug))
+    if (scope.kind !== "agent" && scope.kind !== "project")
+        return { error: "only an agent session or a project chat can become a channel" };
+    if (scope.kind === "agent" && !channel.members.includes(scope.slug))
         return { error: `the channel must include @${scope.slug}` };
     if (isBusy(state))
         return { error: "agent is still working — wait for the turn to finish" };
-    const main = state.seats.get(MAIN);
-    state.seats.delete(MAIN);
-    const seat = main ?? newSeat(scope.slug, state.meta.agent);
-    seat.key = scope.slug;
-    seat.needsContext = true;
-    seat.seenSeq = state.events[state.events.length - 1]?.seq ?? 0;
-    state.seats.set(scope.slug, seat);
-    if (state.meta.sessions?.[MAIN]) {
-        const { [MAIN]: session, ...rest } = state.meta.sessions;
-        state.meta.sessions = { ...rest, [scope.slug]: session };
+    if (scope.kind === "project") {
+        if (channel.project !== scope.slug)
+            return { error: `the channel must belong to project "${scope.slug}"` };
+        dropBackend(state);
+        state.seats.delete(MAIN);
+        if (state.meta.sessions?.[MAIN]) {
+            const { [MAIN]: _gone, ...rest } = state.meta.sessions;
+            state.meta.sessions = rest;
+        }
+        state.meta.project = scope.slug;
+    }
+    else {
+        const main = state.seats.get(MAIN);
+        state.seats.delete(MAIN);
+        const seat = main ?? newSeat(scope.slug, state.meta.agent);
+        seat.key = scope.slug;
+        seat.needsContext = true;
+        seat.seenSeq = state.events[state.events.length - 1]?.seq ?? 0;
+        state.seats.set(scope.slug, seat);
+        if (state.meta.sessions?.[MAIN]) {
+            const { [MAIN]: session, ...rest } = state.meta.sessions;
+            state.meta.sessions = { ...rest, [scope.slug]: session };
+        }
     }
     state.meta.scope = { kind: "channel", slug: channel.slug };
     state.meta.title = channel.name;

package/dist/inspector/chat/types.d.ts

@@ -21,6 +21,11 @@ export type ChatScope = {
     slug: string;
     routine?: string;
 }
+/** A project: the chat carries its brief, state, systems of record and links; see projects.ts. */
+ | {
+    kind: "project";
+    slug: string;
+}
 /** A channel: several agents (and humans) share one transcript; see channels.ts. */
  | {
     kind: "channel";
@@ -42,6 +47,12 @@ export interface ChatMeta {
     scope: ChatScope;
     /** Slug of the vibeable open in this chat's preview pane (cwd is its folder while set). */
     vibeable?: string;
+    /**
+     * The project this chat belongs to when its scope is not the project
+     * itself: a channel that started as a project chat. Lists the chat under
+     * the project and hands every seat the project's context.
+     */
+    project?: string;
     /**
      * The agent's own session id per seat ("main", or the agent slug in a
      * channel): after a restart or the idle reaper, the next backend resumes

package/dist/inspector/git.js

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
-import { reposRootFor, resolveProject, vibeablesRootFor, isSafeGitName } from "../config.js";
+import { projectsRootFor, reposRootFor, resolveProject, vibeablesRootFor, isSafeGitName } from "../config.js";
 import { ENV_FILE } from "../runner/docker.js";
 import { getOutputDir, getProjectRoot } from "./context.js";
 /**
@@ -203,7 +203,7 @@ async function checkedOut(repo) {
 }
 /**
  * The roots that may be committed, as repo-relative paths: the workflows,
- * knowledge, agents, skills, channels and vibeables roots this project
+ * knowledge, agents, skills, channels, vibeables and projects roots this project
  * declares, plus kraftwerk.yml and the project README. The output directory
  * is excluded even when it lives inside one of them.
  */
@@ -234,6 +234,8 @@ function scopeFor({ project, repoRoot }) {
         path.resolve(project.root, "channels"),
         // Vibeables are the workspace's own apps: versioned with it, unlike clones.
         vibeablesRootFor(project),
+        // Projects too: briefs, state and logs are the workspace's own record.
+        projectsRootFor(project),
         project.configPath,
         path.resolve(project.root, "README.md"),
     ];
@@ -411,7 +413,7 @@ export async function gitStatus(fresh = false) {
     const blocked = all.filter((f) => !f.syncable).sort(byPath);
     const blockedHidden = Math.max(0, blocked.length - MAX_BLOCKED);
     const scopeError = scope.wholeRepo
-        ? "A configured root points at the repository root, which would put the whole repo in scope. Narrow workflows/knowledge/agents/skills/vibeables in kraftwerk.yml."
+        ? "A configured root points at the repository root, which would put the whole repo in scope. Narrow workflows/knowledge/agents/skills/vibeables/projects in kraftwerk.yml."
         : undefined;
     const value = {
         ...base,

package/dist/inspector/instances.d.ts

@@ -1,7 +1,7 @@
 import type { AgentSummary } from "./agents.js";
 import type { ChannelSummary } from "./channels.js";
 /** Durable per-project record. The root is the key; everything else derives from it. */
-export interface ProjectRecord {
+export interface WorkspaceRecord {
     root: string;
     firstSeen: string;
     lastStarted: string;
@@ -29,7 +29,7 @@ export interface DiscoveredInstance {
 }
 /**
  * One workspace as the switcher shows it: a known project (running or
- * not) or a running instance the projects registry doesn't know yet.
+ * not) or a running instance the workspace registry doesn't know yet.
  */
 export interface WorkspaceEntry {
     name: string;
@@ -49,6 +49,8 @@ export interface WorkspaceEntry {
     lastStarted?: string;
     lastStopped?: string;
 }
+/** File name of a root's record: a hash of the absolute root, the same under the old and the new directory. */
+export declare const workspaceRecordName: (root: string) => string;
 /** ~/… for display. */
 export declare const tildify: (p: string) => string;
 /** Write this instance's registry file (call once the server listens). */
@@ -60,15 +62,15 @@ export declare function unregisterInstance(): void;
 /** All other running instances, verified live. Cached briefly — /api/meta is polled. */
 export declare function discoverInstances(): Promise<DiscoveredInstance[]>;
 /** Upsert the project record for a root (call on every inspector start). */
-export declare function registerProject(root: string): Promise<void>;
-export declare const syncProjectAgents: (root: string, agents: AgentSummary[]) => Promise<void>;
-export declare const syncProjectChannels: (root: string, channels: ChannelSummary[]) => Promise<void>;
+export declare function registerWorkspace(root: string): Promise<void>;
+export declare const syncWorkspaceAgents: (root: string, agents: AgentSummary[]) => Promise<void>;
+export declare const syncWorkspaceChannels: (root: string, channels: ChannelSummary[]) => Promise<void>;
 /** Stamp lastStopped on clean shutdown. Sync so exit handlers can call it. */
-export declare function markProjectStopped(): void;
-/** All known projects, most recently started first. */
-export declare function listProjects(): Promise<ProjectRecord[]>;
-/** Drop a project record (the root itself is untouched). */
-export declare function forgetProject(root: string): Promise<boolean>;
+export declare function markWorkspaceStopped(): void;
+/** All known workspaces, most recently started first. */
+export declare function listWorkspaceRecords(): Promise<WorkspaceRecord[]>;
+/** Drop a workspace record (the root itself is untouched) — from the legacy directory too, see migrateRegistry. */
+export declare function forgetWorkspace(root: string): Promise<boolean>;
 /**
  * The switcher's view: every known project joined with the live instances,
  * plus running instances with no project record yet. The calling instance
@@ -118,14 +120,14 @@ export interface StartResult {
  * Waits up to ~5s for the new inspector to answer so callers can link
  * straight to it.
  */
-export declare function startProject(root: string): Promise<StartResult>;
+export declare function startWorkspace(root: string): Promise<StartResult>;
 /**
  * Stop a running workspace: SIGTERM to its server process, which
  * unregisters, stamps lastStopped and exits; the `kraftwerk ui` supervisor
  * follows. Matched by root, or by url for instances from older versions
  * that registered no root. Waits up to ~5s for the port to go quiet.
  */
-export declare function stopProject(target: {
+export declare function stopWorkspace(target: {
     root?: string;
     url?: string;
 }): Promise<{