Skip to content

JAM v1.8.0

Latest

Choose a tag to compare

@github-actions github-actions released this 10 Sep 08:44
eecdecc

JAM v1.8.0 — asking a command what it does, and being told which limit was hit

What changed

--help no longer runs the command. Measured on a real machine: a person
typed jam setup --help expecting documentation. The setup wizard ran. It
re-registered JAM with two hosts and moved the recorded registration from one
version to another, while they were reading what they thought was a description
of what the command would do.

The cause was narrow and the reach was not. --help was recognised only as a
command in its own right, so a help flag arriving after a subcommand was just
another argument and fell through to the handler. Every mutating path in the
dispatcher was reachable this way:

jam setup --help              ran the wizard
jam update --help             ran the update
jam refresh --help            re-registered
jam uninstall --help          removed the registration
jam auth login --help         started the credential flow
jam runtime use … --help      rewrote the runtime selection
jam jira write-apply … --help applied the plan

The guard is now in the dispatcher, before the switch, and it looks at every
argument rather than the first. The launcher answers runtime before dispatching,
so it has its own.

There is deliberately no per-command list. A list of commands that must be
protected is a list that will be missing the next command somebody adds; the
dispatcher is the one place all of them pass through.

Completeness says which limit was reached. Three situations were collapsing
into two codes, and two of those readings were wrong:

a preview that stopped at page one       PARTIAL_API_RESPONSE   (wrong)
a complete walk that hit the page cap    OUTPUT_BUDGET          (wrong)
a result larger than the token budget    reported in notes      (right)

PARTIAL_API_RESPONSE says Jira answered with less than it was asked for. A
preview is the caller getting exactly what they asked for — one page, on
purpose. OUTPUT_BUDGET says something was dropped to fit a size; the page cap
is about how far the read walked, and nothing was trimmed.

They now have their own names, and the meta carries what a caller needs to act:

PREVIEW_LIMIT      one page by request  →  ask again with scope="complete"
PAGINATION_LIMIT   the safety cap       →  narrow the JQL
moreAvailable      is there more after what you got
returnedCount      how many you got

The third was already right and is now pinned: a result can be complete and
still be larger than you want, and saying so must not turn complete false.

Pagination stays inside JAM. No continuation token reaches the caller
through any field. Handing one out would move paging to the agent, which is the
boundary this exists to hold.

Gate

npm test          582 pass · 0 fail
npm run release:check   clean
CI                ubuntu + windows, node 20 and 22, all green

New fixtures:

help-no-side-effect.test.ts       31  every mutating dispatcher path × --help and -h,
                                      asserting the mutating modules were not called
completeness-semantics.test.ts     7  each situation separately, both at once, and
                                      "no continuation token reaches the caller"

What an independent review checked and did not find

The review looked for a way past the help gate through argument order, through a
subcommand parsing its own flags first, and through the launcher path. It found
none: the gate runs before the switch, and the launcher's own runtime group has
a matching one. It also confirmed no continuation token can escape through a
nested field, and that PREVIEW_LIMIT and PAGINATION_LIMIT cannot be confused
— a preview caps pages at one, so the pagination flag is structurally
unreachable there.

Install / Upgrade

jam update

Moves this machine's registration to the published release. It does not re-plan
the project binding — that is jam setup's job.

First run on a machine with no JAM:

npx --yes @jam-mcp/bootstrap@1.8.0 setup --agent

Agent setup

Unchanged from 1.7.0.

npx --yes @jam-mcp/bootstrap@1.8.0 setup --agent
jam status --json

Compatibility

Node >= 20. The three packages ship in lockstep at 1.8.0 and depend on each
other at that exact version.

No state change on disk. Nothing in ~/.jam is read or written differently.

One behaviour change a caller can see. A command that carries --help or
-h now prints usage and exits 0 instead of running. Any script that relied on
a help flag being ignored will stop doing the thing it was doing — which is the
point, and is the safe direction to fail in.

Two IncompleteReason values are new — PREVIEW_LIMIT and
PAGINATION_LIMIT — and two CompletenessMeta fields are added,
moreAvailable and returnedCount. A consumer that switches exhaustively on
reason will see values it does not know. The old values are not removed;
searches that used to report PARTIAL_API_RESPONSE or OUTPUT_BUDGET for these
two situations now report the new ones instead.

Verified

npx tsc --noEmit        green
npm test                582 pass / 0 fail
npm run build           green
npm run release:check   consistent across manifests, code and docs
CI                      pr-title + ubuntu/windows × node 20/22, all green

Behaviour, in the suite rather than against a live site — each mutating
dispatcher path is driven with the mutating modules replaced by spies, so the
assertion is that they were not called at all:

every mutating command × --help     usage printed, no mutator called
every mutating command × -h         usage printed, no mutator called
the same commands without a flag    the command runs as before
jam help / --help / -h              unchanged

Not run against real Jira: this release changes no Jira interaction. The
completeness work was verified against a fake Jira that pages, which is where
the page-cap and preview boundaries actually live.

Known limitations

The two new meta fields are optional in the type. moreAvailable and
returnedCount are always populated today, because one place builds a search
meta and it fills both unconditionally. The type does not enforce that. A caller
seeing undefined cannot distinguish "nothing more" from "not reported", and a
second construction site could reintroduce the ambiguity silently.

Usage text goes to stdout from the server and stderr from the launcher. The
launcher holds stdout for the MCP protocol on every path; the server has always
written usage to stdout. This release did not unify them.

The reported incident was not reproduced. Re-running jam setup --help
against the broken build would change this machine's registration again. What
was verified is that the old dispatcher structure routes setup --help to the
wizard, and that the new one does not.

MCP/CLI parity was not audited end to end. The --help path is closed on
the CLI side only.