smol-symphony 0.1.0 → 0.2.0

package/dist/mcp.js

@@ -1,110 +1,174 @@
 // Per-issue MCP server. Each active dispatch registers an entry here; the agent inside
-// the smolvm connects to /api/v1/issues/<id>/mcp with the per-dispatch bearer token and
-// sees exactly two tools:
+// the Gondolin VM connects to /api/v1/issues/<id>/mcp with the per-dispatch bearer token and
+// sees these tools:
 //
-//   mark_done(summary)              ─ atomic file move into the terminal state, sets the
-//                                     marked_done flag on the RunningEntry so the runner
+//   transition(to_state, notes?)    ─ atomic file move into another declared state,
+//                                     optionally appending notes to the issue body
+//                                     first. Sets the `transitioned` flag so the runner
 //                                     exits cleanly on next post-turn check.
 //   request_human_steering(question, context?)
 //                                   ─ stashes the question on the RunningEntry, returns
 //                                     an ack to the agent. The runner then pauses the
 //                                     autonomous loop and awaits a human reply submitted
 //                                     via POST /api/v1/issues/<id>/steering-reply.
+//   propose_issue(title, ...)       ─ drops a new issue file into the first declared
+//                                     holding state directory for operator triage.
 //
 // The URL is the capability: the agent only ever knows its own /<id>/mcp endpoint. The
 // bearer token is belt-and-braces in case a non-agent caller can reach 8787.
 //
 // MCP wire format here is JSON-RPC 2.0 over HTTP (the "Streamable HTTP" transport's
-// non-SSE subset). We implement only the subset our two tools need: initialize, tools/list,
+// non-SSE subset). We implement only the subset our tools need: initialize, tools/list,
 // tools/call, plus a polite notifications/initialized acknowledgement.
-import { randomBytes, timingSafeEqual } from 'node:crypto';
-import { Buffer } from 'node:buffer';
-import { lstat, mkdir, writeFile } from 'node:fs/promises';
-import path from 'node:path';
 import { log } from './logging.js';
-const TERMINAL_STATE_FOR_DONE_DEFAULT = 'Done';
-/**
- * Pick the terminal state directory mark_done should move issues into.
- *
- * Shared between the orchestrator (which snapshots this at dispatch time onto
- * the RunningEntry) and the registry's fallback path. Prefers an entry whose
- * lowercase form is "done"; falls back to the first configured terminal state,
- * then to a hardcoded "Done" when the list is empty.
- */
-export function pickTerminalTarget(terminalStates) {
-    const preferred = terminalStates.find((s) => s.toLowerCase() === 'done');
-    if (preferred)
-        return preferred;
-    if (terminalStates.length > 0)
-        return terminalStates[0];
-    return TERMINAL_STATE_FOR_DONE_DEFAULT;
-}
+import { writeIssueFile, pickHoldingState, NoHoldingStateError } from './issues.js';
+import { realClock, isoFromClock } from './util/clock.js';
+import { realCrypto } from './util/crypto.js';
 const PROTOCOL_VERSION = '2025-06-18';
 const TOOL_LIST = [
     {
-        name: 'mark_done',
-        description: 'Signal that this issue is fully complete. The orchestrator will move the issue file into the terminal Done state, persist the title/summary you provide for downstream tooling (PR title, PR body, transcripts), and stop dispatching new turns. Call this once, at the very end of a successful run. There is no RESULT.md to write — the structured fields here are the canonical record.',
+        name: 'request_human_steering',
+        description: 'Pause work and ask the human operator a question. Your current turn will end immediately after this returns; the human response will arrive as the prompt for your next turn. Use only when you cannot proceed without a decision a human must make.',
         inputSchema: {
             type: 'object',
             properties: {
-                title: {
+                question: {
                     type: 'string',
-                    description: 'Short single-line title in imperative voice (≤72 chars recommended). Becomes the PR/commit title for the work. Example: "Add CHANGELOG.md with MCP entry".',
+                    description: 'The question to ask the human. Be specific about what decision they need to make.',
                 },
-                summary: {
+                context: {
                     type: 'string',
-                    description: 'Multi-paragraph narrative describing what changed, why, and any follow-ups the agent noticed but did not do. Becomes the PR body / transcript record.',
+                    description: 'Optional: relevant context the human needs to answer (file paths, options considered, etc.).',
                 },
             },
-            required: ['title', 'summary'],
+            required: ['question'],
         },
     },
     {
-        name: 'request_human_steering',
-        description: 'Pause work and ask the human operator a question. Your current turn will end immediately after this returns; the human response will arrive as the prompt for your next turn. Use only when you cannot proceed without a decision a human must make.',
+        name: 'transition',
+        description: 'Move this issue into another declared state, optionally appending notes to its body for the next agent. Use this for handoffs — implementer → reviewer, reviewer → implementer (rework), or implementer → terminal Done — rather than only at the very end of the work. Notes are appended to the issue file BEFORE the state move, so the next dispatch sees them in `issue.description` along with everything the previous agents wrote. `to_state` must be one of the states declared in WORKFLOW.md; if the current state declares `allowed_transitions`, `to_state` must also be in that list. On a terminal target, the workspace is removed after your turn ends and no further turns will be dispatched. On a non-terminal target, the same workspace and `agent/<id>` git branch survive into the next state.',
         inputSchema: {
             type: 'object',
             properties: {
-                question: {
+                to_state: {
                     type: 'string',
-                    description: 'The question to ask the human. Be specific about what decision they need to make.',
+                    description: 'Declared state to transition into (case-insensitive match against `states:` in WORKFLOW.md). Examples: "Review", "Done", "Todo".',
                 },
-                context: {
+                notes: {
                     type: 'string',
-                    description: 'Optional: relevant context the human needs to answer (file paths, options considered, etc.).',
+                    description: 'Optional markdown notes to append to the issue body before the move. These become part of the issue description the next agent (in `to_state`) reads. Use this for review findings, rework instructions, or PR-body content on a terminal transition.',
                 },
             },
-            required: ['question'],
+            required: ['to_state'],
+        },
+    },
+    {
+        name: 'propose_issue',
+        description: 'Propose a new issue for the human to triage. The orchestrator drops the proposal into a non-active "Triage" state directory and does NOT dispatch it — the operator approves (moves to the active queue) or discards it from the dashboard. Use this when you notice work that is out of scope for your current task: an unrelated bug, a follow-up the operator should size, a refactor a future agent could pick up. The parent issue you are working on is automatically recorded; do not paste it into the body.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Short single-line title in imperative voice (≤72 chars recommended). Example: "Fix race condition in workspace cleanup".',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Optional multi-paragraph body for the issue. Explain what you observed, where (file paths), and why it is worth handling separately from your current task.',
+                },
+                labels: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of label strings.',
+                },
+                priority: {
+                    type: 'number',
+                    description: 'Optional integer priority hint (tracker-defined meaning).',
+                },
+            },
+            required: ['title'],
         },
     },
 ];
 export class McpRegistry {
     tracker;
-    opts;
     byIdentifier = new Map();
     effectivePort = null;
-    constructor(tracker, opts) {
+    // Live state-config map, kept in sync with the orchestrator's view via
+    // `updateStates`. Used by `transition` to validate `to_state` and to resolve
+    // the role of the target (terminal => set cleanup_workspace_on_exit). An
+    // empty map means every transition call lands in the "unknown_state" branch,
+    // which is the correct behaviour: without a declared states map, the agent
+    // has no valid target to name.
+    states = {};
+    // Issue 38 (generalised in issue 144): when the PR engine is enabled,
+    // transitions into the merge state do NOT flip `cleanup_workspace_on_exit`
+    // even though the target state's role is `terminal`. The pr resource owns
+    // the workspace lifecycle for those issues — it rebases inside the workspace
+    // and cleans it up after the PR merges/closes. Without this gate the
+    // terminal-cleanup path would reap the workspace before the engine could
+    // ever use it. The caller (bin/symphony.ts) derives `mergeState` from
+    // `derivePrRouting(cfg.states).mergeState` and `enabled` from `cfg.pr.enabled`.
+    prMerge = { enabled: false, mergeState: null };
+    // Injected wall clock. Tests pin time; production wires `Date.now` (or
+    // accepts the realClock default). Used to stamp `proposed_at` on
+    // propose_issue submissions so the core is deterministic under test.
+    now;
+    // Injected crypto port. Production wires `realCrypto` (randomBytes +
+    // timingSafeEqual); tests can pin deterministic tokens to assert wire
+    // format without sampling randomness.
+    crypto;
+    constructor(tracker, opts = {}) {
         this.tracker = tracker;
-        this.opts = opts;
+        if (opts.states)
+            this.states = opts.states;
+        if (opts.prMerge)
+            this.prMerge = opts.prMerge;
+        this.now = opts.now ?? realClock;
+        this.crypto = opts.crypto ?? realCrypto;
     }
-    updateTerminalStates(states) {
-        this.opts.terminalStates = states;
+    /**
+     * Push the latest state-config map (and optional PR merge-cleanup gate) in
+     * after a workflow reload. Tests that don't care about the PR engine can call
+     * with a single argument; production wires both so reloads that flip
+     * `pr.enabled` or move the merge state take effect on subsequent transitions.
+     */
+    updateStates(states, prMerge) {
+        this.states = states;
+        if (prMerge !== undefined) {
+            this.prMerge = prMerge ?? { enabled: false, mergeState: null };
+        }
     }
     /** Called once after the HTTP server binds, so URL construction uses the real port. */
     setEffectivePort(port) {
         this.effectivePort = port;
     }
+    /**
+     * The bound HTTP port, or null until the server binds. Exposed so the Gondolin
+     * dispatch can wire the guest→host MCP `tcp.hosts` tunnel to the real
+     * `mcp.host:effectivePort` while the guest dials a fixed synthetic host.
+     */
+    getEffectivePort() {
+        return this.effectivePort;
+    }
     /**
      * Build the URL the ACP agent will be told to POST to. Returns null when no HTTP server
      * is available and no explicit URL is configured; the runner uses that to skip MCP
      * injection (with a warning) instead of advertising an unreachable endpoint.
+     *
+     * `baseOverride` (e.g. the Gondolin guest synthetic base `http://symphony-mcp:7001`)
+     * wins over both `explicit_host_url` and the real host:port: under Gondolin the
+     * guest cannot reach the host loopback directly, so the runner passes the synthetic
+     * base that a per-dispatch `tcp.hosts` entry tunnels to the real MCP server.
      */
-    buildUrl(identifier, mcp) {
-        const base = mcp.explicit_host_url
-            ? mcp.explicit_host_url.replace(/\/+$/, '')
-            : this.effectivePort === null
-                ? null
-                : `http://${mcp.host}:${this.effectivePort}`;
+    buildUrl(identifier, mcp, baseOverride) {
+        const base = baseOverride
+            ? baseOverride.replace(/\/+$/, '')
+            : mcp.explicit_host_url
+                ? mcp.explicit_host_url.replace(/\/+$/, '')
+                : this.effectivePort === null
+                    ? null
+                    : `http://${mcp.host}:${this.effectivePort}`;
         if (!base)
             return null;
         return `${base}/api/v1/issues/${encodeURIComponent(identifier)}/mcp`;
@@ -114,18 +178,18 @@ export class McpRegistry {
      * agent's MCP server config via ACP's session/new mcpServers field.
      */
     activate(entry) {
-        const token = randomBytes(24).toString('base64url');
+        const token = this.crypto.newToken();
         entry.mcp_token = token;
-        entry.marked_done = false;
+        entry.transitioned = false;
         entry.steering_requested = false;
         entry.steering_question = null;
         entry.steering_context = null;
-        // Carry the dispatch-time snapshots through verbatim. Reading
-        // this.tracker.currentRoot() / this.preferredTerminalState() here would be
-        // wrong: activate runs AFTER workspace setup, before_run hook, and smolvm
-        // bring-up — a window during which a WORKFLOW.md reload can mutate tracker
-        // root or terminal_states. The dispatch-time values are the only ones that
-        // accurately reflect the world the run was started in.
+        // Carry the dispatch-time tracker-root snapshot through verbatim. Reading
+        // this.tracker.currentRoot() here would be wrong: activate runs AFTER
+        // workspace setup and Gondolin VM bring-up — a window during
+        // which a WORKFLOW.md reload can mutate tracker.root. The dispatch-time
+        // value is the only one that accurately reflects the world the run was
+        // started in.
         const active = {
             issueId: entry.issue_id,
             identifier: entry.identifier,
@@ -133,12 +197,10 @@ export class McpRegistry {
             token,
             pendingReply: null,
             trackerRootSnapshot: entry.tracker_root_at_dispatch,
-            terminalTarget: entry.terminal_target_at_dispatch,
         };
         this.byIdentifier.set(entry.identifier, active);
         log.debug('mcp activated', {
             issue_identifier: entry.identifier,
-            terminal_target: active.terminalTarget,
             tracker_root: active.trackerRootSnapshot,
         });
         return token;
@@ -212,7 +274,7 @@ export class McpRegistry {
         if (!active) {
             return makeError(getId(body), -32001, 'issue not active');
         }
-        if (!constantTimeStringEqual(active.token, token)) {
+        if (!this.crypto.constantTimeEqual(active.token, token)) {
             return makeError(getId(body), -32002, 'invalid token');
         }
         if (!isRpcRequest(body)) {
@@ -256,12 +318,15 @@ export class McpRegistry {
                     const params = (body.params ?? {});
                     const name = params.name;
                     const args = params.arguments ?? {};
-                    if (name === 'mark_done') {
-                        return await this.callMarkDone(active, id, args);
+                    if (name === 'transition') {
+                        return await this.callTransition(active, id, args);
                     }
                     if (name === 'request_human_steering') {
                         return this.callRequestHumanSteering(active, id, args);
                     }
+                    if (name === 'propose_issue') {
+                        return await this.callProposeIssue(active, id, args);
+                    }
                     return makeError(id, -32601, `unknown tool: ${name}`);
                 }
                 case 'ping': {
@@ -284,71 +349,135 @@ export class McpRegistry {
             return makeError(id, -32603, err.message);
         }
     }
-    async callMarkDone(active, id, args) {
-        const titleRaw = typeof args.title === 'string' ? args.title.trim() : '';
-        const summary = typeof args.summary === 'string' ? args.summary : '';
-        if (!titleRaw) {
-            return makeToolError(id, 'title is required and must be a non-empty string');
-        }
-        if (titleRaw.includes('\n')) {
-            return makeToolError(id, 'title must be a single line (no embedded newlines)');
+    /**
+     * Shared file-move + flag-flip path used by `transition`. Returns the tracker's
+     * resolved {from, to, newPath} on success, throwing the underlying TrackerError
+     * on failure so the caller can wrap it in a tool-error response.
+     *
+     * Cleanup-on-exit is decided by the role of the canonical target state: terminal
+     * targets clean the workspace, active/holding targets preserve it so the same
+     * `agent/<id>` git branch survives across the handoff. Callers must have already
+     * resolved `toState` to its canonical declared name via `canonicalStateName`, so
+     * this routine assumes the lookup is in the states map.
+     */
+    async performTransition(active, toState, notes, actor) {
+        if (!this.tracker.moveIssueToState) {
+            throw new Error('this tracker does not support state transitions');
         }
-        if (!summary.trim()) {
-            return makeToolError(id, 'summary is required and must be a non-empty string');
+        const fromRoot = active.trackerRootSnapshot ?? undefined;
+        const fromState = active.entry.issue.state;
+        const result = await this.tracker.moveIssueToState(active.issueId, toState, {
+            fromRoot,
+            fromState,
+            notes: notes.length > 0 ? notes : undefined,
+            actor,
+        });
+        active.entry.transitioned = true;
+        // Look up the canonical declared name (preserving operator-supplied casing)
+        // so the role lookup matches the workflow's `states:` map.
+        const stateMap = this.states;
+        const canonicalName = canonicalStateName(stateMap, result.toState);
+        const targetIsTerminal = canonicalName !== null && stateMap[canonicalName].role === 'terminal';
+        // Issue 38 / 144: suppress terminal cleanup when the PR engine owns this
+        // state's workspace. The pr resource will reap the workspace once the
+        // PR has merged (or been closed). Other terminal states (Cancelled
+        // typically) still cleanup immediately — the close path only needs to talk
+        // to GitHub, not the workspace.
+        const suppressCleanupForMerge = targetIsTerminal &&
+            canonicalName !== null &&
+            this.prMerge.enabled &&
+            this.prMerge.mergeState !== null &&
+            canonicalName.toLowerCase() === this.prMerge.mergeState.toLowerCase();
+        active.entry.cleanup_workspace_on_exit = targetIsTerminal && !suppressCleanupForMerge;
+        // Mutate the entry's view of the issue's state so downstream code (runner's
+        // cleanup, orchestrator's terminal-state workspace removal) resolves the right
+        // state's `actions:`. Without this, the terminal-state cleanup actions would
+        // resolve against the pre-transition state and a terminal-state handoff
+        // (e.g. Done's push_branch + create_pr_if_missing) would never fire.
+        active.entry.issue.state = canonicalName ?? result.toState;
+        // Stash the transition so the orchestrator shell can fold it into the run
+        // log as a `transition` lifecycle event after the attempt unwinds (issue
+        // 123). Pure here — no IO; the run-log write happens host-side.
+        active.entry.last_transition = {
+            from_state: result.fromState,
+            to_state: canonicalName ?? result.toState,
+            notes,
+            actor,
+            terminal: targetIsTerminal,
+        };
+        return result;
+    }
+    /**
+     * `symphony.transition({ to_state, notes? })`: validate the target against the
+     * declared `states:` map + the current state's `allowed_transitions` list, then
+     * delegate to `performTransition` which owns the actual file move and flag flip.
+     *
+     * Validation failures return MCP tool-result errors (`isError: true`) with a
+     * human-readable text block AND a structured JSON block describing the error
+     * shape. This is NOT a JSON-RPC `error` envelope — the SDK delivers it as a
+     * normal tool result and the agent reads the structured payload to pick a valid
+     * target on its next call. `transitioned` stays false; no file is touched.
+     */
+    async callTransition(active, id, args) {
+        const toStateRaw = typeof args.to_state === 'string' ? args.to_state.trim() : '';
+        const notes = typeof args.notes === 'string' ? args.notes : '';
+        if (!toStateRaw) {
+            return makeToolError(id, 'to_state is required and must be a non-empty string');
         }
         if (!this.tracker.moveIssueToState) {
             return makeToolError(id, 'this tracker does not support state transitions');
         }
-        // Use the snapshots captured at activate time, not the registry's live config.
-        // A WORKFLOW.md reload that changes tracker.root or terminal_states between
-        // dispatch and mark_done must not redirect the move.
-        //
-        // Pass the entry's dispatched-from state as `fromState` so the tracker can
-        // disambiguate when a stale terminal copy (e.g. a leftover Done/ABC-1.md
-        // from a prior cycle) shares the issue id with the active In Progress copy.
-        // Without this, a blind first-match could pick the stale terminal file and
-        // silently no-op via the same-state short-circuit.
-        const target = active.terminalTarget;
-        const fromRoot = active.trackerRootSnapshot ?? undefined;
-        const fromState = active.entry.issue.state;
-        try {
-            const result = await this.tracker.moveIssueToState(active.issueId, target, {
-                fromRoot,
-                fromState,
+        const stateMap = this.states;
+        const declaredNames = Object.keys(stateMap);
+        const canonicalTarget = canonicalStateName(stateMap, toStateRaw);
+        if (canonicalTarget === null) {
+            const text = `state "${toStateRaw}" is not declared. declared: ${declaredNames.length > 0 ? declaredNames.join(', ') : '<none>'}`;
+            log.info('mcp transition rejected: unknown_state', {
+                issue_identifier: active.identifier,
+                requested_to_state: toStateRaw,
+                declared_states: declaredNames,
             });
-            active.entry.marked_done = true;
-            // The reconcile loop normally sets cleanup_workspace_on_exit when it observes a
-            // terminal-state transition, but the runner can exit (via the marked_done flag)
-            // before the next reconcile tick. Set it here so the workspace is cleaned up on
-            // worker exit regardless of which path got there first.
-            active.entry.cleanup_workspace_on_exit = true;
-            // Persist the structured title+summary into the workspace so the after_run
-            // hook (and any other consumers) can read them. Format is markdown so
-            // operators can `cat` it without parsing JSON:
-            //   # <title>
-            //
-            //   <summary>
-            try {
-                const stagingDir = await pickStagingDir(active.entry.workspace_path);
-                await mkdir(stagingDir, { recursive: true });
-                const body = `# ${titleRaw}\n\n${summary.trim()}\n`;
-                await writeFile(path.join(stagingDir, 'mark_done.md'), body, { mode: 0o644 });
-            }
-            catch (err) {
-                // Persistence failure is non-fatal — the move already happened, the
-                // flag is set, and the title/summary are in the log line below. We
-                // surface it as a warning so the operator can investigate.
-                log.warn('mcp mark_done: failed to persist mark_done.md', {
-                    issue_identifier: active.identifier,
-                    error: err.message,
-                });
+            return makeStructuredToolError(id, text, {
+                error: 'unknown_state',
+                declared_states: declaredNames,
+            });
+        }
+        const fromStateRaw = active.entry.issue.state;
+        const canonicalFrom = canonicalStateName(stateMap, fromStateRaw);
+        if (canonicalFrom !== null) {
+            // Per the brief: `allowed_transitions: null | undefined` => "any declared
+            // state is reachable"; a present array => restrict to that list (empty
+            // list => no transitions out, agent must wait for human cleanup).
+            const allowed = stateMap[canonicalFrom].allowed_transitions;
+            if (allowed) {
+                const allowedLower = new Set(allowed.map((s) => s.toLowerCase()));
+                if (!allowedLower.has(canonicalTarget.toLowerCase())) {
+                    const text = `transition to "${canonicalTarget}" is not allowed from "${canonicalFrom}". allowed: ${allowed.length > 0 ? allowed.join(', ') : '<none>'}`;
+                    log.info('mcp transition rejected: transition_not_allowed', {
+                        issue_identifier: active.identifier,
+                        from_state: canonicalFrom,
+                        requested_to_state: canonicalTarget,
+                        allowed_transitions: allowed,
+                    });
+                    return makeStructuredToolError(id, text, {
+                        error: 'transition_not_allowed',
+                        from_state: canonicalFrom,
+                        requested_to_state: canonicalTarget,
+                        allowed_transitions: allowed,
+                    });
+                }
             }
-            log.info('mcp mark_done', {
+        }
+        const actor = active.entry.resolved_actor;
+        try {
+            const result = await this.performTransition(active, canonicalTarget, notes, actor);
+            log.info('mcp transition', {
                 issue_identifier: active.identifier,
                 from: result.fromState,
                 to: result.toState,
-                title: titleRaw,
-                summary_chars: summary.length,
+                notes_len: notes.length,
+                actor,
+                cleanup: active.entry.cleanup_workspace_on_exit,
             });
             return {
                 jsonrpc: '2.0',
@@ -357,15 +486,21 @@ export class McpRegistry {
                     content: [
                         {
                             type: 'text',
-                            text: `Marked ${active.identifier} as done (moved to ${result.toState}). Stop now; no further turns will be dispatched.`,
+                            text: `Transitioned ${active.identifier} from ${result.fromState} to ${result.toState}${notes.length > 0 ? ` with notes (${notes.length} chars) appended` : ''}. End this turn now; the next dispatch will pick up under the new state.`,
                         },
                     ],
                     isError: false,
+                    structuredContent: {
+                        from_state: result.fromState,
+                        to_state: result.toState,
+                        cleanup_workspace_on_exit: active.entry.cleanup_workspace_on_exit,
+                        notes_appended: notes.length > 0,
+                    },
                 },
             };
         }
         catch (err) {
-            return makeToolError(id, `failed to mark done: ${err.message}`);
+            return makeToolError(id, `failed to transition: ${err.message}`);
         }
     }
     callRequestHumanSteering(active, id, args) {
@@ -399,53 +534,107 @@ export class McpRegistry {
             },
         };
     }
-    preferredTerminalState() {
-        return pickTerminalTarget(this.opts.terminalStates);
+    /**
+     * Drop a new issue file into the tracker's Triage/ directory. The orchestrator
+     * never dispatches Triage entries because the state's role is `holding`, not
+     * `active`; the operator approves or discards from the dashboard. Parent issue (the active
+     * dispatch this MCP call came from) is stamped into the front-matter as
+     * `proposed_by` so provenance is visible in the file and the UI.
+     *
+     * Uses the dispatch-time tracker root snapshot — same rationale as `transition`:
+     * a WORKFLOW.md reload that mutates tracker.root mid-flight must not redirect
+     * an in-flight propose call to a different filesystem location.
+     */
+    async callProposeIssue(active, id, args) {
+        const titleRaw = typeof args.title === 'string' ? args.title.trim() : '';
+        const description = typeof args.description === 'string' ? args.description : '';
+        if (!titleRaw) {
+            return makeToolError(id, 'title is required and must be a non-empty string');
+        }
+        if (titleRaw.includes('\n')) {
+            return makeToolError(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;
+        // Resolve the tracker root: prefer the dispatch-time snapshot, fall back to the
+        // tracker's live root (e.g. for tests / trackers without a snapshot). Without a
+        // resolvable root we can't write the file, so surface a clean tool error.
+        const root = active.trackerRootSnapshot ??
+            (this.tracker.currentRoot ? this.tracker.currentRoot() : null);
+        if (!root) {
+            return makeToolError(id, 'tracker root is not available; cannot create issue files (is this a non-local tracker?)');
+        }
+        // Landing state: first declared `holding` state in declaration order. The
+        // workflow parser refuses configs without one, but if validation was
+        // bypassed we surface a structured `no_holding_state` error so the agent
+        // doesn't keep retrying against a misconfigured workflow.
+        let landingState;
+        try {
+            landingState = pickHoldingState(this.states);
+        }
+        catch (err) {
+            if (err instanceof NoHoldingStateError) {
+                return makeStructuredToolError(id, 'cannot propose issue: workflow has no holding-role state declared', {
+                    error: 'no_holding_state',
+                    declared_states: Object.keys(this.states),
+                });
+            }
+            throw err;
+        }
+        try {
+            const result = await writeIssueFile({
+                trackerRoot: root,
+                state: landingState,
+                title: titleRaw,
+                description,
+                priority,
+                labels,
+                now: realClock,
+                extra_front_matter: {
+                    proposed_by: active.identifier,
+                    proposed_at: isoFromClock(this.now),
+                },
+            });
+            log.info('mcp propose_issue', {
+                proposed_by: active.identifier,
+                identifier: result.identifier,
+                state: result.state,
+                title: titleRaw,
+                description_chars: description.length,
+            });
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Proposed issue ${result.identifier} in ${result.state}/. The operator will approve or discard from the dashboard; do not wait for it. Continue your current task.`,
+                        },
+                    ],
+                    isError: false,
+                    // Structured data alongside the human-readable text — MCP clients that
+                    // surface this make the identifier programmatically available without
+                    // re-parsing the content string.
+                    structuredContent: {
+                        identifier: result.identifier,
+                        state: result.state,
+                        path: result.path,
+                    },
+                },
+            };
+        }
+        catch (err) {
+            return makeToolError(id, `failed to propose issue: ${err.message}`);
+        }
     }
     /** Snapshot of currently active issues, used by HTTP for routing lookups. */
     isActive(identifier, token) {
         const active = this.byIdentifier.get(identifier);
-        return !!active && constantTimeStringEqual(active.token, token);
-    }
-}
-/**
- * Constant-time string comparison for secrets. Uses crypto.timingSafeEqual on
- * equal-length buffers; rejects different-length inputs (the registry only ever
- * issues fixed-width base64url tokens, so a length mismatch is unconditionally
- * a wrong-token signal and the early exit doesn't leak per-byte timing).
- *
- * We compare BYTE lengths after UTF-8 encoding, not JS string `.length` (which
- * counts UTF-16 code units). An attacker-supplied non-ASCII token can match the
- * real token's code-unit count while encoding to a different byte length; passing
- * those buffers to timingSafeEqual would throw `Input buffers must have the same
- * byte length`, surfacing as an HTTP 500 instead of a clean wrong-token rejection.
- */
-function constantTimeStringEqual(a, b) {
-    const aBuf = Buffer.from(a, 'utf8');
-    const bBuf = Buffer.from(b, 'utf8');
-    if (aBuf.length !== bBuf.length)
-        return false;
-    return timingSafeEqual(aBuf, bBuf);
-}
-/**
- * Pick the symphony-runtime staging directory for a workspace. Mirrors the
- * adapter-staging policy in adapters.ts: when the workspace has its own
- * `.git/` directory, the runtime files live inside it (outside the working
- * tree, structurally untrackable); otherwise they sit at workspace root.
- * `mark_done` writes its persisted artifact here so the after_run hook can
- * find it via the same probe.
- */
-async function pickStagingDir(workspacePath) {
-    const gitPath = path.join(workspacePath, '.git');
-    try {
-        const st = await lstat(gitPath);
-        if (st.isDirectory())
-            return path.join(workspacePath, '.git', 'symphony-runtime');
+        return !!active && this.crypto.constantTimeEqual(active.token, token);
     }
-    catch {
-        // .git missing or unstat-able — fall through to the workspace-root path.
-    }
-    return path.join(workspacePath, '.symphony-runtime');
 }
 function getId(body) {
     if (body && typeof body === 'object' && !Array.isArray(body)) {
@@ -475,4 +664,43 @@ function makeToolError(id, message) {
         },
     };
 }
+/**
+ * MCP tool error with both a human-readable text block and a structured JSON
+ * block. Used by `symphony.transition` so agents can read the rejection's
+ * structured payload (`declared_states`, `allowed_transitions`, etc.) to pick a
+ * valid target on their next call without re-parsing the prose. Pairs with
+ * `makeToolError` (text-only) for everything else.
+ */
+function makeStructuredToolError(id, text, json) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+            // MCP 2025-06-18 `CallToolResult.content` is `ContentBlock[]` and does not
+            // define a `json` block type; the canonical home for machine-readable
+            // payloads is `structuredContent`. Keep only the text block in `content[]`
+            // for human display and put the structured shape on the SDK-recognised slot.
+            content: [{ type: 'text', text }],
+            isError: true,
+            structuredContent: json,
+        },
+    };
+}
+/**
+ * Resolve a caller-supplied state name to its canonical declared form (the
+ * casing the operator wrote in `states:`). Comparison is case-insensitive to
+ * mirror the rest of symphony (eligibility, reconciliation, the local-tracker
+ * directory scan all compare lowercase). Returns null when no declared name
+ * matches.
+ */
+function canonicalStateName(states, name) {
+    if (Object.prototype.hasOwnProperty.call(states, name))
+        return name;
+    const lower = name.toLowerCase();
+    for (const declared of Object.keys(states)) {
+        if (declared.toLowerCase() === lower)
+            return declared;
+    }
+    return null;
+}
 //# sourceMappingURL=mcp.js.map