harnery 0.35.0 → 0.37.0

package/dist/lib/http/client.d.ts

@@ -9,7 +9,8 @@ import type { CookieJar } from "../cookies/index.js";
  * Used by the `fetch` command and other tooling that wants to share session
  * 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. */
@@ -35,22 +36,27 @@ 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;
 }
 /**
  * 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 declare function fetchWithJar(url: string, opts?: FetchOptions): Promise<FetchResult>;
+export declare function fetchWithJar<TResponseType extends FetchResponseType = "text">(url: string, opts?: FetchOptions<TResponseType>): Promise<FetchResult<FetchBody<TResponseType>>>;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/http/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsD7F"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM;IAC5E,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,0FAA0F;IAC1F,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,KAAK,SAAS,CAAC,aAAa,SAAS,iBAAiB,IAAI,aAAa,SAAS,OAAO,GACnF,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM,EACjF,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAY,CAAC,aAAa,CAAM,GACrC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CA8EhD"}

package/dist/lib/http/client.js

@@ -1,7 +1,8 @@
 /**
  * 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.
  */
@@ -21,13 +22,27 @@ export async function fetchWithJar(url, opts = {}) {
                 headers[k] = v;
         }
     }
-    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 = {
         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) {
         const setCookieHeaders = collectSetCookie(response.headers);
@@ -46,12 +61,15 @@ export async function fetchWithJar(url, opts = {}) {
     response.headers.forEach((value, key) => {
         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,
         cookiesSaved,
     };
 }

package/dist/lib/http/index.d.ts

@@ -1,3 +1,3 @@
-export { type FetchOptions, type FetchResult, fetchWithJar } from "./client.js";
+export { type FetchOptions, type FetchResponseType, type FetchResult, fetchWithJar, } from "./client.js";
 export * from "./request.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/http/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChF,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/http/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,cAAc,cAAc,CAAC"}

package/dist/lib/http/index.js

@@ -1,2 +1,2 @@
-export { fetchWithJar } from "./client.js";
+export { fetchWithJar, } from "./client.js";
 export * from "./request.js";

package/dist/lib/indexer-exclusions.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/** Ensure both editor exclusions exist. Returns init-style action lines. */
+export declare function applyIndexerExclusions(projectRoot: string, dryRun: boolean): string[];
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export declare function removeIndexerExclusions(projectRoot: string, dryRun: boolean): string[];
+//# sourceMappingURL=indexer-exclusions.d.ts.map

package/dist/lib/indexer-exclusions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer-exclusions.d.ts","sourceRoot":"","sources":["../../src/lib/indexer-exclusions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA4IH,4EAA4E;AAC5E,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAErF;AAED,2FAA2F;AAC3F,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,CAKtF"}

package/dist/lib/indexer-exclusions.js

@@ -0,0 +1,176 @@
+/**
+ * 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) {
+    const t = line.trim();
+    return (t === ".harnery" ||
+        t === ".harnery/" ||
+        t === "/.harnery" ||
+        t === "/.harnery/" ||
+        t === ".harnery/**" ||
+        t === "/.harnery/**");
+}
+function applyCursorIgnore(projectRoot, dryRun) {
+    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, dryRun) {
+    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;
+    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;
+    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 ?? {};
+    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, dryRun) {
+    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, dryRun) {
+    const path = resolve(projectRoot, VSCODE_SETTINGS);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    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;
+    const watcher = settings[WATCHER_KEY];
+    if (typeof watcher !== "object" || watcher === null || Array.isArray(watcher))
+        return null;
+    const map = watcher;
+    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, dryRun) {
+    return [applyCursorIgnore(projectRoot, dryRun), applyVscodeWatcherExclude(projectRoot, dryRun)];
+}
+/** Reverse exactly what apply wrote. Returns action lines; silent when nothing is ours. */
+export function removeIndexerExclusions(projectRoot, dryRun) {
+    return [
+        removeCursorIgnore(projectRoot, dryRun),
+        removeVscodeWatcherExclude(projectRoot, dryRun),
+    ].filter((line) => line !== null);
+}

package/dist/lib/instructions/apply.d.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/`.

package/dist/lib/instructions/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsDH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAmBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CA+GnF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CAkFrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CAkDb"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAyFH,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAYlE;AAmBD,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CAoInF;AAED,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,CA8FrF;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzC,WAAW,CA2Db"}

package/dist/lib/instructions/apply.js

@@ -7,25 +7,28 @@
  * 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/`.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmdirSync, rmSync, writeFileSync, } from "node:fs";
 import { dirname, join } from "node:path";
-import { stripJsonComments } from "../../core/config.js";
+import { endOfTurnStatusCommand, stripJsonComments } from "../../core/config.js";
 import { readHostAddendum } from "./host-addendum.js";
-import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, spliceRegion, } from "./splice.js";
+import { checkOwnedSkill, checkRegion, isOwnedFile, removeRegion, shortHash, spliceRegion, } from "./splice.js";
 import { HOST_ADDENDUM_REGION, IMPORT_REGION, INSTRUCTIONS_REGION, renderInstructionsBlock, SKILLS, } from "./templates.js";
 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 = {
     "claude-code": join(".claude", "skills"),
     cursor: join(".agents", "skills"),
@@ -43,6 +46,36 @@ function skillBody(render, binName) {
     const content = render(binName);
     return content.slice(content.indexOf("-->") + 3).trim();
 }
+function cursorRuleBody(projectRoot, binName) {
+    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, binName) {
+    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) {
     const p = join(projectRoot, ".harnery", "config.jsonc");
@@ -157,6 +190,26 @@ export function applyInstructions(projectRoot, opts) {
             }
         }
     }
+    // ── 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);
@@ -239,6 +292,19 @@ export function removeInstructions(projectRoot, opts) {
             }
         }
     }
+    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) {
@@ -305,6 +371,11 @@ export function checkInstructions(projectRoot, opts) {
                 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;

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAqGR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAgHR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -113,6 +113,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.
@@ -125,6 +131,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/dist/lib/local-file-url.d.ts

@@ -0,0 +1,9 @@
+/** Mnemonic dashboard port: 4276 spells HARN on a phone keypad. */
+export declare const DEFAULT_WEB_PORT = 4276;
+/** Cookie-isolated host for navigable repo files. */
+export declare const FILES_ORIGIN_HOST = "harnery-files.localhost";
+/** Encode each repo-path segment while preserving slash-based URL resolution. */
+export declare function encodedRepoPath(relPath: string): string;
+export declare function localFilesOriginUrl(relPath: string, port?: number | string, protocol?: string): string;
+export declare function localFileViewerUrl(relPath: string, port?: number | string): string;
+//# sourceMappingURL=local-file-url.d.ts.map

package/dist/lib/local-file-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-url.d.ts","sourceRoot":"","sources":["../../src/lib/local-file-url.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,qDAAqD;AACrD,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,MAAyB,EACxC,QAAQ,SAAU,GACjB,MAAM,CAGR;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,MAAM,GAAG,MAAyB,GACvC,MAAM,CAER"}

package/dist/lib/local-file-url.js

@@ -0,0 +1,20 @@
+/** 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) {
+    return relPath
+        .replace(/^\/+/, "")
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+export function localFilesOriginUrl(relPath, port = DEFAULT_WEB_PORT, protocol = "http:") {
+    const portPart = String(port) === "" ? "" : `:${port}`;
+    return `${protocol}//${FILES_ORIGIN_HOST}${portPart}/${encodedRepoPath(relPath)}`;
+}
+export function localFileViewerUrl(relPath, port = DEFAULT_WEB_PORT) {
+    return `http://localhost:${port}/files?path=${encodeURIComponent(relPath)}`;
+}