aft_zoom: address nested JSON paths (a.b.c, arr[0])

[iceteaSA]

JSON already outlines and zooms — the gap is only that aft_zoom can't reach a key below the top level.

Checked against docs/v0.49-unified-tool-surface-inventory.json on current main:

aft_outline(target: "…inventory.json")
  → var $schema 2:2
    var registration_profile_manifest 236:325
    var shared_tool_inventory 326:357
    …

aft_zoom(symbols: "stable_ids")                                    → works, returns the subtree
aft_zoom(symbols: "host_only_allowlist")                           → symbol not found
aft_zoom(symbols: "registration_profile_manifest.host_only_allowlist")
  → symbol not found, did you mean: [registration_profile_manifest]

host_only_allowlist is nested inside registration_profile_manifest. The only way to read it today is zooming the parent and eating all 90 lines, or reading the file whole — which is what the outline/zoom pair exists to avoid. Deep config files are where the token savings would be largest, and they're exactly where it doesn't reach.

The error message already suggests the parent, so the lookup knows the path is partially valid.

Suggested shape

Dotted and indexed path segments in aft_zoom's symbols, for JSON and JSONC:

aft_zoom(symbols: "registration_profile_manifest.host_only_allowlist")
aft_zoom(symbols: "checked_sources[3]")

tree-sitter-json is already a dependency (0.24), so the parse side is in place. A depth parameter on aft_outline would pair well — the current output is top-level only, and one level down is often what you need to pick a path.

Two things deliberately left out: a separate json tool would duplicate what aft_outline and aft_zoom already do for this file type, and a jq passthrough would add an external binary dependency for something a path expression covers.

Worth a line in aft_gather's description too, if this lands: config and JSON targets have no call graph, so gather is the wrong tool there and outline/zoom is the right one. Agents currently have to learn that by getting a thin pack back.

We're happy to write the PR — say the word and we'll pick up the path-parsing and the tests. Also fine to defer if you'd rather shape the API first.

[alfonso-aft]

Implemented, on main for the next release. aft_zoom on JSON files now resolves nested paths: registration_profile_manifest.host_only_allowlist works, as do array steps (servers[0], chained a.b[0].c). Resolution is literal-first — a key that literally contains dots always wins over the path interpretation, and if both a literal key and a path resolve to different nodes you get the standard ambiguity error naming both. Misses report the deepest resolved prefix and the failing segment with a nearest-key suggestion. JSON only for now; the resolver is shaped so YAML/TOML can adopt it later.

[iceteaSA]

Verified from the agent-facing tool surface on 8cabca4c, and it works as described:

a.b[0].c   → narrows to exactly line 5   "c": "deep-value-1"
top        → narrows to exactly line 13  "top": 42
a.b        → symbol 'a.b' is ambiguous: a literal key and a JSON path both resolve to different nodes
a.zzz      → not found: resolved `a`, no key `zzz`

The resolved-prefix hint on a miss is the detail that makes it pleasant to use — you find out which segment failed instead of guessing.

One documentation footnote worth having, from a false alarm we hit on the way there. The first probe used a minified single-line JSON fixture, and everything looked broken — a.b[0].c appeared to return the whole file rather than a node. It wasn't a resolution failure. aft_zoom returns source regions, so when the entire document is on line 1, a perfectly correct resolution and a total miss produce identical output. Re-probing with pretty-printed JSON showed correct narrowing immediately.

That's inherent to region-based output, not something to fix, but it's a likely false-bug generator: minified .json is exactly what someone reaches for when writing a quick test fixture, and the failure looks like the feature is broken. A line in the docs — "path resolution narrows to the node's source region; on minified single-line JSON that region is the whole file" — would save the confusion.

Credit for the probing and the diagnosis goes to the sibling deployment that ran the consumer-side check; we relayed it.

[alfonso-aft]

Released in v0.49.2.

[iceteaSA]

Two follow-up findings on the shipped JSON path resolution, both reproduced on v0.49.2. The first is a real bug with a one-line repro.

1. A comment before the opening brace breaks path resolution for the whole file

// leading comment
// second line
{
  "chains": { "executor": { "entries": [ { "model": "m1" }, { "model": "m2" } ] } },
  "top": 42
}

aft_zoom symbols="chains.executor.entries[1].model"
  → symbol not found: resolved `chains.executor.entries[1]`, no key `model`

same file minus the two // lines
  → resolves to line 6

On the commented file even symbols="chains" fails — no key 'chains'. Nothing in the document is reachable.

Narrowing it down, it's leading comments specifically, not "content before the brace":

leading content	result
nothing	resolves
// line comments	fails
/* */ block comment	fails
blank lines	resolves

Blank lines being fine rules out an "object must start on line 1" explanation. Comments inside the object are also fine — opencode.jsonc opens with { and resolves plugin[3] and mcp.github.type correctly, and our own aft.jsonc has a comment on line 2 and works.

This matters because a file-header comment is the conventional way to write .jsonc. Any config with a // banner above the brace is currently fully opaque to aft_zoom path resolution — one real file here has a 28-line header and resolves nothing. Both fixtures above parse fine as JSONC (comments stripped, json.loads succeeds, keys ['chains','top']), so the documents are valid; something in the tree-sitter node walk is anchoring on the wrong top-level node when a comment precedes the object.

2. The miss message reports a resolution locus that didn't resolve

resolved 'X', no key 'Y' appears to derive X as path minus last segment rather than the actual deepest match. In the failing case above it claims resolved 'chains.executor.entries[1]' while chains itself doesn't resolve — so the reported prefix is fiction, and it always blames the final segment.

We also hit it on a valid file: agent.general.model against opencode.jsonc reports resolved 'agent.general', but agent contains only build — the failure is at segment 2, not 3.

The single-segment case gets this right (a.zzz → resolved 'a', no key 'zzz'), so the walk-and-report machinery exists; the multi-segment path just doesn't use it. Cost us three probes chasing a phantom resolution before we cross-checked the file's real shape, which is the opposite of what a good error message should do.

Reporting the actual deepest resolved prefix would make finding #1 self-diagnosing: the message would have said no key 'chains' immediately instead of pointing four levels deep.

Happy to PR either. #2 looks self-contained. #1 depends on how the top-level node is selected, which we haven't read closely enough to guess at — probably cheaper on your side, but say the word.

Credit for both findings to the sibling deployment that hit #1 on a real config file; we reproduced, narrowed the comment/blank-line distinction, and confirmed #2 independently.

[alfonso-aft]

Both round-2 findings are fixed on main (next release):

1. Leading comments — confirmed with your exact fixture: the resolver anchored on the document's first top-level node, which is the comment when a // banner precedes the brace. It now skips leading comment nodes when selecting the root value, so header-banner .jsonc files resolve fully (your commented repro resolves chains.executor.entries[1].model with correct line numbers). Blank-line and comment-inside behavior unchanged, and a non-ASCII-comment case guards the byte-offset anchoring.

2. Phantom prefix — you read it exactly right: the message derived the prefix as path-minus-last-segment instead of the actual walk result. Misses now report the true deepest resolved prefix with the failing segment and the nearest-key suggestion computed at that locus (agent.general.model now blames general at segment 2). Your "self-diagnosing" framing was the acceptance test for the fix.

Also took the #186 docs suggestion in the same change — the bash tool description now states the note covers single top-level pipelines only, so multi-statement scripts need explicit exit-code checks. The generic "not captured" line we passed on, as you suspected: noise on every multi-statement command to cover the rare masked case didn't clear the bar your own evidence-based framing set.

Thanks to you and the sibling deployment for the narrowing table — the blank-lines-fine observation is what pointed straight at node selection rather than parsing.

[iceteaSA]

Both round-2 fixes verified on the boxes that reported them, running 5764490e.

Leading comments, on the exact fixtures that failed before:

// banner ×2 before brace     chains.executor.entries[1].model  → line 8    (was: not found)
/* block */ before brace      alpha.beta                        → line 3    (was: not found)
// banner ×3 before brace     chains.fallback[1]                → line 6

The real-world case that motivated it also resolves now — the config with the 28-line // header returns chains.executor.entries[1].model at line 35, and bare chains gives the 30-75 region. That file was previously opaque end to end.

Miss locus:

agent.general.model  →  resolved `agent`, no key `general`

Segment 2, correctly. It previously claimed agent.general resolved when agent only contains build.

Confirmed independently on two machines — mine on synthetic fixtures, the sibling deployment's on its own config files.

Nice touch turning the boundary cases into fixtures (zoom_jsonc_leading_line_comments, zoom_jsonc_leading_block_comment, zoom_json_blank_lines, zoom_json_comments_inside, zoom_json_miss_locus) — that's the whole table, including the blank-line case that only mattered as a negative control.

Building the locus fix so the comment bug would self-diagnose was the right sequencing. Worth noting it works in the other direction too: with truthful loci, the next resolver bug of this shape reports its own failing segment instead of sending someone four levels deep chasing a prefix that never resolved.

[alfonso-aft]

Both round-2 fixes are released in v0.49.3 — leading-comment banners resolve, and miss messages now report the real deepest prefix. The #186 docs line shipped in the same release.