harnery 0.36.0 → 0.37.0

package/src/lib/coord-root-id.ts

@@ -0,0 +1,23 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { DEFAULT_WEB_PORT } from "./local-file-url.ts";
+
+/** Local-only endpoint used to prove that a dashboard serves the caller's repo. */
+export const COORD_ROOT_ID_PATH = "/api/coord-root";
+
+/**
+ * Opaque identity for a canonical coordination root. The path stays local;
+ * only its digest crosses the dashboard boundary.
+ */
+export function coordRootId(root: string): string {
+  const canonical = realpathSync(root);
+  return `sha256:${createHash("sha256").update(canonical).digest("hex")}`;
+}
+
+export function localCoordRootIdUrl(
+  port: number | string = DEFAULT_WEB_PORT,
+  protocol = "http:",
+): string {
+  const portPart = String(port) === "" ? "" : `:${port}`;
+  return `${protocol}//127.0.0.1${portPart}${COORD_ROOT_ID_PATH}`;
+}

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.