@mclawnet/swarm 0.1.12 → 0.1.14

package/dist/__tests__/workspace-types.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+describe("WorkspaceProvider types", () => {
+    it("WorkspaceHandle has the expected shape (compile-time + runtime sanity)", () => {
+        const h = {
+            swarmId: "s1",
+            projectRoot: "/proj",
+            strategy: "git-worktree",
+            cwd: "/proj/.worktrees/s1",
+            metadata: { repoRoot: "/proj", baseCommit: "abc123", branchName: "clawnet/swarm-s1" },
+        };
+        expect(h.strategy).toBe("git-worktree");
+        expect(h.metadata.branchName).toBe("clawnet/swarm-s1");
+    });
+    it("WorkspaceStrategy union admits both variants", () => {
+        const a = "git-worktree";
+        const b = "snapshot-copy";
+        expect([a, b]).toHaveLength(2);
+    });
+    it("WorkspaceProvider interface enforces the four members", () => {
+        // Compile-time only: this fake implementation must satisfy the interface.
+        const fake = {
+            id: "git-worktree",
+            priority: 1,
+            isApplicable: async () => true,
+            prepare: async (input) => ({
+                swarmId: input.swarmId,
+                projectRoot: input.projectRoot,
+                strategy: "git-worktree",
+                cwd: "/x",
+                metadata: {},
+            }),
+            dispose: async () => { },
+        };
+        expect(fake.id).toBe("git-worktree");
+    });
+});
+//# sourceMappingURL=workspace-types.test.js.map

package/dist/__tests__/workspace-types.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-types.test.js","sourceRoot":"","sources":["../../src/__tests__/workspace-types.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAG9C,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,wEAAwE,EAAE,GAAG,EAAE;QAChF,MAAM,CAAC,GAAoB;YACzB,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,OAAO;YACpB,QAAQ,EAAE,cAAc;YACxB,GAAG,EAAE,qBAAqB;YAC1B,QAAQ,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,kBAAkB,EAAE;SACtF,CAAC;QACF,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACxC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,CAAC,GAAsB,cAAc,CAAC;QAC5C,MAAM,CAAC,GAAsB,eAAe,CAAC;QAC7C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,0EAA0E;QAC1E,MAAM,IAAI,GAAsB;YAC9B,EAAE,EAAE,cAAc;YAClB,QAAQ,EAAE,CAAC;YACX,YAAY,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;YAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;gBACzB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,QAAQ,EAAE,cAAc;gBACxB,GAAG,EAAE,IAAI;gBACT,QAAQ,EAAE,EAAE;aACb,CAAC;YACF,OAAO,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;SACxB,CAAC;QACF,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/worktree-gc.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worktree-gc.test.d.ts.map

package/dist/__tests__/worktree-gc.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-gc.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/worktree-gc.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/worktree-gc.test.js

@@ -0,0 +1,183 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync, existsSync, utimesSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { projectRoot } from "@mclawnet/task";
+import { gcWorktrees, DEFAULT_WORKTREE_GC_AGE_MS } from "../always-on/worktree-gc.js";
+let WORK;
+let HOME;
+beforeEach(() => {
+    WORK = mkdtempSync(join(tmpdir(), "wgc-work-"));
+    HOME = mkdtempSync(join(tmpdir(), "wgc-home-"));
+    mkdirSync(join(WORK, ".worktrees"), { recursive: true });
+});
+afterEach(() => {
+    try {
+        rmSync(WORK, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+    try {
+        rmSync(HOME, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+});
+/** Create a fake worktree dir with one file; back-date its mtime by `ageMs`. */
+function seedWorktree(name, ageMs, fileBytes = 100) {
+    const dir = join(WORK, ".worktrees", name);
+    mkdirSync(dir, { recursive: true });
+    const fp = join(dir, "fake-file.txt");
+    writeFileSync(fp, "x".repeat(fileBytes));
+    const past = new Date(Date.now() - ageMs);
+    utimesSync(dir, past, past);
+    utimesSync(fp, past, past);
+    return dir;
+}
+/** Create a swarm snapshot at the conventional path with `status`. */
+function seedSnapshot(swarmId, status) {
+    const dir = join(projectRoot(WORK, HOME), "swarms", swarmId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "recovery.json"), JSON.stringify({ id: swarmId, workDir: WORK, status }));
+}
+describe("gcWorktrees (PR-B Sub-PR-B4)", () => {
+    it("retains active swarms regardless of age", async () => {
+        // An old dir but its swarm is still running → must NOT delete
+        seedWorktree("active-old", 48 * 3600 * 1000); // 48h ago
+        seedSnapshot("active-old", "running");
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.scanned).toBe(1);
+        expect(r.removed).toBe(0);
+        expect(r.retained).toBe(1);
+        expect(r.decisions[0]).toMatchObject({ name: "active-old", action: "retained-active" });
+        expect(existsSync(join(WORK, ".worktrees", "active-old"))).toBe(true);
+    });
+    it("retains young dirs (within 24h debug window) even when swarm is terminal", async () => {
+        seedWorktree("young-failed", 1 * 3600 * 1000); // 1h ago
+        seedSnapshot("young-failed", "failed");
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.removed).toBe(0);
+        expect(r.retained).toBe(1);
+        expect(r.decisions[0].action).toBe("retained-young");
+        expect(existsSync(join(WORK, ".worktrees", "young-failed"))).toBe(true);
+    });
+    it("removes old dirs whose swarm is terminal (completed/failed/cancelled)", async () => {
+        seedWorktree("old-completed", 48 * 3600 * 1000);
+        seedSnapshot("old-completed", "completed");
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.removed).toBe(1);
+        expect(r.retained).toBe(0);
+        expect(r.decisions[0].action).toBe("removed");
+        expect(existsSync(join(WORK, ".worktrees", "old-completed"))).toBe(false);
+    });
+    it("removes old dirs with NO matching snapshot at all (snapshot already cleaned up)", async () => {
+        seedWorktree("orphan-old", 48 * 3600 * 1000);
+        // No snapshot seeded — coordinator already evicted it
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.removed).toBe(1);
+        expect(existsSync(join(WORK, ".worktrees", "orphan-old"))).toBe(false);
+    });
+    it("treats paused as ACTIVE (D14 runner will promote it next tick)", async () => {
+        seedWorktree("paused-old", 48 * 3600 * 1000);
+        seedSnapshot("paused-old", "paused");
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.removed).toBe(0);
+        expect(r.retained).toBe(1);
+        expect(r.decisions[0].action).toBe("retained-active");
+    });
+    it("scans + reaps multiple entries without touching worktree contents", async () => {
+        // PR-B follow-up — replaces the original "reports total bytes" case.
+        // Size telemetry was deleted because the recursive readdirSync/statSync
+        // walk it required pegged the agent at 99% CPU for ~15min per tick
+        // when worktrees contained node_modules (~70k files each). The reap
+        // decision only needs scanned/removed/retained — never the byte total.
+        seedWorktree("a-active", 1000, 200);
+        seedSnapshot("a-active", "running");
+        seedWorktree("b-removed", 48 * 3600 * 1000, 500);
+        seedSnapshot("b-removed", "completed");
+        seedWorktree("c-young", 1000, 300);
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.scanned).toBe(3);
+        expect(r.removed).toBe(1);
+        expect(r.retained).toBe(2);
+        // Size telemetry intentionally absent — re-introducing it MUST NOT
+        // walk worktree contents. See the doc comment at the top of
+        // worktree-gc.ts. Type-level + runtime double guard: ts-expect-error
+        // catches the regression at `tsc` time (no need to run vitest),
+        // toHaveProperty catches it at runtime in case someone adds the
+        // field via index signature / Record cast.
+        // @ts-expect-error — totalBytesBefore intentionally removed; see worktree-gc.ts header
+        void r.totalBytesBefore;
+        // @ts-expect-error — totalBytesAfter intentionally removed; see worktree-gc.ts header
+        void r.totalBytesAfter;
+        // @ts-expect-error — decisions[i].bytes intentionally removed; see worktree-gc.ts header
+        void r.decisions[0].bytes;
+        expect(r).not.toHaveProperty("totalBytesBefore");
+        expect(r).not.toHaveProperty("totalBytesAfter");
+        expect(r.decisions[0]).not.toHaveProperty("bytes");
+    });
+    it("dryRun=true counts but doesn't actually delete", async () => {
+        seedWorktree("dry-old", 48 * 3600 * 1000);
+        seedSnapshot("dry-old", "completed");
+        const r = gcWorktrees({ workDir: WORK, home: HOME, dryRun: true });
+        expect(r.removed).toBe(1);
+        expect(r.decisions[0].action).toBe("removed");
+        // BUT the dir still exists
+        expect(existsSync(join(WORK, ".worktrees", "dry-old"))).toBe(true);
+    });
+    it("no .worktrees/ dir → empty result, no error", () => {
+        const fresh = mkdtempSync(join(tmpdir(), "wgc-empty-"));
+        try {
+            const r = gcWorktrees({ workDir: fresh, home: HOME });
+            expect(r.scanned).toBe(0);
+            expect(r.removed).toBe(0);
+            expect(r.retained).toBe(0);
+            expect(r.decisions).toEqual([]);
+        }
+        finally {
+            rmSync(fresh, { recursive: true, force: true });
+        }
+    });
+    it("default maxAgeMs is 24h", () => {
+        expect(DEFAULT_WORKTREE_GC_AGE_MS).toBe(24 * 60 * 60 * 1000);
+    });
+    // PR-B follow-up regression — the original safeDirBytes walked every
+    // file under every worktree synchronously, including node_modules. In
+    // production this issued ~1M sync stat syscalls per tick, pegged the
+    // agent at 99% CPU for ~15min, and froze the Node event loop (silent
+    // log, agent_timeout from hub, InboxWatcher fs.watch never fires,
+    // swarm_complete_request stays delivered=false). The fix deleted the
+    // recursive walker entirely. This test pins that door shut: even when
+    // a worktree contains a fake node_modules tree, the result shape MUST
+    // NOT carry per-entry byte counts. Anyone re-introducing the walker
+    // would have to re-add the fields too, which fails the structural
+    // assertions below.
+    it("retains heavy worktree without exposing per-entry byte fields", () => {
+        const wtName = "fake-heavy";
+        const wtDir = join(WORK, ".worktrees", wtName);
+        mkdirSync(wtDir, { recursive: true });
+        seedSnapshot(wtName, "running"); // mark active → retained-active branch
+        // Realistic-shape fake node_modules under the worktree: 200 files
+        // across 20 sub-dirs. Detail doesn't matter to the assertion — it's
+        // here purely to fail-fast if any code re-adds a recursive walker
+        // that would inflate per-tick wall clock.
+        const nm = join(wtDir, "node_modules");
+        for (let i = 0; i < 20; i++) {
+            const pkg = join(nm, `pkg-${i}`);
+            mkdirSync(pkg, { recursive: true });
+            for (let j = 0; j < 10; j++) {
+                writeFileSync(join(pkg, `f-${j}.js`), "x".repeat(50));
+            }
+        }
+        const r = gcWorktrees({ workDir: WORK, home: HOME });
+        expect(r.scanned).toBe(1);
+        expect(r.retained).toBe(1);
+        expect(r.decisions[0].action).toBe("retained-active");
+        // The structural guard: byte counts are gone. If a future change
+        // re-introduces safeDirBytes (or any sync recursive walk over
+        // worktree contents), it'll need to add these fields back AND
+        // update consumers — these assertions force the conversation.
+        expect(r).not.toHaveProperty("totalBytesBefore");
+        expect(r).not.toHaveProperty("totalBytesAfter");
+        expect(r.decisions[0]).not.toHaveProperty("bytes");
+    });
+});
+//# sourceMappingURL=worktree-gc.test.js.map

package/dist/__tests__/worktree-gc.test.js.map

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

package/dist/always-on/activity-reader.d.ts

@@ -0,0 +1,27 @@
+import type { AlwaysOnActivityRecord } from "@mclawnet/shared";
+export interface ReadActivityOptions {
+    /** Clamped to [1, 500] by readAlwaysOnActivity. Default 100. */
+    limit?: number;
+    /** Default 0. */
+    skip?: number;
+    /** Optional filter on tick decision. */
+    decision?: "fired" | "skipped" | "halted";
+}
+export interface ReadActivityResult {
+    ticks: AlwaysOnActivityRecord[];
+    hasMore: boolean;
+    /** Total count AFTER decision filter, BEFORE pagination. */
+    total: number;
+}
+/**
+ * Parse the always-on.log file under <projectRoot> and return a paginated
+ * newest-first slice.
+ *
+ * Tolerant by design:
+ *   - Missing file → empty result (NOT an error).
+ *   - Blank lines → skipped.
+ *   - JSON.parse errors → that line is skipped (NOT thrown), so a single
+ *     corrupt line never 500s the endpoint.
+ */
+export declare function readAlwaysOnActivity(workDir: string, home: string, opts?: ReadActivityOptions): ReadActivityResult;
+//# sourceMappingURL=activity-reader.d.ts.map

package/dist/always-on/activity-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-reader.d.ts","sourceRoot":"","sources":["../../src/always-on/activity-reader.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAI/D,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,QAAQ,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAKD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,mBAAwB,GAC7B,kBAAkB,CAuCpB"}

package/dist/always-on/activity-reader.js

@@ -0,0 +1,95 @@
+// Always-on activity log reader (M9 t1).
+//
+// Pure read-path over `<projectRoot>/always-on.log` (JSONL, one tick per
+// line). Written by AlwaysOnManager.appendLog; this module never touches
+// the writer. Returns wire-shape records (AlwaysOnActivityRecord) so the
+// Hub REST layer can pass them through verbatim.
+//
+// Known limitations (MVP):
+//   - Reads only `always-on.log`; the rotated `.log.1` backup is ignored.
+//   - Whole-file read + reverse: fine at ≤10MB cap; revisit if cap grows.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { projectRoot } from "@mclawnet/task";
+const LOG_FILENAME = "always-on.log";
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 500;
+/**
+ * Parse the always-on.log file under <projectRoot> and return a paginated
+ * newest-first slice.
+ *
+ * Tolerant by design:
+ *   - Missing file → empty result (NOT an error).
+ *   - Blank lines → skipped.
+ *   - JSON.parse errors → that line is skipped (NOT thrown), so a single
+ *     corrupt line never 500s the endpoint.
+ */
+export function readAlwaysOnActivity(workDir, home, opts = {}) {
+    const limit = clampLimit(opts.limit);
+    const skip = Math.max(0, Math.floor(opts.skip ?? 0));
+    const decision = opts.decision;
+    const path = join(projectRoot(workDir, home), LOG_FILENAME);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        if (err?.code === "ENOENT") {
+            return { ticks: [], hasMore: false, total: 0 };
+        }
+        throw err;
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            // Corrupt line — skip silently. Don't fail the whole read.
+            continue;
+        }
+        if (!isActivityRecord(parsed))
+            continue;
+        if (decision && parsed.decision !== decision)
+            continue;
+        records.push(parsed);
+    }
+    // Newest-first. JSONL is append-only chronological, so reversing is enough.
+    records.reverse();
+    const total = records.length;
+    const slice = records.slice(skip, skip + limit);
+    const hasMore = skip + slice.length < total;
+    return { ticks: slice, hasMore, total };
+}
+function clampLimit(input) {
+    if (input == null || !Number.isFinite(input))
+        return DEFAULT_LIMIT;
+    const n = Math.floor(input);
+    if (n < 1)
+        return 1;
+    if (n > MAX_LIMIT)
+        return MAX_LIMIT;
+    return n;
+}
+function isActivityRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const obj = value;
+    if (typeof obj.at !== "string")
+        return false;
+    if (obj.decision !== "fired" &&
+        obj.decision !== "skipped" &&
+        obj.decision !== "halted") {
+        return false;
+    }
+    if (!Array.isArray(obj.gateBreakdown))
+        return false;
+    if (typeof obj.durationMs !== "number")
+        return false;
+    return true;
+}
+//# sourceMappingURL=activity-reader.js.map

package/dist/always-on/activity-reader.js.map

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

package/dist/always-on/always-on-manager.d.ts

@@ -0,0 +1,170 @@
+import type { AlwaysOnSnapshot, AlwaysOnTickRecord } from "@mclawnet/shared";
+import { WorkCycleRunner, type TaskRef } from "./workcycle-runner.js";
+import type { TaskSource } from "./task-sources/types.js";
+import type { TaskStore } from "@mclawnet/task";
+import { type AlwaysOnConfig, type AlwaysOnPersistedConfig } from "./config.js";
+import type { SwarmCoordinator } from "../swarm-coordinator.js";
+export interface AlwaysOnManagerOptions {
+    home: string;
+    swarmCoordinator: SwarmCoordinator;
+    /**
+     * Picks the next task for a given project; null = nothing actionable.
+     * Backwards-compat (M7) single-source DI. When `taskSources` is also
+     * provided the cascade picker takes precedence — `pickNextTask` is then
+     * ignored, but kept in the type for callers that still pass it.
+     */
+    pickNextTask?: (projectRoot: string) => Promise<TaskRef | null>;
+    /**
+     * M8.0 cascade source list. When provided the manager builds a
+     * CascadePicker over these sources and wires it into the runner with the
+     * source lifecycle hooks active. When omitted, falls back to the M7
+     * single-source `pickNextTask` DI above (or a TaskStore-backed source
+     * when `taskStore` is provided).
+     */
+    taskSources?: TaskSource[];
+    /**
+     * Convenience: when neither `pickNextTask` nor `taskSources` is provided
+     * but a TaskStore factory is, the manager auto-wraps it into a default
+     * single-source cascade. Lets the agent pass just the store factory and
+     * get the same picking behaviour as M7.
+     */
+    taskStore?: (projectRoot: string) => TaskStore | undefined;
+    /** Optional clock injection for tests. */
+    now?: () => Date;
+    /** Override the user-active window (tests). */
+    userActiveWindowMs?: number;
+    /** Override the log rotation byte cap (tests). */
+    logRotateBytes?: number;
+    /**
+     * Construct a WorkCycleRunner. Defaults to a real runner bound to the
+     * shared SwarmCoordinator + provided pickNextTask. Test-only override.
+     */
+    runnerFactory?: (workDir: string) => WorkCycleRunner;
+}
+export declare class AlwaysOnManager {
+    private readonly home;
+    private readonly swarmCoordinator;
+    private readonly pickNextTask;
+    private readonly cascadePicker;
+    /**
+     * R3 I-B — kept around so `drainPending(workDir)` can iterate sources
+     * BEFORE the cascade runs each tick. The cascade picker itself only
+     * exposes filtered-pick semantics; the drain must bypass the filter so
+     * a source whose toggle was flipped off mid-flight still gets to reap
+     * its in-flight work.
+     */
+    private readonly taskSources;
+    private readonly now;
+    private readonly userActiveWindowMs;
+    private readonly logRotateBytes;
+    private readonly runnerFactory?;
+    private readonly entries;
+    constructor(opts: AlwaysOnManagerOptions);
+    /**
+     * Boot (or rebuild) the scheduler for one project. Loads config from disk;
+     * restores ticksToday/lastFireAt when the persisted date matches today; if
+     * mode === "off", the scheduler is created but left stopped (cheap, lets
+     * `applyConfig` flip the switch later without re-instantiating).
+     *
+     * Idempotent: calling start() twice for the same project rebuilds; the old
+     * scheduler is stopped first to avoid duplicate timers.
+     */
+    start(workDir: string): Promise<void>;
+    /** Stop the scheduler for a project and drop the entry. Idempotent. */
+    stop(workDir: string): Promise<void>;
+    /**
+     * Returns the live snapshot serialised to the wire format (Date → ISO),
+     * or null when no scheduler is booted for the project.
+     */
+    snapshot(workDir: string): AlwaysOnSnapshot | null;
+    /**
+     * Re-sync the live scheduler with whatever's on disk right now (M7.3).
+     * The M7.2 projects-handler already does load→merge→save, then calls our
+     * hook with the new config. Rather than re-doing the persistence here we
+     * just pull the canonical state off disk and push it into the scheduler.
+     * Auto-boots if the project never started; idempotent otherwise.
+     */
+    refreshFromDisk(workDir: string): Promise<void>;
+    /**
+     * Apply a config patch: merges over the persisted baseline, writes it back,
+     * updates the live scheduler in place. Auto-boots the scheduler when the
+     * project has never been started (UI may flip a mode on a fresh project).
+     *
+     * Returns the merged config and the post-update snapshot so callers can
+     * hand both back to the UI in one round trip.
+     */
+    applyConfig(workDir: string, patch: Omit<Partial<AlwaysOnConfig>, "pausedUntil"> & {
+        pausedUntil?: string | null;
+        lastIntrospectionAt?: string | null;
+        lastIntrospectionRejected?: boolean | null;
+        pendingIntrospectionSwarmId?: string | null;
+        pendingIntrospectionWorkspaceCwd?: string | null;
+    }): Promise<{
+        config: AlwaysOnPersistedConfig;
+        snapshot: AlwaysOnSnapshot;
+    }>;
+    /**
+     * Record agent activity for the userActive gate. S1 hotfix: scoped per
+     * project. Pass `workDir` to update one project only; omit (or pass null)
+     * to broadcast to every entry — preserves the old global behaviour for
+     * callers that can't resolve a workDir from an inbound hub frame.
+     */
+    recordActivity(workDir?: string | null): void;
+    /**
+     * B6 — force a tick immediately, clearing the per-project userActive
+     * timestamp first so the gate cascade doesn't skip on "user active <30min
+     * ago". Dev-only entrypoint: the hub gates the corresponding HTTP route on
+     * `NODE_ENV !== "production"` so this never reaches the agent in prod.
+     *
+     * Returns the TickRecord (decision + gateBreakdown + durationMs) and the
+     * post-tick snapshot in one call so the caller can show in dev tooling
+     * whether the force-tick fired or still skipped (e.g. on a real
+     * pausedUntil that genuinely should block).
+     *
+     * Note: only `lastActivityAt` is cleared. Other gates (pausedUntil,
+     * dailyBudget) intentionally still apply — force-tick is for bypassing
+     * the "I'm typing, don't fire" UX gate, not the user's explicit pause or
+     * the daily budget. Throws when no scheduler is booted for the project.
+     */
+    forceTick(workDir: string): Promise<{
+        record: AlwaysOnTickRecord;
+        snapshot: AlwaysOnSnapshot;
+    }>;
+    /** Stop every per-project scheduler. Called on agent shutdown. */
+    disposeAll(): Promise<void>;
+    /**
+     * R3 I-B — public test/ops hook. Invokes `drainPending(workDir)` on every
+     * TaskSource that defines it, regardless of whether its toggle is on. This
+     * is the same drain that runs automatically inside `onFire` before each
+     * tick; exposed publicly so:
+     *   - tests can simulate "user toggled off mid-flight → next tick reaps
+     *     cleanly" without driving the scheduler timer, and
+     *   - future ops surfaces (admin reseed, manual reconcile) can request a
+     *     drain pass without firing a work cycle.
+     * Failures inside a single source are logged and swallowed — one source's
+     * drain must not break the manager's tick loop.
+     */
+    drainAllSources(workDir: string): Promise<void>;
+    /**
+     * Hotfix C1 — map a TaskSource onto its taskSources toggle flag and
+     * resolve against the project's persisted config. Unknown source names
+     * default to enabled so non-standard sources (e.g. tests, future M9
+     * sources not yet listed in `AlwaysOnTaskSourcesConfig`) aren't silently
+     * dropped. Called fresh per pick by the cascade picker filter, so toggling
+     * a source on/off in the UI takes effect on the very next tick — no
+     * scheduler/picker rebuild required (the JSON read is cheap compared to a
+     * swarm spawn).
+     */
+    private isSourceEnabledForProject;
+    /** User-facing gates: pausedUntil + userActive. */
+    private buildGates;
+    /**
+     * Persist ticksToday/lastFireAt AND append a jsonl line to always-on.log.
+     * Hooked into DiscoveryScheduler.onTick so every fired / skipped / halted
+     * decision is captured. Best-effort — write failures are logged but never
+     * thrown back into the scheduler tick loop.
+     */
+    private onTick;
+    private appendLog;
+}
+//# sourceMappingURL=always-on-manager.d.ts.map

package/dist/always-on/always-on-manager.d.ts.map

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