@allocator-one/harness-cli 1.16.0 → 1.17.1

package/README.md

@@ -927,6 +927,129 @@ refusal exits 1 with the server's message and what it means
 answers a capability that doesn't exist, ships disabled, or is switched off
 with the same 404.
 
+## Code index
+
+```sh
+harness code sync                    # sync this worktree’s overlay
+harness code sync --path ../app      # use that worktree’s host/org config
+harness code status --json           # active version and local freshness
+harness code status --skipped        # include the base’s skipped-files report
+```
+
+The repository must be shared through the organization’s Harness GitHub
+connection and code indexing must be enabled for that org. The server builds
+commit bases from GitHub. The CLI polls a fetching base with backoff, opens an
+overlay sync, uploads only blobs that sync requests, and activates it. It never
+uploads a base or follows source symlinks. A successful sync reports the server’s
+state; `queued` means indexing has been requested, not that queries are ready.
+Safe source reads require macOS 11 or later, or Linux with `/proc/self/fd`;
+code sync refuses when these kernel facilities are unavailable.
+
+Sync needs both `harness:read` and `harness:write`; ordinary `code status`
+needs `harness:read`, and base-status requests also need `harness:write`. `--skipped` on sync or status asks the server for its base
+exclusions (path and reason). Local binary, oversized, ignored and secret-shaped
+files are excluded before upload. Built-in secret rules cannot be removed by
+an ignore-file negation. Deny and secret-path matches use ASCII case-insensitive
+checks; path identities are preserved. Served content expressions must exactly
+match the reviewed sources bundled with this client, or be literal-only markers
+matched as substrings. Other expressions stop sync with an upgrade message before
+source scanning. Source content is never included in diagnostics.
+
+`.harnesscodeignore` uses the code-index policy dialect, not Git's ignore
+grammar: each line is trimmed; `#` and `!` lines are skipped; and a backslash
+is literal. The CLI reports warnings for skipped `!` lines and backslashes.
+Patterns are case-sensitive, limited to 256 bytes and eight `*` characters,
+and an ignore file has at most 1,000 patterns and 64 KiB. Matching uses the
+server's UTF-8 byte semantics (`?` matches one byte), ASCII-only case folding
+for deny globs, and linear-time wildcard matching. Unicode whitespace is trimmed;
+a byte-order mark is literal. The client refuses ignore files above 64 KiB and
+Git metadata above 16 MiB. The server's indexed extensions are exact, so `.TS`
+is distinct from `.ts`.
+
+The working copy's `.harnesscodeignore` governs its view. The CLI compares it with
+the committed ignore file: newly ignored base paths become delete entries, and
+newly included files are read from the worktree through the usual policy checks.
+It never reads unchanged source content from the base. If ignore changes exceed
+20,000 overlay paths, commit the ignore file so the server-built base honors it.
+
+View/session state is isolated by server, organization, repository and worktree
+under the user’s cache directory. `HARNESS_CODE_STATE_DIR` overrides the directory
+and must be absolute when non-empty (an empty override is unset). It stores control metadata and hashes, not source bytes or
+tokens. Retrying the same interrupted overlay reuses its client ID. An uncertain
+activation retains its opened sync ID and timestamp; the CLI reads that sync and
+records its original pending version once it is no longer receiving. A missing sync
+is treated as a replaced, never-activated sync only within 60 minutes; an older
+missing sync fails closed. The server keeps a client ID unique per view and
+manifest across states, so the CLI never uses one for a different manifest. A stale
+policy is fetched again and the overlay rescanned. Syncs of the same local view are serialized: a
+second sync is refused while one is running, because opening a sync can replace older
+unactivated syncs on the server. If the process is forcibly interrupted, its error
+message names the lock directory; remove it only after confirming no sync is running.
+The server refuses overlays above 20,000 paths; sync against a newer base commit. A failed index is reported as `failed` with exit
+code 1. A worktree with no active or pending version, or a removed cached view,
+is `not_synced`; an existing active snapshot that no longer matches is `stale`.
+An activation receipt records an assigned version, including a superseded or
+failed one; only `code status` reporting `current` proves that the indexed active
+version matches the local snapshot.
+
+### Query the active view
+
+```sh
+harness code search 'process' --kind function --limit 20
+harness code explain 'OPAQUE_ID_FROM_SEARCH' --budget-tokens 4000
+harness code affected --symbol 'OPAQUE_ID' --file src/app.ts --depth 3
+harness code context --symbol 'OPAQUE_ID' --budget-tokens 2000 --json
+harness code context 'name' --path ../app
+```
+
+Queries need `harness:read` and an existing view from `code sync`. They read its
+active version, even while a later version is pending. The output includes base
+commit, overlay digest, active version and pending progress. Querying neither
+scans nor uploads local source. No code-index MCP tools are registered.
+
+Human output cites `path:line@sha256`, indexed snippets, version and base/overlay
+origin. Search citations may lack snippet text: use `context` to retrieve it.
+Context items that exceed the budget remain citations explicitly lacking text.
+JSON preserves server `data` and `meta`, adding a `guidance` array. Resolved,
+possible, name-only and unresolved references remain separate. A snippet budget
+covers the server's indexed text, not command formatting or metadata.
+
+Contract 1.3 `meta.truncation` is always displayed: the returned count, the total
+if the server supplies it, limits and next command or narrowing hint. The CLI
+never invents a total or silently pages beyond the request. A `not_tracked`
+coverage answer gives a local `rg` hint instead of asserting there are no callers.
+Results cite the indexed snapshot; inspect the current file before editing it.
+
+IDs are opaque. Swift IDs include declaration positions and can stop resolving
+when an edit moves a declaration; qualified names can include argument labels.
+Do not parse or reconstruct either. `not_found` asks you to search again, rather
+than blindly retrying an old symbol. `--include-ambiguous` and `--include-types`
+explicitly expand the affected walk; without them, possible/type impact is
+reported separately. Limits are bounded (search 1–100; depth 1–6; at most 200
+seeds; snippet budget 100–16,000, or 100–32,000 for context).
+
+### Agent Skill
+
+The portable source of truth ships as `skills/harness-code/SKILL.md` in both npm
+packages. Copy it into your consumer repo's skill tree, following that repo's
+adapters and metadata conventions. For an agent that discovers `.agents/skills`:
+
+```sh
+mkdir -p .agents/skills
+cp -R "$(npm root -g)/@allocator-one/harness-cli/skills/harness-code" .agents/skills/
+```
+
+A short `AGENTS.md`/`CLAUDE.md` snippet:
+
+> For symbol relationships, callers, impact and cited context, use the
+> harness-code skill and `harness code search/explain/affected/context`. Start
+> with `code status`; use `rg` for literal text and `not_tracked` coverage.
+> Report truncation and indexed hashes/versions; search again after missing IDs.
+
+Allocator-one adoption and a paired agent tool-use comparison against a grep-only
+baseline are delivered in the consumer follow-up to CLI-70, before publication.
+
+
 ## Uploads
 
 `harness upload <path>` uploads a file and prints a markdown reference to

package/dist/{chunk-FQWV5MIC.js → chunk-5THYIKLW.js}

@@ -11,14 +11,34 @@ var CLI_PACKAGE = pkg.name;
 // src/invocation.ts
 import { basename } from "path";
 var OPERATOR_PACKAGE = "@allocator-one/operator";
-function invokedName(argv1 = process.argv[1], packageName = CLI_PACKAGE) {
+var INFRAONE_PACKAGE = "@allocator-one/infraone";
+var PACKAGES = {
+  harness: "@allocator-one/harness-cli",
+  operator: OPERATOR_PACKAGE,
+  infraone: INFRAONE_PACKAGE
+};
+var operatorMount = false;
+function mountOperatorUnderInfraone() {
+  operatorMount = true;
+}
+function operatorMounted() {
+  return operatorMount;
+}
+function invokedName(argv1 = process.argv[1], packageName = CLI_PACKAGE, infraoneBinary = typeof __INFRAONE_BINARY__ !== "undefined" && __INFRAONE_BINARY__ === true) {
+  if (operatorMount) return "operator";
+  if (infraoneBinary) return "infraone";
   const typed = basename(argv1 ?? "").replace(/\.[cm]?js$/i, "").toLowerCase();
-  if (typed === "operator" || typed === "harness") return typed;
-  return packageName === OPERATOR_PACKAGE ? "operator" : "harness";
+  if (typed === "operator" || typed === "harness" || typed === "infraone") return typed;
+  if (packageName === OPERATOR_PACKAGE) return "operator";
+  return packageName === INFRAONE_PACKAGE ? "infraone" : "harness";
 }
 function named(text, name = invokedName()) {
   if (name === "harness") return text;
-  return text.replace(/^harness: /gm, `${name}: `).replace(/(?<![\w@/.-])harness (?=[a-z])(?!disagree)/g, `${name} `).replaceAll("@allocator-one/harness-cli", OPERATOR_PACKAGE);
+  if (name === "operator" && operatorMount) return mountedNamed(text);
+  return text.replace(/^harness: /gm, `${name}: `).replace(/(?<![\w@/.-])harness (?=[a-z])(?!disagree)/g, `${name} `).replaceAll(PACKAGES.harness, PACKAGES[name]);
+}
+function mountedNamed(text) {
+  return text.replace(/^(?:harness|operator): /gm, "infraone: ").replace(/(?<![\w@/.-])(?<!infraone )(?:harness|operator) (?=[a-z[<])(?!disagree)/g, "infraone operator ").replaceAll(PACKAGES.harness, INFRAONE_PACKAGE).replaceAll(OPERATOR_PACKAGE, INFRAONE_PACKAGE);
 }
 var OPERATOR_COMMANDS = [
   "run",
@@ -67,6 +87,8 @@ export {
   CLI_VERSION,
   CLI_PACKAGE,
   OPERATOR_PACKAGE,
+  mountOperatorUnderInfraone,
+  operatorMounted,
   invokedName,
   named,
   layoutOperatorHelp