harnery 0.46.0 → 0.47.0

package/src/core/config.ts

@@ -11,7 +11,8 @@
  * `coord` (heartbeat freshness), `logs` (structured-log storage budgets),
  * `artifacts` (working-file retention),
  * `backup` (restic repo/password/prune policy), `sync` (rclone
- * remote/prefix), and `web` (dashboard port) sections. The `files` deny/override section
+ * remote/prefix), `computer` (opt-in desktop control), `autoUpdate` (activity-fired
+ * project self-update), and `web` (dashboard port) sections. The `files` deny/override section
  * is parsed separately by `web/lib/files.ts`.
  *
  * Env vars and CLI flags override any config value per invocation (each accessor
@@ -24,6 +25,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { coordEnv } from "../lib/env.ts";
 import { DEFAULT_WEB_PORT } from "../lib/local-file-url.ts";
+import { AUTOUPDATE_DEFAULTS, type AutoUpdateConfig } from "./autoupdate/types.ts";
 import { resolveEventLedgerRotateActiveBytesV3 } from "./events/v3/rotation-config.ts";
 import {
   type PromptContextConfig,
@@ -82,6 +84,8 @@ interface HarneryConfig {
     promptContext?: unknown;
     /** Project-only opt-in; read via `codexWindowsBridgeConfig()`. */
     codexWindowsBridge?: unknown;
+    /** Project-only opt-in; read via `portableHookCommands()`. */
+    portableCommands?: unknown;
   };
   /**
    * Agent-ritual policy owned by the host project. Git finalization is opt-in:
@@ -220,6 +224,24 @@ interface HarneryConfig {
   sync?: { remote?: string; prefix?: string };
   /** Standalone dashboard defaults. */
   web?: { port?: number; bind?: string };
+  /**
+   * Opt-in desktop control (`computer` command, ADR 0228). Inert unless
+   * `enabled` is true. Project config only; read via `readComputerConfig()`.
+   */
+  computer?: { enabled?: boolean; idle_seconds?: number; wait_seconds?: number };
+  /**
+   * Activity-fired project self-update (ADR 0229). Inert unless `enabled` is
+   * true. Project config only; read via `readAutoUpdateConfig()`.
+   */
+  autoUpdate?: {
+    enabled?: boolean;
+    checkMinutes?: number;
+    steps?: unknown;
+    dailySteps?: unknown;
+    watch?: unknown;
+    timeoutMinutes?: number;
+    cleanup?: boolean;
+  };
   [k: string]: unknown;
 }
 
@@ -545,6 +567,18 @@ export function codexWindowsBridgeConfig(projectRoot: string): CodexWindowsBridg
   return { entryPoint, error: null };
 }
 
+/**
+ * Per-project opt-in that makes `init` write the same adapter hook commands on
+ * every OS: `agent-hook` from PATH, plus a native Codex `commandWindows`. A
+ * project that commits its settings files and is cloned on Windows and POSIX
+ * needs it, because the default form depends on the OS that ran `init`. Read
+ * from the project config only, for the same reason as the Windows bridge.
+ * Anything but `true` keeps the default.
+ */
+export function portableHookCommands(projectRoot: string): boolean {
+  return readProjectConfig(projectRoot).hooks?.portableCommands === true;
+}
+
 export function hostPromptReminder(coordRoot?: string | null): string | null {
   const root = coordRoot ?? findCoordRoot();
   if (!root) return null;
@@ -718,6 +752,113 @@ export function readAdmissionConfig(coordRoot?: string | null): AdmissionProject
   };
 }
 
+/** Effective `computer` settings; unset tunables fall back to the command's defaults. */
+export interface ComputerProjectConfig {
+  enabled: boolean;
+  /** Desktop lease idle expiry in seconds. */
+  idle_seconds?: number;
+  /** How long `computer call` waits for another agent's lease, in seconds. */
+  wait_seconds?: number;
+}
+
+/**
+ * Desktop-control settings from `.harnery/config.jsonc`:
+ *
+ * ```jsonc
+ * "computer": { "enabled": true, "idle_seconds": 120, "wait_seconds": 30 }
+ * ```
+ *
+ * Project config only: enabling desktop control is a per-project decision, so a
+ * user-global value never turns it on. Malformed values are dropped one by one;
+ * `enabled` is true only when the project sets it to exactly `true`.
+ */
+export function readComputerConfig(coordRoot?: string | null): ComputerProjectConfig {
+  const root = coordRoot ?? findCoordRoot();
+  if (!root) return { enabled: false };
+  const raw = readProjectConfig(root).computer;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { enabled: false };
+  const record = raw as Record<string, unknown>;
+  const idle = positiveNumber(record.idle_seconds, 86_400);
+  const wait = record.wait_seconds;
+  const waitOk = typeof wait === "number" && Number.isFinite(wait) && wait >= 0 && wait <= 3600;
+  return {
+    enabled: record.enabled === true,
+    ...(idle !== undefined ? { idle_seconds: idle } : {}),
+    ...(waitOk ? { wait_seconds: wait } : {}),
+  };
+}
+
+// Project-only parse cache keyed by the file's stat signature. Hooks call the
+// auto-update reader on every prompt, so an unchanged file costs one stat.
+let projectCache: { path: string; signature: string; cfg: HarneryConfig } | null = null;
+
+function readProjectConfigCached(root: string): HarneryConfig {
+  const p = join(root, ".harnery", "config.jsonc");
+  const signature = statSignature(p);
+  if (signature === null) return {};
+  if (projectCache && projectCache.path === p && projectCache.signature === signature) {
+    return projectCache.cfg;
+  }
+  const cfg = parseConfigFile(p);
+  projectCache = { path: p, signature, cfg };
+  return cfg;
+}
+
+function clampInteger(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(value)));
+}
+
+/** Keep each argv that is a non-empty array of non-empty strings; drop the rest. */
+function argvList(value: unknown): string[][] {
+  if (!Array.isArray(value)) return [];
+  const out: string[][] = [];
+  for (const entry of value) {
+    if (!Array.isArray(entry) || entry.length === 0) continue;
+    if (!entry.every((part) => typeof part === "string" && part.length > 0)) continue;
+    out.push([...(entry as string[])]);
+  }
+  return out;
+}
+
+/**
+ * Project self-update settings from `.harnery/config.jsonc` (ADR 0229):
+ *
+ * ```jsonc
+ * "autoUpdate": {
+ *   "enabled": true,
+ *   "steps": [["bin/pull-all"]],
+ *   "dailySteps": [["bin/doctor", "--quiet"]],
+ *   "watch": ["~/.local/share/example/hooks.json"],
+ *   "checkMinutes": 15,
+ *   "timeoutMinutes": 20,
+ *   "cleanup": true
+ * }
+ * ```
+ *
+ * Project config only: running commands on activity is a per-project
+ * decision, so a user-global value never turns it on. Null when the project
+ * has no `autoUpdate` section. Malformed values are dropped one by one;
+ * `enabled` is true only when the project sets it to exactly `true`.
+ */
+export function readAutoUpdateConfig(coordRoot: string): AutoUpdateConfig | null {
+  const raw = readProjectConfigCached(coordRoot).autoUpdate;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const record = raw as Record<string, unknown>;
+  const watch = Array.isArray(record.watch)
+    ? record.watch.filter((p): p is string => typeof p === "string" && p.trim().length > 0)
+    : [];
+  return {
+    enabled: record.enabled === true,
+    checkMinutes: clampInteger(record.checkMinutes, 1, 1440, AUTOUPDATE_DEFAULTS.checkMinutes),
+    steps: argvList(record.steps),
+    dailySteps: argvList(record.dailySteps),
+    watch,
+    timeoutMinutes: clampInteger(record.timeoutMinutes, 1, 240, AUTOUPDATE_DEFAULTS.timeoutMinutes),
+    cleanup: record.cleanup !== false,
+  };
+}
+
 /**
  * Whether this repo pins workflow runs to subscription billing:
  * `.harnery/config.jsonc` `{ "workflow": { "subscriptionOnly": true } }`.

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

@@ -568,6 +568,7 @@ function rootOfHarnery(): string {
 
 function repositoryBuild(root: string): string {
   const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], {
+    windowsHide: true,
     encoding: "utf8",
     timeout: 5000,
   });

package/src/core/events/v3/runtime-build.ts

@@ -16,6 +16,7 @@ export function currentHarneryRuntimeBuild(): string {
   const root = harneryPackageRoot();
   if (existsSync(resolve(root, ".git"))) {
     const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], {
+      windowsHide: true,
       encoding: "utf8",
       timeout: 5_000,
     });

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 { codexWindowsBridgeConfig, resolveBinName } from "../../config.ts";
+import { codexWindowsBridgeConfig, portableHookCommands, resolveBinName } from "../../config.ts";
 import {
   ADAPTER_SPECS,
   type AdapterId,
@@ -122,6 +122,22 @@ export function hookCommandWindows(
 export interface WiringOptions {
   /** Bridge entry point from `hooks.codexWindowsBridge`, or null when not opted in. */
   windowsBridgeEntryPoint?: string | null;
+  /**
+   * `hooks.portableCommands`: write the same `agent-hook` commands from PATH on
+   * every OS, plus a native Codex `commandWindows`, so one committed settings
+   * file is current everywhere.
+   */
+  portableCommands?: boolean;
+  /** The OS to write for. Defaults to the host; tests inject it. */
+  platform?: NodeJS.Platform;
+}
+
+/** The wiring options a project's committed config selects. */
+export function projectWiringOptions(projectRoot: string): WiringOptions {
+  return {
+    windowsBridgeEntryPoint: codexWindowsBridgeConfig(projectRoot).entryPoint,
+    portableCommands: portableHookCommands(projectRoot),
+  };
 }
 
 /** The `commandWindows` init writes for one event, or undefined for none. */
@@ -132,7 +148,12 @@ export function expectedCommandWindows(
   adapter: AdapterId,
   options?: WiringOptions,
 ): string | undefined {
-  if (!spec.windowsBridgeHooks || !options?.windowsBridgeEntryPoint) return undefined;
+  if (!spec.windowsBridgeHooks) return undefined;
+  if (!options?.windowsBridgeEntryPoint) {
+    return (options?.platform ?? process.platform) === "win32" || options?.portableCommands
+      ? nativeHookCommand(agentHookPath, subcommand, adapter)
+      : undefined;
+  }
   return hookCommandWindows(
     spec,
     agentHookPath,
@@ -193,7 +214,11 @@ export function hookCommand(
   agentHookPath: string,
   subcommand: string,
   adapter: AdapterId,
+  options?: WiringOptions,
 ): string {
+  if ((options?.platform ?? process.platform) === "win32") {
+    return nativeHookCommand(agentHookPath, subcommand, adapter);
+  }
   if (agentHookPath === "agent-hook") {
     return `agent-hook ${subcommand} --adapter ${adapter}`;
   }
@@ -201,13 +226,29 @@ export function hookCommand(
   return `bash ${anchor}${agentHookPath} ${subcommand} --adapter ${adapter}`;
 }
 
+function nativeHookCommand(agentHookPath: string, subcommand: string, adapter: AdapterId): string {
+  if (agentHookPath === "agent-hook") return `agent-hook ${subcommand} --adapter ${adapter}`;
+  const runner = join(dirname(agentHookPath), "run.mjs").replaceAll("\\", "/");
+  return `node "${runner}" agent-hook ${subcommand} --adapter ${adapter}`;
+}
+
 /**
  * Pick a committed hook target that survives cloning the consumer elsewhere.
  * Projects that contain Harnery can use its repo-relative launcher. Standalone
  * consumers use the package's installed `agent-hook` executable from PATH
  * instead of recording a relative path back into one developer's package tree.
  */
-export function agentHookPathForProject(projectRoot: string, packageRoot: string): string {
+export function agentHookPathForProject(
+  projectRoot: string,
+  packageRoot: string,
+  options?: WiringOptions,
+): string {
+  // Native npm shims run the linked source checkout without Bash, and do not
+  // depend on a hook's working directory after an agent changes directories.
+  // A project that commits one settings file for every OS asks for the same.
+  if ((options?.platform ?? process.platform) === "win32" || options?.portableCommands) {
+    return "agent-hook";
+  }
   const hook = join(packageRoot, "bin", "agent-hook");
   const candidate = relative(projectRoot, hook);
   if (candidate === ".." || candidate.startsWith(`..${sep}`) || isAbsolute(candidate)) {
@@ -268,6 +309,7 @@ export function diffWiring(
         expected.agentHookPath,
         event.subcommand,
         expected.adapter,
+        expected,
       );
       const timeout = hookTimeoutFor(spec, event.subcommand);
       const commandWindows = expectedCommandWindows(
@@ -386,7 +428,9 @@ function pluginDrift(
   const packageRoot = harneryPackageRoot();
   const check = checkOpenCodePlugin(projectRoot, {
     binName: resolveBinName(projectRoot),
-    agentHook: packageRoot ? agentHookPathForProject(projectRoot, packageRoot) : "agent-hook",
+    agentHook: packageRoot
+      ? agentHookPathForProject(projectRoot, packageRoot, projectWiringOptions(projectRoot))
+      : "agent-hook",
   });
   if (check.status === "fresh") return null;
   if (check.status === "missing") return null;
@@ -425,14 +469,15 @@ export function loadAdapterWiring(projectRoot: string): AdapterWiringStatus[] {
       continue;
     }
     const packageRoot = harneryPackageRoot();
+    const options = projectWiringOptions(projectRoot);
     const diff = diffWiring(
       settings,
       spec,
       packageRoot
         ? {
-            agentHookPath: agentHookPathForProject(projectRoot, packageRoot),
+            agentHookPath: agentHookPathForProject(projectRoot, packageRoot, options),
             adapter: id,
-            windowsBridgeEntryPoint: codexWindowsBridgeConfig(projectRoot).entryPoint,
+            ...options,
           }
         : undefined,
     );

package/src/core/hooks/autoupdate-cue.ts

@@ -0,0 +1,72 @@
+import { coordEnv } from "../../lib/env.ts";
+import type { AutoUpdateNotice, TickResult } from "../autoupdate/types.ts";
+import { readAutoUpdateConfig } from "../config.ts";
+
+/** Prefix on every self-update line injected into an agent's context. */
+export const AUTOUPDATE_CUE_PREFIX = "Auto-update: ";
+
+export interface AutoUpdateCueDeps {
+  tick: (coordRoot: string) => TickResult;
+  pendingNotices: (coordRoot: string, sessionKey: string) => AutoUpdateNotice[];
+}
+
+export interface AutoUpdateCueOptions {
+  /**
+   * Whether this hook will show context to the agent. When false, the tick
+   * still runs but notices stay queued for a session that can read them.
+   */
+  deliver?: boolean;
+  /** Test seam; production loads the engine lazily. */
+  deps?: AutoUpdateCueDeps;
+  /** Receives tick or delivery failures. The cue itself never throws. */
+  onError?: (err: unknown, phase: "autoupdate-tick" | "autoupdate-notices") => void;
+}
+
+async function loadDeps(): Promise<AutoUpdateCueDeps> {
+  const engine = await import("../autoupdate/index.ts");
+  return {
+    tick: (root) => engine.autoUpdateTick(root),
+    pendingNotices: (root, key) => engine.pendingNotices(root, key),
+  };
+}
+
+/**
+ * Fire the activity-driven self-update check (ADR 0229) and collect the
+ * notices this session has not seen yet, one context line each.
+ *
+ * Projects without an `autoUpdate` section pay one config stat and never load
+ * the engine. With the section, the tick's hot path is one stamp stat; any
+ * real work runs in a detached child, so the hook never waits on it. Fails
+ * open: an error is reported through `onError` and the cue is empty.
+ */
+export async function autoUpdateHookContext(
+  coordRoot: string,
+  sessionKey: string,
+  options: AutoUpdateCueOptions = {},
+): Promise<string> {
+  if (coordEnv("AUTOUPDATE_CHILD") === "1") return "";
+  let deps: AutoUpdateCueDeps;
+  try {
+    if (!readAutoUpdateConfig(coordRoot)) return "";
+    deps = options.deps ?? (await loadDeps());
+  } catch (err) {
+    options.onError?.(err, "autoupdate-tick");
+    return "";
+  }
+  try {
+    deps.tick(coordRoot);
+  } catch (err) {
+    options.onError?.(err, "autoupdate-tick");
+  }
+  if (options.deliver === false || !sessionKey) return "";
+  try {
+    return deps
+      .pendingNotices(coordRoot, sessionKey)
+      .map((notice) => `${AUTOUPDATE_CUE_PREFIX}${notice.text.trim()}`)
+      .filter((line) => line.length > AUTOUPDATE_CUE_PREFIX.length)
+      .join("\n");
+  } catch (err) {
+    options.onError?.(err, "autoupdate-notices");
+    return "";
+  }
+}

package/src/core/hooks/cli.ts

@@ -108,6 +108,7 @@ import {
   parsePayload,
 } from "./adapter/parse.ts";
 import { hookTimeoutFor } from "./adapter/wiring.ts";
+import { autoUpdateHookContext } from "./autoupdate-cue.ts";
 import { scheduleBackupSnapshot } from "./backup-schedule.ts";
 import {
   captureImages,
@@ -139,6 +140,7 @@ import type { SessionNameDisplayInspection } from "./resolve/transcript.ts";
 import {
   inspectSessionNameDisplayImmediately,
   scanAssistantStatusBoxPresent,
+  scanPendingBackgroundHandoffs,
   scanStatusBoxPresent,
   scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
@@ -1315,6 +1317,13 @@ async function handleSessionStarted(run: HookRun): Promise<void> {
   } catch (err) {
     logError(coordRoot, err, { phase: "backup-schedule" });
   }
+  // Project self-update (ADR 0229) fires on activity. The tick costs one stat
+  // when fresh and otherwise launches a detached child; queued notices for
+  // this session ride the same context as the backup cue.
+  const autoUpdateCue = await autoUpdateHookContext(coordRoot, owner.instance_id, {
+    deliver: coordEnv("WORKFLOW_CHILD") !== "1",
+    onError: (err, phase) => logError(coordRoot, err, { phase }),
+  });
   // Storage maintenance can walk large stores. It runs in a detached worker so
   // session start emits its context without waiting for it; an adapter that
   // stops a slow hook would otherwise drop that context entirely.
@@ -1343,7 +1352,7 @@ async function handleSessionStarted(run: HookRun): Promise<void> {
       data,
       adapter,
       recovery?.briefing ?? "",
-      backupCue,
+      [backupCue, autoUpdateCue].filter(Boolean).join("\n\n"),
     );
     if (injected && recovery) {
       completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
@@ -1472,6 +1481,11 @@ async function handleTurnStarted(run: HookRun): Promise<void> {
       logError(coordRoot, err, { phase: "prompt-context-user-prompt" });
     }
   }
+  // Project self-update (ADR 0229): see handleSessionStarted.
+  const autoUpdateCue = await autoUpdateHookContext(coordRoot, owner.instance_id, {
+    deliver: coordEnv("WORKFLOW_CHILD") !== "1",
+    onError: (err, phase) => logError(coordRoot, err, { phase }),
+  });
   try {
     const injected = await emitUserPromptSubmitSystemMessage(
       coordRoot,
@@ -1481,6 +1495,7 @@ async function handleTurnStarted(run: HookRun): Promise<void> {
       payload?.cwd,
       recovery?.briefing ?? "",
       hostPromptContext,
+      autoUpdateCue,
     );
     if (injected && recovery) {
       completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
@@ -1506,6 +1521,18 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
     logError(coordRoot, err, { phase: "stop-presence" });
   }
 
+  // Claude Code may move a running foreground command (often the agent's own
+  // commit and push) into the background to deliver a user message. Until it
+  // reports back, finalization cannot pass, so the verdict defers the status
+  // demands instead of bouncing the agent in a loop.
+  const pendingBackgroundHandoffs =
+    adapter === "claude-code"
+      ? scanPendingBackgroundHandoffs(
+          payload?.transcript_path ??
+            behavior.discoverTranscript?.(payload?.session_id ?? sessionId),
+        )
+      : [];
+
   // Stop verdict (V3 ritual + task/status gate). Direct in-process call: the
   // rule lives in Harnery. agent-hook already emitted this turn.completed
   // with privacy-safe ritual observations, so the evidence is in the stream.
@@ -1519,8 +1546,24 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
     session_name_observation_unavailable: typeof data.session_name_unavailable_reason === "string",
     bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
     workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
+    pending_background_handoff: pendingBackgroundHandoffs.length > 0,
   });
+  if (verdict.rule === "stop-hook.background_handoff_deferred") {
+    appendDebug(coordRoot, {
+      ...debugBase,
+      effect: "stop-deferred-background-handoff",
+      background_task_ids: pendingBackgroundHandoffs,
+    });
+  }
   if (!verdict.allow) {
+    // Re-arm the prompt-time ritual reminder; it is otherwise shown only on a
+    // session's first prompt so the per-prompt context stays small.
+    try {
+      const { markTurnRitualBounced } = await import("../agents/render/prompt-context.ts");
+      markTurnRitualBounced(coordRoot, owner.instance_id);
+    } catch (err) {
+      logError(coordRoot, err, { phase: "stop-ritual-rearm" });
+    }
     // Backstop for sessions whose evidence can never land (e.g. a headless
     // child whose status command resolves to a different owner): after
     // `cap` consecutive blocked stops in one cycle, allow the stop instead
@@ -1553,6 +1596,12 @@ async function handleStop(run: HookRun): Promise<number | undefined> {
   // until the adapter has committed turn.completed above. Reconcile only
   // when such a request exists; any later real work cancels it in the
   // finalizer instead of being terminated underneath the agent.
+  // A deferred stop proves nothing about finalization; an explicit end must
+  // wait for the turn that reports the background task's result.
+  if (verdict.rule === "stop-hook.background_handoff_deferred") {
+    if (behavior.runtimeContextRetry) scheduleRuntimeContextRetry(coordRoot, adapter, sessionId);
+    return undefined;
+  }
   try {
     const { hasPendingExplicitSessionEndV3, reconcileSessionFinalizationV3 } = await import(
       "../agents/session-finalizer-v3.ts"
@@ -2408,6 +2457,7 @@ async function emitUserPromptSubmitSystemMessage(
   workspaceCwd?: string,
   recoveryBriefing = "",
   hostPromptContext = "",
+  autoUpdateCue = "",
 ): Promise<boolean> {
   // Workflow children get no prompt-time coordination context, matching
   // SessionStart. The turn ritual is not enforced for them, the naming nudge
@@ -2436,6 +2486,9 @@ async function emitUserPromptSubmitSystemMessage(
   if (hostPromptContext) {
     additionalContext = [additionalContext, hostPromptContext].filter(Boolean).join("\n\n");
   }
+  if (autoUpdateCue) {
+    additionalContext = [additionalContext, autoUpdateCue].filter(Boolean).join("\n\n");
+  }
   if (!additionalContext) return false;
 
   const { emitContext } = await import("./adapter/output.ts");

package/src/core/hooks/effects/index.ts

@@ -17,7 +17,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import { applyDetection } from "../../../lib/presence.ts";
-import { coordBinPath } from "../../agents/coord-bin.ts";
+import { coordBinPath, spawnCoordBinSync } from "../../agents/coord-bin.ts";
 
 export { captureImages, imageJanitor, recordImageArtifactsV3 } from "./image-capture.ts";
 
@@ -70,7 +70,7 @@ export function journalJanitor(repoRoot: string): void {
   try {
     const bin = harnBin(repoRoot);
     if (!bin) return;
-    spawnSync("bash", [bin, "journal", "janitor", "--quiet"], {
+    spawnCoordBinSync(bin, ["journal", "janitor", "--quiet"], {
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       timeout: 5000,
       stdio: "ignore",
@@ -89,7 +89,7 @@ export function journalRecoveryCue(repoRoot: string): string {
   try {
     const bin = harnBin(repoRoot);
     if (!bin) return "";
-    const r = spawnSync("bash", [bin, "journal", "recovery-cue"], {
+    const r = spawnCoordBinSync(bin, ["journal", "recovery-cue"], {
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       timeout: 5000,
       encoding: "utf8",
@@ -105,7 +105,7 @@ export function journalArchive(repoRoot: string, owner: string): void {
   try {
     const bin = harnBin(repoRoot);
     if (!bin || !owner) return;
-    spawnSync("bash", [bin, "journal", "archive", "--owner", owner], {
+    spawnCoordBinSync(bin, ["journal", "archive", "--owner", owner], {
       env: { ...process.env, HARNERY_OUTPUT_SESSION_TEE: "0" },
       timeout: 5000,
       stdio: "ignore",

package/src/core/hooks/resolve/coord-root.ts

@@ -91,6 +91,7 @@ function gitRevParse(start: string, flag: string): string | null {
     // A stale adapter project directory may no longer exist. Treat spawn
     // failure as no path evidence instead of turning discovery into an error.
     const result = spawnSync("git", ["rev-parse", flag], {
+      windowsHide: true,
       cwd: start,
       encoding: "utf8",
     });

package/src/core/hooks/resolve/transcript.ts

@@ -94,6 +94,67 @@ export function scanAssistantStatusBoxPresent(
   );
 }
 
+/** A handoff older than this no longer defers Stop, so a lost notification cannot disable the ritual. */
+export const BACKGROUND_HANDOFF_MAX_AGE_MS = 30 * 60 * 1000;
+
+/**
+ * Claude Code interleaves request-capture rows of several hundred KB each, so
+ * the 256KB status-box window can lose a handoff written a minute earlier.
+ */
+const BACKGROUND_HANDOFF_TAIL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Claude Code background tasks it moved off the foreground on its own (to
+ * deliver a mid-command user message) that have not yet posted a
+ * `<task-notification>`. Only the structured `toolUseResult` fields written by
+ * Claude Code open a handoff; the agent cannot forge them through tool output.
+ * Any later notification text naming the task closes it, so a spoofed
+ * notification can only make Stop stricter. A command the agent chose to
+ * background (`run_in_background`) or a Monitor opens nothing.
+ */
+export function scanPendingBackgroundHandoffs(
+  transcriptPath: string | undefined,
+  nowMs: number = Date.now(),
+): string[] {
+  const readablePath = resolveTranscriptPath(transcriptPath);
+  if (!readablePath) return [];
+  let size: number;
+  try {
+    size = statSync(readablePath).size;
+  } catch {
+    return [];
+  }
+  const text = readRange(readablePath, Math.max(0, size - BACKGROUND_HANDOFF_TAIL_BYTES), size);
+  if (!text) return [];
+  const opened = new Map<string, number>();
+  for (const line of text.split("\n")) {
+    // Request-capture rows echo the same text; the row-type check below keeps
+    // only Claude Code's own top-level tool-result rows.
+    if (line.includes("backgroundedToDeliverMessage")) {
+      const row = parseTranscriptRow(line);
+      const result = row?.toolUseResult as
+        | { backgroundTaskId?: unknown; backgroundedToDeliverMessage?: unknown }
+        | undefined;
+      if (
+        row?.type === "user" &&
+        result?.backgroundedToDeliverMessage === true &&
+        typeof result.backgroundTaskId === "string" &&
+        result.backgroundTaskId
+      ) {
+        opened.set(result.backgroundTaskId, Date.parse(String(row.timestamp)));
+      }
+    }
+    if (line.includes("task-notification")) {
+      for (const match of line.matchAll(/<task-id>([^<]+)<\/task-id>/g)) {
+        opened.delete(match[1]!);
+      }
+    }
+  }
+  return [...opened]
+    .filter(([, at]) => Number.isFinite(at) && nowMs - at <= BACKGROUND_HANDOFF_MAX_AGE_MS)
+    .map(([id]) => id);
+}
+
 /** Most recent user-visible assistant text across Claude Code and Codex JSONL. */
 export function scanLatestAssistantText(transcriptPath: string | undefined): string | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);

package/src/core/semantic/service.ts

@@ -17,6 +17,7 @@ import {
 } from "node:fs";
 import { hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { coordEnv } from "../../lib/env.ts";
 import {
   type ReadLedgerV3SinceResult,
@@ -150,7 +151,9 @@ export async function spawnSemanticService(
   const sharedLogs = coordEnv("SHARED_LOGS") !== "0";
   const logFd = sharedLogs ? undefined : openSync(paths.log, "a", stateFileMode());
   if (logFd !== undefined) chmodSync(paths.log, stateFileMode());
-  const harnBin = new URL("../../../bin/harn", import.meta.url).pathname;
+  const harnBin = fileURLToPath(
+    new URL(import.meta.url.endsWith(".ts") ? "../../cli.ts" : "../../cli.js", import.meta.url),
+  );
   if (!existsSync(harnBin)) {
     if (logFd !== undefined) closeSync(logFd);
     throw new Error(`cannot find harn executable at ${harnBin}`);
@@ -160,7 +163,8 @@ export async function spawnSemanticService(
     args.push("--calls-per-hour", String(options.callsPerHour));
   }
   let spawnError: Error | undefined;
-  const child = spawn(harnBin, args, {
+  const child = spawn(process.execPath, [harnBin, ...args], {
+    windowsHide: true,
     cwd: coordRoot,
     detached: true,
     stdio: logFd === undefined ? ["ignore", "ignore", "ignore"] : ["ignore", logFd, logFd],