@hasna/hooks 0.3.10 → 0.4.0

package/hooks/codewith-native-common.ts

@@ -1,5 +1,5 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "path";
 import { homedir, tmpdir } from "os";
 
 export interface CodewithHookInput {
@@ -485,6 +485,148 @@ function shouldSkipHasnaTreeRule(targetPath: string, rule: ProtectedPathRule, cu
   return isInsidePath(target, currentManagedRepoRoot);
 }
 
+function isMissingPathError(error: unknown): boolean {
+  return error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function hasUnsafeTargetComponent(worktreesRoot: string, target: string): boolean {
+  const relativeTarget = relative(worktreesRoot, target);
+  const parts = relativeTarget.split(sep).filter(Boolean);
+  if (parts.some((part) => part.toLowerCase() === ".git")) return true;
+
+  const filesystemRoot = parse(target).root;
+  const absoluteParts = relative(filesystemRoot, target).split(sep).filter(Boolean);
+  let probe = filesystemRoot;
+  try {
+    if (lstatSync(probe).isSymbolicLink()) return true;
+  } catch {
+    return true;
+  }
+  for (const part of absoluteParts) {
+    probe = join(probe, part);
+    try {
+      const metadata = lstatSync(probe);
+      if (metadata.isSymbolicLink()) return true;
+      if (probe === target && metadata.isFile() && metadata.nlink > 1) return true;
+    } catch (error) {
+      if (isMissingPathError(error)) return false;
+      return true;
+    }
+  }
+  return false;
+}
+
+function managedLeaseRoot(worktreesRoot: string, target: string): string | null {
+  const relativeTarget = relative(worktreesRoot, target);
+  const parts = relativeTarget.split(sep).filter(Boolean);
+  if (parts.length < 3) return null;
+  const leaseRoot = resolve(worktreesRoot, ...parts.slice(0, 3));
+  return managedWorktreeInfo(leaseRoot).managed ? leaseRoot : null;
+}
+
+async function verifiedLinkedWorktreeRoot(leaseRoot: string): Promise<string | null> {
+  const controlFile = join(leaseRoot, ".git");
+  try {
+    const metadata = lstatSync(controlFile);
+    if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink !== 1) return null;
+  } catch {
+    return null;
+  }
+
+  if (!commandExists("git")) return null;
+  const result = await runCommand([
+    "git",
+    "rev-parse",
+    "--show-toplevel",
+    "--absolute-git-dir",
+    "--git-common-dir",
+  ], { cwd: leaseRoot, timeoutMs: 2000 });
+  if (result.exitCode !== 0) return null;
+  const [repoRootRaw, gitDirRaw, commonDirRaw] = result.stdout.trim().split(/\r?\n/);
+  if (!repoRootRaw || !gitDirRaw || !commonDirRaw) return null;
+
+  const repoRoot = resolve(repoRootRaw);
+  const gitDir = resolveFrom(leaseRoot, gitDirRaw);
+  const commonDir = resolveFrom(leaseRoot, commonDirRaw);
+  if (repoRoot !== resolve(leaseRoot)) return null;
+  try {
+    const physicalGitDir = realpathSync(gitDir);
+    const physicalCommonDir = realpathSync(commonDir);
+    const physicalWorktreesDir = realpathSync(join(commonDir, "worktrees"));
+    if (physicalGitDir === physicalWorktreesDir || !isInsidePath(physicalGitDir, physicalWorktreesDir)) return null;
+    if (dirname(physicalWorktreesDir) !== physicalCommonDir) return null;
+
+    const commondirPointer = readFileSync(join(gitDir, "commondir"), "utf-8").trim();
+    const gitdirPointer = readFileSync(join(gitDir, "gitdir"), "utf-8").trim();
+    if (!commondirPointer || !gitdirPointer) return null;
+    if (realpathSync(resolveFrom(gitDir, commondirPointer)) !== physicalCommonDir) return null;
+    const expectedControlFile = resolve(controlFile);
+    const backPointer = resolveFrom(gitDir, gitdirPointer);
+    if (backPointer !== expectedControlFile) return null;
+    if (realpathSync(backPointer) !== realpathSync(expectedControlFile)) return null;
+  } catch {
+    return null;
+  }
+  return repoRoot;
+}
+
+async function managedRepoRootForAbsoluteTarget(
+  targetPath: string,
+  repoRootCache: Map<string, Promise<string | null>>,
+): Promise<string | null> {
+  if (!isAbsolute(targetPath)) return null;
+  const worktreesRoot = resolve(defaultWorktreesRoot());
+  const target = resolve(targetPath);
+  if (target === worktreesRoot || !isInsidePath(target, worktreesRoot)) return null;
+  if (hasUnsafeTargetComponent(worktreesRoot, target)) return null;
+
+  let physicalWorktreesRoot: string;
+  try {
+    physicalWorktreesRoot = realpathSync(worktreesRoot);
+  } catch {
+    return null;
+  }
+
+  const leaseRoot = managedLeaseRoot(worktreesRoot, target);
+  if (!leaseRoot) return null;
+  let repoRootPromise = repoRootCache.get(leaseRoot);
+  if (!repoRootPromise) {
+    repoRootPromise = verifiedLinkedWorktreeRoot(leaseRoot);
+    repoRootCache.set(leaseRoot, repoRootPromise);
+  }
+  const repoRoot = await repoRootPromise;
+  if (!repoRoot) return null;
+  const resolvedRepoRoot = resolve(repoRoot);
+  if (resolvedRepoRoot !== resolve(leaseRoot)) return null;
+  try {
+    const physicalRepoRoot = realpathSync(resolvedRepoRoot);
+    if (physicalRepoRoot === physicalWorktreesRoot || !isInsidePath(physicalRepoRoot, physicalWorktreesRoot)) return null;
+    const probe = dirname(target);
+    let existingProbe = probe;
+    while (true) {
+      try {
+        lstatSync(existingProbe);
+        break;
+      } catch (error) {
+        if (!isMissingPathError(error)) return null;
+      }
+      const parent = dirname(existingProbe);
+      if (parent === existingProbe || !isInsidePath(parent, resolvedRepoRoot)) return null;
+      existingProbe = parent;
+    }
+    const physicalProbe = realpathSync(existingProbe);
+    const missingSuffix = relative(existingProbe, target);
+    if (!missingSuffix || missingSuffix === ".." || missingSuffix.startsWith(`..${sep}`) || isAbsolute(missingSuffix)) return null;
+    const physicalTarget = existsSync(target)
+      ? realpathSync(target)
+      : resolve(physicalProbe, missingSuffix);
+    if (physicalTarget === physicalRepoRoot || !isInsidePath(physicalTarget, physicalRepoRoot)) return null;
+  } catch {
+    return null;
+  }
+  return resolvedRepoRoot;
+}
+
 function threatensRule(targetPath: string, rule: ProtectedPathRule, currentManagedRepoRoot: string | null): boolean {
   if (shouldSkipHasnaTreeRule(targetPath, rule, currentManagedRepoRoot)) return false;
   const contentBase = broadContentWipeBase(targetPath);
@@ -849,12 +991,22 @@ export async function classifyDangerousOperation(input: CodewithHookInput): Prom
     }
   }
 
+  const managedRepoRootCache = new Map<string, Promise<string | null>>();
+  const worktreesRoot = resolve(defaultWorktreesRoot());
   for (const candidate of extractFileToolPaths(input)) {
     const targetPath = resolveFrom(cwd, candidate.path);
+    const hasUnsafeManagedComponent = isInsidePath(targetPath, worktreesRoot)
+      && hasUnsafeTargetComponent(worktreesRoot, targetPath);
+    const targetManagedRepoRoot = hasUnsafeManagedComponent
+      ? null
+      : await managedRepoRootForAbsoluteTarget(targetPath, managedRepoRootCache);
+    const exemptManagedRepoRoot = hasUnsafeManagedComponent
+      ? null
+      : targetManagedRepoRoot;
     const extraRule = workspaceRoots.map((root) => hasnaDivisionRuleFor(targetPath, root)).find((rule): rule is ProtectedPathRule => Boolean(rule));
     const allRules = extraRule ? [...rules, extraRule] : rules;
     for (const rule of allRules) {
-      if (mutatesRule(targetPath, rule, currentManagedRepoRoot)) {
+      if (mutatesRule(targetPath, rule, exemptManagedRepoRoot)) {
         return {
           block: true,
           targetPath,

package/hooks/hook-fleet-blockers-gate/README.md

@@ -1,6 +1,8 @@
 # hook-fleet-blockers-gate
 
-A PreToolUse hook that stops an agent from working through a fleet freeze. While an unread `[FREEZE]` blocking message is active, mutating tools are denied with a clear reason; read-only tools stay allowed so the agent can read the freeze and react. Part of the Hasna fleet comms workflow (every-turn insurance).
+A PreToolUse hook that stops an agent from working through a real fleet stop. While an unread **`blocking=1` blocker** is active, mutating tools are denied with a clear reason; read-only tools stay allowed so the agent can read the blocker and react. Part of the Hasna fleet comms workflow (every-turn insurance).
+
+To halt the fleet, the owner creates a `blocking=1` blocker (tag it `[FREEZE]` by convention); to lift it, the owner resolves/removes that blocker. Freeze **text** posted to channels is informational and never stops work.
 
 ## Installation
 
@@ -12,22 +14,32 @@ hooks install fleet-blockers-gate
 
 On each `PreToolUse` event:
 
-1. **Read-only tools pass immediately** — `Read`, `Glob`, `Grep`, `WebFetch`, MCP `get_*`/`list_*`/`search_*`-style operations, etc. A frozen agent must stay able to orient itself.
-2. **Freeze state is TTL-cached** (`~/.hasna/hooks/state/fleet-blockers-gate.json`, default 60s) so the common path never spawns a process per tool call.
-3. On cache expiry it runs `conversations blockers -j` with a hard 500ms timeout and scans unread blocking messages for the `[FREEZE]` severity tag.
-4. If frozen, mutating tools are denied via `permissionDecision: "deny"` with the freeze reason; the agent is told to read the blocker and wait for `[UNFREEZE]`.
+1. **Read-only tools pass immediately** — `Read`, `Glob`, `Grep`, `WebFetch`, MCP `get_*`/`list_*`/`search_*`-style operations, etc. A frozen agent must stay able to orient itself. **Exception:** `conversations` `read_*` tools (`read_messages`, `read_channel`, `read_digest`, `read_thread`, …) are **gated** during a freeze, because they mark messages read by default and would clear the blocker's unread state — self-lifting the stop just by browsing. A frozen agent inspects the blocker with the read-only `mcp__conversations__get_blockers` (and `get_message`/`search_messages`/`list_*`/`get_thread_replies`), none of which mark messages read.
+2. **Freeze state is TTL-cached** (`~/.hasna/hooks/state/fleet-blockers-gate.json`) so the common path never spawns a process per tool call. The TTL is asymmetric — a freeze is held for the full TTL (default 60s) but a "clear" is re-checked quickly (default 5s), so a freshly-issued freeze engages fast while a lift disengages slowly (the safe direction).
+3. On cache miss it runs `conversations blockers -j` once (default 1500ms timeout) and denies if the result contains **any** `blocking=1` blocker. `conversations blockers` (`getUnreadBlockers`) returns every unread, in-scope blocker with no limit window, so the check is order-independent and cannot be truncated.
+4. If frozen, mutating tools are denied via `permissionDecision: "deny"` with the blocker's author and text as **advisory** context; the agent is told the blocker must be resolved/removed to lift the stop.
+
+**Freeze text is never scanned.** Denial is driven solely by the `blocking=1` flag — this kills the phantom-freeze bug where any `[FREEZE]` string from any author wedged the fleet, and it stops ignoring real blockers that lacked the `[FREEZE]` text.
+
+**Author is not a security gate.** `conversations` does not authenticate `from_agent`, so the author is shown only as advisory context and is never used to allow or deny (gating on a spoofable field would be false assurance).
+
+**Fail-open by design:** if the `conversations` CLI is missing, the service is down, or the check times out, tools are allowed — the gate must never wedge an agent. An unverified (comms-failure) "clear" is not cached, so the check retries on the next mutating tool.
 
-Fail-open by design: if the `conversations` CLI is missing, the service is down, or the check times out, tools are allowed — the gate must never wedge an agent.
+## Operating notes & limitations
 
-The freeze clears when the blocking message is no longer unread (read + resolved), after which the next cache refresh allows tools again.
+- **Identity and membership are effectively required.** The blockers query is scoped to the agent (`getUnreadBlockers`: `to_agent = me OR channel in my channels`). Set `HOOKS_FLEET_AGENT` to the agent's **real registered identity**, and ensure that identity is a **member of a broadly-subscribed freeze channel**, with the freeze posted using `--blocking`. If the identity is wrong or not subscribed, the blocker is never returned and the brake silently no-ops (fail-open). Wiring this correctly is a deployment responsibility.
+- **Author-agnostic = fail-safe, not tamper-proof.** `conversations` does not authenticate `from_agent`, so the gate does not (and cannot meaningfully) trust the author. Any agent that can set `blocking=1` can therefore cause a stop; recovery is to resolve/remove the blocker or use the kill switch. This is a deliberate fail-safe tradeoff, not an authenticated control.
+- **The deny reason echoes untrusted content.** Up to ~240 characters of the blocker's body are included in the deny message as advisory context. Treat that text as untrusted input (it originates from whoever posted the blocker).
+- **The MCP read-only classification is a prefix heuristic.** Operations whose last `__` segment starts with `get`/`list`/`read`/`search`/… are treated as read-only. A destructively-named op (e.g. a hypothetical `get_and_reset`) could be misclassified as read-only; the `conversations` `read_*` family is explicitly gated as an exception. For high-assurance servers, prefer an explicit per-server allowlist.
 
 ## Configuration
 
 ```bash
-export HOOKS_FLEET_GATE_DISABLE=1     # Kill switch — allow everything
-export HOOKS_FLEET_GATE_TTL_MS=60000  # Cache TTL (default 60000)
-export HOOKS_FLEET_TIMEOUT_MS=500     # Blockers check timeout (default 500)
-export HOOKS_FLEET_AGENT="chief"      # Identity passed as --from
+export HOOKS_FLEET_GATE_DISABLE=1        # Kill switch — allow everything
+export HOOKS_FLEET_GATE_TTL_MS=60000     # Frozen-state cache TTL (default 60000)
+export HOOKS_FLEET_GATE_CLEAR_TTL_MS=5000 # Clear-state cache TTL (default 5000)
+export HOOKS_FLEET_TIMEOUT_MS=1500       # Blockers check timeout (default 1500)
+export HOOKS_FLEET_AGENT="chief"         # Identity passed as --from to scope the query
 ```
 
 ## Requirements

package/hooks/hook-fleet-blockers-gate/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hasna/hook-fleet-blockers-gate",
-  "version": "0.1.0",
-  "description": "Claude Code PreToolUse hook that blocks mutating tools while an unread [FREEZE] blocker is active (TTL-cached, fail-open under 500ms)",
+  "version": "0.1.1",
+  "description": "Claude Code PreToolUse hook that blocks mutating tools while an unread blocking=1 blocker is active (TTL-cached, fail-open)",
   "type": "module",
   "main": "./dist/hook.js",
   "exports": {

package/hooks/hook-fleet-blockers-gate/src/hook.test.ts

@@ -1,5 +1,16 @@
 import { describe, test, expect } from "bun:test";
-import { isReadOnlyTool, detectFreeze, parseBlockersJson } from "./hook";
+import {
+  isReadOnlyTool,
+  isSafeArg,
+  marksReadState,
+  buildDenyReason,
+  detectFreeze,
+  parseBlockersJson,
+  computeFreezeState,
+  decide,
+} from "./hook";
+
+const NOW = new Date("2026-07-20T00:00:00.000Z");
 
 describe("hook-fleet-blockers-gate", () => {
   describe("isReadOnlyTool", () => {
@@ -43,40 +54,156 @@ describe("hook-fleet-blockers-gate", () => {
       expect(isReadOnlyTool("mcp__x__getaway_driver")).toBe(false);
       expect(isReadOnlyTool("mcp__x__listen_events")).toBe(false);
     });
+
+    // self-lift fix: conversations read_* tools mark messages read, which would
+    // clear the blocker's read_at and lift the freeze — so they must be GATED.
+    test("conversations read_* tools are GATED (they mark messages read → self-lift)", () => {
+      expect(isReadOnlyTool("mcp__conversations__read_messages")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_channel")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_digest")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_thread")).toBe(false);
+      expect(isReadOnlyTool("mcp__conversations__read_channel_notifications")).toBe(false);
+    });
+
+    test("safe conversations orientation tools stay ALLOWED during a freeze", () => {
+      expect(isReadOnlyTool("mcp__conversations__get_blockers")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__get_message")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__search_messages")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__list_channels")).toBe(true);
+      expect(isReadOnlyTool("mcp__conversations__get_thread_replies")).toBe(true);
+    });
+
+    test("read_* gating is scoped to conversations (other servers' read_ ops unaffected)", () => {
+      expect(marksReadState("mcp__conversations__read_messages")).toBe(true);
+      expect(marksReadState("mcp__conversations__get_blockers")).toBe(false);
+      expect(marksReadState("mcp__files__read_file")).toBe(false);
+      // a non-conversations read_ op still passes the generic prefix rule
+      expect(isReadOnlyTool("mcp__files__read_file")).toBe(true);
+    });
   });
 
-  describe("detectFreeze", () => {
-    test("finds [FREEZE] in blocker content", () => {
+  describe("buildDenyReason", () => {
+    const msg = buildDenyReason("Active blocking=1 blocker from bot: [FREEZE] cutover");
+
+    test("points at the read-only get_blockers tool", () => {
+      expect(msg).toContain("mcp__conversations__get_blockers");
+    });
+
+    test("warns against the self-lifting read_* tools", () => {
+      expect(msg).toContain("read_messages");
+      expect(msg).toContain("read_channel");
+    });
+
+    test("does not tell the agent to run the gated Bash `conversations blockers` command", () => {
+      // The phrase must not appear as a bare command instruction (it is the MCP tool that is referenced).
+      expect(msg).not.toContain("conversations blockers");
+    });
+
+    test("carries the underlying blocker reason", () => {
+      expect(msg).toContain("Active blocking=1 blocker from bot");
+    });
+  });
+
+  describe("isSafeArg (argument-injection guard)", () => {
+    test("accepts fleet agent names and email-style ids", () => {
+      expect(isSafeArg("lycurgus")).toBe(true);
+      expect(isSafeArg("andrei@hasna.com")).toBe(true);
+      expect(isSafeArg("agent_07.beta-1")).toBe(true);
+    });
+
+    test("rejects leading dash (flag injection), spaces, shell metachars, empty", () => {
+      expect(isSafeArg("--from")).toBe(false);
+      expect(isSafeArg("-j")).toBe(false);
+      expect(isSafeArg("a b")).toBe(false);
+      expect(isSafeArg("a;rm -rf /")).toBe(false);
+      expect(isSafeArg("a`whoami`")).toBe(false);
+      expect(isSafeArg("$(id)")).toBe(false);
+      expect(isSafeArg("")).toBe(false);
+      expect(isSafeArg(undefined)).toBe(false);
+    });
+  });
+
+  describe("detectFreeze — blocking=1 is the only trigger", () => {
+    // blocking=1 -> DENY
+    test("a blocking=1 blocker freezes (author- and text-agnostic)", () => {
       const result = detectFreeze([
-        { from: "chief", content: "[FREEZE] cutover in progress — stop all publishes" },
+        { from_agent: "andrei@hasna.com", content: "[FREEZE] fleet cutover", blocking: true },
       ]);
       expect(result.frozen).toBe(true);
-      expect(result.reason).toContain("chief");
-      expect(result.reason).toContain("[FREEZE]");
+      expect(result.reason).toContain("blocking=1");
+      expect(result.reason).toContain("andrei@hasna.com");
     });
 
-    test("finds [FREEZE] in preview field", () => {
-      const result = detectFreeze([{ from: "chief", preview: "[FREEZE] db migration" }]);
+    test("a blocking=1 blocker with NO freeze text still freezes", () => {
+      const result = detectFreeze([
+        { from_agent: "release-bot", content: "migration running, do not deploy", blocking: true },
+      ]);
       expect(result.frozen).toBe(true);
+      expect(result.reason).toContain("release-bot");
     });
 
-    test("non-freeze blockers do not freeze", () => {
-      const result = detectFreeze([
-        { from: "worker", content: "please review PR #42 when you can" },
-      ]);
-      expect(result.frozen).toBe(false);
+    test("a blocking=1 blocker from any author freezes (author is not a security gate)", () => {
+      expect(detectFreeze([{ from_agent: "some-agent", content: "hold", blocking: true }]).frozen).toBe(true);
+    });
+
+    // freeze TEXT with no blocking=1 -> ALLOW (phantom-freeze bug stays fixed)
+    test("[FREEZE] text without a blocking flag does NOT freeze (phantom-freeze fix)", () => {
+      expect(
+        detectFreeze([{ from_agent: "andrei@hasna.com", content: "[FREEZE] heads up", blocking: false }]).frozen
+      ).toBe(false);
+      expect(
+        detectFreeze([{ from_agent: "some-agent", content: "[FREEZE] cutover", blocking: false }]).frozen
+      ).toBe(false);
+    });
+
+    test("[UNFREEZE]/severity text is ignored entirely (no text scanning)", () => {
+      expect(
+        detectFreeze([{ from_agent: "andrei@hasna.com", content: "[UNFREEZE] all clear", blocking: false }]).frozen
+      ).toBe(false);
     });
 
+    // no blockers -> ALLOW
     test("empty list does not freeze", () => {
       expect(detectFreeze([]).frozen).toBe(false);
     });
 
+    test("non-blocking messages do not freeze", () => {
+      expect(detectFreeze([{ from_agent: "worker", content: "please review PR #42", blocking: false }]).frozen).toBe(false);
+    });
+
     test("garbage entries are ignored", () => {
       expect(detectFreeze([null, 42, "string", {}]).frozen).toBe(false);
     });
 
-    test("lowercase freeze tag does not trigger (exact uppercase per HACP)", () => {
-      expect(detectFreeze([{ content: "[freeze] not a real tag" }]).frozen).toBe(false);
+    test("blocking flag tolerates numeric/string encodings (1, '1', 'true')", () => {
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: 1 }]).frozen).toBe(true);
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: "1" }]).frozen).toBe(true);
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: "true" }]).frozen).toBe(true);
+    });
+
+    test("false-y blocking encodings do not freeze", () => {
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: 0 }]).frozen).toBe(false);
+      expect(detectFreeze([{ from_agent: "x", content: "y", blocking: "false" }]).frozen).toBe(false);
+      expect(detectFreeze([{ from_agent: "x", content: "y" }]).frozen).toBe(false);
+    });
+
+    // order-independence: a green suite must not be able to hide a "first item only" bug
+    test("a blocking=1 blocker anywhere in the list freezes (order-independent)", () => {
+      const result = detectFreeze([
+        { from_agent: "a", content: "note 1", blocking: false },
+        { from_agent: "b", content: "note 2", blocking: false },
+        { from_agent: "c", content: "note 3", blocking: false },
+        { from_agent: "d", content: "the real stop", blocking: true },
+      ]);
+      expect(result.frozen).toBe(true);
+      expect(result.reason).toContain("the real stop");
+    });
+
+    test("reads the real from_agent schema field for the advisory reason", () => {
+      const result = detectFreeze([
+        { from_agent: "coordinator", to_agent: "worker", channel: "announcements", content: "stop", blocking: true },
+      ]);
+      expect(result.reason).toContain("coordinator");
     });
   });
 
@@ -103,4 +230,73 @@ describe("hook-fleet-blockers-gate", () => {
     });
   });
 
+  describe("computeFreezeState — fail-open + verified", () => {
+    // comms error -> ALLOW (fail-open, unverified)
+    test("runner error → fail-open (not frozen, unverified)", () => {
+      const e = computeFreezeState(NOW, () => {
+        throw new Error("conversations CLI missing / timeout");
+      });
+      expect(e.state.frozen).toBe(false);
+      expect(e.verified).toBe(false);
+    });
+
+    // no blockers -> ALLOW (verified)
+    test("empty blockers → not frozen, verified", () => {
+      const e = computeFreezeState(NOW, () => "[]");
+      expect(e.state.frozen).toBe(false);
+      expect(e.verified).toBe(true);
+    });
+
+    // blocking=1 -> DENY
+    test("blocking=1 in CLI output → frozen, verified", () => {
+      const raw = JSON.stringify([{ from_agent: "bot", content: "deploy freeze", blocking: true }]);
+      const e = computeFreezeState(NOW, () => raw);
+      expect(e.state.frozen).toBe(true);
+      expect(e.verified).toBe(true);
+    });
+
+    test("parses the real wrapped shape and stays order-independent", () => {
+      const raw = JSON.stringify({
+        blockers: [
+          { from_agent: "a", content: "x", blocking: false },
+          { from_agent: "b", content: "stop now", blocking: true },
+        ],
+      });
+      const e = computeFreezeState(NOW, () => raw);
+      expect(e.state.frozen).toBe(true);
+    });
+
+    test("malformed CLI output → fail-open (not frozen) but verified", () => {
+      const e = computeFreezeState(NOW, () => "not-json-at-all");
+      expect(e.state.frozen).toBe(false);
+      expect(e.verified).toBe(true);
+    });
+  });
+
+  describe("decide — permission gate", () => {
+    const frozen = { frozen: true, reason: "Active blocking=1 blocker from bot: x" };
+    const clear = { frozen: false, reason: "" };
+
+    // HOOKS_FLEET_GATE_DISABLE=1 -> ALLOW
+    test("kill switch (disabled) → allow even under a freeze", () => {
+      expect(decide({ disabled: true, toolName: "Bash", freeze: frozen }).allow).toBe(true);
+    });
+
+    // read-only tool under a blocker -> ALLOW
+    test("read-only tool under an active freeze → allow", () => {
+      expect(decide({ disabled: false, toolName: "Read", freeze: frozen }).allow).toBe(true);
+      expect(decide({ disabled: false, toolName: "mcp__conversations__get_blockers", freeze: frozen }).allow).toBe(true);
+    });
+
+    // blocking=1 + mutating -> DENY
+    test("mutating tool under an active freeze → deny (with reason)", () => {
+      const d = decide({ disabled: false, toolName: "Bash", freeze: frozen });
+      expect(d.allow).toBe(false);
+      expect(d.reason).toContain("blocking=1");
+    });
+
+    test("mutating tool with no freeze → allow", () => {
+      expect(decide({ disabled: false, toolName: "Bash", freeze: clear }).allow).toBe(true);
+    });
+  });
 });