@cad0p/pi-steering 0.1.0

package/src/observer-dispatcher.ts

@@ -0,0 +1,290 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * v2 observer dispatcher.
+ *
+ * Observers are the `tool_result` side of the steering engine: rules
+ * decide "can this run" pre-execution; observers record "what happened"
+ * post-execution. Typical use is to `appendEntry` into pi's session
+ * JSONL so later predicates can gate on prior turn state (the
+ * "description was read in a PRIOR turn" idiom from the ADR).
+ *
+ * This module merges user-declared observers (from
+ * {@link SteeringConfig.observers}) with plugin-shipped ones (from
+ * {@link ResolvedPluginState.observers}), then on every `tool_result`:
+ *
+ *   1. Applies the observer's `watch` filter (toolName + inputMatches
+ *      + exitCode). No `watch` means "fire on every tool_result".
+ *   2. Calls `observer.onResult(event, observerCtx)`. Awaits if it
+ *      returns a promise.
+ *   3. Catches thrown errors per-observer — one buggy observer does
+ *      NOT prevent the rest from running.
+ *
+ * Observer context (`ObserverContext`) is built fresh per event, using
+ * `appendEntry` and `findEntries` closures shared with the evaluator.
+ * `exec` is deliberately NOT exposed — observers are expected to be
+ * lightweight state-recording hooks. Complex tool_result analysis that
+ * needs to shell out belongs in a separate pi extension hook or in a
+ * rule's `when.condition` pre-execution, not in an observer.
+ *
+ * Wiring (Phase 3c): the extension runtime subscribes to `tool_result`
+ * and forwards the event + current `agentLoopIndex` into `dispatch`.
+ */
+
+import type {
+  ExtensionContext,
+  ToolResultEvent as PiToolResultEvent,
+} from "@earendil-works/pi-coding-agent";
+import {
+  createAppendEntry,
+  createFindEntries,
+  createSessionEntryCache,
+  type EvaluatorHost,
+} from "./evaluator-internals/context.ts";
+import { mergeObserversUserFirst } from "./internal/merge-observers.ts";
+import {
+  extractRefTextsForBash,
+  matchesWatch,
+} from "./internal/watch-matcher.ts";
+import type { ResolvedPluginState } from "./plugin-merger.ts";
+import { validateName } from "./plugin-merger.ts";
+import type {
+  Observer,
+  ObserverContext,
+  ToolResultEvent as SchemaToolResultEvent,
+} from "./schema.ts";
+
+// Re-export the shared filter contract so existing consumers that
+// imported `matchesWatch` from this module (most notably the testing
+// harness's `testObserver`) don't need to switch imports. The source
+// of truth lives in `./internal/watch-matcher.ts`; this re-export
+// keeps the public surface stable.
+export { matchesWatch } from "./internal/watch-matcher.ts";
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime-facing dispatcher handle. Phase 3c holds an instance per
+ * session and calls {@link dispatch} from the pi `tool_result` listener.
+ */
+export interface ObserverDispatcher {
+  /**
+   * Dispatch a single `tool_result` to every matching observer.
+   *
+   * Resolves when all observer handlers have settled. Handlers that
+   * throw are caught + logged via `console.warn` and do not prevent
+   * subsequent observers from running.
+   */
+  dispatch(
+    event: PiToolResultEvent,
+    ctx: ExtensionContext,
+    agentLoopIndex: number,
+  ): Promise<void>;
+}
+
+/**
+ * Construct an {@link ObserverDispatcher}.
+ *
+ * Arguments:
+ *   - `resolved`       — merged plugin state from {@link resolvePlugins}.
+ *                         Source of plugin-shipped observers and the
+ *                         registry used by the evaluator at the same
+ *                         level.
+ *   - `userObservers`  — the user's `config.observers` list (already
+ *                         deduped at the loader level in Phase 2). User
+ *                         observers fire BEFORE plugin observers on the
+ *                         same event; within each group, registration
+ *                         order decides.
+ *   - `host`           — narrow surface exposing pi's `exec` +
+ *                         `appendEntry`. Passed straight through to the
+ *                         per-event observer context.
+ */
+export function buildObserverDispatcher(
+  resolved: ResolvedPluginState,
+  userObservers: readonly Observer[],
+  host: EvaluatorHost,
+): ObserverDispatcher {
+  // S3 defense-in-depth: validate user-authored observer names so a
+  // malformed name surfaces with the same `(user config)` label as
+  // production diagnostics. Production routes through
+  // `runMergerPipeline`'s `invalid-name` diagnostic; this throw
+  // covers direct-caller paths (unit tests, SDK embedders).
+  // See ./INVARIANTS.md for the S/E tag glossary.
+  for (const o of userObservers) {
+    const d = validateName("observer", o.name, "user config");
+    if (d !== undefined) throw new Error(`[pi-steering] ${d.message}`);
+  }
+
+  // Merge user and plugin observers; duplicates of observer.name are
+  // deduped here by first-registered (user takes precedence over a
+  // plugin observer of the same name — matches the "user overrides
+  // plugin by declaring their own" pattern the rule list uses). Shared
+  // with the evaluator's speculative-synthesis reverse-index via
+  // `mergeObserversUserFirst` so both callers see the same final list.
+  const merged = mergeObserversUserFirst(userObservers, resolved.observers);
+
+  return {
+    dispatch: (event, ctx, agentLoopIndex) =>
+      dispatchEvent(event, ctx, agentLoopIndex, merged, host),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+async function dispatchEvent(
+  event: PiToolResultEvent,
+  ctx: ExtensionContext,
+  agentLoopIndex: number,
+  observers: readonly Observer[],
+  host: EvaluatorHost,
+): Promise<void> {
+  // Top-level fail-open wrap. Per-observer throws are already
+  // isolated in the inner loop; this outer wrap exists so a throw in
+  // the dispatch SCAFFOLDING (e.g. a session-JSONL read blowing up
+  // inside `createFindEntries`, or an unexpected shape on the
+  // incoming event) is logged rather than propagating back into pi's
+  // `tool_result` hook. Observers are best-effort state recorders —
+  // a broken engine should not take down the tool_result pipeline.
+  try {
+    await dispatchEventInner(event, ctx, agentLoopIndex, observers, host);
+  } catch (err) {
+    console.warn(
+      `[pi-steering] observer dispatcher threw: ${formatError(err)}`,
+    );
+  }
+}
+
+async function dispatchEventInner(
+  event: PiToolResultEvent,
+  ctx: ExtensionContext,
+  agentLoopIndex: number,
+  observers: readonly Observer[],
+  host: EvaluatorHost,
+): Promise<void> {
+  // Shared per-event session-entry cache: findEntries + appendEntry
+  // share it so an earlier observer's appendEntry invalidates the
+  // cached read for that customType, and a later observer's
+  // findEntries(customType) sees the fresh write (S2/E1). Without the
+  // shared cache, observer A appending "description-read" + observer
+  // B reading "description-read" on the same event would see a stale
+  // pre-write snapshot.
+  const entryCache = createSessionEntryCache();
+  const findEntries = createFindEntries(ctx, entryCache);
+  // Shared appendEntry: auto-tags writes with `_agentLoopIndex` so
+  // `when.happened: { in: "agent_loop" }` can filter by agent-loop
+  // scope. Safe to hoist out of the loop: the wrapper is stateless.
+  const appendEntry = createAppendEntry(host, agentLoopIndex, entryCache);
+
+  // Hoist the per-event projections out of the loop so N observers
+  // each get the identical event shape + exit code without paying N
+  // copies of the same work.
+  const exitCode = extractExitCode(event);
+  const schemaEvent = toSchemaEvent(event, exitCode);
+
+  // Wrapper-aware command-ref cache (ADR §12). Populated lazily on the
+  // first observer whose watch filter references `inputMatches.command`
+  // against a bash event; reused across subsequent observers on the
+  // same event so `sh -c '…'` / `sudo …` are parsed at most once per
+  // dispatch regardless of how many observers share the filter shape.
+  // `null` encodes "extraction attempted but failed (parse error or
+  // non-bash event)" so we don't retry per observer.
+  let refTextsCache: readonly string[] | null | undefined;
+  const getRefTexts = (): readonly string[] | null => {
+    if (refTextsCache !== undefined) return refTextsCache;
+    refTextsCache = extractRefTextsForBash(schemaEvent);
+    return refTextsCache;
+  };
+
+  for (const observer of observers) {
+    if (!matchesWatch(observer.watch, schemaEvent, getRefTexts)) continue;
+
+    // Each observer gets its own ctx so appendEntry writes attribute
+    // cleanly. `exec` is intentionally absent — observers are recording
+    // hooks, not shell-out points.
+    const observerCtx: ObserverContext = {
+      cwd: ctx.cwd,
+      agentLoopIndex,
+      appendEntry,
+      findEntries,
+    };
+
+    try {
+      const result = observer.onResult(schemaEvent, observerCtx);
+      if (result instanceof Promise) {
+        await result;
+      }
+    } catch (err) {
+      // One observer's bug must not poison the rest. Log with the
+      // observer name so the operator can locate + disable it.
+      console.warn(
+        `[pi-steering] observer "${observer.name}" threw: ${formatError(err)}`,
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Schema event projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract an exit code from a pi tool_result event. Only bash events
+ * carry one (via `details.exitCode`). Other tool results lack a
+ * meaningful numeric code; we return `undefined` and let the watch
+ * filter's `exitCode` check decide.
+ */
+function extractExitCode(event: PiToolResultEvent): number | undefined {
+  if (event.toolName !== "bash") return undefined;
+  const details = event.details as { exitCode?: number } | undefined;
+  if (!details || typeof details.exitCode !== "number") return undefined;
+  return details.exitCode;
+}
+
+/**
+ * Project pi's concrete `ToolResultEvent` onto the schema's minimal
+ * {@link SchemaToolResultEvent}. Observers are typed against the schema
+ * shape — they don't depend on pi's internal tool details unions. The
+ * fields we fill:
+ *
+ *   - `toolName` + `input`   — direct.
+ *   - `output`               — pi's `content` (TextContent/ImageContent
+ *                               array) passed through unchanged. Observer
+ *                               handlers cast to the shape they expect.
+ *   - `exitCode`             — passed in precomputed by the caller
+ *                               (so the extraction runs once per event,
+ *                               not once per matching observer); bash
+ *                               events only, others leave it `undefined`.
+ */
+function toSchemaEvent(
+  event: PiToolResultEvent,
+  exitCode: number | undefined,
+): SchemaToolResultEvent {
+  const out: SchemaToolResultEvent = {
+    toolName: event.toolName,
+    input: event.input,
+    output: event.content,
+  };
+  if (exitCode !== undefined) out.exitCode = exitCode;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Error formatting
+// ---------------------------------------------------------------------------
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) return `${err.message}\n${err.stack ?? ""}`;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+// Re-export host type for symmetry with evaluator.ts.
+export type { EvaluatorHost } from "./evaluator-internals/context.ts";

package/src/per-predicate-typing.test.ts

@@ -0,0 +1,361 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Type-level pinning for the per-predicate typing scaffold introduced
+ * alongside the not-block onUnknown semantics.
+ *
+ * Runtime assertions are minimal — the value of these tests is the
+ * compile-time pinning of the registry-driven mapped types
+ * ({@link TopLevelWhenClause}, {@link TopLevelWhenClauseNoRecurse},
+ * {@link OuterValue}, {@link InnerValue}). If a future change widens
+ * a type incorrectly (e.g. accepting a leaf-level `onUnknown:` inside
+ * `not:`, or adding `not: not:` recursion), the `// @ts-expect-error`
+ * directives here surface the regression at typecheck time.
+ *
+ * Plugin-author registry shape: the `gitPlugin` module augments
+ * `PiSteeringPredicates` with `branch:`, `upstream:`, `remote:`,
+ * `isClean:`, `hasStagedChanges:`, `commitsAhead:` (see
+ * `plugins/git/index.ts`). `cwd:` is a built-in non-registry leaf on
+ * {@link BuiltInWhenLeaves} and is tested via
+ * {@link TopLevelWhenClause} directly. This test file imports
+ * gitPlugin so the augmentation is in scope before the type-level
+ * pins below.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+// Importing gitPlugin pulls in its `declare global { interface
+// PiSteeringPredicates { ... } }` augmentation; without this import
+// the registry would be empty and `PluginPredicateKey` would be
+// `never`, collapsing every mapped type to `{}` with the operator
+// field. The reference below keeps the import live for the
+// type-system without triggering unused-import diagnostics.
+import gitPlugin from "./plugins/git/index.ts";
+import type {
+  CommitsAheadArgs,
+  commitsAhead,
+  hasStagedChanges,
+  isClean,
+} from "./plugins/git/predicates.ts";
+import type {
+  BuiltInWhenLeaves,
+  InnerValue,
+  OuterValue,
+  PluginPredicateKey,
+  PredicateHandler,
+  TopLevelWhenClause,
+  TopLevelWhenClauseNoRecurse,
+} from "./schema.ts";
+
+const _gitPluginRegistered: typeof gitPlugin = gitPlugin;
+void _gitPluginRegistered;
+
+// ---------------------------------------------------------------------------
+// Positive cases — must typecheck
+// ---------------------------------------------------------------------------
+
+describe("per-predicate typing: positive cases", () => {
+  it("registry pins gitPlugin's 6 predicate keys after `declare global`", () => {
+    // Type-level assertion: every gitPlugin predicate key is a
+    // member of `PluginPredicateKey`. A regression that drops one
+    // of the augmented entries surfaces here as a type error.
+    // `cwd` is NOT in this set — it's a built-in non-registry leaf
+    // on BuiltInWhenLeaves (covered by the `BuiltInWhenLeaves`
+    // shape pin in not-block-onunknown.test.ts).
+    const keys: PluginPredicateKey[] = [
+      "branch",
+      "upstream",
+      "remote",
+      "isClean",
+      "hasStagedChanges",
+      "commitsAhead",
+    ];
+    assert.equal(keys.length, 6);
+  });
+
+  it("TopLevelWhenClause: bare leaf forms (Pattern, boolean, number)", () => {
+    const w: TopLevelWhenClause = {
+      cwd: /work/,
+      branch: "main",
+      isClean: true,
+      commitsAhead: 1,
+    };
+    assert.ok(w.cwd !== undefined);
+  });
+
+  it("TopLevelWhenClause: spread leaf forms with leaf-level onUnknown:", () => {
+    const w: TopLevelWhenClause = {
+      cwd: { pattern: /work/, onUnknown: "allow" },
+      isClean: { value: true, onUnknown: "allow" },
+      commitsAhead: { eq: 0, onUnknown: "allow" },
+    };
+    assert.ok(w.cwd !== undefined);
+  });
+
+  it("TopLevelWhenClause: not?: with bare inner leaves + block-level onUnknown:", () => {
+    const w: TopLevelWhenClause = {
+      not: {
+        cwd: /github/,
+        onUnknown: "block",
+      },
+    };
+    assert.ok(w.not?.cwd !== undefined);
+  });
+
+  it("TopLevelWhenClauseNoRecurse: spreadBase form (no modifiers) inside not:", () => {
+    const w: TopLevelWhenClause = {
+      not: {
+        commitsAhead: { lt: 5 },
+        cwd: { pattern: /github/ },
+        onUnknown: "block",
+      },
+    };
+    assert.ok(w.not?.commitsAhead !== undefined);
+  });
+
+  it("OuterValue<K>: bare OR (spreadBase + modifiers) (built-in cwd via BuiltInWhenLeaves)", () => {
+    // `cwd:` is a built-in leaf on {@link BuiltInWhenLeaves}, not a
+    // registry-driven key, so its type pin uses the interface field
+    // directly rather than `OuterValue<"cwd">`. Registry-key version
+    // uses `branch:` (gitPlugin-augmented), with the same
+    // bare-or-spread+modifiers shape contract.
+    const bareCwd: NonNullable<BuiltInWhenLeaves["cwd"]> = /pattern/;
+    const spreadCwd: NonNullable<BuiltInWhenLeaves["cwd"]> = {
+      pattern: /pattern/,
+      onUnknown: "allow",
+    };
+    const bareBranch: OuterValue<"branch"> = /pattern/;
+    const spreadBranch: OuterValue<"branch"> = {
+      pattern: /pattern/,
+      onUnknown: "allow",
+    };
+    assert.ok(bareCwd !== undefined);
+    assert.ok(spreadCwd !== undefined);
+    assert.ok(bareBranch !== undefined);
+    assert.ok(spreadBranch !== undefined);
+  });
+
+  it("InnerValue<K>: bare OR spreadBase (NO modifiers) (built-in cwd inside not: via BuiltInWhenLeaves)", () => {
+    // Inside `not:`, `cwd:` retains its built-in shape (Pattern |
+    // Pattern[] | { pattern, onUnknown? }) —
+    // {@link TopLevelWhenClauseNoRecurse} intersects
+    // {@link BuiltInWhenLeaves} verbatim. Registry-key version uses
+    // `branch:` to pin the bare-or-spreadBase (no modifiers) contract.
+    const bareBranch: InnerValue<"branch"> = /pattern/;
+    const spreadBranch: InnerValue<"branch"> = { pattern: /pattern/ };
+    assert.ok(bareBranch !== undefined);
+    assert.ok(spreadBranch !== undefined);
+  });
+
+  it('InnerValue<"upstream">: bare OR spreadBase (NO modifiers)', () => {
+    // Mirrors the `branch` pin above for the other Pattern-leaf
+    // registry-driven predicates so a future shape regression on
+    // any one of them surfaces independently.
+    const bare: InnerValue<"upstream"> = /origin\/main/;
+    const spread: InnerValue<"upstream"> = { pattern: /origin\/main/ };
+    assert.ok(bare !== undefined);
+    assert.ok(spread !== undefined);
+  });
+
+  it('InnerValue<"remote">: bare OR spreadBase (NO modifiers)', () => {
+    const bare: InnerValue<"remote"> = /github\.com/;
+    const spread: InnerValue<"remote"> = { pattern: /github\.com/ };
+    assert.ok(bare !== undefined);
+    assert.ok(spread !== undefined);
+  });
+
+  it('InnerValue<"hasStagedChanges">: bare boolean OR { value: boolean } (NO modifiers)', () => {
+    const bare: InnerValue<"hasStagedChanges"> = true;
+    const spread: InnerValue<"hasStagedChanges"> = { value: true };
+    assert.ok(bare !== undefined);
+    assert.ok(spread !== undefined);
+  });
+
+  it("upstream: bare + spread + leaf-level onUnknown:", () => {
+    const bare: OuterValue<"upstream"> = /origin\/main/;
+    const spread: OuterValue<"upstream"> = {
+      pattern: /origin\/main/,
+      onUnknown: "allow",
+    };
+    assert.ok(bare !== undefined);
+    assert.ok(spread !== undefined);
+  });
+
+  it("remote: bare + spread + leaf-level onUnknown:", () => {
+    const bare: OuterValue<"remote"> = /github\.com/;
+    const spread: OuterValue<"remote"> = {
+      pattern: /github\.com/,
+      onUnknown: "allow",
+    };
+    assert.ok(bare !== undefined);
+    assert.ok(spread !== undefined);
+  });
+
+  it("hasStagedChanges: bare boolean + spread { value, onUnknown? }", () => {
+    const bare: OuterValue<"hasStagedChanges"> = true;
+    const spread: OuterValue<"hasStagedChanges"> = {
+      value: true,
+      onUnknown: "allow",
+    };
+    assert.ok(bare !== undefined);
+    assert.ok(spread !== undefined);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Negative cases — must NOT typecheck (// @ts-expect-error guards)
+// ---------------------------------------------------------------------------
+
+describe("per-predicate typing: negative cases (compile-time)", () => {
+  it("rule-level onUnknown: is forbidden on TopLevelWhenClause", () => {
+    const w: TopLevelWhenClause = {
+      cwd: /work/,
+      // @ts-expect-error — rule-level onUnknown: is not on TopLevelWhenClause's type.
+      onUnknown: "block",
+    };
+    assert.ok(w.cwd !== undefined);
+  });
+
+  it("leaf-level onUnknown: inside not: is forbidden (modifiers live at block level)", () => {
+    const w: TopLevelWhenClause = {
+      not: {
+        // @ts-expect-error — InnerValue<"branch"> is bare | spreadBase, no modifiers.
+        branch: { pattern: "main", onUnknown: "allow" },
+      },
+    };
+    assert.ok(w.not !== undefined);
+  });
+
+  it("leaf-level onUnknown: inside not: is forbidden for boolean predicates too", () => {
+    const w: TopLevelWhenClause = {
+      not: {
+        // @ts-expect-error — InnerValue<"isClean"> is boolean | { value: boolean }, no modifiers.
+        isClean: { value: true, onUnknown: "allow" },
+      },
+    };
+    assert.ok(w.not !== undefined);
+  });
+
+  it("leaf-level onUnknown: inside not: is forbidden for object-shaped predicates too", () => {
+    const w: TopLevelWhenClause = {
+      not: {
+        // @ts-expect-error — InnerValue<"commitsAhead"> is number | spreadBase, no modifiers.
+        commitsAhead: { lt: 5, onUnknown: "allow" },
+      },
+    };
+    assert.ok(w.not !== undefined);
+  });
+
+  it("not: not: recursion is forbidden", () => {
+    const w: TopLevelWhenClause = {
+      not: {
+        // @ts-expect-error — TopLevelWhenClauseNoRecurse has no `not?:` field.
+        not: { cwd: "/" },
+      },
+    };
+    assert.ok(w.not !== undefined);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// PredicateShape auto-detect via DefaultSpreadBase
+// ---------------------------------------------------------------------------
+
+describe("PredicateShape: DefaultSpreadBase auto-detection", () => {
+  it("PredicateShape<Patterns> auto-detects spreadBase to { pattern: Patterns }", () => {
+    // Type-only assertion via assignability. If the auto-detect
+    // breaks (e.g. tuple-wrap removed and union distributes), this
+    // fails to typecheck. `branch:` carries the same Patterns-bare
+    // shape as the built-in `cwd:` leaf and lives in the registry,
+    // so it's the right registry-side anchor for this pin.
+    type BranchShape = PiSteeringPredicates["branch"];
+    const _spread: BranchShape["spreadBase"] = { pattern: /work/ };
+    void _spread;
+    assert.ok(true);
+  });
+
+  it("PredicateShape<boolean> auto-detects spreadBase to { value: boolean }", () => {
+    type IsCleanShape = PiSteeringPredicates["isClean"];
+    const _spread: IsCleanShape["spreadBase"] = { value: true };
+    void _spread;
+    assert.ok(true);
+  });
+
+  it("PredicateShape<number, ExplicitSpreadBase> uses the explicit override", () => {
+    // commitsAhead has explicit SpreadBase = { eq?, gt?, lt?, wrt? }
+    // (auto-detect from `number` would give { value: number }).
+    type CAShape = PiSteeringPredicates["commitsAhead"];
+    const _spread: CAShape["spreadBase"] = { eq: 1, wrt: "origin/main" };
+    void _spread;
+    assert.ok(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// PluginPredicateKey reserved-key filter
+// ---------------------------------------------------------------------------
+
+describe("PluginPredicateKey: reserved-key filter", () => {
+  it("filters out reserved names (`not`, `onUnknown`)", () => {
+    // Belt-and-suspenders type-only check. The runtime guard in
+    // `plugin-merger.ts` is the authoritative gate (it throws at
+    // config-resolve time when a plugin attempts to register a
+    // reserved key); this assertion pins the type-level filter that
+    // drops reserved names from the registry-driven mapped types
+    // (`TopLevelWhenClause`, `TopLevelWhenClauseNoRecurse`) so an IDE
+    // hover never suggests a key the runtime would reject.
+    type ContainsNot = "not" extends PluginPredicateKey ? true : false;
+    type ContainsOnUnknown = "onUnknown" extends PluginPredicateKey
+      ? true
+      : false;
+    const _a: ContainsNot = false;
+    const _b: ContainsOnUnknown = false;
+    void _a;
+    void _b;
+    assert.ok(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// gitPlugin handler signatures (named exports vs registry shapes)
+// ---------------------------------------------------------------------------
+
+describe("gitPlugin handler signatures: named-export type pins", () => {
+  it("`commitsAhead` is `PredicateHandler<number | CommitsAheadArgs>`", () => {
+    // Pins the named export against the registry shape. If a future
+    // change widens the handler arg (e.g., adding a new union member
+    // without updating the registry's `PredicateShape<number,
+    // CommitsAheadArgs>` SpreadBase), the conditional collapses to
+    // `false` and the assignment fails to typecheck.
+    type _CommitsAheadSig =
+      typeof commitsAhead extends PredicateHandler<number | CommitsAheadArgs>
+        ? true
+        : false;
+    const _checkCommitsAhead: _CommitsAheadSig = true;
+    void _checkCommitsAhead;
+    assert.ok(true);
+  });
+
+  it("`isClean` is `PredicateHandler<boolean | { value: boolean }>`", () => {
+    type _IsCleanSig =
+      typeof isClean extends PredicateHandler<boolean | { value: boolean }>
+        ? true
+        : false;
+    const _checkIsClean: _IsCleanSig = true;
+    void _checkIsClean;
+    assert.ok(true);
+  });
+
+  it("`hasStagedChanges` is `PredicateHandler<boolean | { value: boolean }>`", () => {
+    type _HasStagedSig =
+      typeof hasStagedChanges extends PredicateHandler<
+        boolean | { value: boolean }
+      >
+        ? true
+        : false;
+    const _checkHasStaged: _HasStagedSig = true;
+    void _checkHasStaged;
+    assert.ok(true);
+  });
+});