petbox-wire 0.1.0-ci.1206

package/src/harness-models.ts

@@ -0,0 +1,158 @@
+// Per-harness model-id policy for the agent-artifact compiler.
+//
+// Sibling of harness-capabilities.ts, same contract: EVERY cell is a factual claim about a
+// harness taken from that harness's docs or a verified live observation. Do not invent.
+//
+// WHY THIS EXISTS (intake `wire-apply-writes-unresolvable-model-id`, 2026-07-12; policy
+// REVISED 2026-07-13 after a live-fire measurement falsified the original premise — see task
+// `model-gate-revision-premise-falsified`): `apply` wrote whatever ~/.petbox/roles.json said
+// into the target harness's frontmatter. The 2026-07-12 incident was a roles.json whose
+// `claude-code` block had been filled with a Factory Droid id (`custom:DeepSeek-V4-Pro-0`).
+// The gate was built on the assumption that Claude Code SILENTLY falls back to the session's
+// model on an unresolvable `model:`. A live measurement (`claude -p`, four runs incl. a haiku
+// control and the literal incident id) disproved that: Claude Code fails LOUD — zero subagent
+// tokens, `Agent terminated early due to an API error: There's an issue with the selected model
+// (...)` — for every unresolvable id tried, alias-shaped or concrete-id-shaped alike.
+//
+// A closed allow-list built on the false premise mostly produced FALSE POSITIVES instead: a
+// brand-new id Claude Code would happily accept (e.g. a future `claude-opus-5`) got blocked by
+// `apply` before the harness ever saw it, purely because this file's list hadn't caught up yet.
+//
+// Policy is now THREE-tier per harness:
+//   known   — an alias/`inherit` value (or, for an open-policy harness, any id — see below).
+//             No violation, no warning.
+//   unknown — shape-valid for this harness (looks like one of its own ids, e.g. `claude-*`) but
+//             not on the small known-alias list — plausibly a real id newer than this file.
+//             NON-BLOCKING: write it and warn. If it is actually wrong, the harness itself now
+//             fails loud at runtime (verified above) — an acceptable, visible failure mode this
+//             gate no longer needs to preempt.
+//   foreign — recognizably ANOTHER harness's id shape (droid's `custom:*` BYOK scheme, or a
+//             `provider/model` id — opencode's own syntax) landing in this harness's binding.
+//             That is the 2026-07-12 incident shape exactly. BLOCKING: refuse to write it.
+//
+// Per-harness id-space claim:
+//   closed — the harness's KNOWN aliases are enumerable (used for the "known" tier); ids outside
+//            that list are classified unknown/foreign by SHAPE, not by a maintained exhaustive
+//            catalog (see classifyModel below).
+//   open   — the id space is provider-defined and open-ended (a registry/gateway resolves it);
+//            we make no claim at all, so the gate never fires. This is honesty, not laxity: a
+//            false allow-list would block legitimate ids.
+//
+// What this gate still cannot see, and remains defensive about: a model that IS valid but is
+// excluded by an org `availableModels` policy, where Claude Code is documented to silently fall
+// back to inherit. That path has not been measured live (it needs an org policy to test
+// against) — it is the reason this gate is not simply deleted, only narrowed.
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import type { HarnessId } from "./harness-capabilities.ts";
+
+export type HarnessModelPolicy =
+  | { readonly kind: "closed"; readonly allowed: readonly string[] }
+  | { readonly kind: "open"; readonly reason: string };
+
+/** Three-tier classification of a candidate model id for a given harness (see file header). */
+export type ModelClassification = "known" | "unknown" | "foreign";
+
+/**
+ * Claude Code frontmatter `model:` known-alias list — tier aliases + `inherit`.
+ * Verified live in this repo's roster (.claude/agents/*.md, 2026-07-12) — opus, sonnet, haiku,
+ * fable all register and resolve; `inherit` is the documented "use the parent's model" value.
+ * Also verified live 2026-07-13: the Task-tool `model` parameter is a CLOSED ENUM restricted to
+ * exactly these four tier aliases (`sonnet|opus|haiku|fable`) — a concrete id there is rejected
+ * by input-schema validation before any API call. A concrete Anthropic model id (`claude-opus-4-8`
+ * and similar) is real and resolvable in frontmatter, but deliberately NOT enumerated here: the
+ * catalog changes faster than this file, and an unlisted-but-real id must warn, not block (see
+ * classifyModel's "unknown" tier) — that is the whole point of the 2026-07-13 revision.
+ */
+const CLAUDE_CODE_MODELS: readonly string[] = ["inherit", "haiku", "sonnet", "opus", "fable"] as const;
+
+const MODEL_POLICIES: Readonly<Record<HarnessId, HarnessModelPolicy>> = {
+  "claude-code": { kind: "closed", allowed: CLAUDE_CODE_MODELS },
+  // opencode resolves `provider/model` against whatever providers are configured locally
+  // (models.dev catalog + custom providers) — the set is not knowable from the kit.
+  opencode: {
+    kind: "open",
+    reason: "opencode resolves provider/model ids against the locally configured providers",
+  },
+  // Factory droid frontmatter takes `inherit` or an id from the workspace's model registry,
+  // including BYOK `custom:*` entries — not knowable from the kit.
+  // https://docs.factory.ai/cli/configuration/custom-droids § Controlling the model
+  droid: {
+    kind: "open",
+    reason: "droid resolves ids against the workspace model registry (incl. custom:* BYOK)",
+  },
+};
+
+/**
+ * Model policy for a harness id.
+ * Unknown harness → open (we know nothing about its model space; the capability gate already
+ * blocks every role on an unknown harness, so nothing slips through here).
+ */
+export function harnessModelPolicy(harness: string): HarnessModelPolicy {
+  const p = (MODEL_POLICIES as Record<string, HarnessModelPolicy | undefined>)[harness];
+  return p ?? { kind: "open", reason: `unknown harness '${harness}' — no model claims` };
+}
+
+/** Known-alias ids for a harness ("known" tier only), or null when the harness's id space is open. */
+export function allowedModels(harness: string): readonly string[] | null {
+  const p = harnessModelPolicy(harness);
+  return p.kind === "closed" ? p.allowed : null;
+}
+
+/** Strip a trailing context-window suffix: `claude-opus-4-8[1m]` → `claude-opus-4-8`. */
+function stripContextSuffix(model: string): string {
+  return model.replace(/\[[^\]]*\]$/, "");
+}
+
+/**
+ * Shape of ANOTHER harness's model id landing in this binding: droid's BYOK scheme
+ * (`custom:DeepSeek-V4-Pro-0`) or a `provider/model` id (opencode's own syntax, e.g.
+ * `deepseek/deepseek-v4-pro`, `anthropic/claude-sonnet-4`). Claude Code frontmatter never uses
+ * either shape — this is a naming-convention fact, not a claim about any specific catalog.
+ */
+function looksLikeForeignHarnessId(model: string): boolean {
+  return model.includes("/") || model.includes(":");
+}
+
+/**
+ * Shape of a Claude Code / Anthropic model id: the `claude-` prefix (case-insensitive), on the
+ * id with its context-window suffix already stripped. Every concrete Anthropic id observed to
+ * date starts this way — matching it is not a claim that any particular suffix resolves, only
+ * that it is plausibly this harness's own id and not a typo of something unrelated.
+ */
+function looksLikeClaudeId(model: string): boolean {
+  return /^claude-/i.test(model);
+}
+
+/**
+ * Three-tier classification of `model` for `harness` (see file header for the policy).
+ * Open-policy harness → always "known" (no claim is made, so nothing is ever flagged).
+ * Closed-policy harness (claude-code today):
+ *   - exact allow-list membership (case-insensitive, `[1m]`-suffix ignored) → "known";
+ *   - else a recognizable foreign-harness shape (`provider/model`, `scheme:id`) → "foreign";
+ *   - else this harness's own id shape (`claude-*`) → "unknown" (plausible, unverified);
+ *   - else (matches no known shape at all, e.g. `gpt-5`) → "foreign".
+ * An empty/blank model has no shape to classify — callers must guard blank separately (unbound
+ * is legitimate inherit, not a model to classify; see checkRoleModelTruthfulness).
+ */
+export function classifyModel(harness: string, model: string): ModelClassification {
+  const policy = harnessModelPolicy(harness);
+  if (policy.kind === "open") return "known";
+  const m = stripContextSuffix(model.trim()).toLowerCase();
+  if (!m) return "foreign";
+  if (policy.allowed.some((a) => a.toLowerCase() === m)) return "known";
+  if (looksLikeForeignHarnessId(m)) return "foreign";
+  if (looksLikeClaudeId(m)) return "unknown";
+  return "foreign";
+}
+
+/**
+ * Can `harness` be written `model` at all — i.e. is this NOT the blocking "foreign" tier?
+ * True for both "known" and "unknown" (shape-valid, non-blocking) classifications; false only
+ * for "foreign". Use classifyModel directly when the known/unknown distinction matters (e.g. to
+ * decide whether to emit a non-blocking warning).
+ */
+export function isResolvableModel(harness: string, model: string): boolean {
+  return classifyModel(harness, model) !== "foreign";
+}

package/src/hook-drain.ts

@@ -0,0 +1,42 @@
+// Shared "let me exit already" helper for the SessionStart/Stop hooks (pull-memory.ts,
+// push-session.ts, droid-pull-memory.ts, droid-push-session.ts).
+//
+// Empirically measured (not assumed — see the exit comments in those files): an aborted
+// fetch() against a REAL remote server that is slow/stalled (not a fast ECONNREFUSED) can
+// leave its underlying TLSSocket alive for several seconds — sometimes ~10s — AFTER the
+// AbortController fires and our own await has already settled, even with `Connection: close`
+// sent on the request. `Connection: close` does stop keep-alive from being the default
+// blocker (confirmed: a completed request's socket closes immediately), but it does not
+// speed up the teardown of a socket whose request never got a response before being aborted.
+// Left alone, a hook process that just returns from main() would sit waiting for the OS/TLS
+// stack to finish that teardown, turning one slow session start into an ~18s stall (2x the
+// fetch budget, since two separate fetch attempts can each leave one behind).
+//
+// The fix is NOT to hard `process.exit()` — that is the exact race that caused the original
+// crash (`Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`) when a handle was mid-close.
+// Instead: mark any still-open handles as non-blocking for the event loop (`unref()`) once our
+// own logical work is done. Node keeps tearing them down in the background exactly as it would
+// have anyway (nothing is force-destroyed, so there is no close-teardown race) — it just stops
+// waiting on them to decide the process is finished, so a natural exit follows immediately.
+//
+// process._getActiveHandles() is a private/undocumented Node API (no public equivalent exists;
+// process.getActiveResourcesInfo() is public but returns descriptive strings, not handle
+// references, so it cannot be used to unref anything). It has been stable across Node versions
+// for a very long time and is the same mechanism debugging tools like wtfnode/why-is-node-running
+// rely on. Best-effort: wrapped so a future Node removing/renaming it degrades to "do nothing"
+// rather than throwing.
+export function unrefLingeringHandles(): void {
+  try {
+    const handles = (process as unknown as { _getActiveHandles?: () => unknown[] })._getActiveHandles?.();
+    if (!Array.isArray(handles)) return;
+    for (const h of handles) {
+      try {
+        (h as { unref?: () => void }).unref?.();
+      } catch {
+        // best-effort per handle
+      }
+    }
+  } catch {
+    // best-effort: never let this stop the hook from exiting
+  }
+}

package/src/hook-prune.test.ts

@@ -0,0 +1,165 @@
+// Unit tests for the retired-prompt-RAG hook MIGRATION (hook-prune.ts).
+//
+// What this pins: prompt-RAG was removed from the kit, but a machine that ever ran
+// `petbox-wire --prompt-rag` still has the hook command written into ~/.claude/settings.json and
+// ~/.factory/settings.json, pointing at a prompt-rag.ts the kit no longer ships. If wire only
+// deleted the kit files, that hook would fail on EVERY prompt. So wire prunes it unconditionally,
+// idempotently, and without disturbing any other hook — exactly the four properties below.
+//
+// The logic lives in its own module precisely so it can be tested: wire.ts runs main() at import
+// time and can never be imported by a test (same reason wire-exit.ts / posix-env.ts exist).
+//
+// Run: node --test src/hook-prune.test.ts   (Node >= 23.6 native TS type-stripping)
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  hasDeadPromptRagHook,
+  hasHookTargeting,
+  LEGACY_PROMPT_RAG_FILE,
+  pruneDeadPromptRagHooks,
+  pruneHooksTargeting,
+} from "./hook-prune.ts";
+
+// The two commands older kits actually wrote (CC plain; Droid with the --agent droid suffix).
+const CC_RAG_CMD = 'node "C:\\Users\\x\\.petbox\\wire\\prompt-rag.ts"';
+const DROID_RAG_CMD = 'node "C:\\Users\\x\\.petbox\\wire\\prompt-rag.ts" --agent droid';
+const PUSH_CMD = 'node "C:\\Users\\x\\.petbox\\wire\\push-session.ts"';
+const PULL_CMD = 'node "C:\\Users\\x\\.petbox\\wire\\pull-memory.ts"';
+const FOREIGN_CMD = 'node "C:\\Users\\x\\my-own-hooks\\lint.ts"';
+
+const cmd = (command: string) => ({ type: "command", command });
+
+// A realistic ~/.claude/settings.json `hooks` object from a machine that opted into prompt-RAG.
+function claudeHooksWithRag(): any {
+  return {
+    Stop: [{ hooks: [cmd(PUSH_CMD)] }],
+    SessionStart: [{ hooks: [cmd(PULL_CMD)] }],
+    UserPromptSubmit: [{ hooks: [cmd(CC_RAG_CMD)] }],
+  };
+}
+
+// ---- prune when present ----------------------------------------------------------------------
+
+test("prune removes the dead prompt-rag hook from a Claude settings hooks object", () => {
+  const hooks = claudeHooksWithRag();
+  assert.equal(hasDeadPromptRagHook(hooks), true);
+
+  const pruned = pruneDeadPromptRagHooks(hooks);
+
+  assert.equal(pruned, 1);
+  assert.equal(hasDeadPromptRagHook(hooks), false);
+  // The now-empty event key is gone entirely (no `"UserPromptSubmit": []` litter).
+  assert.equal("UserPromptSubmit" in hooks, false);
+});
+
+test("prune catches the droid variant (`--agent droid` suffix) — matching is on the quoted basename", () => {
+  const hooks = { UserPromptSubmit: [{ hooks: [cmd(DROID_RAG_CMD)] }] };
+  assert.equal(hasDeadPromptRagHook(hooks), true);
+  assert.equal(pruneDeadPromptRagHooks(hooks), 1);
+  assert.equal(hasDeadPromptRagHook(hooks), false);
+});
+
+test("prune removes BOTH variants and every duplicate, wherever they sit", () => {
+  const hooks = {
+    UserPromptSubmit: [
+      { hooks: [cmd(CC_RAG_CMD), cmd(FOREIGN_CMD)] },
+      { hooks: [cmd(DROID_RAG_CMD)] },
+      { hooks: [cmd(CC_RAG_CMD)] }, // a duplicate group from a re-wire on an older kit
+    ],
+  };
+  assert.equal(pruneDeadPromptRagHooks(hooks), 3);
+  // The user's own hook in the shared group survives; the groups that held ONLY rag hooks are gone.
+  assert.deepEqual(hooks.UserPromptSubmit, [{ hooks: [cmd(FOREIGN_CMD)] }]);
+});
+
+// ---- no-op when absent -----------------------------------------------------------------------
+
+test("no-op when no prompt-rag hook is present: nothing removed, object untouched", () => {
+  const hooks = {
+    Stop: [{ hooks: [cmd(PUSH_CMD)] }],
+    SessionStart: [{ hooks: [cmd(PULL_CMD)] }],
+  };
+  const before = JSON.stringify(hooks);
+
+  assert.equal(hasDeadPromptRagHook(hooks), false);
+  assert.equal(pruneDeadPromptRagHooks(hooks), 0);
+  assert.equal(JSON.stringify(hooks), before);
+});
+
+test("no-op on a settings file with no hooks at all (missing / junk hooks value)", () => {
+  assert.equal(pruneDeadPromptRagHooks(undefined), 0);
+  assert.equal(pruneDeadPromptRagHooks(null), 0);
+  assert.equal(pruneDeadPromptRagHooks("nonsense"), 0);
+  assert.equal(pruneDeadPromptRagHooks({}), 0);
+  assert.equal(hasDeadPromptRagHook(undefined), false);
+  assert.equal(hasDeadPromptRagHook({}), false);
+});
+
+// ---- idempotence -----------------------------------------------------------------------------
+
+test("double run is a byte-identical no-op (idempotent: the second wire changes nothing)", () => {
+  const hooks = claudeHooksWithRag();
+
+  assert.equal(pruneDeadPromptRagHooks(hooks), 1);
+  const afterFirst = JSON.stringify(hooks);
+
+  // Second `wire` run on the same machine: nothing left to prune → nothing rewritten.
+  assert.equal(pruneDeadPromptRagHooks(hooks), 0);
+  assert.equal(JSON.stringify(hooks), afterFirst);
+
+  // …and a third, for good measure.
+  assert.equal(pruneDeadPromptRagHooks(hooks), 0);
+  assert.equal(JSON.stringify(hooks), afterFirst);
+});
+
+// ---- leaves everything else alone ------------------------------------------------------------
+
+test("leaves other hooks alone — kit hooks, foreign hooks, and unrelated events all survive", () => {
+  const hooks: any = {
+    Stop: [{ hooks: [cmd(PUSH_CMD)] }],
+    SessionStart: [{ hooks: [cmd(PULL_CMD)] }],
+    UserPromptSubmit: [
+      { hooks: [cmd(FOREIGN_CMD)] }, // someone else's UserPromptSubmit hook
+      { hooks: [cmd(CC_RAG_CMD)] },
+    ],
+    PreToolUse: [{ matcher: "Bash", hooks: [cmd(FOREIGN_CMD)] }],
+  };
+
+  assert.equal(pruneDeadPromptRagHooks(hooks), 1);
+
+  assert.deepEqual(hooks, {
+    Stop: [{ hooks: [cmd(PUSH_CMD)] }],
+    SessionStart: [{ hooks: [cmd(PULL_CMD)] }],
+    UserPromptSubmit: [{ hooks: [cmd(FOREIGN_CMD)] }], // event kept — it still has a real hook
+    PreToolUse: [{ matcher: "Bash", hooks: [cmd(FOREIGN_CMD)] }], // matcher preserved
+  });
+});
+
+test("leaves shapes it does not own exactly as found (non-array event, pre-existing empty group)", () => {
+  const hooks: any = {
+    Weird: "not-an-array",
+    SessionStart: [{ hooks: [] }, { hooks: [cmd(PULL_CMD)] }], // an empty group we did NOT create
+    UserPromptSubmit: [{ hooks: [cmd(CC_RAG_CMD)] }],
+  };
+
+  assert.equal(pruneDeadPromptRagHooks(hooks), 1);
+
+  assert.deepEqual(hooks, {
+    Weird: "not-an-array",
+    SessionStart: [{ hooks: [] }, { hooks: [cmd(PULL_CMD)] }],
+  });
+});
+
+// ---- the generic primitive (kept from the deleted prompt-rag-hook.ts) -------------------------
+
+test("pruneHooksTargeting / hasHookTargeting match on the QUOTED basename of any kit file", () => {
+  assert.equal(LEGACY_PROMPT_RAG_FILE, "prompt-rag.ts");
+
+  const hooks = { Stop: [{ hooks: [cmd(PUSH_CMD)] }] };
+  assert.equal(hasHookTargeting(hooks, "push-session.ts"), true);
+  assert.equal(hasHookTargeting(hooks, "pull-memory.ts"), false); // a different kit file
+  assert.equal(hasHookTargeting(hooks, "push-session"), false); // the CLOSING QUOTE is part of the needle
+  assert.equal(pruneHooksTargeting(hooks, "push-session.ts"), 1);
+  assert.deepEqual(hooks, {});
+});

package/src/hook-prune.ts

@@ -0,0 +1,83 @@
+// Settings surgery for GLOBAL agent hook files (~/.claude/settings.json, ~/.factory/settings.json).
+//
+// Why this module exists at all: prompt-RAG (a global UserPromptSubmit hook that injected exact-match
+// context) has been REMOVED from the kit. But a machine that ever ran `petbox-wire --prompt-rag` has
+// the hook command WRITTEN INTO those two settings files, pointing at `<STABLE>/prompt-rag.ts`. The
+// kit no longer ships that file, so the leftover hook would fail on EVERY prompt. Deleting the kit
+// files without pruning the settings is therefore not a removal — it is a breakage.
+//
+// So `wire` runs the prune UNCONDITIONALLY (there is no flag left to gate it on) and idempotently:
+// it removes only hook entries whose command targets prompt-rag.ts (both the plain Claude Code
+// variant and the `--agent droid` one), leaves every other hook untouched, and a second run is a
+// byte-identical no-op (the caller only rewrites the file when something was actually removed).
+//
+// Lives in its own side-effect-free module (like wire-exit.ts / posix-env.ts / wire-identity.ts)
+// precisely so it is importable by a test: wire.ts runs main() at import time and cannot be.
+//
+// Plain TS for native node type-stripping: no enum/namespace/parameter-properties, zero deps.
+
+// The kit file every legacy prompt-RAG hook command targets, on either agent. Both variants are
+//   node "<...>/prompt-rag.ts"                (Claude Code)
+//   node "<...>/prompt-rag.ts" --agent droid  (Factory Droid)
+// so matching the QUOTED basename catches both without caring where the stable kit lives.
+export const LEGACY_PROMPT_RAG_FILE = "prompt-rag.ts";
+
+// Remove EVERY hook (across all events) whose command targets the given STABLE kit file, then drop
+// the groups THIS call emptied (and an event key it emptied entirely). Mutates hooksObj in place;
+// returns the count pruned. Deliberately conservative:
+//   - a non-array event value is left exactly as found (we never rewrite a shape we do not own),
+//   - a group that was already empty before this call is left alone (it is not ours to clean),
+// so on a settings file with no prompt-rag hook this is a pure read: returns 0, mutates nothing.
+export function pruneHooksTargeting(hooksObj: any, fileBasename: string): number {
+  if (!hooksObj || typeof hooksObj !== "object") return 0;
+  let removed = 0;
+  const needle = `${fileBasename}"`;
+  for (const event of Object.keys(hooksObj)) {
+    if (!Array.isArray(hooksObj[event])) continue;
+    const groups: any[] = hooksObj[event];
+    const emptiedHere = new Set<any>();
+    for (const g of groups) {
+      if (!g || !Array.isArray(g.hooks)) continue;
+      const before = g.hooks.length;
+      g.hooks = g.hooks.filter(
+        (h: any) => !(typeof h?.command === "string" && h.command.includes(needle)),
+      );
+      const gone = before - g.hooks.length;
+      removed += gone;
+      if (gone > 0 && g.hooks.length === 0) emptiedHere.add(g);
+    }
+    if (emptiedHere.size === 0) continue;
+    const kept = groups.filter((g) => !emptiedHere.has(g));
+    if (kept.length === 0) delete hooksObj[event];
+    else hooksObj[event] = kept;
+  }
+  return removed;
+}
+
+// Does this settings `hooks` object carry a hook targeting the given kit file? (Quoted-basename
+// match, so it is agnostic to where the stable kit lives.) Read-only.
+export function hasHookTargeting(hooksObj: any, fileBasename: string): boolean {
+  if (!hooksObj || typeof hooksObj !== "object") return false;
+  const needle = `${fileBasename}"`;
+  for (const event of Object.keys(hooksObj)) {
+    const groups: any[] = Array.isArray(hooksObj[event]) ? hooksObj[event] : [];
+    for (const g of groups) {
+      if (!g || !Array.isArray(g.hooks)) continue;
+      if (g.hooks.some((h: any) => typeof h?.command === "string" && h.command.includes(needle))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// The migration itself: drop every dead prompt-RAG hook from one agent's `hooks` object.
+// Returns the number removed (0 = nothing to do = the caller must not rewrite the file).
+export function pruneDeadPromptRagHooks(hooksObj: any): number {
+  return pruneHooksTargeting(hooksObj, LEGACY_PROMPT_RAG_FILE);
+}
+
+// Does this settings `hooks` object still carry a dead prompt-RAG hook?
+export function hasDeadPromptRagHook(hooksObj: any): boolean {
+  return hasHookTargeting(hooksObj, LEGACY_PROMPT_RAG_FILE);
+}