harnery 0.41.0 → 0.43.0

package/src/core/config.ts

@@ -80,6 +80,8 @@ interface HarneryConfig {
   /** Optional host prompt-context extension. Project config only. */
   hooks?: {
     promptContext?: unknown;
+    /** Project-only opt-in; read via `codexWindowsBridgeConfig()`. */
+    codexWindowsBridge?: unknown;
   };
   /**
    * Agent-ritual policy owned by the host project. Git finalization is opt-in:
@@ -107,7 +109,7 @@ interface HarneryConfig {
    * `workflow run` in this repo to subscription billing (API-key vars are
    * scrubbed from child envs) without anyone having to remember the flag.
    */
-  workflow?: { subscriptionOnly?: boolean };
+  workflow?: { subscriptionOnly?: boolean; workerFullAccess?: unknown };
   /**
    * Cross-machine presence (ADR 0016). `{ enabled: false }` opts a repo out of
    * the git-refs transport (publishing `refs/harnery/presence/<machine>` to
@@ -166,11 +168,22 @@ interface HarneryConfig {
    * Managed working-artifact defaults. `default_retention_days` is the
    * create-time TTL when the caller does not pass `artifacts create --days`.
    */
+  /** Local server registry (`servers` command, `harnery/core/servers`). */
+  servers?: {
+    /** Inclusive port range per server type, e.g. `"preview": [3100, 3199]`. */
+    port_ranges?: Record<string, unknown>;
+    idle_hours?: number;
+    owner_stale_hours?: number;
+  };
   artifacts?: {
     default_retention_days?: number;
     auto_clean?: boolean;
     max_bytes?: number;
     max_unit_bytes?: number;
+    idle_grace_hours?: number;
+    hold_days?: number;
+    max_held_bytes?: number;
+    min_free_bytes?: number;
   };
   /**
    * Page review packs. `auto_clean` lets `qa-run` and `review-pack create`
@@ -494,6 +507,42 @@ export function resolveHooksSetupHint(coordRoot?: string | null): string | null
  * values fail closed to no reminder so a malformed optional setting cannot
  * break the prompt hook.
  */
+/** A plain Windows command name, so it is safe to splice into a PowerShell hook command. */
+const CODEX_WINDOWS_BRIDGE_ENTRY_POINT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+export interface CodexWindowsBridgeConfig {
+  /** Command name Windows-native Codex hooks hand off to, or null when not opted in. */
+  entryPoint: string | null;
+  /** Why the configured value was ignored, when it was. */
+  error: string | null;
+}
+
+/**
+ * Per-project opt-in that routes Windows-native Codex hooks through a resident
+ * WSL bridge (ADR 0197). Read from the project config only: the value is
+ * written into the committed `.codex/hooks.json`, so a user-level setting
+ * would make `init` output differ between machines. An invalid value is
+ * ignored and reported rather than spliced into a shell command.
+ */
+export function codexWindowsBridgeConfig(projectRoot: string): CodexWindowsBridgeConfig {
+  const raw = readProjectConfig(projectRoot).hooks?.codexWindowsBridge;
+  if (raw === undefined) return { entryPoint: null, error: null };
+  const entryPoint = isPlainObject(raw) ? raw.entryPoint : undefined;
+  if (typeof entryPoint !== "string") {
+    return {
+      entryPoint: null,
+      error: "hooks.codexWindowsBridge.entryPoint must be a command name",
+    };
+  }
+  if (!CODEX_WINDOWS_BRIDGE_ENTRY_POINT.test(entryPoint)) {
+    return {
+      entryPoint: null,
+      error: `hooks.codexWindowsBridge.entryPoint ${JSON.stringify(entryPoint)} is not a plain command name`,
+    };
+  }
+  return { entryPoint, error: null };
+}
+
 export function hostPromptReminder(coordRoot?: string | null): string | null {
   const root = coordRoot ?? findCoordRoot();
   if (!root) return null;
@@ -601,6 +650,27 @@ export function workflowSubscriptionOnly(coordRoot?: string | null): boolean {
   return readConfig(root).workflow?.subscriptionOnly === true;
 }
 
+/**
+ * The host's raw worker full-access policy (ADR 0192), validated by
+ * `parseWorkerFullAccessPolicy` in the workflow layer, which knows each
+ * adapter's effort scale.
+ *
+ * `.harnery/config.jsonc`:
+ * `{ "workflow": { "workerFullAccess": { "enabled": true, "floors": { ... } } } }`
+ *
+ * This is a trust boundary, so it comes only from the project config, like
+ * `agents.finalizationRoots`: a user-global file cannot remove the sandbox from
+ * one project's workers. `HARNERY_WORKFLOW_WORKER_FULL_ACCESS=0` turns it off
+ * for one process. There is deliberately no `=1`: an environment variable can
+ * withdraw the grant but never supply it.
+ */
+export function workflowWorkerFullAccessConfig(coordRoot?: string | null): unknown {
+  if (coordEnv("WORKFLOW_WORKER_FULL_ACCESS") === "0") return { enabled: false };
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return undefined;
+  return readProjectConfig(root).workflow?.workerFullAccess;
+}
+
 /**
  * How this project's `.harnery/` state is shared: `private` or `group`. `HARNERY_STORAGE_SHARING`
  * overrides per process; an unrecognized value falls back to `private`, the safer reading.
@@ -765,6 +835,46 @@ export function resolveWebPort(explicitPort?: string, coordRoot?: string | null)
   return DEFAULT_WEB_PORT;
 }
 
+/** The configured inclusive port range for one server type, or null. */
+export function serverPortRange(type: string, coordRoot?: string | null): [number, number] | null {
+  const root = coordRoot ?? findCoordRoot();
+  const value = root ? readConfig(root).servers?.port_ranges?.[type] : undefined;
+  if (!Array.isArray(value) || value.length !== 2) return null;
+  const [low, high] = value as unknown[];
+  const valid = (n: unknown): n is number =>
+    Number.isInteger(n) && (n as number) > 0 && (n as number) < 65536;
+  return valid(low) && valid(high) && low <= high ? [low, high] : null;
+}
+
+/** Every configured server port range, keyed by type (invalid entries dropped). */
+export function serverPortRanges(coordRoot?: string | null): Record<string, [number, number]> {
+  const root = coordRoot ?? findCoordRoot();
+  const ranges = root ? readConfig(root).servers?.port_ranges : undefined;
+  const out: Record<string, [number, number]> = {};
+  for (const type of Object.keys(ranges ?? {})) {
+    const range = serverPortRange(type, root);
+    if (range) out[type] = range;
+  }
+  return out;
+}
+
+/** Configured `servers gc` windows; undefined fields use the built-in defaults. */
+export function serverGcConfig(coordRoot?: string | null): {
+  idle_hours?: number;
+  owner_stale_hours?: number;
+} {
+  const root = coordRoot ?? findCoordRoot();
+  const configured = root ? readConfig(root).servers : undefined;
+  const positive = (n: unknown): n is number =>
+    typeof n === "number" && Number.isFinite(n) && n > 0;
+  return {
+    ...(positive(configured?.idle_hours) ? { idle_hours: configured.idle_hours } : {}),
+    ...(positive(configured?.owner_stale_hours)
+      ? { owner_stale_hours: configured.owner_stale_hours }
+      : {}),
+  };
+}
+
 /** Policy for converging independent termination signals on one finalizer. */
 export function sessionFinalizationConfig(coordRoot?: string | null): SessionFinalizationConfig {
   const root = coordRoot ?? findCoordRoot();
@@ -843,12 +953,81 @@ export function artifactMaxUnitBytes(coordRoot?: string | null): number {
   );
 }
 
+/**
+ * How long an unexpired workspace must sit idle before a size rule (the
+ * per-bundle ceiling or the repository budget) may delete it. Idle means no
+ * change inside the workspace and no heartbeat from its owner. An agent waiting
+ * on a human reply looks idle, so a short window deletes work someone is still
+ * reviewing. Precedence: `HARNERY_ARTIFACT_IDLE_GRACE_HOURS` ->
+ * `artifacts.idle_grace_hours` -> 24. Expiry never waits for this grace.
+ */
+export function artifactIdleGraceHours(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_IDLE_GRACE_HOURS"),
+    root ? readConfig(root).artifacts?.idle_grace_hours : undefined,
+    1,
+    24 * 365,
+    24,
+  );
+}
+
+/**
+ * Default lifetime of an artifact hold. A hold that is not renewed lapses after
+ * this many days and the workspace returns to ordinary retention. Precedence:
+ * `HARNERY_ARTIFACT_HOLD_DAYS` -> `artifacts.hold_days` -> 14.
+ */
+export function artifactHoldDays(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_HOLD_DAYS"),
+    root ? readConfig(root).artifacts?.hold_days : undefined,
+    1,
+    365,
+    14,
+  );
+}
+
+/**
+ * Advisory budget for held artifact bytes. Exceeding it produces warnings
+ * only: holds record owner intent, so cleanup never deletes held work.
+ * Precedence: `HARNERY_ARTIFACT_MAX_HELD_BYTES` -> `artifacts.max_held_bytes`
+ * -> 20 GiB.
+ */
+export function artifactMaxHeldBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_MAX_HELD_BYTES"),
+    root ? readConfig(root).artifacts?.max_held_bytes : undefined,
+    64 * 1024 * 1024,
+    1024 * 1024 * 1024 * 1024,
+    DEFAULT_ARTIFACT_MAX_BYTES,
+  );
+}
+
+/**
+ * Free-disk floor for the artifact store. Below it, artifact commands warn and
+ * `artifacts create --big` refuses unless `--allow-low-disk` is passed.
+ * Precedence: `HARNERY_ARTIFACT_MIN_FREE_BYTES` -> `artifacts.min_free_bytes`
+ * -> 20 GiB. Zero disables the floor.
+ */
+export function artifactMinFreeBytes(coordRoot?: string | null): number {
+  const root = coordRoot ?? findCoordRoot();
+  return integerSetting(
+    coordEnv("ARTIFACT_MIN_FREE_BYTES"),
+    root ? readConfig(root).artifacts?.min_free_bytes : undefined,
+    0,
+    1024 * 1024 * 1024 * 1024 * 1024,
+    20 * 1024 * 1024 * 1024,
+  );
+}
+
 /**
  * Whether opportunistic cleanup of expired artifact workspaces runs.
  * Precedence: `HARNERY_ARTIFACT_AUTO_CLEAN` (0/false disables) ->
- * `artifacts.auto_clean` -> enabled. The sweep only ever deletes
- * `managed-expired` entries via the same guarded classifier as
- * `artifacts clean --yes`.
+ * `artifacts.auto_clean` -> enabled. The sweep deletes the same
+ * `managed-expired`, `managed-oversize`, and `managed-over-budget` entries as
+ * `artifacts clean --yes`, through the same guarded classifier.
  */
 export function artifactAutoCleanEnabled(coordRoot?: string | null): boolean {
   const env = coordEnv("ARTIFACT_AUTO_CLEAN");

package/src/core/diagnostics/bundle.ts

@@ -15,6 +15,7 @@ import type {
 } from "../artifacts/index.ts";
 import {
   ARTIFACT_MANIFEST,
+  artifactHoldState,
   artifactsRoot,
   configuredArtifactRetentionDays,
   createArtifact,
@@ -412,7 +413,7 @@ function candidateArtifactId(artifactPath: string): string | undefined {
 function candidateClassification(
   manifest: ArtifactManifestV2,
 ): ArtifactInventoryEntry["classification"] {
-  if (manifest.holds.length > 0) return "managed-held";
+  if (artifactHoldState(manifest).active.length > 0) return "managed-held";
   if (!manifest.released_at) return "managed-active";
   return Date.parse(manifest.retention.expires_at) <= Date.now()
     ? "managed-expired"

package/src/core/events/v3/producers/recorder.ts

@@ -1130,6 +1130,22 @@ function processHookSignalLocked(
     if (input.signal === "sub-agent-start") {
       if (!sourceId) return { state: "ignored" };
       delegation = state.delegations.find((candidate) => candidate.source_id === sourceId);
+      if (delegation?.open_event_id) {
+        // SendMessage to a running background agent re-fires SubagentStart.
+        // The delegation is already open; a second agent.started is noise.
+        writeProducerDiagnosticV3(input.coordRoot, "duplicate_subagent_start_suppressed", {
+          adapter: input.adapter,
+          signal: input.signal,
+          reason: "delegation_already_open",
+          instance_id: input.instance_id,
+          session_hash: sessionHash,
+          generation_id: state.generation_id,
+          delegation_id: delegation.delegation_id,
+          payload: input.payload,
+        });
+        publishProducerState(input.coordRoot, path, state);
+        return { state: "ignored" };
+      }
       if (!delegation) {
         const opened = openSpanStateV3({
           span_id: spanIdV3(),

package/src/core/events/v3/projection.ts

@@ -539,7 +539,17 @@ function applyAgentStarted(
   projection: SafetyProjectionV3,
   event: Extract<EventV3, { event_type: "agent.started" }>,
 ): void {
-  if (projection.delegations[event.payload.delegation_id]) {
+  const existing = projection.delegations[event.payload.delegation_id];
+  if (existing) {
+    // Claude Code re-fires SubagentStart when SendMessage resumes a background
+    // agent. A restart naming the same parent and child is that resume, not a
+    // conflicting delegation, and must not strip the parent's authority.
+    if (
+      existing.parent_generation_id === generationIdOf(event) &&
+      existing.child_generation_id === event.payload.child_generation_id
+    ) {
+      return;
+    }
     addDiagnostic(projection, {
       code: "delegation_duplicate_start",
       event_id: event.event_id,

package/src/core/events/v3/support-storage/pack-reader.ts

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
-import { constants, createReadStream } from "node:fs";
+import { constants } from "node:fs";
 import { lstat, mkdir, open, realpath, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { finished } from "node:stream/promises";
 import { StringDecoder } from "node:string_decoder";
 import { createGunzip, createInflateRaw } from "node:zlib";
 import { stateDirMode, stateFileMode } from "../../../storage/modes.ts";
@@ -89,24 +91,17 @@ async function* streamEventV3SupportPackRecordsForManifest(
       throw new Error("event_v3_support_payload_length_mismatch");
     if (payloadStat.size > bounded.max_payload_bytes)
       throw new Error("event_v3_support_payload_too_large");
-    if ((await hashHandle(payloadPath, payloadHandle)) !== manifest.payload.digest) {
+    if ((await hashHandle(payloadHandle)) !== manifest.payload.digest) {
       throw new Error("event_v3_support_payload_digest_mismatch");
     }
     limits.fault?.("after_payload_digest", payloadPath);
     await assertCanonicalSingleGzipMember(
-      payloadPath,
       payloadHandle,
       payloadStat.size,
       bounded.max_decompressed_bytes,
     );
 
     const gunzip = createGunzip();
-    const source = createReadStream(payloadPath, {
-      fd: payloadHandle.fd,
-      autoClose: false,
-      start: 0,
-    });
-    source.pipe(gunzip);
     const decoder = new StringDecoder("utf8");
     let pending = "";
     let decompressedBytes = 0;
@@ -116,7 +111,7 @@ async function* streamEventV3SupportPackRecordsForManifest(
     const entries: EventV3LogicalAuthorityEntry[] = [];
     const seen = new Set<string>();
 
-    for await (const current of gunzip) {
+    for await (const current of decompressHandle(payloadHandle, 0, gunzip)) {
       const chunk = current as Buffer;
       decompressedBytes += chunk.length;
       if (decompressedBytes > bounded.max_decompressed_bytes) {
@@ -247,16 +242,49 @@ export async function unpackEventV3SupportPack(
   }
 }
 
-async function hashHandle(
-  path: string,
-  handle: Awaited<ReturnType<typeof open>>,
-): Promise<`sha256:${string}`> {
+async function hashHandle(handle: Awaited<ReturnType<typeof open>>): Promise<`sha256:${string}`> {
   const hash = createHash("sha256");
-  const stream = createReadStream(path, { fd: handle.fd, autoClose: false, start: 0 });
-  for await (const current of stream) hash.update(current as Buffer);
+  for await (const current of handleChunks(handle, 0)) hash.update(current);
   return `sha256:${hash.digest("hex")}`;
 }
 
+async function* handleChunks(handle: Awaited<ReturnType<typeof open>>, position: number) {
+  while (true) {
+    const buffer = Buffer.alloc(64 * 1024);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+    if (bytesRead === 0) return;
+    position += bytesRead;
+    yield buffer.subarray(0, bytesRead);
+  }
+}
+
+async function* decompressHandle(
+  handle: Awaited<ReturnType<typeof open>>,
+  start: number,
+  decoder: ReturnType<typeof createGunzip>,
+): AsyncGenerator<Buffer> {
+  const source = Readable.from(handleChunks(handle, start));
+  // Observe failures immediately, then settle source reads before the caller
+  // can close and reuse the verified handle, including on early rejection.
+  const completed = finished(source, { cleanup: true }).then(
+    () => undefined,
+    (error: unknown) => error,
+  );
+  source.once("error", (error) => decoder.destroy(error));
+  source.pipe(decoder);
+  try {
+    for await (const chunk of decoder) yield chunk as Buffer;
+    source.unpipe(decoder);
+    source.resume();
+    const error = await completed;
+    if (error) throw error;
+  } finally {
+    source.destroy();
+    decoder.destroy();
+    await completed;
+  }
+}
+
 async function realDirectory(path: string): Promise<string> {
   const stat = await lstat(path);
   if (!stat.isDirectory() || stat.isSymbolicLink())
@@ -265,7 +293,6 @@ async function realDirectory(path: string): Promise<string> {
 }
 
 async function assertCanonicalSingleGzipMember(
-  path: string,
   handle: Awaited<ReturnType<typeof open>>,
   payloadBytes: number,
   maximumDecompressedBytes: number,
@@ -284,9 +311,8 @@ async function assertCanonicalSingleGzipMember(
     throw new Error("event_v3_support_gzip_header_noncanonical");
   }
   const inflate = createInflateRaw();
-  createReadStream(path, { fd: handle.fd, autoClose: false, start: 10 }).pipe(inflate);
   let decompressed = 0;
-  for await (const current of inflate) {
+  for await (const current of decompressHandle(handle, 10, inflate)) {
     decompressed += (current as Buffer).length;
     if (decompressed > maximumDecompressedBytes) {
       inflate.destroy();

package/src/core/hooks/adapter/events.ts

@@ -69,6 +69,20 @@ export interface AdapterSpec {
    * wandered (the session shell `cd`ing into a subdirectory or off-repo).
    */
   projectDirEnv?: string;
+  /**
+   * Per-handler `timeout` (seconds) written on every Harnery hook entry. Without
+   * one, an adapter's own default applies (Codex: 600 seconds), so a stalled
+   * hook can hold a tool call for ten minutes. `bySubcommand` overrides
+   * `default` for one event.
+   */
+  hookTimeouts?: { default: number; bySubcommand?: Record<string, number> };
+  /**
+   * The adapter runs a handler's `commandWindows` instead of `command` on
+   * Windows. A project that opts in (`hooks.codexWindowsBridge`) gets one that
+   * hands the hook to a resident WSL bridge (ADR 0197); otherwise init leaves
+   * the field off.
+   */
+  windowsBridgeHooks?: boolean;
 }
 
 /** Claude Code: `.claude/settings.json`. */
@@ -191,6 +205,11 @@ export const ADAPTER_SPECS: Record<AdapterId, AdapterSpec> = {
     legacyEvents: LEGACY_CODEX_EVENTS,
     allowedTopLevelKeys: ["description", "hooks"],
     allowedEventKeys: CODEX_ALLOWED_EVENT_KEYS,
+    // A Codex hook that times out fails open: the run is marked failed and
+    // the tool proceeds. Codex clamps SessionEnd to 3 seconds and defaults it
+    // to 1, which is too short for a cold hook start.
+    hookTimeouts: { default: 20, bySubcommand: { "session-end": 3 } },
+    windowsBridgeHooks: true,
   },
   opencode: {
     settingsFile: ".opencode/plugins/harnery/index.ts",

package/src/core/hooks/adapter/runtime-telemetry.ts

@@ -671,7 +671,9 @@ function claudeModelContextCapability(model: string): ClaudeModelContextCapabili
   const normalized = model.toLowerCase();
   const oneMillionTokenModels = new Set([
     "claude-fable-5",
+    "claude-opus-5-5",
     "claude-opus-5",
+    "claude-sonnet-5-5",
     "claude-sonnet-5",
     "claude-opus-4-8",
     "claude-opus-4-7",
@@ -679,7 +681,7 @@ function claudeModelContextCapability(model: string): ClaudeModelContextCapabili
     "claude-sonnet-4-6",
   ]);
   if (oneMillionTokenModels.has(normalized)) {
-    return { limit_tokens: 1_000_000, authority: "anthropic_model_capabilities_2026_08" };
+    return { limit_tokens: 1_000_000, authority: "anthropic_model_capabilities_2026_09" };
   }
   if (normalized === "claude-haiku-4-5" || normalized === "claude-haiku-4-5-20251001") {
     return { limit_tokens: 200_000, authority: "anthropic_model_capabilities_2026_08" };

package/src/core/hooks/adapter/wiring.ts

@@ -14,7 +14,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveBinName } from "../../config.ts";
+import { codexWindowsBridgeConfig, resolveBinName } from "../../config.ts";
 import {
   ADAPTER_SPECS,
   type AdapterId,
@@ -24,10 +24,19 @@ import {
 } from "./events.ts";
 import { checkOpenCodePlugin, isOwnedOpenCodePlugin } from "./opencode-plugin.ts";
 
-/** Claude Code + Codex entry: `{ hooks: [{ type, command }] }`. */
+/** One Claude Code or Codex command handler. */
+export interface ClaudeHookHandler {
+  type: string;
+  command: string;
+  /** Codex: run instead of `command` on Windows. */
+  commandWindows?: string;
+  timeout?: number;
+}
+
+/** Claude Code + Codex entry: `{ hooks: [{ type, command, commandWindows?, timeout? }] }`. */
 export interface ClaudeHookGroup {
   matcher?: string;
-  hooks: { type: string; command: string }[];
+  hooks: ClaudeHookHandler[];
 }
 /** Cursor entry: a flat `{ command }`. */
 export interface CursorHookGroup {
@@ -53,14 +62,92 @@ export interface SettingsFile {
 export function makeEntry(
   shape: HookEntryShape,
   command: string,
-  extras?: { loop_limit?: number },
+  extras?: { loop_limit?: number; timeout?: number; commandWindows?: string },
 ): HookGroup {
-  if (shape !== "cursor") return { hooks: [{ type: "command", command }] };
+  if (shape !== "cursor") {
+    return {
+      hooks: [
+        orderHandlerKeys({
+          type: "command",
+          command,
+          commandWindows: extras?.commandWindows,
+          timeout: extras?.timeout,
+        }),
+      ],
+    };
+  }
   return extras?.loop_limit !== undefined
     ? { command, loop_limit: extras.loop_limit }
     : { command };
 }
 
+/**
+ * Rebuild a handler with Harnery's fields first in a fixed order, dropping
+ * undefined ones and keeping any other fields after them.
+ */
+export function orderHandlerKeys(handler: ClaudeHookHandler): ClaudeHookHandler {
+  const { type, command, commandWindows, timeout, ...rest } = handler;
+  return {
+    type,
+    command,
+    ...(commandWindows !== undefined ? { commandWindows } : {}),
+    ...(timeout !== undefined ? { timeout } : {}),
+    ...rest,
+  };
+}
+
+/**
+ * The Windows command for an opted-in project (ADR 0197). It hands the hook to
+ * the bridge entry point when that is on PATH and the working directory is a
+ * WSL UNC path, and otherwise runs the usual command. `ProviderPath` drops the
+ * provider prefix that `Path` carries. The trailing `exit $LASTEXITCODE` is
+ * required: without it PowerShell reports any non-zero exit from inside the
+ * `if` block as 1, which would turn a hook's blocking exit 2 into a failure.
+ */
+export function hookCommandWindows(
+  spec: AdapterSpec,
+  agentHookPath: string,
+  subcommand: string,
+  adapter: AdapterId,
+  entryPoint: string,
+): string {
+  const direct = hookCommand(spec, agentHookPath, subcommand, adapter);
+  return (
+    `if ((Get-Command ${entryPoint} -ErrorAction Ignore) -and $PWD.ProviderPath -like '\\\\wsl*') ` +
+    `{ ${entryPoint} ${subcommand} --adapter ${adapter} } else { ${direct} }; exit $LASTEXITCODE`
+  );
+}
+
+/** Project-level choices that change what init writes. */
+export interface WiringOptions {
+  /** Bridge entry point from `hooks.codexWindowsBridge`, or null when not opted in. */
+  windowsBridgeEntryPoint?: string | null;
+}
+
+/** The `commandWindows` init writes for one event, or undefined for none. */
+export function expectedCommandWindows(
+  spec: AdapterSpec,
+  agentHookPath: string,
+  subcommand: string,
+  adapter: AdapterId,
+  options?: WiringOptions,
+): string | undefined {
+  if (!spec.windowsBridgeHooks || !options?.windowsBridgeEntryPoint) return undefined;
+  return hookCommandWindows(
+    spec,
+    agentHookPath,
+    subcommand,
+    adapter,
+    options.windowsBridgeEntryPoint,
+  );
+}
+
+/** The `timeout` init writes on one event's Harnery hook, or undefined for none. */
+export function hookTimeoutFor(spec: AdapterSpec, subcommand: string): number | undefined {
+  if (!spec.hookTimeouts) return undefined;
+  return spec.hookTimeouts.bySubcommand?.[subcommand] ?? spec.hookTimeouts.default;
+}
+
 /** Pin Cursor Stop followups to Harnery's loop cap. Returns true when the entry changed. */
 export function applyCursorStopLoopLimit(group: HookGroup, subcommand: string): boolean {
   if (subcommand !== "stop") return false;
@@ -144,7 +231,7 @@ export interface WiringDiff {
   duplicates: HookEvent[];
   /** Spec events wired under an event key other than the canonical one. */
   misplaced: HookEvent[];
-  /** Spec events whose correct-key command differs from init's canonical command. */
+  /** Spec events whose correct-key command, `commandWindows`, or `timeout` differs from what init writes. */
   stale: HookEvent[];
   /** Settings fields rejected by a adapter with a strict top-level schema. */
   invalidTopLevelKeys: string[];
@@ -159,7 +246,7 @@ export interface WiringDiff {
 export function diffWiring(
   settings: SettingsFile,
   spec: AdapterSpec,
-  expected?: { agentHookPath: string; adapter: AdapterId },
+  expected?: { agentHookPath: string; adapter: AdapterId } & WiringOptions,
 ): WiringDiff {
   const missing: HookEvent[] = [];
   const present: HookEvent[] = [];
@@ -182,7 +269,27 @@ export function diffWiring(
         event.subcommand,
         expected.adapter,
       );
-      if (commands.some((command) => command !== canonical)) stale.push(event);
+      const timeout = hookTimeoutFor(spec, event.subcommand);
+      const commandWindows = expectedCommandWindows(
+        spec,
+        expected.agentHookPath,
+        event.subcommand,
+        expected.adapter,
+        expected,
+      );
+      const handlerDrift = groups.some(
+        (group) =>
+          "hooks" in group &&
+          Array.isArray(group.hooks) &&
+          group.hooks.some(
+            (hook) =>
+              typeof hook.command === "string" &&
+              commandWiresSubcommand(hook.command, event.subcommand) &&
+              ((timeout !== undefined && hook.timeout !== timeout) ||
+                (spec.windowsBridgeHooks === true && hook.commandWindows !== commandWindows)),
+          ),
+      );
+      if (handlerDrift || commands.some((command) => command !== canonical)) stale.push(event);
     }
     const wrongKey = Object.entries(hooks).some(
       ([key, otherGroups]) =>
@@ -325,6 +432,7 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
         ? {
             agentHookPath: agentHookPathForProject(projectRoot, packageRoot),
             adapter: id,
+            windowsBridgeEntryPoint: codexWindowsBridgeConfig(projectRoot).entryPoint,
           }
         : undefined,
     );