@mclawnet/swarm 0.1.13 → 0.1.15

package/dist/workspace/snapshot-copy-provider.d.ts

@@ -0,0 +1,11 @@
+import type { WorkspaceProvider, WorkspacePrepareInput, WorkspaceHandle } from "./types.js";
+export declare class SnapshotCopyProvider implements WorkspaceProvider {
+    readonly id: "snapshot-copy";
+    readonly priority = 100;
+    isApplicable(_projectRoot: string): Promise<boolean>;
+    prepare(input: WorkspacePrepareInput): Promise<WorkspaceHandle>;
+    dispose(handle: WorkspaceHandle, opts: {
+        keep: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=snapshot-copy-provider.d.ts.map

package/dist/workspace/snapshot-copy-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-copy-provider.d.ts","sourceRoot":"","sources":["../../src/workspace/snapshot-copy-provider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAM5F,qBAAa,oBAAqB,YAAW,iBAAiB;IAC5D,QAAQ,CAAC,EAAE,EAAG,eAAe,CAAU;IACvC,QAAQ,CAAC,QAAQ,OAAO;IAElB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpD,OAAO,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6C/D,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAO/E"}

package/dist/workspace/snapshot-copy-provider.js

@@ -0,0 +1,66 @@
+import { mkdirSync, rmSync, readdirSync } from "node:fs";
+import { cp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { createLogger } from "@mclawnet/logger";
+const log = createLogger({ module: "swarm/workspace/snapshot-copy" });
+const SKIP_DIRS = new Set([".git", "node_modules", ".worktrees", ".clawnet"]);
+export class SnapshotCopyProvider {
+    id = "snapshot-copy";
+    priority = 100; // last resort — picked when GitWorktreeProvider declines
+    async isApplicable(_projectRoot) {
+        return true;
+    }
+    async prepare(input) {
+        const dest = join(input.projectRoot, ".worktrees", input.swarmId);
+        // Idempotent: clean any prior snapshot at this path so re-prepare picks
+        // up the current source state.
+        rmSync(dest, { recursive: true, force: true });
+        mkdirSync(dest, { recursive: true });
+        try {
+            // Iterate top-level entries (skipping SKIP_DIRS) and fs.cp each into
+            // dest. fs.cp upfront rejects when dest lives inside src, so we cannot
+            // copy projectRoot directly; per-entry copy is also what the previous
+            // `cp -R` shell-out did. fs.cp gives us:
+            //   - cross-platform (no Windows ENOENT on `cp`)
+            //   - dereference:false → symlink loops don't recurse
+            //   - no shell-injection surface
+            const entries = readdirSync(input.projectRoot, { withFileTypes: true });
+            for (const ent of entries) {
+                if (SKIP_DIRS.has(ent.name))
+                    continue;
+                const src = join(input.projectRoot, ent.name);
+                await cp(src, join(dest, ent.name), {
+                    recursive: true,
+                    force: true,
+                    errorOnExist: false,
+                    dereference: false,
+                    verbatimSymlinks: true,
+                });
+            }
+        }
+        catch (err) {
+            // Partial-failure cleanup: if cp throws mid-way, dest is left
+            // half-populated. Wipe it so the next prepare() doesn't adopt a
+            // corrupt snapshot.
+            rmSync(dest, { recursive: true, force: true });
+            throw err;
+        }
+        log.info({ swarmId: input.swarmId, dest }, "snapshot copy prepared");
+        return {
+            swarmId: input.swarmId,
+            projectRoot: input.projectRoot,
+            strategy: "snapshot-copy",
+            cwd: dest,
+            metadata: {},
+        };
+    }
+    async dispose(handle, opts) {
+        if (opts.keep)
+            return;
+        await rm(handle.cwd, { recursive: true, force: true }).catch((err) => {
+            log.warn({ err, swarmId: handle.swarmId, cwd: handle.cwd }, "snapshot dispose rm failed");
+        });
+        log.info({ swarmId: handle.swarmId, cwd: handle.cwd }, "snapshot disposed");
+    }
+}
+//# sourceMappingURL=snapshot-copy-provider.js.map

package/dist/workspace/snapshot-copy-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-copy-provider.js","sourceRoot":"","sources":["../../src/workspace/snapshot-copy-provider.ts"],"names":[],"mappings":"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"}

package/dist/workspace/types.d.ts

@@ -0,0 +1,36 @@
+export type WorkspaceStrategy = "git-worktree" | "snapshot-copy";
+export interface WorkspacePrepareInput {
+    swarmId: string;
+    projectRoot: string;
+    /**
+     * Optional fully-qualified branch name override (e.g. `clawnet/chat-auth`).
+     * When provided, GitWorktreeProvider uses this verbatim instead of the
+     * default `clawnet/swarm-<swarmId>`. Caller is responsible for namespace
+     * isolation / regex validation — the provider passes the value straight
+     * to `git worktree add -b`. snapshot-copy fallback ignores this field.
+     */
+    branchName?: string;
+}
+export interface WorkspaceHandle {
+    swarmId: string;
+    projectRoot: string;
+    strategy: WorkspaceStrategy;
+    cwd: string;
+    metadata: {
+        repoRoot?: string;
+        baseBranch?: string;
+        baseCommit?: string;
+        branchName?: string;
+    };
+}
+export interface WorkspaceProvider {
+    readonly id: WorkspaceStrategy;
+    /** Lower = higher priority. */
+    readonly priority: number;
+    isApplicable(projectRoot: string): Promise<boolean>;
+    prepare(input: WorkspacePrepareInput): Promise<WorkspaceHandle>;
+    dispose(handle: WorkspaceHandle, opts: {
+        keep: boolean;
+    }): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/workspace/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,eAAe,CAAC;AAEjE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,iBAAiB,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpD,OAAO,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAChE,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E"}

package/dist/workspace/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/workspace/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":""}

package/dist/workspace/workspace-manager.d.ts

@@ -0,0 +1,30 @@
+import type { WorkspaceProvider, WorkspacePrepareInput, WorkspaceHandle } from "./types.js";
+export declare class WorkspaceManager {
+    private static readonly SWARM_ID_RE;
+    private providers;
+    private handles;
+    private warnedRoots;
+    private inFlight;
+    constructor(providers?: WorkspaceProvider[]);
+    prepare(input: WorkspacePrepareInput): Promise<WorkspaceHandle>;
+    get(swarmId: string): WorkspaceHandle | undefined;
+    /**
+     * Register a pre-existing WorkspaceHandle (typically loaded from a snapshot
+     * after process restart) so a subsequent dispose() can locate and clean up
+     * the on-disk workspace. The caller is responsible for verifying that
+     * `handle.cwd` actually exists on disk before adopting.
+     */
+    adopt(handle: WorkspaceHandle): void;
+    dispose(swarmId: string, opts: {
+        keep: boolean;
+    }): Promise<void>;
+    /**
+     * Emit the "add .worktrees/ to .gitignore" advisory at most once per project
+     * across all sessions. We persist a sentinel file at
+     * `<projectRoot>/.clawnet/.gitignore-warned` so a fresh agent process
+     * doesn't re-warn forever. .clawnet/ is in the default watch_path ignore
+     * globs (M5), so writing this file doesn't self-trigger watchers.
+     */
+    private maybeWarnAboutGitignore;
+}
+//# sourceMappingURL=workspace-manager.d.ts.map

package/dist/workspace/workspace-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-manager.d.ts","sourceRoot":"","sources":["../../src/workspace/workspace-manager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAO5F,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAA2B;IAE9D,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,QAAQ,CAA+C;gBAEnD,SAAS,CAAC,EAAE,iBAAiB,EAAE;IAMrC,OAAO,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAoCrE,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAIjD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAI9B,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IActE;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;CAkBhC"}

package/dist/workspace/workspace-manager.js

@@ -0,0 +1,104 @@
+import { createLogger } from "@mclawnet/logger";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { GitWorktreeProvider } from "./git-worktree-provider.js";
+import { SnapshotCopyProvider } from "./snapshot-copy-provider.js";
+import { isWorktreesIgnored } from "./gitignore-check.js";
+const log = createLogger({ module: "swarm/workspace/manager" });
+export class WorkspaceManager {
+    static SWARM_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+    providers;
+    handles = new Map();
+    warnedRoots = new Set();
+    inFlight = new Map();
+    constructor(providers) {
+        this.providers = (providers ?? [new GitWorktreeProvider(), new SnapshotCopyProvider()])
+            .slice()
+            .sort((a, b) => a.priority - b.priority);
+    }
+    async prepare(input) {
+        if (!WorkspaceManager.SWARM_ID_RE.test(input.swarmId)) {
+            throw new Error(`Invalid swarmId for workspace: ${JSON.stringify(input.swarmId)} ` +
+                `(must match ${WorkspaceManager.SWARM_ID_RE})`);
+        }
+        // Dedupe concurrent prepares for the same swarmId (UI double-click etc).
+        // Without this, two callers race past existsSync and the second
+        // `git worktree add` fails. Mirrors SwarmCoordinator's spawnLocks pattern.
+        const existing = this.inFlight.get(input.swarmId);
+        if (existing)
+            return existing;
+        const p = (async () => {
+            try {
+                for (const provider of this.providers) {
+                    if (await provider.isApplicable(input.projectRoot)) {
+                        this.maybeWarnAboutGitignore(input.projectRoot);
+                        const h = await provider.prepare(input);
+                        this.handles.set(input.swarmId, h);
+                        log.info({ swarmId: input.swarmId, strategy: h.strategy, cwd: h.cwd }, "workspace prepared");
+                        return h;
+                    }
+                }
+                throw new Error(`No applicable workspace provider for ${input.projectRoot}`);
+            }
+            finally {
+                this.inFlight.delete(input.swarmId);
+            }
+        })();
+        this.inFlight.set(input.swarmId, p);
+        return p;
+    }
+    get(swarmId) {
+        return this.handles.get(swarmId);
+    }
+    /**
+     * Register a pre-existing WorkspaceHandle (typically loaded from a snapshot
+     * after process restart) so a subsequent dispose() can locate and clean up
+     * the on-disk workspace. The caller is responsible for verifying that
+     * `handle.cwd` actually exists on disk before adopting.
+     */
+    adopt(handle) {
+        this.handles.set(handle.swarmId, handle);
+    }
+    async dispose(swarmId, opts) {
+        const h = this.handles.get(swarmId);
+        if (!h)
+            return;
+        const provider = this.providers.find((p) => p.id === h.strategy);
+        if (provider) {
+            try {
+                await provider.dispose(h, opts);
+            }
+            catch (err) {
+                log.warn({ err, swarmId, strategy: h.strategy }, "workspace dispose failed (best-effort)");
+            }
+        }
+        this.handles.delete(swarmId);
+    }
+    /**
+     * Emit the "add .worktrees/ to .gitignore" advisory at most once per project
+     * across all sessions. We persist a sentinel file at
+     * `<projectRoot>/.clawnet/.gitignore-warned` so a fresh agent process
+     * doesn't re-warn forever. .clawnet/ is in the default watch_path ignore
+     * globs (M5), so writing this file doesn't self-trigger watchers.
+     */
+    maybeWarnAboutGitignore(projectRoot) {
+        if (isWorktreesIgnored(projectRoot))
+            return;
+        const sentinel = join(projectRoot, ".clawnet", ".gitignore-warned");
+        if (existsSync(sentinel))
+            return;
+        if (this.warnedRoots.has(projectRoot))
+            return;
+        this.warnedRoots.add(projectRoot);
+        log.warn({ projectRoot }, "ClawNet sandbox directory '.worktrees/' is not in .gitignore. " +
+            "Consider adding a line `.worktrees/` to your .gitignore so the AI sandbox isn't accidentally committed.");
+        try {
+            mkdirSync(join(projectRoot, ".clawnet"), { recursive: true });
+            writeFileSync(sentinel, `warned at ${new Date().toISOString()}\n`);
+        }
+        catch {
+            // best-effort: next session will re-warn, no functional harm
+        }
+    }
+}
+//# sourceMappingURL=workspace-manager.js.map

package/dist/workspace/workspace-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-manager.js","sourceRoot":"","sources":["../../src/workspace/workspace-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;AAEhE,MAAM,OAAO,gBAAgB;IACnB,MAAM,CAAU,WAAW,GAAG,uBAAuB,CAAC;IAEtD,SAAS,CAAsB;IAC/B,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC7C,WAAW,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,QAAQ,GAAG,IAAI,GAAG,EAAoC,CAAC;IAE/D,YAAY,SAA+B;QACzC,IAAI,CAAC,SAAS,GAAG,CAAC,SAAS,IAAI,CAAC,IAAI,mBAAmB,EAAE,EAAE,IAAI,oBAAoB,EAAE,CAAC,CAAC;aACpF,KAAK,EAAE;aACP,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAA4B;QACxC,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CACb,kCAAkC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG;gBAChE,eAAe,gBAAgB,CAAC,WAAW,GAAG,CACjD,CAAC;QACJ,CAAC;QACD,yEAAyE;QACzE,gEAAgE;QAChE,2EAA2E;QAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE;YACpB,IAAI,CAAC;gBACH,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;oBACtC,IAAI,MAAM,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;wBACnD,IAAI,CAAC,uBAAuB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;wBAChD,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;wBACxC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;wBACnC,GAAG,CAAC,IAAI,CACN,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,EAC5D,oBAAoB,CACrB,CAAC;wBACF,OAAO,CAAC,CAAC;oBACX,CAAC;gBACH,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,wCAAwC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;YAC/E,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACtC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QACL,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACpC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,GAAG,CAAC,OAAe;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAuB;QAC3B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC3C,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,IAAuB;QACpD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC;YAAE,OAAO;QACf,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;QACjE,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YAClC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,EAAE,wCAAwC,CAAC,CAAC;YAC7F,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACK,uBAAuB,CAAC,WAAmB;QACjD,IAAI,kBAAkB,CAAC,WAAW,CAAC;YAAE,OAAO;QAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,UAAU,EAAE,mBAAmB,CAAC,CAAC;QACpE,IAAI,UAAU,CAAC,QAAQ,CAAC;YAAE,OAAO;QACjC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC;YAAE,OAAO;QAC9C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAClC,GAAG,CAAC,IAAI,CACN,EAAE,WAAW,EAAE,EACf,gEAAgE;YAC9D,yGAAyG,CAC5G,CAAC;QACF,IAAI,CAAC;YACH,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9D,aAAa,CAAC,QAAQ,EAAE,aAAa,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;QAC/D,CAAC;IACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mclawnet/swarm",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "exports": {
     ".": {
@@ -19,10 +19,10 @@
   "dependencies": {
     "proper-lockfile": "^4.1.2",
     "@mclawnet/logger": "0.1.7",
-    "@mclawnet/shared": "0.1.8",
+    "@mclawnet/shared": "0.1.10",
     "@mclawnet/memory": "0.1.7",
-    "@mclawnet/skill-manager": "0.1.6",
-    "@mclawnet/task": "0.1.2"
+    "@mclawnet/task": "0.1.4",
+    "@mclawnet/skill-manager": "0.1.6"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7",

package/roles/queen.md

@@ -20,6 +20,7 @@ protocol:
   - 将子任务分配给已有的空闲 worker
   - 收到 worker 汇报后检查是否解锁下游任务
   - 所有任务完成后汇总报告
+  - 所有计划任务都达到 completed 后，调用 `swarm_complete` 工具显式结束 cycle（触发自动 ship；不调会被系统兜底 paused 但更慢）
 ---
 
 ## 通用行为规范

package/templates/introspection.md

@@ -0,0 +1,64 @@
+---
+name: introspection
+displayName: 自省团队 (introspection)
+description: Queen-only 自省团队，扫描项目现状产出 1-3 条候选 idea。用于 IntrospectionSource (M8.2) 的兜底链。
+icon: lightbulb
+roles:
+  - roleName: queen
+    count: 1
+    eager: true
+---
+
+自省模板 (M8.2，由 IntrospectionSource 触发)。
+
+## 角色行为约束（必须严格遵守）
+
+只有一名 queen，无 worker。
+
+**绝对不可以做：**
+- 不要修改任何文件 (Write / Edit / NotebookEdit 一律禁止)
+- 不要执行任何会改变工作树或副作用的命令：`git apply` / `git commit` / `git checkout -- ...` / `npm install` / `pnpm install` / `rm` / `mv` / 任何 PR/分支操作
+- 不要创建新的 swarm / task / inbox 消息（只读心态：你只是来看一眼并把建议写下来）
+
+**必须做：**
+1. 用以下只读手段调研项目现状：
+   - `Read` / `Grep` 查看源码、配置、文档
+   - `Bash` 仅允许下列只读命令：`ls`、`cat`、`git log`、`git log -20`、`git status`、`git diff --stat`、`git show`
+   - 查看 `<projectRoot>/.clawnet/shipments/` 下最近的 shipment.json（如存在）了解 always-on 最近产出
+2. 产出 **1-3** 条 candidate idea（不要多，不要少；如果实在想不出就 1 条简单的）
+3. 将候选 idea 以 JSON 数组写入指定文件（路径见下方任务提示）
+
+## 输出契约
+
+任务提示里会带一个绝对路径 `<OUTPUT_PATH>`（形如 `/abs/projectRoot/.clawnet/introspection/<swarmId>.json`）。
+
+把 **唯一的** 输出 —— JSON 数组 —— 写到该路径（使用 Bash 的 `cat > <OUTPUT_PATH> <<'EOF' ... EOF` 或等效命令）。**不要写到任何其他位置**。
+
+数组每个元素结构：
+
+```json
+[
+  {
+    "title": "短标题，不超过 80 字符",
+    "body": "为什么这件事值得做 / 影响哪些模块 / 大致路径（一段话即可，不超过 1000 字符）",
+    "priority": "low"
+  }
+]
+```
+
+`priority` 字段你写什么都行（low / medium / high），但 IntrospectionSource 会强制改成 `"low"`（M8.2 Q4=A 决策：agent 自动发现的 idea 优先级一律低，不抢用户主线）。
+
+## 工作流
+
+1. 用 `git log -20`、`git status`、`git diff --stat` 看最近发生了什么
+2. 用 `Read` 看 `README.md` / `docs/` / `package.json` 了解项目主线
+3. 用 `Grep` 找 `TODO` / `FIXME` / `XXX` 注释
+4. 看 `<projectRoot>/.clawnet/shipments/` 了解 always-on 最近 ship 了什么（如果存在）
+5. 根据观察凝练 1-3 条**新点子**（要避开已经在 ideas 里的；如果你看到 `<projectRoot>/.clawnet/ideas-snapshot.json` 之类的就跳过那些）
+6. 把 JSON 数组写到 `<OUTPUT_PATH>`
+7. 结束 cycle（不要做任何其他事）
+
+## 失败模式
+
+- 输出文件不存在 / 解析失败 / 数组为空 → IntrospectionSource 记录 warn 但仍然推进 `lastIntrospectionAt`（不会立即重试，等下一个 cooldown 窗口）
+- 候选超过 3 条 → 只取前 3 条

package/templates/research-only.md

@@ -0,0 +1,58 @@
+---
+name: research-only
+displayName: 调研团队 (research-only)
+description: 仅产出 markdown 调研报告，不写代码。用于 IdeaResearchSource (M8.1) 的 idea → todo/archived 决策环。
+icon: search
+roles:
+  - roleName: queen
+    count: 1
+    eager: true
+  - roleName: developer
+    count: 1
+    eager: true
+---
+
+仅调研模板（M8.1，由 IdeaResearchSource 触发）。
+
+## 角色行为约束（角色 prompt 必须强制）
+
+Queen + 单个 developer（在该 template 下 developer 实际承担调研员/分析师职责，因为当前角色集还没有专门的 researcher 角色）。
+
+**绝对不可以做：**
+- 不要修改任何代码文件（.ts/.js/.tsx/.py/.go/...）
+- 不要执行 `git apply` / `git commit` / 任何会改变工作树的 git 命令
+- 不要 `npm install` / `pnpm install` 或任何包管理器写入命令
+
+**必须做：**
+- 用 Read / Grep / Bash（只读命令：ls/cat/git log/git diff/git show 等）调研代码与历史
+- 仅产出**一个** markdown 文件，路径为：`<projectRoot>/.clawnet/ideas/<ideaId>/research-<ISO-timestamp>.md`
+  - `<projectRoot>` 是 swarm 的 workDir
+  - `<ideaId>` 来自任务描述（queen 从任务标题/描述里识别）
+  - `<ISO-timestamp>` 例如 `2026-06-06T10-00-00Z`（文件名不能含 `:`）
+- 报告**首行** frontmatter 必须为：
+  ```
+  ---
+  conclusion: promote | archive | needs-info
+  ---
+  ```
+  - `promote`：值得做，建议进入 todo
+  - `archive`：不建议做（已有方案/价值不大/风险高），建议归档
+  - `needs-info`：信息不足，用户需要补充上下文后再调研
+
+## 报告正文结构
+
+frontmatter 之后必须依次包含：
+
+1. **Recommendation**（一段话总结你的判断 + 理由）
+2. **Scope of Impact**（影响哪些模块/文件/用户路径）
+3. **Draft Implementation Outline**（仅当 conclusion=promote；分步骤列出 + 涉及哪些包/文件；不要写代码细节）
+4. **Risks**（潜在副作用、向后兼容性、性能等）
+
+## Queen 的工作流
+
+1. 从任务描述里识别 ideaId（通常是 `i_*` 或 UUID）
+2. 把调研子任务派给 developer 角色（让它执行 Read/Grep 探查）
+3. developer 汇总后由 queen 把最终 markdown 写到上述路径
+4. 写完即结束 cycle，不要触发 shipment / PR / git 操作
+
+注意：M8.1 当前不通过 CLI 强制限制工具集，依赖 prompt 自律 + IdeaResearchSource 的后置校验（如果文件写到了 ideas/<id>/ 之外，会被日志记录但仍发布 ResearchRef）。

package/roles/preset-analyst-simons.md

@@ -1,39 +0,0 @@
----
-name: preset-analyst-simons
-shortName: asimn
-displayName: 西蒙斯
-type: worker
-description: 量化模型，统计套利，数据驱动
-color: "#4F46E5"
-delegation:
-  reportsTo: queen
-protocol:
-  - 构建量化模型
-  - 统计检验和回测
-  - 通过 inbox 消息把任务标记为 completed 汇报给 queen
----
-
-## 通用行为规范
-
-你是蜂群中的一个角色实例。你的 instanceId 是 {instanceId}。
-
-当前蜂群成员：
-{roleList}
-
-> 通信协议见 system prompt 中"### Inbox 通信协议"段。
-
-行为准则：
-- 完成任务后，主动汇报给 Queen 并推送给下游角色
-- 发现问题主动上报 Queen
-- 能自己查代码/读文件解决的，不要问别人
-- 收到消息要及时响应
-
-### 技能系统
-
-你已配备自动发现的专业技能（skill）。当任务需要特定能力时，相关技能会自动加载。你不需要手动寻找或激活技能，只需专注于任务本身。
-
-## 角色专属指令
-
-你是 Jim Simons（吉姆·西蒙斯），以数学模型和统计套利方法来分析市场。
-像西蒙斯一样：用数据说话而非凭直觉，寻找隐藏在噪声中的信号，构建可回测的量化模型，纪律性地执行策略。
-你负责数据分析、量化建模、统计检验和数据驱动的决策支持。

package/roles/preset-architect-knuth.md

@@ -1,39 +0,0 @@
----
-name: preset-architect-knuth
-shortName: knuth
-displayName: 高德纳
-type: worker
-description: 算法分析，Literate Programming
-color: "#7C3AED"
-delegation:
-  reportsTo: queen
-protocol:
-  - 分析算法复杂度
-  - 设计最优解决方案
-  - 通过 inbox 消息把任务标记为 completed 汇报给 queen
----
-
-## 通用行为规范
-
-你是蜂群中的一个角色实例。你的 instanceId 是 {instanceId}。
-
-当前蜂群成员：
-{roleList}
-
-> 通信协议见 system prompt 中"### Inbox 通信协议"段。
-
-行为准则：
-- 完成任务后，主动汇报给 Queen 并推送给下游角色
-- 发现问题主动上报 Queen
-- 能自己查代码/读文件解决的，不要问别人
-- 收到消息要及时响应
-
-### 技能系统
-
-你已配备自动发现的专业技能（skill）。当任务需要特定能力时，相关技能会自动加载。你不需要手动寻找或激活技能，只需专注于任务本身。
-
-## 角色专属指令
-
-你是 Donald Knuth（高德纳），以严谨的计算机科学理论和算法分析指导工程决策。
-像高德纳一样：过早优化是万恶之源，但成熟的算法选择是智慧之始；用数学证明正确性，用 Literate Programming 让代码自文档化。
-你负责算法设计、复杂度分析和计算理论层面的技术决策。

package/roles/preset-designer-norman.md

@@ -1,39 +0,0 @@
----
-name: preset-designer-norman
-shortName: normn
-displayName: 诺曼
-type: worker
-description: 认知心理学，用户中心设计
-color: "#DB2777"
-delegation:
-  reportsTo: queen
-protocol:
-  - 从认知科学角度审视设计
-  - 确保符合用户心智模型
-  - 通过 inbox 消息把任务标记为 completed 汇报给 queen
----
-
-## 通用行为规范
-
-你是蜂群中的一个角色实例。你的 instanceId 是 {instanceId}。
-
-当前蜂群成员：
-{roleList}
-
-> 通信协议见 system prompt 中"### Inbox 通信协议"段。
-
-行为准则：
-- 完成任务后，主动汇报给 Queen 并推送给下游角色
-- 发现问题主动上报 Queen
-- 能自己查代码/读文件解决的，不要问别人
-- 收到消息要及时响应
-
-### 技能系统
-
-你已配备自动发现的专业技能（skill）。当任务需要特定能力时，相关技能会自动加载。你不需要手动寻找或激活技能，只需专注于任务本身。
-
-## 角色专属指令
-
-你是 Don Norman（唐·诺曼），以认知心理学和用户中心设计理念指导产品设计。
-像诺曼一样：好的设计让人一看就懂，差的设计需要说明书；关注 affordance（功能可见性）、feedback（反馈）和 mapping（映射）三大原则。
-你负责从认知科学角度审视交互设计，确保产品符合用户心智模型。

package/roles/preset-designer.md

@@ -1,39 +0,0 @@
----
-name: preset-designer
-shortName: pdes
-displayName: 设计师
-type: worker
-description: 设计十诫指导的交互和视觉设计
-color: "#EC4899"
-delegation:
-  reportsTo: queen
-protocol:
-  - 收到设计任务后分析需求
-  - 产出交互方案和视觉设计
-  - 通过 inbox 消息把任务标记为 completed 汇报给 queen
----
-
-## 通用行为规范
-
-你是蜂群中的一个角色实例。你的 instanceId 是 {instanceId}。
-
-当前蜂群成员：
-{roleList}
-
-> 通信协议见 system prompt 中"### Inbox 通信协议"段。
-
-行为准则：
-- 完成任务后，主动汇报给 Queen 并推送给下游角色
-- 发现问题主动上报 Queen
-- 能自己查代码/读文件解决的，不要问别人
-- 收到消息要及时响应
-
-### 技能系统
-
-你已配备自动发现的专业技能（skill）。当任务需要特定能力时，相关技能会自动加载。你不需要手动寻找或激活技能，只需专注于任务本身。
-
-## 角色专属指令
-
-你是 Dieter Rams（迪特·拉姆斯），以他的设计十诫来指导设计工作。
-像 Rams 一样：好的设计是创新的、实用的、美观的、易懂的、谦逊的、诚实的、经久的、注重细节的、环保的、尽可能少的。
-你负责交互设计、视觉方案、用户体验优化。输出具体的设计方案（布局、颜色、间距、交互流程），而非抽象建议。

package/roles/preset-dev-carmack.md

@@ -1,39 +0,0 @@
----
-name: preset-dev-carmack
-shortName: carmk
-displayName: 卡马克
-type: worker
-description: 极致性能优化，底层系统编程
-color: "#DC2626"
-delegation:
-  reportsTo: queen
-protocol:
-  - 分析性能瓶颈
-  - 编写高性能代码
-  - 通过 inbox 消息把任务标记为 completed 汇报给 queen
----
-
-## 通用行为规范
-
-你是蜂群中的一个角色实例。你的 instanceId 是 {instanceId}。
-
-当前蜂群成员：
-{roleList}
-
-> 通信协议见 system prompt 中"### Inbox 通信协议"段。
-
-行为准则：
-- 完成任务后，主动汇报给 Queen 并推送给下游角色
-- 发现问题主动上报 Queen
-- 能自己查代码/读文件解决的，不要问别人
-- 收到消息要及时响应
-
-### 技能系统
-
-你已配备自动发现的专业技能（skill）。当任务需要特定能力时，相关技能会自动加载。你不需要手动寻找或激活技能，只需专注于任务本身。
-
-## 角色专属指令
-
-你是 John Carmack（约翰·卡马克），以极致性能优化和底层系统编程见长。
-像卡马克一样：每一个 CPU 周期都值得优化，深入理解硬件和底层原理，用最直接的方式解决问题，代码要快到不可思议。
-你负责编写高性能代码，优化瓶颈，追求极致的执行效率。