@jam-mcp/server 1.3.1 → 1.4.0

package/README.md

@@ -74,10 +74,10 @@ auth login   Store Jira credentials in this user's OS secret store
 runtime      Show or change which JAM build this machine runs
 ```
 
-Written out, that is `npx --yes @jam-mcp/launcher@1.3.1 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.4.0 doctor`, or just `jam
 doctor` if you took the launcher's optional global install. Starting from
 nothing — no install, no runtime chosen yet — use
-`npx --yes @jam-mcp/bootstrap@1.3.1 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.4.0 init` instead.
 
 Credentials come from the process environment or this user's OS secret store —
 never from a repository file — and never appear in logs, telemetry, or tool

package/dist/adapters/credentials/secret-store.d.ts

@@ -22,8 +22,13 @@ export type RunResult = {
     stderr: string;
     error?: NodeJS.ErrnoException;
 };
-/** Injected by tests so the suite never touches a real keychain. */
-export type RunFn = (command: string, args: string[], input?: string) => RunResult;
+/**
+ * Injected by tests so the suite never touches a real keychain.
+ *
+ * `env` is merged over the inherited environment, and carries only values that
+ * are not secret - a file path, say. Secrets travel on stdin.
+ */
+export type RunFn = (command: string, args: string[], input?: string, env?: Record<string, string>) => RunResult;
 export interface SecretStore {
     /** Shown by `jam auth login`. Names the mechanism, never a value. */
     readonly label: string;

package/dist/adapters/credentials/secret-store.js

@@ -30,10 +30,11 @@ export function secretStoreDisabled(env = process.env) {
 function account() {
     return userInfo().username;
 }
-function defaultRun(command, args, input) {
+function defaultRun(command, args, input, env) {
     const result = spawnSync(command, args, {
         encoding: "utf8",
         ...(input === undefined ? {} : { input }),
+        ...(env === undefined ? {} : { env: { ...process.env, ...env } }),
         // No shell: arguments are passed as an array, so nothing is re-parsed.
         windowsHide: true,
     });
@@ -138,43 +139,94 @@ function linuxStore(run) {
  * Kept separate from ~/.jam/config.yaml, which declares itself hand-editable
  * and free of credentials.
  */
+/**
+ * Both scripts need DPAPI, and both must survive a host that rewrote where
+ * PowerShell looks for modules.
+ *
+ * A CI runner does exactly that - it prepends its own paths, including ones
+ * belonging to a different PowerShell edition, and then Windows PowerShell 5.1
+ * either cannot resolve `ConvertTo-SecureString` at all or trips over type data
+ * from a module that was never meant for it. Neither failure says anything
+ * about credentials, so both look like a JAM bug to whoever reads them.
+ *
+ * So the child starts from the machine's own module path and asks for the
+ * module by name. This changes nothing outside that one short-lived process.
+ */
+const IMPORT_SECURITY = "$env:PSModulePath=[Environment]::GetEnvironmentVariable('PSModulePath','Machine');" +
+    "Import-Module Microsoft.PowerShell.Security -ErrorAction Stop;";
+/**
+ * What the child writes, we read as UTF-8 - so say so before it writes anything.
+ *
+ * `spawnSync` is told `encoding: "utf8"`, but powershell.exe writes through the
+ * console code page, which on a Korean install is 949. The bytes and the decoder
+ * then disagree and an error message arrives as mojibake: the user is handed a
+ * failure they cannot even read. Setting the output encoding inside the child
+ * changes nothing outside it.
+ */
+const UTF8_OUTPUT = "[Console]::OutputEncoding=[Text.Encoding]::UTF8;" +
+    "$OutputEncoding=[Text.Encoding]::UTF8;";
+/**
+ * Read stdin as UTF-8, by saying so on the stream rather than on the console.
+ *
+ * `[Console]::In` on Windows PowerShell 5.1 is already bound to the console
+ * input code page by the time a `-Command` script could change it, so a value
+ * with non-ASCII in it - a Jira account under a Korean name, say - arrived
+ * mangled and was then encrypted mangled. Opening the standard input stream
+ * with an explicit encoding sidesteps that entirely.
+ */
+const READ_STDIN_UTF8 = "$in=(New-Object IO.StreamReader(" +
+    "[Console]::OpenStandardInput(),[Text.Encoding]::UTF8)).ReadToEnd();";
 function windowsStore(run) {
     const dir = join(homedir(), ".jam");
     const path = join(dir, "credentials.dpapi");
-    // The path reaches PowerShell as an argument, never interpolated into the
-    // script text; the secret reaches it on stdin.
+    /**
+     * The path reaches PowerShell in an environment variable, never in argv and
+     * never interpolated into the script text.
+     *
+     * It used to ride as a trailing argument with `-args`, which does not work:
+     * `powershell.exe -Command` appends what follows to the command text rather
+     * than filling `$args` - that is `-File` semantics - so the script read
+     * `$args[0]` as `$null` and `Set-Content` refused the null path. Reading was
+     * broken the same way and failed quietly, since `Test-Path $null` is false.
+     *
+     * The variable holds a path, not a secret. The secret still reaches the
+     * process on stdin and appears nowhere else.
+     */
+    const PATH_VAR = "JAM_SECRET_FILE";
     const decrypt = [
         "-NoProfile",
         "-NonInteractive",
         "-Command",
-        "$p=$args[0]; if(!(Test-Path $p)){exit 1};" +
+        UTF8_OUTPUT +
+            IMPORT_SECURITY +
+            `$p=$env:${PATH_VAR}; if(!(Test-Path $p)){exit 1};` +
             "$s=Get-Content $p -Raw | ConvertTo-SecureString;" +
             "[Runtime.InteropServices.Marshal]::PtrToStringAuto(" +
             "[Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))",
-        "-args",
     ];
     const encrypt = [
         "-NoProfile",
         "-NonInteractive",
         "-Command",
-        "$in=[Console]::In.ReadToEnd();" +
+        UTF8_OUTPUT +
+            IMPORT_SECURITY +
+            READ_STDIN_UTF8 +
             "$in | ConvertTo-SecureString -AsPlainText -Force |" +
-            " ConvertFrom-SecureString | Set-Content $args[0] -NoNewline",
-        "-args",
+            ` ConvertFrom-SecureString | Set-Content $env:${PATH_VAR} -NoNewline`,
     ];
     return {
         label: "Windows DPAPI (user-encrypted file)",
         read() {
             if (!existsSync(path))
                 return undefined;
-            const res = run("powershell", [...decrypt, path]);
+            const res = run("powershell", decrypt, undefined, { [PATH_VAR]: path });
             if (res.error || res.status !== 0)
                 return undefined;
             return parse(res.stdout.trim());
         },
         write(values) {
             mkdirSync(dir, { recursive: true });
-            const res = run("powershell", [...encrypt, path], JSON.stringify(values));
+            const res = run("powershell", encrypt, JSON.stringify(values), { [PATH_VAR]: path });
             if (res.error?.code === "ENOENT")
                 throw unavailable("powershell");
             if (res.status !== 0)

package/dist/adapters/jira-cloud/jira-read.adapter.js

@@ -45,21 +45,11 @@ export class JiraCloudReadAdapter {
         // Read straight off the raw payload rather than through the mapper: the
         // mapper's job is the shape the read tools see, and this identity is only
         // for the write plane. Raw DTOs still stop here.
-        const raw = data.fields;
-        const assignee = raw?.["assignee"];
+        const assignee = data.fields?.assignee;
         const accountId = typeof assignee?.accountId === "string" ? assignee.accountId : undefined;
-        // Only the ids that were asked for, and only when some were: a caller that
-        // did not request a custom field gets no entry rather than an empty object
-        // it has to tell apart from a field that is genuinely unset.
-        const customFieldValues = {};
-        for (const field of req.fields) {
-            if (field.startsWith("customfield_"))
-                customFieldValues[field] = raw?.[field] ?? null;
-        }
         return {
             issue: mapIssueWithMeta(data, this.config).issue,
             ...(accountId ? { assigneeAccountId: accountId } : {}),
-            ...(Object.keys(customFieldValues).length > 0 ? { customFieldValues } : {}),
             responseBytes: bytes,
         };
     }

package/dist/application/apply-write.js

@@ -1,10 +1,9 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
 import { assertAssignable } from "../policy/assignee-policy.js";
-import { assertCustomFieldUnchanged } from "../policy/custom-field-policy.js";
 import { assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
-import { currentCustomFieldView, readIssue } from "./plan-write.js";
+import { readIssue } from "./plan-write.js";
 /**
  * Execute a plan JAM made, then go and look at what happened.
  *
@@ -63,18 +62,10 @@ export async function applyWritePlan(deps, request) {
  * own state, which `assertUnchanged` already compared.
  */
 async function revalidate(deps, plan) {
-    if (plan.mutation.kind === "assignee") {
-        const target = plan.intendedAfter["assignee"];
-        assertAssignable(plan.issueKey, target, await deps.jiraAssignees.isAssignable(plan.issueKey, plan.mutation.accountId));
+    if (plan.mutation.kind !== "assignee")
         return;
-    }
-    if (plan.mutation.kind === "custom-field" && plan.customFieldRequirements) {
-        // A field can be taken off a screen, lose its `set` operation, change type
-        // or have an option renamed without the issue's own revision moving, so
-        // `assertUnchanged` cannot see any of it. These are the premises the plan
-        // actually rested on, re-derived.
-        assertCustomFieldUnchanged(plan.issueKey, plan.customFieldRequirements, await deps.jiraEditMetadata.getEditableFields(plan.issueKey));
-    }
+    const target = plan.intendedAfter["assignee"];
+    assertAssignable(plan.issueKey, target, await deps.jiraAssignees.isAssignable(plan.issueKey, plan.mutation.accountId));
 }
 /**
  * Send the mutation, once.
@@ -101,14 +92,6 @@ async function mutate(deps, plan) {
             case "assignee":
                 await deps.jiraWrite.assignIssue(plan.issueKey, plan.mutation.accountId);
                 return {};
-            case "custom-field":
-                // The ordinary issue edit endpoint. A custom field is a field; what
-                // made it need its own operation was deciding whether it may be
-                // written and in what shape, and that is already settled here.
-                await deps.jiraWrite.updateIssue(plan.issueKey, {
-                    [plan.mutation.fieldId]: plan.mutation.value,
-                });
-                return {};
             case "create":
                 // Unreachable: a create plan is routed to applyCreateIssue above. The
                 // case exists so adding a mutation kind is a compile error here rather
@@ -141,7 +124,7 @@ function isAmbiguous(err) {
  * ours.
  */
 async function verify(deps, plan) {
-    const snapshot = await readIssue(deps, plan.issueKey, plan.mutation.kind === "custom-field" ? [plan.mutation.fieldId] : []);
+    const snapshot = await readIssue(deps, plan.issueKey);
     const issue = snapshot.issue;
     if (plan.mutation.kind === "assignee") {
         // On the accountId, never on the display name. Two people can share a
@@ -173,15 +156,6 @@ async function verify(deps, plan) {
         }
         return { comments: comments.length, commentAdded: wanted };
     }
-    if (plan.mutation.kind === "custom-field" && plan.customFieldRequirements) {
-        const requirements = plan.customFieldRequirements;
-        const expected = plan.intendedAfter["customField"];
-        const observedValue = currentCustomFieldView({ id: requirements.fieldId, name: requirements.fieldName }, requirements.kind, snapshot.customFieldValues?.[requirements.fieldId]);
-        if (!sameCustomFieldValue(requirements.kind, expected.value, observedValue.value)) {
-            throw verificationFailed(plan, { customField: expected }, { customField: observedValue });
-        }
-        return { customField: observedValue };
-    }
     const observed = observedFor(plan, issue);
     for (const [field, expected] of Object.entries(plan.intendedAfter)) {
         if (!sameValue(observed[field], expected)) {
@@ -215,27 +189,6 @@ function observedFor(plan, issue) {
     }
     return observed;
 }
-/**
- * Did the field end up holding what was planned?
- *
- * Options are compared on their ids, never on their labels - an option is
- * identified by its id, and a label is what a person reads. For a multi-select
- * the comparison is set-wise: Jira is free to return the same selection in a
- * different order, and that is not a different selection.
- */
-function sameCustomFieldValue(kind, expected, observed) {
-    if (kind === "multi-option") {
-        const ids = (v) => (Array.isArray(v) ? v.map((o) => o.id) : []).sort();
-        const a = ids(expected);
-        const b = ids(observed);
-        return a.length === b.length && a.every((id, i) => id === b[i]);
-    }
-    if (kind === "single-option") {
-        const id = (v) => v && typeof v === "object" && !Array.isArray(v) ? v.id : undefined;
-        return id(expected) === id(observed);
-    }
-    return expected === observed;
-}
 function sameValue(observed, expected) {
     if (Array.isArray(expected) || Array.isArray(observed)) {
         const a = Array.isArray(observed) ? [...observed].map(String).sort() : [];

package/dist/application/plan-write.d.ts

@@ -1,6 +1,6 @@
 import type { JamDeps } from "../deps.js";
 import type { FullIssueContext } from "../domain/context.js";
-import type { CustomFieldKind, CustomFieldValueView, WritePlan, WritePlanReceipt } from "../domain/write.js";
+import type { WritePlan, WritePlanReceipt } from "../domain/write.js";
 export type PlanWriteRequest = {
     /** Absent for `issue.create`, which names a project rather than an issue. */
     key?: string;
@@ -40,18 +40,5 @@ export type IssueSnapshot = {
     issue: FullIssueContext;
     /** Identity of the current assignee, which `issue.assignee` cannot supply. */
     assigneeAccountId?: string;
-    /** Raw values for any custom field ids that were asked for. */
-    customFieldValues?: Record<string, unknown>;
 };
-export declare function readIssue(deps: JamDeps, issueKey: string, extraFields?: string[]): Promise<IssueSnapshot>;
-/**
- * What the field holds now, in the shape a receipt shows.
- *
- * Jira stores an option as an object and a scalar as itself; a person reading
- * `before` wants the same canonical form they will see in `intendedAfter`, so
- * they can compare the two rather than a payload against a summary.
- */
-export declare function currentCustomFieldView(field: {
-    id: string;
-    name: string;
-}, kind: CustomFieldKind, raw: unknown): CustomFieldValueView;
+export declare function readIssue(deps: JamDeps, issueKey: string): Promise<IssueSnapshot>;

package/dist/application/plan-write.js

@@ -1,7 +1,6 @@
 import { JamError } from "../domain/errors.js";
 import { assertExistingIssueOperation, assertFieldsAllowed, assertOperationAllowed, assertWriteScope, PLAN_TTL_MS, resolveTransition, } from "../policy/write-policy.js";
 import { assertAssignable, assertNotAlreadyAssigned, exactMatches, resolveAssignee, } from "../policy/assignee-policy.js";
-import { assertEditable, classifyKind, resolveCustomFieldValue, resolveWritableField, } from "../policy/custom-field-policy.js";
 import { planCreateIssue } from "./plan-create-issue.js";
 /**
  * Work out whether a requested change is currently possible, and describe it.
@@ -32,15 +31,9 @@ export async function planWrite(deps, request) {
     // does not write should get that answer, not a round trip and then that
     // answer.
     const input = validateInput(operation, request.input);
-    // Which custom field the whitelist says this is, settled before the read so
-    // the read can fetch its current value in the same request. A selector the
-    // team never opted in costs no Jira call at all.
-    const targetField = operation === "custom-field.update"
-        ? resolveWritableField(deps.config, input.field)
-        : undefined;
-    const snapshot = await readIssue(deps, issueKey, targetField ? [targetField.id] : []);
+    const snapshot = await readIssue(deps, issueKey);
     const issue = snapshot.issue;
-    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId, customFieldRequirements } = await describe(deps, operation, issueKey, snapshot, input, targetField);
+    const { before, intendedAfter, mutation, transition, baseAssigneeAccountId } = await describe(deps, operation, issueKey, snapshot, input);
     const createdAt = new Date();
     const plan = deps.writePlans.create({
         kind: "existing-issue",
@@ -54,7 +47,6 @@ export async function planWrite(deps, request) {
         expiresAt: new Date(createdAt.getTime() + PLAN_TTL_MS).toISOString(),
         ...(transition ? { transition } : {}),
         ...(baseAssigneeAccountId ? { baseAssigneeAccountId } : {}),
-        ...(customFieldRequirements ? { customFieldRequirements } : {}),
         mutation,
     });
     return {
@@ -71,8 +63,8 @@ export async function planWrite(deps, request) {
         },
     };
 }
-export async function readIssue(deps, issueKey, extraFields = []) {
-    const { issue: found, assigneeAccountId, customFieldValues } = await deps.jira.getIssue({
+export async function readIssue(deps, issueKey) {
+    const { issue: found, assigneeAccountId } = await deps.jira.getIssue({
         key: issueKey,
         // `issuetype` and `description` are here for creation's verification step,
         // which has to confirm the issue Jira made is the one that was asked for.
@@ -89,33 +81,13 @@ export async function readIssue(deps, issueKey, extraFields = []) {
             "labels",
             "components",
             "updated",
-            // A custom field is only read when one is being written, and then only
-            // that one - so a custom-field update still costs a single direct GET
-            // rather than a second read for the field it is about to change.
-            ...extraFields.filter((f) => !BASE_WRITE_FIELDS.has(f)),
         ],
     });
     if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return {
-        issue: found,
-        ...(assigneeAccountId ? { assigneeAccountId } : {}),
-        ...(customFieldValues ? { customFieldValues } : {}),
-    };
+    return { issue: found, ...(assigneeAccountId ? { assigneeAccountId } : {}) };
 }
-/** Requested on every write-plane read, so an extra field is never a duplicate. */
-const BASE_WRITE_FIELDS = new Set([
-    "summary",
-    "status",
-    "issuetype",
-    "description",
-    "assignee",
-    "priority",
-    "labels",
-    "components",
-    "updated",
-]);
 /**
  * The issue an existing-issue operation names, or a refusal that says why.
  *
@@ -156,30 +128,6 @@ function validateInput(operation, raw) {
             }
             return { status: status.trim() };
         }
-        case "custom-field.update": {
-            // Anything outside this operation's own two keys is refused rather than
-            // ignored. Silently dropping a key an agent supplied is how a caller
-            // ends up with a write that is not the one it described - and the shared
-            // input object means another operation's key is a plausible mistake.
-            const extra = Object.keys(raw).filter((k) => raw[k] !== undefined && k !== "field" && k !== "value");
-            if (extra.length > 0) {
-                throw new JamError("JAM_WRITE_FIELD_NOT_ALLOWED", `custom-field.update takes only \`field\` and \`value\`. Remove: ${extra.join(", ")}.`, { operation, rejected: extra });
-            }
-            const { field, value } = raw;
-            if (typeof field !== "string" || field.trim().length === 0) {
-                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs non-empty `input.field` - a configured custom field id or name.", { operation });
-            }
-            // The value's family is checked against Jira's schema later; what is
-            // checked here is that it is a shape the contract admits at all. An
-            // object, a boolean or a null never reaches the type policy.
-            const isString = typeof value === "string";
-            const isNumber = typeof value === "number";
-            const isStringArray = Array.isArray(value) && value.every((v) => typeof v === "string");
-            if (!isString && !isNumber && !isStringArray) {
-                throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", "custom-field.update needs `input.value` to be a string, a number, or an array of strings.", { operation, received: Array.isArray(value) ? "array" : typeof value });
-            }
-            return { field: field.trim(), value };
-        }
         case "assignee.update": {
             const assignee = raw.assignee;
             if (typeof assignee !== "string" || assignee.trim().length === 0) {
@@ -189,7 +137,7 @@ function validateInput(operation, raw) {
         }
     }
 }
-async function describe(deps, operation, issueKey, snapshot, input, targetField) {
+async function describe(deps, operation, issueKey, snapshot, input) {
     const issue = snapshot.issue;
     switch (operation) {
         case "comment.add": {
@@ -230,31 +178,6 @@ async function describe(deps, operation, issueKey, snapshot, input, targetField)
                 transition,
             };
         }
-        case "custom-field.update": {
-            const field = targetField;
-            const requested = input;
-            // Jira decides what is editable here and now, and in what shape. JAM
-            // does not model project contexts, screens or permissions - it asks the
-            // one endpoint that answers all three at once for this issue.
-            const metadata = await deps.jiraEditMetadata.getEditableFields(issueKey);
-            const editable = assertEditable(issueKey, field, metadata);
-            const kind = classifyKind(editable);
-            const { jiraValue, view, resolvedOptions } = resolveCustomFieldValue(editable, kind, requested);
-            return {
-                before: {
-                    customField: currentCustomFieldView(field, kind, snapshot.customFieldValues?.[field.id]),
-                },
-                intendedAfter: { customField: view },
-                mutation: { kind: "custom-field", fieldId: field.id, value: jiraValue },
-                customFieldRequirements: {
-                    fieldId: field.id,
-                    fieldName: field.name,
-                    kind,
-                    schema: editable.schema,
-                    ...(resolvedOptions ? { resolvedOptions } : {}),
-                },
-            };
-        }
         case "assignee.update": {
             const { assignee: requested } = input;
             // Ask Jira who this is, and decide from what it says. The requested
@@ -317,31 +240,6 @@ function currentValue(issue, field) {
             return undefined;
     }
 }
-/**
- * What the field holds now, in the shape a receipt shows.
- *
- * Jira stores an option as an object and a scalar as itself; a person reading
- * `before` wants the same canonical form they will see in `intendedAfter`, so
- * they can compare the two rather than a payload against a summary.
- */
-export function currentCustomFieldView(field, kind, raw) {
-    const named = { id: field.id, name: field.name };
-    if (kind === "multi-option") {
-        return { ...named, value: Array.isArray(raw) ? raw.map(toOptionView) : [] };
-    }
-    if (kind === "single-option") {
-        return { ...named, value: raw == null ? null : toOptionView(raw) };
-    }
-    if (raw == null)
-        return { ...named, value: null };
-    return { ...named, value: kind === "number" ? Number(raw) : String(raw) };
-}
-function toOptionView(raw) {
-    const o = raw;
-    const id = typeof o?.id === "string" ? o.id : typeof o?.id === "number" ? String(o.id) : "";
-    const label = typeof o?.value === "string" ? o.value : typeof o?.name === "string" ? o.name : String(raw);
-    return { id, label };
-}
 /** Whitelisted values to the shapes Jira's field API expects. */
 function toJiraFields(input) {
     const fields = {};

package/dist/bootstrap/live-toolset.d.ts

@@ -0,0 +1,36 @@
+/**
+ * What the registered entry actually serves.
+ *
+ * Counting the tools of the process doing the counting proves nothing about
+ * the agent's experience: the agent talks to whatever the host registration
+ * launches, which may be an older release with a different tool set. This asks
+ * that process directly, over the protocol the agent uses.
+ */
+export type LiveToolsetVerdict = "OK" | "LIVE_TOOLSET_MISMATCH" | "UNREACHABLE";
+export type LiveToolsetResult = {
+    verdict: LiveToolsetVerdict;
+    expected: string[];
+    actual?: string[];
+    missing?: string[];
+    detail?: string;
+};
+export type ToolsetProbe = (argv: {
+    command: string;
+    args: string[];
+}) => Promise<string[] | null>;
+export declare const expectedTools: () => string[];
+/**
+ * Speak just enough MCP to ask for the tool list: initialize, initialized,
+ * tools/list. A full client would pull in the SDK's transport machinery for
+ * one question that is three lines of JSON.
+ */
+export declare const defaultToolsetProbe: ToolsetProbe;
+/**
+ * Compare what the registered command serves against what this release
+ * defines. A tool the agent cannot see is a tool it does not have, whatever
+ * the package on disk says.
+ */
+export declare function checkLiveToolset(argv: {
+    command: string;
+    args: string[];
+}, probe?: ToolsetProbe): Promise<LiveToolsetResult>;

package/dist/bootstrap/live-toolset.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import { SERVER_VERSION } from "@jam-mcp/launcher";
+import { TOOL_NAMES } from "../mcp/create-server.js";
+const HANDSHAKE_TIMEOUT_MS = 30_000;
+export const expectedTools = () => [...TOOL_NAMES].sort();
+/**
+ * Speak just enough MCP to ask for the tool list: initialize, initialized,
+ * tools/list. A full client would pull in the SDK's transport machinery for
+ * one question that is three lines of JSON.
+ */
+export const defaultToolsetProbe = ({ command, args }) => new Promise((resolve) => {
+    const child = spawn(command, args, {
+        stdio: ["pipe", "pipe", "ignore"],
+        shell: process.platform === "win32",
+    });
+    let buffer = "";
+    let settled = false;
+    const done = (value) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        child.stdin.end();
+        child.kill();
+        resolve(value);
+    };
+    const timer = setTimeout(() => done(null), HANDSHAKE_TIMEOUT_MS);
+    child.on("error", () => done(null));
+    child.on("exit", () => done(null));
+    child.stdout.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        let newline = buffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = buffer.slice(0, newline).trim();
+            buffer = buffer.slice(newline + 1);
+            newline = buffer.indexOf("\n");
+            if (!line)
+                continue;
+            try {
+                const message = JSON.parse(line);
+                if (message.id === 2) {
+                    done((message.result?.tools ?? []).map((tool) => tool.name).sort());
+                    return;
+                }
+            }
+            catch {
+                // Not our line. The server owns stdout for the protocol; anything
+                // unparseable is noise from a wrapper and is skipped rather than
+                // treated as a failure.
+            }
+        }
+    });
+    const send = (payload) => {
+        child.stdin.write(`${JSON.stringify(payload)}\n`);
+    };
+    send({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "jam-doctor", version: SERVER_VERSION },
+        },
+    });
+    send({ jsonrpc: "2.0", method: "notifications/initialized" });
+    send({ jsonrpc: "2.0", id: 2, method: "tools/list" });
+});
+/**
+ * Compare what the registered command serves against what this release
+ * defines. A tool the agent cannot see is a tool it does not have, whatever
+ * the package on disk says.
+ */
+export async function checkLiveToolset(argv, probe = defaultToolsetProbe) {
+    const expected = expectedTools();
+    const actual = await probe(argv).catch(() => null);
+    if (actual === null) {
+        return { verdict: "UNREACHABLE", expected, detail: "the registered command did not answer tools/list" };
+    }
+    const missing = expected.filter((name) => !actual.includes(name));
+    if (missing.length > 0) {
+        return { verdict: "LIVE_TOOLSET_MISMATCH", expected, actual, missing };
+    }
+    return { verdict: "OK", expected, actual };
+}

package/dist/bootstrap/mcp-config-merger.d.ts

@@ -13,12 +13,19 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.3.1", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.0", "serve"];
 };
 /**
- * Recognise wiring from before the launcher existed: a hard-coded path to one
- * machine's checkout, or a bare `jam` that depends on a global PATH install.
- * Both work only where they were written, which is why `--migrate` exists.
+ * Recognise wiring from before the launcher existed: a hard-coded `node` path
+ * to one machine's checkout. That works only where it was written, which is
+ * why `--migrate` exists.
+ *
+ * A bare `jam` is deliberately NOT legacy any more. It is what a persistent
+ * install (`npm install -g @jam-mcp/launcher@<exact>`) provides, and on a
+ * machine whose package runner is broken it is the entry that still works —
+ * a real Windows npm was seen failing to start `npx` children at all. Someone
+ * who registered it chose it; `--migrate` must not silently rewrite that
+ * choice back into the very path that fails there.
  */
 export declare function isLegacyJamEntry(entry: unknown): boolean;
 export type McpMergeResult = {

package/dist/bootstrap/mcp-config-merger.js

@@ -18,16 +18,21 @@ export const JAM_MCP_ENTRY = {
     args: ["--yes", LAUNCHER_PACKAGE_SPEC, "serve"],
 };
 /**
- * Recognise wiring from before the launcher existed: a hard-coded path to one
- * machine's checkout, or a bare `jam` that depends on a global PATH install.
- * Both work only where they were written, which is why `--migrate` exists.
+ * Recognise wiring from before the launcher existed: a hard-coded `node` path
+ * to one machine's checkout. That works only where it was written, which is
+ * why `--migrate` exists.
+ *
+ * A bare `jam` is deliberately NOT legacy any more. It is what a persistent
+ * install (`npm install -g @jam-mcp/launcher@<exact>`) provides, and on a
+ * machine whose package runner is broken it is the entry that still works —
+ * a real Windows npm was seen failing to start `npx` children at all. Someone
+ * who registered it chose it; `--migrate` must not silently rewrite that
+ * choice back into the very path that fails there.
  */
 export function isLegacyJamEntry(entry) {
     if (!entry || typeof entry !== "object")
         return false;
     const { command, args } = entry;
-    if (command === "jam")
-        return true;
     if (command === "node")
         return true;
     if (command === "npx" && Array.isArray(args)) {