pi-anti-doom-loop 0.0.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,95 @@
+# pi-anti-doom-loop
+
+Stop agent doom loops in [pi](https://pi.dev/) before they burn tokens.
+
+Cheap models sometimes get stuck repeating the same cheap tool call — `grep`
+the same file, re-run the same failing command — with no progress. Each
+iteration is so cheap nobody notices until the bill mounts. This extension
+watches every tool call and blocks the loop at the source.
+
+## Install
+
+```bash
+pi install npm:pi-anti-doom-loop
+```
+
+## What it detects
+
+| Signal                          | Default                 | Blocked when                                                    |
+| ------------------------------- | ----------------------- | --------------------------------------------------------------- |
+| Same `(tool, args)` repeated    | 3× in the last 10 calls | The pattern has repeated `3` times with no change               |
+| Same tool failing consecutively | 3×                      | A tool errored `3` times in a row — stop retrying it blindly    |
+| Same assistant text verbatim    | 3× in a row             | The model re-emitted identical text `3` times (text-only loops) |
+
+Blocks hand the model an instructive reason ("change your approach, use a
+different tool, or ask the user"). If the model ignores the block and re-issues
+the exact same call, the turn is **aborted** and you are notified. A verbatim
+text loop (no tool calls involved) aborts the run immediately with a
+notification.
+
+Counters reset on every user prompt, so a task legitimately repeated later in
+the same session is never a false positive.
+
+## Configuration
+
+Environment variables, read at session/prompt start:
+
+| Variable                    | Default | Meaning                                            |
+| --------------------------- | ------- | -------------------------------------------------- |
+| `PI_ANTI_LOOP_REPEATS`      | `3`     | Identical-call block threshold                     |
+| `PI_ANTI_LOOP_FAILS`        | `3`     | Consecutive-failure block threshold                |
+| `PI_ANTI_LOOP_TEXT_REPEATS` | `3`     | Consecutive identical assistant texts before abort |
+| `PI_ANTI_LOOP_WINDOW`       | `10`    | How many recent calls/results are inspected        |
+| `PI_ANTI_LOOP_DISABLE`      | —       | Set to `1` to disable the extension entirely       |
+
+## Command
+
+- `/loopcheck` — show current thresholds and counters
+- `/loopcheck reset` — clear counters
+
+## How it works
+
+Everything hooks into the `tool_call` / `tool_result` events; detection is a
+small sliding-window counter (see `extensions/detector.ts`) with no state kept
+between user prompts. Works with any model — cheap models just trigger it more
+often.
+
+## Development
+
+Requires Node 22.6+ (plain `node` runs the TS self-check).
+
+```bash
+npm install
+npm test        # detector self-check (pure Node, no deps)
+npm run check   # npm test + tsc + oxlint --deny-warnings + oxfmt
+```
+
+Runtime deps: `better-result` (detector decisions) and `effect` v4 (the release guard).
+
+> `peerDependencies` pins `@earendil-works/pi-coding-agent` at `"*"` on purpose — the
+> [pi packages docs](https://pi.dev/docs/latest/packages) require an unbounded range for
+> pi-core packages (pi provides them at runtime). The extension loads `.ts` directly via
+> jiti, so no build step ships; `prepublishOnly` runs the full quality gate before publish.
+
+> When a call is blocked, escalation still works without recording it in the window:
+> re-issuing the identical call increments a per-signature block counter and aborts the
+> turn on the second block. Thresholds are clamped to a minimum of 2 so a bad config
+> can never brick the agent.
+
+## Releasing
+
+Publishing is handled by the GitHub Actions workflow [`.github/workflows/release.yml`](.github/workflows/release.yml), guarded against version drift:
+
+1. Add an npm **Automation** token as the `NPM_TOKEN` repo secret (Settings → Secrets and variables → Actions, or `gh secret set NPM_TOKEN`).
+2. Bump `version` in `package.json`, commit, then tag and push:
+
+```bash
+git tag v0.0.1
+git push origin v0.0.1
+```
+
+CI runs the quality gate, then the **version bump guard** (`npm run guard`): it blocks publishing if the version is already on npm or the tag doesn't match `package.json`. After the first publish, the [pi.dev gallery](https://pi.dev/packages) picks the package up automatically via the `pi-package` keyword.
+
+## License
+
+MIT

package/extensions/detector.ts

@@ -0,0 +1,301 @@
+/**
+ * Pure loop-detection logic — no pi imports, so it is runnable/testable
+ * standalone (`node extensions/detector.ts` self-check at the bottom).
+ *
+ * Detects two "doom loop" signatures, both scoped to a sliding window so a
+ * genuinely repeated task spread over time never trips it:
+ *
+ *  1. The same tool called with identical arguments `repeatThreshold` times
+ *     (the classic "grep the same file 10 times" loop).
+ *  2. The same tool failing `failThreshold` consecutive times (blind retry
+ *     of a flaky/ungrounded operation).
+ */
+import assert from "node:assert/strict";
+import { Result } from "better-result";
+
+export interface LoopOptions {
+  /** Identical (tool, args) occurrences that trigger a block. */
+  repeatThreshold: number;
+  /** Consecutive same-tool errors that trigger a block. */
+  failThreshold: number;
+  /** How many recent calls/results are inspected for repetition. */
+  windowSize: number;
+  /** Consecutive verbatim assistant messages that trigger an abort. */
+  textRepeatThreshold: number;
+}
+
+export const DEFAULT_OPTIONS: LoopOptions = {
+  repeatThreshold: 3,
+  failThreshold: 3,
+  windowSize: 10,
+  textRepeatThreshold: 3,
+};
+
+export function readOptions(env: Record<string, string | undefined> = process.env): LoopOptions {
+  // ponytail: min 2 — a threshold of 1 would block every tool call / abort on
+  // the first message, bricking the agent (deepsec finding).
+  const num = (key: string, fallback: number): number => {
+    const raw = env[key];
+    if (!raw) return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 2 ? n : fallback;
+  };
+  return {
+    repeatThreshold: num("PI_ANTI_LOOP_REPEATS", DEFAULT_OPTIONS.repeatThreshold),
+    failThreshold: num("PI_ANTI_LOOP_FAILS", DEFAULT_OPTIONS.failThreshold),
+    windowSize: num("PI_ANTI_LOOP_WINDOW", DEFAULT_OPTIONS.windowSize),
+    textRepeatThreshold: num("PI_ANTI_LOOP_TEXT_REPEATS", DEFAULT_OPTIONS.textRepeatThreshold),
+  };
+}
+
+/** Keys sorted recursively so {a:1,b:2} and {b:2,a:1} share a signature. */
+export function canonical(input: unknown): string {
+  if (input === null || typeof input !== "object") return JSON.stringify(input);
+  if (Array.isArray(input)) return `[${input.map(canonical).join(",")}]`;
+  const obj = input as Record<string, unknown>;
+  return `{${Object.keys(obj)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`)
+    .join(",")}}`;
+}
+
+export function signature(toolName: string, input: unknown): string {
+  return `${toolName}:${canonical(input)}`;
+}
+
+export interface BlockDecision {
+  /** Reason shown to the LLM as the (blocked) tool result. */
+  reason: string;
+  /** True when this exact call was already blocked before — caller should abort the turn. */
+  escalate: boolean;
+}
+
+/**
+ * Call `check` in `tool_call` (before executing). If it returns a decision,
+ * block the call. Call `record` only for calls that were NOT blocked, and
+ * `recordResult` in `tool_result` for executed calls.
+ */
+export class LoopDetector {
+  readonly opts: LoopOptions;
+  private recentSigs: string[] = [];
+  private recentResults: { tool: string; error: boolean }[] = [];
+  private blockedBySig = new Map<string, number>();
+  private lastText: string | null = null;
+  private textStreak = 0;
+  private textFired = false;
+
+  constructor(opts: LoopOptions = DEFAULT_OPTIONS) {
+    this.opts = opts;
+  }
+
+  check(toolName: string, input: unknown): Result<BlockDecision, undefined> {
+    const sig = signature(toolName, input);
+    const repeats = this.recentSigs.filter((s) => s === sig).length;
+    const total = repeats + 1; // including this call
+    const fails = this.consecutiveFails(toolName);
+
+    if (total < this.opts.repeatThreshold && fails < this.opts.failThreshold)
+      return Result.err(undefined);
+
+    const reasons: string[] = [];
+    if (total >= this.opts.repeatThreshold) {
+      reasons.push(
+        `"${toolName}" was called with identical arguments ${total} times in the last ${this.opts.windowSize} tool calls with no change`,
+      );
+    }
+    if (fails >= this.opts.failThreshold) {
+      reasons.push(`"${toolName}" failed ${fails} consecutive times`);
+    }
+
+    const blockedCount = (this.blockedBySig.get(sig) ?? 0) + 1;
+    this.blockedBySig.set(sig, blockedCount);
+
+    return Result.ok({
+      reason:
+        reasons.join("; ") +
+        `. BLOCKED by anti-doom-loop — you appear to be looping. Change your approach, use a different tool, or ask the user.`,
+      escalate: blockedCount > 1,
+    });
+  }
+
+  record(toolName: string, input: unknown): void {
+    this.recentSigs.push(signature(toolName, input));
+    if (this.recentSigs.length > this.opts.windowSize) this.recentSigs.shift();
+  }
+
+  recordResult(toolName: string, error: boolean): void {
+    this.recentResults.push({ tool: toolName, error });
+    if (this.recentResults.length > this.opts.windowSize) this.recentResults.shift();
+  }
+
+  /**
+   * Consecutive verbatim assistant text (whitespace-normalized). Fires once
+   * per run when the streak reaches textRepeatThreshold, then stays silent
+   * until reset — message_end cannot return a block, so the caller aborts.
+   * $
+   * Detects the text-only loop shape (model re-emits the same sentence
+   * forever, e.g. goal-function loops) that identical-tool-call detection
+   * never sees. Liquid.ai's Antidoom mines loops as 'a section repeats at
+   * least four times'; we use 3 and no length floor because at runtime each
+   * repetition already burns tokens.
+   */
+  checkText(text: string): Result<{ reason: string }, undefined> {
+    const norm = normalizeText(text);
+    if (!norm) return Result.err(undefined); // blank text is not a loop signal
+    this.textStreak = norm === this.lastText ? this.textStreak + 1 : 1;
+    this.lastText = norm;
+    if (this.textStreak >= this.opts.textRepeatThreshold && !this.textFired) {
+      this.textFired = true;
+      return Result.ok({
+        reason:
+          `Assistant replied with identical text ${this.textStreak} times in a row ("${truncate(norm, 80)}"). ` +
+          `You appear to be in a loop — this run is aborted.`,
+      });
+    }
+    return Result.err(undefined);
+  }
+
+  /** Trail of results that are errors of this same tool (consecutive). */
+  private consecutiveFails(toolName: string): number {
+    let n = 0;
+    for (let i = this.recentResults.length - 1; i >= 0; i--) {
+      const r = this.recentResults[i];
+      if (!r.error || r.tool !== toolName) break;
+      n++;
+    }
+    return n;
+  }
+
+  reset(): void {
+    this.recentSigs = [];
+    this.recentResults = [];
+    this.blockedBySig.clear();
+    this.lastText = null;
+    this.textStreak = 0;
+    this.textFired = false;
+  }
+
+  summary(): string {
+    const blocked = [...this.blockedBySig.values()].reduce((a, b) => a + b, 0);
+    const text = this.textStreak > 1 ? `, text streak ${this.textStreak}` : "";
+    return `window: ${this.recentSigs.length}/${this.opts.windowSize} calls, ${this.recentResults.length} results, blocked ${blocked} time(s)${text}`;
+  }
+}
+
+/** Collapse runs of whitespace so formatting drift never hides a verbatim loop. */
+export function normalizeText(text: string): string {
+  return text.trim().replace(/\s+/g, " ");
+}
+
+/** First `max` chars of a single-line string, with an ellipsis. */
+export function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+
+// --- self-check (runs under `node extensions/detector.ts`, skipped when loaded by pi) ---
+if (import.meta.main) {
+  const opts: LoopOptions = {
+    repeatThreshold: 3,
+    failThreshold: 3,
+    windowSize: 10,
+    textRepeatThreshold: 3,
+  };
+  const d: LoopDetector = new LoopDetector(opts);
+
+  // 1. identical calls: 2 pass, 3rd is blocked; retry of a blocked call escalates
+  assert.ok(d.check("bash", { command: "grep foo bar.ts" }).isErr(), "1st call passes");
+  d.record("bash", { command: "grep foo bar.ts" });
+  assert.ok(d.check("bash", { command: "grep foo bar.ts" }).isErr(), "2nd call passes");
+  d.record("bash", { command: "grep foo bar.ts" });
+  const hit = d.check("bash", { command: "grep foo bar.ts" });
+  assert.ok(hit.isOk(), "3rd identical call should block");
+  if (hit.isOk()) {
+    assert.equal(hit.value.escalate, false, "first block does not escalate");
+    assert.match(hit.value.reason, /identical arguments 3 times/);
+  }
+  // LLM ignores the block and retries the exact same call: escalate
+  const hit2 = d.check("bash", { command: "grep foo bar.ts" });
+  assert.ok(hit2.isOk() && hit2.value.escalate, "retry of a blocked call should escalate");
+
+  // 2. different arguments are not a loop
+  d.reset();
+  assert.ok(d.check("read", { path: "a.ts" }).isErr());
+  d.record("read", { path: "a.ts" });
+  assert.ok(d.check("read", { path: "b.ts" }).isErr());
+  d.record("read", { path: "b.ts" });
+  assert.ok(d.check("read", { path: "a.ts" }).isErr(), "arg order/counter: only same args count");
+
+  // 3. key order does not matter
+  assert.equal(signature("read", { a: 1, b: 2 }), signature("read", { b: 2, a: 1 }));
+
+  // 4. consecutive same-tool failures trigger a block
+  d.reset();
+  d.recordResult("bash", true);
+  d.recordResult("bash", true);
+  d.recordResult("bash", true);
+  const failHit = d.check("bash", { command: "npm test" });
+  assert.ok(failHit.isOk(), "3 consecutive failures should block");
+  if (failHit.isOk()) assert.match(failHit.value.reason, /failed 3 consecutive times/);
+
+  // 5. an interleaved success breaks the failure streak
+  d.reset();
+  d.recordResult("bash", true);
+  d.recordResult("bash", false);
+  d.recordResult("bash", true);
+  d.recordResult("bash", true);
+  assert.ok(d.check("bash", { command: "npm test" }).isErr(), "success breaks the streak");
+
+  // 6. window eviction: stale repeats no longer count
+  d.reset();
+  for (let i = 0; i < opts.windowSize; i++) d.record("bash", { command: `cmd ${i}` });
+  assert.ok(d.check("bash", { command: "cmd 0" }).isErr(), "evicted repeats do not count");
+
+  // 7. verbatim assistant text loop: fires once at the 3rd identical message
+  d.reset();
+  assert.ok(d.checkText("Now update buildProgram.").isErr(), "1st text passes");
+  assert.ok(d.checkText("Now update buildProgram.").isErr(), "2nd text passes");
+  const textHit = d.checkText("Now update buildProgram.");
+  assert.ok(textHit.isOk(), "3rd identical text should fire");
+  if (textHit.isOk()) {
+    assert.match(textHit.value.reason, /identical text 3 times/);
+    assert.match(textHit.value.reason, /aborted/);
+  }
+  assert.ok(d.checkText("Now update buildProgram.").isErr(), "fires only once per run");
+
+  // 8. whitespace drift does not hide a verbatim loop
+  d.reset();
+  d.checkText("Read the region:");
+  d.checkText("Read  the   region:");
+  const wsHit = d.checkText(" Read the region: ");
+  assert.ok(wsHit.isOk(), "whitespace-normalized repeats should fire");
+
+  // 9. a different message breaks the streak (need 3 consecutive AFTER the break to fire)
+  d.reset();
+  d.checkText("A");
+  d.checkText("A");
+  d.checkText("B"); // breaks the streak
+  d.checkText("A");
+  assert.ok(d.checkText("A").isErr(), "only 2 consecutive As after the break must not fire");
+  const again = d.checkText("A");
+  assert.ok(again.isOk(), "3 consecutive As after the break fire");
+
+  // 10. empty/blank text is ignored as a loop signal
+  d.reset();
+  d.checkText("");
+  d.checkText("   ");
+  assert.ok(d.checkText("").isErr(), "blank text must not fire");
+
+  // 11. threshold 1 is clamped away (would brick the agent)
+  const clamped = readOptions({
+    PI_ANTI_LOOP_REPEATS: "1",
+    PI_ANTI_LOOP_FAILS: "0",
+    PI_ANTI_LOOP_TEXT_REPEATS: "-2",
+  });
+  assert.equal(clamped.repeatThreshold, 3, "1 falls back to default");
+  assert.equal(clamped.failThreshold, 3, "0 falls back to default");
+  assert.equal(clamped.textRepeatThreshold, 3, "negative falls back to default");
+  const two = readOptions({ PI_ANTI_LOOP_REPEATS: "2" });
+  assert.equal(two.repeatThreshold, 2, "2 is the minimum accepted");
+
+  console.log("detector self-check: all assertions passed");
+}

package/extensions/index.ts

@@ -0,0 +1,98 @@
+/**
+ * anti-doom-loop — pi extension that detects and breaks agent doom loops.
+ *
+ * Cheap models sometimes repeat the same cheap tool call (grep, read, ls)
+ * without progress, silently burning tokens. This extension watches every
+ * tool call and blocks loops before they cost anything:
+ *
+ *  - identical (tool, args) repeated `PI_ANTI_LOOP_REPEATS` times (default 3)
+ *    in the last `PI_ANTI_LOOP_WINDOW` calls → block with an instructive reason
+ *  - the same tool failing `PI_ANTI_LOOP_FAILS` consecutive times (default 3)
+ *    → block with a "stop retrying, fix the root cause" reason
+ *
+ * Blocking hands control back to the model once. If the model re-issues the
+ * exact same blocked call, the turn is aborted (escalation).
+ *
+ * Counters reset on every user prompt, so a task legitimately repeated later
+ * in the session is never a false positive. Disable with PI_ANTI_LOOP_DISABLE=1.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { LoopDetector, readOptions } from "./detector";
+
+export default function (pi: ExtensionAPI): void {
+  if (process.env.PI_ANTI_LOOP_DISABLE === "1") return;
+
+  let detector = new LoopDetector(readOptions());
+  let configTxt = settingsTxt(detector);
+  const blockedIds = new Set<string>();
+
+  pi.on("session_start", () => reset());
+
+  // Fresh counters per user prompt: only the loop happening *right now* counts.
+  pi.on("before_agent_start", () => reset());
+
+  pi.on("tool_call", (event, ctx) => {
+    const decision = detector.check(event.toolName, event.input);
+    if (decision.isErr()) {
+      detector.record(event.toolName, event.input);
+      return;
+    }
+    const block = decision.value;
+    blockedIds.add(event.toolCallId);
+    if (block.escalate) {
+      ctx.ui.notify("Anti-doom-loop: identical call blocked again — aborting turn", "error");
+      ctx.abort();
+    }
+    return { block: true, reason: block.reason };
+  });
+
+  // Blocked calls never ran, so their (error) result must not count as a failure.
+  pi.on("tool_result", (event) => {
+    if (blockedIds.has(event.toolCallId)) {
+      blockedIds.delete(event.toolCallId);
+      return;
+    }
+    detector.recordResult(event.toolName, event.isError === true);
+  });
+
+  // Text-only doom loops (model re-emits the same sentence with no tool calls)
+  // never reach tool_call. Detect verbatim assistant repeats and abort the run.
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (message.role !== "assistant") return;
+    const content = Array.isArray(message.content) ? message.content : [];
+    const text = content
+      .filter((c): c is { type: "text"; text: string } => c.type === "text")
+      .map((c) => c.text)
+      .join(" ");
+    if (!text) return;
+    const hit = detector.checkText(text);
+    if (hit.isOk()) {
+      ctx.ui.notify(`Anti-doom-loop: ${hit.value.reason}`, "error");
+      ctx.abort();
+    }
+  });
+
+  pi.registerCommand("loopcheck", {
+    description: "Anti-doom-loop status; `/loopcheck reset` clears counters",
+    handler: async (args, ctx) => {
+      if (args.trim().toLowerCase() === "reset") {
+        reset();
+        ctx.ui.notify("Anti-doom-loop: counters reset", "info");
+        return;
+      }
+      ctx.ui.notify(`${configTxt}. ${detector.summary()}`, "info");
+    },
+  });
+
+  function reset(): void {
+    detector = new LoopDetector(readOptions());
+    configTxt = settingsTxt(detector);
+    blockedIds.clear();
+  }
+}
+
+function settingsTxt(d: LoopDetector): string {
+  const o = d.opts;
+  return `anti-doom-loop: repeats>=${o.repeatThreshold}/window ${o.windowSize}, fails>=${o.failThreshold}`;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "pi-anti-doom-loop",
+  "version": "0.0.1",
+  "description": "Detect and break agent doom loops in pi: blocks identical repeated tool calls and blind retries before they burn tokens.",
+  "keywords": [
+    "anti-doom-loop",
+    "loop-detection",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/irfndi/pi-anti-doom-loop",
+  "license": "MIT",
+  "author": "irfandi <join.mantap@gmail.com> (https://github.com/irfndi)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/irfndi/pi-anti-doom-loop.git"
+  },
+  "files": [
+    "extensions",
+    "scripts"
+  ],
+  "type": "module",
+  "main": "extensions/index.ts",
+  "types": "extensions/index.ts",
+  "exports": {
+    ".": "./extensions/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run test && tsc --noEmit && oxlint --deny-warnings && oxfmt --check .",
+    "prepublishOnly": "npm run check",
+    "test": "node extensions/detector.ts",
+    "guard": "node scripts/guard-publish.ts",
+    "lint": "oxlint --deny-warnings",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check ."
+  },
+  "dependencies": {
+    "better-result": "^3.0.0",
+    "effect": "^4.0.0-beta.103"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^22.0.0",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.77.0",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}

package/scripts/guard-publish.ts

@@ -0,0 +1,145 @@
+/**
+ * Version bump guard — the consistency gate before `npm publish`.
+ *
+ * Fails (exit 1) unless BOTH hold:
+ *   1. The package.json version is NOT already the latest published on npm
+ *      (npm never overwrites a published version; re-releasing the same
+ *      version is a no-op at best and a dishonest release at worst).
+ *   2. If an expected version is passed (e.g. a tag like v0.0.1), it matches
+ *      the package.json version — so tags and manifests can't drift.
+ *
+ * Implemented with Effect v4: each fallible step (read, parse, fetch, guard
+ * rules) lives in the typed error channel, so failures short-circuit with a
+ * clean GUARD FAIL message and exit code 1.
+ *
+ * Usage:
+ *   node scripts/guard-publish.ts            # keep published version < local
+ *   node scripts/guard-publish.ts v0.0.1     # also require local == 0.0.1
+ */
+import { Effect } from "effect";
+import { readFile } from "node:fs/promises";
+
+interface GuardError {
+  message: string;
+}
+
+interface Manifest {
+  name: string;
+  version: string;
+}
+
+const fail = (message: string): Effect.Effect<never, GuardError> => Effect.fail({ message });
+
+const readManifest: Effect.Effect<string, GuardError> = Effect.tryPromise({
+  try: () => readFile(new URL("../package.json", import.meta.url), "utf8"),
+  catch: () => ({ message: "GUARD FAIL: could not read package.json" }),
+});
+
+const parseManifest = (raw: string): Effect.Effect<Manifest, GuardError> => {
+  let manifest: Manifest;
+  try {
+    manifest = JSON.parse(raw) as Manifest;
+  } catch {
+    return Effect.fail({ message: "GUARD FAIL: package.json is not valid JSON" });
+  }
+  return Effect.succeed(manifest);
+};
+const semverLike = (value: string): boolean => /^\d+\.\d+\.\d+$/.test(value);
+
+/**
+ * Whether a git tag `v<version>` exists in the current checkout. On the
+ * manual-dispatch path no tag is pushed, so this closes the tag/sync gap.
+ */
+const tagExists = (version: string): Effect.Effect<boolean> =>
+  Effect.tryPromise({
+    try: async () => {
+      const { execFile } = await import("node:child_process");
+      const { promisify } = await import("node:util");
+      const run = promisify(execFile);
+      try {
+        const { stdout } = await run("git", ["tag", "-l", `v${version}`], { cwd: process.cwd() });
+        return stdout.trim().length > 0;
+      } catch {
+        return false; // no git repo / git missing → treat as no tag
+      }
+    },
+    catch: () => new Error("git tag check failed"),
+  }).pipe(Effect.catch(() => Effect.succeed(false)));
+/**
+ * Latest published version on npm, or null when the package was never
+ * published or the registry is unreachable (warn-only on network failure —
+ * `npm publish` remains the real gate).
+ */
+const fetchPublished = (name: string): Effect.Effect<string | null> =>
+  Effect.tryPromise({
+    try: async () => {
+      const res = await fetch(`https://registry.npmjs.org/${name}/latest`, {
+        headers: { accept: "application/json" },
+      });
+      if (!res.ok) return null;
+      return ((await res.json()) as { version?: string }).version ?? null;
+    },
+    catch: () => {
+      console.warn(
+        "GUARD WARN: could not reach the npm registry; skipping published-version check.",
+      );
+      return new Error("registry unreachable");
+    },
+  }).pipe(Effect.catch(() => Effect.succeed(null)));
+
+const program: Effect.Effect<string, GuardError> = Effect.gen(function* () {
+  const raw = yield* readManifest;
+  const pkg = yield* parseManifest(raw);
+  const local = pkg.version;
+  const expected = (process.argv[2] ?? "").replace(/^v/, ""); // tolerate "v0.0.1"
+
+  if (!semverLike(local)) {
+    yield* fail(`GUARD FAIL: package.json version "${local}" is not a semver X.Y.Z.`);
+  }
+  if (expected && expected !== local) {
+    yield* fail(
+      `GUARD FAIL: expected "${expected}" (tag/input) does not match package.json version "${local}". ` +
+        `Bump package.json to ${expected}, or tag ${local}.`,
+    );
+  }
+
+  const published = yield* fetchPublished(pkg.name);
+  if (published === local) {
+    yield* fail(
+      `GUARD FAIL: ${pkg.name}@${local} is already published on npm. ` +
+        `Bump the version in package.json to cut a new release.`,
+    );
+  }
+
+  // On the manual-dispatch path no tag is pushed, so require the version to
+  // exist as a git tag — keeps the tag/manifest-sync invariant on both entry
+  // points (clawpatch finding).
+  if (expected && (yield* tagExists(expected)) === false) {
+    yield* fail(
+      `GUARD FAIL: expected version "${expected}" has no matching git tag v${expected}. Tag it first.`,
+    );
+  }
+
+  return (
+    `GUARD OK: publishing ${pkg.name}@${local}` +
+    (published ? ` (latest on npm: ${published})` : " (first publish — not on npm yet)")
+  );
+});
+
+interface Outcome {
+  ok: boolean;
+  message: string;
+}
+
+const outcome: Outcome = await Effect.runPromise(
+  Effect.match(program, {
+    onFailure: (error: GuardError): Outcome => ({ ok: false, message: error.message }),
+    onSuccess: (message: string): Outcome => ({ ok: true, message }),
+  }),
+);
+
+if (!outcome.ok) {
+  console.error(outcome.message);
+  process.exit(1);
+}
+console.log(outcome.message);