@femtomc/mu-orchestrator 26.2.70 → 26.2.71

package/dist/dag_reconcile.d.ts

@@ -0,0 +1,62 @@
+import { type Issue, type ValidationResult } from "@femtomc/mu-core";
+export type DagRootPhase = "active" | "waiting_review" | "refining" | "done";
+export declare const DAG_ROOT_PHASE_TAG_PREFIX = "loop:";
+export type DagReconcileDecision = {
+    kind: "root_final";
+    validation: ValidationResult;
+} | {
+    kind: "reopen_retryable";
+    issue: Issue;
+    reason: string;
+} | {
+    kind: "dispatch_leaf";
+    issue: Issue;
+} | {
+    kind: "dispatch_reviewer";
+    issue: Issue;
+    round: number;
+} | {
+    kind: "enter_waiting_review";
+    reason: string;
+    round: number;
+} | {
+    kind: "review_accept";
+    issue: Issue;
+    round: number;
+} | {
+    kind: "review_refine";
+    issue: Issue;
+    round: number;
+    reason: string;
+} | {
+    kind: "review_budget_exhausted";
+    issue: Issue;
+    round: number;
+    max_rounds: number;
+} | {
+    kind: "resume_active";
+    reason: string;
+} | {
+    kind: "repair_deadlock";
+    reason: string;
+};
+export type DagReconcileOpts = {
+    issues: readonly Issue[];
+    rootId: string;
+    attemptsByIssueId?: ReadonlyMap<string, number>;
+    maxReorchestrationAttempts?: number;
+    maxRefineRoundsPerRoot?: number;
+    dispatchTags?: readonly string[];
+};
+/**
+ * Deterministic intra-root reconcile selector.
+ *
+ * This function is intentionally side-effect free: it inspects one DAG snapshot and computes the
+ * next orchestrator action. The caller is responsible for applying effects and then reconciling
+ * again against a refreshed snapshot.
+ */
+export declare const DAG_RECONCILE_ENGINE_INVARIANTS: readonly ["ORCH-DAG-RECON-001: one snapshot in -> one deterministic next action out.", "ORCH-DAG-RECON-002: retryable reopen decisions are budget-aware and derived from DAG primitives.", "ORCH-DAG-RECON-003: root finality is checked before dispatch in non-retry paths.", "ORCH-DAG-RECON-004: leaf dispatch selection is delegated to deterministic core ready-leaf primitives.", "ORCH-DAG-RECON-005: review loop is explicit: active -> waiting_review -> (done | refining).", "ORCH-DAG-RECON-006: refine loops are deterministically budgeted per root."];
+export declare function rootPhaseFromTags(tags: readonly string[]): DagRootPhase;
+export declare function withRootPhaseTag(tags: readonly string[], phase: DagRootPhase): string[];
+export declare function reconcileDagTurn(opts: DagReconcileOpts): DagReconcileDecision;
+//# sourceMappingURL=dag_reconcile.d.ts.map

package/dist/dag_reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag_reconcile.d.ts","sourceRoot":"","sources":["../src/dag_reconcile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,KAAK,KAAK,EAAE,KAAK,gBAAgB,EAAe,MAAM,kBAAkB,CAAC;AAEvH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,gBAAgB,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7E,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAUjD,MAAM,MAAM,oBAAoB,GAC7B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,UAAU,EAAE,gBAAgB,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,yBAAyB,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACpF;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,MAAM,MAAM,gBAAgB,GAAG;IAC9B,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,qiBAOlC,CAAC;AAqEX,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAWvE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,CAGvF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,oBAAoB,CA0H7E"}

package/dist/dag_reconcile.js

@@ -0,0 +1,210 @@
+import { readyLeaves, retryableDagCandidates, validateDag } from "@femtomc/mu-core";
+export const DAG_ROOT_PHASE_TAG_PREFIX = "loop:";
+const ROOT_PHASES = new Set(["active", "waiting_review", "refining", "done"]);
+const REVIEWER_ROLE_TAG = "role:reviewer";
+const REVIEW_ROUND_TAG_PREFIX = "review:round:";
+const ACCEPT_OUTCOMES = new Set(["accept", "success"]);
+const REFINE_OUTCOMES = new Set(["failure", "needs_work", "refine"]);
+const DEFAULT_DISPATCH_TAGS = ["node:agent"];
+const DEFAULT_MAX_REFINE_ROUNDS = 3;
+/**
+ * Deterministic intra-root reconcile selector.
+ *
+ * This function is intentionally side-effect free: it inspects one DAG snapshot and computes the
+ * next orchestrator action. The caller is responsible for applying effects and then reconciling
+ * again against a refreshed snapshot.
+ */
+export const DAG_RECONCILE_ENGINE_INVARIANTS = [
+    "ORCH-DAG-RECON-001: one snapshot in -> one deterministic next action out.",
+    "ORCH-DAG-RECON-002: retryable reopen decisions are budget-aware and derived from DAG primitives.",
+    "ORCH-DAG-RECON-003: root finality is checked before dispatch in non-retry paths.",
+    "ORCH-DAG-RECON-004: leaf dispatch selection is delegated to deterministic core ready-leaf primitives.",
+    "ORCH-DAG-RECON-005: review loop is explicit: active -> waiting_review -> (done | refining).",
+    "ORCH-DAG-RECON-006: refine loops are deterministically budgeted per root.",
+];
+function normalizeOutcome(outcome) {
+    if (typeof outcome !== "string") {
+        return null;
+    }
+    const normalized = outcome.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : null;
+}
+function compareByCreatedThenId(a, b) {
+    if (a.created_at !== b.created_at) {
+        return a.created_at - b.created_at;
+    }
+    return a.id.localeCompare(b.id);
+}
+function reviewRound(issue) {
+    for (const tag of issue.tags) {
+        if (!tag.startsWith(REVIEW_ROUND_TAG_PREFIX)) {
+            continue;
+        }
+        const raw = tag.slice(REVIEW_ROUND_TAG_PREFIX.length).trim();
+        if (!/^\d+$/.test(raw)) {
+            continue;
+        }
+        return Math.max(1, Number.parseInt(raw, 10));
+    }
+    return null;
+}
+function compareReviewerIssues(a, b) {
+    const ar = reviewRound(a);
+    const br = reviewRound(b);
+    if (ar != null || br != null) {
+        if (ar == null) {
+            return -1;
+        }
+        if (br == null) {
+            return 1;
+        }
+        if (ar !== br) {
+            return ar - br;
+        }
+    }
+    return compareByCreatedThenId(a, b);
+}
+function hasParentDep(issue, parentId) {
+    return issue.deps.some((dep) => dep.type === "parent" && dep.target === parentId);
+}
+function isReviewerIssue(issue) {
+    return issue.tags.includes(REVIEWER_ROLE_TAG);
+}
+function reviewerIssuesForRoot(issues, rootId) {
+    return issues
+        .filter((issue) => isReviewerIssue(issue) && hasParentDep(issue, rootId))
+        .sort(compareReviewerIssues);
+}
+function normalizeMaxRefineRounds(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return Math.max(1, Math.trunc(value));
+    }
+    return DEFAULT_MAX_REFINE_ROUNDS;
+}
+export function rootPhaseFromTags(tags) {
+    for (const tag of tags) {
+        if (!tag.startsWith(DAG_ROOT_PHASE_TAG_PREFIX)) {
+            continue;
+        }
+        const candidate = tag.slice(DAG_ROOT_PHASE_TAG_PREFIX.length);
+        if (ROOT_PHASES.has(candidate)) {
+            return candidate;
+        }
+    }
+    return "active";
+}
+export function withRootPhaseTag(tags, phase) {
+    const withoutPhase = tags.filter((tag) => !tag.startsWith(DAG_ROOT_PHASE_TAG_PREFIX));
+    return [...withoutPhase, `${DAG_ROOT_PHASE_TAG_PREFIX}${phase}`];
+}
+export function reconcileDagTurn(opts) {
+    const root = opts.issues.find((issue) => issue.id === opts.rootId) ?? null;
+    const rootPhase = rootPhaseFromTags(root?.tags ?? []);
+    const reviewerIssues = reviewerIssuesForRoot(opts.issues, opts.rootId);
+    const latestReviewer = reviewerIssues.length > 0 ? reviewerIssues[reviewerIssues.length - 1] : null;
+    const latestReviewRound = latestReviewer ? (reviewRound(latestReviewer) ?? reviewerIssues.length) : 0;
+    const nextReviewRound = latestReviewRound > 0 ? latestReviewRound + 1 : 1;
+    const maxRefineRounds = normalizeMaxRefineRounds(opts.maxRefineRoundsPerRoot);
+    const refineRoundsUsed = reviewerIssues.filter((issue) => {
+        if (issue.status !== "closed") {
+            return false;
+        }
+        const outcome = normalizeOutcome(issue.outcome);
+        return outcome != null && REFINE_OUTCOMES.has(outcome);
+    }).length;
+    if (rootPhase === "refining") {
+        return {
+            kind: "resume_active",
+            reason: "review_requested_refinement",
+        };
+    }
+    if (rootPhase === "waiting_review") {
+        if (!latestReviewer) {
+            return {
+                kind: "enter_waiting_review",
+                reason: "reviewer_missing",
+                round: nextReviewRound,
+            };
+        }
+        if (latestReviewer.status === "open") {
+            return {
+                kind: "dispatch_reviewer",
+                issue: latestReviewer,
+                round: latestReviewRound,
+            };
+        }
+        if (latestReviewer.status === "in_progress") {
+            return {
+                kind: "repair_deadlock",
+                reason: `reviewer in_progress: ${latestReviewer.id}`,
+            };
+        }
+        const outcome = normalizeOutcome(latestReviewer.outcome);
+        if (outcome != null && ACCEPT_OUTCOMES.has(outcome)) {
+            return {
+                kind: "review_accept",
+                issue: latestReviewer,
+                round: latestReviewRound,
+            };
+        }
+        if (refineRoundsUsed > maxRefineRounds) {
+            return {
+                kind: "review_budget_exhausted",
+                issue: latestReviewer,
+                round: latestReviewRound,
+                max_rounds: maxRefineRounds,
+            };
+        }
+        return {
+            kind: "review_refine",
+            issue: latestReviewer,
+            round: latestReviewRound,
+            reason: `outcome=${outcome ?? "null"}`,
+        };
+    }
+    if (rootPhase === "done") {
+        const validation = validateDag(opts.issues, opts.rootId);
+        if (validation.is_final) {
+            return { kind: "root_final", validation };
+        }
+        return {
+            kind: "resume_active",
+            reason: "done_phase_not_final",
+        };
+    }
+    const retryable = retryableDagCandidates(opts.issues, {
+        root_id: opts.rootId,
+        attempts_by_issue_id: opts.attemptsByIssueId,
+        max_attempts: opts.maxReorchestrationAttempts,
+    }).filter((entry) => !isReviewerIssue(entry.issue));
+    if (retryable.length > 0) {
+        const target = retryable[0];
+        return {
+            kind: "reopen_retryable",
+            issue: target.issue,
+            reason: target.reason,
+        };
+    }
+    const validation = validateDag(opts.issues, opts.rootId);
+    if (validation.is_final) {
+        return {
+            kind: "enter_waiting_review",
+            reason: validation.reason,
+            round: nextReviewRound,
+        };
+    }
+    const ready = readyLeaves(opts.issues, {
+        root_id: opts.rootId,
+        tags: opts.dispatchTags ?? DEFAULT_DISPATCH_TAGS,
+    }).filter((issue) => !isReviewerIssue(issue));
+    if (ready.length === 0) {
+        return {
+            kind: "repair_deadlock",
+            reason: validation.reason,
+        };
+    }
+    return {
+        kind: "dispatch_leaf",
+        issue: ready[0],
+    };
+}

package/dist/dag_runner.d.ts

@@ -3,6 +3,31 @@ import { type EventLog } from "@femtomc/mu-core/node";
 import type { ForumStore } from "@femtomc/mu-forum";
 import type { IssueStore } from "@femtomc/mu-issue";
 import type { ModelOverrides } from "./model_resolution.js";
+/**
+ * Default-on orchestration reconcile contract for `DagRunner`.
+ *
+ * The orchestration redesign is the default behavior (no feature-flag fork). Compatibility adapters
+ * are allowed only if they preserve the same durable state transitions and emitted events.
+ */
+export type DagRunnerReconcilePhase = "turn_start" | "unstick_retryable" | "validate_root" | "select_leaf" | "dispatch_issue" | "repair_deadlock" | "postcondition_reconcile" | "requeue_retryable" | "turn_end";
+/** Review/refinement control loop that reconcile implementations must honor. */
+export type DagRunnerReviewLoopPhase = "plan" | "execute" | "review" | "accept" | "refine";
+/**
+ * Enumerated invariants (kept implementation-facing so tests can assert these explicitly).
+ */
+export declare const DAG_RUNNER_CONTRACT_INVARIANTS: readonly ["ORCH-RECON-001: Reconcile is default-on and must not branch behind rollout flags.", "ORCH-RECON-002: At most one issue is claimed+dispatched per reconcile step for a root.", "ORCH-RECON-003: A dispatched issue must end closed; otherwise the runner force-closes with outcome=failure.", "ORCH-RECON-004: failure/needs_work outcomes may be retried only up to the per-issue attempt budget (currently 3).", "ORCH-RECON-005: Root finality check (`validate(root).is_final`) runs before dispatch each step.", "ORCH-RECON-006: Review loop semantics are plan -> execute -> review -> (accept | refine).", "ORCH-RECON-007: Refine loops are budgeted (default max_refine_rounds_per_root=3); exhaustion is terminal.", "ORCH-RECON-008: Compatibility adapters may exist in-place, but must preserve this state machine and events."];
+/** Default refine-loop budget for upcoming reviewer integration modules. */
+export declare const DEFAULT_MAX_REFINE_ROUNDS_PER_ROOT = 3;
+/**
+ * Reviewer semantics contract:
+ * - accept => review step closes with `success`; root can move to terminal validation
+ * - refine => review step closes with `refine` (or legacy `needs_work`), then orchestrator schedules follow-up work
+ */
+export declare const REVIEW_DECISION_TO_OUTCOME: {
+    readonly accept: "success";
+    readonly refine: "refine";
+};
+export declare const DAG_RUNNER_BUDGET_INVARIANTS: readonly ["ORCH-BUDGET-001: max_steps is a hard upper bound on reconcile turns per run invocation.", "ORCH-BUDGET-002: per-issue re-orchestration attempts are capped at 3.", "ORCH-BUDGET-003: reviewer refine rounds are capped per root (default 3)."];
 export type DagResult = {
     status: "root_final" | "no_executable_leaf" | "max_steps_exhausted" | "error";
     steps: number;
@@ -49,7 +74,23 @@ export declare class DagRunner {
         backend?: BackendRunner;
         events?: EventLog;
         modelOverrides?: ModelOverrides;
+        maxRefineRoundsPerRoot?: number;
     });
+    /**
+     * Reconcile entrypoint for one root DAG.
+     *
+     * Turn state machine (default path, no rollout flag branch):
+     *   turn_start
+     *     -> unstick_retryable
+     *     -> validate_root
+     *     -> select_leaf
+     *        -> (none) repair_deadlock -> turn_end
+     *        -> (leaf) dispatch_issue -> postcondition_reconcile -> requeue_retryable -> turn_end
+     *
+     * Reviewer/refinement loop contract:
+     *   plan -> execute -> review -> (accept | refine)
+     *   refine -> execute (after orchestrator persists follow-up executable work)
+     */
     run(rootId: string, maxSteps?: number, opts?: DagRunnerRunOpts): Promise<DagResult>;
 }
 export {};

package/dist/dag_runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dag_runner.d.ts","sourceRoot":"","sources":["../src/dag_runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAA8D,MAAM,mBAAmB,CAAC;AAEnH,OAAO,EAEN,KAAK,QAAQ,EAKb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAGjF,MAAM,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,YAAY,GAAG,oBAAoB,GAAG,qBAAqB,GAAG,OAAO,CAAC;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC5B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,KAAK,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAIF,KAAK,iBAAiB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AAwBF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAIvE;AAED,qBAAa,SAAS;;gBAYpB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,aAAa,CAAC;QAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;QAAC,cAAc,CAAC,EAAE,cAAc,CAAA;KAAO;IAoLrF,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC;CAiNjG"}
+{"version":3,"file":"dag_runner.d.ts","sourceRoot":"","sources":["../src/dag_runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAA8D,MAAM,mBAAmB,CAAC;AAEnH,OAAO,EAEN,KAAK,QAAQ,EAKb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,uBAAuB,CAAC;AAGjF;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAChC,YAAY,GACZ,mBAAmB,GACnB,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,iBAAiB,GACjB,yBAAyB,GACzB,mBAAmB,GACnB,UAAU,CAAC;AAEd,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3F;;GAEG;AACH,eAAO,MAAM,8BAA8B,0zBASjC,CAAC;AAEX,4EAA4E;AAC5E,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;CAG7B,CAAC;AAEX,eAAO,MAAM,4BAA4B,2PAI/B,CAAC;AAQX,MAAM,MAAM,SAAS,GAAG;IACvB,MAAM,EAAE,YAAY,GAAG,oBAAoB,GAAG,qBAAqB,GAAG,OAAO,CAAC;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC5B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,qBAAqB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,yBAAyB,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,KAAK,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAIF,KAAK,iBAAiB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC;AA4CF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAIvE;AAED,qBAAa,SAAS;;gBAapB,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE;QACL,OAAO,CAAC,EAAE,aAAa,CAAC;QACxB,MAAM,CAAC,EAAE,QAAQ,CAAC;QAClB,cAAc,CAAC,EAAE,cAAc,CAAC;QAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;KAC3B;IAuMP;;;;;;;;;;;;;;OAcG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,SAAS,CAAC;CA6VjG"}

package/dist/dag_runner.js

@@ -2,7 +2,42 @@ import { mkdir } from "node:fs/promises";
 import { join, relative } from "node:path";
 import { SdkBackend, roleFromTags, systemPromptForRole } from "@femtomc/mu-agent";
 import { currentRunId, fsEventLogFromRepoRoot, getStorePaths, newRunId, runContext, } from "@femtomc/mu-core/node";
+import { reconcileDagTurn, withRootPhaseTag } from "./dag_reconcile.js";
 import { resolveModelConfig } from "./model_resolution.js";
+/**
+ * Enumerated invariants (kept implementation-facing so tests can assert these explicitly).
+ */
+export const DAG_RUNNER_CONTRACT_INVARIANTS = [
+    "ORCH-RECON-001: Reconcile is default-on and must not branch behind rollout flags.",
+    "ORCH-RECON-002: At most one issue is claimed+dispatched per reconcile step for a root.",
+    "ORCH-RECON-003: A dispatched issue must end closed; otherwise the runner force-closes with outcome=failure.",
+    "ORCH-RECON-004: failure/needs_work outcomes may be retried only up to the per-issue attempt budget (currently 3).",
+    "ORCH-RECON-005: Root finality check (`validate(root).is_final`) runs before dispatch each step.",
+    "ORCH-RECON-006: Review loop semantics are plan -> execute -> review -> (accept | refine).",
+    "ORCH-RECON-007: Refine loops are budgeted (default max_refine_rounds_per_root=3); exhaustion is terminal.",
+    "ORCH-RECON-008: Compatibility adapters may exist in-place, but must preserve this state machine and events.",
+];
+/** Default refine-loop budget for upcoming reviewer integration modules. */
+export const DEFAULT_MAX_REFINE_ROUNDS_PER_ROOT = 3;
+/**
+ * Reviewer semantics contract:
+ * - accept => review step closes with `success`; root can move to terminal validation
+ * - refine => review step closes with `refine` (or legacy `needs_work`), then orchestrator schedules follow-up work
+ */
+export const REVIEW_DECISION_TO_OUTCOME = {
+    accept: "success",
+    refine: "refine",
+};
+export const DAG_RUNNER_BUDGET_INVARIANTS = [
+    "ORCH-BUDGET-001: max_steps is a hard upper bound on reconcile turns per run invocation.",
+    "ORCH-BUDGET-002: per-issue re-orchestration attempts are capped at 3.",
+    "ORCH-BUDGET-003: reviewer refine rounds are capped per root (default 3).",
+];
+const MAX_REORCHESTRATION_ATTEMPTS = 3;
+const REVIEWER_ROLE_TAG = "role:reviewer";
+const ORCHESTRATOR_ROLE_TAG = "role:orchestrator";
+const REVIEWER_ACCEPT_OUTCOMES = new Set(["accept", "success"]);
+const REVIEWER_REFINE_OUTCOMES = new Set(["failure", "needs_work", "refine"]);
 function roundTo(n, digits) {
     const f = 10 ** digits;
     return Math.round(n * f) / f;
@@ -23,6 +58,24 @@ function normalizeSelfMetadataValue(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : "unknown";
 }
+function normalizeOutcome(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : null;
+}
+function sameTags(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i += 1) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
 export function renderAgentSelfMetadata(meta) {
     const model = normalizeSelfMetadataValue(meta.model);
     const thinkingLevel = normalizeSelfMetadataValue(meta.thinkingLevel);
@@ -35,6 +88,7 @@ export class DagRunner {
     #events;
     #backend;
     #modelOverrides;
+    #maxRefineRoundsPerRoot;
     #reorchestrateOutcomes = new Set(["failure", "needs_work"]);
     #attempts = new Map();
     constructor(store, forum, repoRoot, opts = {}) {
@@ -44,6 +98,7 @@ export class DagRunner {
         this.#events = opts.events ?? fsEventLogFromRepoRoot(repoRoot);
         this.#backend = opts.backend ?? new SdkBackend();
         this.#modelOverrides = opts.modelOverrides ?? {};
+        this.#maxRefineRoundsPerRoot = Math.max(1, Math.trunc(opts.maxRefineRoundsPerRoot ?? DEFAULT_MAX_REFINE_ROUNDS_PER_ROOT));
     }
     async #resolveConfig() {
         return resolveModelConfig(this.#modelOverrides);
@@ -121,10 +176,14 @@ export class DagRunner {
         if (!before) {
             return;
         }
+        const tagsWithoutRole = before.tags.filter((t) => !t.startsWith("role:"));
+        const tagsWithAgent = tagsWithoutRole.includes("node:agent")
+            ? tagsWithoutRole
+            : [...tagsWithoutRole, "node:agent"];
         const reopened = await this.#store.update(issueId, {
             status: "open",
             outcome: null,
-            tags: [...before.tags.filter((t) => !t.startsWith("role:")), "role:orchestrator"],
+            tags: [...tagsWithAgent, ORCHESTRATOR_ROLE_TAG],
         });
         await this.#events.emit("dag.unstick.reopen", {
             source: "dag_runner",
@@ -139,49 +198,72 @@ export class DagRunner {
             reason: opts.reason,
         }), "orchestrator");
     }
-    async #maybeUnstick(rootId, step) {
-        const idsInScope = new Set(await this.#store.subtree_ids(rootId));
-        const rows = await this.#store.list();
-        // Build children mapping once.
-        const childrenOf = new Map();
-        for (const row of rows) {
-            for (const dep of row.deps ?? []) {
-                if (dep.type !== "parent")
-                    continue;
-                const list = childrenOf.get(dep.target) ?? [];
-                list.push(row);
-                childrenOf.set(dep.target, list);
-            }
+    async #setRootPhase(rootId, phase) {
+        const root = await this.#store.get(rootId);
+        if (!root) {
+            return null;
         }
-        const hasOpenChildren = (issueId) => (childrenOf.get(issueId) ?? []).some((child) => child.status !== "closed");
-        const candidates = [];
-        for (const row of rows) {
-            if (!idsInScope.has(row.id))
-                continue;
-            if (row.status !== "closed")
-                continue;
-            // Circuit breaker: skip issues that have exhausted their attempts.
-            if ((this.#attempts.get(row.id) ?? 0) >= 3)
-                continue;
-            const outcome = row.outcome;
-            if (outcome && this.#reorchestrateOutcomes.has(outcome)) {
-                if (hasOpenChildren(row.id))
-                    continue;
-                candidates.push(row);
-                continue;
-            }
-            if (outcome === "expanded" && (childrenOf.get(row.id)?.length ?? 0) === 0) {
-                candidates.push(row);
+        const nextTags = withRootPhaseTag(root.tags, phase);
+        if (sameTags(root.tags, nextTags)) {
+            return root;
+        }
+        return await this.#store.update(rootId, { tags: nextTags });
+    }
+    async #ensureReviewerIssue(rootId, round, step, rows) {
+        const hasParent = (issue) => issue.deps.some((dep) => dep.type === "parent" && dep.target === rootId);
+        const pending = rows
+            .filter((issue) => issue.tags.includes(REVIEWER_ROLE_TAG) && hasParent(issue) && issue.status !== "closed")
+            .sort((a, b) => {
+            if (a.created_at !== b.created_at) {
+                return a.created_at - b.created_at;
             }
+            return a.id.localeCompare(b.id);
+        })
+            .pop();
+        if (pending) {
+            return pending;
         }
-        if (candidates.length === 0) {
-            return false;
+        const root = rows.find((row) => row.id === rootId) ?? null;
+        if (!root) {
+            return null;
         }
-        candidates.sort((a, b) => (a.priority ?? 3) - (b.priority ?? 3));
-        const target = candidates[0];
-        await this.#reopenForOrchestration(target.id, { reason: `was outcome=${target.outcome}`, step });
-        return true;
+        const created = await this.#store.create(`Review round ${round}: ${root.title}`, {
+            body: `Review the completed execution for root ${rootId}.\n\n` +
+                `Close with outcome=success to accept, or outcome=refine/needs_work to request follow-up worker work.\n` +
+                `Do not create child issues; refinement scheduling is orchestrator-owned.`,
+            tags: ["node:agent", REVIEWER_ROLE_TAG, `review:round:${round}`],
+            priority: Math.max(1, (root.priority ?? 3) - 1),
+        });
+        await this.#store.add_dep(created.id, "parent", rootId);
+        await this.#events.emit("dag.review.issue_created", {
+            source: "dag_runner",
+            issueId: rootId,
+            payload: { root_id: rootId, step, round, review_issue_id: created.id },
+        });
+        await this.#forum.post(`issue:${rootId}`, JSON.stringify({
+            step,
+            issue_id: rootId,
+            type: "review_requested",
+            round,
+            review_issue_id: created.id,
+        }), "orchestrator");
+        return created;
     }
+    /**
+     * Reconcile entrypoint for one root DAG.
+     *
+     * Turn state machine (default path, no rollout flag branch):
+     *   turn_start
+     *     -> unstick_retryable
+     *     -> validate_root
+     *     -> select_leaf
+     *        -> (none) repair_deadlock -> turn_end
+     *        -> (leaf) dispatch_issue -> postcondition_reconcile -> requeue_retryable -> turn_end
+     *
+     * Reviewer/refinement loop contract:
+     *   plan -> execute -> review -> (accept | refine)
+     *   refine -> execute (after orchestrator persists follow-up executable work)
+     */
     async run(rootId, maxSteps = 20, opts = {}) {
         const hooks = opts.hooks;
         const runId = currentRunId() ?? newRunId();
@@ -195,31 +277,144 @@ export class DagRunner {
             try {
                 for (let i = 0; i < maxSteps; i++) {
                     const step = i + 1;
-                    // 0. Unstick: failures / needs_work trigger re-orchestration.
-                    await this.#maybeUnstick(rootId, step);
-                    // 2. Check termination.
-                    const v = await this.#store.validate(rootId);
-                    if (v.is_final) {
+                    const rows = await this.#store.list();
+                    const decision = reconcileDagTurn({
+                        issues: rows,
+                        rootId,
+                        attemptsByIssueId: this.#attempts,
+                        maxReorchestrationAttempts: MAX_REORCHESTRATION_ATTEMPTS,
+                        maxRefineRoundsPerRoot: this.#maxRefineRoundsPerRoot,
+                        dispatchTags: ["node:agent"],
+                    });
+                    if (decision.kind === "reopen_retryable") {
+                        await this.#reopenForOrchestration(decision.issue.id, {
+                            reason: decision.reason,
+                            step,
+                        });
+                        continue;
+                    }
+                    if (decision.kind === "enter_waiting_review") {
+                        const phased = await this.#setRootPhase(rootId, "waiting_review");
+                        if (!phased) {
+                            final = { status: "error", steps: step, error: "root vanished" };
+                            return final;
+                        }
+                        const reviewIssue = await this.#ensureReviewerIssue(rootId, decision.round, step, rows);
+                        if (!reviewIssue) {
+                            final = { status: "error", steps: step, error: "review_issue_create_failed" };
+                            return final;
+                        }
+                        await this.#events.emit("dag.review.waiting", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: {
+                                root_id: rootId,
+                                step,
+                                round: decision.round,
+                                review_issue_id: reviewIssue.id,
+                                reason: decision.reason,
+                            },
+                        });
+                        continue;
+                    }
+                    if (decision.kind === "review_accept") {
+                        await this.#setRootPhase(rootId, "done");
+                        await this.#store.update(rootId, { status: "closed", outcome: "success" });
+                        await this.#events.emit("dag.review.accept", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: { root_id: rootId, step, round: decision.round, review_issue_id: decision.issue.id },
+                        });
+                        await this.#forum.post(`issue:${rootId}`, JSON.stringify({
+                            step,
+                            issue_id: rootId,
+                            type: "review_accept",
+                            round: decision.round,
+                            review_issue_id: decision.issue.id,
+                        }), "orchestrator");
+                        continue;
+                    }
+                    if (decision.kind === "review_refine") {
+                        await this.#setRootPhase(rootId, "refining");
+                        const normalized = normalizeOutcome(decision.issue.outcome);
+                        if (normalized !== REVIEW_DECISION_TO_OUTCOME.refine) {
+                            await this.#store.update(decision.issue.id, { outcome: REVIEW_DECISION_TO_OUTCOME.refine });
+                        }
+                        await this.#events.emit("dag.review.refine", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: {
+                                root_id: rootId,
+                                step,
+                                round: decision.round,
+                                review_issue_id: decision.issue.id,
+                                reason: decision.reason,
+                            },
+                        });
+                        await this.#forum.post(`issue:${rootId}`, JSON.stringify({
+                            step,
+                            issue_id: rootId,
+                            type: "review_refine",
+                            round: decision.round,
+                            review_issue_id: decision.issue.id,
+                            reason: decision.reason,
+                        }), "orchestrator");
+                        continue;
+                    }
+                    if (decision.kind === "review_budget_exhausted") {
+                        await this.#setRootPhase(rootId, "done");
+                        await this.#store.update(rootId, { status: "closed", outcome: "budget_exhausted" });
+                        await this.#events.emit("dag.review.budget_exhausted", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: {
+                                root_id: rootId,
+                                step,
+                                round: decision.round,
+                                max_rounds: decision.max_rounds,
+                                review_issue_id: decision.issue.id,
+                            },
+                        });
+                        final = {
+                            status: "error",
+                            steps: step,
+                            error: `review_budget_exhausted:${decision.max_rounds}`,
+                        };
+                        return final;
+                    }
+                    if (decision.kind === "resume_active") {
+                        await this.#setRootPhase(rootId, "active");
+                        await this.#reopenForOrchestration(rootId, {
+                            reason: decision.reason,
+                            step,
+                        });
+                        await this.#events.emit("dag.review.resume_active", {
+                            source: "dag_runner",
+                            issueId: rootId,
+                            payload: { root_id: rootId, step, reason: decision.reason },
+                        });
+                        continue;
+                    }
+                    if (decision.kind === "root_final") {
                         final = { status: "root_final", steps: i, error: "" };
                         return final;
                     }
-                    // 3. Select next ready leaf.
-                    const candidates = await this.#store.ready(rootId, { tags: ["node:agent"] });
-                    if (candidates.length === 0) {
-                        // Repair pass on the root to resolve deadlocks / bad expansions.
+                    if (decision.kind === "repair_deadlock") {
+                        // repair_deadlock phase: run orchestrator on root to create executable leaf work.
                         await this.#events.emit("dag.unstick.start", {
                             source: "dag_runner",
                             issueId: rootId,
                             payload: { root_id: rootId, step },
                         });
-                        const rootIssue = await this.#store.get(rootId);
+                        const rootIssue = rows.find((row) => row.id === rootId) ?? null;
                         if (!rootIssue) {
                             final = { status: "error", steps: i, error: "root vanished" };
                             return final;
                         }
                         const idsInScope = new Set(await this.#store.subtree_ids(rootId));
-                        const openIssues = (await this.#store.list({ status: "open" })).filter((r) => idsInScope.has(r.id));
+                        const openIssues = rows.filter((row) => idsInScope.has(row.id) && row.status === "open");
                         const diag = `- open_issues: ${openIssues.length}\n` +
+                            `- reconcile_reason: ${decision.reason}\n` +
                             `- action: diagnose deadlocks or missing expansions and create executable leaf work\n` +
                             `- hint: run \`mu issues ready --root ${rootId}\` and \`mu issues list --root ${rootId}\`\n`;
                         const repairIssue = {
@@ -251,7 +446,7 @@ export class DagRunner {
                         });
                         continue;
                     }
-                    const issue = candidates[0];
+                    const issue = decision.issue;
                     const issueId = issue.id;
                     const role = roleFromTags(issue.tags);
                     await this.#events.emit("dag.step.start", {
@@ -262,7 +457,7 @@ export class DagRunner {
                     if (hooks?.onStepStart) {
                         await hooks.onStepStart({ rootId, step, issueId, role, title: issue.title ?? "" });
                     }
-                    // 3. Claim.
+                    // dispatch_issue: claim leaf
                     await this.#events.emit("dag.claim", {
                         source: "dag_runner",
                         issueId,
@@ -272,7 +467,7 @@ export class DagRunner {
                     // Track attempt count for circuit breaker.
                     const attempt = (this.#attempts.get(issueId) ?? 0) + 1;
                     this.#attempts.set(issueId, attempt);
-                    // 4. Route + 5. Render + 6. Execute.
+                    // dispatch_issue: resolve model + execute backend
                     const cfg = await this.#resolveConfig();
                     const logSuffix = attempt > 1 ? `attempt-${attempt}` : "";
                     const onBackendLine = hooks?.onBackendLine;
@@ -283,7 +478,7 @@ export class DagRunner {
                             ? (line) => onBackendLine({ rootId, step, issueId, logSuffix, line })
                             : undefined,
                     });
-                    // 7. Check postconditions.
+                    // postcondition_reconcile
                     let updated = await this.#store.get(issueId);
                     if (!updated) {
                         final = { status: "error", steps: step, error: "issue vanished" };
@@ -297,7 +492,20 @@ export class DagRunner {
                         });
                         updated = await this.#store.close(issueId, "failure");
                     }
-                    // 8. Log to forum.
+                    if (role === "reviewer") {
+                        const normalized = normalizeOutcome(updated.outcome);
+                        let canonicalOutcome = null;
+                        if (normalized && REVIEWER_ACCEPT_OUTCOMES.has(normalized)) {
+                            canonicalOutcome = REVIEW_DECISION_TO_OUTCOME.accept;
+                        }
+                        else if (normalized && REVIEWER_REFINE_OUTCOMES.has(normalized)) {
+                            canonicalOutcome = REVIEW_DECISION_TO_OUTCOME.refine;
+                        }
+                        if (canonicalOutcome && updated.outcome !== canonicalOutcome) {
+                            updated = await this.#store.update(issueId, { outcome: canonicalOutcome });
+                        }
+                    }
+                    // turn_end: persist execution record
                     await this.#forum.post(`issue:${issueId}`, JSON.stringify({
                         step,
                         issue_id: issueId,
@@ -327,9 +535,9 @@ export class DagRunner {
                             outcome: updated.outcome,
                         },
                     });
-                    // 9. Re-orchestrate on failure / needs_work (circuit breaker: max 3 attempts).
-                    if (updated.outcome && this.#reorchestrateOutcomes.has(updated.outcome)) {
-                        if (attempt < 3) {
+                    // requeue_retryable (bounded by attempt budget)
+                    if (role !== "reviewer" && updated.outcome && this.#reorchestrateOutcomes.has(updated.outcome)) {
+                        if (attempt < MAX_REORCHESTRATION_ATTEMPTS) {
                             await this.#reopenForOrchestration(issueId, { reason: `outcome=${updated.outcome}`, step });
                         }
                         else {

package/dist/index.d.ts

@@ -1,5 +1,9 @@
-export type { DagResult, DagRunnerBackendLineEvent, DagRunnerHooks, DagRunnerRunOpts, DagRunnerStepEndEvent, DagRunnerStepStartEvent, } from "./dag_runner.js";
-export { DagRunner } from "./dag_runner.js";
+export type { DagResult, DagRunnerBackendLineEvent, DagRunnerHooks, DagRunnerReconcilePhase, DagRunnerReviewLoopPhase, DagRunnerRunOpts, DagRunnerStepEndEvent, DagRunnerStepStartEvent, } from "./dag_runner.js";
+export { DAG_RUNNER_BUDGET_INVARIANTS, DAG_RUNNER_CONTRACT_INVARIANTS, DEFAULT_MAX_REFINE_ROUNDS_PER_ROOT, DagRunner, REVIEW_DECISION_TO_OUTCOME, } from "./dag_runner.js";
+export type { DagReconcileDecision, DagReconcileOpts, DagRootPhase } from "./dag_reconcile.js";
+export { DAG_RECONCILE_ENGINE_INVARIANTS, reconcileDagTurn } from "./dag_reconcile.js";
+export type { InterRootQueuePolicy, InterRootQueueReconcilePlan, InterRootQueueSnapshot, OrchestrationQueueState, } from "./inter_root_queue_reconcile.js";
+export { DEFAULT_INTER_ROOT_QUEUE_POLICY, INTER_ROOT_QUEUE_RECONCILE_INVARIANTS, normalizeInterRootQueuePolicy, ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS, ORCHESTRATION_QUEUE_INVARIANTS, reconcileInterRootQueue, } from "./inter_root_queue_reconcile.js";
 export type { ModelOverrides, ResolvedModelConfig } from "./model_resolution.js";
 export { resolveModelConfig } from "./model_resolution.js";
 export type { PiStreamRendererOpts } from "./pi_stream_renderer.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,SAAS,EACT,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,SAAS,EACT,yBAAyB,EACzB,cAAc,EACd,uBAAuB,EACvB,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,uBAAuB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACN,4BAA4B,EAC5B,8BAA8B,EAC9B,kCAAkC,EAClC,SAAS,EACT,0BAA0B,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/F,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACvF,YAAY,EACX,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,GACvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACN,+BAA+B,EAC/B,qCAAqC,EACrC,6BAA6B,EAC7B,uCAAuC,EACvC,8BAA8B,EAC9B,uBAAuB,GACvB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
-export { DagRunner } from "./dag_runner.js";
+export { DAG_RUNNER_BUDGET_INVARIANTS, DAG_RUNNER_CONTRACT_INVARIANTS, DEFAULT_MAX_REFINE_ROUNDS_PER_ROOT, DagRunner, REVIEW_DECISION_TO_OUTCOME, } from "./dag_runner.js";
+export { DAG_RECONCILE_ENGINE_INVARIANTS, reconcileDagTurn } from "./dag_reconcile.js";
+export { DEFAULT_INTER_ROOT_QUEUE_POLICY, INTER_ROOT_QUEUE_RECONCILE_INVARIANTS, normalizeInterRootQueuePolicy, ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS, ORCHESTRATION_QUEUE_INVARIANTS, reconcileInterRootQueue, } from "./inter_root_queue_reconcile.js";
 export { resolveModelConfig } from "./model_resolution.js";
 export { PiStreamRenderer } from "./pi_stream_renderer.js";

package/dist/inter_root_queue_reconcile.d.ts

@@ -0,0 +1,45 @@
+export type OrchestrationQueueState = "queued" | "active" | "waiting_review" | "refining" | "done" | "failed" | "cancelled";
+/**
+ * Inter-root scheduler policy knob for durable queue drain.
+ * - sequential: exactly one active root (`max_active_roots=1`)
+ * - parallel: bounded fanout (`max_active_roots>=1`)
+ */
+export type InterRootQueuePolicy = {
+    mode: "sequential";
+    max_active_roots: 1;
+} | {
+    mode: "parallel";
+    max_active_roots: number;
+};
+export declare const DEFAULT_INTER_ROOT_QUEUE_POLICY: InterRootQueuePolicy;
+export declare function normalizeInterRootQueuePolicy(policy: InterRootQueuePolicy | null | undefined): InterRootQueuePolicy;
+/**
+ * Allowed queue transitions. Downstream queue tests should enforce this table exactly.
+ */
+export declare const ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS: Record<OrchestrationQueueState, readonly OrchestrationQueueState[]>;
+export declare const ORCHESTRATION_QUEUE_INVARIANTS: readonly ["ORCH-QUEUE-001: Queue writes are durable before acknowledging enqueue/start/resume requests.", "ORCH-QUEUE-002: Queue dispatch must claim exactly one active item at a time per root slot.", "ORCH-QUEUE-003: Terminal states (done|failed|cancelled) are immutable.", "ORCH-QUEUE-004: Review path is active -> waiting_review -> (done | refining).", "ORCH-QUEUE-005: Refinement re-enters execution only via refining -> queued.", "ORCH-QUEUE-006: sequential policy permits <=1 active root; parallel permits <=max_active_roots active roots."];
+export type InterRootQueueSnapshot = {
+    queue_id: string;
+    root_issue_id: string | null;
+    state: OrchestrationQueueState;
+    job_id: string | null;
+    created_at_ms: number;
+};
+export type InterRootQueueReconcilePlan = {
+    policy: InterRootQueuePolicy;
+    max_active_roots: number;
+    active_root_count: number;
+    available_root_slots: number;
+    activate_queue_ids: string[];
+    launch_queue_ids: string[];
+};
+export declare const INTER_ROOT_QUEUE_RECONCILE_INVARIANTS: readonly ["ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.", "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.", "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.", "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot."];
+/**
+ * Deterministic inter-root queue reconcile primitive.
+ *
+ * Computes queue activation/launch intentions from durable queue state and policy. The caller is
+ * responsible for performing side effects (claim, launch, bind, transition) and reconciling again
+ * against refreshed queue/runtime snapshots.
+ */
+export declare function reconcileInterRootQueue<Row extends InterRootQueueSnapshot>(rows: readonly Row[], policy: InterRootQueuePolicy): InterRootQueueReconcilePlan;
+//# sourceMappingURL=inter_root_queue_reconcile.d.ts.map

package/dist/inter_root_queue_reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inter_root_queue_reconcile.d.ts","sourceRoot":"","sources":["../src/inter_root_queue_reconcile.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAChC,QAAQ,GACR,QAAQ,GACR,gBAAgB,GAChB,UAAU,GACV,MAAM,GACN,QAAQ,GACR,WAAW,CAAC;AAEf;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC7B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,gBAAgB,EAAE,CAAC,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,+BAA+B,EAAE,oBAG7C,CAAC;AAEF,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAAG,oBAAoB,CAWnH;AAED;;GAEG;AACH,eAAO,MAAM,uCAAuC,EAAE,MAAM,CAC3D,uBAAuB,EACvB,SAAS,uBAAuB,EAAE,CASlC,CAAC;AAEF,eAAO,MAAM,8BAA8B,miBAOjC,CAAC;AAIX,MAAM,MAAM,sBAAsB,GAAG;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,uBAAuB,CAAC;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACzC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,qCAAqC,gdAKxC,CAAC;AAoBX;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,SAAS,sBAAsB,EACzE,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,MAAM,EAAE,oBAAoB,GAC1B,2BAA2B,CAgD7B"}

package/dist/inter_root_queue_reconcile.js

@@ -0,0 +1,111 @@
+export const DEFAULT_INTER_ROOT_QUEUE_POLICY = {
+    mode: "sequential",
+    max_active_roots: 1,
+};
+export function normalizeInterRootQueuePolicy(policy) {
+    if (!policy) {
+        return DEFAULT_INTER_ROOT_QUEUE_POLICY;
+    }
+    if (policy.mode === "parallel") {
+        return {
+            mode: "parallel",
+            max_active_roots: Math.max(1, Math.trunc(policy.max_active_roots)),
+        };
+    }
+    return DEFAULT_INTER_ROOT_QUEUE_POLICY;
+}
+/**
+ * Allowed queue transitions. Downstream queue tests should enforce this table exactly.
+ */
+export const ORCHESTRATION_QUEUE_ALLOWED_TRANSITIONS = {
+    queued: ["active", "cancelled"],
+    active: ["waiting_review", "done", "failed", "cancelled"],
+    waiting_review: ["refining", "done", "failed", "cancelled"],
+    refining: ["queued", "failed", "cancelled"],
+    done: [],
+    failed: [],
+    cancelled: [],
+};
+export const ORCHESTRATION_QUEUE_INVARIANTS = [
+    "ORCH-QUEUE-001: Queue writes are durable before acknowledging enqueue/start/resume requests.",
+    "ORCH-QUEUE-002: Queue dispatch must claim exactly one active item at a time per root slot.",
+    "ORCH-QUEUE-003: Terminal states (done|failed|cancelled) are immutable.",
+    "ORCH-QUEUE-004: Review path is active -> waiting_review -> (done | refining).",
+    "ORCH-QUEUE-005: Refinement re-enters execution only via refining -> queued.",
+    "ORCH-QUEUE-006: sequential policy permits <=1 active root; parallel permits <=max_active_roots active roots.",
+];
+const INTER_ROOT_OCCUPIED_STATES = new Set(["active", "waiting_review", "refining"]);
+export const INTER_ROOT_QUEUE_RECONCILE_INVARIANTS = [
+    "ORCH-INTER-ROOT-RECON-001: one queue snapshot + policy yields one deterministic activation/launch plan.",
+    "ORCH-INTER-ROOT-RECON-002: activation order is FIFO (`created_at_ms`, then `queue_id`) with per-root slot dedupe.",
+    "ORCH-INTER-ROOT-RECON-003: sequential policy admits <=1 occupied root; parallel admits <=max_active_roots roots.",
+    "ORCH-INTER-ROOT-RECON-004: launch candidates are active rows without bound job ids, one launch per root slot.",
+];
+function stableCompare(a, b) {
+    if (a.created_at_ms !== b.created_at_ms) {
+        return a.created_at_ms - b.created_at_ms;
+    }
+    return a.queue_id.localeCompare(b.queue_id);
+}
+function normalizeMaxActiveRoots(policy) {
+    if (policy.mode === "parallel") {
+        return Math.max(1, Math.trunc(policy.max_active_roots));
+    }
+    return 1;
+}
+function queueRootSlotKey(row) {
+    return row.root_issue_id ? `root:${row.root_issue_id}` : `queue:${row.queue_id}`;
+}
+/**
+ * Deterministic inter-root queue reconcile primitive.
+ *
+ * Computes queue activation/launch intentions from durable queue state and policy. The caller is
+ * responsible for performing side effects (claim, launch, bind, transition) and reconciling again
+ * against refreshed queue/runtime snapshots.
+ */
+export function reconcileInterRootQueue(rows, policy) {
+    const sorted = [...rows].sort(stableCompare);
+    const maxActiveRoots = normalizeMaxActiveRoots(policy);
+    const occupiedRoots = new Set();
+    const launchRoots = new Set();
+    const launchQueueIds = [];
+    for (const row of sorted) {
+        if (!INTER_ROOT_OCCUPIED_STATES.has(row.state)) {
+            continue;
+        }
+        const slotKey = queueRootSlotKey(row);
+        occupiedRoots.add(slotKey);
+        if (row.state !== "active" || row.job_id != null || launchRoots.has(slotKey)) {
+            continue;
+        }
+        launchRoots.add(slotKey);
+        launchQueueIds.push(row.queue_id);
+    }
+    const availableRootSlots = Math.max(0, maxActiveRoots - occupiedRoots.size);
+    const claimedRoots = new Set();
+    const activateQueueIds = [];
+    if (availableRootSlots > 0) {
+        for (const row of sorted) {
+            if (row.state !== "queued") {
+                continue;
+            }
+            const slotKey = queueRootSlotKey(row);
+            if (occupiedRoots.has(slotKey) || claimedRoots.has(slotKey)) {
+                continue;
+            }
+            claimedRoots.add(slotKey);
+            activateQueueIds.push(row.queue_id);
+            if (activateQueueIds.length >= availableRootSlots) {
+                break;
+            }
+        }
+    }
+    return {
+        policy,
+        max_active_roots: maxActiveRoots,
+        active_root_count: occupiedRoots.size,
+        available_root_slots: availableRootSlots,
+        activate_queue_ids: activateQueueIds,
+        launch_queue_ids: launchQueueIds,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@femtomc/mu-orchestrator",
-  "version": "26.2.70",
+  "version": "26.2.71",
   "description": "Long-running execution engine for mu work plans.",
   "keywords": [
     "mu",
@@ -21,10 +21,10 @@
     "dist/**"
   ],
   "dependencies": {
-    "@femtomc/mu-agent": "26.2.70",
-    "@femtomc/mu-core": "26.2.70",
-    "@femtomc/mu-forum": "26.2.70",
-    "@femtomc/mu-issue": "26.2.70",
+    "@femtomc/mu-agent": "workspace:*",
+    "@femtomc/mu-core": "workspace:*",
+    "@femtomc/mu-forum": "workspace:*",
+    "@femtomc/mu-issue": "workspace:*",
     "@mariozechner/pi-coding-agent": "^0.53.0",
     "@mariozechner/pi-ai": "^0.53.0"
   }