@jam-mcp/server 1.6.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.6.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.6.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.6.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-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\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 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

@@ -9,6 +9,7 @@ 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
@@ -35,6 +36,11 @@ Jira
   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)
@@ -155,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.6.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.6.0",
+    "@jam-mcp/launcher": "1.7.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"