@loopover/engine 1.0.0

package/dist/miner/self-review-adapter.d.ts

@@ -0,0 +1,106 @@
+import { type PredictedGateInput, type PredictedGateVerdict, type GateCheckConclusion } from "../predicted-gate.js";
+import type { FocusManifest } from "../focus-manifest/guidance.js";
+import type { AdvisoryFinding, BountyRecord, IssueRecord, PullRequestRecord, RepositoryRecord } from "../types/predicted-gate-types.js";
+import type { IssueQualityReport } from "../signals/predicted-gate-engine.js";
+/** One changed file in the attempt's live worktree diff. Mirrors `SlopChangedFile` (`src/signals/slop.ts`). */
+export type SelfReviewChangedFile = {
+    path: string;
+    additions?: number | undefined;
+    deletions?: number | undefined;
+};
+/** Structural mirror of `SlopBand` (`src/signals/slop.ts`). */
+export type SelfReviewSlopBand = "clean" | "low" | "elevated" | "high";
+/** Structural mirror of `SlopAssessmentInput` (`src/signals/slop.ts`) -- see the module doc comment on why
+ *  this is a hand-kept mirror rather than an import. */
+export type SelfReviewSlopInput = {
+    changedFiles?: SelfReviewChangedFile[] | undefined;
+    tests?: string[] | undefined;
+    testFiles?: string[] | undefined;
+    description?: string | null | undefined;
+    commitMessages?: string[] | undefined;
+    inDuplicateCluster?: boolean | undefined;
+    hasLinkedIssue?: boolean | undefined;
+    issueDiscoveryLane?: boolean | undefined;
+};
+/** Structural mirror of `SlopAssessment` (`src/signals/slop.ts`). Reuses the engine's own native
+ *  `AdvisoryFinding` for `findings` (predicted-gate-types.ts's own comment already documents it as the mirror
+ *  of `src/signals/engine.ts`'s `SignalFinding`, which slop.ts's findings are typed as). */
+export type SelfReviewSlopAssessment = {
+    slopRisk: number;
+    band: SelfReviewSlopBand;
+    findings: AdvisoryFinding[];
+};
+/** Injected dependency binding the real `src/signals/slop.ts#buildSlopAssessment` -- mirrors the
+ *  `RewardRiskEngineDeps` injection pattern for the identical not-yet-extracted-into-the-engine reason. */
+export type SelfReviewAdapterDeps = {
+    runSlopAssessment: (input: SelfReviewSlopInput) => SelfReviewSlopAssessment;
+};
+/**
+ * The attempt-side state an iterate-loop iteration (#2333) has available each round: the live worktree diff,
+ * plus the acceptance-criteria-derived identity fields a synthetic PR needs. Nothing here requires network
+ * access -- everything is either local diff state or already resolved by an earlier phase (prompt packet /
+ * acceptance criteria).
+ */
+export type AttemptDiffState = {
+    repoFullName: string;
+    contributorLogin: string;
+    title: string;
+    body?: string | undefined;
+    labels?: string[] | undefined;
+    linkedIssues?: number[] | undefined;
+    authorAssociation?: string | undefined;
+    changedFiles: SelfReviewChangedFile[];
+    testFiles?: string[] | undefined;
+    commitMessages?: string[] | undefined;
+    issueDiscoveryLane?: boolean | undefined;
+};
+/** Repo-level context the caller supplies once per attempt (this adapter does not fetch it itself -- see the
+ *  module doc comment). Mirrors `buildPredictedGateVerdict`'s own non-diff-state parameters exactly. */
+export type SelfReviewContext = {
+    manifest: FocusManifest;
+    repo: RepositoryRecord | null;
+    issues: IssueRecord[];
+    pullRequests: PullRequestRecord[];
+    bounties?: BountyRecord[] | undefined;
+    issueQuality?: IssueQualityReport | null | undefined;
+    confirmedContributor?: boolean | undefined;
+    /** Whether this attempt's synthetic PR is itself in a duplicate cluster -- the caller computes this from
+     *  `pullRequests`/`issues` the same way the live gate's collision report would. Threaded separately from
+     *  `diffState` since it depends on repo-level context, not the diff itself. */
+    inDuplicateCluster?: boolean | undefined;
+};
+export type SelfReviewVerdict = {
+    predictedGateVerdict: PredictedGateVerdict;
+    slopAssessment: SelfReviewSlopAssessment;
+    changedPaths: string[];
+    /** The hard requirement this issue's deliverables call for: true ONLY when `predictedGateVerdict.conclusion`
+     *  is a clear pass ({@link SELF_REVIEW_PASSING_CONCLUSION}). Any other conclusion -- `"failure"`,
+     *  `"action_required"`, `"neutral"`, or `"skipped"` -- means false. Callers (this adapter's own consumers,
+     *  and independently the iterate-loop orchestrator, #2333, as defense in depth) must never hand off to
+     *  submission when this is false. */
+    passesPredictedGate: boolean;
+};
+/** The one literal conclusion value that counts as a clear pass. Exported so callers enforcing the same hard
+ *  requirement (defense in depth, per this issue's own deliverable) check against the identical literal rather
+ *  than each re-deriving their own notion of "passing". */
+export declare const SELF_REVIEW_PASSING_CONCLUSION: GateCheckConclusion;
+/** Build the `PredictedGateInput` (repo, contributor login, title, body, labels, linked issues) from the
+ *  attempt's diff state -- the compact synthetic-PR-identity fields `buildPredictedGateVerdict` needs, as
+ *  distinct from the repo-level {@link SelfReviewContext}. */
+export declare function buildSelfReviewPredictedGateInput(diffState: AttemptDiffState): PredictedGateInput;
+/** The real changed file paths from the diff, for the `changedPaths` argument `buildPredictedGateVerdict`
+ *  needs to evaluate path-dependent checks (focus-manifest path policy, path-gated pre-merge checks, the
+ *  file-count size/guardrail hold). Omitting them silently under-predicts per predicted-gate.ts's own
+ *  `PREDICTED_GATE_NOTE_NO_PATHS` disclaimer -- a dangerous false-confidence bug if the miner's own loop
+ *  relied on an omitted-paths call. `runSelfReview` below always threads this through; it is exported
+ *  separately so a caller assembling `SelfReviewContext` can also see the exact same path list if needed. */
+export declare function buildSelfReviewChangedPaths(diffState: AttemptDiffState): string[];
+/** Build the slop-assessment input from the diff state + context, mirroring `SlopAssessmentInput` exactly. */
+export declare function buildSelfReviewSlopInput(diffState: AttemptDiffState, context: SelfReviewContext): SelfReviewSlopInput;
+/**
+ * Run the full self-review pass for one iteration: build the predicted-gate + slop inputs from the attempt's
+ * diff state, call `buildPredictedGateVerdict` with the caller-supplied repo-level context (`changedPaths`
+ * ALWAYS threaded through explicitly, never omitted), run the injected slop assessment, and combine into one
+ * verdict.
+ */
+export declare function runSelfReview(diffState: AttemptDiffState, context: SelfReviewContext, deps: SelfReviewAdapterDeps): SelfReviewVerdict;

package/dist/miner/self-review-adapter.js

@@ -0,0 +1,83 @@
+// Self-review adapter (#2334): turns an attempt's live worktree diff state into the SAME inputs
+// `buildPredictedGateVerdict` (predicted-gate.ts) and the slop-signal pass (src/signals/slop.ts) expect, so
+// the iterate-loop's self-review call (#2333) is genuinely byte-identical to what the live maintainer gate
+// would compute post-submission -- not an approximation.
+//
+// SLOP INJECTION: `src/signals/slop.ts` has not been extracted into this package (it depends on several
+// sibling `src/signals/*` modules that are also unextracted) -- mirrors the established `RewardRiskEngineDeps`
+// injection pattern (`reward-risk.ts`, #2281) for the identical reason: this module takes the slop assessment
+// as an INJECTED function rather than importing slop.ts directly, so the engine package keeps zero import
+// dependency on the private `src/` tree. `SelfReviewSlopInput`/`SelfReviewSlopAssessment` below are a
+// hand-kept structural mirror of slop.ts's `SlopAssessmentInput`/`SlopAssessment` -- same discipline as
+// `types/predicted-gate-types.ts`'s own header comment ("Local mirrors from src/... Keep in sync by hand").
+// The real binding (`buildSlopAssessment`) lives in whichever `src`-side shim wires a live iterate-loop.
+import { buildPredictedGateVerdict } from "../predicted-gate.js";
+/** The one literal conclusion value that counts as a clear pass. Exported so callers enforcing the same hard
+ *  requirement (defense in depth, per this issue's own deliverable) check against the identical literal rather
+ *  than each re-deriving their own notion of "passing". */
+export const SELF_REVIEW_PASSING_CONCLUSION = "success";
+function isClearPass(conclusion) {
+    return conclusion === SELF_REVIEW_PASSING_CONCLUSION;
+}
+/** Build the `PredictedGateInput` (repo, contributor login, title, body, labels, linked issues) from the
+ *  attempt's diff state -- the compact synthetic-PR-identity fields `buildPredictedGateVerdict` needs, as
+ *  distinct from the repo-level {@link SelfReviewContext}. */
+export function buildSelfReviewPredictedGateInput(diffState) {
+    return {
+        repoFullName: diffState.repoFullName,
+        contributorLogin: diffState.contributorLogin,
+        title: diffState.title,
+        ...(diffState.body !== undefined ? { body: diffState.body } : {}),
+        ...(diffState.labels !== undefined ? { labels: diffState.labels } : {}),
+        ...(diffState.linkedIssues !== undefined ? { linkedIssues: diffState.linkedIssues } : {}),
+        ...(diffState.authorAssociation !== undefined ? { authorAssociation: diffState.authorAssociation } : {}),
+    };
+}
+/** The real changed file paths from the diff, for the `changedPaths` argument `buildPredictedGateVerdict`
+ *  needs to evaluate path-dependent checks (focus-manifest path policy, path-gated pre-merge checks, the
+ *  file-count size/guardrail hold). Omitting them silently under-predicts per predicted-gate.ts's own
+ *  `PREDICTED_GATE_NOTE_NO_PATHS` disclaimer -- a dangerous false-confidence bug if the miner's own loop
+ *  relied on an omitted-paths call. `runSelfReview` below always threads this through; it is exported
+ *  separately so a caller assembling `SelfReviewContext` can also see the exact same path list if needed. */
+export function buildSelfReviewChangedPaths(diffState) {
+    return diffState.changedFiles.map((file) => file.path);
+}
+/** Build the slop-assessment input from the diff state + context, mirroring `SlopAssessmentInput` exactly. */
+export function buildSelfReviewSlopInput(diffState, context) {
+    return {
+        changedFiles: diffState.changedFiles,
+        testFiles: diffState.testFiles,
+        description: diffState.body ?? null,
+        commitMessages: diffState.commitMessages,
+        inDuplicateCluster: context.inDuplicateCluster,
+        hasLinkedIssue: (diffState.linkedIssues?.length ?? 0) > 0,
+        issueDiscoveryLane: diffState.issueDiscoveryLane,
+    };
+}
+/**
+ * Run the full self-review pass for one iteration: build the predicted-gate + slop inputs from the attempt's
+ * diff state, call `buildPredictedGateVerdict` with the caller-supplied repo-level context (`changedPaths`
+ * ALWAYS threaded through explicitly, never omitted), run the injected slop assessment, and combine into one
+ * verdict.
+ */
+export function runSelfReview(diffState, context, deps) {
+    const changedPaths = buildSelfReviewChangedPaths(diffState);
+    const predictedGateVerdict = buildPredictedGateVerdict({
+        input: buildSelfReviewPredictedGateInput(diffState),
+        manifest: context.manifest,
+        repo: context.repo,
+        issues: context.issues,
+        pullRequests: context.pullRequests,
+        ...(context.bounties !== undefined ? { bounties: context.bounties } : {}),
+        ...(context.issueQuality !== undefined ? { issueQuality: context.issueQuality } : {}),
+        ...(context.confirmedContributor !== undefined ? { confirmedContributor: context.confirmedContributor } : {}),
+        changedPaths,
+    });
+    const slopAssessment = deps.runSlopAssessment(buildSelfReviewSlopInput(diffState, context));
+    return {
+        predictedGateVerdict,
+        slopAssessment,
+        changedPaths,
+        passesPredictedGate: isClearPass(predictedGateVerdict.conclusion),
+    };
+}

package/dist/miner/submission-gate.d.ts

@@ -0,0 +1,40 @@
+import { type MinerKillSwitchScope } from "../governor/kill-switch.js";
+import type { PredictedGateVerdict } from "../predicted-gate.js";
+import type { SelfReviewSlopAssessment, SelfReviewSlopBand } from "./self-review-adapter.js";
+/** The one literal conclusion value that counts as a clear predicted-gate pass -- same literal self-review-
+ *  adapter.ts's `SELF_REVIEW_PASSING_CONCLUSION` uses, kept as an independent constant here so this module has
+ *  no runtime dependency beyond types on self-review-adapter.ts. */
+export declare const SUBMISSION_GATE_PASSING_CONCLUSION: "success";
+/** True when `band` is at or under `threshold`'s severity (inclusive) -- e.g. a `"low"` band is within a
+ *  `"elevated"` threshold, and a band exactly equal to the threshold still passes. */
+export declare function isSlopBandWithinThreshold(band: SelfReviewSlopBand, threshold: SelfReviewSlopBand): boolean;
+/** `"observe"` mirrors `AUTONOMY_LEVELS`' deny-by-default floor: {@link shouldSubmit} still computes and
+ *  returns the real signal-based decision (for logging), but structurally forces `allow: false` regardless --
+ *  not left to an external caller to remember to also check the mode before acting on `allow: true`. */
+export type SubmissionGateMode = "observe" | "enforce";
+export type SubmissionGateCandidate = {
+    /** Checked FIRST, before any other field below -- see the module doc comment's KILL-SWITCH section. */
+    killSwitchScope: MinerKillSwitchScope;
+    /** `null` means the predictor was unreachable or errored -- fails closed, exactly like a genuine non-passing
+     *  verdict, never treated as "no opinion, so allow". */
+    predictedGateVerdict: PredictedGateVerdict | null;
+    /** `null` means the slop check errored -- fails closed, exactly like a genuine over-threshold assessment. */
+    slopAssessment: SelfReviewSlopAssessment | null;
+    /** The maximum slop band that still permits submission (inclusive of this exact band). */
+    slopThreshold: SelfReviewSlopBand;
+    mode: SubmissionGateMode;
+};
+export type SubmissionGateDecision = {
+    allow: boolean;
+    /** Always populated when `allow` is `false` (including in `"observe"` mode, prefixed to distinguish a
+     *  would-have-allowed dry-run from a real block) -- every decision is auditable, not just denials. */
+    reasons: string[];
+};
+/**
+ * THE gate: build (or invoke) `gittensory_open_pr`'s action spec ONLY when this returns `allow: true`. Requires
+ * BOTH a clean predicted-gate pass AND a slop band at or under the configured threshold; any missing signal, or
+ * `mode: "observe"`, forces `allow: false`. The kill-switch is checked FIRST, before any other logic -- an
+ * active kill-switch blocks unconditionally, regardless of otherwise-passing signals. Pure; identical inputs
+ * always yield the identical decision.
+ */
+export declare function shouldSubmit(candidate: SubmissionGateCandidate): SubmissionGateDecision;

package/dist/miner/submission-gate.js

@@ -0,0 +1,89 @@
+// Gated-submission trigger (#2336): THE safety-critical chokepoint of Phase 4 -- the actual decision point
+// that decides "call gittensory_open_pr NOW" for an autonomous run. Conservatively requires BOTH a predicted-
+// gate PASS AND a slop score under a configurable threshold before a local-write open_pr action spec is ever
+// built. Any ambiguity (a missing/errored signal) resolves to NOT submitting -- this function never defaults
+// to allow.
+//
+// SEQUENCING: runs BEFORE `buildOpenPrSpec` (src/mcp/local-write-tools.ts) is ever called -- i.e. before the
+// Governor chokepoint (#2340) ever sees an open_pr action spec to evaluate. The two are complementary, not
+// redundant: this gates on CONTENT-QUALITY signals (predicted-gate conclusion, slop risk) specific to the
+// candidate diff; the chokepoint gates on RESOURCE/GOVERNANCE signals (rate-limit, budget, reputation, self-
+// plagiarism, dry-run mode) that apply to every write action class, not just open_pr. "The actual call site
+// invoking buildOpenPrSpec / gittensory_open_pr is gated exclusively through this function" (this issue's own
+// deliverable) is a POLICY this and every future call site must honor -- wiring a real call site is a later,
+// separate issue (mirrors #2333/#2335's own split between loop mechanics and policy).
+//
+// INPUT SHAPE: `predictedGateVerdict`/`slopAssessment` are typed exactly as the fields `SelfReviewVerdict`
+// (self-review-adapter.ts, #2334) already carries, so a caller can pass the SAME verdict the iterate-loop's
+// own self-review (#2333) already computed at handoff time -- this is a defense-in-depth RE-CHECK of that
+// verdict immediately before submission, not a redundant re-computation from scratch.
+//
+// DRY-RUN: mirrors `src/settings/autonomy.ts`'s deny-by-default dial (`AUTONOMY_LEVELS`, `"observe"` as the
+// floor) for safe rollout of THIS function's own thresholds -- distinct from, and evaluated separately from,
+// the Governor chokepoint's own dry-run/live action-mode dial (#2342), which gates autonomous WRITING at all
+// for a repo. `"observe"` here is specifically for safely calibrating the predicted-gate/slop thresholds
+// against live traffic before ever trusting them to gate a real submission.
+//
+// KILL-SWITCH (#2339): checked FIRST, before any other logic -- flipping the kill-switch must halt this
+// chokepoint immediately, the same way it halts the Governor chokepoint (#2340). Reuses
+// `isMinerKillSwitchActive` (kill-switch.ts, #2341) directly rather than a bespoke wrapper -- the exact "single
+// shared helper, not duplicated per call site" #2339's own deliverable calls for; `loop-reentry-policy.ts`'s
+// `shouldReenter` consults the identical function. `killSwitchScope` is REQUIRED (not optional-with-a-
+// permissive-default) so a caller cannot forget to resolve and pass it -- the same fail-closed-by-construction
+// discipline as every other required field here.
+import { isMinerKillSwitchActive } from "../governor/kill-switch.js";
+/** The one literal conclusion value that counts as a clear predicted-gate pass -- same literal self-review-
+ *  adapter.ts's `SELF_REVIEW_PASSING_CONCLUSION` uses, kept as an independent constant here so this module has
+ *  no runtime dependency beyond types on self-review-adapter.ts. */
+export const SUBMISSION_GATE_PASSING_CONCLUSION = "success";
+const SLOP_BAND_SEVERITY = Object.freeze({
+    clean: 0,
+    low: 1,
+    elevated: 2,
+    high: 3,
+});
+/** True when `band` is at or under `threshold`'s severity (inclusive) -- e.g. a `"low"` band is within a
+ *  `"elevated"` threshold, and a band exactly equal to the threshold still passes. */
+export function isSlopBandWithinThreshold(band, threshold) {
+    return SLOP_BAND_SEVERITY[band] <= SLOP_BAND_SEVERITY[threshold];
+}
+/** The pure signal check, independent of `mode` -- {@link shouldSubmit} layers the observe/enforce dial on
+ *  top of this. Returns an empty array only when BOTH signals genuinely pass. */
+function evaluateSubmissionSignals(candidate) {
+    const reasons = [];
+    if (candidate.predictedGateVerdict === null) {
+        reasons.push("predicted_gate_unavailable");
+    }
+    else if (candidate.predictedGateVerdict.conclusion !== SUBMISSION_GATE_PASSING_CONCLUSION) {
+        const blockerCodes = candidate.predictedGateVerdict.blockers.map((blocker) => blocker.code).join(",");
+        reasons.push(`predicted_gate_not_passing:${candidate.predictedGateVerdict.conclusion}${blockerCodes ? `:${blockerCodes}` : ""}`);
+    }
+    if (candidate.slopAssessment === null) {
+        reasons.push("slop_assessment_unavailable");
+    }
+    else if (!isSlopBandWithinThreshold(candidate.slopAssessment.band, candidate.slopThreshold)) {
+        reasons.push(`slop_band_exceeds_threshold:${candidate.slopAssessment.band}>${candidate.slopThreshold}`);
+    }
+    return reasons;
+}
+/**
+ * THE gate: build (or invoke) `gittensory_open_pr`'s action spec ONLY when this returns `allow: true`. Requires
+ * BOTH a clean predicted-gate pass AND a slop band at or under the configured threshold; any missing signal, or
+ * `mode: "observe"`, forces `allow: false`. The kill-switch is checked FIRST, before any other logic -- an
+ * active kill-switch blocks unconditionally, regardless of otherwise-passing signals. Pure; identical inputs
+ * always yield the identical decision.
+ */
+export function shouldSubmit(candidate) {
+    if (isMinerKillSwitchActive(candidate.killSwitchScope)) {
+        return { allow: false, reasons: [`${candidate.killSwitchScope}_kill_switch_active`] };
+    }
+    const reasons = evaluateSubmissionSignals(candidate);
+    const signalsPass = reasons.length === 0;
+    if (candidate.mode === "observe") {
+        return {
+            allow: false,
+            reasons: signalsPass ? ["observe_mode_active:would_have_allowed"] : ["observe_mode_active:would_have_blocked", ...reasons],
+        };
+    }
+    return { allow: signalsPass, reasons };
+}

package/dist/miner/worktree-allocator.d.ts

@@ -0,0 +1,59 @@
+export type WorktreeExecResult = {
+    code: number | null;
+    stdout?: string;
+    stderr?: string;
+};
+/** The injected git exec — a real `child_process` spawn in prod, a fake in tests. */
+export type WorktreeExecFn = (cmd: string, args: readonly string[], opts: {
+    cwd: string;
+}) => Promise<WorktreeExecResult>;
+/** The deterministic worktree location + branch for one attempt. */
+export type WorktreePlan = {
+    attemptId: string;
+    worktreePath: string;
+    branchName: string;
+};
+/** Worktrees live under this dir inside the repo; the branch carries this prefix. */
+export declare const WORKTREE_SUBDIR = ".gittensory-worktrees";
+export declare const WORKTREE_BRANCH_PREFIX = "gittensory/attempt/";
+/**
+ * Compute the deterministic worktree path + branch name for an attempt — keyed on the attempt id, never a random
+ * suffix. Pure. Two concurrent attempts with distinct ids get distinct paths/branches; the same id always maps to
+ * the same location (so a crashed attempt's worktree is identifiable and cleanable).
+ */
+export declare function planWorktree(input: {
+    repoPath: string;
+    attemptId: string;
+}): WorktreePlan;
+export type WorktreeAddResult = {
+    ok: boolean;
+    plan: WorktreePlan;
+    error?: string;
+};
+/**
+ * Create the attempt's isolated worktree via `git worktree add -b <branch> <path> <baseBranch>`, run through the
+ * injected exec. Returns the plan (so the caller knows the path/branch) and, on failure, git's stderr.
+ */
+export declare function addWorktree(input: {
+    exec: WorktreeExecFn;
+    repoPath: string;
+    baseBranch: string;
+    attemptId: string;
+}): Promise<WorktreeAddResult>;
+export type WorktreeRemoveResult = {
+    ok: boolean;
+    removed: boolean;
+    error?: string;
+};
+/** Retention policy: retain a FAILED attempt's worktree for post-mortem, remove a SUCCEEDED attempt's. */
+export declare function shouldRetainWorktree(attemptOk: boolean): boolean;
+/**
+ * Tear down the attempt's worktree via `git worktree remove --force <path>`, through the injected exec. When
+ * `retain` is set the worktree is KEPT (no exec, `removed: false`) for post-mortem — pass `shouldRetainWorktree(ok)`.
+ */
+export declare function removeWorktree(input: {
+    exec: WorktreeExecFn;
+    repoPath: string;
+    worktreePath: string;
+    retain?: boolean;
+}): Promise<WorktreeRemoveResult>;

package/dist/miner/worktree-allocator.js

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+/** Worktrees live under this dir inside the repo; the branch carries this prefix. */
+export const WORKTREE_SUBDIR = ".gittensory-worktrees";
+export const WORKTREE_BRANCH_PREFIX = "gittensory/attempt/";
+const MAX_SLUG_LENGTH = 64;
+/** Deterministically slugify an attempt id into a filesystem- and git-ref-safe token (same id → same slug). */
+function slugifyAttemptId(attemptId) {
+    const slug = attemptId
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "");
+    if (!slug)
+        throw new Error("invalid_attempt_id");
+    return slug.slice(0, MAX_SLUG_LENGTH);
+}
+/**
+ * Compute the deterministic worktree path + branch name for an attempt — keyed on the attempt id, never a random
+ * suffix. Pure. Two concurrent attempts with distinct ids get distinct paths/branches; the same id always maps to
+ * the same location (so a crashed attempt's worktree is identifiable and cleanable).
+ */
+export function planWorktree(input) {
+    const slug = slugifyAttemptId(input.attemptId);
+    return {
+        attemptId: input.attemptId,
+        worktreePath: join(input.repoPath, WORKTREE_SUBDIR, slug),
+        branchName: `${WORKTREE_BRANCH_PREFIX}${slug}`,
+    };
+}
+/**
+ * Create the attempt's isolated worktree via `git worktree add -b <branch> <path> <baseBranch>`, run through the
+ * injected exec. Returns the plan (so the caller knows the path/branch) and, on failure, git's stderr.
+ */
+export async function addWorktree(input) {
+    const plan = planWorktree({ repoPath: input.repoPath, attemptId: input.attemptId });
+    const result = await input.exec("git", ["worktree", "add", "-b", plan.branchName, plan.worktreePath, input.baseBranch], { cwd: input.repoPath });
+    if (result.code === 0)
+        return { ok: true, plan };
+    const detail = (result.stderr ?? "").trim() || `git_worktree_add_exit_${result.code}`;
+    return { ok: false, plan, error: detail };
+}
+/** Retention policy: retain a FAILED attempt's worktree for post-mortem, remove a SUCCEEDED attempt's. */
+export function shouldRetainWorktree(attemptOk) {
+    return !attemptOk;
+}
+/**
+ * Tear down the attempt's worktree via `git worktree remove --force <path>`, through the injected exec. When
+ * `retain` is set the worktree is KEPT (no exec, `removed: false`) for post-mortem — pass `shouldRetainWorktree(ok)`.
+ */
+export async function removeWorktree(input) {
+    if (input.retain)
+        return { ok: true, removed: false };
+    const result = await input.exec("git", ["worktree", "remove", "--force", input.worktreePath], {
+        cwd: input.repoPath,
+    });
+    if (result.code === 0)
+        return { ok: true, removed: true };
+    const detail = (result.stderr ?? "").trim() || `git_worktree_remove_exit_${result.code}`;
+    return { ok: false, removed: false, error: detail };
+}

package/dist/miner/worktree-pool.d.ts

@@ -0,0 +1,55 @@
+import { type WorktreePlan } from "./worktree-allocator.js";
+/** One live allocation: which attempt holds which planned worktree. */
+export type WorktreeAllocation = {
+    attemptId: string;
+    repoPath: string;
+    plan: WorktreePlan;
+};
+/** The pool's whole allocation state — a serializable snapshot the persistence wrapper stores. */
+export type WorktreePoolState = {
+    allocations: readonly WorktreeAllocation[];
+};
+export type WorktreePoolConfig = {
+    /** Maximum concurrent worktrees. A non-positive cap allocates nothing. */
+    maxConcurrency: number;
+};
+/** The empty pool — nothing allocated. */
+export declare const EMPTY_WORKTREE_POOL: WorktreePoolState;
+export type AcquireWorktreeResult = {
+    ok: true;
+    state: WorktreePoolState;
+    allocation: WorktreeAllocation;
+} | {
+    ok: false;
+    reason: "already_allocated" | "at_capacity";
+    state: WorktreePoolState;
+};
+/** True when `attemptId` currently holds an allocation. Pure. */
+export declare function isWorktreeAllocated(state: WorktreePoolState, attemptId: string): boolean;
+/** Slots still available before the concurrency cap (never negative). Pure. */
+export declare function availableWorktreeSlots(state: WorktreePoolState, config: WorktreePoolConfig): number;
+/**
+ * Acquire a worktree slot for an attempt. The slot's path/branch is derived deterministically from the
+ * attempt id via {@link planWorktree}. Fails WITHOUT mutating when the attempt already holds a slot
+ * (`already_allocated`, idempotency guard) or the pool is at its concurrency cap (`at_capacity`). Pure —
+ * returns a new state on success.
+ */
+export declare function acquireWorktree(state: WorktreePoolState, config: WorktreePoolConfig, input: {
+    attemptId: string;
+    repoPath: string;
+}): AcquireWorktreeResult;
+/**
+ * Release an attempt's slot, freeing it for reuse. Pure and idempotent — releasing an attempt that holds no
+ * slot returns an equivalent state. The caller tears down the actual worktree (via the primitive) separately.
+ */
+export declare function releaseWorktree(state: WorktreePoolState, attemptId: string): WorktreePoolState;
+/**
+ * Reclaim orphaned slots: free every allocation whose attempt is no longer in the live set (e.g. after a crash
+ * left the bookkeeping ahead of reality). Returns the surviving state plus the reclaimed allocations so the
+ * caller can tear down their leaked worktrees (or flag them for manual cleanup) rather than leaking forever.
+ * Pure.
+ */
+export declare function reclaimOrphanedWorktrees(state: WorktreePoolState, liveAttemptIds: Iterable<string>): {
+    state: WorktreePoolState;
+    reclaimed: WorktreeAllocation[];
+};

package/dist/miner/worktree-pool.js

@@ -0,0 +1,65 @@
+// Git-worktree POOL allocator (#4297): the pure, in-memory scheduling logic for a POOL of per-attempt git
+// worktrees across concurrent fleet attempts — acquire/release under a concurrency cap, plus orphan
+// reclamation. Complementary to the isolation PRIMITIVE (worktree-allocator.ts, #4269), which plans/creates/
+// tears down ONE worktree; this manages the SET of them so two concurrent attempts never collide and a crash
+// can't leak worktree slots forever.
+//
+// Per #4297, the pure allocation logic lives here in gittensory-engine so it is unit-testable WITHOUT touching
+// a real filesystem or database. The thin bookkeeping wrapper that PERSISTS this state (local SQLite, the same
+// way claim-ledger.js / run-state.js do) is a separate miner-package layer — it holds a WorktreePoolState,
+// calls these pure transitions, and writes the result back. No IO here: every function takes state in and
+// returns new state out.
+import { planWorktree } from "./worktree-allocator.js";
+/** The empty pool — nothing allocated. */
+export const EMPTY_WORKTREE_POOL = { allocations: [] };
+/** True when `attemptId` currently holds an allocation. Pure. */
+export function isWorktreeAllocated(state, attemptId) {
+    return state.allocations.some((allocation) => allocation.attemptId === attemptId);
+}
+/** Slots still available before the concurrency cap (never negative). Pure. */
+export function availableWorktreeSlots(state, config) {
+    return Math.max(0, config.maxConcurrency - state.allocations.length);
+}
+/**
+ * Acquire a worktree slot for an attempt. The slot's path/branch is derived deterministically from the
+ * attempt id via {@link planWorktree}. Fails WITHOUT mutating when the attempt already holds a slot
+ * (`already_allocated`, idempotency guard) or the pool is at its concurrency cap (`at_capacity`). Pure —
+ * returns a new state on success.
+ */
+export function acquireWorktree(state, config, input) {
+    if (isWorktreeAllocated(state, input.attemptId)) {
+        return { ok: false, reason: "already_allocated", state };
+    }
+    if (state.allocations.length >= config.maxConcurrency) {
+        return { ok: false, reason: "at_capacity", state };
+    }
+    const allocation = {
+        attemptId: input.attemptId,
+        repoPath: input.repoPath,
+        plan: planWorktree({ repoPath: input.repoPath, attemptId: input.attemptId }),
+    };
+    return { ok: true, state: { allocations: [...state.allocations, allocation] }, allocation };
+}
+/**
+ * Release an attempt's slot, freeing it for reuse. Pure and idempotent — releasing an attempt that holds no
+ * slot returns an equivalent state. The caller tears down the actual worktree (via the primitive) separately.
+ */
+export function releaseWorktree(state, attemptId) {
+    const allocations = state.allocations.filter((allocation) => allocation.attemptId !== attemptId);
+    return allocations.length === state.allocations.length ? state : { allocations };
+}
+/**
+ * Reclaim orphaned slots: free every allocation whose attempt is no longer in the live set (e.g. after a crash
+ * left the bookkeeping ahead of reality). Returns the surviving state plus the reclaimed allocations so the
+ * caller can tear down their leaked worktrees (or flag them for manual cleanup) rather than leaking forever.
+ * Pure.
+ */
+export function reclaimOrphanedWorktrees(state, liveAttemptIds) {
+    const live = new Set(liveAttemptIds);
+    const reclaimed = [];
+    const remaining = [];
+    for (const allocation of state.allocations) {
+        (live.has(allocation.attemptId) ? remaining : reclaimed).push(allocation);
+    }
+    return { state: reclaimed.length === 0 ? state : { allocations: remaining }, reclaimed };
+}

package/dist/miner-goal-lane-fit.d.ts

@@ -0,0 +1,18 @@
+import type { MinerGoalSpec } from "./miner-goal-spec.js";
+/** Whether a repo's miner goal spec permits autonomous targeting (explicit opt-out only). */
+export declare function isMinerRepoTargetable(spec: MinerGoalSpec): boolean;
+/**
+ * Compute a [0, 1] lane-fit score from issue labels and a parsed {@link MinerGoalSpec}. Path-based fit is
+ * intentionally omitted — discovery metadata has labels only; path gating belongs in the analyze phase.
+ */
+export declare function computeMinerGoalLaneFit(issue: {
+    labels: readonly string[];
+}, spec: MinerGoalSpec): number;
+/**
+ * Lane-fit for metadata-ranked issues. Uses full path+label {@link computeLaneFit} when
+ * `candidatePaths` are present; otherwise falls back to label-only {@link computeMinerGoalLaneFit}.
+ */
+export declare function computeMetadataLaneFit(issue: {
+    labels: readonly string[];
+    candidatePaths?: readonly string[] | undefined;
+}, spec: MinerGoalSpec): number;