harnery 0.4.0 → 0.6.0

package/src/core/hooks/effects/index.ts

@@ -17,6 +17,7 @@ import { existsSync, readdirSync, rmSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import { applyDetection } from "../../../lib/presence.ts";
+import { resolveBinName } from "../../config.ts";
 
 export type { CaptureContext } from "./image-capture.ts";
 export { captureImages, imageJanitor } from "./image-capture.ts";
@@ -126,7 +127,7 @@ export function scratchArchive(repoRoot: string, owner: string): void {
  */
 export function syncClaudeSessions(repoRoot: string, force: boolean): void {
   try {
-    const bin = join(repoRoot, "bin", "bp");
+    const bin = join(repoRoot, "bin", resolveBinName(repoRoot));
     if (!existsSync(bin)) return;
     const env: Record<string, string | undefined> = {
       ...process.env,

package/src/core/hooks/guard-path.ts

@@ -0,0 +1,34 @@
+/**
+ * Canonicalize a write-tool target path for the claim guard.
+ *
+ * Returns the monorepo-relative path, or `null` when the target lies OUTSIDE the
+ * repo (an absolute path not under coordRoot, e.g. a `/tmp` scratchpad or other
+ * session-temp file).
+ *
+ * The claim system is intentionally repo-scoped: it coordinates monorepo files,
+ * not arbitrary absolute paths, so the guard skips out-of-repo targets. Skipping
+ * them is right on two counts. First, it keeps non-repo paths out of a
+ * heartbeat's `files_touched`. Second, the ordering rule compares raw path
+ * strings, and an absolute `/tmp/…` sorts before every repo-relative path
+ * (`/` = 0x2F < any letter), so without this a scratchpad write would spuriously
+ * "block" a legitimately-held repo file. Returning null keeps such paths out of
+ * the claim system entirely.
+ *
+ * Accepted tradeoff: this also means shared out-of-repo files (a user-level
+ * memory or plans directory) are not coordinated across agents. The alternative,
+ * normalizing every path to one consistent key so those stay coordinated, was
+ * rejected as gold-plating a rare, merge-disciplined race in a deadlock-critical
+ * path. Coordinate shared state by keeping it in the repo, not out of it.
+ *
+ * Relative inputs are assumed already-repo-relative (Codex `apply_patch` emits
+ * cwd-relative paths). The in-repo check requires the `<root>/` separator, so a
+ * sibling dir that merely shares a prefix (`/repo-other` vs `/repo`) is treated
+ * as out-of-repo, not stripped.
+ */
+export function canonicalize(coordRoot: string, p: string): string | null {
+  if (!p) return null;
+  if (p === coordRoot) return ".";
+  if (p.startsWith(`${coordRoot}/`)) return p.slice(coordRoot.length + 1);
+  if (p.startsWith("/")) return null; // absolute + not under coordRoot → out-of-repo
+  return p; // relative → treat as repo-relative
+}

package/src/lib/agent-browser/client.ts

@@ -124,7 +124,7 @@ export class AgentBrowser {
         return;
       }
       const stateFile =
-        this.opts.stateFilePath ?? `/tmp/bp-agent-browser-state-${process.pid}.json`;
+        this.opts.stateFilePath ?? `/tmp/harn-agent-browser-state-${process.pid}.json`;
       writeFileSync(stateFile, JSON.stringify(jarStore, null, 2));
       this.exec(["state", "load", stateFile], 10_000);
       this.cookiesSeeded = true;

package/src/lib/browser/client.ts

@@ -18,6 +18,12 @@ import {
   type OverflowResult,
   type WidthResult,
 } from "./layout.js";
+import {
+  buildClearRuntsAnnotationsScript,
+  buildRuntsAnnotateScript,
+  buildRuntsCheck,
+  type RuntsResult,
+} from "./runts.js";
 import {
   buildAnnotateScript,
   buildClearAnnotationsScript,
@@ -357,6 +363,28 @@ export class Browser {
     });
   }
 
+  /**
+   * Scan text blocks for runts — a single word alone on a block's last
+   * visual line. Word-count per line via per-word Range rects (the width
+   * of the last line is deliberately NOT the signal; see runts.ts).
+   */
+  async checkRunts(opts: { scope?: string | null; minChars?: number } = {}): Promise<RuntsResult> {
+    return await this.currentPage.evaluate(buildRuntsCheck(), {
+      scope: opts.scope ?? null,
+      minChars: opts.minChars ?? 40,
+    });
+  }
+
+  /** Inject annotation overlays for runt hits. Used before screenshot. */
+  async annotateRunts(result: RuntsResult): Promise<void> {
+    await this.currentPage.evaluate(buildRuntsAnnotateScript(), { runts: result.runts });
+  }
+
+  /** Remove runt annotation overlays. */
+  async clearRuntsAnnotations(): Promise<void> {
+    await this.currentPage.evaluate(buildClearRuntsAnnotationsScript());
+  }
+
   /** Inject annotation overlays for width + overflow results. Used before screenshot. */
   async annotateLayout(args: {
     widths: WidthResult[];

package/src/lib/browser/index.ts

@@ -17,6 +17,10 @@ export type {
   OverflowResult,
   WidthResult,
 } from "./layout.js";
+export type {
+  RuntHit,
+  RuntsResult,
+} from "./runts.js";
 export type {
   CheckVisibilityOptions,
   VisibilityResult,

package/src/lib/browser/runts.ts

@@ -0,0 +1,218 @@
+// Runt detection for `harn browse` — a runt (a.k.a. "widow word") is a single
+// short word sitting alone on the LAST visual line of a text block. Not a
+// page-break issue; it happens mid-page and just looks sloppy.
+//
+// Detection is by COUNTING WORDS on the last visual line (== 1 word), NOT by
+// relative width: a width threshold misses runts in narrow columns (how-to
+// steps, a right-aligned contact box) where one short word still fills a big
+// slice of the skinny column. "Text block" = element with real text whose
+// element children are all inline — a <p>-only pass silently skips
+// pull-quotes, blurbs and captions that ship as <div>/<blockquote>.
+//
+// Atomic tokens (URLs, emails, phone numbers) are excluded — they can't be
+// rebalanced and usually sit on their own line by design. The detector can't
+// catch a runt that is itself one long word; eyeball as a final pass.
+//
+// The word-level line mapping (per-word Range rects grouped by line top) was
+// first built for the paged.js print-book lint; this is the generalized
+// live-page port.
+
+export interface RuntHit {
+  /** Human label for the owning block: `tag#id` / `tag.class` / `tag`. */
+  block: string;
+  /** The lone word on the last visual line (trailing punctuation included). */
+  word: string;
+  /** First ~80 chars of the block's text, for locating it. */
+  snippet: string;
+  /** Document-relative rect of the runt word (scroll offsets applied). */
+  rect: { x: number; y: number; width: number; height: number };
+  /** Number of visual lines in the block. */
+  lines: number;
+}
+
+export interface RuntsResult {
+  /** Text blocks scanned (post length/inline-children filters). */
+  scannedBlocks: number;
+  /** True when the block sweep hit the internal cap (very large page). */
+  truncated: boolean;
+  runts: RuntHit[];
+}
+
+/**
+ * Build the JS function passed to `page.evaluate`. `scope` narrows the sweep
+ * to one container (null = whole body); `minChars` filters out tiny labels
+ * that can't meaningfully wrap (default 40).
+ */
+export function buildRuntsCheck(): (args: {
+  scope: string | null;
+  minChars: number;
+}) => RuntsResult {
+  return ({ scope, minChars }) => {
+    const INLINE = new Set([
+      "B",
+      "I",
+      "EM",
+      "STRONG",
+      "SPAN",
+      "A",
+      "BR",
+      "SMALL",
+      "SUP",
+      "SUB",
+      "U",
+      "MARK",
+      "CODE",
+      "ABBR",
+      "TIME",
+      "WBR",
+    ]);
+    const ATOMIC = /@|https?:|\.(com|org|net|io|co)\b|\d-\d{3}/;
+    const BLOCK_CAP = 5000;
+    const RUNT_CAP = 50;
+
+    const root = scope ? document.querySelector(scope) : document.body;
+    if (!root) return { scannedBlocks: 0, truncated: false, runts: [] };
+
+    const sx = window.scrollX;
+    const sy = window.scrollY;
+
+    const label = (el: Element): string => {
+      const tag = el.tagName.toLowerCase();
+      if (el.id) return `${tag}#${el.id}`;
+      const cls = typeof el.className === "string" ? el.className.trim() : "";
+      if (cls) return `${tag}.${cls.split(/\s+/).slice(0, 2).join(".")}`;
+      return tag;
+    };
+
+    const all = root.querySelectorAll("*");
+    const runts: RuntHit[] = [];
+    let scanned = 0;
+    let truncated = false;
+
+    for (let i = 0; i < all.length; i++) {
+      const el = all[i];
+      if (!el) continue;
+      const text = el.textContent ?? "";
+      if (text.trim().length < minChars) continue;
+      let allInline = true;
+      for (const c of el.children) {
+        if (!INLINE.has(c.tagName)) {
+          allInline = false;
+          break;
+        }
+      }
+      if (!allInline) continue;
+      const elRect = el.getBoundingClientRect();
+      if (elRect.width <= 0 || elRect.height <= 0) continue;
+
+      if (scanned >= BLOCK_CAP) {
+        truncated = true;
+        break;
+      }
+      scanned++;
+
+      // Map every word to its visual line by rounding the Range rect top.
+      const lines = new Map<number, { words: string[]; last: DOMRect }>();
+      const tw = document.createTreeWalker(el, NodeFilter.SHOW_TEXT);
+      for (let n = tw.nextNode(); n; n = tw.nextNode()) {
+        const value = n.nodeValue ?? "";
+        for (const m of value.matchAll(/\S+/g)) {
+          const r = document.createRange();
+          r.setStart(n, m.index);
+          r.setEnd(n, m.index + m[0].length);
+          const rect = r.getBoundingClientRect();
+          if (!rect.width) continue;
+          const top = Math.round(rect.top);
+          const entry = lines.get(top);
+          if (entry) {
+            entry.words.push(m[0]);
+            entry.last = rect;
+          } else {
+            lines.set(top, { words: [m[0]], last: rect });
+          }
+        }
+      }
+      const tops = [...lines.keys()].sort((a, b) => a - b);
+      if (tops.length < 2) continue; // single line, no runt risk
+      const lastTop = tops[tops.length - 1];
+      const last = lastTop === undefined ? undefined : lines.get(lastTop);
+      if (last?.words.length !== 1) continue;
+      const word = last.words[0] ?? "";
+      if (ATOMIC.test(word)) continue;
+
+      runts.push({
+        block: label(el),
+        word,
+        snippet: text.replace(/\s+/g, " ").trim().slice(0, 80),
+        rect: {
+          x: Math.round(last.last.x + sx),
+          y: Math.round(last.last.y + sy),
+          width: Math.round(last.last.width),
+          height: Math.round(last.last.height),
+        },
+        lines: tops.length,
+      });
+      if (runts.length >= RUNT_CAP) {
+        truncated = true;
+        break;
+      }
+    }
+
+    return { scannedBlocks: scanned, truncated, runts };
+  };
+}
+
+/**
+ * Annotate runt hits onto the live page before the screenshot. Uses a
+ * document-absolute root (not fixed-inset like the other check overlays)
+ * because runts are usually below the fold and the rects are document
+ * coordinates — this keeps boxes aligned on full-page captures.
+ */
+export function buildRuntsAnnotateScript(): (args: { runts: RuntHit[] }) => void {
+  return ({ runts }) => {
+    const ROOT_ID = "__bp-check-runt-annotations__";
+    document.getElementById(ROOT_ID)?.remove();
+    const root = document.createElement("div");
+    root.id = ROOT_ID;
+    root.style.cssText =
+      "position: absolute; top: 0; left: 0; width: 100%; height: 0; overflow: visible; pointer-events: none; z-index: 2147483646;";
+    document.body.appendChild(root);
+
+    for (const hit of runts) {
+      const box = document.createElement("div");
+      box.style.cssText = `
+        position: absolute;
+        left: ${hit.rect.x - 3}px;
+        top: ${hit.rect.y - 3}px;
+        width: ${hit.rect.width + 6}px;
+        height: ${hit.rect.height + 6}px;
+        border: 2px solid #d946ef;
+        box-sizing: border-box;
+        background: #d946ef1a;
+        pointer-events: none;
+      `;
+      const tag = document.createElement("div");
+      tag.textContent = `runt: …${hit.word} (${hit.block})`;
+      tag.style.cssText = `
+        position: absolute;
+        left: 0;
+        top: -18px;
+        background: #d946ef;
+        color: #fff;
+        font: 12px/1.4 -apple-system, system-ui, sans-serif;
+        padding: 1px 6px;
+        border-radius: 3px;
+        white-space: nowrap;
+        pointer-events: none;
+      `;
+      box.appendChild(tag);
+      root.appendChild(box);
+    }
+  };
+}
+
+export function buildClearRuntsAnnotationsScript(): () => void {
+  return () => {
+    document.getElementById("__bp-check-runt-annotations__")?.remove();
+  };
+}

package/src/lib/completion/bash.ts

@@ -162,6 +162,42 @@ function bashEscape(s: string): string {
  * to subcommand / option / value completion. `fn` is the function-name prefix
  * and `binName` is the CLI name used for the `__complete` callback.
  */
+/**
+ * DYNAMIC bash completion: a thin, tree-independent shim. Instead of baking the
+ * command tree into case-tables (which go stale on any command/flag change),
+ * it hands the live command line to `<bin> __complete-line` on every <Tab> and
+ * lets the binary — which always knows its own current tree — answer. Install
+ * once; never regenerate. The trailing `\x1f:<n>` line carries the directive
+ * bitmask (bit 0 = fall back to file completion).
+ */
+export function generateBashDynamic(binName: string): string {
+  const fn = fnPrefix(binName);
+  return `# ${binName} bash completion (dynamic; install once, never stale). Do not edit.
+# Source via:  eval "$(${binName} completion bash --dynamic)"
+${fn}() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  local raw line directive=0
+  local -a cands=()
+  raw="$(${binName} __complete-line "$COMP_CWORD" -- "\${COMP_WORDS[@]}" 2>/dev/null)" || return
+  while IFS= read -r line; do
+    [ -z "$line" ] && continue
+    if [ "\${line:0:2}" = $'\\x1f:' ]; then
+      directive="\${line:2}"
+    else
+      cands+=( "\${line%%$'\\t'*}" )
+    fi
+  done <<< "$raw"
+  if (( directive & 1 )); then
+    COMPREPLY=( $(compgen -f -- "$cur") )
+    return
+  fi
+  local IFS=$'\\n'
+  COMPREPLY=( $(compgen -W "\${cands[*]}" -- "$cur") )
+}
+complete -F ${fn} ${binName}
+`;
+}
+
 function bashDriver(fn: string, binName: string): string {
   return `${fn}() {
   local cur prev words cword

package/src/lib/completion/fish.ts

@@ -67,6 +67,28 @@ function valueAction(
   return { flag: "-r", arg: "" };
 }
 
+/**
+ * DYNAMIC fish completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Fish renders `value\tdescription` lines natively, so the
+ * helper just strips the trailing `\x1f:<n>` directive line. Note: fish's
+ * declarative `complete -a` cannot switch to file completion from inside the
+ * helper, so the File directive is a no-op here — use static fish completion
+ * (`completion fish`) if you need file fallback on a path-valued positional.
+ */
+export function generateFishDynamic(binName: string): string {
+  const fn = `__${binName.replace(/[^a-zA-Z0-9_]/g, "_")}_complete`;
+  return `# ${binName} fish completion (dynamic; install once, never stale). Do not edit.
+# Source via:  ${binName} completion fish --dynamic | source
+function ${fn}
+  set -l toks (commandline -opc)
+  set -l cur (commandline -ct)
+  ${binName} __complete-line (count $toks) -- $toks $cur 2>/dev/null | string match -rv '^\\x1f:'
+end
+complete -c ${binName} -f -a '(${fn})'
+`;
+}
+
 export function generateFish(root: CommandSpec, binName: string): string {
   const out: string[] = [];
   out.push(

package/src/lib/completion/index.ts

@@ -1,5 +1,14 @@
-export { generateBash } from "./bash.js";
-export { generateFish } from "./fish.js";
+export { generateBash, generateBashDynamic } from "./bash.js";
+export { generateFish, generateFishDynamic } from "./fish.js";
+export {
+  type Candidate,
+  type CompletionProviderRunner,
+  type CompletionResult,
+  DIRECTIVE_PREFIX,
+  Directive,
+  encodeResult,
+  resolveCompletions,
+} from "./resolve.js";
 export {
   type CommandSpec,
   type CompletionContextLookup,
@@ -7,4 +16,4 @@ export {
   type PositionalSpec,
   walkProgram,
 } from "./walk.js";
-export { generateZsh } from "./zsh.js";
+export { generateZsh, generateZshDynamic } from "./zsh.js";

package/src/lib/completion/resolve.ts

@@ -0,0 +1,210 @@
+/**
+ * Runtime completion resolver — the authoritative, in-process answer to
+ * "what should I suggest at this cursor position?".
+ *
+ * The static bash/zsh/fish generators bake the whole command tree into shell
+ * case-tables, which go stale the moment a command/flag is added (the script
+ * must be regenerated + reinstalled). The DYNAMIC completion path instead
+ * installs a thin, tree-independent shim that, on every <Tab>, hands the live
+ * command line back to the binary and calls THIS function. Because the binary
+ * always knows its own current command tree, a dynamic shim never goes stale —
+ * install once, ever.
+ *
+ * This mirrors the path-walking the static bash driver does, but in one place
+ * and in TypeScript, so all three shells share identical behavior. It is
+ * deliberately decoupled from Commander internals via the CommandSpec tree
+ * (walkProgram), exactly like the static generators.
+ */
+
+import type { Command } from "commander";
+import { type CommandSpec, type CompletionContextLookup, walkProgram } from "./walk.js";
+
+/** Bitmask of post-processing hints for the shell shim (Cobra-style). */
+export const Directive = {
+  /** Use the returned candidates as completion values. */
+  Default: 0,
+  /** No candidates apply here — the shell should fall back to file completion. */
+  File: 1,
+} as const;
+
+export interface Candidate {
+  value: string;
+  description?: string;
+}
+
+export interface CompletionResult {
+  candidates: Candidate[];
+  directive: number;
+}
+
+/** Provider runner injected by the host CLI (same contract as `__complete`). */
+export type CompletionProviderRunner = (provider: string, partial: string) => Promise<string[]>;
+
+interface PathTables {
+  subcommandsByPath: Map<string, CommandSpec[]>;
+  /** path → flag (long or short) → spec, for both forms. */
+  optionsByPath: Map<string, CommandSpec["options"]>;
+  positionalsByPath: Map<string, CommandSpec["positionals"]>;
+}
+
+function buildTables(root: CommandSpec): PathTables {
+  const subcommandsByPath = new Map<string, CommandSpec[]>();
+  const optionsByPath = new Map<string, CommandSpec["options"]>();
+  const positionalsByPath = new Map<string, CommandSpec["positionals"]>();
+  const walk = (s: CommandSpec): void => {
+    subcommandsByPath.set(s.path, s.subcommands);
+    optionsByPath.set(s.path, s.options);
+    positionalsByPath.set(s.path, s.positionals);
+    for (const sub of s.subcommands) walk(sub);
+  };
+  walk(root);
+  return { subcommandsByPath, optionsByPath, positionalsByPath };
+}
+
+function optionAt(tables: PathTables, path: string, flag: string) {
+  const opts = tables.optionsByPath.get(path) ?? [];
+  return opts.find((o) => o.long === flag || o.short === flag);
+}
+
+function isKnownSubcommand(tables: PathTables, path: string, name: string): boolean {
+  return (tables.subcommandsByPath.get(path) ?? []).some((c) => c.name === name);
+}
+
+/**
+ * Walk the words before the cursor to determine the current command path,
+ * skipping options and the values they consume (mirrors the static driver).
+ * Returns the resolved command path ("" = root).
+ */
+function resolvePath(tables: PathTables, words: string[], cword: number): string {
+  let path = "";
+  let i = 1; // words[0] is the bin name
+  while (i < cword) {
+    const w = words[i] ?? "";
+    if (w.startsWith("-")) {
+      const opt = optionAt(tables, path, w);
+      if (opt?.takesValue) i += 1; // skip the option's value
+    } else if (isKnownSubcommand(tables, path, w)) {
+      path = path ? `${path} ${w}` : w;
+    }
+    i += 1;
+  }
+  return path;
+}
+
+/** Count positional args consumed at the resolved path (non-option, non-subcommand words). */
+function positionalIndex(tables: PathTables, words: string[], cword: number): number {
+  let seen = "";
+  let after = 0;
+  let j = 1;
+  while (j < cword) {
+    const w = words[j] ?? "";
+    if (w.startsWith("-")) {
+      const opt = optionAt(tables, seen, w);
+      if (opt?.takesValue) j += 1;
+    } else if (isKnownSubcommand(tables, seen, w)) {
+      seen = seen ? `${seen} ${w}` : w;
+    } else {
+      after += 1;
+    }
+    j += 1;
+  }
+  return after;
+}
+
+/** Resolve the value source (enum / dynamic-provider / file) for a value slot. */
+async function valueCandidates(
+  source: { valueChoices?: string[]; dynamicProvider?: string },
+  partial: string,
+  runProvider: CompletionProviderRunner,
+): Promise<CompletionResult> {
+  if (source.dynamicProvider) {
+    try {
+      const values = await runProvider(source.dynamicProvider, partial);
+      return { candidates: values.map((value) => ({ value })), directive: Directive.Default };
+    } catch {
+      return { candidates: [], directive: Directive.File };
+    }
+  }
+  if (source.valueChoices && source.valueChoices.length > 0) {
+    return {
+      candidates: source.valueChoices.map((value) => ({ value })),
+      directive: Directive.Default,
+    };
+  }
+  // A value is expected but we have nothing to suggest → let the shell try files.
+  return { candidates: [], directive: Directive.File };
+}
+
+/**
+ * Compute completion candidates for `words` with the cursor at `cword`.
+ * `words[0]` is the bin name; `words[cword]` is the (possibly empty) token
+ * being completed. The shell shim does the final prefix-filtering against that
+ * token, so this returns the full candidate set for the slot.
+ */
+export async function resolveCompletions(
+  program: Command,
+  words: string[],
+  cword: number,
+  lookup: CompletionContextLookup,
+  runProvider: CompletionProviderRunner,
+): Promise<CompletionResult> {
+  const tables = buildTables(walkProgram(program, lookup));
+  const path = resolvePath(tables, words, cword);
+  const cur = words[cword] ?? "";
+  const prev = cword > 0 ? (words[cword - 1] ?? "") : "";
+
+  // Case 1: previous word is an option that takes a value → complete the value.
+  if (prev.startsWith("-")) {
+    const opt = optionAt(tables, path, prev);
+    if (opt?.takesValue) return valueCandidates(opt, cur, runProvider);
+  }
+
+  // Case 2: completing an option name (cur starts with "-").
+  if (cur.startsWith("-")) {
+    const opts = tables.optionsByPath.get(path) ?? [];
+    const candidates: Candidate[] = [];
+    for (const o of opts) {
+      if (o.long) candidates.push({ value: o.long, description: o.description });
+      if (o.short) candidates.push({ value: o.short, description: o.description });
+    }
+    return { candidates, directive: Directive.Default };
+  }
+
+  // Case 3: subcommands available at this path → suggest them.
+  const subs = tables.subcommandsByPath.get(path) ?? [];
+  if (subs.length > 0) {
+    return {
+      candidates: subs.map((c) => ({ value: c.name, description: c.description })),
+      directive: Directive.Default,
+    };
+  }
+
+  // Case 4: positional value slot.
+  const positionals = tables.positionalsByPath.get(path) ?? [];
+  const idx = positionalIndex(tables, words, cword);
+  const pos =
+    positionals[idx] ??
+    (positionals[positionals.length - 1]?.variadic
+      ? positionals[positionals.length - 1]
+      : undefined);
+  if (pos) return valueCandidates(pos, cur, runProvider);
+
+  // Nothing structured to suggest → file completion.
+  return { candidates: [], directive: Directive.File };
+}
+
+/** Sentinel prefix for the trailing directive line in the wire protocol. */
+export const DIRECTIVE_PREFIX = "\x1f:";
+
+/**
+ * Serialize a result for the shell shim: one `value\tdescription` line per
+ * candidate, then a final `\x1f:<directive>` line. The \x1f (unit separator)
+ * prefix makes the directive line unambiguous against real candidate values.
+ */
+export function encodeResult(result: CompletionResult): string {
+  const lines = result.candidates.map((c) =>
+    c.description ? `${c.value}\t${c.description}` : c.value,
+  );
+  lines.push(`${DIRECTIVE_PREFIX}${result.directive}`);
+  return `${lines.join("\n")}\n`;
+}

package/src/lib/completion/walk.ts

@@ -84,7 +84,7 @@ function walkCommand(
   // The root program represents `harn` itself; its path stays empty so that
   // top-level subcommands have paths like "anthropic", not "harn anthropic".
   // The shell driver walks COMP_WORDS[1..], so it's already operating in
-  // post-`harn` space and shouldn't see "bp" in its lookup keys.
+  // post-`harn` space and shouldn't see the host bin name in its lookup keys.
   const path = isRoot ? "" : parentPath ? `${parentPath} ${name}` : name;
 
   const subcommands: CommandSpec[] = cmd.commands