smol-symphony 0.2.0 → 0.3.1

package/dist/core/issue/file.js

@@ -0,0 +1,149 @@
+// FCIS rewrite — pure issue-file serialization.
+//
+// Functional-core port of the original `src/issues.ts:writeIssueFile`. The
+// original was async and performed real fs IO: it mkdir'd the state dir,
+// `readdir`'d every state directory to discover taken numeric identifiers
+// (collision avoidance), `stat`'d an explicit identifier's target path to
+// reject duplicates, and finally `writeFile`'d the rendered Markdown.
+//
+// In the FCIS layout all of that IO moves OUT of this module:
+//   - The existing-identifier discovery (a `readdir` walk) is performed by the
+//     shell and the resulting SET is SUPPLIED here as plain data
+//     (`existingIdentifiers`). This module only DECIDES which id to take.
+//   - The wall-clock `created_at` / `updated_at` stamp is injected as a plain
+//     ISO string (`nowIso`) — no `Date.now()` / clock read inside core.
+//   - The actual file write becomes a `tracker.write_issue` Effect the caller
+//     executes; this module ALSO returns the fully-rendered file `content` and
+//     the composed `path` so a shell that prefers a raw `fs.write_file` (or
+//     wants to surface the content in a dashboard) needn't re-derive them.
+//
+// Pure + synchronous: (data) -> data + Effect[]. Imports ONLY from src/types.
+import { sanitizeWorkspaceKey } from '../workspace-key.js';
+// Identifier sanitizer (SPEC §5.5 Invariant 3) is the canonical core util.
+const sanitizeIdentifier = sanitizeWorkspaceKey;
+// POSIX-style path join. Core may not import `node:path`; the tracker root is
+// always a real on-disk path and the segments here never contain `..`, so a
+// simple single-slash join is faithful. Strips a trailing slash per segment so
+// `root/` + `state` doesn't produce `root//state`, and keeps an absolute root's
+// leading slash.
+function joinPath(...segments) {
+    const lead = segments[0]?.startsWith('/') ? '/' : '';
+    const parts = segments.map((s) => s.replace(/^\/+|\/+$/g, '')).filter((s) => s.length > 0);
+    return lead + parts.join('/');
+}
+/**
+ * Render a YAML scalar/array value the way the original serializer did:
+ *   - arrays  → `[<json>, <json>, …]`
+ *   - strings → JSON-quoted (escapes + always double-quoted)
+ *   - other   → `String(v)` (numbers, booleans)
+ */
+function renderYamlValue(v) {
+    if (Array.isArray(v)) {
+        return `[${v.map((x) => JSON.stringify(x)).join(', ')}]`;
+    }
+    if (typeof v === 'string') {
+        return JSON.stringify(v);
+    }
+    return String(v);
+}
+/**
+ * Pure issue-file serializer. Decides the identifier (sanitize an explicit one
+ * or pick the next free numeric over `existingIdentifiers`), renders the YAML
+ * front matter + body, composes the path, and returns a `tracker.write_issue`
+ * Effect for the shell to execute. Never throws: refusals come back as a
+ * `{ error }` result the caller maps to a structured rejection.
+ *
+ * Mirrors the original `writeIssueFile` decision branches exactly:
+ *   - explicit identifier → sanitize; reject empty; reject collision
+ *   - no identifier       → count up from 1 to the first id not in the set
+ */
+export function composeIssueFile(input) {
+    const stateDir = joinPath(input.trackerRoot, input.state);
+    let identifier;
+    const explicit = (input.identifier ?? '').trim();
+    if (explicit.length > 0) {
+        identifier = sanitizeIdentifier(explicit);
+        if (identifier.length === 0) {
+            return {
+                ok: false,
+                error: {
+                    code: 'empty_identifier',
+                    message: 'identifier must contain at least one allowed character',
+                },
+            };
+        }
+        const filePath = joinPath(stateDir, `${identifier}.md`);
+        if (input.existingIdentifiers.has(identifier)) {
+            return {
+                ok: false,
+                error: {
+                    code: 'identifier_exists',
+                    message: `issue ${identifier} already exists at ${filePath}`,
+                    identifier,
+                    path: filePath,
+                },
+            };
+        }
+    }
+    else {
+        // No identifier supplied → pick the next free numeric identifier by counting
+        // up from 1. Title-slug files from prior cycles are inert: only numeric
+        // basenames consume IDs (legacy `add-changelog.md` never claims a slot).
+        let n = 1;
+        while (input.existingIdentifiers.has(String(n)))
+            n += 1;
+        identifier = String(n);
+    }
+    const filePath = joinPath(stateDir, `${identifier}.md`);
+    // Standard front matter, in the original's declaration order, then the
+    // caller's extras (which may override — preserving the original's merge).
+    const fm = {
+        id: identifier,
+        identifier,
+        title: input.title,
+        created_at: input.nowIso,
+        updated_at: input.nowIso,
+    };
+    if (typeof input.priority === 'number')
+        fm.priority = input.priority;
+    if (input.labels && input.labels.length > 0)
+        fm.labels = input.labels;
+    if (input.blocked_by && input.blocked_by.length > 0)
+        fm.blocked_by = input.blocked_by;
+    if (input.extra_front_matter) {
+        for (const [k, v] of Object.entries(input.extra_front_matter)) {
+            fm[k] = v;
+        }
+    }
+    const yamlLines = ['---'];
+    for (const [k, v] of Object.entries(fm)) {
+        yamlLines.push(`${k}: ${renderYamlValue(v)}`);
+    }
+    yamlLines.push('---', '');
+    const body = (input.description ?? '').trim();
+    const content = yamlLines.join('\n') + (body.length > 0 ? body + '\n' : '');
+    const writeEffect = {
+        family: 'tracker',
+        kind: 'write_issue',
+        trackerRoot: input.trackerRoot,
+        identifier,
+        state: input.state,
+        title: input.title,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.priority !== undefined ? { priority: input.priority } : {}),
+        ...(input.labels !== undefined ? { labels: input.labels } : {}),
+        ...(input.blocked_by !== undefined ? { blocked_by: input.blocked_by } : {}),
+        ...(input.extra_front_matter !== undefined ? { extraFrontMatter: input.extra_front_matter } : {}),
+    };
+    return {
+        ok: true,
+        result: {
+            path: filePath,
+            identifier,
+            state: input.state,
+            content,
+            effects: [writeEffect],
+        },
+    };
+}
+//# sourceMappingURL=file.js.map

package/dist/core/issue/file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.js","sourceRoot":"","sources":["../../../src/core/issue/file.ts"],"names":[],"mappings":"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"}

package/dist/core/issue/parse.js

@@ -0,0 +1,210 @@
+// FCIS rewrite — pure issue parsing & selection core (SPEC §3.2).
+//
+// Ports the *decision* half of the original `src/trackers/local.ts` (parse +
+// normalize + active-candidate filter + multi-match disambiguation) and the
+// pure collision-pick from `src/issues.ts` (`writeIssueFile`'s next-free-id
+// loop), with the impureCoreRisk removed: the existing-identifier SET is
+// supplied by the shell (which owns the readdir), NOT scanned here.
+//
+// HARD CONSTRAINTS (gate-enforced):
+//   - 100% SYNCHRONOUS. No async/await/Promise anywhere.
+//   - No IO, no node: imports, no process/fetch, no wall clock, no randomness.
+//   - Imports ONLY from src/types/**.
+//
+// The YAML decode itself lives in the shell tracker adapter (it needs the
+// `yaml` userland lib, which core may not import). The shell hands us the
+// already-decoded front-matter map + body + state-from-dir + filename; this
+// module turns that into a normalized `Issue` and makes every selection
+// decision as pure data-in / data-out.
+import { TrackerError, NoHoldingStateError } from '../../types/errors.js';
+import { asString, asStringList, asInt, asTimestamp } from '../coerce.js';
+// Front-matter coercers (asString/asStringList/asInt/asTimestamp) are the
+// canonical ones from core/coerce.ts. NOTE(drift resolved): the old local copy
+// of `asInt` here used `Number.isInteger` (rejecting a fractional priority);
+// the canonical `asInt` truncates (isFinite + Math.trunc), matching the rest
+// of the codebase. See core/coerce.ts header + tests/core/coerce.test.ts.
+// ─── id derivation ───────────────────────────────────────────────────────────
+/**
+ * Canonical id of a raw file: front-matter `id` when non-blank, else the
+ * filename stem. Exported because the shell's transition path resolves the
+ * caller-supplied issueId against this same key.
+ */
+export function idOf(raw) {
+    const fmId = asString(raw.frontMatter['id']);
+    return fmId && fmId.trim().length > 0 ? fmId : raw.identifier;
+}
+// ─── normalize (build Issue objects, resolving blocker states) ───────────────
+/**
+ * Build a blocker lookup keyed by every alias a `blocked_by` entry might use:
+ * the front-matter `identifier`, the canonical `id`, and the filename stem.
+ * Pure: derived solely from `all`. Last-write-wins mirrors the original.
+ */
+function buildBlockerIndex(all) {
+    const byKey = new Map();
+    for (const r of all) {
+        const ident = asString(r.frontMatter['identifier']) ?? r.identifier;
+        byKey.set(ident, r);
+        byKey.set(idOf(r), r);
+        byKey.set(r.identifier, r);
+    }
+    return byKey;
+}
+function toIssue(raw, byKey) {
+    const fm = raw.frontMatter;
+    const id = idOf(raw);
+    const identifier = asString(fm['identifier']) ?? raw.identifier;
+    const title = asString(fm['title']) ?? identifier;
+    const priority = asInt(fm['priority']);
+    const labels = asStringList(fm['labels']).map((s) => s.toLowerCase());
+    const branch_name = asString(fm['branch_name']);
+    const url = asString(fm['url']);
+    const created_at = asTimestamp(fm['created_at']);
+    const updated_at = asTimestamp(fm['updated_at']);
+    const description = raw.description.length > 0 ? raw.description : null;
+    const blockerIdents = asStringList(fm['blocked_by']);
+    const blocked_by = blockerIdents.map((ident) => {
+        const found = byKey.get(ident);
+        if (found) {
+            const foundIdent = asString(found.frontMatter['identifier']) ?? found.identifier;
+            return {
+                id: idOf(found),
+                identifier: foundIdent,
+                state: found.state,
+            };
+        }
+        return { id: null, identifier: ident, state: null };
+    });
+    return {
+        id,
+        identifier,
+        title,
+        description,
+        priority,
+        state: raw.state,
+        branch_name,
+        url,
+        labels,
+        blocked_by,
+        created_at,
+        updated_at,
+    };
+}
+/**
+ * Normalize `target` raw files into `Issue`s, resolving blocker states against
+ * the full `all` view. The original passed both sets so a candidate's
+ * `blocked_by` could reference an issue outside the candidate window.
+ */
+export function normalizeIssues(target, all) {
+    const byKey = buildBlockerIndex(all);
+    return target.map((r) => toIssue(r, byKey));
+}
+/** Parse a single raw file into an `Issue` (blockers resolved only against the file itself). */
+export function parseIssue(raw) {
+    return toIssue(raw, buildBlockerIndex([raw]));
+}
+// ─── state-role helpers (ported from src/issues.ts) ──────────────────────────
+/** Names of every state with `role`, in declaration order. */
+function statesWithRole(states, role) {
+    return Object.entries(states).filter(([, cfg]) => cfg.role === role).map(([name]) => name);
+}
+/** Names of every `role: active` state, in declaration order. */
+export function activeStateNames(states) {
+    return statesWithRole(states, 'active');
+}
+/** Names of every `role: terminal` state, in declaration order. */
+export function terminalStateNames(states) {
+    return statesWithRole(states, 'terminal');
+}
+/**
+ * First declared `role: holding` state in declaration order (where triage /
+ * agent-proposed issues land). Throws `NoHoldingStateError` when none is
+ * declared — callers that surface this to agents should map it to a structured
+ * `no_holding_state` error.
+ */
+export function pickHoldingState(states) {
+    for (const [name, cfg] of Object.entries(states)) {
+        if (cfg.role === 'holding')
+            return name;
+    }
+    throw new NoHoldingStateError('no holding state declared in workflow');
+}
+// ─── active-candidate filtering ──────────────────────────────────────────────
+/**
+ * Select the active-but-not-terminal candidates and normalize them. Mirrors
+ * the original `fetchCandidateIssues`: state comparison is case-insensitive
+ * (SPEC §3.2 "Normalized Issue State"), and a state that is BOTH active and
+ * terminal (a malformed config) is excluded — the `!terminal` guard wins.
+ */
+export function selectCandidateIssues(all, states) {
+    const active = new Set(activeStateNames(states).map((s) => s.toLowerCase()));
+    const terminal = new Set(terminalStateNames(states).map((s) => s.toLowerCase()));
+    const filtered = all.filter((raw) => {
+        const s = raw.state.toLowerCase();
+        return active.has(s) && !terminal.has(s);
+    });
+    return normalizeIssues(filtered, all);
+}
+/** Select & normalize every file whose state is in `stateNames` (case-insensitive). */
+export function selectIssuesByStates(all, stateNames) {
+    if (stateNames.length === 0)
+        return [];
+    const want = new Set(stateNames.map((s) => s.toLowerCase()));
+    const filtered = all.filter((raw) => want.has(raw.state.toLowerCase()));
+    return normalizeIssues(filtered, all);
+}
+/** Select & normalize every file whose canonical id is in `issueIds`. */
+export function selectIssuesByIds(all, issueIds) {
+    if (issueIds.length === 0)
+        return [];
+    const want = new Set(issueIds);
+    const filtered = all.filter((raw) => want.has(idOf(raw)));
+    return normalizeIssues(filtered, all);
+}
+// ─── multi-match disambiguation (ported from resolveMatch) ───────────────────
+/**
+ * Resolve the single raw file that matches `issueId`. Multiple files can share
+ * an id when a stale terminal copy survives alongside a live active copy;
+ * `readdir` ordering is filesystem-dependent, so we refuse to guess. When more
+ * than one candidate matches, prefer the copy whose state equals the
+ * caller-supplied `fromState`; if that still doesn't resolve to exactly one,
+ * throw `TrackerError('local_issue_ambiguous')`.
+ *
+ * `candidates` is the pre-filtered set (state in: all files with `idOf === issueId`).
+ * Throws `TrackerError('local_issue_not_found')` when empty.
+ */
+export function resolveMatch(candidates, issueId, fromState) {
+    if (candidates.length === 0) {
+        throw new TrackerError('local_issue_not_found', `no issue file matches id ${issueId}`);
+    }
+    if (candidates.length === 1)
+        return candidates[0];
+    const preferred = fromState
+        ? candidates.filter((raw) => raw.state.toLowerCase() === fromState.toLowerCase())
+        : [];
+    if (preferred.length === 1)
+        return preferred[0];
+    const statesStr = candidates.map((raw) => raw.state).join(', ');
+    throw new TrackerError('local_issue_ambiguous', `multiple issue files match id ${issueId} across states [${statesStr}]; pass fromState to disambiguate`);
+}
+/** All raw files whose canonical id equals `issueId` (the input `resolveMatch` expects). */
+export function matchingCandidates(all, issueId) {
+    return all.filter((raw) => idOf(raw) === issueId);
+}
+// ─── next-free-identifier collision pick (pure half of writeIssueFile) ───────
+/**
+ * Pick the next free numeric identifier given the existing-identifier SET (the
+ * shell's readdir supplies it — impureCoreRisk fix: NO scan here). Counts up
+ * from 1 until it finds a basename not present in `existing`. Title-slug files
+ * from prior cycles are inert: only numeric basenames consume IDs.
+ *
+ * `existing` should be the union of identifiers across ALL state directories,
+ * so a `Done/3.md` can't silently shadow a freshly created `Todo/3.md` once it
+ * moves out of Todo (faithful to `collectExistingIdentifiers`).
+ */
+export function pickNextNumericIdentifier(existing) {
+    let n = 1;
+    while (existing.has(String(n)))
+        n += 1;
+    return String(n);
+}
+//# sourceMappingURL=parse.js.map

package/dist/core/issue/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/issue/parse.ts"],"names":[],"mappings":"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"}

package/dist/core/mcp/dispatch.js

@@ -0,0 +1,239 @@
+// FCIS rewrite — pure MCP tools/call PRE-move decider (ported from src/mcp.ts:
+// callTransition / callRequestHumanSteering / callProposeIssue). `decideToolCall`
+// is a pure synchronous (data) -> {response, effects} function: it does no IO,
+// reads no clock, holds no Promise.
+//
+// The keystone of the FCIS split — what is and is NOT decided here:
+//   * VALIDATION (data-only) IS decided here: declared-state + `allowed_transitions`
+//     gate, the non-empty/single-line arg checks, and the "steering already
+//     pending" guard. A rejection is the synchronous tool-result (`isError: true`,
+//     plus a structured payload for the transition rejections), with NO effects.
+//   * The MOVE is an EFFECT: a valid transition emits `move_state` +
+//     `set_transitioned`; the shell runs the move, folds the resolved
+//     {fromState,toState}, builds the success response, and decides `defer_cleanup`
+//     (the post-move cleanup gate lives in the core/mcp fold, not here).
+//   * The steering AWAITER Promise is never held here (desync fix, issue 151):
+//     we emit `stash_steering` + `await_steering`; the shell parks the awaiter and
+//     flips `steering_requested` only once it is live.
+//   * `propose_issue` emits `write_issue` with validated fields only; the shell
+//     stamps `proposed_at` from its injected Clock (orig: `isoFromClock(this.now)`).
+import { resolveDeclaredName, isInFlowTransition } from '../state-resolve.js';
+import { makeError } from './protocol.js';
+// ─── Top-level dispatch ─────────────────────────────────────────────────────
+/**
+ * Decide a single `tools/call`. Returns the synchronous response and/or the
+ * effects to perform. Unknown tool names produce a JSON-RPC method-not-found
+ * error (matching the original `unknown tool: <name>` branch).
+ */
+export function decideToolCall(id, toolName, args, view, states) {
+    switch (toolName) {
+        case 'transition':
+            return decideTransition(id, args, view, states);
+        case 'request_human_steering':
+            return decideRequestHumanSteering(id, args, view);
+        case 'propose_issue':
+            return decideProposeIssue(id, args, view, states);
+        default:
+            return { response: makeError(id, -32601, `unknown tool: ${toolName}`), effects: [] };
+    }
+}
+// ─── transition ─────────────────────────────────────────────────────────────
+/**
+ * `transition({ to_state, notes? })`. Validate the target against the declared
+ * states + the current state's `allowed_transitions`, then emit the move.
+ *
+ * Validation rejections return a tool-result error (the structured ones for
+ * `unknown_state` / `transition_not_allowed` carry the machine-readable payload
+ * the agent reads to pick a valid target next call). On success, `response` is
+ * null and `effects` carries `move_state` + `set_transitioned`.
+ */
+export function decideTransition(id, args, view, states) {
+    const toStateRaw = typeof args.to_state === 'string' ? args.to_state.trim() : '';
+    const notes = typeof args.notes === 'string' ? args.notes : '';
+    if (!toStateRaw) {
+        return rejectText(id, 'to_state is required and must be a non-empty string');
+    }
+    if (!view.trackerSupportsMove) {
+        return rejectText(id, 'this tracker does not support state transitions');
+    }
+    const declaredNames = states.order;
+    const canonicalTarget = canonicalStateName(states, toStateRaw);
+    if (canonicalTarget === null) {
+        const text = `state "${toStateRaw}" is not declared. declared: ${declaredNames.length > 0 ? declaredNames.join(', ') : '<none>'}`;
+        return rejectStructured(id, text, {
+            error: 'unknown_state',
+            declared_states: declaredNames,
+        });
+    }
+    // `allowed_transitions: null | undefined` ⇒ any declared state reachable; a
+    // present array restricts (empty array ⇒ no transitions out). Validate only
+    // when the CURRENT state canonicalizes to a declared state with a list. The
+    // in-flow test is the ONE predicate shared with the operator's soft-warning
+    // move endpoint (isInFlowTransition, src/core/state-resolve.ts) — the agent
+    // path HARD-rejects exactly what the operator path only warns on (issue 126).
+    // A self-transition is always in-flow (the predicate short-circuits it).
+    const canonicalFrom = canonicalStateName(states, view.fromState);
+    if (canonicalFrom !== null) {
+        const allowed = states.views[canonicalFrom].allowed_transitions;
+        if (allowed && !isInFlowTransition(allowed, canonicalFrom, canonicalTarget)) {
+            const text = `transition to "${canonicalTarget}" is not allowed from "${canonicalFrom}". allowed: ${allowed.length > 0 ? allowed.join(', ') : '<none>'}`;
+            return rejectStructured(id, text, {
+                error: 'transition_not_allowed',
+                from_state: canonicalFrom,
+                requested_to_state: canonicalTarget,
+                allowed_transitions: allowed,
+            });
+        }
+    }
+    // Valid. Emit the move (the shell runs the tracker file-move and folds the
+    // resolved {fromState,toState} back to build the success response + decide
+    // cleanup). `set_transitioned` flips the post-turn exit flag. The decider
+    // does NOT build the success response (it depends on the resolved tracker
+    // result) → response: null.
+    const effects = [
+        {
+            kind: 'move_state',
+            issueId: view.issueId,
+            toState: canonicalTarget,
+            fromRoot: view.trackerRootSnapshot,
+            fromState: view.fromState,
+            notes,
+            actor: view.actor,
+        },
+        { kind: 'set_transitioned' },
+    ];
+    return { response: null, effects };
+}
+// ─── request_human_steering ───────────────────────────────────────────────
+/**
+ * `request_human_steering({ question, context? })`. Validate the question and
+ * the "already pending" guard, then emit `stash_steering` + `await_steering`.
+ *
+ * The decider returns a READY ack response (the original returned the ack
+ * synchronously — the question is merely queued; the turn ends and the human
+ * reply arrives as the next turn's prompt). The awaiter Promise + the
+ * `steering_requested` flag flip both live in the shell (issue 151).
+ */
+export function decideRequestHumanSteering(id, args, view) {
+    const question = typeof args.question === 'string' ? args.question.trim() : '';
+    const context = typeof args.context === 'string' ? args.context.trim() : '';
+    if (!question) {
+        return rejectText(id, 'question is required and must be a non-empty string');
+    }
+    // Guard on the stashed question (awaiter-liveness desync fix, issue 151): a
+    // non-null pending question means an unanswered request is already out.
+    if (view.steeringPending) {
+        return rejectText(id, 'a steering request is already pending for this issue; end the turn and wait for the response');
+    }
+    const effects = [
+        { kind: 'stash_steering', question, context: context.length > 0 ? context : null },
+        { kind: 'await_steering' },
+    ];
+    const ack = 'Question queued. End this turn now. The human response will arrive as the prompt for your next turn.';
+    return { response: toolResult(id, ack, false), effects };
+}
+// ─── propose_issue ──────────────────────────────────────────────────────────
+/**
+ * `propose_issue({ title, description?, labels?, priority? })`. Validate the
+ * title (non-empty single line), resolve the landing holding state, then emit
+ * the `write_issue` effect. The shell stamps `proposed_at` from its Clock and
+ * builds the success response from the written {identifier,state,path}; on a
+ * valid propose this decider returns `response: null` (the identifier isn't
+ * known until the file is written).
+ *
+ * Two rejections are decided here purely:
+ *   - missing/multiline title (text tool-error)
+ *   - unresolvable tracker root (text tool-error)
+ *   - no declared holding state (structured `no_holding_state` tool-error)
+ */
+export function decideProposeIssue(id, args, view, states) {
+    const titleRaw = typeof args.title === 'string' ? args.title.trim() : '';
+    const description = typeof args.description === 'string' ? args.description : '';
+    if (!titleRaw) {
+        return rejectText(id, 'title is required and must be a non-empty string');
+    }
+    if (titleRaw.includes('\n')) {
+        return rejectText(id, 'title must be a single line (no embedded newlines)');
+    }
+    const labels = Array.isArray(args.labels)
+        ? args.labels.filter((x) => typeof x === 'string')
+        : [];
+    const priority = typeof args.priority === 'number' && Number.isFinite(args.priority) ? args.priority : null;
+    // Original resolved root := dispatch snapshot ?? tracker.currentRoot(); the
+    // shell projects that already-resolved value into `trackerRootSnapshot`, so a
+    // null here is the genuine "no resolvable root" case.
+    if (view.trackerRootSnapshot === null) {
+        return rejectText(id, 'tracker root is not available; cannot create issue files (is this a non-local tracker?)');
+    }
+    // Landing state must exist (first declared `holding` state). Core resolves the
+    // actual landing name HERE (strict, declaration-order) and carries it on the
+    // effect so the shell writer never re-resolves it with a divergent fallback.
+    const landingState = pickHoldingState(states);
+    if (landingState === null) {
+        return rejectStructured(id, 'cannot propose issue: workflow has no holding-role state declared', {
+            error: 'no_holding_state',
+            declared_states: states.order,
+        });
+    }
+    const effects = [
+        {
+            kind: 'write_issue',
+            title: titleRaw,
+            description: description.length > 0 ? description : null,
+            labels,
+            priority,
+            proposedBy: view.identifier,
+            landingState,
+        },
+    ];
+    return { response: null, effects };
+}
+// ─── Pure helpers ───────────────────────────────────────────────────────────
+/**
+ * Canonical declared name for `name` (exact match wins, else a case-insensitive
+ * scan in declaration order). Thin adapter over the canonical
+ * {@link resolveDeclaredName} (core/state-resolve.ts) keyed by the MCP states
+ * view's declared-name `order`. Returns null when no declared state matches.
+ */
+export function canonicalStateName(states, name) {
+    return resolveDeclaredName(states.order, name);
+}
+/**
+ * First declared `holding` state in declaration order, or null when none is
+ * declared. Pure mirror of core/states.pickHoldingState, but returns null (the
+ * caller turns that into the structured `no_holding_state` rejection) rather
+ * than a NoHoldingStateError value, since the original surfaced it as a tool
+ * error to the agent rather than throwing.
+ */
+function pickHoldingState(states) {
+    for (const name of states.order) {
+        const v = states.views[name];
+        if (v && v.role === 'holding')
+            return name;
+    }
+    return null;
+}
+// ─── Response constructors (pure value objects) ───────────────────────────────
+// `makeError` (the JSON-RPC error envelope) is imported from ./protocol.js — the
+// canonical home — rather than re-inlined here (it was byte-identical).
+/**
+ * MCP convention: tool results (success OR error) are a `result`, not a JSON-RPC
+ * error. `isError` marks a tool failure; the optional `structuredContent` slot
+ * carries the machine-readable recovery payload (transition + no_holding_state
+ * rejections) the agent reads to pick a valid next call.
+ */
+function toolResult(id, text, isError, structuredContent) {
+    const result = { content: [{ type: 'text', text }], isError };
+    if (structuredContent)
+        result.structuredContent = structuredContent;
+    return { jsonrpc: '2.0', id, result };
+}
+/** Plain-text tool-error decision with no effects. */
+function rejectText(id, message) {
+    return { response: toolResult(id, message, true), effects: [] };
+}
+/** Structured tool-error decision (text + machine-readable payload), no effects. */
+function rejectStructured(id, text, json) {
+    return { response: toolResult(id, text, true, json), effects: [] };
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/core/mcp/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","sourceRoot":"","sources":["../../../src/core/mcp/dispatch.ts"],"names":[],"mappings":"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"}