harnery 0.31.5 → 0.32.0

package/src/core/hooks/codex-wsl-bridge.ts

@@ -0,0 +1,188 @@
+export interface CodexWslBridgeStatus {
+  ok: boolean;
+  detail: string;
+  threadIdPresent: boolean;
+  wslenvForwardsThreadId: boolean;
+}
+
+export interface CodexWslBridgeOptions {
+  /** The caller already knows this is a Codex adapter process. */
+  expected?: boolean;
+}
+
+export interface CodexWslWorkspaceLinkMapping {
+  /** Absolute path seen by Linux-side tools. */
+  linuxRoot: string;
+  /** Forward-slash UNC path that Codex Desktop can use as a Markdown destination. */
+  hostRoot: string;
+  distro: string;
+}
+
+export interface CodexWslFileLinkTelemetry {
+  /** Markdown destinations that still use the Linux root in a Windows-hosted WSL task. */
+  wsl_linux_file_link_count: number;
+  /** Bounded examples for local diagnosis; omitted when the count is zero. */
+  wsl_linux_file_link_examples?: string[];
+}
+
+/** Whether an adapter-reported workspace is a Linux path exposed through WSL UNC. */
+export function isWslUncPath(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  return (
+    /^\\\\(?:wsl\.localhost|wsl\$)\\/i.test(value) ||
+    /^\\\\\?\\unc\\(?:wsl\.localhost|wsl\$)\\/i.test(value)
+  );
+}
+
+interface ParsedWslUncPath {
+  host: string;
+  distro: string;
+  linuxPath: string;
+}
+
+function parseWslUncPath(value: unknown): ParsedWslUncPath | null {
+  if (typeof value !== "string") return null;
+  const ordinary = value.replace(/^\\\\\?\\UNC\\/i, "\\\\");
+  const match = ordinary.match(/^\\\\(wsl\.localhost|wsl\$)\\([^\\]+)(?:\\(.*))?$/i);
+  if (!match) return null;
+  const host = match[1]!;
+  const distro = match[2]!;
+  const tail = (match[3] ?? "").split("\\").filter(Boolean).join("/");
+  return { host, distro, linuxPath: tail ? `/${tail}` : "/" };
+}
+
+function trimTrailingSlash(path: string): string {
+  return path === "/" ? path : path.replace(/\/+$/, "");
+}
+
+function isWithinOrEqual(path: string, root: string): boolean {
+  return path === root || path.startsWith(`${root}/`);
+}
+
+/**
+ * Derive the Linux-to-host path pair from the actual adapter workspace. The
+ * roots must overlap so an unrelated WSL UNC path cannot authorize a mapping
+ * for some other checkout.
+ */
+export function codexWslWorkspaceLinkMapping(
+  coordRootRaw: string,
+  workspaceCwd: unknown,
+): CodexWslWorkspaceLinkMapping | null {
+  const parsed = parseWslUncPath(workspaceCwd);
+  const linuxRoot = trimTrailingSlash(coordRootRaw.replace(/\\/g, "/"));
+  if (!parsed || !linuxRoot.startsWith("/")) return null;
+  const linuxCwd = trimTrailingSlash(parsed.linuxPath);
+  if (!isWithinOrEqual(linuxCwd, linuxRoot) && !isWithinOrEqual(linuxRoot, linuxCwd)) {
+    return null;
+  }
+  return {
+    linuxRoot,
+    hostRoot: `//${parsed.host}/${parsed.distro}${linuxRoot}`,
+    distro: parsed.distro,
+  };
+}
+
+/** Fresh adapter context for the model. Shell paths stay Linux-native; only
+ * Markdown destinations use the host-visible root. */
+export function renderCodexWslFileLinkContext(coordRoot: string, workspaceCwd: unknown): string {
+  const mapping = codexWslWorkspaceLinkMapping(coordRoot, workspaceCwd);
+  if (!mapping) return "";
+  return (
+    "Codex WSL file links: this task is hosted by Windows while tools run inside WSL. " +
+    `For clickable local-file Markdown links, replace the Linux workspace root \`${mapping.linuxRoot}\` with the host-visible root \`${mapping.hostRoot}\`. ` +
+    `Example: \`[label](<${mapping.hostRoot}/path/to/file>)\`. ` +
+    "Keep Linux paths unchanged in shell commands and tool inputs."
+  );
+}
+
+function withoutMarkdownCode(text: string): string {
+  const output: string[] = [];
+  let fence: { marker: string; length: number } | null = null;
+  for (const line of text.split(/\r?\n/)) {
+    const candidate = line.match(/^\s{0,3}(`{3,}|~{3,})/);
+    if (fence) {
+      if (candidate && candidate[1]![0] === fence.marker && candidate[1]!.length >= fence.length) {
+        fence = null;
+      }
+      output.push("");
+      continue;
+    }
+    if (candidate) {
+      fence = { marker: candidate[1]![0]!, length: candidate[1]!.length };
+      output.push("");
+      continue;
+    }
+    output.push(line.replace(/(`+)([^`\n]*?)\1/g, ""));
+  }
+  return output.join("\n");
+}
+
+function markdownDestinations(text: string): string[] {
+  const out: string[] = [];
+  const visible = withoutMarkdownCode(text);
+  const re = /!?\[[^\]\n]*\]\(\s*(?:<([^>\n]+)>|([^\s)\n]+))/g;
+  for (const match of visible.matchAll(re)) {
+    const target = match[1] ?? match[2];
+    if (target) out.push(target);
+  }
+  return out;
+}
+
+/**
+ * Count Markdown links that point at the Linux workspace root even though the
+ * adapter workspace is Windows-visible UNC. This is telemetry only: the Stop
+ * hook must not replace or retry an otherwise complete Codex reply.
+ */
+export function codexWslFileLinkTelemetry(
+  coordRoot: string,
+  workspaceCwd: unknown,
+  assistantMessage: string,
+): CodexWslFileLinkTelemetry | null {
+  const mapping = codexWslWorkspaceLinkMapping(coordRoot, workspaceCwd);
+  if (!mapping) return null;
+  const mismatches = markdownDestinations(assistantMessage).filter((target) =>
+    isWithinOrEqual(target, mapping.linuxRoot),
+  );
+  return {
+    wsl_linux_file_link_count: mismatches.length,
+    ...(mismatches.length > 0
+      ? { wsl_linux_file_link_examples: mismatches.slice(0, 3).map((path) => path.slice(0, 240)) }
+      : {}),
+  };
+}
+
+function wslenvForwards(wslenv: string | undefined, variable: string): boolean {
+  if (!wslenv) return false;
+  return wslenv.split(":").some((entry) => entry.split("/", 1)[0] === variable);
+}
+
+/**
+ * Inspect the environment contract used when Windows-native Codex launches a
+ * Harnery hook or shell inside WSL. Returns null outside that hybrid mode.
+ */
+export function inspectCodexWslBridge(
+  env: NodeJS.ProcessEnv = process.env,
+  options: CodexWslBridgeOptions = {},
+): CodexWslBridgeStatus | null {
+  const inWsl = Boolean(env.WSL_DISTRO_NAME?.trim() || env.WSL_INTEROP?.trim());
+  if (!inWsl) return null;
+
+  const threadIdPresent = Boolean(env.CODEX_THREAD_ID?.trim());
+  const wslenvForwardsThreadId = wslenvForwards(env.WSLENV, "CODEX_THREAD_ID");
+  if (!options.expected && !threadIdPresent && !wslenvForwardsThreadId) return null;
+
+  const problems: string[] = [];
+  if (!threadIdPresent) problems.push("CODEX_THREAD_ID did not reach WSL");
+  if (!wslenvForwardsThreadId) problems.push("WSLENV does not forward CODEX_THREAD_ID");
+
+  const distro = env.WSL_DISTRO_NAME?.trim();
+  return {
+    ok: problems.length === 0,
+    detail:
+      problems.length === 0
+        ? `thread identity forwarded through WSLENV${distro ? ` (${distro})` : ""}`
+        : problems.join("; "),
+    threadIdPresent,
+    wslenvForwardsThreadId,
+  };
+}

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

@@ -120,7 +120,7 @@ export function journalArchive(repoRoot: string, owner: string): void {
  * Fire the optional host session-sync extension on turn stop / session end.
  * harnery core has no session-telemetry sink of its own; a host that wants one
  * drops an executable at
- * `scripts/hooks/adapter/claude_code/extensions/session-sync.sh` under the coord
+ * `scripts/hooks/harness/claude-code/extensions/session-sync.sh` under the coord
  * root, and core runs it detached + unref'd so a slow sink never blocks the
  * hook. `force` arrives as argv $1 ("1" on session end, "0" on turn stop) so the
  * host can rate-limit the stop path and force-flush on end. No-op when the
@@ -134,8 +134,8 @@ export function runSessionSyncExtension(repoRoot: string, force: boolean): void
       repoRoot,
       "scripts",
       "hooks",
-      "adapter",
-      "claude_code",
+      "harness",
+      "claude-code",
       "extensions",
       "session-sync.sh",
     );
@@ -169,8 +169,8 @@ export function runTurnSummary(
       repoRoot,
       "scripts",
       "hooks",
-      "adapter",
-      "claude_code",
+      "harness",
+      "claude-code",
       "extensions",
       "turn-summary.sh",
     );

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

@@ -99,6 +99,24 @@ export type TurnStop = EventEnvelope<
     tool_call_count: number;
     text_length: number;
     status_box_present: boolean; // adapter sets via transcript scan for `┌─ agent-` prefix
+    /** Strict variant of status_box_present: assistant text blocks only, so a
+     * tool_result carrying the box (the status command's own output) does not
+     * count. Shadow telemetry while the rule-2/3 detector decision is open;
+     * the Stop verdict does not read it yet. */
+    status_box_present_strict?: boolean;
+    /** Whether the session's suggested name is satisfied as of this turn:
+     * either this reply showed it, or an earlier reply did. Present whenever a
+     * suggested name exists, since the Stop verdict reads it per turn. */
+    session_name_present?: boolean;
+    /** Which suggested name `session_name_present` refers to. A projector
+     * rebuild attributes the sighting to this name instead of to whichever
+     * name is current during the replay. */
+    session_name_present_for?: string;
+    /** Shadow telemetry for Windows-hosted Codex workspaces: Markdown link
+     * destinations that still use the Linux coordination root. */
+    wsl_linux_file_link_count?: number;
+    /** Up to three bounded examples for diagnosing the mismatches locally. */
+    wsl_linux_file_link_examples?: string[];
   }
 >;
 
@@ -258,6 +276,10 @@ export type ClaimAcquire = EventEnvelope<
   {
     path: string;
     mode: "read" | "write";
+    finalization?: {
+      disposition: "git" | "output";
+      root: string;
+    };
   }
 >;
 
@@ -284,6 +306,11 @@ export type StateTaskSet = EventEnvelope<
   {
     task: string;
     cleared: boolean;
+    /** True exactly when this call produced the session name (first non-empty
+     * declaration of a human-facing session); never true with a null name. */
+    first_of_session?: boolean;
+    /** The name produced by this call, for the Stop-hook naming rule. */
+    suggested_session_name?: string | null;
   }
 >;
 

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

@@ -17,6 +17,12 @@ import { checkPidToken } from "../../agents/state/proc-start.ts";
  *      events; session_id is the parent-shape default.
  *   3. PID-map lookup at `.harnery/pid-map/<pid>` for our own pid, then ppid
  *      chain (up to 20 hops).
+ *   4. `CODEX_THREAD_ID` env var, accepted only when a live heartbeat by that
+ *      id exists under `.harnery/active/`. Codex sessions use their thread id
+ *      as the heartbeat instance_id, and a Windows→WSL bridge forwards the
+ *      var into process trees that descend from no registered process — the
+ *      one place the pid walk can never land. Validated so a garbage value
+ *      cannot fabricate an identity.
  *
  * Returns null when nothing resolves. Callers must treat null as "no owner"
  * and skip the event (Phase 2 fail-safe; Phase 3 will mint a temporary owner
@@ -25,7 +31,10 @@ import { checkPidToken } from "../../agents/state/proc-start.ts";
 export function resolveOwner(opts: {
   payload: Record<string, unknown> | null;
   coordRoot: string;
-}): { instance_id: string; source: "env" | "payload" | "pidmap-self" | "pidmap-ancestor" } | null {
+}): {
+  instance_id: string;
+  source: "env" | "payload" | "pidmap-self" | "pidmap-ancestor" | "codex-env";
+} | null {
   const env = coordEnv("AGENT_COORD_OWNER");
   if (env && env.length > 0) {
     return { instance_id: env, source: "env" };
@@ -76,6 +85,18 @@ export function resolveOwner(opts: {
     }
   }
 
+  // Tier 4: Codex thread id, heartbeat-validated. Last because the pid map is
+  // more specific when it answers — an inherited env var can outlive the
+  // process tree it described, a live pid-map row cannot.
+  const codexThreadId = process.env.CODEX_THREAD_ID?.trim();
+  if (
+    codexThreadId &&
+    /^[A-Za-z0-9-]+$/.test(codexThreadId) &&
+    existsSync(join(opts.coordRoot, ".harnery", "active", `${codexThreadId}.json`))
+  ) {
+    return { instance_id: codexThreadId, source: "codex-env" };
+  }
+
   return null;
 }
 

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

@@ -1,4 +1,5 @@
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 
 /**
  * Scan a CC-style JSONL transcript for the `┌─ agent-` status-box prefix in
@@ -20,6 +21,56 @@ export function scanStatusBoxPresent(transcriptPath: string | undefined): boolea
   return text.includes("┌─ agent-");
 }
 
+/**
+ * Scan a CC-style JSONL transcript for a needle in ASSISTANT message text
+ * blocks only. Used by `turn.stop` to detect the suggested session name in the
+ * reply.
+ *
+ * The row filter is load-bearing: the transcript tail also carries the needle
+ * inside `tool_result` rows (the `agents set-task` JSON output) and hook
+ * context rows, so a raw `includes()` over the tail — the way the status-box
+ * scan works — would false-pass the moment set-task runs. Verified empirically
+ * 2026-08-09 against a live transcript.
+ *
+ * Same 256KB tail window as the other scans; the window's first line may be a
+ * truncated JSON row, which the per-line parse guard skips.
+ */
+export function scanAssistantTextIncludes(
+  transcriptPath: string | undefined,
+  needle: string,
+): boolean {
+  if (!transcriptPath || !needle || !existsSync(transcriptPath)) return false;
+  const text = tailText(transcriptPath);
+  if (!text) return false;
+  for (const line of text.split("\n")) {
+    // Cheap gate before parsing: most lines don't contain the needle at all.
+    if (!line.includes(needle)) continue;
+    try {
+      const row = JSON.parse(line) as {
+        type?: unknown;
+        message?: { content?: unknown };
+      };
+      if (row.type !== "assistant") continue;
+      const content = row.message?.content;
+      if (typeof content === "string") {
+        if (content.includes(needle)) return true;
+        continue;
+      }
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (typeof block !== "object" || block === null) continue;
+        const b = block as { type?: unknown; text?: unknown };
+        if (b.type === "text" && typeof b.text === "string" && b.text.includes(needle)) {
+          return true;
+        }
+      }
+    } catch {
+      // Truncated/partial line (tail-window start or flush race); skip it.
+    }
+  }
+  return false;
+}
+
 /**
  * Resolve the agent's model from a CC-style JSONL transcript by reading the
  * most-recent assistant message's `message.model`. Claude Code's SessionStart
@@ -56,6 +107,118 @@ export function scanTranscriptModel(transcriptPath: string | undefined): string
   return undefined;
 }
 
+const SESSION_FILE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i;
+/** Skip absurdly large transcripts rather than buffering them. */
+const FORK_SCAN_MAX_BYTES = 128 * 1024 * 1024;
+/** How many message uuids to sample across the fork's copied prefix. */
+const FORK_SAMPLE_SIZE = 24;
+
+/**
+ * Detect the parent session of a forked CC conversation from its transcript.
+ *
+ * Empirical basis (verified 2026-08-05 against `claude --resume <id>
+ * --fork-session`): the fork copies the parent's rows into a new
+ * `<new-session-id>.jsonl`, rewriting every row's `sessionId` to the new id
+ * but PRESERVING each copied message row's `uuid`. So a sibling transcript in
+ * the same project directory that contains the fork's message uuids is an
+ * ancestor of the fork.
+ *
+ * Ancestor vs. parent: a grandparent (when the parent was itself a fork)
+ * shares the fork's early uuids too, but only the true parent contains the
+ * whole copied prefix. At detection time the fork's transcript is almost
+ * entirely copied prefix, so uuids sampled across the whole file separate the
+ * two: score candidates by containment, highest wins.
+ *
+ * Sibling forks force a second rule: a PRIOR fork of the same parent also
+ * contains the whole copied prefix, so it ties the true parent on score. The
+ * sibling additionally carries its own post-fork turns, which the parent
+ * lacks, so among tied scores the MINIMAL container (fewest message rows)
+ * wins. A wrong pick under this rule stays within the ancestry (grandparent
+ * at worst); a recency tie-break can name a non-ancestor sibling (observed
+ * 2026-08-05 with two probes forked off one parent).
+ *
+ * Fail-soft by design: any read error, an unflushed transcript, or no
+ * qualifying sibling returns undefined, which downgrades the caller to the
+ * no-lineage behavior. Never throws.
+ */
+export function detectForkParent(
+  transcriptPath: string | undefined,
+  sessionId: string,
+): string | undefined {
+  try {
+    if (!transcriptPath || !sessionId || !existsSync(transcriptPath)) return undefined;
+    if (statSync(transcriptPath).size > FORK_SCAN_MAX_BYTES) return undefined;
+    const own = readFileSync(transcriptPath, "utf8");
+    const uuids = messageUuids(own);
+    if (uuids.length === 0) return undefined;
+    const sample = sampleEvenly(uuids, FORK_SAMPLE_SIZE);
+
+    const dir = dirname(transcriptPath);
+    const ownFile = basename(transcriptPath);
+    let best: { id: string; score: number; rows: number; mtimeMs: number } | null = null;
+    for (const file of readdirSync(dir)) {
+      if (file === ownFile || !SESSION_FILE_RE.test(file)) continue;
+      const candidateId = file.slice(0, -".jsonl".length);
+      if (candidateId === sessionId) continue;
+      const path = join(dir, file);
+      let stat: ReturnType<typeof statSync>;
+      try {
+        stat = statSync(path);
+      } catch {
+        continue;
+      }
+      if (stat.size > FORK_SCAN_MAX_BYTES) continue;
+      let text: string;
+      try {
+        text = readFileSync(path, "utf8");
+      } catch {
+        continue;
+      }
+      // Cheap gate before scoring: an ancestor must contain the fork's first
+      // copied message uuid (the copy always starts at the beginning).
+      if (!text.includes(sample[0]!)) continue;
+      let score = 0;
+      for (const u of sample) if (text.includes(u)) score++;
+      if (score < Math.max(1, Math.ceil(sample.length / 2))) continue;
+      const rows = messageUuids(text).length;
+      const wins =
+        !best ||
+        score > best.score ||
+        (score === best.score &&
+          (rows < best.rows || (rows === best.rows && stat.mtimeMs < best.mtimeMs)));
+      if (wins) best = { id: candidateId, score, rows, mtimeMs: stat.mtimeMs };
+    }
+    return best?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Message-row uuids (user/assistant rows only), in file order. */
+function messageUuids(text: string): string[] {
+  const out: string[] = [];
+  for (const line of text.split("\n")) {
+    if (!line.includes('"uuid"')) continue;
+    try {
+      const row = JSON.parse(line) as { type?: unknown; uuid?: unknown };
+      if (row.type !== "user" && row.type !== "assistant") continue;
+      if (typeof row.uuid === "string" && row.uuid.length > 0) out.push(row.uuid);
+    } catch {
+      // Truncated/partial line (flush race); skip it.
+    }
+  }
+  return out;
+}
+
+/** Up to <n> items spread evenly across the list, always including the first. */
+function sampleEvenly(items: string[], n: number): string[] {
+  if (items.length <= n) return items;
+  const out: string[] = [];
+  const step = items.length / n;
+  for (let i = 0; i < n; i++) out.push(items[Math.floor(i * step)]!);
+  return out;
+}
+
 /** Tail-read up to 256KB from the end of a file as UTF-8, or undefined on error. */
 function tailText(path: string): string | undefined {
   try {

package/src/core/hooks/session-name-presence.ts

@@ -0,0 +1,52 @@
+/**
+ * Session-name presence for `turn.stop`.
+ *
+ * While the heartbeat carries a `suggested_session_name`, report whether the
+ * naming ritual is satisfied: either this turn's reply shows the name, or an
+ * earlier reply already did. Scanning covers assistant text blocks only (the
+ * raw transcript tail also carries the name inside the set-task tool_result,
+ * which must not count) plus the adapter-supplied last assistant message, for
+ * stops that arrive without a transcript.
+ *
+ * Two properties the stop-hook naming rule depends on:
+ *
+ * 1. Once a name is satisfied, every later stop keeps reporting `true` rather
+ *    than omitting the field. The rule wants an in-window `turn.stop` carrying
+ *    `session_name_present: true`; omitting it after the heartbeat stamp meant
+ *    nothing could ever re-emit the flag, so every subsequent reply blocked --
+ *    including the replies reproducing the exact name the rule asked for.
+ * 2. The result names WHICH suggested name it covered, so a projector rebuild
+ *    attributes the sighting to that name instead of to whichever name is
+ *    current during the replay. Without it, a re-minted name inherited an older
+ *    name's sighting and looked satisfied without ever having been shown.
+ *
+ * Never throws: coordination telemetry must not take down a hook.
+ */
+
+import { readHeartbeat, stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
+
+export interface SessionNamePresence {
+  session_name_present?: boolean;
+  session_name_present_for?: string;
+}
+
+export function sessionNamePresence(
+  coordRoot: string,
+  instanceId: string,
+  lastAssistantMessage: string,
+  scanAssistantText: (name: string) => boolean,
+): SessionNamePresence {
+  try {
+    const hb = readHeartbeat(coordRoot, instanceId);
+    const name = hb?.suggested_session_name;
+    if (!name) return {};
+    if (hb?.session_name_seen_for === name) {
+      return { session_name_present: true, session_name_present_for: name };
+    }
+    const present = scanAssistantText(name) || lastAssistantMessage.includes(name);
+    if (present) stampSessionNameSeen(coordRoot, instanceId, name);
+    return { session_name_present: present, session_name_present_for: name };
+  } catch {
+    return {};
+  }
+}