harnery 0.31.6 → 0.33.0

package/src/core/hooks/codex-authorization.ts

@@ -0,0 +1,253 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+export type CodexHookTrustStatus = "managed" | "trusted" | "untrusted" | "modified";
+
+export type CodexHookAuthorizationStatus =
+  | "runnable"
+  | "review_required"
+  | "disabled"
+  | "not_wired"
+  | "error";
+
+export interface CodexHookAuthorizationResult {
+  status: CodexHookAuthorizationStatus;
+  detail: string;
+  hookCount: number;
+  disabledCount: number;
+  trustCounts: Partial<Record<CodexHookTrustStatus, number>>;
+}
+
+export interface CodexHookAuthorizationProbeOptions {
+  cwd: string;
+  codexBin?: string;
+  appServerArgs?: string[];
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+}
+
+interface JsonObject {
+  [key: string]: unknown;
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string")
+    : [];
+}
+
+function trustStatus(value: unknown): CodexHookTrustStatus | null {
+  return value === "managed" || value === "trusted" || value === "untrusted" || value === "modified"
+    ? value
+    : null;
+}
+
+function normalizedPath(value: string): string {
+  return value.replaceAll("\\", "/").replace(/\/$/, "").toLowerCase();
+}
+
+/**
+ * Convert Codex app-server's `hooks/list` response into the one authorization
+ * state doctor needs. This is intentionally read-only: hashes are observed but
+ * never persisted, and only commands containing Harnery's `agent-hook` binary
+ * are included in the result.
+ */
+export function assessCodexHookList(response: unknown, cwd: string): CodexHookAuthorizationResult {
+  if (!isObject(response) || !isObject(response.result) || !Array.isArray(response.result.data)) {
+    return {
+      status: "error",
+      detail: "Codex hooks/list returned an invalid response",
+      hookCount: 0,
+      disabledCount: 0,
+      trustCounts: {},
+    };
+  }
+
+  const entries = response.result.data.filter(isObject);
+  const expected = normalizedPath(cwd);
+  const entry =
+    entries.find((candidate) => {
+      const candidateCwd = candidate.cwd;
+      return typeof candidateCwd === "string" && normalizedPath(candidateCwd) === expected;
+    }) ?? (entries.length === 1 ? entries[0] : undefined);
+  if (!entry) {
+    return {
+      status: "error",
+      detail: "Codex hooks/list omitted the requested workspace",
+      hookCount: 0,
+      disabledCount: 0,
+      trustCounts: {},
+    };
+  }
+
+  const errors = stringArray(entry.errors);
+  if (errors.length > 0) {
+    return {
+      status: "error",
+      detail: `Codex could not load hooks: ${errors.join("; ")}`,
+      hookCount: 0,
+      disabledCount: 0,
+      trustCounts: {},
+    };
+  }
+
+  const hooks = Array.isArray(entry.hooks) ? entry.hooks.filter(isObject) : [];
+  const harneryHooks = hooks.filter(
+    (hook) =>
+      typeof hook.command === "string" && /(?:^|[\\/\s])agent-hook(?:\s|$)/.test(hook.command),
+  );
+  if (harneryHooks.length === 0) {
+    return {
+      status: "not_wired",
+      detail: "Codex discovered no Harnery hooks",
+      hookCount: 0,
+      disabledCount: 0,
+      trustCounts: {},
+    };
+  }
+
+  const counts: Partial<Record<CodexHookTrustStatus, number>> = {};
+  let disabledCount = 0;
+  for (const hook of harneryHooks) {
+    const status = trustStatus(hook.trustStatus);
+    if (!status) {
+      return {
+        status: "error",
+        detail: "Codex returned an unknown hook trust state",
+        hookCount: harneryHooks.length,
+        disabledCount,
+        trustCounts: counts,
+      };
+    }
+    counts[status] = (counts[status] ?? 0) + 1;
+    if (hook.enabled !== true) disabledCount += 1;
+  }
+
+  const reviewCount = (counts.untrusted ?? 0) + (counts.modified ?? 0);
+  const warnings = stringArray(entry.warnings);
+  const warningSuffix = warnings.length > 0 ? `; ${warnings.length} Codex warning(s)` : "";
+  if (reviewCount > 0) {
+    return {
+      status: "review_required",
+      detail:
+        `${reviewCount} of ${harneryHooks.length} Harnery hooks require review` +
+        ` (${counts.untrusted ?? 0} new, ${counts.modified ?? 0} modified)${warningSuffix}`,
+      hookCount: harneryHooks.length,
+      disabledCount,
+      trustCounts: counts,
+    };
+  }
+  if (disabledCount > 0) {
+    return {
+      status: "disabled",
+      detail: `${disabledCount} of ${harneryHooks.length} trusted Harnery hooks are disabled${warningSuffix}`,
+      hookCount: harneryHooks.length,
+      disabledCount,
+      trustCounts: counts,
+    };
+  }
+  return {
+    status: "runnable",
+    detail: `${harneryHooks.length} Harnery hooks trusted and enabled${warningSuffix}`,
+    hookCount: harneryHooks.length,
+    disabledCount: 0,
+    trustCounts: counts,
+  };
+}
+
+/**
+ * Ask the active Codex CLI for hook authorization through its app-server
+ * protocol. The child is closed as soon as `hooks/list` responds. Harnery never
+ * calls the trust-write method and never reads Codex's private config format.
+ */
+export function probeCodexHookAuthorization(
+  options: CodexHookAuthorizationProbeOptions,
+): Promise<CodexHookAuthorizationResult> {
+  const codexBin = options.codexBin ?? "codex";
+  const args = options.appServerArgs ?? ["app-server"];
+  const timeoutMs = options.timeoutMs ?? 5_000;
+
+  return new Promise((resolve) => {
+    const child = spawn(codexBin, args, {
+      cwd: options.cwd,
+      env: options.env ?? process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const lines = createInterface({ input: child.stdout });
+    let settled = false;
+    let stderr = "";
+
+    const finish = (result: CodexHookAuthorizationResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      lines.close();
+      child.stdin.end();
+      child.kill();
+      resolve(result);
+    };
+    const fail = (detail: string): void =>
+      finish({ status: "error", detail, hookCount: 0, disabledCount: 0, trustCounts: {} });
+
+    const timer = setTimeout(() => {
+      fail(`Codex hooks/list timed out after ${timeoutMs}ms`);
+    }, timeoutMs);
+
+    child.stderr.on("data", (chunk: Buffer | string) => {
+      if (stderr.length < 4_096) stderr += chunk.toString();
+    });
+    child.stdin.on("error", (error) => fail(`Codex app-server input failed: ${error.message}`));
+    child.on("error", (error) => fail(`could not start Codex app-server: ${error.message}`));
+    child.on("close", (code) => {
+      if (!settled) {
+        const suffix = stderr.trim() ? `: ${stderr.trim().slice(0, 500)}` : "";
+        fail(
+          `Codex app-server exited before hooks/list completed (exit ${code ?? "unknown"})${suffix}`,
+        );
+      }
+    });
+    lines.on("line", (line) => {
+      let message: JsonObject;
+      try {
+        const parsed = JSON.parse(line) as unknown;
+        if (!isObject(parsed)) return;
+        message = parsed;
+      } catch {
+        return;
+      }
+      if (message.id === 0) {
+        if (message.error) {
+          fail("Codex app-server rejected initialization");
+          return;
+        }
+        child.stdin.write(`${JSON.stringify({ method: "initialized" })}\n`);
+        child.stdin.write(
+          `${JSON.stringify({ method: "hooks/list", id: 1, params: { cwds: [options.cwd] } })}\n`,
+        );
+        return;
+      }
+      if (message.id === 1) {
+        if (message.error) {
+          fail("Codex app-server rejected hooks/list");
+          return;
+        }
+        finish(assessCodexHookList(message, options.cwd));
+      }
+    });
+
+    child.stdin.write(
+      `${JSON.stringify({
+        method: "initialize",
+        id: 0,
+        params: {
+          clientInfo: { name: "harnery_doctor", title: "Harnery Doctor", version: "0.0.0" },
+        },
+      })}\n`,
+    );
+  });
+}

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

@@ -51,6 +51,14 @@ export type SessionStart = EventEnvelope<
     cwd: string;
     model?: string;
     pid: number;
+    /** Content hash of every repo-authored instruction/config file this
+     * adapter can load for the session's working-path profile. */
+    instruction_bundle_id?: string;
+    /** Parallel hash of canonical AGENTS.md + .agents sources. This diagnoses
+     * sync drift without splitting behavior cohorts when rendered bytes match. */
+    instruction_source_id?: string;
+    instruction_profile_root?: string;
+    instruction_component_count?: number;
     /** Present iff this session is a `workflow run` child: the run id whose
      * transcript owns it (child env HARNERY_WORKFLOW_RUN_ID). Optional-field
      * addition per the schema evolution rules (minor bump). */
@@ -93,12 +101,55 @@ export type UserPromptSubmit = EventEnvelope<
   }
 >;
 
+/** Direct adapter evidence that the session is waiting for operator input. */
+export type InteractionInputRequested = EventEnvelope<
+  "interaction.input_requested",
+  {
+    request_kind: "permission";
+    tool_name?: string;
+    reason?: string;
+  }
+>;
+
 export type TurnStop = EventEnvelope<
   "turn.stop",
   {
     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[];
+  }
+>;
+
+/** The evaluated end-turn policy outcome. One row per Stop evaluation makes
+ * the future bounce denominator explicit and keeps repeated remediation nags
+ * from being mistaken for additional human turns. */
+export type StopVerdict = EventEnvelope<
+  "stop.verdict",
+  {
+    allow: boolean;
+    rule: string;
+    reason?: string;
+    enforcement_mode: "enforced" | "observe_only" | "exempt" | "fail_open";
+    eligible: boolean;
+    nag_delivered: boolean;
   }
 >;
 
@@ -258,6 +309,10 @@ export type ClaimAcquire = EventEnvelope<
   {
     path: string;
     mode: "read" | "write";
+    finalization?: {
+      disposition: "git" | "output";
+      root: string;
+    };
   }
 >;
 
@@ -284,6 +339,19 @@ 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;
+  }
+>;
+
+export type StateTaskState = EventEnvelope<
+  "state.task_state",
+  {
+    state: "active" | "blocked" | "done";
+    reason?: string;
   }
 >;
 
@@ -459,7 +527,9 @@ export type Event =
   | SubagentStart
   | SubagentStop
   | UserPromptSubmit
+  | InteractionInputRequested
   | TurnStop
+  | StopVerdict
   | CommandStart
   | CommandOutput
   | CommandEnd
@@ -478,6 +548,7 @@ export type Event =
   | ClaimRelease
   | ClaimConflict
   | StateTaskSet
+  | StateTaskState
   | StateStatusChecked
   | StateJournalAppend
   | StatePresenceChange

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;
 }