@loopover/engine 1.0.0

package/dist/governor/action-mode.d.ts

@@ -0,0 +1,55 @@
+import type { GovernorLedgerEvent } from "../governor-ledger.js";
+import { type MinerKillSwitchScope } from "./kill-switch.js";
+/** Whether the miner actually executes a write, only shadow-logs what it WOULD do, or is halted entirely. */
+export type MinerActionMode = "paused" | "dry_run" | "live";
+/**
+ * The ONLY value that opts a miner into LIVE write execution. Deliberately a specific string literal, not a
+ * boolean -- a fat-fingered `liveModeOptIn: true`, `"yes"`, `"on"`, or `GITTENSORY_MINER_LIVE_MODE=1` must never
+ * accidentally unlock writes the way a truthy-coerced flag could. Per the issue's explicit requirement: "not a
+ * generic boolean flag that could be accidentally true."
+ */
+export declare const MINER_LIVE_MODE_OPT_IN = "live";
+/** Env var an operator sets (to exactly {@link MINER_LIVE_MODE_OPT_IN}) to opt their own miner instance into
+ *  live write execution. Repo-side opt-in alone is never enough to execute writes. */
+export declare const MINER_LIVE_MODE_ENV_VAR = "GITTENSORY_MINER_LIVE_MODE";
+/** True only when `value` is EXACTLY the {@link MINER_LIVE_MODE_OPT_IN} string -- no truthy coercion, no case
+ *  folding, no alternate spellings. Everything else (including `true`, `"Live"`, `"1"`) reads as not opted in. */
+export declare function isExplicitMinerLiveModeOptIn(value: unknown): boolean;
+/** True when the operator's global env-level live-mode opt-in is set to exactly {@link MINER_LIVE_MODE_OPT_IN}. */
+export declare function isGlobalMinerLiveModeOptIn(env: Record<string, string | undefined>): boolean;
+/**
+ * Resolve the miner's overall action mode. Precedence (safest wins, mirroring `resolveAgentActionMode`):
+ * 1. Kill-switch active (either scope, #2341) -> `"paused"` -- always wins, regardless of any live-mode opt-in.
+ * 2. BOTH the operator's global env config AND the target repo's own `.gittensory-miner.yml`
+ *    (`MinerGoalSpec.execution.liveModeOptIn`) explicitly opt in -> `"live"`. The repo field is a repo-side
+ *    allowance, not an operator-authored authorization to execute writes under the miner's credentials.
+ * 3. Otherwise -> `"dry_run"`. No config anywhere, either side omitted, or a malformed/partial config that fails
+ *    to normalize to the exact opt-in literal, all fall through to this branch -- absence or ambiguity always
+ *    means dry-run.
+ *
+ * A target repo that wants to guarantee it never receives live automated writes -- even from an operator whose
+ * own miner instance is globally live -- can omit its repo opt-in or set its OWN kill-switch (`killSwitch.paused:
+ * true`, #2341), which takes precedence over any live-mode opt-in per step 1 above.
+ */
+export declare function resolveMinerActionMode(input: {
+    killSwitchScope: MinerKillSwitchScope;
+    repoLiveModeOptIn?: unknown;
+    globalLiveModeOptIn: boolean;
+}): MinerActionMode;
+/** True only for `"live"` -- the only mode that performs a real write. `"paused"` does nothing; `"dry_run"`
+ *  records a shadow action but never mutates. */
+export declare function minerActionModeExecutes(mode: MinerActionMode): boolean;
+/**
+ * Governor-ledger row for a dry-run SHADOW action (#2342's "logs the WOULD-BE action... without ever invoking
+ * the actual command" deliverable). `eventType` stays within the existing closed vocabulary (`"allowed"` -- the
+ * Governor's other checks did not deny this action, dry-run mode is simply choosing to shadow-log instead of
+ * execute); `decision: "dry_run"` is the distinct marker this deliverable calls for. `wouldBeAction` is left as
+ * a generic record (not the concrete `LocalWriteActionSpec` type) so this package stays decoupled from the
+ * main app's `src/mcp/local-write-tools.ts` -- the caller wiring a real action spec into this call owns that
+ * shape.
+ */
+export declare function buildMinerDryRunGovernorLedgerEvent(input: {
+    repoFullName?: string | null | undefined;
+    actionClass: string;
+    wouldBeAction: Record<string, unknown>;
+}): GovernorLedgerEvent;

package/dist/governor/action-mode.js

@@ -0,0 +1,74 @@
+// Governor dry-run-by-default enforcement (#2342): resolves the miner's overall action mode -- "safest wins"
+// precedence mirroring `resolveAgentActionMode` (`src/settings/agent-execution.ts`): paused > dry_run > live.
+// A freshly-configured miner (no opt-in present anywhere) MUST default to dry_run, never live -- this is the
+// deny-by-default floor `src/settings/autonomy.ts`'s `DEFAULT_AUTONOMY_LEVEL = "observe"` establishes for the
+// review-stack, extended here to the miner's own runtime.
+//
+// DETECTOR ONLY -- no IO, no persistence. Consulting this alongside the other pure calculators (rate-limit,
+// budget caps, reputation, self-plagiarism, non-convergence) and recording every CHECK is the Governor
+// chokepoint's job (#2340), which consults this module (after the kill-switch) in its precedence ladder.
+import { isMinerKillSwitchActive } from "./kill-switch.js";
+/**
+ * The ONLY value that opts a miner into LIVE write execution. Deliberately a specific string literal, not a
+ * boolean -- a fat-fingered `liveModeOptIn: true`, `"yes"`, `"on"`, or `GITTENSORY_MINER_LIVE_MODE=1` must never
+ * accidentally unlock writes the way a truthy-coerced flag could. Per the issue's explicit requirement: "not a
+ * generic boolean flag that could be accidentally true."
+ */
+export const MINER_LIVE_MODE_OPT_IN = "live";
+/** Env var an operator sets (to exactly {@link MINER_LIVE_MODE_OPT_IN}) to opt their own miner instance into
+ *  live write execution. Repo-side opt-in alone is never enough to execute writes. */
+export const MINER_LIVE_MODE_ENV_VAR = "GITTENSORY_MINER_LIVE_MODE";
+/** True only when `value` is EXACTLY the {@link MINER_LIVE_MODE_OPT_IN} string -- no truthy coercion, no case
+ *  folding, no alternate spellings. Everything else (including `true`, `"Live"`, `"1"`) reads as not opted in. */
+export function isExplicitMinerLiveModeOptIn(value) {
+    return value === MINER_LIVE_MODE_OPT_IN;
+}
+/** True when the operator's global env-level live-mode opt-in is set to exactly {@link MINER_LIVE_MODE_OPT_IN}. */
+export function isGlobalMinerLiveModeOptIn(env) {
+    return env[MINER_LIVE_MODE_ENV_VAR] === MINER_LIVE_MODE_OPT_IN;
+}
+/**
+ * Resolve the miner's overall action mode. Precedence (safest wins, mirroring `resolveAgentActionMode`):
+ * 1. Kill-switch active (either scope, #2341) -> `"paused"` -- always wins, regardless of any live-mode opt-in.
+ * 2. BOTH the operator's global env config AND the target repo's own `.gittensory-miner.yml`
+ *    (`MinerGoalSpec.execution.liveModeOptIn`) explicitly opt in -> `"live"`. The repo field is a repo-side
+ *    allowance, not an operator-authored authorization to execute writes under the miner's credentials.
+ * 3. Otherwise -> `"dry_run"`. No config anywhere, either side omitted, or a malformed/partial config that fails
+ *    to normalize to the exact opt-in literal, all fall through to this branch -- absence or ambiguity always
+ *    means dry-run.
+ *
+ * A target repo that wants to guarantee it never receives live automated writes -- even from an operator whose
+ * own miner instance is globally live -- can omit its repo opt-in or set its OWN kill-switch (`killSwitch.paused:
+ * true`, #2341), which takes precedence over any live-mode opt-in per step 1 above.
+ */
+export function resolveMinerActionMode(input) {
+    if (isMinerKillSwitchActive(input.killSwitchScope))
+        return "paused";
+    if (input.globalLiveModeOptIn && isExplicitMinerLiveModeOptIn(input.repoLiveModeOptIn))
+        return "live";
+    return "dry_run";
+}
+/** True only for `"live"` -- the only mode that performs a real write. `"paused"` does nothing; `"dry_run"`
+ *  records a shadow action but never mutates. */
+export function minerActionModeExecutes(mode) {
+    return mode === "live";
+}
+/**
+ * Governor-ledger row for a dry-run SHADOW action (#2342's "logs the WOULD-BE action... without ever invoking
+ * the actual command" deliverable). `eventType` stays within the existing closed vocabulary (`"allowed"` -- the
+ * Governor's other checks did not deny this action, dry-run mode is simply choosing to shadow-log instead of
+ * execute); `decision: "dry_run"` is the distinct marker this deliverable calls for. `wouldBeAction` is left as
+ * a generic record (not the concrete `LocalWriteActionSpec` type) so this package stays decoupled from the
+ * main app's `src/mcp/local-write-tools.ts` -- the caller wiring a real action spec into this call owns that
+ * shape.
+ */
+export function buildMinerDryRunGovernorLedgerEvent(input) {
+    return {
+        eventType: "allowed",
+        repoFullName: input.repoFullName ?? null,
+        actionClass: input.actionClass,
+        decision: "dry_run",
+        reason: "dry_run_mode_active",
+        payload: { wouldBeAction: input.wouldBeAction },
+    };
+}

package/dist/governor/budget-cap.d.ts

@@ -0,0 +1,49 @@
+import type { GovernorLedgerEventType } from "../governor-ledger.js";
+/** The three independent ceilings for a whole run. A dimension with a ceiling of 0 permits no usage at all
+ *  (any usage reaches it), mirroring rate-limit.ts treating `limit: 0` as "nothing allowed". */
+export type GovernorCapLimits = {
+    /** Maximum cumulative budget/cost units permitted for the run (may be fractional, e.g. a dollar cost). */
+    budget: number;
+    /** Maximum cumulative turns/iterations permitted for the run (whole counts). */
+    turns: number;
+    /** Termination ceiling: maximum elapsed session time in milliseconds. */
+    elapsedMs: number;
+};
+/** A run's cumulative usage so far. Caller-supplied — this module never reads a clock or a meter itself. */
+export type GovernorCapUsage = {
+    /** Budget/cost already spent this run. */
+    budgetSpent: number;
+    /** Turns/iterations already taken this run. */
+    turnsTaken: number;
+    /** Elapsed session time so far in milliseconds. */
+    elapsedMs: number;
+};
+/** One dimension's evaluation. `remaining` is headroom before the ceiling and is never negative. */
+export type GovernorCapDimension = {
+    /** The normalized ceiling for this dimension. */
+    limit: number;
+    /** The normalized usage measured against that ceiling. */
+    used: number;
+    /** Headroom left before the ceiling (0 once reached; never negative). */
+    remaining: number;
+    /** True once usage has reached OR passed the ceiling. */
+    exceeded: boolean;
+};
+/** The combined report. `verdict` is drawn from GOVERNOR_LEDGER_EVENT_TYPES (not a parallel vocabulary) so it
+ *  aligns with the events the governor-ledger records: `allowed` (all caps clear), `denied` (a budget/turn cap
+ *  reached), or `kill_switch` (the termination ceiling reached — a hard wall-clock stop). */
+export type GovernorCapReport = {
+    verdict: GovernorLedgerEventType;
+    budget: GovernorCapDimension;
+    turns: GovernorCapDimension;
+    termination: GovernorCapDimension;
+};
+/**
+ * Evaluate a run's cumulative usage against its budget/turn/termination ceilings. Pure: it reads the two typed
+ * inputs and returns a report without mutating anything or reading a clock. Each dimension is normalized and
+ * evaluated independently, then combined into one verdict — termination (a hard wall-clock ceiling) is the most
+ * severe (`kill_switch`), a reached budget or turn ceiling is `denied`, and everything clear is `allowed`.
+ * Every numeric input is normalized first, so a non-finite, negative, or fractional value can never produce a
+ * NaN verdict or a negative remaining-budget/turns value.
+ */
+export declare function evaluateGovernorCaps(usage: GovernorCapUsage, limits: GovernorCapLimits): GovernorCapReport;

package/dist/governor/budget-cap.js

@@ -0,0 +1,34 @@
+// Normalize any numeric input to a finite, non-negative value (a non-finite or negative value becomes 0), so no
+// input can make a verdict NaN or a remaining value negative. Mirrors rate-limit.ts's finiteNonNegativeInt but
+// keeps fractional precision for continuous dimensions (budget cost, elapsed milliseconds).
+function finiteNonNegative(value) {
+    return Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+// Integer variant for the turn-count dimension (turns are whole iterations), matching rate-limit.ts exactly.
+function finiteNonNegativeInt(value) {
+    return Number.isFinite(value) ? Math.max(0, Math.floor(value)) : 0;
+}
+// Evaluate one dimension: usage reaching or passing the ceiling is `exceeded`, and headroom is clamped at 0 so
+// it can never go negative. Both operands are already normalized by the caller.
+function evaluateDimension(used, limit) {
+    return { limit, used, remaining: Math.max(0, limit - used), exceeded: used >= limit };
+}
+/**
+ * Evaluate a run's cumulative usage against its budget/turn/termination ceilings. Pure: it reads the two typed
+ * inputs and returns a report without mutating anything or reading a clock. Each dimension is normalized and
+ * evaluated independently, then combined into one verdict — termination (a hard wall-clock ceiling) is the most
+ * severe (`kill_switch`), a reached budget or turn ceiling is `denied`, and everything clear is `allowed`.
+ * Every numeric input is normalized first, so a non-finite, negative, or fractional value can never produce a
+ * NaN verdict or a negative remaining-budget/turns value.
+ */
+export function evaluateGovernorCaps(usage, limits) {
+    const budget = evaluateDimension(finiteNonNegative(usage.budgetSpent), finiteNonNegative(limits.budget));
+    const turns = evaluateDimension(finiteNonNegativeInt(usage.turnsTaken), finiteNonNegativeInt(limits.turns));
+    const termination = evaluateDimension(finiteNonNegative(usage.elapsedMs), finiteNonNegative(limits.elapsedMs));
+    const verdict = termination.exceeded
+        ? "kill_switch"
+        : budget.exceeded || turns.exceeded
+            ? "denied"
+            : "allowed";
+    return { verdict, budget, turns, termination };
+}

package/dist/governor/chokepoint.d.ts

@@ -0,0 +1,58 @@
+import type { GovernorLedgerEvent } from "../governor-ledger.js";
+import type { PortfolioConvergenceInput, PortfolioConvergenceThresholds, PortfolioConvergenceVerdict } from "../portfolio/non-convergence.js";
+import { type MinerActionMode } from "./action-mode.js";
+import type { GovernorCapLimits, GovernorCapReport, GovernorCapUsage } from "./budget-cap.js";
+import { type MinerKillSwitchScope } from "./kill-switch.js";
+import type { RepoOutcomeHistory, SelfReputationThresholds, SelfReputationThrottleDecision } from "./reputation-throttle.js";
+import type { OwnSubmissionRecord, SelfPlagiarismCandidate, SelfPlagiarismConfig, SelfPlagiarismVerdict } from "./self-plagiarism.js";
+import type { WriteRateLimitBackoffStore, WriteRateLimitBucketStore, WriteRateLimitPolicies, WriteRateLimitVerdict } from "./write-rate-limit.js";
+/** Which stage of the precedence ladder produced the final verdict. */
+export type GovernorDecisionStage = "kill_switch" | "dry_run" | "rate_limit" | "budget_cap" | "non_convergence" | "reputation_throttle" | "self_plagiarism" | "allow" | "internal_error";
+export type GovernorChokepointInput = {
+    actionClass: string;
+    repoFullName: string;
+    nowMs: number;
+    /** Full would-be action spec, logged verbatim on a dry-run shadow (#2342) or a final denial's audit payload. */
+    wouldBeAction: Record<string, unknown>;
+    killSwitchGlobal: boolean;
+    killSwitchRepoPaused?: boolean | null | undefined;
+    liveModeGlobalOptIn: boolean;
+    liveModeRepoOptIn?: unknown;
+    rateLimitBuckets: WriteRateLimitBucketStore;
+    rateLimitBackoffAttempts: WriteRateLimitBackoffStore;
+    rateLimitPolicies?: WriteRateLimitPolicies | undefined;
+    rateLimitRandomFn?: (() => number) | undefined;
+    capUsage: GovernorCapUsage;
+    capLimits: GovernorCapLimits;
+    convergenceInput: PortfolioConvergenceInput;
+    convergenceThresholds?: PortfolioConvergenceThresholds | undefined;
+    reputationHistory?: RepoOutcomeHistory | undefined;
+    reputationThresholds?: SelfReputationThresholds | undefined;
+    selfPlagiarismCandidate?: SelfPlagiarismCandidate | undefined;
+    selfPlagiarismRecentSubmissions?: readonly OwnSubmissionRecord[] | undefined;
+    selfPlagiarismConfig?: SelfPlagiarismConfig | undefined;
+};
+export type GovernorDecisionDetail = {
+    killSwitchScope: MinerKillSwitchScope;
+    mode: MinerActionMode;
+    rateLimit?: WriteRateLimitVerdict;
+    budgetCap?: GovernorCapReport;
+    convergence?: PortfolioConvergenceVerdict;
+    reputation?: SelfReputationThrottleDecision;
+    selfPlagiarism?: SelfPlagiarismVerdict;
+};
+export type GovernorDecision = {
+    /** True only when every consulted stage allowed AND the resolved mode is `"live"`. */
+    allowed: boolean;
+    mode: MinerActionMode;
+    stage: GovernorDecisionStage;
+    reason: string;
+    detail: GovernorDecisionDetail;
+    /** The single row to append to the governor ledger for this chokepoint invocation. */
+    ledgerEvent: GovernorLedgerEvent;
+};
+/**
+ * Evaluate every write action against the full precedence ladder and return one fail-closed verdict. See the
+ * module doc comment for the exact stage order and which stages are conditional on `actionClass`.
+ */
+export declare function evaluateGovernorChokepoint(input: GovernorChokepointInput): GovernorDecision;

package/dist/governor/chokepoint.js

@@ -0,0 +1,269 @@
+// The Governor chokepoint (#2340): the single fail-closed decision point every miner write action MUST pass
+// through before executing a `LocalWriteActionSpec` (`src/mcp/local-write-tools.ts`: open_pr, file_issue,
+// apply_labels, post_eligibility_comment, create_branch, delete_branch, generate_tests). This composes the
+// previously-built pure calculators into one verdict -- it is the reason Phase 5 exists.
+//
+// PRECEDENCE ("safest wins", mirroring `resolveAgentActionMode` in `src/settings/agent-execution.ts`):
+//   global kill-switch > per-repo pause > dry-run > rate-limit > budget/turn/termination cap > non-convergence
+//   > self-reputation throttle > self-plagiarism > allow.
+// The issue's own deliverable names rate-limit, budget caps, and non-convergence explicitly. This module also
+// composes self-reputation-throttle and self-plagiarism, per those two calculators' OWN doc comments
+// (`reputation-throttle.ts`: "the chokepoint can record WHY a submission cadence was scaled"; `self-plagiarism.ts`:
+// "the Governor open_pr chokepoint (#2340) composes this verdict with rate-limit, budget caps, and
+// non-convergence") -- both already ship a `*LedgerEvent` builder keyed on their own boolean
+// throttled/allowed field, so composing them here reuses an existing, already-reviewed gate semantic rather
+// than inventing a new one. Both are evaluated only for `actionClass === "open_pr"` (their own ledger builders
+// hardcode/scope to PR submissions; a label-apply or branch-delete has no diff fingerprint or "submission
+// cadence" to throttle).
+//
+// FAIL CLOSED: any stage that throws (malformed caller input escaping this module's typed boundary) denies
+// immediately with `stage: "internal_error"`, never falls through to `allow`.
+//
+// PURE: no IO, no bucket/ledger persistence. This returns a verdict only; the miner-lib wrapper
+// (`packages/gittensory-miner/lib/governor-chokepoint.js`) owns mutating rate-limit buckets and appending the
+// returned ledger event, mirroring the existing engine-pure/miner-lib-stateful split every sibling module uses.
+import { classifyPortfolioConvergence, DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS } from "../portfolio/non-convergence.js";
+import { minerActionModeExecutes, resolveMinerActionMode } from "./action-mode.js";
+import { evaluateGovernorCaps } from "./budget-cap.js";
+import { isMinerKillSwitchActive, resolveMinerKillSwitch } from "./kill-switch.js";
+import { DEFAULT_SELF_REPUTATION_THRESHOLDS, selfReputationThrottle } from "./reputation-throttle.js";
+import { DEFAULT_SELF_PLAGIARISM_CONFIG, selfPlagiarismCheck } from "./self-plagiarism.js";
+import { evaluateWriteRateLimit } from "./write-rate-limit.js";
+/** Action classes that carry a per-submission diff fingerprint / outcome-cadence concept. Reputation-throttle
+ *  and self-plagiarism are evaluated only for these -- a label-apply or branch-delete has neither. */
+const SELF_SUBMISSION_ACTION_CLASSES = new Set(["open_pr"]);
+function denyResult(input) {
+    return {
+        allowed: false,
+        mode: input.mode,
+        stage: input.stage,
+        reason: input.reason,
+        detail: input.detail,
+        ledgerEvent: {
+            eventType: input.eventType,
+            repoFullName: input.repoFullName,
+            actionClass: input.actionClass,
+            decision: input.stage === "kill_switch" ? "paused" : input.eventType === "throttled" ? "throttle" : "deny",
+            reason: input.reason,
+            payload: { stage: input.stage, ...input.extraPayload },
+        },
+    };
+}
+/**
+ * Evaluate every write action against the full precedence ladder and return one fail-closed verdict. See the
+ * module doc comment for the exact stage order and which stages are conditional on `actionClass`.
+ */
+export function evaluateGovernorChokepoint(input) {
+    const killSwitchScope = resolveMinerKillSwitch({ global: input.killSwitchGlobal, repoPaused: input.killSwitchRepoPaused });
+    const mode = resolveMinerActionMode({
+        killSwitchScope,
+        repoLiveModeOptIn: input.liveModeRepoOptIn,
+        globalLiveModeOptIn: input.liveModeGlobalOptIn,
+    });
+    const baseDetail = { killSwitchScope, mode };
+    if (isMinerKillSwitchActive(killSwitchScope)) {
+        return denyResult({
+            stage: "kill_switch",
+            reason: `${killSwitchScope}_kill_switch_active`,
+            mode,
+            detail: baseDetail,
+            eventType: "kill_switch",
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+        });
+    }
+    if (!minerActionModeExecutes(mode)) {
+        // dry_run: shadow-log the would-be action without evaluating (or executing) anything further. The other
+        // stages are intentionally NOT consulted here -- the ladder's own documented order places dry-run before
+        // rate-limit, and a caller wanting a full "what-would-the-full-verdict-be" preview can call this function
+        // again with a synthetic live opt-in in a non-production dry-run harness.
+        return {
+            allowed: false,
+            mode,
+            stage: "dry_run",
+            reason: "dry_run_mode_active",
+            detail: baseDetail,
+            ledgerEvent: {
+                eventType: "allowed",
+                repoFullName: input.repoFullName,
+                actionClass: input.actionClass,
+                decision: "dry_run",
+                reason: "dry_run_mode_active",
+                payload: { wouldBeAction: input.wouldBeAction },
+            },
+        };
+    }
+    let rateLimit;
+    try {
+        rateLimit = evaluateWriteRateLimit({
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+            buckets: input.rateLimitBuckets,
+            backoffAttempts: input.rateLimitBackoffAttempts,
+            nowMs: input.nowMs,
+            ...(input.rateLimitPolicies ? { policies: input.rateLimitPolicies } : {}),
+            ...(input.rateLimitRandomFn ? { randomFn: input.rateLimitRandomFn } : {}),
+        });
+    }
+    catch (error) {
+        return denyResult({
+            stage: "internal_error",
+            reason: `rate_limit_calculator_error: ${error instanceof Error ? error.message : String(error)}`,
+            mode,
+            detail: baseDetail,
+            eventType: "denied",
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+        });
+    }
+    const detailWithRateLimit = { ...baseDetail, rateLimit };
+    if (!rateLimit.allowed) {
+        return denyResult({
+            stage: "rate_limit",
+            reason: rateLimit.reason,
+            mode,
+            detail: detailWithRateLimit,
+            eventType: "throttled",
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+            extraPayload: { retryAfterMs: rateLimit.retryAfterMs, blockedBy: rateLimit.blockedBy },
+        });
+    }
+    let budgetCap;
+    try {
+        budgetCap = evaluateGovernorCaps(input.capUsage, input.capLimits);
+    }
+    catch (error) {
+        return denyResult({
+            stage: "internal_error",
+            reason: `budget_cap_calculator_error: ${error instanceof Error ? error.message : String(error)}`,
+            mode,
+            detail: detailWithRateLimit,
+            eventType: "denied",
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+        });
+    }
+    const detailWithBudget = { ...detailWithRateLimit, budgetCap };
+    if (budgetCap.verdict !== "allowed") {
+        return denyResult({
+            stage: "budget_cap",
+            reason: `budget_cap_${budgetCap.verdict}`,
+            mode,
+            detail: detailWithBudget,
+            eventType: budgetCap.verdict,
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+            extraPayload: { budget: budgetCap.budget, turns: budgetCap.turns, termination: budgetCap.termination },
+        });
+    }
+    let convergence;
+    try {
+        convergence = classifyPortfolioConvergence(input.convergenceInput, input.convergenceThresholds ?? DEFAULT_PORTFOLIO_CONVERGENCE_THRESHOLDS);
+    }
+    catch (error) {
+        return denyResult({
+            stage: "internal_error",
+            reason: `non_convergence_calculator_error: ${error instanceof Error ? error.message : String(error)}`,
+            mode,
+            detail: detailWithBudget,
+            eventType: "denied",
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+        });
+    }
+    const detailWithConvergence = { ...detailWithBudget, convergence };
+    if (convergence.status === "non_convergent") {
+        return denyResult({
+            stage: "non_convergence",
+            reason: convergence.reasons.join(" "),
+            mode,
+            detail: detailWithConvergence,
+            eventType: "denied",
+            actionClass: input.actionClass,
+            repoFullName: input.repoFullName,
+        });
+    }
+    const isSelfSubmissionAction = SELF_SUBMISSION_ACTION_CLASSES.has(input.actionClass);
+    let detailWithReputation = detailWithConvergence;
+    // `!== undefined` (not a truthy check): an omitted key means "skip this stage"; any OTHER value the caller
+    // supplied -- including a bad `null` from a malformed upstream source -- must reach the calculator and, if it
+    // cannot handle it, fail closed via the catch below, never silently skip.
+    if (isSelfSubmissionAction && input.reputationHistory !== undefined) {
+        let reputation;
+        try {
+            reputation = selfReputationThrottle(input.reputationHistory, input.reputationThresholds ?? DEFAULT_SELF_REPUTATION_THRESHOLDS);
+        }
+        catch (error) {
+            return denyResult({
+                stage: "internal_error",
+                reason: `reputation_throttle_calculator_error: ${error instanceof Error ? error.message : String(error)}`,
+                mode,
+                detail: detailWithConvergence,
+                eventType: "denied",
+                actionClass: input.actionClass,
+                repoFullName: input.repoFullName,
+            });
+        }
+        detailWithReputation = { ...detailWithConvergence, reputation };
+        if (reputation.throttled) {
+            return denyResult({
+                stage: "reputation_throttle",
+                reason: reputation.reason,
+                mode,
+                detail: detailWithReputation,
+                eventType: "throttled",
+                actionClass: input.actionClass,
+                repoFullName: input.repoFullName,
+                extraPayload: { cadenceFactor: reputation.cadenceFactor, unfavorableRatio: reputation.unfavorableRatio },
+            });
+        }
+    }
+    let finalDetail = detailWithReputation;
+    // Same `!== undefined` reasoning as the reputation-throttle stage above.
+    if (isSelfSubmissionAction && input.selfPlagiarismCandidate !== undefined) {
+        let selfPlagiarism;
+        try {
+            selfPlagiarism = selfPlagiarismCheck(input.selfPlagiarismCandidate, input.selfPlagiarismRecentSubmissions ?? [], input.selfPlagiarismConfig ?? DEFAULT_SELF_PLAGIARISM_CONFIG);
+        }
+        catch (error) {
+            return denyResult({
+                stage: "internal_error",
+                reason: `self_plagiarism_calculator_error: ${error instanceof Error ? error.message : String(error)}`,
+                mode,
+                detail: detailWithReputation,
+                eventType: "denied",
+                actionClass: input.actionClass,
+                repoFullName: input.repoFullName,
+            });
+        }
+        finalDetail = { ...detailWithReputation, selfPlagiarism };
+        if (!selfPlagiarism.allowed) {
+            return denyResult({
+                stage: "self_plagiarism",
+                reason: selfPlagiarism.reason,
+                mode,
+                detail: finalDetail,
+                eventType: selfPlagiarism.eventType,
+                actionClass: input.actionClass,
+                repoFullName: input.repoFullName,
+                extraPayload: { similarity: selfPlagiarism.similarity ?? null },
+            });
+        }
+    }
+    return {
+        allowed: true,
+        mode,
+        stage: "allow",
+        reason: "all_governor_checks_passed",
+        detail: finalDetail,
+        ledgerEvent: {
+            eventType: "allowed",
+            repoFullName: input.repoFullName,
+            actionClass: input.actionClass,
+            decision: "allow",
+            reason: "all_governor_checks_passed",
+            payload: {},
+        },
+    };
+}

package/dist/governor/kill-switch.d.ts

@@ -0,0 +1,38 @@
+import type { GovernorLedgerEvent } from "../governor-ledger.js";
+/** Env var an operator sets to halt ALL miner write activity, across every repo, immediately. */
+export declare const MINER_KILL_SWITCH_ENV_VAR = "GITTENSORY_MINER_KILL_SWITCH";
+/** Which trigger (if any) is currently halting miner write activity for a given repo. */
+export type MinerKillSwitchScope = "global" | "repo" | "none";
+/**
+ * True when the operator's global env-level kill-switch is set. Mirrors `isGlobalAgentPause`'s idiom exactly
+ * (case-insensitive `1`/`true`/`yes`/`on`) — absence or any other value reads as not tripped. This function
+ * does not itself fail closed; the caller composing it into a decision (the Governor chokepoint) is
+ * responsible for that.
+ */
+export declare function isGlobalMinerKillSwitch(env: Record<string, string | undefined>): boolean;
+/**
+ * Resolve which kill-switch scope (if any) is active for a repo. Pure and stateless: identical inputs always
+ * yield the identical scope, so toggling either input off on the next call immediately reflects "resumed" with
+ * no residual state here to corrupt — any queue/attempt state a caller holds is untouched by this resolution.
+ * Precedence: a global halt always reports as `"global"`, regardless of the per-repo flag (never masked); a
+ * per-repo pause alone is sufficient to halt just that repo.
+ */
+export declare function resolveMinerKillSwitch(input: {
+    global: boolean;
+    repoPaused?: boolean | null | undefined;
+}): MinerKillSwitchScope;
+/** True for any active scope (`"global"` or `"repo"`) — false only for `"none"`. */
+export declare function isMinerKillSwitchActive(scope: MinerKillSwitchScope): boolean;
+/**
+ * Governor-ledger row for a kill-switch STATE TRANSITION (#2341's "state changes are themselves recorded"
+ * deliverable) — call only when the scope actually changed since the previous check, not on every check (every
+ * check's allow/deny for a real write action is the Governor chokepoint's job, #2340, not this primitive's).
+ * Returns `null` when there is no transition, so a caller can unconditionally call this each check and only
+ * append when it returns non-null.
+ */
+export declare function buildMinerKillSwitchTransitionGovernorLedgerEvent(input: {
+    repoFullName?: string | null | undefined;
+    actionClass: string;
+    previousScope: MinerKillSwitchScope;
+    scope: MinerKillSwitchScope;
+}): GovernorLedgerEvent | null;

package/dist/governor/kill-switch.js

@@ -0,0 +1,62 @@
+// Governor kill-switch (#2341): the emergency-halt primitive every write-adjacent governor decision consults
+// FIRST, before any other calculator. Two independent triggers compose into one scope: a GLOBAL env-level
+// switch that halts every repo at once, and a PER-REPO switch (from `.gittensory-miner.yml`'s MinerGoalSpec
+// `killSwitch.paused` field) that halts only its own repo's queue while leaving the rest of the fleet running.
+// Mirrors `src/settings/agent-execution.ts`'s `isGlobalAgentPause` truthy-string idiom for the review-stack's
+// own kill-switch (#776) — a parallel mechanism for the miner's own local runtime, not the same one.
+//
+// DETECTOR ONLY — no IO, no persistence. Composing this with the other pure calculators into one fail-closed
+// allow/deny verdict (and recording every CHECK, not just a transition) is the Governor chokepoint's job
+// (#2340), which consults this module first in its "safest wins" precedence.
+/** Truthy-string idiom shared with `isGlobalAgentPause` (`src/settings/agent-execution.ts`) — same accepted
+ *  literal set, so an operator only needs to remember one convention across both kill-switches. */
+const TRUTHY_ENV_VALUE = /^(1|true|yes|on)$/i;
+/** Env var an operator sets to halt ALL miner write activity, across every repo, immediately. */
+export const MINER_KILL_SWITCH_ENV_VAR = "GITTENSORY_MINER_KILL_SWITCH";
+/**
+ * True when the operator's global env-level kill-switch is set. Mirrors `isGlobalAgentPause`'s idiom exactly
+ * (case-insensitive `1`/`true`/`yes`/`on`) — absence or any other value reads as not tripped. This function
+ * does not itself fail closed; the caller composing it into a decision (the Governor chokepoint) is
+ * responsible for that.
+ */
+export function isGlobalMinerKillSwitch(env) {
+    return TRUTHY_ENV_VALUE.test(env[MINER_KILL_SWITCH_ENV_VAR] ?? "");
+}
+/**
+ * Resolve which kill-switch scope (if any) is active for a repo. Pure and stateless: identical inputs always
+ * yield the identical scope, so toggling either input off on the next call immediately reflects "resumed" with
+ * no residual state here to corrupt — any queue/attempt state a caller holds is untouched by this resolution.
+ * Precedence: a global halt always reports as `"global"`, regardless of the per-repo flag (never masked); a
+ * per-repo pause alone is sufficient to halt just that repo.
+ */
+export function resolveMinerKillSwitch(input) {
+    if (input.global)
+        return "global";
+    if (input.repoPaused === true)
+        return "repo";
+    return "none";
+}
+/** True for any active scope (`"global"` or `"repo"`) — false only for `"none"`. */
+export function isMinerKillSwitchActive(scope) {
+    return scope !== "none";
+}
+/**
+ * Governor-ledger row for a kill-switch STATE TRANSITION (#2341's "state changes are themselves recorded"
+ * deliverable) — call only when the scope actually changed since the previous check, not on every check (every
+ * check's allow/deny for a real write action is the Governor chokepoint's job, #2340, not this primitive's).
+ * Returns `null` when there is no transition, so a caller can unconditionally call this each check and only
+ * append when it returns non-null.
+ */
+export function buildMinerKillSwitchTransitionGovernorLedgerEvent(input) {
+    if (input.previousScope === input.scope)
+        return null;
+    const tripped = isMinerKillSwitchActive(input.scope);
+    return {
+        eventType: "kill_switch",
+        repoFullName: input.repoFullName ?? null,
+        actionClass: input.actionClass,
+        decision: tripped ? "tripped" : "resumed",
+        reason: tripped ? `${input.scope}_kill_switch_engaged` : `${input.previousScope}_kill_switch_cleared`,
+        payload: { previousScope: input.previousScope, scope: input.scope },
+    };
+}