harnery 0.41.0 → 0.42.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/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,
     );

package/src/core/hooks/cli.ts

@@ -90,6 +90,7 @@ import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/
 import { stableScopeId } from "../workflow/scope-id.ts";
 import { type AdapterBehavior, adapterBehavior } from "./adapter/behaviors/index.ts";
 import { detectAdapter, shouldSkipHookAdapter } from "./adapter/detect.ts";
+import { ADAPTER_SPECS } from "./adapter/events.ts";
 import {
   extractBashCommand,
   extractToolDescription,
@@ -98,6 +99,7 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./adapter/parse.ts";
+import { hookTimeoutFor } from "./adapter/wiring.ts";
 import { scheduleBackupSnapshot } from "./backup-schedule.ts";
 import {
   captureImages,
@@ -131,6 +133,7 @@ import {
   scanStatusBoxPresent,
   scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
+import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
 import { shellWaiterReason } from "./shell-waiter.ts";
 
@@ -140,6 +143,7 @@ interface Argv {
 }
 
 let hookHealthState: HookHealthState | undefined;
+let hookRunMarkerPath: string | null = null;
 
 function parseArgv(argv: string[]): Argv {
   const out: Argv = { eventName: null, extra: [] };
@@ -351,7 +355,12 @@ function buildEventData(
       const forkedFrom: string | undefined = undefined;
       // Assign (or recover) name + kind in-process. Idempotent: resume
       // returns the original name; new owner consumes a counter slot.
-      const assigned = assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
+      // Workflow children stay unnamed, as on the tool path: a pool name
+      // would make them the addressee of mail held for that name.
+      const assigned =
+        coordEnv("WORKFLOW_CHILD") === "1"
+          ? undefined
+          : assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
       // Write the adapter pid-map row so `harn agents whoami` ppid-walks find
       // this owner. Prefer the payload pid (the actual claude binary), then the
       // anchor walk (the `node` ancestor for Cursor, which has no payload pid),
@@ -416,7 +425,10 @@ function buildEventData(
       // SessionStart. Mint durable display identity here so a later
       // SessionStart remains idempotent and Codec is not stuck on the
       // 8-character native id.
-      if (!readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name) {
+      if (
+        coordEnv("WORKFLOW_CHILD") !== "1" &&
+        !readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name
+      ) {
         assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session");
       }
       const prompt = p?.prompt ?? "";
@@ -663,6 +675,24 @@ async function main(): Promise<number> {
   const { eventName, extra } = parseArgv(process.argv.slice(2));
   const adapter = detectAdapter(process.argv.slice(2));
   const behavior = adapter ? adapterBehavior(adapter) : null;
+  // Adapters that kill a hook at its timeout get a start marker, so a killed
+  // run leaves evidence for doctor (ADR 0197). Written before stdin is read.
+  const markerSpec = adapter ? ADAPTER_SPECS[adapter] : undefined;
+  const markerTimeout =
+    markerSpec && eventName && markerSpec.events.some((e) => e.subcommand === eventName)
+      ? hookTimeoutFor(markerSpec, eventName)
+      : undefined;
+  if (markerTimeout !== undefined && adapter && eventName && coordEnv("AGENT_COORD_OFF") !== "1") {
+    const markerRoot = resolveCoordRoot(process.cwd());
+    if (markerRoot) {
+      hookRunMarkerPath = writeHookRunMarker(markerRoot, {
+        event: eventName,
+        adapter,
+        pid: process.pid,
+        timeout_sec: markerTimeout,
+      });
+    }
+  }
   const raw = await readStdin();
   hookHealthState = beginHookHealth({
     started_at_ms: hookStartedAt,
@@ -1189,9 +1219,12 @@ async function handleSessionStarted(run: HookRun): Promise<void> {
   const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import(
     "../storage/maintenance-providers.ts"
   );
-  // Effect: throttled daily sweep of expired artifact workspaces (guarded,
-  // managed-expired only; see autoCleanArtifacts). Best-effort like every
-  // janitor here: a failure logs and never blocks session start.
+  // Effect: throttled hourly artifact sweep (see autoCleanArtifacts). It
+  // deletes expired workspaces, plus unheld workspaces over the per-bundle
+  // ceiling or repository budget once they have been idle past
+  // artifacts.idle_grace_hours. Each deletion is rechecked first and recorded
+  // in .harnery/artifact-deletions.jsonl. Best-effort like every janitor
+  // here: a failure logs and never blocks session start.
   try {
     autoCleanArtifacts(coordRoot);
   } catch (err) {
@@ -1564,7 +1597,8 @@ async function handlePostToolUse(run: HookRun): Promise<void> {
   // status is the wrong place to ask.
   try {
     const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
-    const name = sessionNameDisplayPending(row);
+    // A workflow child has no user-visible title to set.
+    const name = coordEnv("WORKFLOW_CHILD") === "1" ? undefined : sessionNameDisplayPending(row);
     if (name && toolResponseMintedSessionName(payload?.tool_response, name)) {
       // Record the title before asking for it. The suggestion can still
       // change afterwards (an assigned-name rewrite, a lifecycle re-mint, a
@@ -1765,6 +1799,7 @@ async function enforcePendingSessionNameDisplay(
   payload: ParsedPayload | null,
   coordination: Heartbeat | null,
 ): Promise<boolean> {
+  if (coordEnv("WORKFLOW_CHILD") === "1") return true;
   const name = sessionNameDisplayPending(coordination);
   if (!name) return true;
 
@@ -2168,6 +2203,10 @@ async function emitUserPromptSubmitSystemMessage(
   recoveryBriefing = "",
   hostPromptContext = "",
 ): Promise<boolean> {
+  // Workflow children get no prompt-time coordination context, matching
+  // SessionStart. The turn ritual is not enforced for them, the naming nudge
+  // would register them as named peers, and rendering drains peer mail.
+  if (coordEnv("WORKFLOW_CHILD") === "1") return false;
   const behavior = adapterBehavior(adapter);
   const { renderPromptContext } = await import("../agents/render/prompt-context.ts");
   let additionalContext = renderPromptContext({
@@ -2307,6 +2346,7 @@ function completeRecoveryInjection(
 
 main()
   .then(async (code) => {
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
       finished_at_ms: performance.now(),
       finished_rss_bytes: process.memoryUsage().rss,
@@ -2321,6 +2361,7 @@ main()
       pid: process.pid,
       phase: "top-level",
     });
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
       finished_at_ms: performance.now(),
       finished_rss_bytes: process.memoryUsage().rss,