@mclawnet/swarm 0.1.4 → 0.1.6

package/dist/persistence.js

@@ -1,52 +1,89 @@
-import { writeFileSync, readFileSync, existsSync, mkdirSync, appendFileSync, rmSync, readdirSync, } from "node:fs";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, appendFileSync, rmSync, readdirSync, renameSync, } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-function getSwarmsDir() {
-    return join(homedir(), ".clawnet", "swarms");
+import { randomBytes } from "node:crypto";
+import { projectRoot } from "@mclawnet/task";
+import { createLogger } from "@mclawnet/logger";
+const log = createLogger({ module: "swarm-persistence" });
+function getHome() {
+    return process.env.CLAWNET_HOME ?? homedir();
 }
-function getSwarmDir(swarmId) {
-    return join(getSwarmsDir(), swarmId);
+function getSwarmsDir(workDir) {
+    return join(projectRoot(workDir, getHome()), "swarms");
+}
+function getSwarmDir(workDir, swarmId) {
+    return join(getSwarmsDir(workDir), swarmId);
 }
 export function saveSwarmSnapshot(swarm) {
-    const dir = getSwarmDir(swarm.id);
+    if (!swarm.workDir) {
+        throw new Error("saveSwarmSnapshot requires swarm.workDir");
+    }
+    const dir = getSwarmDir(swarm.workDir, swarm.id);
     mkdirSync(dir, { recursive: true });
     const snapshot = {
         id: swarm.id,
         hubSessionId: swarm.hubSessionId,
         workDir: swarm.workDir,
+        teamName: swarm.teamName ?? "default",
         roles: Array.from(swarm.roles.values()).map((r) => ({
             instanceId: r.instanceId,
             roleName: r.roleName,
             status: r.status,
             currentTask: r.currentTask,
+            claudeSessionId: r.claudeSessionId,
+            type: r.definition?.type,
         })),
         plan: swarm.plan,
         nextInstanceSeq: Object.fromEntries(swarm.nextInstanceSeq),
         savedAt: Date.now(),
         status: swarm.status,
         planStatus: swarm.planStatus,
+        partialRecover: swarm.partialRecover,
     };
-    writeFileSync(join(dir, "recovery.json"), JSON.stringify(snapshot, null, 2));
+    // Atomic write: write to a unique tmp file in the same dir, then rename
+    // over the target. rename(2) within a filesystem is atomic — readers either
+    // see the previous valid snapshot or the new one, never a half-written file.
+    const finalPath = join(dir, "recovery.json");
+    const tmpPath = join(dir, `recovery.${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(tmpPath, JSON.stringify(snapshot, null, 2));
+    try {
+        renameSync(tmpPath, finalPath);
+    }
+    catch (err) {
+        // best-effort cleanup of the tmp file so we don't leak garbage on disk
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        throw err;
+    }
 }
-export function loadSwarmSnapshot(swarmId) {
-    const filePath = join(getSwarmDir(swarmId), "recovery.json");
+export function loadSwarmSnapshot(workDir, swarmId) {
+    const filePath = join(getSwarmDir(workDir, swarmId), "recovery.json");
     if (!existsSync(filePath))
         return null;
     try {
-        return JSON.parse(readFileSync(filePath, "utf-8"));
+        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
+        return {
+            ...raw,
+            teamName: raw.teamName ?? "default",
+        };
     }
-    catch {
+    catch (err) {
+        log.warn({ err: err instanceof Error ? err.message : String(err), filePath, swarmId, workDir }, "loadSwarmSnapshot: failed to parse recovery.json — treating as missing");
         return null;
     }
 }
-export function deleteSwarmSnapshot(swarmId) {
-    const recoveryPath = join(getSwarmDir(swarmId), "recovery.json");
+export function deleteSwarmSnapshot(workDir, swarmId) {
+    const recoveryPath = join(getSwarmDir(workDir, swarmId), "recovery.json");
     if (existsSync(recoveryPath)) {
         rmSync(recoveryPath);
     }
 }
-export function readMessageLog(swarmId) {
-    const filePath = join(getSwarmDir(swarmId), "messages.jsonl");
+export function readMessageLog(workDir, swarmId) {
+    const filePath = join(getSwarmDir(workDir, swarmId), "messages.jsonl");
     if (!existsSync(filePath))
         return [];
     try {
@@ -68,17 +105,55 @@ export function readMessageLog(swarmId) {
         return [];
     }
 }
-export function appendMessageLog(swarmId, entry) {
-    const dir = getSwarmDir(swarmId);
+export function appendMessageLog(workDir, swarmId, entry) {
+    const dir = getSwarmDir(workDir, swarmId);
     mkdirSync(dir, { recursive: true });
     appendFileSync(join(dir, "messages.jsonl"), JSON.stringify(entry) + "\n");
 }
+/**
+ * List recoverable swarms across all per-project roots. The authoritative
+ * `workDir` is read from each snapshot's `workDir` field (snapshots written
+ * since 0.1.6 always include it). Falling back on the encoded directory
+ * name is lossy for paths whose segments contain `-`, so we deliberately
+ * skip entries whose snapshot can't be parsed or doesn't carry `workDir`.
+ */
 export function listRecoverableSwarmIds() {
-    const dir = getSwarmsDir();
-    if (!existsSync(dir))
+    const projectsDir = join(getHome(), ".clawnet", "projects");
+    if (!existsSync(projectsDir))
         return [];
-    return readdirSync(dir, { withFileTypes: true })
-        .filter((e) => e.isDirectory() && existsSync(join(dir, e.name, "recovery.json")))
-        .map((e) => e.name);
+    const result = [];
+    for (const projEntry of readdirSync(projectsDir, { withFileTypes: true })) {
+        if (!projEntry.isDirectory())
+            continue;
+        const swarmsDir = join(projectsDir, projEntry.name, "swarms");
+        if (!existsSync(swarmsDir))
+            continue;
+        for (const swarmEntry of readdirSync(swarmsDir, { withFileTypes: true })) {
+            if (!swarmEntry.isDirectory())
+                continue;
+            const swarmDir = join(swarmsDir, swarmEntry.name);
+            const recoveryPath = join(swarmDir, "recovery.json");
+            if (!existsSync(recoveryPath)) {
+                // Orphan: a swarm directory exists but was never persisted (likely
+                // an aborted SwarmCoordinator.create()). Surface it for the operator
+                // — never auto-delete (could destroy in-progress user state).
+                log.warn({ swarmDir, swarmId: swarmEntry.name, projectDir: projEntry.name }, "listRecoverableSwarmIds: swarm directory has no recovery.json — skipping (manual cleanup may be needed)");
+                continue;
+            }
+            try {
+                const raw = JSON.parse(readFileSync(recoveryPath, "utf-8"));
+                if (typeof raw.workDir === "string" && raw.workDir.length > 0) {
+                    result.push({ workDir: raw.workDir, swarmId: swarmEntry.name });
+                }
+                else {
+                    log.warn({ recoveryPath, swarmId: swarmEntry.name }, "listRecoverableSwarmIds: snapshot missing workDir field — skipping");
+                }
+            }
+            catch (err) {
+                log.warn({ err: err instanceof Error ? err.message : String(err), recoveryPath, swarmId: swarmEntry.name }, "listRecoverableSwarmIds: failed to parse recovery.json — skipping");
+            }
+        }
+    }
+    return result;
 }
 //# sourceMappingURL=persistence.js.map

package/dist/persistence.js.map

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

package/dist/project-files.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Project files endpoint helpers.
+ *
+ * Surfaces a fixed whitelist of files inside a project's `workDir` (CLAUDE.md
+ * and .claude/settings*.json) so the UI can read/write them without giving
+ * blanket FS access.
+ *
+ * Why a hard-coded whitelist (no globs in P1):
+ *   The Claude CLI auto-loads exactly these paths from cwd. Limiting to the
+ *   exact set lets us audit every read/write and rules out mistakes like a
+ *   user typing `relPath=../../etc/passwd` or `.git/config`. Phase 2 may add
+ *   `.claude/rules/*.md`, which will require a careful prefix-glob design.
+ *
+ * Defense-in-depth path checks:
+ *   1. relPath must be in WHITELIST (exact string match)
+ *   2. Resolved absolute path must live under realpath(workDir)
+ *   3. realpath() resolves symlinks, so a symlink inside .claude/ that
+ *      points outside workDir is still rejected by check (2).
+ */
+export declare const PROJECT_FILE_WHITELIST: readonly ["CLAUDE.md", ".claude/CLAUDE.md", ".claude/settings.json", ".claude/settings.local.json"];
+export type ProjectFileRelPath = (typeof PROJECT_FILE_WHITELIST)[number];
+export interface ProjectFileEntry {
+    relPath: ProjectFileRelPath;
+    exists: boolean;
+    size?: number;
+    mtime?: number;
+    loadedByCli: true;
+}
+export interface ProjectFileContent {
+    relPath: ProjectFileRelPath;
+    content: string;
+    mtime: number;
+    etag: string;
+}
+export declare class ProjectFilesError extends Error {
+    status: number;
+    details?: Record<string, unknown> | undefined;
+    constructor(status: number, message: string, details?: Record<string, unknown> | undefined);
+}
+/** Type guard — narrows an arbitrary string to the whitelist union. */
+export declare function isWhitelistedRelPath(rel: string): rel is ProjectFileRelPath;
+/** List the whitelist with stat info for present files. Never throws. */
+export declare function listProjectFiles(workDir: string): ProjectFileEntry[];
+/**
+ * Read a whitelisted file. Returns content="" + etag of empty string when
+ * the file does not exist, so the editor UI can populate a blank textarea
+ * with a valid etag for first-write conflict detection.
+ */
+export declare function readProjectFile(workDir: string, relPath: string): ProjectFileContent;
+export interface WriteOptions {
+    ifMatchEtag?: string;
+}
+/**
+ * Atomic write: validates JSON syntax for `.json` files, ensures parent
+ * `.claude/` exists, writes to a tmp sibling, then renames. Returns the
+ * post-write content snapshot. On etag mismatch throws 409 with the current
+ * server-side content so the UI can render a 3-way diff.
+ */
+export declare function writeProjectFile(workDir: string, relPath: string, newContent: string, opts?: WriteOptions): ProjectFileContent;
+//# sourceMappingURL=project-files.d.ts.map

package/dist/project-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-files.d.ts","sourceRoot":"","sources":["../src/project-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAcH,eAAO,MAAM,sBAAsB,qGAKzB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAEjC,MAAM,EAAE,MAAM;IAEd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,MAAM,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAK3C;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,kBAAkB,CAE3E;AA8CD,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAmCpE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAmBpF;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,YAAiB,GACtB,kBAAkB,CA6DpB"}

package/dist/project-files.js

@@ -0,0 +1,214 @@
+/**
+ * Project files endpoint helpers.
+ *
+ * Surfaces a fixed whitelist of files inside a project's `workDir` (CLAUDE.md
+ * and .claude/settings*.json) so the UI can read/write them without giving
+ * blanket FS access.
+ *
+ * Why a hard-coded whitelist (no globs in P1):
+ *   The Claude CLI auto-loads exactly these paths from cwd. Limiting to the
+ *   exact set lets us audit every read/write and rules out mistakes like a
+ *   user typing `relPath=../../etc/passwd` or `.git/config`. Phase 2 may add
+ *   `.claude/rules/*.md`, which will require a careful prefix-glob design.
+ *
+ * Defense-in-depth path checks:
+ *   1. relPath must be in WHITELIST (exact string match)
+ *   2. Resolved absolute path must live under realpath(workDir)
+ *   3. realpath() resolves symlinks, so a symlink inside .claude/ that
+ *      points outside workDir is still rejected by check (2).
+ */
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { dirname, join, sep } from "node:path";
+export const PROJECT_FILE_WHITELIST = [
+    "CLAUDE.md",
+    ".claude/CLAUDE.md",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+];
+export class ProjectFilesError extends Error {
+    status;
+    details;
+    constructor(status, message, details) {
+        super(message);
+        this.status = status;
+        this.details = details;
+        this.name = "ProjectFilesError";
+    }
+}
+/** Type guard — narrows an arbitrary string to the whitelist union. */
+export function isWhitelistedRelPath(rel) {
+    return PROJECT_FILE_WHITELIST.includes(rel);
+}
+/**
+ * Resolve `relPath` against `workDir` and verify the result is still inside
+ * workDir even after symlink resolution. Throws ProjectFilesError on any
+ * violation. Returns the absolute path (which may not exist yet — caller
+ * decides whether absence is OK).
+ */
+function resolveSafe(workDir, relPath) {
+    // workDir itself must exist for any of this to make sense.
+    let workDirReal;
+    try {
+        workDirReal = realpathSync(workDir);
+    }
+    catch {
+        throw new ProjectFilesError(404, "workDir does not exist on disk");
+    }
+    const candidate = join(workDirReal, relPath);
+    // For an existing file, realpath the file. For a not-yet-existing file,
+    // realpath the *parent* (which we may need to mkdir later) — this still
+    // catches symlink escapes from intermediate components.
+    let probe;
+    if (existsSync(candidate)) {
+        probe = realpathSync(candidate);
+    }
+    else {
+        // Walk up to the first existing ancestor and realpath it; that's enough
+        // to ensure we won't end up writing outside workDir even after rename().
+        let parent = dirname(candidate);
+        while (!existsSync(parent))
+            parent = dirname(parent);
+        probe = realpathSync(parent);
+    }
+    if (probe !== workDirReal && !probe.startsWith(workDirReal + sep)) {
+        throw new ProjectFilesError(403, "Path resolves outside workDir", {
+            relPath,
+        });
+    }
+    return candidate;
+}
+function computeEtag(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 12);
+}
+/** List the whitelist with stat info for present files. Never throws. */
+export function listProjectFiles(workDir) {
+    const out = [];
+    for (const rel of PROJECT_FILE_WHITELIST) {
+        let abs;
+        try {
+            abs = resolveSafe(workDir, rel);
+        }
+        catch {
+            // workDir missing or path escape — surface as "not exists" rather than
+            // erroring the whole list call (e.g. a project whose workDir was deleted
+            // on disk should still be navigable).
+            out.push({ relPath: rel, exists: false, loadedByCli: true });
+            continue;
+        }
+        if (!existsSync(abs)) {
+            out.push({ relPath: rel, exists: false, loadedByCli: true });
+            continue;
+        }
+        try {
+            const st = statSync(abs);
+            if (!st.isFile()) {
+                out.push({ relPath: rel, exists: false, loadedByCli: true });
+                continue;
+            }
+            out.push({
+                relPath: rel,
+                exists: true,
+                size: st.size,
+                mtime: st.mtime.getTime(),
+                loadedByCli: true,
+            });
+        }
+        catch {
+            out.push({ relPath: rel, exists: false, loadedByCli: true });
+        }
+    }
+    return out;
+}
+/**
+ * Read a whitelisted file. Returns content="" + etag of empty string when
+ * the file does not exist, so the editor UI can populate a blank textarea
+ * with a valid etag for first-write conflict detection.
+ */
+export function readProjectFile(workDir, relPath) {
+    if (!isWhitelistedRelPath(relPath)) {
+        throw new ProjectFilesError(400, "relPath not in whitelist", { relPath });
+    }
+    const abs = resolveSafe(workDir, relPath);
+    if (!existsSync(abs)) {
+        return { relPath, content: "", mtime: 0, etag: computeEtag("") };
+    }
+    const st = statSync(abs);
+    if (!st.isFile()) {
+        throw new ProjectFilesError(400, "Path is not a regular file", { relPath });
+    }
+    const content = readFileSync(abs, "utf-8");
+    return {
+        relPath,
+        content,
+        mtime: st.mtime.getTime(),
+        etag: computeEtag(content),
+    };
+}
+/**
+ * Atomic write: validates JSON syntax for `.json` files, ensures parent
+ * `.claude/` exists, writes to a tmp sibling, then renames. Returns the
+ * post-write content snapshot. On etag mismatch throws 409 with the current
+ * server-side content so the UI can render a 3-way diff.
+ */
+export function writeProjectFile(workDir, relPath, newContent, opts = {}) {
+    if (!isWhitelistedRelPath(relPath)) {
+        throw new ProjectFilesError(400, "relPath not in whitelist", { relPath });
+    }
+    // Optimistic-concurrency check happens BEFORE any FS mutation.
+    if (opts.ifMatchEtag !== undefined) {
+        const current = readProjectFile(workDir, relPath);
+        if (current.etag !== opts.ifMatchEtag) {
+            throw new ProjectFilesError(409, "etag mismatch", {
+                relPath,
+                currentEtag: current.etag,
+                currentContent: current.content,
+                currentMtime: current.mtime,
+            });
+        }
+    }
+    // Validate JSON before touching disk so we never leave broken settings.json.
+    if (relPath.endsWith(".json")) {
+        if (newContent.trim().length === 0) {
+            // Empty JSON → store as `{}` so the file remains valid for CLI consumers.
+            newContent = "{}\n";
+        }
+        else {
+            try {
+                JSON.parse(newContent);
+            }
+            catch (err) {
+                throw new ProjectFilesError(400, "Invalid JSON", {
+                    relPath,
+                    parseError: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    else if (relPath.endsWith(".md")) {
+        // Ensure trailing newline — POSIX text-file convention; avoids editors
+        // appending a newline on next manual edit and producing spurious diffs.
+        if (newContent.length > 0 && !newContent.endsWith("\n")) {
+            newContent = newContent + "\n";
+        }
+    }
+    const abs = resolveSafe(workDir, relPath);
+    const parent = dirname(abs);
+    if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    // tmp file lives in the same directory so rename() is atomic on the same FS.
+    // randomBytes avoids collisions if two writes race; the loser gets EEXIST on
+    // its own tmp (very unlikely) and retries via the API layer.
+    const tmp = join(parent, `.${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(tmp, newContent, "utf-8");
+    renameSync(tmp, abs);
+    const st = statSync(abs);
+    return {
+        relPath,
+        content: newContent,
+        mtime: st.mtime.getTime(),
+        etag: computeEtag(newContent),
+    };
+}
+//# sourceMappingURL=project-files.js.map

package/dist/project-files.js.map

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

package/dist/projects-fs.d.ts

@@ -0,0 +1,28 @@
+export type TaskStatus = "pending" | "in_progress" | "completed" | "cancelled";
+export interface TaskCounts {
+    pending: number;
+    in_progress: number;
+    completed: number;
+    cancelled: number;
+}
+export interface ProjectSummary {
+    encodedCwd: string;
+    workDir: string;
+    createdAt: string | null;
+    swarmCount: number;
+    taskCount: number;
+    taskCounts: TaskCounts;
+}
+export interface SwarmSummary {
+    swarmId: string;
+    teamName: string;
+    status: string;
+    roleCount: number;
+    savedAt: number | null;
+}
+export declare function listProjectDirs(home?: string): string[];
+export declare function resolveWorkDir(home: string, encodedCwd: string): string | null;
+export declare function loadProjectSummary(home: string, encodedCwd: string): ProjectSummary | null;
+export declare function loadSwarmSummaries(home: string, workDir: string): SwarmSummary[];
+export declare function listAllProjectSummaries(home?: string): ProjectSummary[];
+//# sourceMappingURL=projects-fs.d.ts.map

package/dist/projects-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects-fs.d.ts","sourceRoot":"","sources":["../src/projects-fs.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,CAAC;AAC/E,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;CACxB;AACD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAkBD,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAMvD;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAY9E;AAiBD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAkB1F;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAiBhF;AAED,wBAAgB,uBAAuB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAKvE"}

package/dist/projects-fs.js

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { TaskStore, projectRoot } from "@mclawnet/task";
+import { loadSwarmSnapshot } from "./persistence.js";
+function getHome(homeOverride) {
+    return homeOverride ?? process.env.CLAWNET_HOME ?? homedir();
+}
+function projectsDir(home) {
+    return join(home, ".clawnet", "projects");
+}
+function isSafeEncoded(encoded) {
+    if (!encoded)
+        return false;
+    if (encoded.includes("/") || encoded.includes("\\"))
+        return false;
+    if (encoded.includes("\0"))
+        return false;
+    if (encoded === "." || encoded === ".." || encoded.includes(".."))
+        return false;
+    return true;
+}
+export function listProjectDirs(home) {
+    const dir = projectsDir(getHome(home));
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+export function resolveWorkDir(home, encodedCwd) {
+    if (!isSafeEncoded(encodedCwd))
+        return null;
+    const dirs = listProjectDirs(home);
+    if (!dirs.includes(encodedCwd))
+        return null;
+    const metaPath = join(projectsDir(home), encodedCwd, "meta.json");
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+        return typeof meta.workDir === "string" ? meta.workDir : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readMetaCreatedAt(home, encodedCwd) {
+    const metaPath = join(projectsDir(home), encodedCwd, "meta.json");
+    if (!existsSync(metaPath))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
+        return meta.createdAt ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function emptyCounts() {
+    return { pending: 0, in_progress: 0, completed: 0, cancelled: 0 };
+}
+export function loadProjectSummary(home, encodedCwd) {
+    const workDir = resolveWorkDir(home, encodedCwd);
+    if (!workDir)
+        return null;
+    const store = new TaskStore({ workDir, home });
+    const tasks = store.list();
+    const counts = emptyCounts();
+    for (const t of tasks) {
+        if (t.status in counts)
+            counts[t.status] += 1;
+    }
+    const swarms = loadSwarmSummaries(home, workDir);
+    return {
+        encodedCwd,
+        workDir,
+        createdAt: readMetaCreatedAt(home, encodedCwd),
+        swarmCount: swarms.length,
+        taskCount: tasks.length,
+        taskCounts: counts,
+    };
+}
+export function loadSwarmSummaries(home, workDir) {
+    const swarmsRoot = join(projectRoot(workDir, home), "swarms");
+    if (!existsSync(swarmsRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(swarmsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const snap = loadSwarmSnapshot(workDir, entry.name);
+        if (!snap)
+            continue;
+        out.push({
+            swarmId: snap.id,
+            teamName: snap.teamName,
+            status: snap.status ?? "unknown",
+            roleCount: snap.roles?.length ?? 0,
+            savedAt: snap.savedAt ?? null,
+        });
+    }
+    return out;
+}
+export function listAllProjectSummaries(home) {
+    const h = getHome(home);
+    return listProjectDirs(h)
+        .map((e) => loadProjectSummary(h, e))
+        .filter((s) => !!s);
+}
+//# sourceMappingURL=projects-fs.js.map

package/dist/projects-fs.js.map

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

package/dist/recovery.d.ts

@@ -1,5 +1,17 @@
 import type { SwarmCoordinator } from "./swarm-coordinator.js";
 import { type SwarmSnapshot } from "./persistence.js";
 export declare function listRecoverableSwarms(): SwarmSnapshot[];
+/**
+ * Backwards-compatible recovery helper.
+ *
+ * Delegates to {@link SwarmCoordinator.recover}, which:
+ *   - respawns each role with its persisted instanceId,
+ *   - passes `claudeSessionId` through as `--resume` so per-role conversations
+ *     continue,
+ *   - drains each role's offline inbox via `inboxRelay.deliver`,
+ *   - leaves the recovered swarm in `paused` state.
+ *
+ * Older callers still pass a full snapshot — we only need its `id`.
+ */
 export declare function recoverSwarm(coordinator: SwarmCoordinator, snapshot: SwarmSnapshot): Promise<void>;
 //# sourceMappingURL=recovery.d.ts.map