harnery 0.4.0 → 0.5.0

package/dist/commands/completion.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAY1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8DN"}
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../src/commands/completion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAkB1E;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAqGN"}

package/dist/commands/completion.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
-import { generateBash, generateFish, generateZsh, walkProgram, } from "../lib/completion/index.js";
+import { encodeResult, generateBash, generateBashDynamic, generateFish, generateFishDynamic, generateZsh, generateZshDynamic, resolveCompletions, walkProgram, } from "../lib/completion/index.js";
 const noopProviderRunner = async () => [];
 const noopLookup = () => undefined;
 /**
@@ -22,25 +22,35 @@ export function registerCompletionCommand(program, _emit, context) {
     const root = program
         .command("completion")
         .description("Shell tab-completion. Emit a script per shell or install to the standard location.");
+    const dynamicHint = "Emit a thin shim that calls the binary at tab-time (never goes stale; install once)";
     root
         .command("bash")
         .description("Emit bash completion script to stdout")
-        .action(() => {
-        const out = generateBash(walkProgram(program, lookup), program.name());
+        .option("--dynamic", dynamicHint)
+        .action((opts) => {
+        const out = opts.dynamic
+            ? generateBashDynamic(program.name())
+            : generateBash(walkProgram(program, lookup), program.name());
         process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
     root
         .command("zsh")
         .description("Emit zsh completion script to stdout")
-        .action(() => {
-        const out = generateZsh(walkProgram(program, lookup), program.name());
+        .option("--dynamic", dynamicHint)
+        .action((opts) => {
+        const out = opts.dynamic
+            ? generateZshDynamic(program.name())
+            : generateZsh(walkProgram(program, lookup), program.name());
         process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
     root
         .command("fish")
         .description("Emit fish completion script to stdout")
-        .action(() => {
-        const out = generateFish(walkProgram(program, lookup), program.name());
+        .option("--dynamic", dynamicHint)
+        .action((opts) => {
+        const out = opts.dynamic
+            ? generateFishDynamic(program.name())
+            : generateFish(walkProgram(program, lookup), program.name());
         process.stdout.write(out); // raw bytes: shell completion scripts must be unframed (consumer evals stdout).
     });
     root
@@ -49,6 +59,7 @@ export function registerCompletionCommand(program, _emit, context) {
         .option("--shell <name>", "bash | zsh | fish (default: auto-detect from $SHELL)")
         .option("--path <file>", "Override destination path")
         .option("--print-path", "Print the destination path and exit (no write)")
+        .option("--dynamic", `${dynamicHint} (recommended)`)
         .action(async (opts) => {
         await installCompletion(program, opts, lookup);
     });
@@ -72,6 +83,26 @@ export function registerCompletionCommand(program, _emit, context) {
     });
     // Keep TS happy that the variable is used.
     void hidden;
+    // Hidden internal entry for DYNAMIC completion: the thin shim passes the live
+    // command line (cursor index + all words after `--`) and we compute the full
+    // candidate set from the live command tree. `--` stops option parsing so
+    // words like `-h` reach the variadic instead of being read as our flags.
+    const hiddenLine = program
+        .command("__complete-line <cword> [words...]", { hidden: true })
+        .description("Internal: full-line completion callback for the dynamic shell shim")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .action(async (cword, words) => {
+        try {
+            const result = await resolveCompletions(program, words ?? [], Number.parseInt(cword, 10) || 0, lookup, runProvider);
+            process.stdout.write(encodeResult(result)); // lint-ok-emission: shell callback; the encoded candidate/directive stream is the contract with the shim.
+        }
+        catch {
+            // Never break the user's tab: emit just the file-fallback directive.
+            process.stdout.write("\x1f:1\n"); // lint-ok-emission: shell callback fallback directive.
+        }
+    });
+    void hiddenLine;
 }
 async function installCompletion(program, opts, lookup) {
     const shell = opts.shell ?? detectShell();
@@ -84,16 +115,23 @@ async function installCompletion(program, opts, lookup) {
         process.stdout.write(`${destination}\n`); // lint-ok-emission: --print-path is meant to be piped (e.g., dest=$(harn completion install --print-path)).
         return;
     }
+    const name = program.name();
     let content;
     switch (shell) {
         case "bash":
-            content = generateBash(walkProgram(program, lookup), program.name());
+            content = opts.dynamic
+                ? generateBashDynamic(name)
+                : generateBash(walkProgram(program, lookup), name);
             break;
         case "zsh":
-            content = generateZsh(walkProgram(program, lookup), program.name());
+            content = opts.dynamic
+                ? generateZshDynamic(name)
+                : generateZsh(walkProgram(program, lookup), name);
             break;
         case "fish":
-            content = generateFish(walkProgram(program, lookup), program.name());
+            content = opts.dynamic
+                ? generateFishDynamic(name)
+                : generateFish(walkProgram(program, lookup), name);
             break;
         default:
             process.stderr.write(`Unknown shell: ${shell}\n`); // lint-ok-emission: install-time error, see above.

package/dist/core/agents/rules/claim-conflict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CAiFjF"}
+{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CAyFjF"}

package/dist/core/agents/rules/claim-conflict.js

@@ -62,7 +62,15 @@ export function evaluateClaim(coordRoot, req) {
     // single-agent flow can't deadlock with itself, and the rule otherwise
     // forces release-and-reacquire cycles on every reverse-order edit pair.
     const hasFreshPeers = otherPeers.some((p) => isFresh(p.last_heartbeat) && p.files_touched.length > 0);
-    if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0) {
+    // Re-editing a path already in our own files_touched acquires no new lock
+    // edge, so it can't create a circular wait — the ordering rule must not block
+    // it. Without this exemption, an agent that edits a higher-sorting file and
+    // then makes a second pass over an already-held lower-sorting file gets a
+    // spurious ordering_violation (the dominant friction source under concurrency:
+    // both agent-Gibson holding README.md and agent-Ophelia holding AGENTS.md were
+    // blocked re-editing those held files after touching a higher path, 2026-07-03).
+    const alreadyHeld = myPeer?.files_touched.includes(req.path) ?? false;
+    if (hasFreshPeers && myPeer && myPeer.files_touched.length > 0 && !alreadyHeld) {
         // Only ACTIVE (uncommitted) edits should constrain lock ordering. A claim on
         // a committed-clean file is a finished edit, not a held lock, so it must not
         // wall off a lower-sorted acquisition. Without this, a long session
@@ -79,7 +87,7 @@ export function evaluateClaim(coordRoot, req) {
                     allow: false,
                     exit_code: 2,
                     rule: "claim.ordering_violation",
-                    reason: `Cannot acquire ${req.path} while holding ${highest} (claim ordering rule: paths must be acquired in sorted order). Release the higher claim first.`,
+                    reason: `Cannot acquire ${req.path}: you already hold ${highest}, which sorts after it (claim ordering rule: acquire paths in sorted order to prevent deadlock between concurrent agents). Fix by editing in sorted order, or by committing ${highest} first, since a committed-clean file no longer blocks and is auto-pruned.`,
                 };
             }
             // Every blocker is a finished (committed-clean) edit: prune them so they

package/dist/core/hooks/cli.js

@@ -28,6 +28,7 @@ import { projectHeartbeats } from "../agents/state/heartbeat-projector.js";
 import { shellMutationPaths } from "../agents/state/shell-mutation.js";
 import { captureImages, detectPresence, imageJanitor, playSound, resetSoundCounters, runTurnSummary, scratchArchive, scratchJanitor, scratchRecoveryCue, soundForEvent, syncClaudeSessions, } from "./effects/index.js";
 import { emit } from "./events/emit.js";
+import { canonicalize } from "./guard-path.js";
 import { detectHarness } from "./harness/detect.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./harness/parse.js";
 import { parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
@@ -688,7 +689,9 @@ async function main() {
 }
 async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, harness) {
     const toolName = data.tool_name ?? "";
-    const targets = collectGuardTargets(toolName, data).map((p) => canonicalize(coordRoot, p));
+    const targets = collectGuardTargets(toolName, data)
+        .map((p) => canonicalize(coordRoot, p))
+        .filter((p) => p !== null);
     if (targets.length === 0)
         return;
     const agentCoordBin = join(coordRoot, "harnery", "bin", "agent-coord");
@@ -737,15 +740,6 @@ async function runPreToolUseGuard(coordRoot, instanceId, sessionId, data, harnes
 /** Canonicalize a path to monorepo-relative form. Absolute paths under
  * coordRoot get the prefix stripped; relative paths pass through (assumed
  * already canonical). */
-function canonicalize(coordRoot, p) {
-    if (!p)
-        return p;
-    if (p.startsWith(`${coordRoot}/`))
-        return p.slice(coordRoot.length + 1);
-    if (p === coordRoot)
-        return ".";
-    return p;
-}
 /** Pull the candidate path(s) out of a write-tool payload. Empty array when
  * the tool isn't a write or no path could be derived. */
 function collectGuardTargets(toolName, data) {

package/dist/core/hooks/guard-path.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 declare function canonicalize(coordRoot: string, p: string): string | null;
+//# sourceMappingURL=guard-path.d.ts.map

package/dist/core/hooks/guard-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-path.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/guard-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE"}

package/dist/core/hooks/guard-path.js

@@ -0,0 +1,38 @@
+/**
+ * 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, p) {
+    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/dist/lib/completion/bash.d.ts

@@ -22,4 +22,19 @@
  */
 import type { CommandSpec } from "./walk.js";
 export declare function generateBash(root: CommandSpec, binName: string): string;
+/**
+ * The driver: the parts of the completion that don't depend on the command
+ * tree. Walks COMP_WORDS to determine the current command path, then dispatches
+ * 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 declare function generateBashDynamic(binName: string): string;
 //# sourceMappingURL=bash.d.ts.map

package/dist/lib/completion/bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/bash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAuBzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2FvE"}
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/bash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA8B,MAAM,WAAW,CAAC;AAuBzE,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CA2FvE;AAqBD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA0B3D"}

package/dist/lib/completion/bash.js

@@ -155,6 +155,41 @@ function bashEscape(s) {
  * 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) {
+    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, binName) {
     return `${fn}() {
   local cur prev words cword

package/dist/lib/completion/fish.d.ts

@@ -12,5 +12,15 @@
  * giving us per-tab callbacks for free.
  */
 import type { CommandSpec } from "./walk.js";
+/**
+ * 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 declare function generateFishDynamic(binName: string): string;
 export declare function generateFish(root: CommandSpec, binName: string): string;
 //# sourceMappingURL=fish.d.ts.map

package/dist/lib/completion/fish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fish.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/fish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAuD7C,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgEvE"}
+{"version":3,"file":"fish.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/fish.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAuD7C;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAW3D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAgEvE"}

package/dist/lib/completion/fish.js

@@ -55,6 +55,27 @@ function valueAction(opt, binName) {
     }
     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) {
+    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, binName) {
     const out = [];
     out.push(`# ${binName} fish completion, generated by \`${binName} completion fish\`. Do not edit.`);

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

@@ -1,5 +1,6 @@
-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, type OptionSpec, type PositionalSpec, walkProgram, } from "./walk.js";
-export { generateZsh } from "./zsh.js";
+export { generateZsh, generateZshDynamic } from "./zsh.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EACL,KAAK,SAAS,EACd,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,EACrB,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,uBAAuB,EAC5B,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,WAAW,GACZ,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}

package/dist/lib/completion/index.js

@@ -1,4 +1,5 @@
-export { generateBash } from "./bash.js";
-export { generateFish } from "./fish.js";
+export { generateBash, generateBashDynamic } from "./bash.js";
+export { generateFish, generateFishDynamic } from "./fish.js";
+export { DIRECTIVE_PREFIX, Directive, encodeResult, resolveCompletions, } from "./resolve.js";
 export { walkProgram, } from "./walk.js";
-export { generateZsh } from "./zsh.js";
+export { generateZsh, generateZshDynamic } from "./zsh.js";

package/dist/lib/completion/resolve.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 CompletionContextLookup } from "./walk.js";
+/** Bitmask of post-processing hints for the shell shim (Cobra-style). */
+export declare const Directive: {
+    /** Use the returned candidates as completion values. */
+    readonly Default: 0;
+    /** No candidates apply here — the shell should fall back to file completion. */
+    readonly File: 1;
+};
+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[]>;
+/**
+ * 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 declare function resolveCompletions(program: Command, words: string[], cword: number, lookup: CompletionContextLookup, runProvider: CompletionProviderRunner): Promise<CompletionResult>;
+/** Sentinel prefix for the trailing directive line in the wire protocol. */
+export declare const DIRECTIVE_PREFIX = "\u001F:";
+/**
+ * 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 declare function encodeResult(result: CompletionResult): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/lib/completion/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../src/lib/completion/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAoB,KAAK,uBAAuB,EAAe,MAAM,WAAW,CAAC;AAExF,yEAAyE;AACzE,eAAO,MAAM,SAAS;IACpB,wDAAwD;;IAExD,gFAAgF;;CAExE,CAAC;AAEX,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AAiGhG;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,uBAAuB,EAC/B,WAAW,EAAE,wBAAwB,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA4C3B;AAED,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,YAAU,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAM7D"}

package/dist/lib/completion/resolve.js

@@ -0,0 +1,171 @@
+/**
+ * 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 { 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,
+};
+function buildTables(root) {
+    const subcommandsByPath = new Map();
+    const optionsByPath = new Map();
+    const positionalsByPath = new Map();
+    const walk = (s) => {
+        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, path, flag) {
+    const opts = tables.optionsByPath.get(path) ?? [];
+    return opts.find((o) => o.long === flag || o.short === flag);
+}
+function isKnownSubcommand(tables, path, name) {
+    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, words, cword) {
+    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, words, cword) {
+    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, partial, runProvider) {
+    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, words, cword, lookup, runProvider) {
+    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 = [];
+        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) {
+    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/dist/lib/completion/zsh.d.ts

@@ -10,4 +10,12 @@
  */
 import type { CommandSpec } from "./walk.js";
 export declare function generateZsh(root: CommandSpec, binName: string): string;
+/**
+ * DYNAMIC zsh completion: a thin, tree-independent shim that calls
+ * `<bin> __complete-line` on every <Tab> (see bash.ts generateBashDynamic for
+ * the rationale). Candidate lines are `value\tdescription`; the shim converts
+ * the tab to `:` so `_describe` renders descriptions. The trailing `\x1f:<n>`
+ * line carries the directive (bit 0 = file fallback → `_files`).
+ */
+export declare function generateZshDynamic(binName: string): string;
 //# sourceMappingURL=zsh.d.ts.map