harnery 0.35.0 → 0.37.0

package/src/lib/http/client.ts

@@ -11,7 +11,9 @@ import type { Cookie, CookieJar } from "../cookies/index.ts";
  * state with `browse`.
  */
 
-export interface FetchOptions {
+export type FetchResponseType = "text" | "bytes";
+
+export interface FetchOptions<TResponseType extends FetchResponseType = "text"> {
   /** HTTP method. Default GET. */
   method?: string;
   /** Request body. Strings/Buffers/Streams pass through to fetch directly. */
@@ -37,14 +39,20 @@ export interface FetchOptions {
    * only land when the key isn't already set.
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /** Response body representation. Default `text`; use `bytes` for lossless file output. */
+  responseType?: TResponseType;
 }
 
-export interface FetchResult {
+type FetchBody<TResponseType extends FetchResponseType> = TResponseType extends "bytes"
+  ? Uint8Array
+  : string;
+
+export interface FetchResult<TBody = string> {
   status: number;
   statusText: string;
   url: string;
   headers: Record<string, string>;
-  body: string;
+  body: TBody;
   /** Number of cookies persisted back into the jar (0 if no jar passed). */
   cookiesSaved: number;
 }
@@ -52,11 +60,15 @@ export interface FetchResult {
 /**
  * Fetch a URL with optional cookie-jar attach + persist.
  *
- * Returns the response body as a string (callers handle JSON parsing).
+ * Returns the response body as text by default (callers handle JSON parsing).
+ * Pass `responseType: "bytes"` when the caller must preserve the body exactly.
  * Streams aren't supported; this is a CLI helper, not a streaming HTTP
  * client. Use Bun's `fetch` directly for streaming workloads.
  */
-export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promise<FetchResult> {
+export async function fetchWithJar<TResponseType extends FetchResponseType = "text">(
+  url: string,
+  opts: FetchOptions<TResponseType> = {},
+): Promise<FetchResult<FetchBody<TResponseType>>> {
   const headers: Record<string, string> = { ...(opts.headers ?? {}) };
 
   if (opts.jar) {
@@ -74,13 +86,32 @@ export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promis
     }
   }
 
-  const response = await fetch(url, {
+  // Byte mode is a download boundary, so keep the HTTP representation bytes
+  // aligned with the response headers. Bun otherwise decompresses the body
+  // while retaining Content-Encoding and the encoded Content-Length.
+  if (opts.responseType === "bytes" && !headers["Accept-Encoding"] && !headers["accept-encoding"]) {
+    headers["Accept-Encoding"] = "identity";
+  }
+  const fetchInit: RequestInit & { decompress?: boolean } = {
     method: opts.method ?? "GET",
     body: opts.body,
     headers,
     redirect: opts.redirect ?? "follow",
     signal: opts.signal,
-  });
+  };
+  if (opts.responseType === "bytes") fetchInit.decompress = false;
+
+  const response = await fetch(url, fetchInit);
+
+  if (
+    opts.responseType === "bytes" &&
+    typeof Bun === "undefined" &&
+    response.headers.has("content-encoding")
+  ) {
+    throw new Error(
+      "cannot preserve a content-encoded response under the Node fallback; install Bun or request identity encoding",
+    );
+  }
 
   let cookiesSaved = 0;
   if (opts.jar) {
@@ -102,12 +133,17 @@ export async function fetchWithJar(url: string, opts: FetchOptions = {}): Promis
     headerObj[key] = value;
   });
 
+  const body =
+    opts.responseType === "bytes"
+      ? new Uint8Array(await response.arrayBuffer())
+      : await response.text();
+
   return {
     status: response.status,
     statusText: response.statusText,
     url: response.url,
     headers: headerObj,
-    body: await response.text(),
+    body: body as FetchBody<TResponseType>,
     cookiesSaved,
   };
 }

package/src/lib/http/index.ts

@@ -1,2 +1,7 @@
-export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+export {
+  type FetchOptions,
+  type FetchResponseType,
+  type FetchResult,
+  fetchWithJar,
+} from "./client.js";
 export * from "./request.ts";

package/src/lib/indexer-exclusions.ts

@@ -0,0 +1,173 @@
+/**
+ * Editor-indexer exclusions for the `.harnery/` coord root.
+ *
+ * `harn init` already writes `.harnery/.gitignore`, which keeps git-aware
+ * tools out of runtime state. Two high-traffic editor surfaces ignore
+ * gitignore, though: Cursor's codebase indexer (governed by a repo-root
+ * `.cursorindexingignore`) and the VS Code/Cursor file watcher (governed by
+ * `files.watcherExclude` in `.vscode/settings.json`). A busy coord root holds
+ * tens of thousands of ledger events plus working artifacts, so on
+ * session-heavy hosts the missing exclusions turn editor startup into an
+ * indexing storm over machine-local state no editor needs to see.
+ *
+ * `applyIndexerExclusions` is idempotent and non-destructive: it appends a
+ * managed entry to `.cursorindexingignore` (or creates the file) and merges a
+ * single key into `.vscode/settings.json` (or creates it). A settings file it
+ * cannot merge safely (comments, malformed JSON, or a non-object
+ * `files.watcherExclude`) is left byte-identical and reported as a manual
+ * step. `removeIndexerExclusions` reverses exactly what apply wrote: it never
+ * removes a `.harnery/` ignore entry the consumer added themselves (detected
+ * by the absence of the managed comment) and never edits a settings file it
+ * could not have written into.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const CURSOR_IGNORE = ".cursorindexingignore";
+const MANAGED_COMMENT =
+  "# .harnery/ is machine-local harnery runtime state (entry managed by init)";
+const MANAGED_ENTRY = ".harnery/";
+const VSCODE_DIR = ".vscode";
+const VSCODE_SETTINGS = ".vscode/settings.json";
+const WATCHER_KEY = "files.watcherExclude";
+const WATCHER_GLOB = "**/.harnery/**";
+
+/** True when a `.cursorindexingignore` line already excludes the coord root. */
+function coversCoordRoot(line: string): boolean {
+  const t = line.trim();
+  return (
+    t === ".harnery" ||
+    t === ".harnery/" ||
+    t === "/.harnery" ||
+    t === "/.harnery/" ||
+    t === ".harnery/**" ||
+    t === "/.harnery/**"
+  );
+}
+
+function applyCursorIgnore(projectRoot: string, dryRun: boolean): string {
+  const path = resolve(projectRoot, CURSOR_IGNORE);
+  if (existsSync(path)) {
+    const raw = readFileSync(path, "utf8");
+    if (raw.split("\n").some(coversCoordRoot)) {
+      return `· ${CURSOR_IGNORE} already excludes .harnery/`;
+    }
+    if (dryRun) return `+ would append .harnery/ to ${CURSOR_IGNORE}`;
+    const sep = raw === "" || raw.endsWith("\n") ? "" : "\n";
+    writeFileSync(path, `${raw}${sep}${MANAGED_COMMENT}\n${MANAGED_ENTRY}\n`);
+    return `+ appended .harnery/ to ${CURSOR_IGNORE}`;
+  }
+  if (dryRun) return `+ would create ${CURSOR_IGNORE} (excludes .harnery/ from Cursor indexing)`;
+  writeFileSync(path, `${MANAGED_COMMENT}\n${MANAGED_ENTRY}\n`);
+  return `+ created ${CURSOR_IGNORE} (excludes .harnery/ from Cursor indexing)`;
+}
+
+function applyVscodeWatcherExclude(projectRoot: string, dryRun: boolean): string {
+  const path = resolve(projectRoot, VSCODE_SETTINGS);
+  if (!existsSync(path)) {
+    if (dryRun) return `+ would create ${VSCODE_SETTINGS} (file watcher excludes .harnery/)`;
+    mkdirSync(resolve(projectRoot, VSCODE_DIR), { recursive: true });
+    const body = JSON.stringify({ [WATCHER_KEY]: { [WATCHER_GLOB]: true } }, null, 2);
+    writeFileSync(path, `${body}\n`);
+    return `+ created ${VSCODE_SETTINGS} (file watcher excludes .harnery/)`;
+  }
+  const raw = readFileSync(path, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // JSONC (comments, trailing commas) or malformed. A rewrite would drop the
+    // consumer's comments, so leave the file alone and name the one-key merge.
+    return `! ${VSCODE_SETTINGS} is not plain JSON; add "${WATCHER_KEY}": {"${WATCHER_GLOB}": true} manually`;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return `! ${VSCODE_SETTINGS} is not a settings object; add "${WATCHER_KEY}": {"${WATCHER_GLOB}": true} manually`;
+  }
+  const settings = parsed as Record<string, unknown>;
+  const watcher = settings[WATCHER_KEY];
+  if (
+    watcher !== undefined &&
+    (typeof watcher !== "object" || watcher === null || Array.isArray(watcher))
+  ) {
+    return `! ${VSCODE_SETTINGS} has a non-object "${WATCHER_KEY}"; add "${WATCHER_GLOB}": true manually`;
+  }
+  const map = (watcher as Record<string, unknown> | undefined) ?? {};
+  if (map[WATCHER_GLOB] === true) {
+    return `· ${VSCODE_SETTINGS} file watcher already excludes .harnery/`;
+  }
+  if (dryRun) return `+ would add ${WATCHER_GLOB} to ${WATCHER_KEY} in ${VSCODE_SETTINGS}`;
+  map[WATCHER_GLOB] = true;
+  settings[WATCHER_KEY] = map;
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+  return `+ added ${WATCHER_GLOB} to ${WATCHER_KEY} in ${VSCODE_SETTINGS}`;
+}
+
+function removeCursorIgnore(projectRoot: string, dryRun: boolean): string | null {
+  const path = resolve(projectRoot, CURSOR_IGNORE);
+  if (!existsSync(path)) return null;
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+  // Only the managed pair is ours. A bare `.harnery/` line without the managed
+  // comment is a consumer's own entry and stays.
+  if (!lines.some((line) => line.trim() === MANAGED_COMMENT)) return null;
+  if (dryRun) return `+ would remove the managed .harnery/ entry from ${CURSOR_IGNORE}`;
+  const kept = lines.filter((line) => {
+    const t = line.trim();
+    return t !== MANAGED_COMMENT && t !== MANAGED_ENTRY;
+  });
+  if (kept.every((line) => line.trim() === "")) {
+    rmSync(path);
+    return `+ removed ${CURSOR_IGNORE} (was harnery-only)`;
+  }
+  let out = kept.join("\n");
+  if (!out.endsWith("\n")) out += "\n";
+  writeFileSync(path, out);
+  return `+ removed the managed .harnery/ entry from ${CURSOR_IGNORE}`;
+}
+
+function removeVscodeWatcherExclude(projectRoot: string, dryRun: boolean): string | null {
+  const path = resolve(projectRoot, VSCODE_SETTINGS);
+  if (!existsSync(path)) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    // Not plain JSON, so apply never wrote into it.
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  const settings = parsed as Record<string, unknown>;
+  const watcher = settings[WATCHER_KEY];
+  if (typeof watcher !== "object" || watcher === null || Array.isArray(watcher)) return null;
+  const map = watcher as Record<string, unknown>;
+  if (!(WATCHER_GLOB in map)) return null;
+  if (dryRun) return `+ would remove ${WATCHER_GLOB} from ${VSCODE_SETTINGS}`;
+  delete map[WATCHER_GLOB];
+  if (Object.keys(map).length === 0) delete settings[WATCHER_KEY];
+  if (Object.keys(settings).length === 0) {
+    rmSync(path);
+    try {
+      // Drop the .vscode/ directory too when the settings file was all it held.
+      rmdirSync(resolve(projectRoot, VSCODE_DIR));
+    } catch {
+      // Non-empty or shared; leave it.
+    }
+    return `+ removed ${VSCODE_SETTINGS} (was harnery-only)`;
+  }
+  writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`);
+  return `+ removed ${WATCHER_GLOB} from ${VSCODE_SETTINGS}`;
+}
+
+/** Ensure both editor exclusions exist. Returns init-style action lines. */
+export function applyIndexerExclusions(projectRoot: string, dryRun: boolean): string[] {
+  return [applyCursorIgnore(projectRoot, dryRun), applyVscodeWatcherExclude(projectRoot, dryRun)];
+}
+
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export function removeIndexerExclusions(projectRoot: string, dryRun: boolean): string[] {
+  return [
+    removeCursorIgnore(projectRoot, dryRun),
+    removeVscodeWatcherExclude(projectRoot, dryRun),
+  ].filter((line): line is string => line !== null);
+}

package/src/lib/instructions/apply.ts

@@ -7,13 +7,15 @@
  * writes, and deletes so init/deinit stay thin and this stays integration-
  * testable against a temp dir.
  *
- * Two files, one dir:
+ * Three files, one dir:
  *   - `AGENTS.md` — the always-on orientation block (a managed region; the
  *     consumer owns the rest of the file).
  *   - `CLAUDE.md` — claude-code only; Claude Code reads CLAUDE.md, not AGENTS.md,
  *     so a fresh consumer gets a CLAUDE.md whose managed region imports
  *     `@AGENTS.md`. A CLAUDE.md that already imports AGENTS.md or already carries
  *     the block (a host that generates CLAUDE.md from AGENTS.md) is left alone.
+ *   - `.cursor/rules/harnery-turn-ritual.mdc` — cursor only; an Always Apply
+ *     rule that makes the Stop-enforced status footer visible in reply text.
  *   - `<adapter-skill-dir>/<skill>/SKILL.md` — fully-owned files, honoring
  *     `skills.exclude` in `.harnery/config.jsonc`. Claude Code uses
  *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.
@@ -29,7 +31,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { stripJsonComments } from "../../core/config.ts";
+import { endOfTurnStatusCommand, stripJsonComments } from "../../core/config.ts";
 import { readHostAddendum } from "./host-addendum.ts";
 import {
   checkOwnedSkill,
@@ -37,6 +39,7 @@ import {
   isOwnedFile,
   type ManagedStatus,
   removeRegion,
+  shortHash,
   spliceRegion,
 } from "./splice.ts";
 import {
@@ -50,6 +53,7 @@ import {
 
 const AGENTS_FILE = "AGENTS.md";
 const CLAUDE_FILE = "CLAUDE.md";
+const CURSOR_RULE_FILE = join(".cursor", "rules", "harnery-turn-ritual.mdc");
 const ADAPTER_SKILLS_DIR: Readonly<Record<string, string>> = {
   "claude-code": join(".claude", "skills"),
   cursor: join(".agents", "skills"),
@@ -71,6 +75,39 @@ function skillBody(render: (bin: string) => string, binName: string): string {
   return content.slice(content.indexOf("-->") + 3).trim();
 }
 
+function cursorRuleBody(projectRoot: string, binName: string): string {
+  const statusCommand = endOfTurnStatusCommand(projectRoot);
+  return [
+    "# Harnery turn ritual",
+    "",
+    "On every turn that uses tools:",
+    "",
+    `1. Run \`${binName} agents set-task "<short focus>"\` during the turn, even when the focus is unchanged.`,
+    `2. Make \`${statusCommand}\` your final tool call.`,
+    "3. Append that command's stdout verbatim in a fenced code block at the bottom of the same substantive reply.",
+    "",
+    "Cursor Stop enforces all three signals. A missing signal produces one follow-up that names every repair needed.",
+  ].join("\n");
+}
+
+function cursorRuleContent(projectRoot: string, binName: string): string {
+  const body = cursorRuleBody(projectRoot, binName);
+  const marker =
+    `<!-- harnery:generated cursor-turn-ritual v=${shortHash(body)}; machine-owned; ` +
+    `regenerated by \`${binName} init\`, removed by \`${binName} deinit\`. ` +
+    "Edit the harnery template, not this file. -->";
+  return [
+    "---",
+    "description: Harnery end-of-turn coordination ritual",
+    "alwaysApply: true",
+    "---",
+    marker,
+    "",
+    body,
+    "",
+  ].join("\n");
+}
+
 /** Read `skills.exclude` from `.harnery/config.jsonc` (absent/unparseable → none). */
 export function readSkillsExclude(projectRoot: string): Set<string> {
   const p = join(projectRoot, ".harnery", "config.jsonc");
@@ -203,6 +240,27 @@ export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyRe
     }
   }
 
+  // ── Cursor Always Apply rule ────────────────────────────────────────────
+  if (opts.adapter === "cursor") {
+    const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+    const content = cursorRuleContent(projectRoot, opts.binName);
+    const before = existsSync(rulePath) ? readFileSync(rulePath, "utf8") : null;
+    if (before === content) {
+      actions.push(`· ${CURSOR_RULE_FILE} already current`);
+    } else if (before !== null && !isOwnedFile(before)) {
+      warnings.push(`left ${CURSOR_RULE_FILE} (hand-edited; no harnery ownership marker)`);
+    } else {
+      if (!opts.dryRun) {
+        mkdirSync(dirname(rulePath), { recursive: true });
+        writeFileSync(rulePath, content);
+      }
+      const fresh = before === null;
+      actions.push(
+        `${fresh ? "+" : "~"} ${verbed(fresh ? "write" : "update", fresh ? "wrote" : "updated")} ${CURSOR_RULE_FILE}`,
+      );
+    }
+  }
+
   // ── shipped skills ───────────────────────────────────────────────────────
   if (skillsDir) {
     const exclude = readSkillsExclude(projectRoot);
@@ -301,6 +359,18 @@ export function removeInstructions(projectRoot: string, opts: RemoveOpts): Apply
     }
   }
 
+  if (opts.adapter === "cursor") {
+    const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+    if (existsSync(rulePath)) {
+      if (!isOwnedFile(readFileSync(rulePath, "utf8"))) {
+        warnings.push(`left ${CURSOR_RULE_FILE} (hand-edited; no harnery ownership marker)`);
+      } else {
+        if (!opts.dryRun) rmSync(rulePath);
+        actions.push(`+ ${opts.dryRun ? "would delete" : "deleted"} ${CURSOR_RULE_FILE}`);
+      }
+    }
+  }
+
   // ── shipped skills ───────────────────────────────────────────────────────
   if (skillsDir) {
     for (const skill of SKILLS) {
@@ -384,6 +454,15 @@ export function checkInstructions(
         note(`skill ${skill.id}`, checkOwnedSkill(c, skillBody(skill.render, opts.binName)));
       }
     }
+
+    if (opts.adapter === "cursor") {
+      const rulePath = join(projectRoot, CURSOR_RULE_FILE);
+      const content = existsSync(rulePath) ? readFileSync(rulePath, "utf8") : "";
+      note(
+        `${CURSOR_RULE_FILE} rule`,
+        checkOwnedSkill(content, cursorRuleBody(projectRoot, opts.binName)),
+      );
+    }
   } catch (err) {
     errored = true;
     issues.push(`error reading instructions state: ${(err as Error).message}`);

package/src/lib/instructions/templates.ts

@@ -135,6 +135,12 @@ coordination ledger (\`.harnery/ledgers/v3/\`). Lead a shell command with a
 carries a reason instead of \`(no intent)\`; the [tool-intent
 guide](https://harnery.com/guides/tool-intent/) owns the details.
 
+**Messaging another agent.** \`${b} agents ping <name> "<message>"\` reaches an
+agent by name whether or not they are running: a live agent sees it on their next
+prompt, and a dormant name holds it until a session of that name next starts.
+Send it as your first and only step. Do not check who is live first, and do not
+hunt for somewhere else to leave it. Only a never-used name is refused.
+
 **Journal.** \`${b} journal add <category> "<text>"\` (category = ${journalCats})
 leaves breadcrumbs that survive context compaction;
 \`${b} journal read\` reads yours, \`${b} journal read --name <peer>\` reads a peer's.
@@ -147,6 +153,11 @@ returned path, then run \`${b} artifacts release <id>\` when active work is done
 Do not create a repo-root temp directory; \`${b} artifacts clean\` previews
 expired cleanup and requires \`--yes\` to delete anything.
 
+**Local file links.** When the operator should open a local repo file, mint the
+URL with \`${b} files url <repo-relative-path>\` instead of guessing it. HTML opens
+as a real page with working scripts and relative assets; other files open in the
+dashboard viewer. Use localhost links only when the operator shares this machine.
+
 **Decision docket.** When you would otherwise stop to ask a human a decision you
 can't resolve from the repo, file it instead. \`${b} decision file "<question>"\`
 records it and lets you proceed on a stated default; \`${b} decision search "<terms>"\`

package/src/lib/local-file-url.ts

@@ -0,0 +1,31 @@
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export const DEFAULT_WEB_PORT = 4276;
+
+/** Cookie-isolated host for navigable repo files. */
+export const FILES_ORIGIN_HOST = "harnery-files.localhost";
+
+/** Encode each repo-path segment while preserving slash-based URL resolution. */
+export function encodedRepoPath(relPath: string): string {
+  return relPath
+    .replace(/^\/+/, "")
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function localFilesOriginUrl(
+  relPath: string,
+  port: number | string = DEFAULT_WEB_PORT,
+  protocol = "http:",
+): string {
+  const portPart = String(port) === "" ? "" : `:${port}`;
+  return `${protocol}//${FILES_ORIGIN_HOST}${portPart}/${encodedRepoPath(relPath)}`;
+}
+
+export function localFileViewerUrl(
+  relPath: string,
+  port: number | string = DEFAULT_WEB_PORT,
+): string {
+  return `http://localhost:${port}/files?path=${encodeURIComponent(relPath)}`;
+}