harnery 0.31.6 → 0.33.0

package/src/commands/instructions.ts

@@ -0,0 +1,129 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import { countTokens } from "gpt-tokenizer/model/gpt-4o";
+import type { EmitContext } from "../commander.ts";
+import { monorepoRoot } from "../core/agents/index.ts";
+import type { Adapter } from "../core/hooks/events/schema.ts";
+import {
+  buildInstructionBundle,
+  type InstructionBundleComponent,
+} from "../lib/instructions/bundle.ts";
+
+interface ManifestOptions {
+  adapter: string;
+  format: string;
+  output?: string;
+}
+
+export function registerInstructionsCommand(program: Command, emit: EmitContext): void {
+  const command = program
+    .command("instructions")
+    .description(
+      "Inspect and version the repo-authored instruction bundle loaded by each adapter.",
+    );
+
+  command
+    .command("manifest [paths...]")
+    .description("Emit a machine-readable bundle manifest for one or more working paths")
+    .option("--adapter <adapter>", "claude-code, cursor, codex, or all", "all")
+    .option("--format <type>", "Output format: json or table", "json")
+    .option("-o, --output <file>", "Write the complete JSON manifest to a file")
+    .action((paths: string[], options: ManifestOptions) => {
+      if (options.format === "json") emit.config({ format: "json" });
+      const coordRoot = monorepoRoot() ?? process.cwd();
+      const adapters = parseAdapters(options.adapter);
+      const profiles = (paths.length > 0 ? paths : [process.cwd()]).flatMap((path) =>
+        adapters.map((adapter) =>
+          enrichBundle(
+            buildInstructionBundle({ coordRoot, cwd: resolve(path), adapter }),
+            coordRoot,
+          ),
+        ),
+      );
+
+      const manifest = {
+        ok: true,
+        schema_version: 1,
+        generated_at: new Date().toISOString(),
+        source_commit: gitHead(coordRoot),
+        tokenizer: "o200k_base",
+        coord_root: ".",
+        profile_count: profiles.length,
+        profiles,
+      };
+      if (options.output) {
+        const output = resolve(options.output);
+        writeFileSync(output, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+        emit.data({
+          ok: true,
+          output,
+          schema_version: manifest.schema_version,
+          generated_at: manifest.generated_at,
+          source_commit: manifest.source_commit,
+          profile_count: manifest.profile_count,
+        });
+      } else {
+        emit.data(manifest);
+      }
+    });
+}
+
+function parseAdapters(value: string): Adapter[] {
+  if (value === "all") return ["claude-code", "cursor", "codex"];
+  if (value === "claude-code" || value === "cursor" || value === "codex") return [value];
+  throw new Error(`unsupported adapter '${value}' (expected claude-code, cursor, codex, or all)`);
+}
+
+function enrichBundle(bundle: ReturnType<typeof buildInstructionBundle>, coordRoot: string) {
+  const components = bundle.components.map((component) => enrichComponent(component, coordRoot));
+  const canonicalSources = bundle.canonical_sources.map((component) =>
+    enrichComponent(component, coordRoot),
+  );
+  return {
+    ...bundle,
+    coord_root: ".",
+    components,
+    canonical_sources: canonicalSources,
+    totals: totals(components),
+    canonical_source_totals: totals(canonicalSources),
+  };
+}
+
+function enrichComponent(component: InstructionBundleComponent, coordRoot: string) {
+  const bytes = readFileSync(resolve(coordRoot, component.path));
+  const text = bytes.includes(0) ? null : bytes.toString("utf8");
+  return {
+    ...component,
+    chars: text?.length ?? null,
+    tokens: text === null ? null : countTokens(text),
+  };
+}
+
+function totals(components: ReturnType<typeof enrichComponent>[]) {
+  const roles = ["always_loaded", "just_in_time", "runtime_config"] as const;
+  return {
+    files: components.length,
+    bytes: components.reduce((sum, component) => sum + component.bytes, 0),
+    tokens: components.reduce((sum, component) => sum + (component.tokens ?? 0), 0),
+    by_role: Object.fromEntries(
+      roles.map((role) => {
+        const selected = components.filter((component) => component.role === role);
+        return [
+          role,
+          {
+            files: selected.length,
+            bytes: selected.reduce((sum, component) => sum + component.bytes, 0),
+            tokens: selected.reduce((sum, component) => sum + (component.tokens ?? 0), 0),
+          },
+        ];
+      }),
+    ),
+  };
+}
+
+function gitHead(root: string): string | null {
+  const result = spawnSync("git", ["rev-parse", "HEAD"], { cwd: root, encoding: "utf8" });
+  return result.status === 0 ? result.stdout.trim() : null;
+}

package/src/commands/presence.ts

@@ -175,7 +175,13 @@ export function registerPresenceCommand(program: Command, emit: EmitContext): vo
         for (const a of m.agents) {
           const task = a.task ? `  "${a.task.slice(0, 70)}"` : "";
           const files = a.files_touched?.length ? `  [${a.files_touched.length} files]` : "";
-          emit.text(`  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}\n`);
+          const lifecycle =
+            a.task_state === "blocked" && a.task_state_reason
+              ? `${a.task_state}: ${a.task_state_reason}`
+              : a.task_state;
+          emit.text(
+            `  agent-${a.name ?? a.instance_id.slice(0, 8)}${task}${files}  activity=${a.activity} lifecycle=${lifecycle}\n`,
+          );
         }
       }
     });

package/src/commands/tunnel.ts

@@ -76,7 +76,6 @@ interface LogsOpts {
   name?: string;
   follow?: boolean;
   gate?: boolean;
-  cloudflared?: boolean;
   provider?: boolean;
 }
 
@@ -916,7 +915,7 @@ function status(opts: StatusOpts): void {
     return;
   }
   if (states.length === 1) {
-    // Single tunnel: show the full detail block (backward-compatible).
+    // A single tunnel is clearer as a detail block than as a one-row table.
     statusDetail(states[0]);
     return;
   }
@@ -953,8 +952,7 @@ function logs(opts: LogsOpts): void {
   const name = resolveName(opts.name);
   const state = readState(name);
   const provider = state?.provider ?? "cloudflare";
-  const which =
-    opts.cloudflared || opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
+  const which = opts.provider ? providerLogFile(name, provider) : gateLogFile(name);
   const path = cachePath("tunnel", which);
   if (!existsSync(path)) {
     emit.error({ code: "tunnel_no_log", message: `No log file at ${path}` });
@@ -1089,7 +1087,6 @@ export function registerTunnelCommand(
     .option("-f, --follow", "follow the log")
     .option("--gate", "tail the gate log (default)")
     .option("--provider", "tail the provider log instead")
-    .option("--cloudflared", "tail the Cloudflare provider log instead (legacy alias)")
     .action(logs);
 
   const allow = cmd

package/src/core/agents/canonical-emit.ts

@@ -37,11 +37,11 @@ export function resolveEmitRoot(start: string = process.cwd()): string | null {
   return resolveCoordRoot(start);
 }
 
-export function emitCanonical(input: CanonicalEmitInput): void {
+export function emitCanonical(input: CanonicalEmitInput): boolean {
   const root = resolveEmitRoot();
-  if (!root) return;
+  if (!root) return false;
   const binary = coordBinPath("agent-coord", root);
-  if (!binary) return;
+  if (!binary) return false;
   try {
     const args = [
       "emit-event",
@@ -71,15 +71,16 @@ export function emitCanonical(input: CanonicalEmitInput): void {
     if (result.error || result.status !== 0) {
       const why = result.error ? result.error.message : `exit ${result.status}`;
       process.stderr.write(`emitCanonical: ${input.type} emit failed (${why})\n`); // lint-ok-emission: soft-fail diagnostic promised by the module doc; silent drops cost blocked turns
+      return false;
     }
+    return true;
   } catch {
-    /* never break the caller */
+    return false;
   }
 }
 
 /**
- * Normalize the heartbeat's `platform` field (which uses snake_case
- * `claude_code`) to the canonical kebab-case Adapter type.
+ * Normalize the heartbeat's `platform` field to the canonical Adapter type.
  */
 export function normalizeAdapter(platform: string | undefined): "claude-code" | "cursor" | "codex" {
   if (platform === "cursor") return "cursor";

package/src/core/agents/cli.ts

@@ -96,23 +96,11 @@ async function handleVerdict(root: string): Promise<number> {
   } else if (parsed.rule === "claim") {
     const { evaluateClaim } = await import("./rules/claim-conflict.ts");
     verdict = evaluateClaim(root, parsed as unknown as Parameters<typeof evaluateClaim>[1]);
-  } else if (parsed.rule === "commit") {
-    const { evaluateCommit } = await import("./rules/commit-conflict.ts");
-    const result = evaluateCommit(root, parsed as unknown as Parameters<typeof evaluateCommit>[1]);
-    // Map CommitVerdictResult → the standard verdict envelope, stash details
-    // on extra fields so the bash caller can pull conflicts + log_lines.
-    verdict = {
-      allow: result.allow,
-      exit_code: result.exit_code,
-      rule: result.rule,
-      reason: result.message,
-      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
-    } as typeof verdict;
-    (verdict as Record<string, unknown>).conflicts = result.conflicts;
-    (verdict as Record<string, unknown>).log_lines = result.log_lines;
-    (verdict as Record<string, unknown>).suppressed_self_attribution =
-      result.suppressed_self_attribution ?? false;
   } else {
+    // NB: rule === "commit" was served here until 2026-08-09; the commit
+    // guard now enters through `git-hook pre-commit`, which runs the same
+    // evaluateCommit in-process. A straggler host lands in this fail-open
+    // branch, which is the pre-migration behavior for a malformed request.
     verdict = {
       allow: true,
       exit_code: 0,
@@ -261,14 +249,6 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       );
       return 0;
     }
-    case "stamp-status-call": {
-      const hb = writer.stampStatusCheck(root, owner);
-      if (!hb) return 1;
-      process.stdout.write(
-        `${JSON.stringify({ instance_id: owner, last_status_at: hb.last_status_at })}\n`,
-      );
-      return 0;
-    }
     case "set-turn-summary": {
       const summary = args.join(" ");
       const hb = writer.setTurnSummary(root, owner, summary);
@@ -344,10 +324,20 @@ async function handleStateAction(root: string, action: string, rest: string[]):
       // fragility. Positionals (sessionId, model) stay as-is once flags are
       // filtered out.
       const adapter = args.find((a) => a.startsWith("--adapter="))?.slice("--adapter=".length);
+      const forkedFrom = args
+        .find((a) => a.startsWith("--forked-from="))
+        ?.slice("--forked-from=".length);
       const positional = args.filter((a) => !a.startsWith("--"));
       const sessionId = positional[0];
       const model = positional[1];
-      const hb = writer.healHeartbeat(root, owner, sessionId, model, adapter);
+      const hb = writer.healHeartbeat(
+        root,
+        owner,
+        sessionId,
+        model,
+        adapter,
+        forkedFrom ? { forkedFrom } : undefined,
+      );
       process.stdout.write(`${JSON.stringify({ instance_id: owner, recreated: !!hb })}\n`);
       return hb ? 0 : 1;
     }
@@ -497,69 +487,39 @@ async function handleCouncilAction(root: string, action: string, rest: string[])
 
 async function handleAssignName(root: string, rest: string[]): Promise<number> {
   const { assignName } = await import("./state/names.ts");
-  const [owner, kindArg] = rest;
+  // Optional recorded-fork-lineage flag: --forked-from <parent_instance_id>.
+  // Supplied by an adapter layer that knows (or detected) that this session
+  // was branched from another conversation. Inert on resume: assignName only
+  // stamps lineage on the row that first assigns the instance.
+  let forkedFrom: string | undefined;
+  const positional: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "--forked-from") {
+      forkedFrom = rest[++i];
+      continue;
+    }
+    positional.push(rest[i]!);
+  }
+  const [owner, kindArg] = positional;
   if (!owner || !kindArg) {
-    process.stderr.write("agent-coord assign-name <instance_id> <session|subagent|transient>\n");
+    process.stderr.write(
+      "agent-coord assign-name <instance_id> <session|subagent|transient> [--forked-from <instance_id>]\n",
+    );
     return 2;
   }
   if (kindArg !== "session" && kindArg !== "subagent" && kindArg !== "transient") {
     process.stderr.write(`agent-coord assign-name: invalid kind ${kindArg}\n`);
     return 2;
   }
-  const name = assignName(root, owner, kindArg);
-  process.stdout.write(`${JSON.stringify({ instance_id: owner, name, kind: kindArg })}\n`);
-  return 0;
-}
-
-async function handlePostCommit(root: string): Promise<number> {
-  const raw = await readStdin();
-  let req: { owner?: string; prune?: string[] } = {};
-  try {
-    req = JSON.parse(raw);
-  } catch {
-    return 0;
-  }
-  const { groupUnclaim } = await import("./state/heartbeat-writer.ts");
-
-  // Session-group-wide unclaim. `owner` is the parent's session_id which is
-  // also the group key (parent + subagents share session_id). Each actual
-  // removal also emits a durable claim.release event — the projector rebuilds
-  // files_touched from the permanent Edit/Write events, so a file-only prune
-  // would resurrect on the next replay.
-  if (req.owner && Array.isArray(req.prune)) {
-    for (const path of req.prune) {
-      try {
-        for (const hit of groupUnclaim(root, req.owner, path)) {
-          await emitClaimRelease(root, hit.instance_id, hit, path, "commit");
-        }
-      } catch {
-        /* best-effort */
-      }
-    }
-  }
-  return 0;
-}
-
-async function handlePostCheckout(root: string, _rest: string[]): Promise<number> {
-  const raw = await readStdin();
-  let req: { owner?: string; removed?: string[] } = {};
-  try {
-    req = JSON.parse(raw);
-  } catch {
-    return 0;
-  }
-  const { groupUnclaim } = await import("./state/heartbeat-writer.ts");
-  if (req.owner && Array.isArray(req.removed)) {
-    for (const path of req.removed) {
-      try {
-        for (const hit of groupUnclaim(root, req.owner, path)) {
-          await emitClaimRelease(root, hit.instance_id, hit, path, "checkout");
-        }
-      } catch {
-        /* best-effort */
-      }
-    }
-  }
+  const name = assignName(root, owner, kindArg, forkedFrom ? { forkedFrom } : undefined);
+  process.stdout.write(
+    `${JSON.stringify({
+      instance_id: owner,
+      name,
+      kind: kindArg,
+      ...(forkedFrom ? { forked_from: forkedFrom } : {}),
+    })}\n`,
+  );
   return 0;
 }
 
@@ -660,9 +620,13 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
   const sessionNameNudge = args["session-name-nudge"] === "true";
   const taskNudge = args["task-nudge"] === "true";
   const statusFooterNudge = args["status-footer-nudge"] === "true";
+  // Value is the adapter id; a bare flag (parsed as "true") still enables the
+  // reminder with the adapter-neutral wording.
+  const turnRitualNudge =
+    args["turn-ritual-nudge"] === "true" ? "generic" : args["turn-ritual-nudge"];
   if (!instanceId) {
     process.stderr.write(
-      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--status-footer-nudge]\n",
+      "agent-coord prompt-context --instance <id> [--session <id>] [--name <agent-name>] [--session-name-nudge] [--task-nudge] [--status-footer-nudge] [--turn-ritual-nudge <adapter>]\n",
     );
     return 2;
   }
@@ -675,6 +639,7 @@ async function handlePromptContext(root: string, rest: string[]): Promise<number
     sessionNameNudge,
     taskNudge,
     statusFooterNudge,
+    turnRitualNudge,
   });
   process.stdout.write(text);
   return 0;
@@ -841,6 +806,100 @@ async function handleEmitEvent(root: string, rest: string[]): Promise<number> {
   return 0;
 }
 
+/**
+ * `agent-coord git-hook <event> [args]` — the single entry a host git hook
+ * invokes. Owns ALL of the coordination git plumbing that hosts used to carry
+ * as bash (staged/committed/checkout-removed collection, submodule
+ * canonicalization, gitlink probe, verdict, claim pruning), so a harnery
+ * upgrade upgrades hook behavior with no change to the host's hook file.
+ *
+ * Events: pre-commit (E-guard verdict; exit 1 blocks the commit),
+ * post-commit (prune committed paths' claims), post-checkout <old> <new>
+ * (release claims on paths the ref move rewrote).
+ *
+ * Fail-open by design: an internal error never blocks a commit (parity with
+ * the bash era, where a crashed verdict read as empty and the hook moved on).
+ * A clean conflict verdict still blocks.
+ */
+async function handleGitHook(fallbackRoot: string, rest: string[]): Promise<number> {
+  const event = rest[0];
+  if (process.env.HARNERY_AGENT_COORD_OFF === "1") return 0;
+  const cwd = process.cwd();
+
+  try {
+    const gh = await import("./git-hook.ts");
+    // Pin the coord root to the superproject: a submodule cwd may carry its
+    // own config-only .harnery that the generic root walk would land on.
+    const root = gh.discoverCoordRoot(cwd) ?? fallbackRoot;
+
+    if (event === "pre-commit") {
+      const { staged, gitlinks } = gh.collectStaged(cwd);
+      if (staged.length === 0) return 0;
+      const { evaluateCommit } = await import("./rules/commit-conflict.ts");
+      const result = evaluateCommit(root, {
+        staged_paths: staged,
+        staged_gitlinks: gitlinks,
+        bypass: process.env.HARNERY_AGENT_COORD_BYPASS === "1",
+      });
+      // Forensics channel shared with the stdin `verdict` path.
+      try {
+        const logPath = join(root, ".harnery", "debug", "agent-coord-verdict.ndjson");
+        await mkdir(dirname(logPath), { recursive: true });
+        await appendFile(
+          logPath,
+          `${JSON.stringify({ ts: new Date().toISOString(), via: "git-hook", staged, verdict: result })}\n`,
+        );
+      } catch {
+        /* diagnostics never break a verdict */
+      }
+      if (result.rule !== "commit.pass") {
+        if (result.message) process.stdout.write(`\n${result.message}\n\n`);
+        for (const c of result.conflicts) {
+          process.stdout.write(`    ${c.staged_path}  (held by ${c.short_name})\n`);
+        }
+        process.stdout.write("\n");
+      }
+      if (!result.allow) {
+        process.stdout.write(
+          "  Wait for them to finish, split the commit, or set\n" +
+            "  HARNERY_AGENT_COORD_BYPASS=1 to force this commit through.\n\n",
+        );
+        return result.exit_code || 1;
+      }
+      return 0;
+    }
+
+    if (event === "post-commit" || event === "post-checkout") {
+      const paths =
+        event === "post-commit"
+          ? gh.collectCommitted(cwd)
+          : gh.collectCheckoutRemoved(cwd, rest[1] ?? "", rest[2] ?? "");
+      if (paths.length === 0) return 0;
+      const { resolveOwner } = await import("../hooks/resolve/owner.ts");
+      const owner = resolveOwner({ payload: null, coordRoot: root })?.instance_id;
+      if (!owner) return 0;
+      const { groupUnclaim } = await import("./state/heartbeat-writer.ts");
+      const reason = event === "post-commit" ? ("commit" as const) : ("checkout" as const);
+      for (const path of paths) {
+        try {
+          for (const hit of groupUnclaim(root, owner, path)) {
+            await emitClaimRelease(root, hit.instance_id, hit, path, reason);
+          }
+        } catch {
+          /* best-effort */
+        }
+      }
+      return 0;
+    }
+
+    process.stderr.write(`agent-coord git-hook: unknown event ${event ?? "(none)"}\n`);
+    return 0;
+  } catch {
+    // Fail open: coordination must never brick git.
+    return 0;
+  }
+}
+
 async function main(): Promise<number> {
   const [subcommand, ...rest] = process.argv.slice(2);
   const root = findCoordRoot(process.cwd());
@@ -860,7 +919,6 @@ async function main(): Promise<number> {
 
   if (
     subcommand === "set-task" ||
-    subcommand === "stamp-status-call" ||
     subcommand === "set-turn-summary" ||
     subcommand === "release-claim" ||
     subcommand === "kill-heartbeat" ||
@@ -918,12 +976,8 @@ async function main(): Promise<number> {
     return handleShellMutationClaimLog(root, rest);
   }
 
-  if (subcommand === "post-commit") {
-    return handlePostCommit(root);
-  }
-
-  if (subcommand === "post-checkout") {
-    return handlePostCheckout(root, rest);
+  if (subcommand === "git-hook") {
+    return handleGitHook(root, rest);
   }
 
   await logNoop(root, subcommand ?? "(none)", rest);

package/src/core/agents/coord-client.ts

@@ -75,12 +75,27 @@ export interface Heartbeat {
   task?: string;
   /** UTC ISO-8601 timestamp when task was last set/cleared. Used by adapters without Stop enforcement to compute staleness. 2026-05-24. */
   task_updated_at?: string | null;
+  /** Current evidence-derived activity axis. */
+  activity?: "unknown" | "working" | "needs_input" | "idle";
+  activity_updated_at?: string;
+  activity_source?: string;
+  /** Explicit task lifecycle axis. */
+  task_state?: "active" | "blocked" | "done";
+  task_state_updated_at?: string;
+  task_state_reason?: string;
+  /** Session name built on the first non-empty set-task; its presence means "this session has been named". 2026-08-09. */
+  suggested_session_name?: string;
+  /** Stamped by turn.stop once the suggested name is seen in assistant reply text. 2026-08-09. */
+  session_name_seen_at?: string;
+  /** Which suggested name the latest sighting covered. */
+  session_name_seen_for?: string;
   /** Auto-generated per-turn summary written by the Stop hook via Haiku. 2026-05-23. */
   turn_summary?: string | null;
   /** UTC ISO-8601 timestamp when turn_summary was last refreshed. */
   turn_summary_updated_at?: string | null;
-  /** Hook client: `claude_code` (default) or `cursor`. Cursor Phase 1. */
+  /** Hook client: `claude-code` (default) or `cursor`. Cursor Phase 1. */
   platform?: string;
+  workflow_run_id?: string;
 }
 
 /**
@@ -260,10 +275,10 @@ export function parsePidmapRowOwner(row: string): string {
   return tab >= 0 ? trimmed.slice(0, tab) : trimmed;
 }
 
-/** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
+/** Parse platform from a pid-map row; legacy rows default to `claude-code`. */
 export function parsePidmapRowPlatform(row: string): string {
   const platform = row.trim().split("\t")[1]?.trim();
-  return platform || "claude_code";
+  return platform || "claude-code";
 }
 
 /** Parse the start token from a pid-map row; rows written before it carry none. */
@@ -368,7 +383,7 @@ function readPidmapRow(pidmapDir: string, pid: number): string | null {
  *
  * Pid-map files are `instance_id` or `instance_id\tplatform` (Cursor Phase 1).
  * Prefer a row whose platform matches `HARNERY_AGENT_COORD_PLATFORM` (default
- * `claude_code`); otherwise return the first owner seen on the walk.
+ * `claude-code`); otherwise return the first owner seen on the walk.
  *
  * Subagents intentionally do not write pid-map entries; a Bash-tool ppid-walk
  * from inside a subagent therefore resolves to the *parent's* pid-map entry.
@@ -443,7 +458,7 @@ export function resolveOwnerByPidmap(root: string): {
   const pidmapDir = resolve(root, ".harnery", "pid-map");
   if (!existsSync(pidmapDir)) return { owner: null, source: "none" };
 
-  const prefer = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim() || "claude_code";
+  const prefer = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim() || "claude-code";
   let fallbackOwner: string | null = null;
   let pid: number | null = process.pid;
 
@@ -482,6 +497,7 @@ const SESSION_ID_ENV_VARS = [
   "CURSOR_SESSION_ID",
   "CURSOR_CONVERSATION_ID",
   "CODEX_SESSION_ID",
+  "CODEX_THREAD_ID",
 ] as const;
 
 /** Read normalized candidates from the first non-empty adapter session-id env var. */