harnery 0.46.0 → 0.47.0

package/src/lib/http/client.ts

@@ -54,15 +54,6 @@ export interface FetchOptions<TResponseType extends FetchResponseType = "text">
   extraCookies?: ExtraCookies;
   /** Response body representation. Default `text`; use `bytes` for lossless file output. */
   responseType?: TResponseType;
-  /**
-   * With `redirect: "follow"`, follow redirects in this client instead of the
-   * runtime's fetch. Every hop then gets its own cookie header, `extraHeaders`
-   * call, and Set-Cookie persistence, so a caller that inspects those can stop
-   * a chain between hops. Credential headers are dropped on a cross-origin hop.
-   * Default: on whenever a `jar` is passed (host-only cookies must follow the
-   * jar's exact-host rule on every hop), off without one.
-   */
-  clientRedirects?: boolean;
 }
 
 type FetchBody<TResponseType extends FetchResponseType> = TResponseType extends "bytes"
@@ -86,23 +77,40 @@ export interface FetchResult<TBody = string> {
  * 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.
+ *
+ * With `redirect: "follow"` (the default) this client follows redirects
+ * itself instead of the runtime's fetch, with or without a jar, so one
+ * policy governs every hop:
+ *   - Each hop gets its own jar Cookie header (exact-host for host-only
+ *     cookies), its own `extraHeaders(url)` call for the hop's URL, and its
+ *     own Set-Cookie persistence. A callback that throws stops the chain
+ *     before the next request.
+ *   - A same-origin hop keeps every caller header.
+ *   - A cross-origin hop keeps only the caller headers in
+ *     `CROSS_ORIGIN_REDIRECT_HEADERS`; credentials, bypass tokens, and custom
+ *     `X-*` headers are dropped for the rest of the chain.
+ *   - A cross-origin 307 or 308 on a request that is not GET or HEAD throws
+ *     instead of resending the body to the new origin.
  */
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const MAX_CLIENT_REDIRECTS = 20;
 
+/** Caller headers that survive a redirect to a different origin (lowercase). */
+export const CROSS_ORIGIN_REDIRECT_HEADERS: ReadonlySet<string> = new Set([
+  "user-agent",
+  "accept",
+  "accept-language",
+  "range",
+]);
+
 export async function fetchWithJar<TResponseType extends FetchResponseType = "text">(
   url: string,
   opts: FetchOptions<TResponseType> = {},
 ): Promise<FetchResult<FetchBody<TResponseType>>> {
-  // With a jar, redirects are followed here so every hop gets its own Cookie
-  // header from the jar (exact-host for host-only cookies) and its own
-  // Set-Cookie persistence; the runtime would otherwise carry or drop the
-  // first hop's header on its own rules. Pass `clientRedirects: false` to opt out.
-  const clientRedirects = opts.clientRedirects ?? Boolean(opts.jar);
-  if (!clientRedirects || (opts.redirect ?? "follow") !== "follow") return fetchOnce(url, opts);
+  if ((opts.redirect ?? "follow") !== "follow") return fetchOnce(url, opts);
 
   let current = url;
-  let method = opts.method ?? "GET";
+  let method = (opts.method ?? "GET").toUpperCase();
   let body = opts.body;
   let headers = opts.headers;
   let cookiesSaved = 0;
@@ -115,17 +123,23 @@ export async function fetchWithJar<TResponseType extends FetchResponseType = "te
       throw new Error(`Too many redirects (more than ${MAX_CLIENT_REDIRECTS}) starting at ${url}`);
     }
     const next = new URL(location, current);
+    const crossOrigin = next.origin !== new URL(current).origin;
     if (
       result.status === 303 ||
       ((result.status === 301 || result.status === 302) && method !== "GET" && method !== "HEAD")
     ) {
       method = "GET";
       body = undefined;
+    } else if (crossOrigin && method !== "GET" && method !== "HEAD") {
+      throw new Error(
+        `Refusing to follow a ${result.status} redirect of a ${method} request from ${new URL(current).origin} to ${next.origin}: ` +
+          "it would resend the request body to a different origin. Send the request to the new URL directly if that is intended.",
+      );
     }
-    if (next.origin !== new URL(current).origin && headers) {
+    if (crossOrigin && headers) {
       headers = Object.fromEntries(
-        Object.entries(headers).filter(
-          ([name]) => !["authorization", "cookie"].includes(name.toLowerCase()),
+        Object.entries(headers).filter(([name]) =>
+          CROSS_ORIGIN_REDIRECT_HEADERS.has(name.toLowerCase()),
         ),
       );
     }

package/src/lib/instructions/apply.ts

@@ -21,6 +21,7 @@
  *     `.claude/skills/`; Cursor and Codex use `.agents/skills/`.
  */
 
+import { spawnSync } from "node:child_process";
 import {
   existsSync,
   mkdirSync,
@@ -31,7 +32,11 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, join } from "node:path";
-import { endOfTurnStatusCommand, stripJsonComments } from "../../core/config.ts";
+import {
+  endOfTurnStatusCommand,
+  readComputerConfig,
+  stripJsonComments,
+} from "../../core/config.ts";
 import { readHostAddendum } from "./host-addendum.ts";
 import {
   checkOwnedSkill,
@@ -49,6 +54,7 @@ import {
   INSTRUCTIONS_REGION,
   renderInstructionsBlock,
   SKILLS,
+  type SkillTemplate,
 } from "./templates.ts";
 
 const AGENTS_FILE = "AGENTS.md";
@@ -134,12 +140,35 @@ export function readSkillsExclude(projectRoot: string): Set<string> {
 function blockSkills(projectRoot: string, adapter: string): BlockSkills {
   const supported = adapterSkillsDir(adapter) !== null;
   const exclude = readSkillsExclude(projectRoot);
-  return {
+  const skills: BlockSkills = {
     decide: supported && !exclude.has("harn-decide"),
     council: supported && !exclude.has("harn-council"),
     end: supported && !exclude.has("harn-end"),
     team: supported && !exclude.has("harn-team"),
   };
+  // Only an enabled project's block mentions the opt-in skill, so every other
+  // project's block stays byte-identical.
+  if (supported && !exclude.has("harn-computer") && readComputerConfig(projectRoot).enabled) {
+    skills.computer = true;
+  }
+  return skills;
+}
+
+/** False for an opt-in skill whose config gate is off in this project. */
+function skillOptedIn(projectRoot: string, skill: SkillTemplate): boolean {
+  if (skill.optIn === "computer") return readComputerConfig(projectRoot).enabled;
+  return true;
+}
+
+/** Delete an owned skill file and its now-empty harn-* dir (adapter root stays). */
+function removeOwnedSkillFile(skillPath: string): void {
+  rmSync(skillPath);
+  const dir = dirname(skillPath);
+  try {
+    if (readdirSync(dir).length === 0) rmdirSync(dir);
+  } catch {
+    /* dir not empty or gone → leave it */
+  }
 }
 
 interface ApplyOpts {
@@ -170,6 +199,9 @@ export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyRe
   // aborts the whole run instead of leaving AGENTS.md half-updated.
   const addendum = readHostAddendum(projectRoot);
 
+  const parentScope = parentScopeWarning(projectRoot);
+  if (parentScope) warnings.push(parentScope);
+
   // ── AGENTS.md orientation block ─────────────────────────────────────────
   const agentsPath = join(projectRoot, AGENTS_FILE);
   const agentsExisted = existsSync(agentsPath);
@@ -272,6 +304,16 @@ export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyRe
         continue;
       }
       const skillPath = join(projectRoot, skillsDir, skill.relPath);
+      if (!skillOptedIn(projectRoot, skill)) {
+        // Turning the gate off takes back a skill an earlier init wrote.
+        if (existsSync(skillPath) && isOwnedFile(readFileSync(skillPath, "utf8"))) {
+          if (!opts.dryRun) removeOwnedSkillFile(skillPath);
+          actions.push(
+            `+ ${verbed("remove", "removed")} skill ${skill.id} (${skill.optIn}.enabled is off)`,
+          );
+        }
+        continue;
+      }
       const content = skill.render(opts.binName);
       const before = existsSync(skillPath) ? readFileSync(skillPath, "utf8") : null;
       if (before === content) {
@@ -292,6 +334,53 @@ export function applyInstructions(projectRoot: string, opts: ApplyOpts): ApplyRe
   return { actions, warnings };
 }
 
+/** True when `dir` is inside a real Git work tree (an empty `.git` folder does not count). */
+function insideGitWorkTree(dir: string): boolean {
+  const r = spawnSync("git", ["-C", dir, "rev-parse", "--is-inside-work-tree"], {
+    encoding: "utf8",
+  });
+  return r.status === 0 && r.stdout.trim() === "true";
+}
+
+const PARENT_SCAN_SKIP = new Set(["node_modules"]);
+
+/**
+ * Warn when instructions are being installed in a folder that is not a Git
+ * work tree but holds projects carrying their own Harnery instructions block.
+ * Harnesses that read instruction files from parent folders (Claude Code walks
+ * up for CLAUDE.md) would load this block on top of each project's own, and
+ * with the wrong command name when a project pins a different one. Installing
+ * in a non-Git folder stays supported; this only names the overlap.
+ */
+export function parentScopeWarning(projectRoot: string): string | null {
+  if (insideGitWorkTree(projectRoot)) return null;
+  let entries: string[];
+  try {
+    entries = readdirSync(projectRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !PARENT_SCAN_SKIP.has(e.name))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return null;
+  }
+  const marker = `harnery:begin ${INSTRUCTIONS_REGION}`;
+  const children = entries.filter((name) => {
+    try {
+      return readFileSync(join(projectRoot, name, AGENTS_FILE), "utf8").includes(marker);
+    } catch {
+      return false;
+    }
+  });
+  if (children.length === 0) return null;
+  const listed =
+    children.slice(0, 5).join(", ") + (children.length > 5 ? `, +${children.length - 5} more` : "");
+  return (
+    `${projectRoot} is not a Git work tree and contains ${children.length} project(s) with their own ` +
+    `Harnery instructions (${listed}). Harnesses that read parent folders, such as Claude Code, will load ` +
+    `this block on top of theirs. Run init inside each project instead, or pass --project-root <project>.`
+  );
+}
+
 interface RemoveOpts {
   adapter: string;
   dryRun: boolean;
@@ -382,16 +471,7 @@ export function removeInstructions(projectRoot: string, opts: RemoveOpts): Apply
         warnings.push(`left ${skill.relPath} (hand-edited; no harnery ownership marker)`);
         continue;
       }
-      if (!opts.dryRun) {
-        rmSync(skillPath);
-        // Drop the now-empty harn-* dir, leaving the adapter skills root intact.
-        const dir = dirname(skillPath);
-        try {
-          if (readdirSync(dir).length === 0) rmdirSync(dir);
-        } catch {
-          /* dir not empty or gone → leave it */
-        }
-      }
+      if (!opts.dryRun) removeOwnedSkillFile(skillPath);
       actions.push(`+ ${opts.dryRun ? "would delete" : "deleted"} skill ${skill.id}`);
     }
   }
@@ -453,6 +533,14 @@ export function checkInstructions(
         if (exclude.has(skill.id)) continue;
         const skillPath = join(projectRoot, skillsDir, skill.relPath);
         const c = existsSync(skillPath) ? readFileSync(skillPath, "utf8") : "";
+        if (!skillOptedIn(projectRoot, skill)) {
+          if (isOwnedFile(c)) {
+            issues.push(
+              `skill ${skill.id}: present but ${skill.optIn}.enabled is off (re-run init)`,
+            );
+          }
+          continue;
+        }
         note(`skill ${skill.id}`, checkOwnedSkill(c, skillBody(skill.render, opts.binName)));
       }
     }

package/src/lib/instructions/git-hooks.ts

@@ -53,18 +53,21 @@ function regionName(event: GitHookEvent): string {
  */
 export function renderGitHookBody(event: GitHookEvent): string {
   const blocking = event === "pre-commit";
+  const native = process.platform === "win32";
+  const command = `${native ? "node " : ""}"$harnery_hook_bin"`;
+  const extension = native ? ".mjs" : "";
   const invoke = blocking
-    ? `  "$harnery_hook_bin" git-hook ${event} "$@"\n` +
+    ? `  ${command} git-hook ${event} "$@"\n` +
       `  harnery_hook_rc=$?\n` +
       `  [ "$harnery_hook_rc" -ne 0 ] && exit "$harnery_hook_rc"\n`
-    : `  "$harnery_hook_bin" git-hook ${event} "$@" >/dev/null 2>&1 || true\n`;
+    : `  ${command} git-hook ${event} "$@" >/dev/null 2>&1 || true\n`;
   return (
     `# Coordination for this hook lives in harnery (agent-coord git-hook ${event});\n` +
     `# upgrading harnery upgrades the behavior. Managed region: do not edit by hand.\n` +
     `harnery_hook_root=$(git rev-parse --show-superproject-working-tree 2>/dev/null)\n` +
     `[ -n "$harnery_hook_root" ] || harnery_hook_root=$(git rev-parse --show-toplevel 2>/dev/null)\n` +
-    `for harnery_hook_bin in "$harnery_hook_root/harnery/bin/agent-coord" "$harnery_hook_root/node_modules/harnery/bin/agent-coord"; do\n` +
-    `  [ -x "$harnery_hook_bin" ] || continue\n` +
+    `for harnery_hook_bin in "$harnery_hook_root/harnery/bin/agent-coord${extension}" "$harnery_hook_root/node_modules/harnery/bin/agent-coord${extension}"; do\n` +
+    `  [ -${native ? "f" : "x"} "$harnery_hook_bin" ] || continue\n` +
     invoke +
     `  break\n` +
     `done`
@@ -79,6 +82,7 @@ export function renderGitHookBody(event: GitHookEvent): string {
  */
 export function resolveHooksDir(projectRoot: string): string | null {
   const r = spawnSync("git", ["rev-parse", "--git-path", "hooks"], {
+    windowsHide: true,
     cwd: projectRoot,
     encoding: "utf8",
     timeout: 5000,

package/src/lib/instructions/templates.ts

@@ -36,6 +36,11 @@ export interface BlockSkills {
   end: boolean;
   /** the `harn-team` skill file is present */
   team: boolean;
+  /**
+   * the opt-in `harn-computer` skill file is present (only when the project
+   * sets `computer.enabled`); absent from the default block entirely
+   */
+  computer?: boolean;
 }
 
 /**
@@ -78,6 +83,11 @@ export function renderInstructionsBlock(
   const teamPointer = skills.team
     ? "The `harn-team` skill owns the tier choice, the governor artifacts, and the drive loop."
     : `See \`${b} governor --help\` for the tier choice and the drive loop.`;
+  // Opt-in surface: the default block stays byte-identical unless the project
+  // enabled computer use and the skill is actually installed.
+  const computerPointer = skills.computer
+    ? `\n\n**Desktop control.** This project enables \`${b} computer\` for driving native desktop apps and real browsers as a last resort. The \`harn-computer\` skill has the loop, and the desktop is one shared resource held by one agent at a time.`
+    : "";
   // Render the journal categories from the canonical enum so this prose can
   // never drift from what `journal add` actually accepts (the "note, plan…" list
   // silently lagged the tool by two categories before this).
@@ -165,7 +175,7 @@ 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>"\`
 surfaces prior decisions, so check for precedent before re-deciding. ${decidePointer}
 
-**Councils.** For a hard or contested decision, convene a council of agents. \`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}`;
+**Councils.** For a hard or contested decision, convene a council of agents. \`${b} council create "<objective>"\` runs structured rounds toward a decision. ${councilPointer}${computerPointer}`;
 }
 
 // ── Skills ──────────────────────────────────────────────────────────────────
@@ -176,6 +186,12 @@ export interface SkillTemplate {
   /** path under the adapter skill dir, e.g. `harn-decide/SKILL.md` */
   relPath: string;
   render: (binName: string) => string;
+  /**
+   * Config gate for an opt-in skill. `"computer"` renders only when the project
+   * sets `computer.enabled: true`; ungated skills always render (minus
+   * `skills.exclude`).
+   */
+  optIn?: "computer";
 }
 
 function decideBody(b: string): string {
@@ -518,6 +534,71 @@ single next action. If you declined to build a team because one already existed,
 say that first; it is the most useful sentence in the reply.`;
 }
 
+function computerBody(b: string): string {
+  return `\`${b} computer\` drives this machine's desktop through a pinned desktop driver.
+It is the last resort: use a vendor API, a CLI, or the browser tools first.
+Reach for it only for a native desktop app, or a page that needs a real
+browser you cannot drive any other way.
+
+## Setup check
+
+\`\`\`bash
+${b} computer status
+\`\`\`
+
+It shows the host, the pinned driver and whether it is installed, the daemon,
+and who holds the desktop. When the driver is missing, the project must enable
+computer use and run \`${b} computer install --yes\`. \`${b} computer doctor\`
+reports the driver's own health checks.
+
+## Core loop
+
+Every step is one call: \`${b} computer call <tool> '<json>'\`. Look up a tool's
+arguments with \`${b} computer describe <tool>\` rather than guessing; \`${b} computer tools\`
+lists them.
+
+1. **Launch** the app in the background with \`launch_app\`.
+2. **Read state** with \`get_window_state\` and \`include_screenshot: false\`. When
+   you need to see the window, pass \`screenshot_out_file\` with a file path
+   and read that file. Inline screenshots are redacted from the output unless
+   you pass \`--keep-screenshot\`, because they flood your context.
+3. **Act by element token** \`"<snapshot_id>:<row>"\` from the latest state:
+   click, \`set_value\`, or invoke, batched through \`run_steps\` when several
+   actions belong together.
+4. **Read back** the state after acting. Confirm the change landed before you
+   retry anything; never repeat an action blind.
+
+## Rules
+
+- Prefer accessibility routes (\`set_value\`, invoke) over \`type_text\` and
+  coordinate clicks.
+- Never pass \`delivery_mode: "foreground"\` unless the driver returned
+  \`background_unavailable\` or \`delivery_failed\` for that action.
+- For a browser, call \`browser_prepare\` with \`allow_launch: true\` and
+  \`profile: {"mode": "isolated_new"}\`. Never attach to the user's real
+  profile unless the operator asks for it.
+- Never type a password, username, or one-time code into a sign-in page. Stop
+  and ask the operator to sign in.
+- Only \`kill_app\` processes you launched.
+
+## One desktop, one holder
+
+Every agent on this machine shares one desktop. \`call\` takes a lease for you
+and refreshes it on every call; it lapses after a short idle period.
+
+- A refusal naming another holder means **wait**, then try once more later. Do
+  not retry in a loop. \`--wait <seconds>\` waits longer on one call.
+- Check the holder with \`${b} computer lease status\`.
+- Release the desktop as soon as you finish:
+
+  \`\`\`bash
+  ${b} computer lease release
+  \`\`\`
+
+Report what you did on the desktop, which apps you launched and closed, and
+anything you left open.`;
+}
+
 export const SKILLS: SkillTemplate[] = [
   {
     id: "harn-decide",
@@ -567,4 +648,17 @@ export const SKILLS: SkillTemplate[] = [
         body: teamBody(binName),
       }),
   },
+  {
+    id: "harn-computer",
+    relPath: "harn-computer/SKILL.md",
+    optIn: "computer",
+    render: (binName) =>
+      buildOwnedSkill({
+        name: "harn-computer",
+        description:
+          "Drive a native desktop app or a real browser through the project's pinned desktop driver, as a last resort after APIs, CLIs, and browser tools. Covers the setup check, the launch / read state / act by element token / read back loop, safety rules, and the shared desktop lease.",
+        binName,
+        body: computerBody(binName),
+      }),
+  },
 ];