harnery 0.32.0 → 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/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,6 +101,16 @@ 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",
   {
@@ -120,6 +138,21 @@ export type TurnStop = EventEnvelope<
   }
 >;
 
+/** 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;
+  }
+>;
+
 // Session-telemetry (merge path)
 export type CommandStart = EventEnvelope<
   "command.start",
@@ -314,6 +347,14 @@ export type StateTaskSet = EventEnvelope<
   }
 >;
 
+export type StateTaskState = EventEnvelope<
+  "state.task_state",
+  {
+    state: "active" | "blocked" | "done";
+    reason?: string;
+  }
+>;
+
 export type StateStatusChecked = EventEnvelope<
   "state.status_checked",
   {
@@ -486,7 +527,9 @@ export type Event =
   | SubagentStart
   | SubagentStop
   | UserPromptSubmit
+  | InteractionInputRequested
   | TurnStop
+  | StopVerdict
   | CommandStart
   | CommandOutput
   | CommandEnd
@@ -505,6 +548,7 @@ export type Event =
   | ClaimRelease
   | ClaimConflict
   | StateTaskSet
+  | StateTaskState
   | StateStatusChecked
   | StateJournalAppend
   | StatePresenceChange

package/src/core/presence/blob.ts

@@ -9,6 +9,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveMachineLabel } from "../../lib/machine.ts";
+import type { AgentActivity, TaskState } from "../agents/state/session-state.ts";
 
 /** Mirror of the local heartbeat freshness window (commands/agents.ts). */
 const FRESHNESS_SECS = 600;
@@ -24,6 +25,9 @@ export interface PresenceAgent {
   session_id?: string;
   platform?: string;
   task?: string;
+  activity: AgentActivity;
+  task_state: TaskState;
+  task_state_reason?: string;
   turn_summary?: string;
   files_touched?: string[];
   last_tool?: string;
@@ -78,6 +82,9 @@ export function buildPresenceBlob(coordRoot: string, now: Date = new Date()): Bu
         session_id: strOr(hb.session_id),
         platform: strOr(hb.platform),
         task: strOr(hb.task),
+        activity: activityOrUnknown(hb.activity),
+        task_state: taskStateOrActive(hb.task_state),
+        task_state_reason: clamp(strOr(hb.task_state_reason), 160),
         turn_summary: clamp(strOr(hb.turn_summary), 160),
         files_touched: Array.isArray(hb.files_touched)
           ? (hb.files_touched as string[]).slice(0, MAX_FILES_PER_AGENT)
@@ -107,6 +114,9 @@ export function buildPresenceBlob(coordRoot: string, now: Date = new Date()): Bu
     n: a.name ?? null,
     k: a.kind ?? null,
     t: a.task ?? null,
+    a: a.activity,
+    l: a.task_state,
+    r: a.task_state_reason ?? null,
     s: a.turn_summary ?? null,
     f: [...(a.files_touched ?? [])].sort(),
   }));
@@ -119,6 +129,14 @@ function strOr(v: unknown): string | undefined {
   return typeof v === "string" && v.length > 0 ? v : undefined;
 }
 
+function activityOrUnknown(v: unknown): AgentActivity {
+  return v === "working" || v === "needs_input" || v === "idle" ? v : "unknown";
+}
+
+function taskStateOrActive(v: unknown): TaskState {
+  return v === "blocked" || v === "done" ? v : "active";
+}
+
 function clamp(v: string | undefined, max: number): string | undefined {
   if (!v) return undefined;
   return v.length > max ? v.slice(0, max) : v;

package/src/core/presence/index.ts

@@ -263,7 +263,7 @@ export function readRemoteMachines(
         machine,
         published_at: blob.published_at,
         age_secs: ageSecs,
-        agents: blob.agents,
+        agents: blob.agents.map(normalizePresenceAgent),
       });
     }
     out.sort((a, b) => a.machine.localeCompare(b.machine));
@@ -272,3 +272,20 @@ export function readRemoteMachines(
     return [];
   }
 }
+
+function normalizePresenceAgent(agent: PresenceAgent): PresenceAgent {
+  const legacy = agent as Partial<PresenceAgent>;
+  return {
+    ...agent,
+    activity:
+      legacy.activity === "working" ||
+      legacy.activity === "needs_input" ||
+      legacy.activity === "idle"
+        ? legacy.activity
+        : "unknown",
+    task_state:
+      legacy.task_state === "blocked" || legacy.task_state === "done"
+        ? legacy.task_state
+        : "active",
+  };
+}

package/src/lib/claude-desktop.ts

@@ -1,6 +1,19 @@
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import {
+  copyFileSync,
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
+import { createInterface } from "node:readline";
 
 /**
  * Claude desktop app session-index access.
@@ -67,6 +80,49 @@ export interface MirrorPlan {
   skippedArchived: number;
 }
 
+export type DesktopLifecycleState = "active" | "blocked" | "done";
+
+export interface DesktopLifecycleRecord {
+  state: DesktopLifecycleState;
+  updatedAt: string;
+  instanceId: string | null;
+  sessionId: string | null;
+  reason: string | null;
+}
+
+export type DesktopTidySource = "lifecycle" | "legacy-prefix";
+
+export interface DesktopTidyAction {
+  entry: DesktopSessionEntry;
+  source: DesktopTidySource;
+  lifecycle: DesktopLifecycleRecord | null;
+}
+
+export type DesktopTidySkipReason =
+  | "already_archived"
+  | "blocked_title"
+  | "lifecycle_active"
+  | "lifecycle_blocked"
+  | "unmatched";
+
+export interface DesktopTidySkip {
+  entry: DesktopSessionEntry;
+  reason: DesktopTidySkipReason;
+  lifecycle: DesktopLifecycleRecord | null;
+}
+
+export interface DesktopTidyPlan {
+  actions: DesktopTidyAction[];
+  skipped: DesktopTidySkip[];
+}
+
+export interface DesktopTidyOptions {
+  /** Restrict entries to accounts whose UUID starts with one of these prefixes. */
+  accounts?: string[];
+  /** Accept an unmatched historical `[DONE]` title as a compatibility fallback. */
+  includeLegacyPrefix?: boolean;
+}
+
 const SESSIONS_DIRNAME = "claude-code-sessions";
 
 function isWsl(): boolean {
@@ -294,3 +350,178 @@ export function applyMirror(plan: MirrorPlan): { copied: number } {
   }
   return { copied };
 }
+
+/**
+ * Read the latest durable lifecycle declaration for every Harnery session.
+ *
+ * The canonical ledger rotates into `events-*.ndjson` archives. Stream each
+ * file rather than loading the whole history into one string, then compare
+ * event timestamps because adapter replay may append an older event later.
+ * Records are indexed by both session_id and instance_id so a desktop
+ * cliSessionId can match either identity shape used by older adapters.
+ */
+export async function readDesktopLifecycleIndex(
+  coordRoot: string,
+): Promise<Map<string, DesktopLifecycleRecord>> {
+  const coordDir = join(coordRoot, ".harnery");
+  const archives = safeReaddir(coordDir)
+    .filter((name) => name.startsWith("events-") && name.endsWith(".ndjson"))
+    .sort();
+  const files = [...archives, "events.ndjson"]
+    .map((name) => join(coordDir, name))
+    .filter((path) => existsSync(path));
+
+  const records = new Map<string, DesktopLifecycleRecord>();
+  const timestamps = new Map<string, number>();
+
+  for (const file of files) {
+    let lines: ReturnType<typeof createInterface> | null = null;
+    try {
+      lines = createInterface({
+        input: createReadStream(file, { encoding: "utf8" }),
+        crlfDelay: Infinity,
+      });
+      for await (const line of lines) {
+        if (!line.trim()) continue;
+        let raw: unknown;
+        try {
+          raw = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (!raw || typeof raw !== "object") continue;
+        const event = raw as Record<string, unknown>;
+        if (event.event_type !== "state.task_state" || typeof event.ts !== "string") continue;
+        const data = event.data;
+        if (!data || typeof data !== "object") continue;
+        const state = (data as Record<string, unknown>).state;
+        if (state !== "active" && state !== "blocked" && state !== "done") continue;
+
+        const instanceId = typeof event.instance_id === "string" ? event.instance_id : null;
+        const sessionId = typeof event.session_id === "string" ? event.session_id : null;
+        const reasonValue = (data as Record<string, unknown>).reason;
+        const record: DesktopLifecycleRecord = {
+          state,
+          updatedAt: event.ts,
+          instanceId,
+          sessionId,
+          reason: typeof reasonValue === "string" && reasonValue.length > 0 ? reasonValue : null,
+        };
+        const timestamp = Number.isFinite(Date.parse(event.ts)) ? Date.parse(event.ts) : 0;
+        for (const key of new Set(
+          [sessionId, instanceId].filter((value): value is string => !!value),
+        )) {
+          const priorTimestamp = timestamps.get(key);
+          if (priorTimestamp !== undefined && priorTimestamp > timestamp) continue;
+          timestamps.set(key, timestamp);
+          records.set(key, record);
+        }
+      }
+    } catch {
+      // A missing or concurrently rotated event file cannot make tidy unsafe:
+      // absent lifecycle evidence leaves entries unmatched and therefore skipped.
+    } finally {
+      lines?.close();
+    }
+  }
+
+  return records;
+}
+
+/** Select desktop entries whose durable lifecycle is done. */
+export function planTidy(
+  accounts: DesktopAccount[],
+  lifecycleBySession: ReadonlyMap<string, DesktopLifecycleRecord>,
+  opts: DesktopTidyOptions = {},
+): DesktopTidyPlan {
+  const selectedAccounts = accounts.filter(
+    (account) =>
+      !opts.accounts?.length ||
+      opts.accounts.some((prefix) => account.accountUuid.startsWith(prefix)),
+  );
+  const actions: DesktopTidyAction[] = [];
+  const skipped: DesktopTidySkip[] = [];
+
+  for (const account of selectedAccounts) {
+    for (const entry of account.entries) {
+      const lifecycle = lifecycleForEntry(entry, lifecycleBySession);
+      if (entry.isArchived) {
+        skipped.push({ entry, reason: "already_archived", lifecycle });
+        continue;
+      }
+      if (hasLifecyclePrefix(entry.title, "BLOCKED")) {
+        skipped.push({ entry, reason: "blocked_title", lifecycle });
+        continue;
+      }
+      if (lifecycle) {
+        if (lifecycle.state === "done") {
+          actions.push({ entry, source: "lifecycle", lifecycle });
+        } else {
+          skipped.push({ entry, reason: `lifecycle_${lifecycle.state}`, lifecycle });
+        }
+        continue;
+      }
+      if (opts.includeLegacyPrefix && hasLifecyclePrefix(entry.title, "DONE")) {
+        actions.push({ entry, source: "legacy-prefix", lifecycle: null });
+      } else {
+        skipped.push({ entry, reason: "unmatched", lifecycle: null });
+      }
+    }
+  }
+
+  return { actions, skipped };
+}
+
+/** Apply a tidy plan with same-directory temp files and atomic renames. */
+export function applyTidy(plan: DesktopTidyPlan): { archived: number; alreadyArchived: number } {
+  let archived = 0;
+  let alreadyArchived = 0;
+  for (const action of plan.actions) {
+    if (archiveEntry(action.entry.file)) archived++;
+    else alreadyArchived++;
+  }
+  return { archived, alreadyArchived };
+}
+
+function lifecycleForEntry(
+  entry: DesktopSessionEntry,
+  lifecycleBySession: ReadonlyMap<string, DesktopLifecycleRecord>,
+): DesktopLifecycleRecord | null {
+  if (entry.cliSessionId) {
+    const lifecycle = lifecycleBySession.get(entry.cliSessionId);
+    if (lifecycle) return lifecycle;
+  }
+  return entry.sessionId ? (lifecycleBySession.get(entry.sessionId) ?? null) : null;
+}
+
+function hasLifecyclePrefix(title: string | null, state: "BLOCKED" | "DONE"): boolean {
+  if (!title) return false;
+  return new RegExp(`^\\s*\\[${state}\\](?:\\s*-|\\s|$)`, "i").test(title);
+}
+
+function archiveEntry(file: string): boolean {
+  const text = readFileSync(file, "utf8");
+  const raw = JSON.parse(text) as unknown;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`desktop entry is not a JSON object: ${file}`);
+  }
+  const entry = raw as Record<string, unknown>;
+  if (entry.isArchived === true) return false;
+  entry.isArchived = true;
+
+  const pretty = text.includes("\n");
+  const trailingNewline = text.endsWith("\n") ? "\n" : "";
+  const next = `${JSON.stringify(entry, null, pretty ? 2 : undefined)}${trailingNewline}`;
+  const temp = join(dirname(file), `.${basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temp, next, { encoding: "utf8", mode: statSync(file).mode });
+    renameSync(temp, file);
+  } finally {
+    try {
+      unlinkSync(temp);
+    } catch {
+      // rename already consumed the temp file, or creation failed before it existed
+    }
+  }
+  return true;
+}