@jam-mcp/server 1.4.2 → 1.4.4

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.4.2 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.4.4 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.4.2 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.4.4 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/composite.js

@@ -74,6 +74,15 @@ export class CompositeCredentialProvider {
             description.baseUrl = values.JIRA_BASE_URL;
         if (values.JIRA_EMAIL)
             description.email = values.JIRA_EMAIL;
+        // Per-field provenance, so "mixed" can be read rather than guessed at.
+        const sources = {};
+        for (const field of ["JIRA_BASE_URL", "JIRA_EMAIL", "JIRA_API_TOKEN"]) {
+            const from = sourceByKey[field];
+            if (from)
+                sources[field] = from;
+        }
+        if (Object.keys(sources).length > 0)
+            description.sources = sources;
         return description;
     }
 }

package/dist/bootstrap/host-mcp.d.ts

@@ -42,6 +42,16 @@ export type HostRunResult = {
 /** Injected by tests. Nothing in this module may reach a real CLI unasked. */
 export type HostRunner = (command: HostCommand) => HostRunResult;
 export declare const defaultHostRunner: HostRunner;
+/**
+ * A runner that only sees what is persistently installed on this machine.
+ *
+ * Under `npx --yes @jam-mcp/bootstrap@X`, PATH carries npx's cache
+ * `node_modules/.bin` - which contains a `jam` shim that vanishes when npx
+ * exits. Any measurement of "does a global jam exist" through the normal PATH
+ * therefore lies during bootstrap, which is exactly when the answer matters
+ * most. This runner strips those entries first.
+ */
+export declare const persistentHostRunner: HostRunner;
 export declare function hostRegistration(id: HostId, options?: {
     bare?: boolean;
 }): HostCommand | undefined;
@@ -80,6 +90,10 @@ export declare function isBareJamEntry(line: string): boolean;
  *
  * undefined when `jam` is not on PATH or does not answer: a registration that
  * cannot be measured counts as stale, same as an unreadable pin.
+ *
+ * Measured through persistentHostRunner by default: under an npx bootstrap
+ * the ordinary PATH resolves `jam` to npx's own ephemeral cache shim, and a
+ * bare registration decided on that evidence dies as soon as npx exits.
  */
 export declare function bareJamVersion(run?: HostRunner): string | undefined;
 /** Is this measured launcher version the one this release registers? */

package/dist/bootstrap/host-mcp.js

@@ -1,18 +1,43 @@
 import { spawnSync } from "node:child_process";
 import { JAM_MCP_ENTRY } from "./mcp-config-merger.js";
+import { shellInvocation, stripPackageRunnerPath } from "./shell-command.js";
 /**
  * These boot a whole Node CLI, and Claude Code health-checks every configured
  * server while listing, which is seconds rather than milliseconds.
  */
 const HOST_TIMEOUT_MS = 20_000;
 export const defaultHostRunner = ({ command, args }) => {
-    const result = spawnSync(command, args, {
+    // Both CLIs are npm shims on Windows, and Node refuses to spawn a .cmd
+    // without a shell. Every argument JAM passes is a bare token - no JSON, no
+    // spaces - and shellInvocation validates exactly that before joining the
+    // argv into one line (an args array plus shell:true is DEP0190).
+    const invocation = shellInvocation(command, args);
+    const result = spawnSync(invocation.command, invocation.args, {
         encoding: "utf8",
         timeout: HOST_TIMEOUT_MS,
-        // Both CLIs are npm shims on Windows, and Node refuses to spawn a .cmd
-        // without a shell. Every argument JAM passes is a bare token - no JSON, no
-        // spaces - precisely so this cannot become a quoting hazard.
-        shell: process.platform === "win32",
+        shell: invocation.shell,
+    });
+    if (result.error)
+        return { status: null, failed: true, stdout: "" };
+    return { status: result.status, failed: false, stdout: result.stdout ?? "" };
+};
+/**
+ * A runner that only sees what is persistently installed on this machine.
+ *
+ * Under `npx --yes @jam-mcp/bootstrap@X`, PATH carries npx's cache
+ * `node_modules/.bin` - which contains a `jam` shim that vanishes when npx
+ * exits. Any measurement of "does a global jam exist" through the normal PATH
+ * therefore lies during bootstrap, which is exactly when the answer matters
+ * most. This runner strips those entries first.
+ */
+export const persistentHostRunner = ({ command, args }) => {
+    const invocation = shellInvocation(command, args);
+    const pathValue = process.env.PATH ?? process.env.Path ?? "";
+    const result = spawnSync(invocation.command, invocation.args, {
+        encoding: "utf8",
+        timeout: HOST_TIMEOUT_MS,
+        shell: invocation.shell,
+        env: { ...process.env, PATH: stripPackageRunnerPath(pathValue) },
     });
     if (result.error)
         return { status: null, failed: true, stdout: "" };
@@ -106,8 +131,12 @@ export function isBareJamEntry(line) {
  *
  * undefined when `jam` is not on PATH or does not answer: a registration that
  * cannot be measured counts as stale, same as an unreadable pin.
+ *
+ * Measured through persistentHostRunner by default: under an npx bootstrap
+ * the ordinary PATH resolves `jam` to npx's own ephemeral cache shim, and a
+ * bare registration decided on that evidence dies as soon as npx exits.
  */
-export function bareJamVersion(run = defaultHostRunner) {
+export function bareJamVersion(run = persistentHostRunner) {
     const result = run({ command: "jam", args: ["runtime", "status", "--json"] });
     if (result.failed || result.status !== 0)
         return undefined;
@@ -187,7 +216,10 @@ function probeHosts(run) {
         };
     });
     function measuredBare() {
-        bareCache ??= { version: bareJamVersion(run) };
+        // The real probe runner sees npx's contaminated PATH; the persistent
+        // runner is the honest one for this question. An injected runner is a
+        // test, and stays in charge of its own answers.
+        bareCache ??= { version: bareJamVersion(run === defaultHostRunner ? persistentHostRunner : run) };
         return bareCache.version;
     }
 }

package/dist/bootstrap/live-toolset.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { shellInvocation } from "./shell-command.js";
 import { SERVER_VERSION } from "@jam-mcp/launcher";
 import { TOOL_NAMES } from "../mcp/create-server.js";
 const HANDSHAKE_TIMEOUT_MS = 30_000;
@@ -9,9 +10,12 @@ export const expectedTools = () => [...TOOL_NAMES].sort();
  * one question that is three lines of JSON.
  */
 export const defaultToolsetProbe = ({ command, args }) => new Promise((resolve) => {
-    const child = spawn(command, args, {
+    // npm shims need a shell on Windows; the argv is joined by shellInvocation
+    // (validated bare tokens) because an args array plus shell:true is DEP0190.
+    const invocation = shellInvocation(command, args);
+    const child = spawn(invocation.command, invocation.args, {
         stdio: ["pipe", "pipe", "ignore"],
-        shell: process.platform === "win32",
+        shell: invocation.shell,
     });
     let buffer = "";
     let settled = false;

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

@@ -13,7 +13,7 @@ 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.4.2", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.4", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded `node` path

package/dist/bootstrap/migration-target.js

@@ -1,13 +1,16 @@
 import { spawnSync } from "node:child_process";
+import { shellInvocation } from "./shell-command.js";
 import { LAUNCHER_PACKAGE_SPEC } from "./mcp-config-merger.js";
 import { computeSetupPlan } from "./setup-plan.js";
 const PROBE_TIMEOUT_MS = 10_000;
 function runNpm(command, args) {
-    const result = spawnSync(command, args, {
+    // npm on Windows is a shell script, not an executable; shellInvocation
+    // joins the validated argv because an args array plus shell:true is DEP0190.
+    const invocation = shellInvocation(command, args);
+    const result = spawnSync(invocation.command, invocation.args, {
         encoding: "utf8",
         timeout: PROBE_TIMEOUT_MS,
-        // npm on Windows is a shell script, not an executable.
-        shell: process.platform === "win32",
+        shell: invocation.shell,
     });
     return {
         status: result.status,

package/dist/bootstrap/setup-plan.d.ts

@@ -3,13 +3,23 @@ import type { MigrationTarget } from "./migration-target.js";
 import { type BootstrapSource } from "./project-config-bootstrapper.js";
 import type { SetupState } from "./setup-state.js";
 export type SetupStatus = "already_configured" | "ready_to_apply" | "user_action_required";
-export type SetupCode = "JAM_PROJECT_SELECTION_REQUIRED" | "JAM_BINDINGS_UNREADABLE" | "JAM_AUTH_REQUIRED" | "JAM_RUNTIME_CONFIG_MISSING" | "JAM_PROJECT_CONFIG_INVALID" | "JAM_MCP_CONFIG_UNREADABLE" | "JAM_MIGRATION_TARGET_UNAVAILABLE";
+export type SetupCode = "JAM_PROJECT_SELECTION_REQUIRED" | "JAM_BINDINGS_UNREADABLE" | "JAM_AUTH_REQUIRED" | "JAM_RUNTIME_CONFIG_MISSING" | "JAM_PROJECT_CONFIG_INVALID" | "JAM_MCP_CONFIG_UNREADABLE" | "JAM_MIGRATION_TARGET_UNAVAILABLE" | "JAM_PROJECT_KEY_CONFLICT";
+/**
+ * Where a project key came from. `repository` is the team's committed
+ * `.jira-agent/project.yaml`; the rest are this user's own settings, in the
+ * precedence order `decideProjectKey` applies.
+ */
+export type KeySource = BootstrapSource | "repository";
+export type KeyOrigin = {
+    key: string;
+    source: KeySource;
+};
 export type SetupChange = {
     type: "create";
     target: "project-config";
     path: string;
     key: string;
-    keySource: BootstrapSource;
+    keySource: KeySource;
 } | {
     type: "create";
     target: "mcp-config";
@@ -30,7 +40,7 @@ export type SetupChange = {
     path: string;
     workspaceId: string;
     key: string;
-    keySource: BootstrapSource;
+    keySource: KeySource;
     /** Present on a rebind, so the preview shows what is being replaced. */
     previousKey?: string;
 } | {
@@ -95,7 +105,11 @@ export type SetupPlan = {
     project?: {
         root: string;
         key?: string;
+        keySource?: KeySource;
     };
+    /** On JAM_PROJECT_KEY_CONFLICT: what was asked for, and what already stands. */
+    requested?: KeyOrigin;
+    existing?: KeyOrigin;
 };
 export type PlanOptions = {
     /**

package/dist/bootstrap/setup-plan.js

@@ -52,7 +52,23 @@ export function computeSetupPlan(state, options = {}) {
             project: { root: state.project.root },
         };
     }
-    const project = { root: state.project.root, key: key.key };
+    // The repository's committed key is the team's answer. When a personal
+    // `--project` disagrees with it, neither side may win silently: overwriting
+    // the repository is not setup's call, and quietly using the repository key
+    // makes the flag a lie. Stop, and name both sources.
+    const conflict = keyConflict(state, options, key);
+    if (conflict) {
+        return {
+            status: "user_action_required",
+            code: "JAM_PROJECT_KEY_CONFLICT",
+            changes: [],
+            requiresUserAction: true,
+            requested: conflict.requested,
+            existing: conflict.existing,
+            project: { root: state.project.root, key: conflict.existing.key, keySource: conflict.existing.source },
+        };
+    }
+    const project = { root: state.project.root, key: key.key, keySource: key.source };
     if (!shared) {
         // Personal scope: the record of "this workspace is that Jira project"
         // lives with the user, and nothing in the repository is touched.
@@ -207,9 +223,11 @@ function planBindingChange(state, key) {
 }
 function resolveKey(state, options) {
     // An existing project.yaml wins: setup must never silently repoint a project,
-    // and a personal note must never override what the team committed.
+    // and a personal note must never override what the team committed. It is
+    // labelled `repository` rather than `explicit` - a reader has to be able to
+    // tell the team's committed answer from what someone typed.
     if (state.project.key)
-        return { key: state.project.key, source: "explicit" };
+        return { key: state.project.key, source: "repository" };
     const decideOptions = {};
     if (options.explicitKey)
         decideOptions.explicitKey = options.explicitKey;
@@ -221,6 +239,24 @@ function resolveKey(state, options) {
         decideOptions.presetsPath = options.presetsPath;
     return decideProjectKey(state.project.root, decideOptions);
 }
+/**
+ * A repository key and an explicit `--project` that disagree. Personal
+ * sources are not conflicts: explicit already beats them in decideProjectKey,
+ * and a stale binding is repaired rather than reported.
+ */
+function keyConflict(state, options, resolved) {
+    const explicit = options.explicitKey?.trim();
+    if (!explicit)
+        return undefined;
+    const repository = state.project.key;
+    if (!repository || repository === explicit)
+        return undefined;
+    void resolved;
+    return {
+        requested: { key: explicit, source: "explicit" },
+        existing: { key: repository, source: "repository" },
+    };
+}
 function planMcpChange(state, options) {
     if (!state.mcp.exists) {
         return { type: "create", target: "mcp-config", path: state.mcp.path };

package/dist/bootstrap/setup-state.d.ts

@@ -1,5 +1,5 @@
 import { type RuntimeMode } from "@jam-mcp/launcher";
-import type { CredentialPort, CredentialSource } from "../ports/credentials.port.js";
+import type { CredentialDescription, CredentialPort, CredentialSource } from "../ports/credentials.port.js";
 import { type HostRunner, type HostState } from "./host-mcp.js";
 import { type McpInspection } from "./mcp-config-merger.js";
 import { type ProjectBinding } from "./project-bindings.js";
@@ -15,6 +15,8 @@ export type RuntimeState = {
 export type CredentialState = {
     present: boolean;
     source: CredentialSource;
+    /** Which source supplied each field. Names only - never a value. */
+    sources?: CredentialDescription["sources"];
     baseUrl?: string;
     email?: string;
 };

package/dist/bootstrap/setup-state.js

@@ -61,6 +61,8 @@ function detectCredentials(credentials) {
         source: described.source,
     };
     // Presence and origin only - the token value never enters this snapshot.
+    if (described.sources)
+        state.sources = described.sources;
     if (described.baseUrl)
         state.baseUrl = described.baseUrl;
     if (described.email)

package/dist/bootstrap/shell-command.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How to hand an npm-shim CLI to spawnSync without tripping DEP0190.
+ *
+ * npm-installed CLIs (`claude`, `codex`, `npm`, `npx`, `jam`) are `.cmd`
+ * shims on Windows, and Node only runs those through a shell. But passing an
+ * args ARRAY together with `shell: true` is deprecated (DEP0190): Node
+ * concatenates the arguments without escaping, so the array form is an
+ * illusion of safety. On Windows the argv is therefore joined into a single
+ * command line HERE, deliberately - and every token is validated bare first,
+ * so the join cannot become a quoting hazard. A token that would need cmd.exe
+ * quoting is refused outright rather than escaped: nothing JAM runs ever
+ * carries one, so meeting one means the input is not ours to guess about.
+ *
+ * On every other platform the array form without a shell is correct and
+ * unchanged.
+ */
+export type ShellInvocation = {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
+export declare function shellInvocation(command: string, args: readonly string[], platform?: NodeJS.Platform): ShellInvocation;
+/**
+ * PATH with package-runner injections removed.
+ *
+ * `npx --yes @jam-mcp/bootstrap@X` prepends its cache's `node_modules/.bin`
+ * to PATH, and that directory contains a `jam` shim - so inside a bootstrap
+ * run, `jam` resolves even on a machine where nothing is installed. Measuring
+ * "does this machine have a persistent jam" through that PATH answered yes on
+ * every fresh machine, and setup then registered a bare `jam serve` that died
+ * the moment npx's directory evaporated (the v1.4.2 fresh-install field
+ * failure). A persistent install lives in npm's global bin, never under a
+ * `node_modules` or `_npx` directory, so those entries are dropped before the
+ * measurement.
+ */
+export declare function stripPackageRunnerPath(pathValue: string, separator?: string): string;

package/dist/bootstrap/shell-command.js

@@ -0,0 +1,31 @@
+import { delimiter } from "node:path";
+/** Anything cmd.exe would re-interpret, plus whitespace and quotes. */
+const CMD_UNSAFE = /[\s&|<>^"'`;()]/;
+export function shellInvocation(command, args, platform = process.platform) {
+    if (platform !== "win32")
+        return { command, args: [...args], shell: false };
+    const unsafe = [command, ...args].find((token) => token === "" || CMD_UNSAFE.test(token));
+    if (unsafe !== undefined) {
+        throw new Error(`refusing to pass a token through cmd.exe unquoted: ${JSON.stringify(unsafe)}`);
+    }
+    return { command: [command, ...args].join(" "), args: [], shell: true };
+}
+/**
+ * PATH with package-runner injections removed.
+ *
+ * `npx --yes @jam-mcp/bootstrap@X` prepends its cache's `node_modules/.bin`
+ * to PATH, and that directory contains a `jam` shim - so inside a bootstrap
+ * run, `jam` resolves even on a machine where nothing is installed. Measuring
+ * "does this machine have a persistent jam" through that PATH answered yes on
+ * every fresh machine, and setup then registered a bare `jam serve` that died
+ * the moment npx's directory evaporated (the v1.4.2 fresh-install field
+ * failure). A persistent install lives in npm's global bin, never under a
+ * `node_modules` or `_npx` directory, so those entries are dropped before the
+ * measurement.
+ */
+export function stripPackageRunnerPath(pathValue, separator = delimiter) {
+    return pathValue
+        .split(separator)
+        .filter((entry) => !/[\\/]node_modules[\\/]|[\\/]_npx[\\/]/.test(`${entry}/`.replace(/[\\/]+$/, "/")))
+        .join(separator);
+}

package/dist/cli/agent-api.js

@@ -61,7 +61,8 @@ export async function setupApplyCommand(options = {}) {
     }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
         plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
-        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        plan.code === "JAM_BINDINGS_UNREADABLE" ||
+        plan.code === "JAM_PROJECT_KEY_CONFLICT") {
         emitJson({ ...plan, changesApplied: false });
         return 1;
     }
@@ -69,11 +70,23 @@ export async function setupApplyCommand(options = {}) {
         ...(options.home ? { home: options.home } : {}),
         ...(options.runHost ? { runHost: options.runHost } : {}),
     });
-    emitJson({ ...plan, status: applyStatus(plan), changesApplied: result.changesApplied });
+    emitJson({
+        ...plan,
+        status: applyStatus(plan, result.changesApplied),
+        changesApplied: result.changesApplied,
+    });
     return plan.requiresUserAction ? 1 : 0;
 }
-function applyStatus(plan) {
-    return plan.requiresUserAction ? "user_action_required" : "already_configured";
+/**
+ * The status of an apply, after it ran. "already_configured" means nothing
+ * was executed; when changes did run the answer is "applied" - reporting
+ * "already_configured" alongside changesApplied:true made the two fields
+ * contradict each other, and an agent could believe either one.
+ */
+function applyStatus(plan, changesApplied) {
+    if (plan.requiresUserAction)
+        return "user_action_required";
+    return changesApplied ? "applied" : "already_configured";
 }
 /**
  * `jam setup --agent` - one shot: detect, plan, apply what is safe, verify.
@@ -90,7 +103,8 @@ export async function setupAgentCommand(options = {}) {
     }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
         plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
-        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        plan.code === "JAM_BINDINGS_UNREADABLE" ||
+        plan.code === "JAM_PROJECT_KEY_CONFLICT") {
         emitJson({ ...plan, changesApplied: false });
         return 1;
     }
@@ -135,10 +149,71 @@ export async function doctorJsonCommand(options = {}) {
         ...(health.error ? { error: health.error } : {}),
         project: { root: state.project.root, ...(state.project.key ? { key: state.project.key } : {}) },
         axes,
+        diagnosis: diagnose(state, axes, health),
         checks: health.checks,
     });
     return passed ? 0 : 1;
 }
+function diagnose(state, axes, health) {
+    const check = (name) => health.checks.find((c) => c.name === name);
+    const fromCheck = (name, code) => {
+        const found = check(name);
+        if (!found)
+            return { state: "UNCHECKED" };
+        return found.ok
+            ? { state: "OK", ...(found.detail ? { detail: found.detail } : {}) }
+            : { state: "FAILED", code, ...(found.detail ? { detail: found.detail } : {}) };
+    };
+    // Credentials: this axis answers "are all three fields resolvable, and from
+    // where" - the snapshot knows that. Whether Jira accepts them is a different
+    // question with its own axis below, and conflating the two is what made a
+    // working "mixed" setup read as broken. "mixed" is never a failure here.
+    const credentialCheck = check("Credentials present");
+    const mixed = state.credentials.source === "mixed";
+    const credentials = !state.credentials.present
+        ? {
+            state: "FAILED",
+            code: "JAM_AUTH_REQUIRED",
+            ...(credentialCheck?.detail ? { detail: credentialCheck.detail } : {}),
+        }
+        : mixed
+            ? { state: "WARNING", detail: `fields come from more than one source: ${describeSources(state)}` }
+            : { state: "OK", detail: `source ${state.credentials.source}` };
+    return {
+        credentials,
+        projectBinding: state.project.key
+            ? { state: "OK", detail: `key ${state.project.key}` }
+            : { state: "FAILED", code: "JAM_PROJECT_SELECTION_REQUIRED", detail: "no project key for this workspace" },
+        runtime: axes.package === "PACKAGE_READY"
+            ? { state: "OK", ...(axes.packageVersion ? { detail: axes.packageVersion } : {}) }
+            : { state: "FAILED", code: "JAM_RUNTIME_CONFIG_MISSING", ...(state.runtime.error ? { detail: state.runtime.error } : {}) },
+        registration: axes.registration === "OK"
+            ? { state: "OK", ...(axes.registeredVersion ? { detail: axes.registeredVersion } : {}) }
+            : axes.registration === "UNREGISTERED"
+                ? { state: "UNCHECKED", detail: "no host has a jam entry for this user" }
+                : { state: "FAILED", code: axes.registration, ...(axes.detail ? { detail: axes.detail } : {}) },
+        liveToolset: axes.live === "OK"
+            ? { state: "OK" }
+            : axes.live === "UNCHECKED"
+                ? { state: "UNCHECKED", ...(axes.detail ? { detail: axes.detail } : {}) }
+                : {
+                    state: "FAILED",
+                    code: axes.live,
+                    ...(axes.missingTools ? { detail: `missing: ${axes.missingTools.join(", ")}` } : {}),
+                },
+        jiraAuthentication: fromCheck("Jira authentication", "JAM_JIRA_AUTHENTICATION_FAILED"),
+        jiraProjectAccess: fromCheck(health.checks.find((c) => c.name.startsWith("JQL search"))?.name ?? "JQL search", "JAM_JIRA_PROJECT_ACCESS_FAILED"),
+    };
+}
+/** Field-to-source names only. A credential value never appears here. */
+function describeSources(state) {
+    const sources = state.credentials.sources;
+    if (!sources)
+        return "unknown";
+    return Object.entries(sources)
+        .map(([field, from]) => `${field}=${from}`)
+        .join(", ");
+}
 async function inspectAxes(state, options) {
     const packageVersion = state.runtime.version;
     const axes = {
@@ -195,6 +270,8 @@ export function authStatusCommand(options = {}) {
         status: credentials.present ? "configured" : "not_configured",
         ...(credentials.present ? {} : { code: "JAM_AUTH_REQUIRED" }),
         source: credentials.source,
+        // Which field came from where. Names only - a value never appears.
+        ...(credentials.sources ? { sources: credentials.sources } : {}),
         ...(credentials.email ? { email: credentials.email } : {}),
         ...(credentials.baseUrl ? { baseUrl: credentials.baseUrl } : {}),
     });

package/dist/cli/auth.js

@@ -137,7 +137,8 @@ export function authLogoutCommand(options = {}) {
  * credential unreachable, and the resulting split shows up as "mixed".
  */
 function reportOverride(ui, port) {
-    const source = port.describe().source;
+    const described = port.describe();
+    const source = described.source;
     if (source === "secret-store")
         return;
     if (source === "mixed") {
@@ -147,6 +148,8 @@ function reportOverride(ui, port) {
         ui.warn("Current JIRA_* environment variables override the stored credentials");
     }
     ui.line(`  Effective source: ${source}`);
+    for (const line of fieldSourceLines(described))
+        ui.line(line);
     ui.line("  Unset them to use what was just stored.");
 }
 /** After a logout, say plainly whether anything still authenticates JAM. */
@@ -161,6 +164,8 @@ function reportRemaining(ui, port) {
         ? "Jira credentials still resolve from outside the secret store"
         : "Part of a Jira credential still resolves from outside the secret store");
     ui.line(`  Effective source: ${described.source}`);
+    for (const line of fieldSourceLines(described))
+        ui.line(line);
     ui.line("  Unset JIRA_BASE_URL, JIRA_EMAIL and JIRA_API_TOKEN to finish logging out.");
 }
 /** undefined when Jira accepted the credentials; otherwise the reason. */
@@ -200,3 +205,15 @@ export function toJiraOrigin(input) {
     }
     return url.protocol === "http:" || url.protocol === "https:" ? url.origin : undefined;
 }
+/**
+ * Which field came from where. "mixed" on its own tells a reader that
+ * something is split without telling them what, so they go looking - these
+ * lines answer it. Field names and source names only: a credential value is
+ * never printed.
+ */
+function fieldSourceLines(described) {
+    const sources = described.sources;
+    if (!sources)
+        return [];
+    return Object.entries(sources).map(([field, from]) => `    ${field}: ${from}`);
+}

package/dist/cli/setup.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { shellInvocation } from "../bootstrap/shell-command.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { runHealthGate } from "../bootstrap/boot-health-gate.js";
@@ -43,7 +44,8 @@ export async function setup(options = {}) {
     }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
         plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
-        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        plan.code === "JAM_BINDINGS_UNREADABLE" ||
+        plan.code === "JAM_PROJECT_KEY_CONFLICT") {
         line(`[FAIL] ${describeBlockingCode(plan)}`);
         return 1;
     }
@@ -132,6 +134,16 @@ function reportApplied(applied, plan) {
     void plan;
 }
 function describeBlockingCode(plan) {
+    if (plan.code === "JAM_PROJECT_KEY_CONFLICT") {
+        // Both sides named, and no suggestion to delete the repository's file -
+        // which project this repository belongs to is the team's decision.
+        return [
+            `This repository declares ${plan.existing?.key} in .jira-agent/project.yaml,`,
+            `but --project asked for ${plan.requested?.key}. JAM will not overwrite the`,
+            "committed key. Either drop --project to use the repository's, or change",
+            "the repository's project.yaml with the team and re-run.",
+        ].join(" ");
+    }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID") {
         return "The project's .jira-agent/project.yaml could not be parsed. Fix it and re-run.";
     }
@@ -178,10 +190,13 @@ async function installAndBuild(root) {
         { name: "Build", args: ["run", "build"] },
     ]) {
         line(`\n> npm ${step.args.join(" ")}`);
-        const res = spawnSync("npm", step.args, {
+        // npm is a .cmd shim on Windows; shellInvocation joins the validated argv
+        // because an args array plus shell:true is DEP0190.
+        const invocation = shellInvocation("npm", step.args);
+        const res = spawnSync(invocation.command, invocation.args, {
             cwd: root,
             stdio: "inherit",
-            shell: process.platform === "win32",
+            shell: invocation.shell,
         });
         if (res.status !== 0) {
             line(`[FAIL] ${step.name}`);

package/dist/ports/credentials.port.d.ts

@@ -14,6 +14,13 @@ export type CredentialDescription = {
     email?: string;
     hasToken: boolean;
     source: CredentialSource;
+    /**
+     * Which source supplied each field. `source` alone says "mixed" without
+     * saying mixed how, which reads as a fault when it is a normal state - a
+     * base URL and email in the OS store with the token exported for one shell
+     * is a supported setup. Names only: no value ever appears here.
+     */
+    sources?: Partial<Record<"JIRA_BASE_URL" | "JIRA_EMAIL" | "JIRA_API_TOKEN", Exclude<CredentialSource, "mixed" | "none">>>;
 };
 export interface CredentialPort {
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "JAM (Jira Agent MCP) - agent-facing Jira access layer: MCP server, setup core, and CLI",
   "keywords": [
     "jira",
@@ -41,7 +41,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jam-mcp/launcher": "1.4.2",
+    "@jam-mcp/launcher": "1.4.4",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"