@jam-mcp/server 1.4.6 → 1.6.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.4.6 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.6.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.4.6 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.6.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/bootstrap/host-mcp.d.ts

@@ -54,6 +54,7 @@ export declare const defaultHostRunner: HostRunner;
 export declare const persistentHostRunner: HostRunner;
 export declare function hostRegistration(id: HostId, options?: {
     bare?: boolean;
+    version?: string;
 }): HostCommand | undefined;
 /** The removal that has to precede re-registering an entry this host already has. */
 export declare function hostUnregistration(id: HostId): HostCommand | undefined;

package/dist/bootstrap/host-mcp.js

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
-import { JAM_MCP_ENTRY } from "./mcp-config-merger.js";
+import { LAUNCHER_PACKAGE } from "@jam-mcp/launcher";
+import { JAM_MCP_ENTRY, LAUNCHER_PACKAGE_SPEC } 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
@@ -75,8 +76,18 @@ export function hostRegistration(id, options = {}) {
     const adapter = ADAPTERS.find((a) => a.id === id);
     if (!adapter)
         return undefined;
-    if (!options.bare)
-        return adapter.register;
+    if (!options.bare) {
+        // `jam update` registers a version this build is not - that is the whole
+        // point of an update. Only the pin moves; the rest of the argv is the same
+        // line setup writes, so the two cannot drift into different registrations.
+        if (!options.version)
+            return adapter.register;
+        const pinned = `${LAUNCHER_PACKAGE}@${options.version}`;
+        return {
+            command: adapter.register.command,
+            args: adapter.register.args.map((arg) => (arg === LAUNCHER_PACKAGE_SPEC ? pinned : arg)),
+        };
+    }
     const at = adapter.register.args.indexOf("--");
     return { command: adapter.register.command, args: [...adapter.register.args.slice(0, at), ...LAUNCH_BARE] };
 }

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

package/dist/cli/lifecycle.d.ts

@@ -0,0 +1,66 @@
+import { type HostId, type HostRunner, type HostState } from "../bootstrap/host-mcp.js";
+export type LifecycleOptions = {
+    json?: boolean;
+    /** Injected by tests. Nothing here may reach a real host CLI or npm unasked. */
+    run?: HostRunner;
+    hosts?: () => HostState[];
+};
+export type RefreshHostPlan = {
+    id: HostId;
+    from?: string;
+    bare: boolean;
+    action: "repin" | "none";
+};
+export type RefreshPlan = {
+    /** The version this build is. `refresh` never moves off it - that is `update`. */
+    version: string;
+    hosts: RefreshHostPlan[];
+    steps: readonly string[];
+};
+/**
+ * What `refresh` would converge. Pure: it runs nothing and writes nothing.
+ *
+ * The scope is deliberately small. A registration that points at a different
+ * launcher than this build is what goes stale here. The project binding, the
+ * credentials, `~/.jam/config.yaml` and every byte of Jira data are outside
+ * it - re-deciding those is `setup`, and calling it "refresh" is how a person
+ * loses a binding they never asked to change.
+ */
+export declare function planRefresh(hosts: readonly HostState[], version?: string): RefreshPlan;
+export declare function refreshLine(plan: RefreshPlan): string;
+/**
+ * `jam refresh` - keep the version, make the registration match it again.
+ *
+ * Nothing is removed before the replacement is known to work, which is the
+ * same order `update` uses and for the same reason: a failed refresh leaves
+ * the machine running what it was running.
+ */
+export declare function jamRefreshCommand(command: string | undefined, options?: LifecycleOptions): Promise<number>;
+export type UninstallPlan = {
+    /** Registrations that would be removed. */
+    hosts: HostId[];
+    /** Whether a global launcher install would be removed with it. */
+    runtime: string | null;
+    preserve: string[];
+};
+/**
+ * `jam uninstall` - remove what JAM installed, keep what is the person's.
+ *
+ * Removed: the MCP registrations JAM wrote, and the global launcher when one
+ * is installed. Kept: `~/.jam` in full - the project bindings, the runtime
+ * choice and the credentials in the OS secret store. There is no purge here
+ * on purpose: nothing yet needs a command that destroys those, and an
+ * irreversible one that nobody asked for is worse than a missing one.
+ */
+export declare function planUninstall(hosts: readonly HostState[], installed: string | null): UninstallPlan;
+export declare function jamUninstallCommand(command: string | undefined, options?: LifecycleOptions): Promise<number>;
+/**
+ * `jam status` - the first place a person asks what is going on.
+ *
+ * This is `doctor`'s user-facing role under the name both products use. The
+ * judgement is not reimplemented: the same health gate and the same per-axis
+ * verdicts answer here, so the two commands can never disagree.
+ */
+export declare function jamStatusCommand(options?: {
+    json?: boolean;
+}): Promise<number>;

package/dist/cli/lifecycle.js

@@ -0,0 +1,233 @@
+import { LAUNCHER_PACKAGE, SERVER_VERSION } from "@jam-mcp/launcher";
+import { spawnSync } from "node:child_process";
+import { doctorJsonCommand } from "./agent-api.js";
+import { doctor } from "./doctor.js";
+import { detectHosts, hostRegistration, hostUnregistration, } from "../bootstrap/host-mcp.js";
+/**
+ * The lifecycle words JAM shares with ASC: `refresh` and `uninstall`.
+ *
+ * The two products answer to the same vocabulary because a person should not
+ * have to remember which one uses which verb:
+ *
+ *   setup      make it usable for the first time
+ *   status     what is configured, what works, what is blocked
+ *   update     move to a newer published release
+ *   refresh    keep the version, re-converge what this build registered
+ *   uninstall  remove the product; the person's state stays
+ *   runtime    which build this machine actually runs
+ *
+ * What is different is ownership, and that stays different. JAM is the Jira
+ * access layer: it has no execution mode, no approval path and no session
+ * model. A Jira write still travels ASC's decision path and lands through
+ * JAM's own write plan/apply - this file does not change that.
+ */
+/** A runner with room for npm. The host runner's 20s is not enough for an install. */
+const defaultRunner = ({ command, args }) => {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        timeout: 180_000,
+        shell: process.platform === "win32",
+    });
+    if (result.error)
+        return { status: null, failed: true, stdout: "" };
+    return { status: result.status, failed: false, stdout: result.stdout ?? "" };
+};
+/**
+ * What `refresh` would converge. Pure: it runs nothing and writes nothing.
+ *
+ * The scope is deliberately small. A registration that points at a different
+ * launcher than this build is what goes stale here. The project binding, the
+ * credentials, `~/.jam/config.yaml` and every byte of Jira data are outside
+ * it - re-deciding those is `setup`, and calling it "refresh" is how a person
+ * loses a binding they never asked to change.
+ */
+export function planRefresh(hosts, version = SERVER_VERSION) {
+    const registered = hosts.filter((host) => host.cliAvailable && host.hasJamEntry);
+    const plans = registered.map((host) => ({
+        id: host.id,
+        ...(host.entryVersion ? { from: host.entryVersion } : {}),
+        bare: host.entryBare === true,
+        // A bare entry runs the global executable, so its line is already whatever
+        // that executable is. Only a pinned line can point somewhere else.
+        action: host.entryBare === true || host.entryVersion === version ? "none" : "repin",
+    }));
+    const moving = plans.filter((host) => host.action === "repin");
+    return {
+        version,
+        hosts: plans,
+        steps: moving.length === 0 ? [] : ["switch-registration", "verify"],
+    };
+}
+export function refreshLine(plan) {
+    const moving = plan.hosts.filter((host) => host.action === "repin");
+    if (plan.hosts.length === 0)
+        return "No host has a JAM registration - `jam setup` is what adds one.";
+    return moving.length === 0
+        ? `Registration is current - JAM ${plan.version}. Version unchanged.`
+        : `Would re-register: ${moving.map((host) => `${host.id} runs ${host.from ?? "?"}`).join(", ")}`;
+}
+/**
+ * `jam refresh` - keep the version, make the registration match it again.
+ *
+ * Nothing is removed before the replacement is known to work, which is the
+ * same order `update` uses and for the same reason: a failed refresh leaves
+ * the machine running what it was running.
+ */
+export async function jamRefreshCommand(command, options = {}) {
+    if (command !== undefined && command !== "check" && command !== "plan") {
+        process.stderr.write(`Unknown refresh command: ${command}\nUsage: jam refresh [check|plan] [--json]\n`);
+        return 1;
+    }
+    const run = options.run ?? defaultRunner;
+    const hosts = (options.hosts ?? (() => detectHosts(run)))();
+    const plan = planRefresh(hosts);
+    if (command === "check" || command === "plan") {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan }, null, 2)}\n`);
+        else
+            process.stdout.write(`${refreshLine(plan)}\n`);
+        return 0;
+    }
+    if (plan.steps.length === 0) {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan, changed: [] }, null, 2)}\n`);
+        else
+            process.stdout.write(`${refreshLine(plan)}\n`);
+        return 0;
+    }
+    const changed = [];
+    for (const host of plan.hosts.filter((h) => h.action === "repin")) {
+        // `mcp add` over an existing entry changes nothing on Claude Code - it
+        // answers "already exists". The removal is what makes the re-pin land.
+        const remove = hostUnregistration(host.id);
+        if (remove)
+            run(remove);
+        const register = hostRegistration(host.id, { version: plan.version });
+        if (!register)
+            continue;
+        const result = run(register);
+        if (result.failed || result.status !== 0) {
+            process.stderr.write(`refresh failed on ${host.id} - re-register with \`jam setup --agent\`.\n`);
+            return 1;
+        }
+        changed.push(host.id);
+    }
+    // Read it back. A registration JAM could not verify is never reported as done.
+    const after = (options.hosts ?? (() => detectHosts(run)))();
+    const stale = after.filter((host) => changed.includes(host.id) && host.entryBare !== true && host.entryVersion !== plan.version);
+    if (stale.length > 0) {
+        process.stderr.write(`health: ${stale.map((host) => `${host.id} still runs ${host.entryVersion ?? "?"}`).join(", ")}\n`);
+        return 1;
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan, changed }, null, 2)}\n`);
+    }
+    else {
+        for (const id of changed)
+            process.stdout.write(`registered: ${id} -> ${plan.version}\n`);
+        process.stdout.write(`JAM ${plan.version} is registered. Version unchanged.\n`);
+    }
+    return 0;
+}
+/**
+ * `jam uninstall` - remove what JAM installed, keep what is the person's.
+ *
+ * Removed: the MCP registrations JAM wrote, and the global launcher when one
+ * is installed. Kept: `~/.jam` in full - the project bindings, the runtime
+ * choice and the credentials in the OS secret store. There is no purge here
+ * on purpose: nothing yet needs a command that destroys those, and an
+ * irreversible one that nobody asked for is worse than a missing one.
+ */
+export function planUninstall(hosts, installed) {
+    return {
+        hosts: hosts.filter((host) => host.cliAvailable && host.hasJamEntry).map((host) => host.id),
+        runtime: installed,
+        preserve: [
+            "~/.jam/projects.yaml - which project each checkout is bound to",
+            "~/.jam/config.yaml - the runtime this machine chose",
+            "Jira credentials in the OS secret store",
+            "every .jira-agent/project.yaml a repository carries",
+        ],
+    };
+}
+export async function jamUninstallCommand(command, options = {}) {
+    if (command !== undefined && command !== "plan") {
+        process.stderr.write(`Unknown uninstall command: ${command}\nUsage: jam uninstall [plan] [--json]\n`);
+        return 1;
+    }
+    const run = options.run ?? defaultRunner;
+    const hosts = (options.hosts ?? (() => detectHosts(run)))();
+    const installed = globalLauncher(run);
+    const plan = planUninstall(hosts, installed);
+    if (command === "plan") {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+        else {
+            process.stdout.write(plan.hosts.length === 0
+                ? "No host registration to remove.\n"
+                : `Would remove the JAM registration from: ${plan.hosts.join(", ")}\n`);
+            if (plan.runtime)
+                process.stdout.write(`Would remove ${LAUNCHER_PACKAGE}@${plan.runtime}\n`);
+            for (const kept of plan.preserve)
+                process.stdout.write(`Would keep: ${kept}\n`);
+        }
+        return 0;
+    }
+    let worst = 0;
+    for (const id of plan.hosts) {
+        const remove = hostUnregistration(id);
+        if (!remove)
+            continue;
+        const result = run(remove);
+        if (result.failed || result.status !== 0) {
+            process.stderr.write(`could not remove the registration from ${id}\n`);
+            worst = 1;
+            continue;
+        }
+        process.stdout.write(`removed: ${id} registration\n`);
+    }
+    if (plan.runtime) {
+        const removal = run({ command: "npm", args: ["uninstall", "-g", LAUNCHER_PACKAGE] });
+        if (removal.failed || removal.status !== 0) {
+            process.stderr.write(`could not remove ${LAUNCHER_PACKAGE} - run: npm uninstall -g ${LAUNCHER_PACKAGE}\n`);
+            worst = 1;
+        }
+        else {
+            process.stdout.write(`removed: ${LAUNCHER_PACKAGE}@${plan.runtime}\n`);
+        }
+    }
+    process.stdout.write("\nYour state stays:\n");
+    for (const kept of plan.preserve)
+        process.stdout.write(`  ${kept}\n`);
+    return worst;
+}
+/** The globally installed launcher version, or null when there is none. */
+function globalLauncher(run) {
+    const result = run({ command: "npm", args: ["ls", "-g", "--depth=0", "--json", LAUNCHER_PACKAGE] });
+    if (result.failed)
+        return null;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return parsed.dependencies?.[LAUNCHER_PACKAGE]?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `jam status` - the first place a person asks what is going on.
+ *
+ * This is `doctor`'s user-facing role under the name both products use. The
+ * judgement is not reimplemented: the same health gate and the same per-axis
+ * verdicts answer here, so the two commands can never disagree.
+ */
+export async function jamStatusCommand(options = {}) {
+    if (options.json)
+        return doctorJsonCommand();
+    process.stdout.write(`jam ${SERVER_VERSION}\n`);
+    const code = await doctor();
+    process.stdout.write(code === 0
+        ? "\nNext: nothing - reading Jira is ready. `jam update` when a newer release is out.\n"
+        : "\nNext: `jam setup` binds this project and stores what is missing. `jam refresh` only re-registers.\n");
+    return code;
+}

package/dist/cli/update.d.ts

@@ -0,0 +1,74 @@
+import { type HostId, type HostRunner } from "../bootstrap/host-mcp.js";
+/**
+ * `jam update` - move this machine to the published release without redoing setup.
+ *
+ * What actually goes stale here is not a directory. JAM is launched by the
+ * host from a registration line, and that line carries an exact pin:
+ *
+ *   jam: npx --yes @jam-mcp/launcher@1.4.5 serve
+ *
+ * A newer JAM on the registry changes nothing until that line moves. Right
+ * after 1.4.6 was published, this machine measured
+ * `registration: HOST_REGISTRATION_STALE (registered 1.4.5)` - the agent was
+ * still talking to the previous server. The command that fixed it was
+ * `jam setup --agent`, which also binds the project, re-detects credentials
+ * and re-plans everything else. Re-running setup is not what "update" means,
+ * so this path never calls it.
+ *
+ * The order is the same one ASC uses, and for the same reason: the new build
+ * is proven to answer *before* the registration is pointed at it. Nothing is
+ * removed first - a failed update leaves the machine running what it was
+ * running.
+ */
+export type UpdateStep = "install" | "verify-install" | "switch-registration" | "verify-health";
+export declare const UPDATE_ORDER: readonly UpdateStep[];
+export type UpdateState = 
+/** Every registration this machine has runs the published release. */
+"CURRENT" | "UPDATE_AVAILABLE"
+/** A registration exists whose version cannot be read - it may run anything. */
+ | "BROKEN"
+/** The registry could not be asked. Nothing is claimed about being up to date. */
+ | "UNKNOWN";
+export type HostPlan = {
+    id: HostId;
+    from?: string;
+    /** A bare `jam serve` entry: the version lives in the global install, not the line. */
+    bare: boolean;
+    action: "repin" | "none" | "unreadable";
+};
+export type JamUpdatePlan = {
+    state: UpdateState;
+    latest?: string;
+    running: string;
+    hosts: HostPlan[];
+    steps: readonly UpdateStep[];
+    detail?: string;
+};
+export type HostFacts = {
+    id: HostId;
+    cliAvailable: boolean;
+    hasJamEntry: boolean;
+    entryVersion?: string;
+    entryBare?: boolean;
+};
+/**
+ * Decide, from what was measured. Pure - it runs nothing and writes nothing.
+ *
+ * A host with no `jam` entry is left alone. Registering JAM somewhere it was
+ * never registered is adoption, not an update, and `jam setup` is where the
+ * person says they want that.
+ */
+export declare function planJamUpdate(input: {
+    latest?: string;
+    hosts: HostFacts[];
+}): JamUpdatePlan;
+export declare function updateLine(plan: JamUpdatePlan): string;
+export type UpdateOptions = {
+    json?: boolean;
+    /** Injected by tests. Nothing here may reach a real host CLI or npm unasked. */
+    run?: HostRunner;
+    /** Injected by tests so a plan never depends on the registry. */
+    latest?: () => string | undefined;
+    hosts?: () => HostFacts[];
+};
+export declare function jamUpdateCommand(command: string | undefined, options?: UpdateOptions): Promise<number>;

package/dist/cli/update.js

@@ -0,0 +1,233 @@
+import { LAUNCHER_PACKAGE, SERVER_VERSION } from "@jam-mcp/launcher";
+import { spawnSync } from "node:child_process";
+import { detectHosts, hostRegistration, hostUnregistration, } from "../bootstrap/host-mcp.js";
+export const UPDATE_ORDER = [
+    "install",
+    "verify-install",
+    "switch-registration",
+    "verify-health",
+];
+/**
+ * Decide, from what was measured. Pure - it runs nothing and writes nothing.
+ *
+ * A host with no `jam` entry is left alone. Registering JAM somewhere it was
+ * never registered is adoption, not an update, and `jam setup` is where the
+ * person says they want that.
+ */
+export function planJamUpdate(input) {
+    const running = SERVER_VERSION;
+    const registered = input.hosts.filter((host) => host.cliAvailable && host.hasJamEntry);
+    if (!input.latest) {
+        return {
+            state: "UNKNOWN",
+            running,
+            hosts: [],
+            steps: [],
+            detail: "the registry could not be asked - nothing is claimed about being up to date",
+        };
+    }
+    const hosts = registered.map((host) => ({
+        id: host.id,
+        ...(host.entryVersion ? { from: host.entryVersion } : {}),
+        bare: host.entryBare === true,
+        action: host.entryVersion === undefined
+            ? "unreadable"
+            : host.entryVersion === input.latest
+                ? "none"
+                : "repin",
+    }));
+    // An entry whose version cannot be read is not "current" - it is a line
+    // running something nobody measured. Say that instead of moving it silently.
+    if (hosts.some((host) => host.action === "unreadable")) {
+        return {
+            state: "BROKEN",
+            latest: input.latest,
+            running,
+            hosts,
+            steps: [...UPDATE_ORDER],
+            detail: "a registration exists whose version could not be read",
+        };
+    }
+    if (hosts.every((host) => host.action === "none")) {
+        return { state: "CURRENT", latest: input.latest, running, hosts, steps: [] };
+    }
+    return { state: "UPDATE_AVAILABLE", latest: input.latest, running, hosts, steps: [...UPDATE_ORDER] };
+}
+export function updateLine(plan) {
+    switch (plan.state) {
+        case "CURRENT":
+            return `Up to date - JAM ${plan.latest} is registered.`;
+        case "UPDATE_AVAILABLE": {
+            const moving = plan.hosts.filter((host) => host.action === "repin");
+            return `Update available - ${plan.latest}: ${moving
+                .map((host) => `${host.id} runs ${host.from}`)
+                .join(", ")}`;
+        }
+        case "BROKEN":
+        case "UNKNOWN":
+            return `${plan.state}: ${plan.detail ?? "(no detail)"}`;
+    }
+}
+/** A process runner with room for an install. The host runner's 20s is not enough for npm. */
+const defaultRunner = ({ command, args }) => {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        timeout: 180_000,
+        shell: process.platform === "win32",
+    });
+    if (result.error)
+        return { status: null, failed: true, stdout: "" };
+    return { status: result.status, failed: false, stdout: result.stdout ?? "" };
+};
+export async function jamUpdateCommand(command, options = {}) {
+    if (command !== undefined && command !== "check" && command !== "plan") {
+        process.stderr.write(`Unknown update command: ${command}\nUsage: jam update [check|plan] [--json]\n`);
+        return 1;
+    }
+    const run = options.run ?? defaultRunner;
+    const latest = (options.latest ?? (() => registryLatest(run)))();
+    const facts = (options.hosts ?? (() => detectHosts(run)))();
+    const plan = planJamUpdate({ ...(latest ? { latest } : {}), hosts: facts });
+    if (command === "check" || command === "plan") {
+        emit(plan, options);
+        return 0;
+    }
+    if (plan.steps.length === 0) {
+        emit(plan, options);
+        return plan.state === "CURRENT" ? 0 : 1;
+    }
+    return apply(plan, run, options);
+}
+function emit(plan, options) {
+    if (options.json)
+        process.stdout.write(`${JSON.stringify({ package: LAUNCHER_PACKAGE, ...plan }, null, 2)}\n`);
+    else
+        process.stdout.write(`${updateLine(plan)}\n`);
+}
+/** What the registry has. undefined when it could not be asked - never a guess. */
+function registryLatest(run) {
+    const result = run({ command: "npm", args: ["view", LAUNCHER_PACKAGE, "version"] });
+    if (result.failed || result.status !== 0)
+        return undefined;
+    const version = result.stdout.trim();
+    return /^\d+\.\d+\.\d+/.test(version) ? version : undefined;
+}
+/**
+ * Does that version actually answer?
+ *
+ * `runtime status --json` is the cheapest honest question: it resolves the
+ * runtime the registered entry would resolve, and needs no bound project. A
+ * pin that cannot answer here is one the host would fail to start - which is
+ * exactly what must not be registered.
+ */
+function launcherAnswers(run, version, bare) {
+    const result = bare
+        ? run({ command: "jam", args: ["runtime", "status", "--json"] })
+        : run({ command: "npx", args: ["--yes", `${LAUNCHER_PACKAGE}@${version}`, "runtime", "status", "--json"] });
+    if (result.failed || result.status !== 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function apply(plan, run, options) {
+    const target = plan.latest;
+    process.stdout.write(`${updateLine(plan)}\n`);
+    const moving = plan.hosts.filter((host) => host.action !== "none");
+    // A bare entry runs the global executable, so that is what has to move.
+    // An npx pin is fetched at launch; verifying it is what "install" means there.
+    if (moving.some((host) => host.bare)) {
+        const installed = run({ command: "npm", args: ["install", "-g", `${LAUNCHER_PACKAGE}@${target}`] });
+        if (installed.failed || installed.status !== 0) {
+            process.stderr.write(`install failed: npm install -g ${LAUNCHER_PACKAGE}@${target}\n`);
+            // Nothing was re-registered. The machine still runs what it ran.
+            return 1;
+        }
+    }
+    for (const host of moving) {
+        const answered = launcherAnswers(run, target, host.bare);
+        if (answered !== target) {
+            process.stderr.write(`verify failed: ${target} did not answer as ${target}${answered ? ` (got ${answered})` : ""} - registration left as it is\n`);
+            return 1;
+        }
+    }
+    process.stdout.write(`verified: ${LAUNCHER_PACKAGE}@${target} answers\n`);
+    for (const host of moving) {
+        // `mcp add` over an existing entry changes nothing on Claude Code - it
+        // answers "already exists". The removal is what makes the re-pin land.
+        if (!host.bare) {
+            const remove = hostUnregistration(host.id);
+            if (remove)
+                run(remove);
+        }
+        const register = hostRegistration(host.id, { ...(host.bare ? { bare: true } : { version: target }) });
+        if (!register)
+            continue;
+        const result = run(register);
+        if (result.failed || result.status !== 0) {
+            process.stderr.write(`switch failed on ${host.id}\n`);
+            return rollback(plan, host, run);
+        }
+        process.stdout.write(`registered: ${host.id} -> ${target}\n`);
+    }
+    // Read it back. A registration JAM could not verify is never reported as done.
+    const after = (options.hosts ?? (() => detectHosts(run)))();
+    const stale = after.filter((host) => moving.some((m) => m.id === host.id) && host.entryVersion !== target);
+    if (stale.length > 0) {
+        process.stderr.write(`health: ${stale.map((host) => `${host.id} still runs ${host.entryVersion ?? "?"}`).join(", ")}\n`);
+        return 1;
+    }
+    // A registration that points at a build which cannot read Jira is not a
+    // finished update. `doctor` is the existing health axis - config, credentials
+    // and one live read - so it is asked here rather than reimplemented.
+    const health = doctorVerdict(run, target, moving.some((host) => host.bare));
+    if (health !== "ready") {
+        process.stderr.write(`doctor: ${health} - rolling back\n`);
+        const first = moving[0];
+        return first ? rollback(plan, first, run) : 1;
+    }
+    process.stdout.write(`JAM ${target} is registered, doctor ready.\n`);
+    return 0;
+}
+/**
+ * What `jam doctor --json` says about the build now registered.
+ *
+ * Run through the same entry the host would run, so this measures the thing
+ * that was just registered rather than the process doing the registering.
+ */
+function doctorVerdict(run, version, bare) {
+    const result = bare
+        ? run({ command: "jam", args: ["doctor", "--json"] })
+        : run({ command: "npx", args: ["--yes", `${LAUNCHER_PACKAGE}@${version}`, "doctor", "--json"] });
+    if (result.failed)
+        return "could not be run";
+    try {
+        const parsed = JSON.parse(result.stdout);
+        return typeof parsed.status === "string" ? parsed.status : "unreadable";
+    }
+    catch {
+        return result.status === 0 ? "ready" : "unreadable";
+    }
+}
+/** Put back the pin that was there. Only possible when it was readable. */
+function rollback(plan, host, run) {
+    if (!host.from || host.bare) {
+        process.stderr.write(`Nothing to roll back to on ${host.id} - re-register with \`jam setup --agent\`.\n`);
+        return 1;
+    }
+    const remove = hostUnregistration(host.id);
+    if (remove)
+        run(remove);
+    const back = hostRegistration(host.id, { version: host.from });
+    const result = back ? run(back) : undefined;
+    if (result && !result.failed && result.status === 0) {
+        process.stderr.write(`rolled back - ${host.id} runs ${host.from} again.\n`);
+        return 1;
+    }
+    process.stderr.write(`rollback failed on ${host.id} - re-register with \`jam setup --agent\`.\n`);
+    return 1;
+}

package/dist/cli-entry.d.ts

@@ -3,5 +3,5 @@
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
  * instead of reimplementing them.
  */
-export declare const USAGE = "jam - Jira Agent MCP\n\nUsage:\n  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)\n  jam doctor              Diagnose config, credentials and Jira connectivity\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and run doctor. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n  jam auth login          Store Jira credentials in this user's OS secret store\n  jam auth logout         Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam doctor --json       Health check as structured output\n  jam auth status --json  Whether Jira credentials are configured (never their value)\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n                          Read Jira from the shell - the same reads the MCP\n                          tools do, for a session that cannot see them yet\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
+export declare const USAGE = "jam - Jira Agent MCP\n\nLifecycle (the same words ASC uses)\n  jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]\n                          Wire up this project and verify it. Binds it to you\n                          alone, writing nothing to the repository; --shared\n                          adopts JAM for the team (project.yaml, .mcp.json)\n  jam status              What is configured, what works, what is blocked\n  jam update              Move this machine's registration to the published release\n  jam refresh             Keep the version; re-register what this build owns\n  jam uninstall           Remove JAM's registrations; your bindings and credentials stay\n  jam runtime             Show which JAM build this machine runs\n  jam runtime use package | development <path>\n                          Change it (writes ~/.jam/config.yaml only, never a project)\n\nJira\n  jam jira search <jql> [--scope preview|complete]\n  jam jira context <KEY> [KEY...]\n  jam jira full <KEY> [KEY...]\n                          Read Jira from the shell - the same reads the MCP\n                          tools do, for a session that cannot see them yet\n\nAuthentication\n  jam auth status [--json]  Whether Jira credentials are configured (never their value)\n  jam auth login            Store them in this user's OS secret store\n  jam auth logout           Remove them again\n\nFor coding agents and scripts (stdout is JSON only, never prompts):\n  jam setup --agent       One shot: detect, plan, apply what is safe, verify\n  jam setup plan --json   Report what setup would change, changing nothing\n  jam setup apply --non-interactive --json\n                          Execute the plan\n  jam status --json       Health check as structured output\n  jam update check|plan [--json]\n  jam refresh check|plan [--json]\n  jam uninstall plan [--json]\n\nHost runtime\n  jam serve               Run the MCP server over stdio - this is what Claude\n                          Code and Codex launch. Not a command a person types.\n\nEnvironment:\n  JIRA_BASE_URL     https://your-site.atlassian.net\n  JIRA_EMAIL        Atlassian account email\n  JIRA_API_TOKEN    Atlassian API token\n  JAM_PROJECT_KEY   Jira project key, used by `jam setup`/`jam serve` when no\n                     .jira-agent/project.yaml exists yet\n\nCredentials and JAM_PROJECT_KEY are read from the current shell's environment\nfirst, then (on Windows) from the User environment - so a value set with\n`setx` works without opening a new terminal.\n";
 export declare function runJamCommand(argv: string[]): Promise<number>;

package/dist/cli-entry.js

@@ -3,6 +3,8 @@ import { doctor } from "./cli/doctor.js";
 import { showRuntime, useRuntime } from "./cli/runtime.js";
 import { serve } from "./cli/serve.js";
 import { setup } from "./cli/setup.js";
+import { jamUpdateCommand } from "./cli/update.js";
+import { jamRefreshCommand, jamStatusCommand, jamUninstallCommand } from "./cli/lifecycle.js";
 import { runSetupWizard } from "./cli/setup-wizard.js";
 import { reportPromptError, Ui } from "./cli/ui.js";
 import { authStatusCommand, doctorJsonCommand, setupAgentCommand, setupApplyCommand, setupPlanCommand, } from "./cli/agent-api.js";
@@ -14,32 +16,45 @@ import { runJiraRead } from "./cli/jira-read.js";
  */
 export const USAGE = `jam - Jira Agent MCP
 
-Usage:
-  jam serve               Run the MCP server over stdio (default; this is what Claude Code / Codex launch)
-  jam doctor              Diagnose config, credentials and Jira connectivity
+Lifecycle (the same words ASC uses)
   jam setup [--project KEY] [--shared] [--migrate] [--non-interactive]
-                          Wire up this project and run doctor. Binds it to you
+                          Wire up this project and verify it. Binds it to you
                           alone, writing nothing to the repository; --shared
                           adopts JAM for the team (project.yaml, .mcp.json)
+  jam status              What is configured, what works, what is blocked
+  jam update              Move this machine's registration to the published release
+  jam refresh             Keep the version; re-register what this build owns
+  jam uninstall           Remove JAM's registrations; your bindings and credentials stay
   jam runtime             Show which JAM build this machine runs
   jam runtime use package | development <path>
                           Change it (writes ~/.jam/config.yaml only, never a project)
-  jam auth login          Store Jira credentials in this user's OS secret store
-  jam auth logout         Remove them again
 
-For coding agents and scripts (stdout is JSON only, never prompts):
-  jam setup --agent       One shot: detect, plan, apply what is safe, verify
-  jam setup plan --json   Report what setup would change, changing nothing
-  jam setup apply --non-interactive --json
-                          Execute the plan
-  jam doctor --json       Health check as structured output
-  jam auth status --json  Whether Jira credentials are configured (never their value)
+Jira
   jam jira search <jql> [--scope preview|complete]
   jam jira context <KEY> [KEY...]
   jam jira full <KEY> [KEY...]
                           Read Jira from the shell - the same reads the MCP
                           tools do, for a session that cannot see them yet
 
+Authentication
+  jam auth status [--json]  Whether Jira credentials are configured (never their value)
+  jam auth login            Store them in this user's OS secret store
+  jam auth logout           Remove them again
+
+For coding agents and scripts (stdout is JSON only, never prompts):
+  jam setup --agent       One shot: detect, plan, apply what is safe, verify
+  jam setup plan --json   Report what setup would change, changing nothing
+  jam setup apply --non-interactive --json
+                          Execute the plan
+  jam status --json       Health check as structured output
+  jam update check|plan [--json]
+  jam refresh check|plan [--json]
+  jam uninstall plan [--json]
+
+Host runtime
+  jam serve               Run the MCP server over stdio - this is what Claude
+                          Code and Codex launch. Not a command a person types.
+
 Environment:
   JIRA_BASE_URL     https://your-site.atlassian.net
   JIRA_EMAIL        Atlassian account email
@@ -77,7 +92,12 @@ export async function runJamCommand(argv) {
     switch (command ?? "serve") {
         case "serve":
             return serve();
+        case "status":
+            return jamStatusCommand({ json: rest.includes("--json") });
+        // The old name for the same question. It keeps working for two minor
+        // releases; `status` is the word both products answer to.
         case "doctor":
+            process.stderr.write("Deprecated. Use `jam status`.\n");
             return rest.includes("--json") ? doctorJsonCommand() : doctor();
         case "setup": {
             const explicitKey = findFlagValue(rest, "--project");
@@ -99,6 +119,22 @@ export async function runJamCommand(argv) {
             // The wizard can ask; the plain path never does.
             return rest.includes("--non-interactive") ? setup(common) : runSetupWizard(common);
         }
+        case "update":
+            // Not `setup` again: setup re-plans the project binding, credentials and
+            // everything else. An update moves the registration pin and nothing more.
+            return jamUpdateCommand(rest[0] === "--json" ? undefined : rest[0], {
+                json: rest.includes("--json"),
+            });
+        case "refresh":
+            // Not `update`: the version does not move here. Only the registration
+            // this build owns is brought back to it.
+            return jamRefreshCommand(rest[0]?.startsWith("--") ? undefined : rest[0], {
+                json: rest.includes("--json"),
+            });
+        case "uninstall":
+            return jamUninstallCommand(rest[0]?.startsWith("--") ? undefined : rest[0], {
+                json: rest.includes("--json"),
+            });
         case "runtime": {
             const json = rest.includes("--json");
             if (rest[0] === "use")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jam-mcp/server",
-  "version": "1.4.6",
+  "version": "1.6.0",
   "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.6",
+    "@jam-mcp/launcher": "1.6.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"