@jam-mcp/server 1.5.0 → 1.7.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.5.0 doctor`, or just `jam
+Written out, that is `npx --yes @jam-mcp/launcher@1.7.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.5.0 init` instead.
+`npx --yes @jam-mcp/bootstrap@1.7.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/application/apply-create-issue.js

@@ -1,7 +1,8 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { canonicalizePlainText } from "../domain/adf.js";
-import { assertSchemaUnchanged } from "../policy/create-policy.js";
+import { assertSchemaUnchanged, CREATE_FIELD_IDS } from "../policy/create-policy.js";
 import { projectKeyOf } from "../policy/write-policy.js";
+import { toJiraCreateFields, validateCreateInput } from "./plan-create-issue.js";
 import { readIssue } from "./plan-write.js";
 /**
  * Create the issue a plan describes, then go and look at what was created.
@@ -24,6 +25,11 @@ export async function applyCreateIssue(deps, plan) {
     if (plan.mutation.kind !== "create") {
         throw new JamError("CONFIG_INVALID", "A create-issue plan must carry a create mutation.");
     }
+    // Plans come off disk now, so the fields being sent are checked against what
+    // this plan's own input produces before anything is created. Editing the
+    // stored mutation without editing the input is caught here; editing both is
+    // asking JAM to plan that create, which is the supported way to get one.
+    assertCreateMutationMatchesInput(plan);
     await revalidateSchema(deps, plan);
     const created = await create(deps, plan);
     const { observed: after, issueId } = await verify(deps, plan, created);
@@ -45,6 +51,47 @@ export async function applyCreateIssue(deps, plan) {
  * not "is the schema identical" - on an active project it rarely is - but "are
  * this plan's premises still true". See assertSchemaUnchanged.
  */
+/**
+ * Check the stored create fields are the ones this plan's input produces.
+ *
+ * The existing-issue path does the same thing in apply-write.ts, and for the
+ * same reason: a plan is a file, and re-deriving is what makes editing it
+ * pointless. Creation can do it without touching Jira - `toJiraCreateFields`
+ * is pure once the issue type and resolved values are known, and those are in
+ * `schemaRequirements`, which `revalidateSchema` checks against Jira right
+ * after this.
+ *
+ * Nothing has been created when this refuses.
+ */
+function assertCreateMutationMatchesInput(plan) {
+    const { schemaRequirements: schema } = plan;
+    // One entry per requested value, so a component list resolves item by item -
+    // matching on fieldId alone would give every component the first one's answer.
+    const resolvedFor = (fieldId, requested) => schema.resolvedValues.find((entry) => entry.fieldId === fieldId && entry.requested === requested)
+        ?.resolved;
+    let derived;
+    try {
+        const input = validateCreateInput(plan.input);
+        const priority = input.priority !== undefined
+            ? resolvedFor(CREATE_FIELD_IDS.priority, input.priority)
+            : undefined;
+        derived = toJiraCreateFields(plan.projectKey, schema.issueTypeId, input, {
+            ...(priority !== undefined ? { priority } : {}),
+            ...(input.components !== undefined
+                ? {
+                    components: input.components.map((name) => resolvedFor(CREATE_FIELD_IDS.components, name) ?? name),
+                }
+                : {}),
+        });
+    }
+    catch (err) {
+        throw new JamError("JAM_WRITE_PLAN_TAMPERED", `This create plan does not describe an issue JAM would create in ${plan.projectKey}. Nothing was created - call jira_write_plan again.`, { planId: plan.planId, project: plan.projectKey, reason: toJamError(err).code });
+    }
+    const recorded = plan.mutation.kind === "create" ? plan.mutation.fields : undefined;
+    if (JSON.stringify(derived) !== JSON.stringify(recorded)) {
+        throw new JamError("JAM_WRITE_PLAN_TAMPERED", `This create plan's recorded fields do not match what its input produces. Nothing was created - call jira_write_plan again.`, { planId: plan.planId, project: plan.projectKey });
+    }
+}
 async function revalidateSchema(deps, plan) {
     const { projectKey, schemaRequirements } = plan;
     const issueTypes = await deps.jiraCreateMetadata.getIssueTypes(projectKey);

package/dist/application/apply-write.js

@@ -3,7 +3,7 @@ import { readModeAfterWrite } from "../policy/consistency-policy.js";
 import { assertAssignable } from "../policy/assignee-policy.js";
 import { assertSameIssue, assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
-import { readIssue } from "./plan-write.js";
+import { readIssue, toJiraFields, validateInput } from "./plan-write.js";
 /**
  * Execute a plan JAM made, then go and look at what happened.
  *
@@ -41,6 +41,11 @@ export async function applyWritePlan(deps, request) {
     // and comparing it would be answering the wrong question.
     assertSameIssue(plan.issueKey, plan.issueId, current.issueId);
     assertUnchanged(plan.issueKey, plan.baseUpdated, current.issue.updated);
+    // The plan came off disk, so derive its mutation again and check it is the
+    // one stored. This is after the revision check on purpose: a moved issue is
+    // a conflict, not tampering, and saying so in that order keeps the two
+    // situations from being reported as each other.
+    assertMutationMatchesInput(plan);
     // Whatever the plan depends on that the revision check cannot see, checked
     // again here. For an assignment that is the target's permission to hold this
     // issue: it can be revoked between planning and applying, and a plan that
@@ -60,6 +65,82 @@ export async function applyWritePlan(deps, request) {
         ...(outcome.commentId ? { commentId: outcome.commentId } : {}),
     };
 }
+/**
+ * Check the stored mutation is the one this plan's input produces.
+ *
+ * Plans used to live in the process that made them, so what apply sent could
+ * only have come from planning. They live in a file now - shared so that a
+ * session whose MCP channel died can still apply one from the shell - and a
+ * file can be edited.
+ *
+ * What replaces the in-process guarantee is this: run the same derivation
+ * planning ran, on the plan's own input, and refuse if the answer differs.
+ * Editing `mutation` alone is caught here. Editing `input` to match means
+ * asking JAM to derive that mutation, which is what `jira_write_plan` is - so
+ * there is nothing to gain by forging a plan that could not be obtained by
+ * asking for one.
+ *
+ * Nothing has been sent to Jira when this refuses.
+ */
+function assertMutationMatchesInput(plan) {
+    let derived;
+    try {
+        // Through validateInput first: the whitelist is part of the derivation, so
+        // a plan carrying a field JAM does not write is refused here rather than
+        // sent. Re-deriving without it would let an edited input past the check
+        // planning applied to it.
+        const input = validateInput(plan.operation, plan.input);
+        derived = deriveMutation(plan, input);
+    }
+    catch (err) {
+        // A plan whose input no longer derives anything is not a plan. Say that,
+        // rather than letting the original refusal read as a fresh request being
+        // rejected.
+        throw new JamError("JAM_WRITE_PLAN_TAMPERED", `This write plan does not describe a change JAM would make for ${plan.issueKey}. Nothing was written - call jira_write_plan again.`, { planId: plan.planId, issueKey: plan.issueKey, reason: toJamError(err).code });
+    }
+    if (JSON.stringify(derived) !== JSON.stringify(plan.mutation)) {
+        throw new JamError("JAM_WRITE_PLAN_TAMPERED", `This write plan's recorded change does not match what its input produces for ${plan.issueKey}. Nothing was written - call jira_write_plan again.`, { planId: plan.planId, issueKey: plan.issueKey });
+    }
+}
+/**
+ * The mutation this plan's input produces, without asking Jira anything.
+ *
+ * Planning calls Jira for two of these - the transition list, the user
+ * directory - and records what it settled on. Re-deriving here reads those
+ * recorded answers rather than fetching them again, for two reasons: apply
+ * would otherwise pay a round trip it does not need, and planning's lookups
+ * carry refusals that belong to planning (`already assigned`, `not
+ * assignable`). Running those a second time would report a check on the
+ * current state as if the plan were malformed.
+ *
+ * What is being checked is narrower and enough: the mutation must be the one
+ * this plan's own parts describe. An edit to `mutation` alone is caught. An
+ * edit that also rewrites the input and the recorded resolution is a different
+ * plan, obtainable by asking for one - and Jira still has to accept it.
+ */
+function deriveMutation(plan, input) {
+    switch (plan.operation) {
+        case "comment.add":
+            return { kind: "comment", text: input.text };
+        case "field.update":
+            return { kind: "fields", fields: toJiraFields(input) };
+        case "status.transition": {
+            // The id came from Jira at plan time and is recorded; what is verified is
+            // that the plan still points at its own resolution.
+            const transition = plan.transition;
+            if (!transition)
+                throw new JamError("CONFIG_INVALID", "A transition plan must record its transition.");
+            return { kind: "transition", transitionId: transition.id };
+        }
+        case "assignee.update": {
+            const target = plan.intendedAfter["assignee"];
+            if (!target?.accountId) {
+                throw new JamError("CONFIG_INVALID", "An assignment plan must record who it resolved to.");
+            }
+            return { kind: "assignee", accountId: target.accountId };
+        }
+    }
+}
 /**
  * Re-derive the premises the revision check does not cover.
  *

package/dist/application/plan-create-issue.d.ts

@@ -42,3 +42,14 @@ export declare function configuredProject(deps: JamDeps): string;
  * one it described.
  */
 export declare function validateCreateInput(raw: Record<string, unknown>): CreateIssueInput;
+/** Whitelisted values to the shapes Jira's create API expects. */
+/**
+ * Exported because apply derives these again and compares - see
+ * `assertCreateMutationMatchesInput` in apply-create-issue.ts. Planning and
+ * applying must produce the same fields from the same input, so they call one
+ * function rather than two that are supposed to agree.
+ */
+export declare function toJiraCreateFields(projectKey: string, issueTypeId: string, input: CreateIssueInput, resolved: {
+    priority?: string;
+    components?: string[];
+}): Record<string, unknown>;

package/dist/application/plan-create-issue.js

@@ -86,6 +86,7 @@ export async function planCreateIssue(deps, request) {
             kind: "create",
             fields: toJiraCreateFields(projectKey, issueType.id, input, { priority, components }),
         },
+        input: request.input,
     });
     return {
         plan,
@@ -169,7 +170,13 @@ function notAllowed(message) {
     return new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", message, { operation: "issue.create" });
 }
 /** Whitelisted values to the shapes Jira's create API expects. */
-function toJiraCreateFields(projectKey, issueTypeId, input, resolved) {
+/**
+ * Exported because apply derives these again and compares - see
+ * `assertCreateMutationMatchesInput` in apply-create-issue.ts. Planning and
+ * applying must produce the same fields from the same input, so they call one
+ * function rather than two that are supposed to agree.
+ */
+export function toJiraCreateFields(projectKey, issueTypeId, input, resolved) {
     const fields = {
         project: { key: projectKey },
         issuetype: { id: issueTypeId },

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 { WritePlan, WritePlanReceipt } from "../domain/write.js";
+import type { ExistingIssueOperation, FieldUpdateInput, WriteInput, WritePlan, WritePlanReceipt } from "../domain/write.js";
 export type PlanWriteRequest = {
     /** Absent for `issue.create`, which names a project rather than an issue. */
     key?: string;
@@ -52,3 +52,14 @@ export type IssueSnapshot = {
     assigneeAccountId?: string;
 };
 export declare function readIssue(deps: JamDeps, issueKey: string): Promise<IssueSnapshot>;
+/**
+ * Check the request against the contract, and normalize it.
+ *
+ * Pure: no Jira, no state. Whether an operation is supported, whether a field
+ * is writable and whether the input is even the right shape are all knowable
+ * without asking Jira anything, so they are answered first.
+ */
+export declare function validateInput(operation: ExistingIssueOperation, raw: Record<string, unknown>): WriteInput;
+/** Whitelisted values to the shapes Jira's field API expects. */
+/** Exported so apply can derive the same fields again and compare. */
+export declare function toJiraFields(input: FieldUpdateInput): Record<string, unknown>;

package/dist/application/plan-write.js

@@ -49,6 +49,7 @@ export async function planWrite(deps, request) {
         ...(transition ? { transition } : {}),
         ...(baseAssigneeAccountId ? { baseAssigneeAccountId } : {}),
         mutation,
+        input: input,
     });
     return {
         plan,
@@ -125,7 +126,7 @@ function requireIssueKey(request) {
  * is writable and whether the input is even the right shape are all knowable
  * without asking Jira anything, so they are answered first.
  */
-function validateInput(operation, raw) {
+export function validateInput(operation, raw) {
     switch (operation) {
         case "comment.add": {
             const text = raw.text;
@@ -256,7 +257,8 @@ function currentValue(issue, field) {
     }
 }
 /** Whitelisted values to the shapes Jira's field API expects. */
-function toJiraFields(input) {
+/** Exported so apply can derive the same fields again and compare. */
+export function toJiraFields(input) {
     const fields = {};
     if (input.summary !== undefined)
         fields["summary"] = input.summary;

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

@@ -1,29 +1,25 @@
 import type { NewWritePlan, WritePlan } from "../domain/write.js";
-/**
- * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
- *
- * In this process, and nowhere else. The alternative considered was a signed
- * self-contained token, and it is worse here on both counts that matter: the
- * signing key would have to come from somewhere (a new secret on disk, or a
- * per-process key that gives the token exactly this lifetime anyway), and the
- * mutation would have to travel through the agent to come back. Keeping the
- * mutation in memory makes forgery impossible rather than merely hard - a
- * `planId` is an opaque handle, and what it names never leaves this process.
- *
- * The cost is that plans do not survive a restart. That is acceptable: a plan
- * is only valid while the issue has not moved, so a stale one was going to be
- * rejected on its own terms, and re-planning is a single read.
- *
- * See docs/decisions/adr-jira-write-plane.md.
- */
+export type WritePlanStoreOptions = {
+    /** Injected by tests so expiry does not depend on wall-clock timing. */
+    now?: () => Date;
+    /** Injected by tests so no suite writes into the real `~/.jam`. */
+    root?: string;
+};
 export declare class WritePlanStore {
     private readonly now;
-    private readonly plans;
-    /** Injected by tests so expiry does not depend on wall-clock timing. */
-    constructor(now?: () => Date);
+    private readonly root;
+    constructor(options?: WritePlanStoreOptions | (() => Date));
     create(plan: NewWritePlan): WritePlan;
     /**
-     * Resolve a plan for applying.
+     * Resolve a plan for applying, and claim it in the same step.
+     *
+     * The claim is a rename, because two processes can now reach the same plan
+     * and `rename` is the only thing here that is atomic. Whoever renames it owns
+     * the apply; everyone else sees the file already gone and is told there is no
+     * such plan - which is the truth, for them.
+     *
+     * Reading and then deleting would leave a window between the two, and for
+     * `comment.add` that window is a second comment.
      *
      * An expired plan is reported as expired rather than as missing: those are
      * different situations, and telling them apart is the difference between
@@ -35,8 +31,18 @@ export declare class WritePlanStore {
      *
      * Single use, so a receipt cannot be turned into a second mutation by
      * calling apply again with the same id - which for `comment.add` would mean
-     * two comments.
+     * two comments. `take` already made that true by claiming the file; this
+     * removes the claim so it does not sit until expiry.
      */
     consume(planId: string): void;
+    private notFound;
+    /** `<planId><suffix>`, with the id checked so it can only name a file here. */
+    private pathFor;
+    private ensureRoot;
+    /**
+     * Drop what has aged out, including claims abandoned by a process that died
+     * mid-apply. Not retrying such a claim is deliberate: apply may already have
+     * reached Jira, and that is `JAM_WRITE_UNCERTAIN`'s whole posture.
+     */
     private evictExpired;
 }

package/dist/application/write-plan-store.js

@@ -1,50 +1,92 @@
 import { randomUUID } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { JamError } from "../domain/errors.js";
 import { planExpired } from "../policy/write-policy.js";
 /**
- * Where a plan lives between `jira_write_plan` and `jira_write_apply`.
+ * Where a plan lives between planning and applying.
  *
- * In this process, and nowhere else. The alternative considered was a signed
- * self-contained token, and it is worse here on both counts that matter: the
- * signing key would have to come from somewhere (a new secret on disk, or a
- * per-process key that gives the token exactly this lifetime anyway), and the
- * mutation would have to travel through the agent to come back. Keeping the
- * mutation in memory makes forgery impossible rather than merely hard - a
- * `planId` is an opaque handle, and what it names never leaves this process.
+ * It used to live in the server process and nowhere else, and the ADR said why:
+ * a signed token needs a signing key from somewhere, and keeping the mutation
+ * in memory made forgery impossible rather than merely hard.
  *
- * The cost is that plans do not survive a restart. That is acceptable: a plan
- * is only valid while the issue has not moved, so a stale one was going to be
- * rejected on its own terms, and re-planning is a single read.
+ * The same ADR named the condition for revisiting that - "if plans ever need to
+ * outlive a process". They do now. `jam jira write-plan` and `jam jira
+ * write-apply` are two processes, so an in-memory plan is gone before apply can
+ * see it, and a session whose MCP registry is stale has no way to write at all.
+ *
+ * So a plan is a file under `~/.jam/write-plans/`, shared by both transports.
+ * MCP and CLI read the same store, which means a plan made through the tools
+ * can be applied from the shell when the tools stop answering - that is the
+ * whole point of the change.
+ *
+ * What replaces the in-process guarantee is in apply, not here: it re-derives
+ * the mutation from the plan's own inputs and refuses if the stored mutation
+ * disagrees. Editing the file to smuggle a different write requires editing the
+ * inputs to match, which is just calling plan again. See apply-write.ts.
  *
  * See docs/decisions/adr-jira-write-plane.md.
  */
+/** One plan, one file. The suffix is the claim: see `take`. */
+const PENDING = ".json";
+const CLAIMED = ".claimed";
 export class WritePlanStore {
     now;
-    plans = new Map();
-    /** Injected by tests so expiry does not depend on wall-clock timing. */
-    constructor(now = () => new Date()) {
-        this.now = now;
+    root;
+    constructor(options = {}) {
+        // The old signature took `now` positionally and tests still use it.
+        const opts = typeof options === "function" ? { now: options } : options;
+        this.now = opts.now ?? (() => new Date());
+        this.root = opts.root ?? join(homedir(), ".jam", "write-plans");
     }
     create(plan) {
         this.evictExpired();
         const stored = { ...plan, planId: randomUUID() };
-        this.plans.set(stored.planId, stored);
+        this.ensureRoot();
+        const path = this.pathFor(stored.planId, PENDING);
+        writeFileSync(path, JSON.stringify(stored), "utf8");
+        // Owner-only. A plan names an issue and what would be written to it, and
+        // nothing else on the machine needs to read that.
+        chmodSync(path, 0o600);
         return stored;
     }
     /**
-     * Resolve a plan for applying.
+     * Resolve a plan for applying, and claim it in the same step.
+     *
+     * The claim is a rename, because two processes can now reach the same plan
+     * and `rename` is the only thing here that is atomic. Whoever renames it owns
+     * the apply; everyone else sees the file already gone and is told there is no
+     * such plan - which is the truth, for them.
+     *
+     * Reading and then deleting would leave a window between the two, and for
+     * `comment.add` that window is a second comment.
      *
      * An expired plan is reported as expired rather than as missing: those are
      * different situations, and telling them apart is the difference between
      * "re-plan" and "you are calling this wrong".
      */
     take(planId) {
-        const plan = this.plans.get(planId);
-        if (!plan) {
-            throw new JamError("JAM_WRITE_PLAN_NOT_FOUND", "No such write plan. Plans live in the running JAM server and do not survive a restart - call jira_write_plan again.", { planId });
+        const pending = this.pathFor(planId, PENDING);
+        const claimed = this.pathFor(planId, CLAIMED);
+        try {
+            renameSync(pending, claimed);
+        }
+        catch {
+            throw this.notFound(planId);
+        }
+        let plan;
+        try {
+            plan = JSON.parse(readFileSync(claimed, "utf8"));
+        }
+        catch {
+            // Unreadable is not "someone else has it" - the file is ours now and it
+            // is unusable, so retire it rather than leaving it to expire.
+            rmSync(claimed, { force: true });
+            throw this.notFound(planId);
         }
         if (planExpired(plan.expiresAt, this.now())) {
-            this.plans.delete(planId);
+            rmSync(claimed, { force: true });
             // What to re-plan against differs by plan: an existing issue has a
             // current state, a create has only the project's current create schema.
             // Naming an issue key here for a create would name an issue that has
@@ -66,16 +108,50 @@ export class WritePlanStore {
      *
      * Single use, so a receipt cannot be turned into a second mutation by
      * calling apply again with the same id - which for `comment.add` would mean
-     * two comments.
+     * two comments. `take` already made that true by claiming the file; this
+     * removes the claim so it does not sit until expiry.
      */
     consume(planId) {
-        this.plans.delete(planId);
+        rmSync(this.pathFor(planId, CLAIMED), { force: true });
     }
+    notFound(planId) {
+        return new JamError("JAM_WRITE_PLAN_NOT_FOUND", "No such write plan. A plan is single-use and expires - call jira_write_plan (or `jam jira write-plan`) again.", { planId });
+    }
+    /** `<planId><suffix>`, with the id checked so it can only name a file here. */
+    pathFor(planId, suffix) {
+        if (!/^[0-9a-fA-F-]{1,64}$/.test(planId)) {
+            throw this.notFound(planId);
+        }
+        return join(this.root, `${planId}${suffix}`);
+    }
+    ensureRoot() {
+        if (!existsSync(this.root))
+            mkdirSync(this.root, { recursive: true, mode: 0o700 });
+    }
+    /**
+     * Drop what has aged out, including claims abandoned by a process that died
+     * mid-apply. Not retrying such a claim is deliberate: apply may already have
+     * reached Jira, and that is `JAM_WRITE_UNCERTAIN`'s whole posture.
+     */
     evictExpired() {
+        if (!existsSync(this.root))
+            return;
         const now = this.now();
-        for (const [id, plan] of this.plans) {
-            if (planExpired(plan.expiresAt, now))
-                this.plans.delete(id);
+        for (const name of readdirSync(this.root)) {
+            if (!name.endsWith(PENDING) && !name.endsWith(CLAIMED))
+                continue;
+            const path = join(this.root, name);
+            try {
+                const plan = JSON.parse(readFileSync(path, "utf8"));
+                if (planExpired(plan.expiresAt, now))
+                    rmSync(path, { force: true });
+            }
+            catch {
+                // Unparseable leftovers are not plans. Removing them keeps the
+                // directory from growing without bound, and nothing is lost: a plan
+                // that cannot be read cannot be applied either.
+                rmSync(path, { force: true });
+            }
         }
     }
 }

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

package/dist/cli/jira-write.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Writing Jira without the MCP channel.
+ *
+ * The companion to cli/jira-read.ts, for the same reason and with the same
+ * shape. A session whose MCP registry came up in a failed state cannot be shown
+ * the tools - Claude Code has no reload surface for a running session - so JAM,
+ * its credentials and its Jira access can all be healthy while `jira_write_plan`
+ * is simply unreachable. Reads were addressed to the shell first; this is the
+ * other half.
+ *
+ * Nothing here is a second write path. `write-plan` and `write-apply` call the
+ * same `planWrite` / `applyWritePlan` the tools call, with the same deps, the
+ * same project binding, the same whitelist and the same plan store - so a plan
+ * made through MCP can be applied here, which is the point when MCP is what
+ * broke.
+ *
+ * The two-call contract is not relaxed for the shell:
+ *
+ *   write-plan   reads Jira, decides what is possible, writes nothing
+ *   write-apply  takes a planId and nothing else, then reads the result back
+ *
+ * There is deliberately no `jam jira comment` or `jam jira close`. A shortcut
+ * that skips planning is exactly what the write plane exists to prevent, and
+ * being on a terminal does not change that.
+ *
+ * Contract, enforced by tests:
+ *   stdout - one JSON document and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ *
+ * `write-apply` never asks for confirmation. What to write was settled when the
+ * plan was made; a prompt here would be a second approval step, which is a
+ * different feature and not this one.
+ */
+import { type BuildDepsOptions, type JamDeps } from "../deps.js";
+export declare const JIRA_WRITE_USAGE: string;
+export type JiraWriteOptions = BuildDepsOptions & {
+    /** Injected by tests so no test reaches a real Jira. */
+    deps?: JamDeps;
+    /** Where the JSON document goes. Defaults to stdout. */
+    write?: (text: string) => void;
+    /** Where diagnostics go. Defaults to stderr. */
+    warn?: (text: string) => void;
+};
+export declare function runJiraWrite(argv: readonly string[], options?: JiraWriteOptions): Promise<number>;

package/dist/cli/jira-write.js

@@ -0,0 +1,146 @@
+/**
+ * Writing Jira without the MCP channel.
+ *
+ * The companion to cli/jira-read.ts, for the same reason and with the same
+ * shape. A session whose MCP registry came up in a failed state cannot be shown
+ * the tools - Claude Code has no reload surface for a running session - so JAM,
+ * its credentials and its Jira access can all be healthy while `jira_write_plan`
+ * is simply unreachable. Reads were addressed to the shell first; this is the
+ * other half.
+ *
+ * Nothing here is a second write path. `write-plan` and `write-apply` call the
+ * same `planWrite` / `applyWritePlan` the tools call, with the same deps, the
+ * same project binding, the same whitelist and the same plan store - so a plan
+ * made through MCP can be applied here, which is the point when MCP is what
+ * broke.
+ *
+ * The two-call contract is not relaxed for the shell:
+ *
+ *   write-plan   reads Jira, decides what is possible, writes nothing
+ *   write-apply  takes a planId and nothing else, then reads the result back
+ *
+ * There is deliberately no `jam jira comment` or `jam jira close`. A shortcut
+ * that skips planning is exactly what the write plane exists to prevent, and
+ * being on a terminal does not change that.
+ *
+ * Contract, enforced by tests:
+ *   stdout - one JSON document and nothing else, no ANSI, no prompts
+ *   stderr - diagnostics only
+ *
+ * `write-apply` never asks for confirmation. What to write was settled when the
+ * plan was made; a prompt here would be a second approval step, which is a
+ * different feature and not this one.
+ */
+import { applyWritePlan } from "../application/apply-write.js";
+import { planWrite } from "../application/plan-write.js";
+import { buildDeps } from "../deps.js";
+import { toJamError } from "../domain/errors.js";
+import { WRITE_OPERATIONS } from "../domain/write.js";
+export const JIRA_WRITE_USAGE = `Usage:
+  jam jira write-plan --operation <op> [--key KEY] --input '<json>'
+  jam jira write-apply <planId>
+
+Operations: ${WRITE_OPERATIONS.join(", ")}
+  issue.create takes no --key; every other operation needs one.
+
+Two calls, always. write-plan changes nothing and returns a planId; write-apply
+takes that planId and nothing else. Output is one JSON document on stdout - the
+same receipt the MCP tools return, for a session that cannot see them.
+`;
+/** `--flag value` / `--flag=value`, and nothing invented when absent. */
+function flagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index >= 0)
+        return argv[index + 1];
+    const inline = argv.find((arg) => arg.startsWith(`${flag}=`));
+    return inline ? inline.slice(flag.length + 1) : undefined;
+}
+const FLAGS_WITH_VALUES = ["--operation", "--key", "--input"];
+const positional = (argv) => {
+    const out = [];
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (FLAGS_WITH_VALUES.includes(arg)) {
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        out.push(arg);
+    }
+    return out;
+};
+export async function runJiraWrite(argv, options = {}) {
+    const write = options.write ?? ((text) => process.stdout.write(text));
+    const warn = options.warn ?? ((text) => process.stderr.write(text));
+    const [subcommand, ...rest] = argv;
+    if (subcommand !== "write-plan" && subcommand !== "write-apply") {
+        warn(`Unknown jira command: ${subcommand ?? "(none)"}\n\n${JIRA_WRITE_USAGE}`);
+        return 1;
+    }
+    // Argument shape is checked here; what the values mean is checked by the
+    // application, which is the same judgement the tools get. This file does not
+    // decide what a valid operation or input is.
+    let request;
+    if (subcommand === "write-plan") {
+        const operation = flagValue(rest, "--operation");
+        if (!operation) {
+            warn(`jam jira write-plan needs --operation.\n\n${JIRA_WRITE_USAGE}`);
+            return 1;
+        }
+        const raw = flagValue(rest, "--input");
+        if (raw === undefined) {
+            warn(`jam jira write-plan needs --input '<json>'.\n\n${JIRA_WRITE_USAGE}`);
+            return 1;
+        }
+        let input;
+        try {
+            input = JSON.parse(raw);
+        }
+        catch {
+            warn("--input must be a JSON object.\n");
+            return 1;
+        }
+        if (typeof input !== "object" || input === null || Array.isArray(input)) {
+            warn("--input must be a JSON object.\n");
+            return 1;
+        }
+        const key = flagValue(rest, "--key");
+        request = {
+            kind: "plan",
+            ...(key ? { key } : {}),
+            operation,
+            input: input,
+        };
+    }
+    else {
+        // Exactly one positional and no way to pass anything else. There is no
+        // payload flag here, and adding one would be adding a way to write
+        // something the plan did not describe.
+        const [planId, ...extra] = positional(rest);
+        if (!planId || extra.length > 0) {
+            warn(`jam jira write-apply takes exactly one planId.\n\n${JIRA_WRITE_USAGE}`);
+            return 1;
+        }
+        request = { kind: "apply", planId };
+    }
+    try {
+        const { deps: injected, write: _w, warn: _n, ...depsOptions } = options;
+        const deps = injected ?? (await buildDeps(depsOptions));
+        const result = request.kind === "plan"
+            ? (await planWrite(deps, {
+                ...(request.key !== undefined ? { key: request.key } : {}),
+                operation: request.operation,
+                input: request.input,
+            })).receipt
+            : await applyWritePlan(deps, { planId: request.planId });
+        write(`${JSON.stringify(result)}\n`);
+        return 0;
+    }
+    catch (err) {
+        // The same normalized codes the tools produce - an agent reads one contract,
+        // not two.
+        write(`${JSON.stringify(toJamError(err).toPayload())}\n`);
+        return 1;
+    }
+}

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-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 update              Move this machine's registration to the published release\n  jam update check        What is registered, what is published (changes nothing)\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  jam jira write-plan --operation <op> [--key KEY] --input '<json>'\n  jam jira write-apply <planId>\n                          Write the same way the tools do: plan first, then\n                          apply that plan by id. Nothing is written until\n                          write-apply, and it takes no payload of its own\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

@@ -4,10 +4,12 @@ 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";
 import { runJiraRead } from "./cli/jira-read.js";
+import { runJiraWrite } from "./cli/jira-write.js";
 /**
  * Command dispatch for the JAM CLI, separated from the bin so other entry
  * points (notably @jam-mcp/bootstrap) can forward to exactly these commands
@@ -15,33 +17,49 @@ 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 update check        What is registered, what is published (changes nothing)
+  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
+  jam jira write-plan --operation <op> [--key KEY] --input '<json>'
+  jam jira write-apply <planId>
+                          Write the same way the tools do: plan first, then
+                          apply that plan by id. Nothing is written until
+                          write-apply, and it takes no payload of its own
+
+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
@@ -80,7 +98,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");
@@ -108,6 +131,16 @@ export async function runJamCommand(argv) {
             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")
@@ -128,9 +161,12 @@ export async function runJamCommand(argv) {
             return 1;
         }
         case "jira":
-            // Reads addressed to the shell, for a session that cannot see the MCP
-            // tools yet. Same application path as the tools - see cli/jira-read.ts.
-            return runJiraRead(rest);
+            // Jira addressed to the shell, for a session that cannot see the MCP
+            // tools. Same application path as the tools, reads and writes alike -
+            // see cli/jira-read.ts and cli/jira-write.ts.
+            return rest[0] === "write-plan" || rest[0] === "write-apply"
+                ? runJiraWrite(rest)
+                : runJiraRead(rest);
         case "help":
         case "--help":
         case "-h":

package/dist/domain/errors.d.ts

@@ -5,7 +5,7 @@
  * is mapped onto one of these codes so the agent (and `jam doctor`) can reason
  * about failures without parsing vendor-specific payloads.
  */
-export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
+export declare const JAM_ERROR_CODES: readonly ["JIRA_AUTH_FAILED", "JIRA_PERMISSION_DENIED", "JQL_INVALID", "ISSUE_NOT_FOUND", "RATE_LIMITED", "CONTEXT_TOO_LARGE", "PARTIAL_RESULT", "CONFIG_INVALID", "JIRA_UNAVAILABLE", "JAM_SETUP_REQUIRED", "JAM_BINDINGS_UNREADABLE", "JAM_WRITE_SCOPE_VIOLATION", "JAM_WRITE_OPERATION_NOT_ALLOWED", "JAM_WRITE_FIELD_NOT_ALLOWED", "JAM_WRITE_TRANSITION_NOT_AVAILABLE", "JAM_WRITE_ISSUE_TYPE_NOT_AVAILABLE", "JAM_WRITE_REQUIRED_FIELD_UNSUPPORTED", "JAM_WRITE_VALUE_NOT_ALLOWED", "JAM_WRITE_SCHEMA_CHANGED", "JAM_WRITE_ASSIGNEE_NOT_FOUND", "JAM_WRITE_ASSIGNEE_AMBIGUOUS", "JAM_WRITE_ASSIGNEE_NOT_ASSIGNABLE", "JAM_WRITE_ASSIGNEE_ALREADY_SET", "JAM_WRITE_PLAN_NOT_FOUND", "JAM_WRITE_PLAN_EXPIRED", "JAM_WRITE_PLAN_TAMPERED", "JAM_WRITE_CONFLICT", "JAM_WRITE_VERIFICATION_FAILED", "JAM_WRITE_UNCERTAIN"];
 export type JamErrorCode = (typeof JAM_ERROR_CODES)[number];
 export type JamErrorPayload = {
     error: {

package/dist/domain/errors.js

@@ -44,6 +44,11 @@ export const JAM_ERROR_CODES = [
     "JAM_WRITE_ASSIGNEE_ALREADY_SET",
     "JAM_WRITE_PLAN_NOT_FOUND",
     "JAM_WRITE_PLAN_EXPIRED",
+    // A stored plan that does not describe a change JAM would make. Plans live in
+    // a file so both transports can reach one, and apply re-derives the mutation
+    // from the plan's own input rather than trusting what the file says. Distinct
+    // from CONFLICT: nothing moved, the plan itself does not hold up.
+    "JAM_WRITE_PLAN_TAMPERED",
     "JAM_WRITE_CONFLICT",
     "JAM_WRITE_VERIFICATION_FAILED",
     "JAM_WRITE_UNCERTAIN",

package/dist/domain/write.d.ts

@@ -161,6 +161,18 @@ type WritePlanCommon = {
     expiresAt: string;
     /** Normalized payload the apply step will send. Never supplied by a caller. */
     mutation: WriteMutation;
+    /**
+     * The validated input the mutation was derived from.
+     *
+     * Kept so apply can derive the mutation again and compare. Plans live in a
+     * file now, and a file can be edited - re-deriving is what makes that
+     * pointless: changing the mutation without changing the input is caught, and
+     * changing both is just calling plan again.
+     *
+     * Validated, not raw: what a caller sent has already been checked against the
+     * operation's whitelist by the time it lands here.
+     */
+    input: Record<string, unknown>;
 };
 /**
  * A plan against an issue that already exists.

package/package.json

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