@orc-brain/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/autoLoop.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Autonomous outer-loop controller (.specs/active/autonomous-loop.md §3.1, G4).
+ * Sits above the event-driven dispatch `tick`: when the orchestrator reports a
+ * run has quiesced (all tasks terminal), this decides whether the goal is
+ * satisfied (finish), needs more work (re-plan + grow the DAG), or has hit a
+ * guard (pause). It never widens a boundary on its own — safety escalations,
+ * scope boundaries, and the budget still bind (§17 design goal #3, Golden Rules).
+ *
+ * Deterministic control flow; the only LLM calls are the injected Planner
+ * (`replan`) and the {@link GoalJudge}. Runaway is bounded three ways (G5): the
+ * budget hard-stop (existing), a `max_replan_cycles` ceiling, and no-progress
+ * detection (a cycle that appends zero tasks pauses the run).
+ */
+import type { Environment, OrchestratorConfig, Plan } from "@orc-brain/shared";
+import type { Store } from "./store/index.js";
+import type { EventBus } from "./eventBus.js";
+import type { Planner } from "./planner.js";
+import type { GoalJudge } from "./goalJudge.js";
+import type { AutoLoopHook } from "./orchestrator.js";
+/** The slice of the orchestrator the controller drives (avoids a hard cycle). */
+export interface AutoLoopOrchestrator {
+    applyReplan(goalId: string, plan: Plan): {
+        scopes: {
+            id: string;
+        }[];
+        tasks: {
+            id: string;
+        }[];
+    };
+    approveScope(scopeId: string): void;
+    finalizeRun(runId: string, state: "done" | "failed", reason?: string): void;
+    parkRun(runId: string, reason: string): void;
+    tick(runId: string): Promise<void>;
+}
+/** Collaborators for the controller. */
+export interface AutoLoopDeps {
+    store: Store;
+    bus: EventBus;
+    config: OrchestratorConfig;
+    planner: Planner;
+    judge: GoalJudge;
+    orchestrator: AutoLoopOrchestrator;
+    /** Environment classifier for the judge's deterministic pass (injectable). */
+    classifyEnv?: (cwd: string) => Environment;
+}
+/** The autonomous controller (autonomous-loop.md §3.1). */
+export declare class AutoLoop implements AutoLoopHook {
+    private readonly deps;
+    /** Runs mid-cycle, so a re-entrant quiesce notification is ignored. */
+    private readonly busy;
+    /** Per-run mode override (POST /runs/:id/mode); falls back to config (G6). */
+    private readonly modeOverride;
+    constructor(deps: AutoLoopDeps);
+    /** Sets the approval mode for a specific run at runtime (G6, Phase F). */
+    setMode(runId: string, mode: "supervised" | "unattended"): void;
+    private modeFor;
+    private classifyEnv;
+    /** Orchestrator hook: a run reached quiescence. Fire-and-forget one cycle. */
+    onRunQuiesced(runId: string): void;
+    /**
+     * One evaluate → replan-or-finish cycle (autonomous-loop.md §3.1). Assumes the
+     * DAG is quiesced (the orchestrator only calls `onRunQuiesced` then).
+     */
+    private runCycle;
+    /** Goal + scope success-criteria descriptions, aggregated for the judge. */
+    private aggregateCriteria;
+    /** Digest of completed scopes' task results for the re-plan prompt (§3.3). */
+    private buildDigest;
+}
+//# sourceMappingURL=autoLoop.d.ts.map

package/dist/autoLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoLoop.d.ts","sourceRoot":"","sources":["../src/autoLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,WAAW,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,GACT;QAAE,MAAM,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QAAC,KAAK,EAAE;YAAE,EAAE,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IACzD,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,QAAQ,CAAC;IACd,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,SAAS,CAAC;IACjB,YAAY,EAAE,oBAAoB,CAAC;IACnC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,WAAW,CAAC;CAC5C;AAsBD,2DAA2D;AAC3D,qBAAa,QAAS,YAAW,YAAY;IAS/B,OAAO,CAAC,QAAQ,CAAC,IAAI;IARjC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAGzB;gBAEyB,IAAI,EAAE,YAAY;IAE/C,0EAA0E;IAC1E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,IAAI;IAI/D,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,WAAW;IAUnB,8EAA8E;IAC9E,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMlC;;;OAGG;YACW,QAAQ;IA8EtB,4EAA4E;IAC5E,OAAO,CAAC,iBAAiB;IASzB,8EAA8E;IAC9E,OAAO,CAAC,WAAW;CAapB"}

package/dist/autoLoop.js

@@ -0,0 +1,178 @@
+/**
+ * Autonomous outer-loop controller (.specs/active/autonomous-loop.md §3.1, G4).
+ * Sits above the event-driven dispatch `tick`: when the orchestrator reports a
+ * run has quiesced (all tasks terminal), this decides whether the goal is
+ * satisfied (finish), needs more work (re-plan + grow the DAG), or has hit a
+ * guard (pause). It never widens a boundary on its own — safety escalations,
+ * scope boundaries, and the budget still bind (§17 design goal #3, Golden Rules).
+ *
+ * Deterministic control flow; the only LLM calls are the injected Planner
+ * (`replan`) and the {@link GoalJudge}. Runaway is bounded three ways (G5): the
+ * budget hard-stop (existing), a `max_replan_cycles` ceiling, and no-progress
+ * detection (a cycle that appends zero tasks pauses the run).
+ */
+import { execFileSync } from "node:child_process";
+import { classifyEnvironment } from "./safety/envClassifier.js";
+/** Reads the current git branch of a directory, or undefined if not a repo. */
+function gitBranch(cwd) {
+    try {
+        return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Truncates a value to a short single-line digest string (Open Decision 3). */
+function digestLine(value, cap = 500) {
+    const s = typeof value === "string" ? value : JSON.stringify(value ?? "");
+    const oneLine = s.replace(/\s+/g, " ").trim();
+    return oneLine.length > cap ? oneLine.slice(0, cap) + "…" : oneLine;
+}
+/** The autonomous controller (autonomous-loop.md §3.1). */
+export class AutoLoop {
+    deps;
+    /** Runs mid-cycle, so a re-entrant quiesce notification is ignored. */
+    busy = new Set();
+    /** Per-run mode override (POST /runs/:id/mode); falls back to config (G6). */
+    modeOverride = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Sets the approval mode for a specific run at runtime (G6, Phase F). */
+    setMode(runId, mode) {
+        this.modeOverride.set(runId, mode);
+    }
+    modeFor(runId) {
+        const override = this.modeOverride.get(runId);
+        if (override)
+            return override;
+        // Feature-flow runs (spec 002 §R5) are unattended by default: the single
+        // human gate was the initial plan approval. Durable across restarts.
+        if (this.deps.store.getRun(runId)?.auto_loop)
+            return "unattended";
+        return this.deps.config.autoLoop.mode;
+    }
+    classifyEnv(cwd, baseBranch) {
+        if (this.deps.classifyEnv)
+            return this.deps.classifyEnv(cwd);
+        // A run with a recorded base branch classifies against it (spec 002 §R10),
+        // so worktree runs never classify as their `orc/…` branches.
+        return classifyEnvironment({ declared: "unknown", branch: baseBranch ?? gitBranch(cwd) }, this.deps.config.safety).environment;
+    }
+    /** Orchestrator hook: a run reached quiescence. Fire-and-forget one cycle. */
+    onRunQuiesced(runId) {
+        if (this.busy.has(runId))
+            return;
+        this.busy.add(runId);
+        void this.runCycle(runId).finally(() => this.busy.delete(runId));
+    }
+    /**
+     * One evaluate → replan-or-finish cycle (autonomous-loop.md §3.1). Assumes the
+     * DAG is quiesced (the orchestrator only calls `onRunQuiesced` then).
+     */
+    async runCycle(runId) {
+        const run = this.deps.store.getRun(runId);
+        if (!run || run.state !== "running")
+            return;
+        const goal = this.deps.store.getGoal(run.goal_id);
+        if (!goal)
+            return;
+        // 1. Evaluate goal satisfaction (hybrid: deterministic + judge).
+        const verdict = await this.deps.judge.evaluate({
+            run_id: runId,
+            goal_id: goal.id,
+            title: goal.title,
+            objective: goal.objective,
+            cwd: goal.repo_root,
+            environment: this.classifyEnv(goal.repo_root, run.base_branch),
+            criteria: this.aggregateCriteria(goal.id),
+        });
+        this.deps.bus.publish({
+            type: "goal_evaluated",
+            run_id: runId,
+            payload: {
+                satisfied: verdict.satisfied,
+                unmet: verdict.unmet,
+                rationale: verdict.rationale,
+            },
+        });
+        // 2. Satisfied → finish.
+        if (verdict.satisfied) {
+            this.deps.orchestrator.finalizeRun(runId, "done");
+            return;
+        }
+        // 3. Guard: re-plan cycle ceiling (G5).
+        if (run.replan_cycle >= this.deps.config.autoLoop.max_replan_cycles) {
+            this.deps.orchestrator.parkRun(runId, "cycle_cap");
+            return;
+        }
+        // 4. Re-plan to close the gap.
+        let plan;
+        try {
+            plan = await this.deps.planner.replan(goal, {
+                completedDigest: this.buildDigest(goal.id),
+                unmetCriteria: verdict.unmet,
+            });
+        }
+        catch {
+            this.deps.orchestrator.parkRun(runId, "replan_failed");
+            return;
+        }
+        const { scopes, tasks } = this.deps.orchestrator.applyReplan(goal.id, plan);
+        const nextCycle = run.replan_cycle + 1;
+        this.deps.bus.publish({
+            type: "replan_cycle",
+            run_id: runId,
+            payload: {
+                cycle: nextCycle,
+                added_scopes: scopes.length,
+                added_tasks: tasks.length,
+            },
+        });
+        // 5. Guard: no progress (G5) — a cycle that adds no work never converges.
+        if (tasks.length === 0) {
+            this.deps.orchestrator.parkRun(runId, "no_progress");
+            return;
+        }
+        this.deps.store.updateRun(runId, { replan_cycle: nextCycle });
+        // 6. Approve the new scopes per mode (G6), then resume dispatch.
+        if (this.modeFor(runId) === "unattended") {
+            for (const s of scopes)
+                this.deps.orchestrator.approveScope(s.id);
+            void this.deps.orchestrator.tick(runId);
+        }
+        else {
+            // Supervised: leave new scopes `proposed`; pause for operator approval.
+            this.deps.orchestrator.parkRun(runId, "awaiting_replan_approval");
+        }
+    }
+    /** Goal + scope success-criteria descriptions, aggregated for the judge. */
+    aggregateCriteria(goalId) {
+        const goal = this.deps.store.getGoal(goalId);
+        const criteria = (goal?.success_criteria ?? []).map((c) => c.description);
+        for (const scope of this.deps.store.listScopesByGoal(goalId)) {
+            for (const c of scope.success_criteria)
+                criteria.push(c.description);
+        }
+        return criteria;
+    }
+    /** Digest of completed scopes' task results for the re-plan prompt (§3.3). */
+    buildDigest(goalId) {
+        const lines = [];
+        for (const scope of this.deps.store.listScopesByGoal(goalId)) {
+            if (scope.status !== "done" && scope.status !== "failed")
+                continue;
+            for (const task of this.deps.store.listTasksByScope(scope.id)) {
+                if (task.result_summary == null)
+                    continue;
+                lines.push(`${scope.name}/${task.title}: ${digestLine(task.result_summary)}`);
+            }
+        }
+        return lines;
+    }
+}
+//# sourceMappingURL=autoLoop.js.map

package/dist/autoLoop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoLoop.js","sourceRoot":"","sources":["../src/autoLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAOlD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AA0BhE,+EAA+E;AAC/E,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE;YAChE,GAAG;YACH,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,SAAS,UAAU,CAAC,KAAc,EAAE,GAAG,GAAG,GAAG;IAC3C,MAAM,CAAC,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO,OAAO,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;AACtE,CAAC;AAED,2DAA2D;AAC3D,MAAM,OAAO,QAAQ;IASU;IAR7B,uEAAuE;IACtD,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC1C,8EAA8E;IAC7D,YAAY,GAAG,IAAI,GAAG,EAGpC,CAAC;IAEJ,YAA6B,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAEnD,0EAA0E;IAC1E,OAAO,CAAC,KAAa,EAAE,IAAiC;QACtD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAEO,OAAO,CAAC,KAAa;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC9C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,yEAAyE;QACzE,qEAAqE;QACrE,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,SAAS;YAAE,OAAO,YAAY,CAAC;QAClE,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;IACxC,CAAC;IAEO,WAAW,CAAC,GAAW,EAAE,UAA0B;QACzD,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC7D,2EAA2E;QAC3E,6DAA6D;QAC7D,OAAO,mBAAmB,CACxB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,IAAI,SAAS,CAAC,GAAG,CAAC,EAAE,EAC7D,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CACxB,CAAC,WAAW,CAAC;IAChB,CAAC;IAED,8EAA8E;IAC9E,aAAa,CAAC,KAAa;QACzB,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO;QACjC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrB,KAAK,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC;IAED;;;OAGG;IACK,KAAK,CAAC,QAAQ,CAAC,KAAa;QAClC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI;YAAE,OAAO;QAElB,iEAAiE;QACjE,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;YAC7C,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,EAAE,IAAI,CAAC,SAAS;YACnB,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,WAAW,CAAC;YAC9D,QAAQ,EAAE,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,CAAC;SAC1C,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YACpB,IAAI,EAAE,gBAAgB;YACtB,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B;SACF,CAAC,CAAC;QAEH,yBAAyB;QACzB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;YAClD,OAAO;QACT,CAAC;QAED,wCAAwC;QACxC,IAAI,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,EAAE,CAAC;YACpE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YACnD,OAAO;QACT,CAAC;QAED,+BAA+B;QAC/B,IAAI,IAAU,CAAC;QACf,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE;gBAC1C,eAAe,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1C,aAAa,EAAE,OAAO,CAAC,KAAK;aAC7B,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC;YACvD,OAAO;QACT,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC5E,MAAM,SAAS,GAAG,GAAG,CAAC,YAAY,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YACpB,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,KAAK;YACb,OAAO,EAAE;gBACP,KAAK,EAAE,SAAS;gBAChB,YAAY,EAAE,MAAM,CAAC,MAAM;gBAC3B,WAAW,EAAE,KAAK,CAAC,MAAM;aAC1B;SACF,CAAC,CAAC;QAEH,0EAA0E;QAC1E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC,CAAC;QAE9D,iEAAiE;QACjE,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,YAAY,EAAE,CAAC;YACzC,KAAK,MAAM,CAAC,IAAI,MAAM;gBAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClE,KAAK,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,wEAAwE;YACxE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,0BAA0B,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,4EAA4E;IACpE,iBAAiB,CAAC,MAAc;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,gBAAgB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QAC1E,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,gBAAgB;gBAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;QACvE,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,8EAA8E;IACtE,WAAW,CAAC,MAAc;QAChC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7D,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;gBAAE,SAAS;YACnE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC9D,IAAI,IAAI,CAAC,cAAc,IAAI,IAAI;oBAAE,SAAS;gBAC1C,KAAK,CAAC,IAAI,CACR,GAAG,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAClE,CAAC;YACJ,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/backpressure.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Rate-limit backpressure (§7.4). Turns a detected {@link LimitSignal} into a
+ * scheduling constraint: a session/weekly/unknown limit pauses *all* dispatch
+ * until the reset; a per-model limit only quarantines that model (router R7
+ * routes around it). Reset times are used when the CLI text carried one,
+ * otherwise an exponential backoff with a cap. Engage/clear are surfaced as
+ * `limit.backpressure` events with a countdown for the UI/CLI.
+ */
+import type { LimitConfig, ModelName } from "@orc-brain/shared";
+import type { EventBus } from "./eventBus.js";
+import { type LimitSignal } from "./safety/limitSignals.js";
+/** Scheduler-facing rate-limit state for one orchestrator. */
+export declare class Backpressure {
+    private readonly bus;
+    private readonly config;
+    private readonly now;
+    private global;
+    private readonly models;
+    /** Consecutive limit hits, for backoff escalation when no reset is parsed. */
+    private consecutive;
+    /** Re-kick the dispatch loop when a hold expires. */
+    onClear?: (runId: string) => void;
+    private readonly timers;
+    constructor(bus: EventBus, config: LimitConfig, now?: () => number);
+    /** Engages backpressure for a detected signal, scheduling its auto-clear. */
+    engage(signal: LimitSignal, runId: string): void;
+    /** True when all new dispatch must halt (global hold active). */
+    isDispatchBlocked(): boolean;
+    /** Models currently quarantined by a per-model limit (router R7 input). */
+    quarantinedModels(): ModelName[];
+    /** Epoch ms the global hold clears at, if any (for status/countdown). */
+    globalResetsAt(): number | undefined;
+    /** Cancels all pending timers (shutdown). */
+    stopAll(): void;
+    private schedule;
+    private emit;
+}
+//# sourceMappingURL=backpressure.d.ts.map

package/dist/backpressure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backpressure.d.ts","sourceRoot":"","sources":["../src/backpressure.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAkB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAQ5E,8DAA8D;AAC9D,qBAAa,YAAY;IAUrB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXtB,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,8EAA8E;IAC9E,OAAO,CAAC,WAAW,CAAK;IACxB,qDAAqD;IACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4C;gBAGhD,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,WAAW,EACnB,GAAG,GAAE,MAAM,MAAyB;IAGvD,6EAA6E;IAC7E,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAkChD,iEAAiE;IACjE,iBAAiB,IAAI,OAAO;IAS5B,2EAA2E;IAC3E,iBAAiB,IAAI,SAAS,EAAE;IAUhC,yEAAyE;IACzE,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC,6CAA6C;IAC7C,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,IAAI;CAab"}

package/dist/backpressure.js

@@ -0,0 +1,103 @@
+/**
+ * Rate-limit backpressure (§7.4). Turns a detected {@link LimitSignal} into a
+ * scheduling constraint: a session/weekly/unknown limit pauses *all* dispatch
+ * until the reset; a per-model limit only quarantines that model (router R7
+ * routes around it). Reset times are used when the CLI text carried one,
+ * otherwise an exponential backoff with a cap. Engage/clear are surfaced as
+ * `limit.backpressure` events with a countdown for the UI/CLI.
+ */
+import { backoffDelayMs } from "./safety/limitSignals.js";
+/** Scheduler-facing rate-limit state for one orchestrator. */
+export class Backpressure {
+    bus;
+    config;
+    now;
+    global = null;
+    models = new Map();
+    /** Consecutive limit hits, for backoff escalation when no reset is parsed. */
+    consecutive = 0;
+    /** Re-kick the dispatch loop when a hold expires. */
+    onClear;
+    timers = new Set();
+    constructor(bus, config, now = () => Date.now()) {
+        this.bus = bus;
+        this.config = config;
+        this.now = now;
+    }
+    /** Engages backpressure for a detected signal, scheduling its auto-clear. */
+    engage(signal, runId) {
+        const t = this.now();
+        const until = signal.resets_at && signal.resets_at > t
+            ? signal.resets_at
+            : t + backoffDelayMs(this.consecutive++, this.config);
+        const delay = Math.max(0, until - t);
+        if (signal.kind === "model_limit" && signal.model) {
+            this.models.set(signal.model, { until, reason: signal.raw });
+            this.emit(true, "model", signal.raw, until, signal.model);
+            this.schedule(delay, () => {
+                this.models.delete(signal.model);
+                this.emit(false, "model", "model limit cleared", undefined, signal.model);
+                this.onClear?.(runId);
+            });
+        }
+        else {
+            this.global = { until, reason: signal.raw };
+            this.emit(true, "global", signal.raw, until);
+            this.schedule(delay, () => {
+                this.global = null;
+                this.consecutive = 0;
+                this.emit(false, "global", "backpressure cleared");
+                this.onClear?.(runId);
+            });
+        }
+    }
+    /** True when all new dispatch must halt (global hold active). */
+    isDispatchBlocked() {
+        if (!this.global)
+            return false;
+        if (this.global.until <= this.now()) {
+            this.global = null;
+            return false;
+        }
+        return true;
+    }
+    /** Models currently quarantined by a per-model limit (router R7 input). */
+    quarantinedModels() {
+        const t = this.now();
+        const out = [];
+        for (const [model, hold] of this.models) {
+            if (hold.until > t)
+                out.push(model);
+            else
+                this.models.delete(model);
+        }
+        return out;
+    }
+    /** Epoch ms the global hold clears at, if any (for status/countdown). */
+    globalResetsAt() {
+        return this.global?.until;
+    }
+    /** Cancels all pending timers (shutdown). */
+    stopAll() {
+        for (const t of this.timers)
+            clearTimeout(t);
+        this.timers.clear();
+    }
+    schedule(delayMs, fn) {
+        const timer = setTimeout(() => {
+            this.timers.delete(timer);
+            fn();
+        }, delayMs);
+        if (typeof timer.unref === "function")
+            timer.unref();
+        this.timers.add(timer);
+    }
+    emit(engaged, scope, reason, resetsAt, model) {
+        this.bus.publish({
+            type: "limit.backpressure",
+            run_id: null,
+            payload: { engaged, scope, model, reason, resets_at: resetsAt },
+        });
+    }
+}
+//# sourceMappingURL=backpressure.js.map

package/dist/backpressure.js.map

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

package/dist/budgetTracker.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Usage & budget tracker (§7). This is an *estimator plus a backpressure
+ * system*, not a meter: under subscription auth `total_cost_usd` is an
+ * estimated USD-equivalent, not a billed amount. It provides (a) relative
+ * consumption per run/scope/task, (b) a spend-equivalent ceiling, and (c)
+ * graceful reaction to real rate-limit signals (handled in limitSignals).
+ */
+import type { BudgetConfig, BudgetState } from "@orc-brain/shared";
+import type { Store } from "./store/index.js";
+import type { EventBus } from "./eventBus.js";
+/** The subset of an SDK result message the ledger needs (§7.1). */
+export interface ResultUsageLike {
+    total_cost_usd?: number;
+    num_turns?: number;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
+    } | null;
+}
+/** Computes the budget state from spend against thresholds (§7.3). */
+export declare function computeBudgetState(spent: number, budget: number, config: BudgetConfig): BudgetState;
+/**
+ * Per-task hard bound (§7.2, Open Decision 6): scope budget ÷ task count,
+ * clamped to `[per_task_min_usd, per_task_max_usd]`. Passed to the worker as
+ * the SDK `maxBudgetUsd` option.
+ */
+export declare function perTaskBudgetUsd(scopeBudgetUsd: number, taskCount: number, config: BudgetConfig): number;
+/** Ledger recorder + threshold enforcer for a single run. */
+export declare class BudgetTracker {
+    private readonly store;
+    private readonly bus;
+    private readonly config;
+    constructor(store: Store, bus: EventBus, config: BudgetConfig);
+    /**
+     * Records one result message to the ledger (one row per message — the source
+     * of truth for aggregation, §7.1), recomputes the run's spend and budget
+     * state, and emits `budget.tick`. Returns the new budget state.
+     */
+    recordResult(args: {
+        run_id: string;
+        task_id: string;
+        session_id: string | null;
+        model: string;
+        result: ResultUsageLike;
+    }): BudgetState;
+    /** Recomputes spend + state for a run from the ledger and emits a tick (§7.3). */
+    refresh(runId: string): BudgetState;
+    /** True when dispatch must halt because the run hit the hard stop (§7.3). */
+    isStopped(runId: string): boolean;
+}
+//# sourceMappingURL=budgetTracker.d.ts.map

package/dist/budgetTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budgetTracker.d.ts","sourceRoot":"","sources":["../src/budgetTracker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QACN,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,uBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,2BAA2B,CAAC,EAAE,MAAM,CAAC;KACtC,GAAG,IAAI,CAAC;CACV;AAED,sEAAsE;AACtE,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,GACnB,WAAW,CAMb;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,MAAM,CAMR;AAED,6DAA6D;AAC7D,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAFN,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,YAAY;IAGvC;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,eAAe,CAAC;KACzB,GAAG,WAAW;IAuBf,kFAAkF;IAClF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW;IAuBnC,6EAA6E;IAC7E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAIlC"}

package/dist/budgetTracker.js

@@ -0,0 +1,93 @@
+/**
+ * Usage & budget tracker (§7). This is an *estimator plus a backpressure
+ * system*, not a meter: under subscription auth `total_cost_usd` is an
+ * estimated USD-equivalent, not a billed amount. It provides (a) relative
+ * consumption per run/scope/task, (b) a spend-equivalent ceiling, and (c)
+ * graceful reaction to real rate-limit signals (handled in limitSignals).
+ */
+/** Computes the budget state from spend against thresholds (§7.3). */
+export function computeBudgetState(spent, budget, config) {
+    if (budget <= 0)
+        return "ok";
+    const frac = spent / budget;
+    if (frac >= config.hard_stop_at)
+        return "stopped";
+    if (frac >= config.warn_at)
+        return "warn";
+    return "ok";
+}
+/**
+ * Per-task hard bound (§7.2, Open Decision 6): scope budget ÷ task count,
+ * clamped to `[per_task_min_usd, per_task_max_usd]`. Passed to the worker as
+ * the SDK `maxBudgetUsd` option.
+ */
+export function perTaskBudgetUsd(scopeBudgetUsd, taskCount, config) {
+    const raw = taskCount > 0 ? scopeBudgetUsd / taskCount : scopeBudgetUsd;
+    return Math.min(config.per_task_max_usd, Math.max(config.per_task_min_usd, raw));
+}
+/** Ledger recorder + threshold enforcer for a single run. */
+export class BudgetTracker {
+    store;
+    bus;
+    config;
+    constructor(store, bus, config) {
+        this.store = store;
+        this.bus = bus;
+        this.config = config;
+    }
+    /**
+     * Records one result message to the ledger (one row per message — the source
+     * of truth for aggregation, §7.1), recomputes the run's spend and budget
+     * state, and emits `budget.tick`. Returns the new budget state.
+     */
+    recordResult(args) {
+        const u = args.result.usage ?? {};
+        this.store.insertLedgerEntry({
+            run_id: args.run_id,
+            task_id: args.task_id,
+            session_id: args.session_id,
+            cost_usd: args.result.total_cost_usd ?? 0,
+            num_turns: args.result.num_turns ?? 0,
+            model: args.model,
+            tokens_in: u.input_tokens ?? 0,
+            tokens_out: u.output_tokens ?? 0,
+            cache_read: u.cache_read_input_tokens ?? 0,
+            cache_write: u.cache_creation_input_tokens ?? 0,
+            recorded_at: new Date().toISOString(),
+        });
+        // Roll the task's own cost forward too, for per-task display.
+        const taskCost = this.store.sumCostForTask(args.task_id);
+        this.store.updateTask(args.task_id, { cost_usd: taskCost });
+        return this.refresh(args.run_id);
+    }
+    /** Recomputes spend + state for a run from the ledger and emits a tick (§7.3). */
+    refresh(runId) {
+        const run = this.store.getRun(runId);
+        if (!run)
+            return "ok";
+        const spent = this.store.sumCostForRun(runId);
+        const state = computeBudgetState(spent, run.budget_usd, this.config);
+        this.store.updateRun(runId, {
+            budget_spent_usd: spent,
+            budget_state: state,
+        });
+        this.bus.publish({
+            type: "budget.tick",
+            run_id: runId,
+            payload: {
+                budget_usd: run.budget_usd,
+                spent_usd: spent,
+                state,
+                warn_at: this.config.warn_at,
+                stop_at: this.config.hard_stop_at,
+            },
+        });
+        return state;
+    }
+    /** True when dispatch must halt because the run hit the hard stop (§7.3). */
+    isStopped(runId) {
+        const run = this.store.getRun(runId);
+        return run?.budget_state === "stopped";
+    }
+}
+//# sourceMappingURL=budgetTracker.js.map

package/dist/budgetTracker.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Default orchestrator configuration (§6, §7, §8). These are the recommended
+ * defaults from §14; `orchestrator.toml` overrides land in Phase 2. Values are
+ * exported so the router, budget tracker, and safety layer share one source.
+ */
+import type { OrchestratorConfig } from "@orc-brain/shared";
+/** Recommended defaults (§14: concurrency 3, warn 70%, hard-stop 90%). */
+export declare const DEFAULT_CONFIG: OrchestratorConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,0EAA0E;AAC1E,eAAO,MAAM,cAAc,EAAE,kBAmG5B,CAAC"}