harnery 0.38.0 → 0.40.0

package/src/core/hooks/adapter/output.ts

@@ -8,16 +8,15 @@
  * - **Claude Code**: `{hookSpecificOutput: {hookEventName, additionalContext}}`
  *   for SessionStart / UserPromptSubmit / SubagentStart; deny uses
  *   `{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason}}`.
- * - **Cursor**: `{additional_context, env?}` flat for sessionStart and other
- *   context-capable events. Its current beforeSubmitPrompt schema can validate
- *   or block but cannot inject context, so UserPromptSubmit output is skipped.
- *   Deny uses `{permission: "deny", agent_message, user_message}`.
+ * - **Cursor**: `{additional_context}` flat for context-capable events,
+ *   including beforeSubmitPrompt. Deny uses
+ *   `{permission: "deny", agent_message, user_message}`.
  * - **Codex**: structurally identical to Claude Code for context and tool
  *   denials. Stop blocks are deliberately suppressed because their automatic
  *   continuation can replace a completed user-facing answer.
  *
  * Every helper writes to process.stdout + newline-terminates so callers can
- * fire-and-forget. Empty text → no-op (no JSON written).
+ * fire-and-forget. Empty text is a no-op.
  */
 
 import type { Adapter } from "../../adapter.ts";
@@ -31,23 +30,17 @@ export type SystemEvent =
   | "PreToolUse"
   | "PostToolUse";
 
-/**
- * Whether this adapter can actually receive injected context for an event.
- * Cursor's beforeSubmitPrompt hook can allow or block a turn but cannot inject
- * model context, so anything rendered for that event is discarded. A caller
- * that consumes state to build the text (draining a mailbox, for instance)
- * must check this first, or the state is spent on output nobody reads.
- */
-export function canReceiveContext(adapter: Adapter, event: SystemEvent): boolean {
-  return !(adapter === "cursor" && event === "UserPromptSubmit");
+export interface StopOutputOptions {
+  /** Existing coordination verdict. Omit when that check passed. */
+  verdict?: { reason?: string; rule: string };
 }
 
 /** Emit a context-injection (peer table, wiring check, council pending, …). */
-export function emitContext(adapter: Adapter, event: SystemEvent, text: string): void {
-  if (!text || text.length === 0) return;
-  if (!canReceiveContext(adapter, event)) return;
+export function emitContext(adapter: Adapter, event: SystemEvent, text: string): boolean {
+  if (!text) return false;
   const json = buildContextJson(adapter, event, text);
   process.stdout.write(`${JSON.stringify(json)}\n`);
+  return true;
 }
 
 /** Emit a PreToolUse deny: blocks the tool call with `reason` shown to the model. */
@@ -83,26 +76,32 @@ export function emitStopBlock(
   adapter: Adapter,
   verdict: { reason?: string; rule: string },
   coordRoot?: string,
+): 0 | 2 {
+  return emitStopOutcome(adapter, { verdict }, coordRoot);
+}
+
+/**
+ * Emit the adapter-specific response for one Stop outcome.
+ */
+export function emitStopOutcome(
+  adapter: Adapter,
+  options: StopOutputOptions,
+  coordRoot?: string,
 ): 0 | 2 {
   if (adapter === "codex") return 0;
 
-  const reason = verdict.reason ?? "End-of-turn coordination ritual incomplete.";
+  const verdict = options.verdict;
+  if (!verdict) return 0;
+
   if (adapter === "cursor") {
-    // The marker leads the message so the Stop verdict can recognize the turn
-    // Cursor opens from it (`STOP_REMEDIATION_MARKER`), and so the operator can
-    // see in chat that the message came from Harnery rather than from them.
-    // Both commands are named because one message that repairs the whole ritual
-    // ends the chain in a single followup; the failing rule is context.
-    const bin = resolveBinName(coordRoot);
-    const statusCommand = endOfTurnStatusCommand(coordRoot);
-    const message = [
-      `${STOP_REMEDIATION_MARKER} rule=${verdict.rule}]`,
-      reason,
-      `Repair the ritual in this turn: run \`${bin} agents set-task "<short focus>"\` and then \`${statusCommand}\` as your last tool call.`,
-    ].join("\n");
-    process.stdout.write(`${JSON.stringify({ followup_message: message })}\n`);
+    process.stdout.write(
+      `${JSON.stringify({ followup_message: cursorCoordinationRemediation(verdict, coordRoot) })}\n`,
+    );
     return 0;
   }
+
+  if (!verdict) return 0;
+  const reason = verdict.reason ?? "End-of-turn coordination ritual incomplete.";
   // Claude Code re-prompts inside one native Stop remediation cycle, but tools
   // run after the first terminal are recorded in recovered telemetry turns.
   // Name the whole ritual so one continuation can repair every required signal.
@@ -113,17 +112,32 @@ export function emitStopBlock(
   return 2;
 }
 
+function cursorCoordinationRemediation(
+  verdict: { reason?: string; rule: string },
+  coordRoot?: string,
+): string {
+  const reason = verdict.reason ?? "End-of-turn coordination ritual incomplete.";
+  // The marker leads the message so the Stop verdict can recognize the turn
+  // Cursor opens from it (`STOP_REMEDIATION_MARKER`), and so the operator can
+  // see in chat that the message came from Harnery rather than from them.
+  // Both commands are named because one message that repairs the whole ritual
+  // ends the chain in a single followup; the failing rule is context.
+  const bin = resolveBinName(coordRoot);
+  const statusCommand = endOfTurnStatusCommand(coordRoot);
+  const message = [
+    `${STOP_REMEDIATION_MARKER} rule=${verdict.rule}]`,
+    reason,
+    `Repair the ritual in this turn: run \`${bin} agents set-task "<short focus>"\` and then \`${statusCommand}\` as your last tool call.`,
+  ].join("\n");
+  return message;
+}
+
 function buildContextJson(
   adapter: Adapter,
   event: SystemEvent,
   text: string,
 ): Record<string, unknown> {
   if (adapter === "cursor") {
-    // Cursor uses a flat top-level key + an env block that survives across the
-    // session. The dispatcher historically also wrote
-    // `env: {HARNERY_AGENT_COORD_ADAPTER, HARNERY_AGENT_COORD_PLATFORM}`. These are
-    // observer hints, not load-bearing; agent-hook + agent-coord recover the
-    // adapter from event metadata. Drop them.
     return { additional_context: text };
   }
   // Claude Code + Codex share the `hookSpecificOutput` envelope.

package/src/core/hooks/backup-schedule.ts

@@ -0,0 +1,147 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseBackupDuration, readHostSnapshotCache } from "../backup/host-snapshot.ts";
+import { backupConfig } from "../config.ts";
+
+/**
+ * Detached runner for the scheduled snapshot. It owns no inherited stdio: a
+ * hook that hands its stderr pipe to a background child keeps the harness
+ * waiting until restic and the remote provider finish, which is the delay the
+ * schedule exists to avoid. Output goes to the log; the exit code goes to the
+ * status file the next session start reads.
+ */
+const RUNNER = `
+harn_bin="$1"
+if_stale="$2"
+log_file="$3"
+status_file="$4"
+shift 4
+stamp() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+if [ -f "$log_file" ] && [ "$(wc -c <"$log_file")" -gt 262144 ]; then
+  tail -c 65536 "$log_file" >"$log_file.rotating" && mv "$log_file.rotating" "$log_file"
+fi
+printf '%s scheduled snapshot start (if-stale %s)\\n' "$(stamp)" "$if_stale" >>"$log_file"
+"$harn_bin" backup snapshot --if-stale "$if_stale" "$@" >>"$log_file" 2>&1
+status=$?
+printf '%s scheduled snapshot exit %s\\n' "$(stamp)" "$status" >>"$log_file"
+printf '{"exit_code":%s,"finished_at":"%s"}\\n' "$status" "$(stamp)" >"$status_file.tmp" && mv "$status_file.tmp" "$status_file"
+exit "$status"
+`.trim();
+
+export interface ScheduledBackupInvocation {
+  harnBin: string;
+  ifStale: string;
+  tags: readonly string[];
+  logFile: string;
+  statusFile: string;
+}
+
+export interface ScheduledBackupStatus {
+  exitCode: number;
+  finishedAt: string;
+}
+
+export interface ScheduledBackupPlan {
+  /** `disabled`: no schedule; `fresh`: local cache proves this host is current; `launch`: run the snapshot. */
+  action: "disabled" | "fresh" | "launch";
+  /** One line for the session context when the previous scheduled run failed. */
+  cue: string | null;
+  invocation: ScheduledBackupInvocation | null;
+}
+
+export function scheduledBackupInvocation(coordRoot: string): ScheduledBackupInvocation | null {
+  const schedule = backupConfig(coordRoot).schedule;
+  if (!schedule) return null;
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+  const logsDir = join(resolve(coordRoot), ".harnery", "logs");
+  return {
+    harnBin: join(packageRoot, "bin", "harn"),
+    ifStale: schedule.ifStale,
+    tags: schedule.tags,
+    logFile: join(logsDir, "backup-schedule.log"),
+    statusFile: join(logsDir, "backup-schedule.status.json"),
+  };
+}
+
+export function readScheduledBackupStatus(statusFile: string): ScheduledBackupStatus | null {
+  if (!existsSync(statusFile)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(statusFile, "utf8")) as {
+      exit_code?: unknown;
+      finished_at?: unknown;
+    };
+    if (typeof parsed.exit_code !== "number" || typeof parsed.finished_at !== "string") {
+      return null;
+    }
+    return { exitCode: parsed.exit_code, finishedAt: parsed.finished_at };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decide what session start should do. The local host cache written by
+ * `harn backup snapshot` is only an optimisation: when it is missing, stale,
+ * or from another host, the launched command still asks restic. A failed
+ * previous run always relaunches so a transient error heals on the next
+ * session instead of waiting out the freshness window.
+ */
+export function planScheduledBackup(coordRoot: string, now = Date.now()): ScheduledBackupPlan {
+  const invocation = scheduledBackupInvocation(coordRoot);
+  if (!invocation) return { action: "disabled", cue: null, invocation: null };
+  const status = readScheduledBackupStatus(invocation.statusFile);
+  const failed = status !== null && status.exitCode !== 0;
+  const cue = failed
+    ? `harnery backup: the last scheduled snapshot failed (exit ${status.exitCode} at ${status.finishedAt}); see ${invocation.logFile}. Fix the cause or run \`harn backup snapshot --if-stale ${invocation.ifStale}\` to retry.`
+    : null;
+  const staleMs = parseBackupDuration(invocation.ifStale);
+  const cache = readHostSnapshotCache(join(resolve(coordRoot), ".harnery"));
+  const fresh =
+    !failed &&
+    staleMs !== null &&
+    cache !== null &&
+    cache.host === hostname() &&
+    now - cache.snapshotAt < staleMs;
+  return { action: fresh ? "fresh" : "launch", cue, invocation };
+}
+
+/** Launch the configured SessionStart snapshot without extending hook latency. */
+export function scheduleBackupSnapshot(coordRoot: string): {
+  launched: boolean;
+  cue: string | null;
+} {
+  const plan = planScheduledBackup(coordRoot);
+  if (plan.cue) process.stderr.write(`${plan.cue}\n`);
+  if (plan.action !== "launch" || !plan.invocation) return { launched: false, cue: plan.cue };
+  const invocation = plan.invocation;
+  mkdirSync(dirname(invocation.logFile), { recursive: true });
+  const tagArgs = invocation.tags.flatMap((tag) => ["--tag", tag]);
+  const child = spawn(
+    "bash",
+    [
+      "-c",
+      RUNNER,
+      "harnery-backup",
+      invocation.harnBin,
+      invocation.ifStale,
+      invocation.logFile,
+      invocation.statusFile,
+      ...tagArgs,
+    ],
+    {
+      cwd: resolve(coordRoot),
+      detached: true,
+      stdio: "ignore",
+    },
+  );
+  child.once("error", () => {
+    process.stderr.write(
+      `harnery backup: scheduled snapshot could not start; see ${invocation.logFile}\n`,
+    );
+  });
+  child.unref();
+  return { launched: true, cue: plan.cue };
+}

package/src/core/hooks/cli.ts

@@ -56,7 +56,12 @@ import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.
 import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.ts";
 import { assignName } from "../agents/state/names.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
-import { agentsRequireGitFinalization, resolveBinName } from "../config.ts";
+import {
+  agentsRequireGitFinalization,
+  coordFreshnessSeconds,
+  hostPromptContextConfig,
+  resolveBinName,
+} from "../config.ts";
 import {
   checkpointContext,
   completeContextRecovery,
@@ -89,6 +94,7 @@ import {
   parsePayload,
 } from "./adapter/parse.ts";
 import { discoverCodexSessionTranscript } from "./adapter/runtime-telemetry.ts";
+import { scheduleBackupSnapshot } from "./backup-schedule.ts";
 import {
   codexWslFileLinkTelemetry,
   inspectCodexWslBridge,
@@ -246,7 +252,10 @@ function assignNameInProcess(
   forkedFrom?: string,
 ): { name: string; kind: string } | null {
   try {
-    const name = assignName(coordRoot, instanceId, kind, forkedFrom ? { forkedFrom } : undefined);
+    const name = assignName(coordRoot, instanceId, kind, {
+      freshnessSecs: coordFreshnessSeconds(coordRoot),
+      ...(forkedFrom ? { forkedFrom } : {}),
+    });
     return { name, kind };
   } catch {
     return null;
@@ -834,6 +843,11 @@ async function main(): Promise<number> {
 
   const sessionId = payload?.session_id ?? payload?.conversation_id ?? owner.instance_id;
   const priorCoordination = readHeartbeat(coordRoot, owner.instance_id);
+  const topLevelSession =
+    coordEnv("WORKFLOW_CHILD") !== "1" &&
+    priorCoordination?.kind !== "subagent" &&
+    priorCoordination?.kind !== "transient" &&
+    !priorCoordination?.workflow_run_id;
   if (
     norm.event_type !== "session.ended" &&
     coordEnv("WORKFLOW_CHILD") !== "1" &&
@@ -1074,6 +1088,16 @@ async function main(): Promise<number> {
   // Adapter-agnostic since v0.5.0; replaces the previous bash UX layer
   // and the equivalent per-adapter bash session_start handlers.
   if (norm.event_type === "session.started") {
+    // A configured backup runs out of process and is freshness-gated per host.
+    // Startup never waits for restic or a remote provider; the child owns no
+    // hook stdio, so the harness is not held open until it finishes. A failed
+    // previous run surfaces as one line in this session's context.
+    let backupCue = "";
+    try {
+      backupCue = scheduleBackupSnapshot(coordRoot).cue ?? "";
+    } catch (err) {
+      logError(coordRoot, err, { phase: "backup-schedule" });
+    }
     // Effect (claude-code): prune stale journal archives + sweep orphans.
     // The recovery-cue is merged into the
     // session-start additionalContext inside emitSessionStartSystemMessage.
@@ -1141,6 +1165,7 @@ async function main(): Promise<number> {
         data,
         adapter,
         recovery?.briefing ?? "",
+        backupCue,
       );
       if (injected && recovery) {
         completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
@@ -1240,6 +1265,29 @@ async function main(): Promise<number> {
         logError(coordRoot, err, { phase: "context-recovery-user-prompt" });
       }
     }
+    let hostPromptContext = "";
+    const hostPromptEnabled = hostPromptContextConfig(coordRoot)?.enabled === true;
+    if (hostPromptEnabled && topLevelSession && !stopRemediation) {
+      try {
+        const { runPromptContext } = await import("./prompt-context/runner.ts");
+        const result = await runPromptContext({
+          coordRoot,
+          adapter,
+          sessionId,
+          turnId: payload?.turn_id ?? v3EventId ?? sessionId,
+          cwd: payload?.cwd ?? process.cwd(),
+          prompt: payload?.prompt ?? "",
+        });
+        appendDebug(coordRoot, {
+          ...debugBase,
+          effect: "prompt-context",
+          ...result.audit,
+        });
+        hostPromptContext = result.context ?? "";
+      } catch (err) {
+        logError(coordRoot, err, { phase: "prompt-context-user-prompt" });
+      }
+    }
     try {
       const injected = await emitUserPromptSubmitSystemMessage(
         coordRoot,
@@ -1248,6 +1296,7 @@ async function main(): Promise<number> {
         adapter,
         payload?.cwd,
         recovery?.briefing ?? "",
+        hostPromptContext,
       );
       if (injected && recovery) {
         completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
@@ -1311,10 +1360,9 @@ async function main(): Promise<number> {
       } else {
         // Adapter-aware enforcement channel: Claude Code honors exit-2 + stderr
         // as a turn block; Cursor ignores exit codes and re-prompts only via a
-        // `followup_message` it auto-submits. Codex returned observe-only above.
-        // emitStopBlock writes the right shape and returns the exit code to use.
-        const { emitStopBlock } = await import("./adapter/output.ts");
-        return emitStopBlock(adapter, verdict, coordRoot);
+        // `followup_message` it auto-submits.
+        const { emitStopOutcome } = await import("./adapter/output.ts");
+        return emitStopOutcome(adapter, { verdict }, coordRoot);
       }
     } else {
       const { clearRemediationCount } = await import("./remediation-cap.ts");
@@ -1906,16 +1954,16 @@ async function emitUserPromptSubmitSystemMessage(
   adapter: Adapter,
   workspaceCwd?: string,
   recoveryBriefing = "",
+  hostPromptContext = "",
 ): Promise<boolean> {
   const { renderPromptContext } = await import("../agents/render/prompt-context.ts");
   let additionalContext = renderPromptContext({
     coordRoot,
     instanceId,
     sessionId,
-    adapter,
     sessionNameNudge: true,
     taskNudge: adapter === "cursor" || adapter === "codex",
-    hostPromptReminder: adapter === "codex",
+    hostPromptReminder: adapter === "codex" || adapter === "cursor",
     statusFooterNudge: adapter === "codex",
     turnRitualNudge: adapter === "claude-code" ? adapter : undefined,
   }).trim();
@@ -1928,11 +1976,13 @@ async function emitUserPromptSubmitSystemMessage(
   if (recoveryBriefing) {
     additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
   }
+  if (hostPromptContext) {
+    additionalContext = [additionalContext, hostPromptContext].filter(Boolean).join("\n\n");
+  }
   if (!additionalContext) return false;
 
   const { emitContext } = await import("./adapter/output.ts");
-  emitContext(adapter, "UserPromptSubmit", additionalContext);
-  return true;
+  return emitContext(adapter, "UserPromptSubmit", additionalContext);
 }
 
 async function emitSubagentStartContext(
@@ -1989,6 +2039,7 @@ async function emitSessionStartSystemMessage(
   emittedData: Record<string, unknown>,
   adapter: Adapter,
   recoveryBriefing = "",
+  backupCue = "",
 ): Promise<boolean> {
   const workflowChild = coordEnv("WORKFLOW_CHILD") === "1";
   let additionalContext = "";
@@ -2026,6 +2077,9 @@ async function emitSessionStartSystemMessage(
   if (recoveryBriefing && !workflowChild) {
     additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
   }
+  if (backupCue && !workflowChild) {
+    additionalContext = [additionalContext, backupCue].filter(Boolean).join("\n\n");
+  }
   if (adapter === "codex" && !workflowChild && isWslUncPath(emittedData.cwd)) {
     const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, emittedData.cwd);
     if (fileLinkContext) {
@@ -2041,11 +2095,8 @@ async function emitSessionStartSystemMessage(
         .join("\n\n");
     }
   }
-  if (!additionalContext) return false;
-
   const { emitContext } = await import("./adapter/output.ts");
-  emitContext(adapter, "SessionStart", additionalContext);
-  return true;
+  return emitContext(adapter, "SessionStart", additionalContext);
 }
 
 function completeRecoveryInjection(

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

@@ -71,10 +71,7 @@ export function codexWslWorkspaceLinkMapping(
   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;
-  }
+  if (!codexWslWorkspaceLinuxPath(coordRootRaw, workspaceCwd)) return null;
   return {
     linuxRoot,
     hostRoot: `//${parsed.host}/${parsed.distro}${linuxRoot}`,
@@ -82,6 +79,21 @@ export function codexWslWorkspaceLinkMapping(
   };
 }
 
+/** Translate an overlapping WSL UNC workspace into its Linux-native path. */
+export function codexWslWorkspaceLinuxPath(
+  coordRootRaw: string,
+  workspaceCwd: unknown,
+): string | 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 linuxCwd;
+}
+
 /** 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 {
@@ -90,7 +102,11 @@ export function renderCodexWslFileLinkContext(coordRoot: string, workspaceCwd: u
   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>)\`. ` +
+    `Example: \`[label](${mapping.hostRoot}/path/to/file)\`. ` +
+    "Percent-encode a space as %20 and a parenthesis as %28 or %29 in the link, " +
+    "and do not wrap the destination in angle brackets: that form is valid " +
+    "Markdown but some renderers style it as a link without keeping the target, " +
+    "so it looks clickable and does nothing. " +
     "Keep Linux paths unchanged in shell commands and tool inputs."
   );
 }

package/src/core/hooks/index.ts

@@ -7,3 +7,4 @@
 export type { Adapter } from "../adapter.ts";
 export type { EventV3 as Event } from "../events/v3/contract.ts";
 export { EventV3Schema } from "../events/v3/contract.ts";
+export * from "./prompt-context/index.ts";