@jam-mcp/server 1.4.3 → 1.4.5

package/README.md

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

package/dist/adapters/credentials/composite.js

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

package/dist/adapters/jira-cloud/mapper.js

@@ -22,6 +22,15 @@ export function mapIssueWithMeta(raw, config) {
         customFields: mapCustomFields(f, config),
         comments: [],
     };
+    // Jira returns `id` as a property of the issue resource, not as a field, so
+    // it arrives whatever the field list says and costs nothing to keep. Set
+    // only when Jira sent one: an empty string would read as an identity that
+    // was looked at and found blank.
+    if (raw.id)
+        issue.issueId = raw.id;
+    const statusCategory = category(f["status"]);
+    if (statusCategory)
+        issue.statusCategory = statusCategory;
     const assignee = user(f["assignee"]);
     if (assignee)
         issue.assignee = assignee;
@@ -123,12 +132,17 @@ export function normalizeFieldValue(value) {
 }
 function issueRef(raw) {
     const ref = { key: raw.key ?? "" };
+    if (raw.id)
+        ref.issueId = raw.id;
     const summary = raw.fields?.summary;
     if (summary)
         ref.summary = summary;
     const status = raw.fields?.status?.name;
     if (status)
         ref.status = status;
+    const statusCategory = raw.fields?.status?.statusCategory?.key;
+    if (statusCategory)
+        ref.statusCategory = statusCategory;
     return ref;
 }
 function str(v) {
@@ -137,6 +151,17 @@ function str(v) {
 function named(v) {
     return v?.name;
 }
+/**
+ * Jira's status category key, or nothing.
+ *
+ * Nothing, specifically, rather than a guess: the alternative is matching
+ * `status.name` against a list of words that mean "done", which is wrong in
+ * every language a project is not configured in and wrong in English the
+ * moment someone renames a status.
+ */
+function category(v) {
+    return v?.statusCategory?.key;
+}
 function user(v) {
     const u = v;
     return u?.displayName ?? u?.emailAddress ?? undefined;

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

@@ -26,11 +26,12 @@ export async function applyCreateIssue(deps, plan) {
     }
     await revalidateSchema(deps, plan);
     const created = await create(deps, plan);
-    const after = await verify(deps, plan, created.key);
+    const { observed: after, issueId } = await verify(deps, plan, created);
     deps.writePlans.consume(plan.planId);
     return {
         status: "applied",
         issue: created.key,
+        issueId,
         operation: plan.operation,
         before: plan.before,
         after,
@@ -118,7 +119,8 @@ function isAmbiguous(err) {
  * a project's automation adds - and none of that was requested, so requiring
  * it to match something would be inventing an expectation nobody stated.
  */
-async function verify(deps, plan, issueKey) {
+async function verify(deps, plan, created) {
+    const issueKey = created.key;
     // Where the issue landed is part of what was intended. The workspace binding
     // is the whole of JAM's write scope, so a key from another project coming
     // back from a create is the one outcome that must never be reported as the
@@ -127,7 +129,15 @@ async function verify(deps, plan, issueKey) {
     if (createdProject !== plan.projectKey) {
         throw verificationFailed(plan, issueKey, { project: plan.projectKey }, { project: createdProject ?? issueKey });
     }
-    const { issue } = await readIssue(deps, issueKey);
+    const { issue, issueId } = await readIssue(deps, issueKey);
+    // Jira named both the id and the key when it accepted the create; the
+    // read-back names them again. They have to agree - a key that already
+    // resolves to a different issue than the one just created is the one case
+    // where reporting the created key would point whoever reads the receipt at
+    // somebody else's issue.
+    if (issueId !== created.id) {
+        throw verificationFailed(plan, issueKey, { issueId: created.id }, { issueId });
+    }
     const observed = {};
     for (const field of Object.keys(plan.intendedAfter)) {
         observed[field] = observedValue(issue, field);
@@ -137,7 +147,7 @@ async function verify(deps, plan, issueKey) {
             throw verificationFailed(plan, issueKey, plan.intendedAfter, observed);
         }
     }
-    return observed;
+    return { observed, issueId };
 }
 /**
  * The created issue's value for one requested field.

package/dist/application/apply-write.js

@@ -1,7 +1,7 @@
 import { JamError, toJamError } from "../domain/errors.js";
 import { readModeAfterWrite } from "../policy/consistency-policy.js";
 import { assertAssignable } from "../policy/assignee-policy.js";
-import { assertUnchanged } from "../policy/write-policy.js";
+import { assertSameIssue, assertUnchanged } from "../policy/write-policy.js";
 import { applyCreateIssue } from "./apply-create-issue.js";
 import { readIssue } from "./plan-write.js";
 /**
@@ -36,6 +36,10 @@ export async function applyWritePlan(deps, request) {
     if (plan.kind === "create-issue")
         return applyCreateIssue(deps, plan);
     const current = await readIssue(deps, plan.issueKey);
+    // Identity before revision: if the key now names a different issue, its
+    // `updated` timestamp is a fact about something nobody planned to change,
+    // and comparing it would be answering the wrong question.
+    assertSameIssue(plan.issueKey, plan.issueId, current.issueId);
     assertUnchanged(plan.issueKey, plan.baseUpdated, current.issue.updated);
     // 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
@@ -48,6 +52,7 @@ export async function applyWritePlan(deps, request) {
     return {
         status: "applied",
         issue: plan.issueKey,
+        issueId: plan.issueId,
         operation: plan.operation,
         before: plan.before,
         after,
@@ -126,6 +131,10 @@ function isAmbiguous(err) {
 async function verify(deps, plan) {
     const snapshot = await readIssue(deps, plan.issueKey);
     const issue = snapshot.issue;
+    // The same identity question again, for the read that produces the evidence.
+    // Confirming the intended value on an issue the key has since come to name
+    // would be reporting somebody else's state as proof of our write.
+    assertSameIssue(plan.issueKey, plan.issueId, snapshot.issueId);
     if (plan.mutation.kind === "assignee") {
         // On the accountId, never on the display name. Two people can share a
         // name, so a name comparison would accept the wrong person's assignment as

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

@@ -38,6 +38,16 @@ export declare function planWrite(deps: JamDeps, request: PlanWriteRequest): Pro
  */
 export type IssueSnapshot = {
     issue: FullIssueContext;
+    /**
+     * The issue's canonical Jira id, carried separately because the write plane
+     * requires it and the read shape only offers it.
+     *
+     * A key is a locator: Jira can move one between issues, and an integration
+     * that recorded a key months ago is holding a string, not a target. Every
+     * write is pinned to this instead - planned against it, re-checked against
+     * it before the mutation, and confirmed against it afterwards.
+     */
+    issueId: string;
     /** Identity of the current assignee, which `issue.assignee` cannot supply. */
     assigneeAccountId?: string;
 };

package/dist/application/plan-write.js

@@ -38,6 +38,7 @@ export async function planWrite(deps, request) {
     const plan = deps.writePlans.create({
         kind: "existing-issue",
         issueKey,
+        issueId: snapshot.issueId,
         projectKey,
         operation,
         before,
@@ -55,6 +56,7 @@ export async function planWrite(deps, request) {
             status: "planned",
             planId: plan.planId,
             issue: plan.issueKey,
+            issueId: plan.issueId,
             operation: plan.operation,
             before: plan.before,
             intendedAfter: plan.intendedAfter,
@@ -86,7 +88,20 @@ export async function readIssue(deps, issueKey) {
     if (!found) {
         throw new JamError("ISSUE_NOT_FOUND", `Jira has no issue ${issueKey}, or it is not visible to this account.`, { issueKey });
     }
-    return { issue: found, ...(assigneeAccountId ? { assigneeAccountId } : {}) };
+    // Jira answered with an issue but named no canonical id. That is not a
+    // resolution JAM can build a write on, and it is refused here - at the one
+    // read every write goes through - rather than by filling the field with an
+    // empty string and carrying a fake identity into a plan. Reads are
+    // unaffected: a list of issues is not invalidated because one entry arrived
+    // thin, and only the write plane treats identity as proof.
+    if (!found.issueId) {
+        throw new JamError("PARTIAL_RESULT", `Jira returned ${issueKey} without a canonical issue id, so JAM cannot confirm which issue this key currently names. Read the issue in Jira before changing it.`, { issueKey });
+    }
+    return {
+        issue: found,
+        issueId: found.issueId,
+        ...(assigneeAccountId ? { assigneeAccountId } : {}),
+    };
 }
 /**
  * The issue an existing-issue operation names, or a refusal that says why.

package/dist/application/search-issues.js

@@ -77,10 +77,19 @@ export async function searchIssues(deps, input) {
 }
 /** Project down to lite fields so heavy data cannot leak through this path. */
 export function toSummary(issue) {
+    // Identity and status semantics ride along at every level, next to the
+    // fields they qualify. Both are already in the payload this projection is
+    // narrowing, so carrying them costs nothing - and dropping them would make
+    // the cheapest read the one an agent cannot safely act on: a key with no
+    // identity behind it, and a status name whose meaning it would have to
+    // guess. Spread rather than assigned afterwards so the JSON an agent reads
+    // puts each beside its subject.
     const summary = {
         key: issue.key,
+        ...(issue.issueId ? { issueId: issue.issueId } : {}),
         summary: issue.summary,
         status: issue.status,
+        ...(issue.statusCategory ? { statusCategory: issue.statusCategory } : {}),
         updated: issue.updated,
         labels: issue.labels,
         components: issue.components,

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

@@ -13,7 +13,7 @@ import { LAUNCHER_PACKAGE_SPEC } from "@jam-mcp/launcher";
 export { LAUNCHER_PACKAGE_SPEC };
 export declare const JAM_MCP_ENTRY: {
     readonly command: "npx";
-    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.3", "serve"];
+    readonly args: readonly ["--yes", "@jam-mcp/launcher@1.4.5", "serve"];
 };
 /**
  * Recognise wiring from before the launcher existed: a hard-coded `node` path

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

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

package/dist/bootstrap/setup-plan.js

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

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

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

package/dist/bootstrap/setup-state.js

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

package/dist/cli/agent-api.js

@@ -61,7 +61,8 @@ export async function setupApplyCommand(options = {}) {
     }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
         plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
-        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        plan.code === "JAM_BINDINGS_UNREADABLE" ||
+        plan.code === "JAM_PROJECT_KEY_CONFLICT") {
         emitJson({ ...plan, changesApplied: false });
         return 1;
     }
@@ -102,7 +103,8 @@ export async function setupAgentCommand(options = {}) {
     }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
         plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
-        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        plan.code === "JAM_BINDINGS_UNREADABLE" ||
+        plan.code === "JAM_PROJECT_KEY_CONFLICT") {
         emitJson({ ...plan, changesApplied: false });
         return 1;
     }
@@ -147,10 +149,71 @@ export async function doctorJsonCommand(options = {}) {
         ...(health.error ? { error: health.error } : {}),
         project: { root: state.project.root, ...(state.project.key ? { key: state.project.key } : {}) },
         axes,
+        diagnosis: diagnose(state, axes, health),
         checks: health.checks,
     });
     return passed ? 0 : 1;
 }
+function diagnose(state, axes, health) {
+    const check = (name) => health.checks.find((c) => c.name === name);
+    const fromCheck = (name, code) => {
+        const found = check(name);
+        if (!found)
+            return { state: "UNCHECKED" };
+        return found.ok
+            ? { state: "OK", ...(found.detail ? { detail: found.detail } : {}) }
+            : { state: "FAILED", code, ...(found.detail ? { detail: found.detail } : {}) };
+    };
+    // Credentials: this axis answers "are all three fields resolvable, and from
+    // where" - the snapshot knows that. Whether Jira accepts them is a different
+    // question with its own axis below, and conflating the two is what made a
+    // working "mixed" setup read as broken. "mixed" is never a failure here.
+    const credentialCheck = check("Credentials present");
+    const mixed = state.credentials.source === "mixed";
+    const credentials = !state.credentials.present
+        ? {
+            state: "FAILED",
+            code: "JAM_AUTH_REQUIRED",
+            ...(credentialCheck?.detail ? { detail: credentialCheck.detail } : {}),
+        }
+        : mixed
+            ? { state: "WARNING", detail: `fields come from more than one source: ${describeSources(state)}` }
+            : { state: "OK", detail: `source ${state.credentials.source}` };
+    return {
+        credentials,
+        projectBinding: state.project.key
+            ? { state: "OK", detail: `key ${state.project.key}` }
+            : { state: "FAILED", code: "JAM_PROJECT_SELECTION_REQUIRED", detail: "no project key for this workspace" },
+        runtime: axes.package === "PACKAGE_READY"
+            ? { state: "OK", ...(axes.packageVersion ? { detail: axes.packageVersion } : {}) }
+            : { state: "FAILED", code: "JAM_RUNTIME_CONFIG_MISSING", ...(state.runtime.error ? { detail: state.runtime.error } : {}) },
+        registration: axes.registration === "OK"
+            ? { state: "OK", ...(axes.registeredVersion ? { detail: axes.registeredVersion } : {}) }
+            : axes.registration === "UNREGISTERED"
+                ? { state: "UNCHECKED", detail: "no host has a jam entry for this user" }
+                : { state: "FAILED", code: axes.registration, ...(axes.detail ? { detail: axes.detail } : {}) },
+        liveToolset: axes.live === "OK"
+            ? { state: "OK" }
+            : axes.live === "UNCHECKED"
+                ? { state: "UNCHECKED", ...(axes.detail ? { detail: axes.detail } : {}) }
+                : {
+                    state: "FAILED",
+                    code: axes.live,
+                    ...(axes.missingTools ? { detail: `missing: ${axes.missingTools.join(", ")}` } : {}),
+                },
+        jiraAuthentication: fromCheck("Jira authentication", "JAM_JIRA_AUTHENTICATION_FAILED"),
+        jiraProjectAccess: fromCheck(health.checks.find((c) => c.name.startsWith("JQL search"))?.name ?? "JQL search", "JAM_JIRA_PROJECT_ACCESS_FAILED"),
+    };
+}
+/** Field-to-source names only. A credential value never appears here. */
+function describeSources(state) {
+    const sources = state.credentials.sources;
+    if (!sources)
+        return "unknown";
+    return Object.entries(sources)
+        .map(([field, from]) => `${field}=${from}`)
+        .join(", ");
+}
 async function inspectAxes(state, options) {
     const packageVersion = state.runtime.version;
     const axes = {
@@ -207,6 +270,8 @@ export function authStatusCommand(options = {}) {
         status: credentials.present ? "configured" : "not_configured",
         ...(credentials.present ? {} : { code: "JAM_AUTH_REQUIRED" }),
         source: credentials.source,
+        // Which field came from where. Names only - a value never appears.
+        ...(credentials.sources ? { sources: credentials.sources } : {}),
         ...(credentials.email ? { email: credentials.email } : {}),
         ...(credentials.baseUrl ? { baseUrl: credentials.baseUrl } : {}),
     });

package/dist/cli/auth.js

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

package/dist/cli/setup.js

@@ -44,7 +44,8 @@ export async function setup(options = {}) {
     }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID" ||
         plan.code === "JAM_MCP_CONFIG_UNREADABLE" ||
-        plan.code === "JAM_BINDINGS_UNREADABLE") {
+        plan.code === "JAM_BINDINGS_UNREADABLE" ||
+        plan.code === "JAM_PROJECT_KEY_CONFLICT") {
         line(`[FAIL] ${describeBlockingCode(plan)}`);
         return 1;
     }
@@ -133,6 +134,16 @@ function reportApplied(applied, plan) {
     void plan;
 }
 function describeBlockingCode(plan) {
+    if (plan.code === "JAM_PROJECT_KEY_CONFLICT") {
+        // Both sides named, and no suggestion to delete the repository's file -
+        // which project this repository belongs to is the team's decision.
+        return [
+            `This repository declares ${plan.existing?.key} in .jira-agent/project.yaml,`,
+            `but --project asked for ${plan.requested?.key}. JAM will not overwrite the`,
+            "committed key. Either drop --project to use the repository's, or change",
+            "the repository's project.yaml with the team and re-run.",
+        ].join(" ");
+    }
     if (plan.code === "JAM_PROJECT_CONFIG_INVALID") {
         return "The project's .jira-agent/project.yaml could not be parsed. Fix it and re-run.";
     }

package/dist/domain/issue.d.ts

@@ -1,7 +1,24 @@
+/**
+ * A reference to a Jira issue.
+ *
+ * `key` is what a person types, a branch name carries and an integration links
+ * on - and it is not an identity. Jira mints keys per project and a key can be
+ * moved between issues, so the same string can name a different issue later.
+ * `issueId` is the identity: the immutable id Jira assigns once and never
+ * reuses.
+ *
+ * `issueId` is optional because JAM will not invent one. Jira supplies it on
+ * every issue resource and on the nested references it embeds, but a payload
+ * that omits it leaves the field absent rather than empty - "not returned" and
+ * "returned blank" are different facts, and only one of them is true.
+ */
 export type IssueRef = {
     key: string;
+    issueId?: string;
     summary?: string;
     status?: string;
+    /** See IssueSummary.statusCategory. */
+    statusCategory?: string;
 };
 /**
  * SEARCH level. Deliberately excludes description/comments/attachments/changelog
@@ -9,8 +26,25 @@ export type IssueRef = {
  */
 export type IssueSummary = {
     key: string;
+    /** Jira's immutable issue id. See IssueRef. */
+    issueId?: string;
     summary: string;
     status: string;
+    /**
+     * Jira's own machine-readable status category key, as Jira publishes it -
+     * currently `new`, `indeterminate` or `done`, plus `undefined` for a status
+     * in no category.
+     *
+     * Passed through, never derived. `status` is a workflow-defined, localized
+     * name: a project can call a category-`done` status "Shipped", "완료" or
+     * "Won't Fix", and matching those strings is how an agent decides an issue
+     * is finished when it is not. This is the field to read instead, and JAM
+     * neither renames Jira's values nor turns them into a verdict of its own.
+     *
+     * Absent when Jira returned a status without a category. Absent is absent -
+     * it is not `new`.
+     */
+    statusCategory?: string;
     assignee?: string;
     priority?: string;
     updated: string;

package/dist/domain/write.d.ts

@@ -172,6 +172,16 @@ type WritePlanCommon = {
 export type ExistingIssueWritePlan = WritePlanCommon & {
     kind: "existing-issue";
     issueKey: string;
+    /**
+     * The canonical Jira id of the issue this plan was made against.
+     *
+     * `issueKey` says where to look; this says what was found there. They are
+     * not the same guarantee: a key is a locator Jira can move between issues,
+     * so re-reading the key at apply time can return a different issue than the
+     * one the plan described. Comparing this is what turns "the key still
+     * resolves" into "it still resolves to the issue that was planned".
+     */
+    issueId: string;
     operation: ExistingIssueOperation;
     baseUpdated: string;
     /**
@@ -239,6 +249,11 @@ export type WritePlanReceipt = {
      * yet - a placeholder key here would be a claim JAM cannot make.
      */
     issue?: string;
+    /**
+     * The canonical Jira id of that issue. Absent for `issue.create` for the
+     * same reason `issue` is: Jira mints both, and it has not been asked yet.
+     */
+    issueId?: string;
     /** The project a new issue would be created in. Present for `issue.create`. */
     project?: string;
     /** How the result of applying this plan will be confirmed. */
@@ -253,6 +268,14 @@ export type WriteApplyReceipt = {
     status: "applied";
     /** For `issue.create`, the key Jira minted - known only after applying. */
     issue: string;
+    /**
+     * The canonical Jira id of the issue that was written, read back from Jira.
+     *
+     * What to record if this write is going to be referred to later. The key is
+     * how a person and an integration will find the issue; this is what says the
+     * thing they find is the thing that was changed.
+     */
+    issueId: string;
     operation: WriteOperation;
     before: Record<string, unknown>;
     after: Record<string, unknown>;

package/dist/mcp/tools/jira-context.tool.js

@@ -9,7 +9,11 @@ Returns everything jira_search returns plus issue type, parent, subtasks, issue
 
 This is the Jira-recorded evidence relevant to readiness, blockers, dependencies and priority - not a readiness verdict. blocksThisIssue reports how Jira words a link; an empty links array means Jira holds no visible link for you, not that nothing blocks the work. Repository and external sources are not evaluated.
 
-Pass every key you care about in one call; they are fetched in a single batched round trip. Check meta.complete and meta.missingKeys before drawing conclusions.`;
+Every issue carries issueId, Jira's immutable id, alongside key. The key is the current human- and integration-facing locator and Jira can move it to another issue; issueId is the identity. Record issueId when a reference has to survive. statusCategory is Jira's own machine-readable category for the status - read it instead of matching status text, which is workflow-defined and localized. Parent, subtasks and links carry issueId too, wherever Jira supplies one.
+
+Pass every key you care about in one call; they are fetched in a single batched round trip. Check meta.complete and meta.missingKeys before drawing conclusions.
+
+This is also how a Jira issue key is checked. Asking for an exact key and getting an issue back is a positive resolution: that key names that issue, right now. A key listed in meta.missingKeys resolved to nothing JAM can see - it may not exist, or it may not be visible to this account, and those are indistinguishable from here. Either way it is unusable, and it is NOT evidence that the number is free, unused or reservable. Never synthesize, increment, predict or reserve a Jira issue key; keys are minted by Jira.`;
 export function registerJiraContext(server, deps) {
     server.registerTool("jira_context", {
         title: "Jira issue context (dependencies, blockers, readiness)",

package/dist/mcp/tools/jira-full.tool.js

@@ -5,7 +5,7 @@ const DESCRIPTION = `Get the complete record for one or more Jira issues, includ
 
 Use for final judgements: was this agreed, is the contract settled, was it approved, can it be closed, what did the other team actually answer, what does this issue mean right now.
 
-Returns everything jira_context returns plus description and every comment (normalized to plain text). This is the most expensive tool - prefer jira_search for listing and jira_context for readiness, and reach for this one when the answer must not be wrong.
+Returns everything jira_context returns - issueId and statusCategory included - plus description and every comment (normalized to plain text). This is the most expensive tool - prefer jira_search for listing and jira_context for readiness, and reach for this one when the answer must not be wrong.
 
 Ask for as few keys as possible: with several issues at once the output budget may drop the oldest comments. Always check meta.commentsComplete and meta.complete - if either is false, the thread you are reading is partial and a "yes, it is agreed" answer is not supported.
 

package/dist/mcp/tools/jira-search.tool.js

@@ -5,10 +5,12 @@ const DESCRIPTION = `Find Jira issues by JQL and get a lightweight list back.
 
 Use for: discovery, listing, "what is open", "what is assigned to me", recent changes, picking candidate issues.
 
-Returns key, summary, status, assignee, priority, updated, labels and components only. It deliberately does NOT return description, comments, attachments or links - that keeps listing cheap.
+Returns key, issueId, summary, status, statusCategory, assignee, priority, updated, labels and components only. It deliberately does NOT return description, comments, attachments or links - that keeps listing cheap.
 
 Because of that, a jira_search result is NOT complete issue context. Never conclude from it that something is agreed, approved, unblocked, or done. Follow up with jira_context (readiness, blockers, dependencies, priority) or jira_full (agreement, contract, approval, closure).
 
+Every issue carries issueId, Jira's immutable id, alongside key. The key is the current human- and integration-facing locator and Jira can move it to another issue; issueId is the identity. Record issueId when a reference has to survive. statusCategory is Jira's own machine-readable category for the status - read it instead of matching status text, which is workflow-defined and localized.
+
 Repository and external sources are not evaluated.
 
 scope="preview" (default) returns the first page for interactive exploration. scope="complete" walks every page - use it whenever the answer depends on the total count or on seeing every match. Check meta.complete before treating the list as exhaustive.`;

package/dist/policy/write-policy.d.ts

@@ -31,6 +31,21 @@ export declare function projectKeyOf(issueKey: string): string | undefined;
  * comment - must not be able to reach into another team's project through it.
  */
 export declare function assertWriteScope(issueKey: string, configuredProject: string): string;
+/**
+ * The key still names the issue the plan was made against.
+ *
+ * A revision check answers "has this issue changed"; this answers the question
+ * underneath it - "is this the same issue at all". Jira keys are locators, not
+ * identities: one can be moved to another issue, and an integration holding
+ * the string would then be pointed somewhere nobody chose. Re-reading the key
+ * and finding a different canonical id means the plan describes an issue this
+ * key no longer names, and the answer is a new plan, not this write.
+ *
+ * JAM_WRITE_CONFLICT rather than a code of its own: the situation is the one
+ * an agent already knows how to handle - the ground moved, plan again against
+ * the current state - and a second code for it would only fragment that.
+ */
+export declare function assertSameIssue(issueKey: string, planned: string, observed: string): void;
 export declare function assertOperationAllowed(operation: string): WriteOperation;
 /**
  * Narrow an already-allowed operation to one that acts on an existing issue.

package/dist/policy/write-policy.js

@@ -48,6 +48,25 @@ export function assertWriteScope(issueKey, configuredProject) {
     }
     return project;
 }
+/**
+ * The key still names the issue the plan was made against.
+ *
+ * A revision check answers "has this issue changed"; this answers the question
+ * underneath it - "is this the same issue at all". Jira keys are locators, not
+ * identities: one can be moved to another issue, and an integration holding
+ * the string would then be pointed somewhere nobody chose. Re-reading the key
+ * and finding a different canonical id means the plan describes an issue this
+ * key no longer names, and the answer is a new plan, not this write.
+ *
+ * JAM_WRITE_CONFLICT rather than a code of its own: the situation is the one
+ * an agent already knows how to handle - the ground moved, plan again against
+ * the current state - and a second code for it would only fragment that.
+ */
+export function assertSameIssue(issueKey, planned, observed) {
+    if (planned === observed)
+        return;
+    throw new JamError("JAM_WRITE_CONFLICT", `${issueKey} no longer names the issue this plan was made against (planned ${planned}, now ${observed}). Plan again against the issue the key names now.`, { issueKey, plannedIssueId: planned, observedIssueId: observed });
+}
 export function assertOperationAllowed(operation) {
     if (!isWriteOperation(operation)) {
         throw new JamError("JAM_WRITE_OPERATION_NOT_ALLOWED", `"${operation}" is not a JAM write operation. Supported: ${WRITE_OPERATIONS.join(", ")}.`, { operation, supported: [...WRITE_OPERATIONS] });

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

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

package/package.json

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