@loopover/engine 1.0.0

package/dist/plan-export.js

@@ -0,0 +1,86 @@
+// Plan DAG rendering (pure).
+//
+// Deterministic, side-effect-free renderers over an already-validated plan DAG (the `planDagSchema` shape used by
+// the MCP `gittensory_plan_status` surface in src/mcp/server.ts). No IO and no new logic: given a plan, produce
+// either a human-readable Markdown checklist ordered by dependency, or a stable, key-ordered JSON string that is
+// byte-identical across runs of the same plan (useful for diffing). The types below mirror the `planDagSchema`
+// shape so the engine package stays standalone and does not import the app's Zod schema.
+// Stable topological order: emit steps whose in-plan dependencies are already emitted, ties broken by the plan's
+// original order. A dependency id not present in the plan is treated as satisfied. Any steps left in a cycle are
+// appended in original order so nothing is dropped and the function always terminates.
+function orderByDependency(steps) {
+    const present = new Set(steps.map((step) => step.id));
+    const emitted = new Set();
+    const ordered = [];
+    const remaining = [...steps];
+    let progressed = true;
+    while (remaining.length > 0 && progressed) {
+        progressed = false;
+        for (let i = 0; i < remaining.length;) {
+            const step = remaining[i];
+            const ready = step.dependsOn.every((dep) => !present.has(dep) || emitted.has(dep));
+            if (ready) {
+                ordered.push(step);
+                emitted.add(step.id);
+                remaining.splice(i, 1);
+                progressed = true;
+            }
+            else {
+                i += 1;
+            }
+        }
+    }
+    ordered.push(...remaining);
+    return ordered;
+}
+// Make an untrusted title/error safe to drop into a Markdown checklist line: collapse any CR/LF run to a single
+// space (both fields allow newlines in the plan schema) so a step cannot spill onto extra rows, and backslash-escape
+// the Markdown control characters that would otherwise re-style the line (emphasis, code, links, html, tables,
+// strikethrough) when the artifact is pasted into a review surface. Backslash is escaped by the same class, so the
+// single pass is idempotent per character.
+function displaySafe(text) {
+    return text.replace(/[\r\n]+/g, " ").replace(/[\\`*_[\]<>|~]/g, "\\$&");
+}
+/**
+ * Render a plan DAG as a Markdown checklist ordered by dependency: one `- [x]`/`- [ ]` line per step (checked when
+ * the step is completed), annotated with its status, its attempt count when it has run, and its last error when
+ * present. Display fields are collapsed to a single line and Markdown control characters are escaped so each step
+ * stays on one row and an untrusted title/error cannot re-style it. Pure — it reads the plan and returns a string.
+ */
+export function renderPlanAsMarkdown(plan) {
+    const ordered = orderByDependency(plan.steps);
+    if (ordered.length === 0)
+        return "_No steps in this plan._";
+    return ordered
+        .map((step) => {
+        const box = step.status === "completed" ? "[x]" : "[ ]";
+        let line = `- ${box} ${displaySafe(step.title)} — ${step.status}`;
+        if (step.attempts > 0)
+            line += ` (attempt ${step.attempts}/${step.maxAttempts})`;
+        if (step.lastError)
+            line += `: ${displaySafe(step.lastError)}`;
+        return line;
+    })
+        .join("\n");
+}
+// Sort object keys at every level so the output is deterministic; arrays (e.g. `steps`) keep their order.
+function sortedKeysReplacer(_key, value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        const source = value;
+        return Object.keys(source)
+            .sort()
+            .reduce((acc, key) => {
+            acc[key] = source[key];
+            return acc;
+        }, {});
+    }
+    return value;
+}
+/**
+ * Render a plan DAG as a stable, deterministically key-ordered JSON string. Two renders of the identical plan are
+ * byte-identical (object keys are sorted at every level; array order is preserved), which makes plan snapshots
+ * diffable across runs. Pure.
+ */
+export function renderPlanAsJson(plan) {
+    return JSON.stringify(plan, sortedKeysReplacer, 2);
+}

package/dist/plan-failure.d.ts

@@ -0,0 +1,5 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether any step in the plan has failed. Pure — reads the plan DAG only.
+ */
+export declare function hasPlanFailedSteps(plan: PlanDag): boolean;

package/dist/plan-failure.js

@@ -0,0 +1,6 @@
+/**
+ * Return whether any step in the plan has failed. Pure — reads the plan DAG only.
+ */
+export function hasPlanFailedSteps(plan) {
+    return plan.steps.some((step) => step.status === "failed");
+}

package/dist/plan-overall-status.d.ts

@@ -0,0 +1,6 @@
+import type { PlanDag } from "./plan-export.js";
+export type PlanOverallStatus = "pending" | "running" | "completed" | "failed" | "blocked";
+/**
+ * Resolve the coarse plan status matching hosted `planProgress`'s `status` field. Pure — reads the plan DAG only.
+ */
+export declare function resolvePlanOverallStatus(plan: PlanDag): PlanOverallStatus;

package/dist/plan-overall-status.js

@@ -0,0 +1,25 @@
+const isDone = (status) => status === "completed" || status === "skipped";
+function nextReadySteps(plan) {
+    const statusById = new Map(plan.steps.map((step) => [step.id, step.status]));
+    return plan.steps.filter((step) => step.status === "pending" && step.dependsOn.every((dep) => isDone(statusById.get(dep) ?? "pending")));
+}
+/**
+ * Resolve the coarse plan status matching hosted `planProgress`'s `status` field. Pure — reads the plan DAG only.
+ */
+export function resolvePlanOverallStatus(plan) {
+    const total = plan.steps.length;
+    const completed = plan.steps.filter((step) => step.status === "completed").length;
+    const skipped = plan.steps.filter((step) => step.status === "skipped").length;
+    const failed = plan.steps.filter((step) => step.status === "failed").length;
+    const running = plan.steps.filter((step) => step.status === "running").length;
+    const pending = plan.steps.filter((step) => step.status === "pending").length;
+    if (total > 0 && completed + skipped === total)
+        return "completed";
+    if (failed > 0)
+        return "failed";
+    if (running > 0)
+        return "running";
+    if (pending > 0 && nextReadySteps(plan).length === 0)
+        return "blocked";
+    return "pending";
+}

package/dist/plan-pending.d.ts

@@ -0,0 +1,5 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether any step in the plan is still pending. Pure — reads the plan DAG only.
+ */
+export declare function hasPlanPendingSteps(plan: PlanDag): boolean;

package/dist/plan-pending.js

@@ -0,0 +1,6 @@
+/**
+ * Return whether any step in the plan is still pending. Pure — reads the plan DAG only.
+ */
+export function hasPlanPendingSteps(plan) {
+    return plan.steps.some((step) => step.status === "pending");
+}

package/dist/plan-progress-complete.d.ts

@@ -0,0 +1,7 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether every step is terminal success (`completed` or `skipped`). Empty plans are not complete. Mirrors
+ * the `completed` branch of hosted `planProgress` (distinct from `isPlanFullyCompleted`, which requires every
+ * step to be `completed`). Pure — reads the plan DAG only.
+ */
+export declare function isPlanProgressComplete(plan: PlanDag): boolean;

package/dist/plan-progress-complete.js

@@ -0,0 +1,10 @@
+/**
+ * Return whether every step is terminal success (`completed` or `skipped`). Empty plans are not complete. Mirrors
+ * the `completed` branch of hosted `planProgress` (distinct from `isPlanFullyCompleted`, which requires every
+ * step to be `completed`). Pure — reads the plan DAG only.
+ */
+export function isPlanProgressComplete(plan) {
+    if (plan.steps.length === 0)
+        return false;
+    return plan.steps.every((step) => step.status === "completed" || step.status === "skipped");
+}

package/dist/plan-ready.d.ts

@@ -0,0 +1,6 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether any step is runnable now: `pending` with every dependency `completed` or `skipped`. Mirrors hosted
+ * `nextReadySteps(plan).length > 0`. Pure.
+ */
+export declare function hasPlanReadySteps(plan: PlanDag): boolean;

package/dist/plan-ready.js

@@ -0,0 +1,12 @@
+const isDone = (status) => status === "completed" || status === "skipped";
+function nextReadySteps(plan) {
+    const statusById = new Map(plan.steps.map((step) => [step.id, step.status]));
+    return plan.steps.filter((step) => step.status === "pending" && step.dependsOn.every((dep) => isDone(statusById.get(dep) ?? "pending")));
+}
+/**
+ * Return whether any step is runnable now: `pending` with every dependency `completed` or `skipped`. Mirrors hosted
+ * `nextReadySteps(plan).length > 0`. Pure.
+ */
+export function hasPlanReadySteps(plan) {
+    return nextReadySteps(plan).length > 0;
+}

package/dist/plan-running.d.ts

@@ -0,0 +1,5 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether any step in the plan is currently running. Pure — reads the plan DAG only.
+ */
+export declare function hasPlanRunningSteps(plan: PlanDag): boolean;

package/dist/plan-running.js

@@ -0,0 +1,6 @@
+/**
+ * Return whether any step in the plan is currently running. Pure — reads the plan DAG only.
+ */
+export function hasPlanRunningSteps(plan) {
+    return plan.steps.some((step) => step.status === "running");
+}

package/dist/plan-skipped.d.ts

@@ -0,0 +1,5 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether any step in the plan was skipped. Pure — reads the plan DAG only.
+ */
+export declare function hasPlanSkippedSteps(plan: PlanDag): boolean;

package/dist/plan-skipped.js

@@ -0,0 +1,6 @@
+/**
+ * Return whether any step in the plan was skipped. Pure — reads the plan DAG only.
+ */
+export function hasPlanSkippedSteps(plan) {
+    return plan.steps.some((step) => step.status === "skipped");
+}

package/dist/plan-step-count.d.ts

@@ -0,0 +1,5 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return the total number of steps in the plan. Pure — reads the plan DAG only.
+ */
+export declare function countPlanSteps(plan: PlanDag): number;

package/dist/plan-step-count.js

@@ -0,0 +1,6 @@
+/**
+ * Return the total number of steps in the plan. Pure — reads the plan DAG only.
+ */
+export function countPlanSteps(plan) {
+    return plan.steps.length;
+}

package/dist/plan-step-stats.d.ts

@@ -0,0 +1,5 @@
+import type { PlanDag, PlanStepStatus } from "./plan-export.js";
+/**
+ * Count plan steps matching a given status. Pure — reads the plan DAG only.
+ */
+export declare function countPlanStepsByStatus(plan: PlanDag, status: PlanStepStatus): number;

package/dist/plan-step-stats.js

@@ -0,0 +1,6 @@
+/**
+ * Count plan steps matching a given status. Pure — reads the plan DAG only.
+ */
+export function countPlanStepsByStatus(plan, status) {
+    return plan.steps.filter((step) => step.status === status).length;
+}

package/dist/plan-templates.d.ts

@@ -0,0 +1,25 @@
+export type RawPlanStep = {
+    id: string;
+    title: string;
+    actionClass?: string | undefined;
+    dependsOn?: string[] | undefined;
+    maxAttempts?: number | undefined;
+    /** When set on the prepare-phase `coding-agent` step, records which execution mode the attempt runs under (#4313). */
+    codingAgentMode?: CodingAgentExecutionMode | undefined;
+};
+/** Re-exported here so plan templates stay standalone — defined in miner/coding-agent-mode.ts. */
+export type CodingAgentExecutionMode = "paused" | "dry_run" | "live";
+export type PlanTemplateStage = "discover" | "analyze" | "create" | "manage" | "plan" | "prepare";
+export type PlanTemplateContext = {
+    subject?: string | undefined;
+    /** Execution mode for the prepare-phase coding-agent step (#4313) — visible end-to-end on the plan DAG. */
+    codingAgentMode?: CodingAgentExecutionMode | undefined;
+};
+export declare function discoverPlanTemplate(context?: PlanTemplateContext): RawPlanStep[];
+export declare function analyzePlanTemplate(context?: PlanTemplateContext): RawPlanStep[];
+export declare function planPlanTemplate(context?: PlanTemplateContext): RawPlanStep[];
+export declare function preparePlanTemplate(context?: PlanTemplateContext): RawPlanStep[];
+export declare function createPlanTemplate(context?: PlanTemplateContext): RawPlanStep[];
+export declare function managePlanTemplate(context?: PlanTemplateContext): RawPlanStep[];
+export declare const PLAN_TEMPLATE_BUILDERS: Readonly<Record<PlanTemplateStage, (context?: PlanTemplateContext) => RawPlanStep[]>>;
+export declare function buildPlanTemplate(stage: PlanTemplateStage, context?: PlanTemplateContext): RawPlanStep[];

package/dist/plan-templates.js

@@ -0,0 +1,107 @@
+// Plan-template library (pure).
+//
+// Reusable plan TEMPLATES for the fixed miner lifecycle (discover -> analyze -> plan -> prepare -> create ->
+// manage -> repeat), emitted in the exact stateless raw-step shape the MCP `gittensory_build_plan` tool accepts
+// (`rawPlanStepSchema` in src/mcp/server.ts), so `build_plan` can normalize them into a validated DAG. Each builder
+// is deterministic and side-effect-free: it only DESCRIBES steps and their `dependsOn` ordering — it never actuates
+// anything. The `RawPlanStep` type below mirrors the raw-step schema so the engine package stays standalone and
+// does not import the app's Zod schema (the tests validate the output against the real schema to guard drift).
+// Title length ceiling of `rawPlanStepSchema.title` (max 300). Titles are hard-capped to this so a long subject can
+// never produce an out-of-range step.
+const MAX_TITLE_CHARS = 300;
+// Keep the woven subject well under the title ceiling so the fixed prefix always survives the cap.
+const MAX_SUBJECT_CHARS = 200;
+// Collapse any run of whitespace (including newlines) to a single space and trim, so a subject yields a clean,
+// deterministic one-line title.
+function normalizeSubject(subject) {
+    return (subject ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_SUBJECT_CHARS);
+}
+// Compose a step title from a fixed prefix and the optional subject, hard-capped to the schema's title ceiling.
+function titleFor(prefix, subject) {
+    const full = subject ? `${prefix}: ${subject}` : prefix;
+    return full.slice(0, MAX_TITLE_CHARS);
+}
+// discover: rank candidate opportunities, validate lane fit, then run a pre-start check before analyze.
+export function discoverPlanTemplate(context = {}) {
+    const subject = normalizeSubject(context.subject);
+    return [
+        { id: "opportunity-rank", title: titleFor("Rank candidate opportunities", subject), actionClass: "discover", dependsOn: [], maxAttempts: 2 },
+        { id: "lane-fit-check", title: titleFor("Validate miner goal lane fit", subject), actionClass: "analyze", dependsOn: ["opportunity-rank"], maxAttempts: 1 },
+        { id: "pre-start-check", title: titleFor("Run pre-start check", subject), actionClass: "analyze", dependsOn: ["lane-fit-check"], maxAttempts: 2 },
+    ];
+}
+// analyze: feasibility check and repository RAG retrieval run independently, then the prompt-packet build consumes
+// both. Mirrors the ANALYZE-phase ordering described in the plan-template issue.
+export function analyzePlanTemplate(context = {}) {
+    const subject = normalizeSubject(context.subject);
+    return [
+        { id: "feasibility-check", title: titleFor("Assess feasibility", subject), actionClass: "analyze", dependsOn: [], maxAttempts: 1 },
+        { id: "rag-retrieval", title: titleFor("Retrieve repository context", subject), actionClass: "retrieve", dependsOn: [], maxAttempts: 3 },
+        { id: "prompt-packet", title: titleFor("Build prompt packet", subject), actionClass: "compose", dependsOn: ["feasibility-check", "rag-retrieval"], maxAttempts: 2 },
+    ];
+}
+// plan: validate the analyze prompt packet, build the execution DAG, then run a readiness check before prepare.
+export function planPlanTemplate(context = {}) {
+    const subject = normalizeSubject(context.subject);
+    return [
+        { id: "packet-validate", title: titleFor("Validate prompt packet", subject), actionClass: "analyze", dependsOn: [], maxAttempts: 1 },
+        { id: "plan-dag-build", title: titleFor("Build execution plan DAG", subject), actionClass: "compose", dependsOn: ["packet-validate"], maxAttempts: 2 },
+        { id: "readiness-check", title: titleFor("Run plan readiness check", subject), actionClass: "analyze", dependsOn: ["plan-dag-build"], maxAttempts: 1 },
+    ];
+}
+// prepare: a strict chain — create the branch, invoke the coding agent (placeholder step; no actuation here), then
+// run the local tests. Mirrors the PREPARE-phase ordering described in the plan-template issue.
+export function preparePlanTemplate(context = {}) {
+    const subject = normalizeSubject(context.subject);
+    const codingAgentStep = {
+        id: "coding-agent",
+        title: titleFor("Invoke coding agent", subject),
+        actionClass: "codegen",
+        dependsOn: ["branch-create"],
+        maxAttempts: 1,
+        ...(context.codingAgentMode === undefined ? {} : { codingAgentMode: context.codingAgentMode }),
+    };
+    return [
+        { id: "branch-create", title: titleFor("Create working branch", subject), actionClass: "vcs", dependsOn: [], maxAttempts: 3 },
+        codingAgentStep,
+        { id: "local-test", title: titleFor("Run local tests", subject), actionClass: "test", dependsOn: ["coding-agent"], maxAttempts: 2 },
+    ];
+}
+// create: commit the working tree, push the branch, then open the pull request with the public-safe packet.
+export function createPlanTemplate(context = {}) {
+    const subject = normalizeSubject(context.subject);
+    return [
+        { id: "commit-changes", title: titleFor("Commit working tree changes", subject), actionClass: "vcs", dependsOn: [], maxAttempts: 2 },
+        { id: "push-branch", title: titleFor("Push feature branch", subject), actionClass: "vcs", dependsOn: ["commit-changes"], maxAttempts: 3 },
+        { id: "open-pull-request", title: titleFor("Open pull request", subject), actionClass: "github", dependsOn: ["push-branch"], maxAttempts: 2 },
+    ];
+}
+// manage: wait for CI, read the gate verdict, then sync the fork default branch for the next cycle.
+export function managePlanTemplate(context = {}) {
+    const subject = normalizeSubject(context.subject);
+    return [
+        { id: "wait-ci", title: titleFor("Wait for CI completion", subject), actionClass: "test", dependsOn: [], maxAttempts: 5 },
+        { id: "read-gate-result", title: titleFor("Read gate verdict", subject), actionClass: "analyze", dependsOn: ["wait-ci"], maxAttempts: 2 },
+        { id: "sync-fork", title: titleFor("Sync fork default branch", subject), actionClass: "vcs", dependsOn: ["read-gate-result"], maxAttempts: 3 },
+    ];
+}
+// Registry of every stage transition to its template builder, so callers can enumerate or dispatch by stage.
+// Frozen so a consumer cannot mutate the shared registry and change dispatch behavior process-wide.
+export const PLAN_TEMPLATE_BUILDERS = Object.freeze({
+    discover: discoverPlanTemplate,
+    analyze: analyzePlanTemplate,
+    create: createPlanTemplate,
+    manage: managePlanTemplate,
+    plan: planPlanTemplate,
+    prepare: preparePlanTemplate,
+});
+// Build the raw-step template for a stage. Pure — a thin dispatcher over `PLAN_TEMPLATE_BUILDERS` that rejects an
+// unknown stage with a clear error rather than a generic "not a function" TypeError (guards non-TypeScript callers).
+export function buildPlanTemplate(stage, context = {}) {
+    const builder = Object.prototype.hasOwnProperty.call(PLAN_TEMPLATE_BUILDERS, stage)
+        ? PLAN_TEMPLATE_BUILDERS[stage]
+        : undefined;
+    if (typeof builder !== "function")
+        throw new Error(`Unknown plan-template stage: ${String(stage)}`);
+    return builder(context);
+}

package/dist/plan-terminated.d.ts

@@ -0,0 +1,6 @@
+import type { PlanDag } from "./plan-export.js";
+/**
+ * Return whether the plan reached a terminal outcome: any step `failed`, or every step is `completed` or `skipped`.
+ * Empty plans are not terminated. Pure.
+ */
+export declare function isPlanTerminated(plan: PlanDag): boolean;

package/dist/plan-terminated.js

@@ -0,0 +1,9 @@
+import { hasPlanFailedSteps } from "./plan-failure.js";
+import { isPlanProgressComplete } from "./plan-progress-complete.js";
+/**
+ * Return whether the plan reached a terminal outcome: any step `failed`, or every step is `completed` or `skipped`.
+ * Empty plans are not terminated. Pure.
+ */
+export function isPlanTerminated(plan) {
+    return hasPlanFailedSteps(plan) || isPlanProgressComplete(plan);
+}

package/dist/portfolio/non-convergence.d.ts

@@ -0,0 +1,37 @@
+export type PortfolioConvergenceStatus = "converging" | "stalled" | "non_convergent";
+/** One queue item's attempt/outcome history. Plain counts — the caller already tracks or supplies these;
+ *  this module invents no persistence (the queue table carries no attempt-history columns today). */
+export type PortfolioConvergenceInput = {
+    /** Total attempts made on this item so far. */
+    attempts: number;
+    /** Consecutive failed attempts since the last improvement (reset to 0 on any progress). */
+    consecutiveFailures: number;
+    /** Times the item was re-enqueued (queued → in_progress → queued) without ever reaching `done`. */
+    reenqueues: number;
+    /** Whether the item has ever reached a terminal `done` outcome. */
+    reachedDone: boolean;
+};
+/** Streak lengths at (or above) which a still-unfinished item reads non-convergent. */
+export type PortfolioConvergenceThresholds = {
+    /** consecutiveFailures ≥ this ⇒ non_convergent. */
+    maxConsecutiveFailures: number;
+    /** reenqueues (without reaching done) ≥ this ⇒ non_convergent. */
+    maxReenqueues: number;
+};
+/** Conservative defaults — a single failure or re-enqueue never trips these; only a sustained streak does. */
+export declare const DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS: PortfolioConvergenceThresholds;
+export type PortfolioConvergenceVerdict = {
+    status: PortfolioConvergenceStatus;
+    reasons: string[];
+};
+/**
+ * Classify one queue item's convergence from its attempt/outcome counts. Pure and deterministic.
+ *
+ * - Zero attempts (not yet tried) reads `converging` — a first attempt is not evidence of a stuck loop
+ *   (the same non-judgment-on-absence rule ../contributor-fit.ts applies to a first attempt).
+ * - An item that has reached `done` is `converging` by definition.
+ * - A sustained streak — `consecutiveFailures` or `reenqueues` at/above its threshold — reads
+ *   `non_convergent`. A single failure or re-enqueue below threshold reads `stalled`, not non-convergent.
+ * - Attempts in progress with no failure streak read `converging`.
+ */
+export declare function classifyPortfolioConvergence(input: PortfolioConvergenceInput, thresholds?: PortfolioConvergenceThresholds): PortfolioConvergenceVerdict;

package/dist/portfolio/non-convergence.js

@@ -0,0 +1,57 @@
+// Non-convergence DETECTOR (#4286): a pure classifier over one portfolio-queue item's attempt/outcome
+// history. It answers whether that item is making progress, is merely stalled, or is stuck in a
+// non-convergent loop (cycling queued → in_progress → queued without ever reaching `done`, per the
+// re-enqueue-in-place behaviour at packages/gittensory-miner/lib/portfolio-queue.js:108-115).
+//
+// DETECTOR ONLY — no enforcement, no write-blocking, no IO, no Date.now(), no randomness. It takes typed
+// counts and returns a typed verdict; it gates nothing on its own. The fail-closed Governor chokepoint that
+// COMPOSES this signal with rate-limit + budget caps into one allow/deny decision is separate,
+// maintainer-owned work tracked in #2340 (milestone 13) — explicitly not this module.
+//
+// Mirrors the pure-classifier-over-typed-input discipline of ../contributor-fit.ts (typed input in,
+// { status, reasons } out, and "absence of history is not evidence of a problem").
+/** Conservative defaults — a single failure or re-enqueue never trips these; only a sustained streak does. */
+export const DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS = {
+    maxConsecutiveFailures: 3,
+    maxReenqueues: 3,
+};
+/**
+ * Classify one queue item's convergence from its attempt/outcome counts. Pure and deterministic.
+ *
+ * - Zero attempts (not yet tried) reads `converging` — a first attempt is not evidence of a stuck loop
+ *   (the same non-judgment-on-absence rule ../contributor-fit.ts applies to a first attempt).
+ * - An item that has reached `done` is `converging` by definition.
+ * - A sustained streak — `consecutiveFailures` or `reenqueues` at/above its threshold — reads
+ *   `non_convergent`. A single failure or re-enqueue below threshold reads `stalled`, not non-convergent.
+ * - Attempts in progress with no failure streak read `converging`.
+ */
+export function classifyPortfolioConvergence(input, thresholds = DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS) {
+    if (input.attempts <= 0) {
+        return {
+            status: "converging",
+            reasons: ["No attempts yet; a first attempt is not evidence of a stuck loop."],
+        };
+    }
+    if (input.reachedDone) {
+        return { status: "converging", reasons: ["Item reached done."] };
+    }
+    const reasons = [];
+    if (input.consecutiveFailures >= thresholds.maxConsecutiveFailures) {
+        reasons.push(`${input.consecutiveFailures} consecutive failures (≥ ${thresholds.maxConsecutiveFailures}).`);
+    }
+    if (input.reenqueues >= thresholds.maxReenqueues) {
+        reasons.push(`re-enqueued ${input.reenqueues} times without reaching done (≥ ${thresholds.maxReenqueues}).`);
+    }
+    if (reasons.length > 0) {
+        return { status: "non_convergent", reasons };
+    }
+    if (input.consecutiveFailures > 0 || input.reenqueues > 0) {
+        return {
+            status: "stalled",
+            reasons: [
+                `${input.consecutiveFailures} consecutive failure(s), ${input.reenqueues} re-enqueue(s) — below the non-convergence threshold.`,
+            ],
+        };
+    }
+    return { status: "converging", reasons: ["Attempts in progress with no failure streak."] };
+}

package/dist/portfolio/queue.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Portfolio queue primitives (#2326). Pure bookkeeping for the miner's local cross-repo work queue:
+ * bucket items by repo, respect global/per-repo WIP caps, and select the next eligible batch in a
+ * deterministic diversified order. No IO, no Date, no randomness, and no enforcement/action logic.
+ */
+export type PortfolioQueueItemState = "queued" | "in_progress";
+export type PortfolioQueueItem = {
+    id: string;
+    repoFullName: string;
+    state: PortfolioQueueItemState;
+};
+export type PortfolioQueueBucket = {
+    repoFullName: string;
+    items: PortfolioQueueItem[];
+};
+export type PortfolioQueue = {
+    buckets: PortfolioQueueBucket[];
+};
+export type PortfolioCaps = {
+    globalWipCap: number;
+    perRepoWipCap: number;
+};
+/** Append one item to the queue, creating its repo bucket if needed. Duplicate/blank ids are ignored. Pure. */
+export declare function enqueueItem(queue: PortfolioQueue, item: PortfolioQueueItem): PortfolioQueue;
+/** Remove matching items by id; empty buckets disappear. Unknown/blank ids are a no-op. Pure. */
+export declare function dequeueItem(queue: PortfolioQueue, itemId: string): PortfolioQueue;
+/** Select the next batch of queued items that fit within global/per-repo WIP caps. The batch always alternates
+ *  repos when another repo still has an eligible item waiting; among those eligible repos, lower current load wins
+ *  and ties keep stable bucket order. Pure. */
+export declare function nextEligibleItems(queue: PortfolioQueue, caps: PortfolioCaps): PortfolioQueueItem[];