@cat-factory/server 0.214.1 → 0.216.0

package/dist/modules/publicApi/PublicMcpController.js

@@ -0,0 +1,74 @@
+// The `./http` entry point, NOT the package root: the root re-exports the stdio boot, whose
+// transport imports `node:process`, and this package is bundled into the Worker facade.
+import { handleMcpHttpRequest, refuseMcpMethod } from '@cat-factory/mcp-server/http';
+import { describeError } from '@cat-factory/kernel';
+import { Hono } from 'hono';
+import { requestLogger } from '../../http/requestLogging.js';
+import { authorizeOrThrow, bearerToken } from './publicApiAuth.js';
+// The HOSTED MCP endpoint (`POST /api/v1/mcp`): the public API spoken as Model Context Protocol, so
+// a host reaches this deployment with no install.
+//
+// Until now the only way to drive cat-factory from a model was `npx @cat-factory/mcp-server`: an npm
+// dependency, a local process per host, and a long-lived key sitting in the host's config file. That
+// rules out every host that cannot spawn one — claude.ai, a hosted agent, a phone — which is most of
+// where people actually work. This is the SAME server behind an HTTP transport, so those hosts need a
+// URL and a key and nothing else. The stdio binary stays: it is the path that needs no backend
+// deployment at all, and the only one for a host with no HTTP MCP support.
+//
+// The protocol implementation is `@cat-factory/mcp-server`'s, deliberately. This controller decides
+// three things and nothing else: who is calling, what their key's scope means for the tool list, and
+// where the tools' own API calls go. Everything a tool DOES is one `/api/v1` request under the
+// caller's own key through the loopback, so this surface cannot drift from the surface it exposes and
+// no capability exists here that the caller could not have reached with `curl`.
+//
+// NOT an OpenAPI operation, unlike every other `/api/v1` route. A JSON-RPC endpoint has no operation
+// shape to describe (one path, one verb, a union of dozens of method bodies), and adding it to the
+// spec would mint an SDK method in four languages for a protocol none of those clients speaks. It is
+// PUBLIC SURFACE under the stability contract from its first release all the same;
+// `backend/docs/public-api.md` carries that obligation in the spec's place.
+//
+// Two refusal shapes, and the split is the caller's own: an auth failure is HTTP-level in the MCP
+// spec (the client reads the status), so it throws and `handleError` renders the deployment's error
+// envelope with its correlation id and machine-readable reason. A method refusal is the TRANSPORT's
+// vocabulary, so it is answered in the transport's own JSON-RPC frame by `refuseMcpMethod`.
+export function publicMcpController(loopback) {
+    const app = new Hono();
+    // Every verb on one handler, so a `GET` gets the protocol's "no stream here" rather than Hono's
+    // bare 404, which a client reads as "no MCP endpoint at this URL".
+    app.all('/api/v1/mcp', async (c) => {
+        const refused = refuseMcpMethod(c.req.method);
+        if (refused)
+            return refused;
+        // `read` is the FLOOR, not a per-tool requirement: the ladder is inclusive, so this refuses only
+        // an absent, unknown or revoked key. What each tool may do stays enforced where it already is, by
+        // the `/api/v1` handler the loopback reaches — a scope table restated here would be a second
+        // authority on the same question, free to disagree with the first.
+        const auth = await authorizeOrThrow(c, 'read');
+        const log = requestLogger(c);
+        return handleMcpHttpRequest(c.req.raw, {
+            // The deployment's own origin, taken from the request being answered: the tools resolve their
+            // paths against it, and it is the one value that is right on a preview URL, a custom domain and
+            // a test harness alike.
+            baseUrl: new URL(c.req.url).origin,
+            // Forwarded verbatim, so the tools authenticate as the CALLER rather than as the deployment.
+            // That is what keeps the workspace scoping and the per-tool scope ladder applying unchanged.
+            // Non-empty by construction: the gate above authenticated THIS value, so the fallback is
+            // unreachable rather than a default standing in for a missing key.
+            apiKey: bearerToken(c) ?? '',
+            fetch: (input, init) => loopback(new Request(input, init), c),
+            // A `read` key can only be REFUSED by a write tool, so listing the writes would spend a model's
+            // turns discovering that. The reason rides along because the fix is a wider key rather than an
+            // operator's edit, and the server's instructions name the right one.
+            ...(auth.scope === 'read' ? { readOnly: true, readOnlyReason: 'key-scope' } : {}),
+            onTransportError: (error) => {
+                // The transport has already answered by the time this fires, so a drop here leaves a caller
+                // reporting a broken endpoint and nothing on this side to read. Through `describeError`
+                // rather than `error.message`: it binds the kind alongside the message and scrubs through
+                // `redactSecrets`, and the request this fault interrupted was carrying a live API key.
+                log.warn('Hosted MCP transport error', describeError(error));
+            },
+        });
+    });
+    return app;
+}
+//# sourceMappingURL=PublicMcpController.js.map

package/dist/modules/publicApi/PublicMcpController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PublicMcpController.js","sourceRoot":"","sources":["../../../src/modules/publicApi/PublicMcpController.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,wFAAwF;AACxF,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AACpF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAG3B,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAElE,oGAAoG;AACpG,kDAAkD;AAClD,EAAE;AACF,qGAAqG;AACrG,qGAAqG;AACrG,qGAAqG;AACrG,sGAAsG;AACtG,+FAA+F;AAC/F,2EAA2E;AAC3E,EAAE;AACF,oGAAoG;AACpG,qGAAqG;AACrG,+FAA+F;AAC/F,sGAAsG;AACtG,gFAAgF;AAChF,EAAE;AACF,qGAAqG;AACrG,mGAAmG;AACnG,qGAAqG;AACrG,mFAAmF;AACnF,4EAA4E;AAC5E,EAAE;AACF,kGAAkG;AAClG,oGAAoG;AACpG,oGAAoG;AACpG,4FAA4F;AAE5F,MAAM,UAAU,mBAAmB,CAAmB,QAAwB;IAC5E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAK,CAAA;IAEzB,gGAAgG;IAChG,mEAAmE;IACnE,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QACjC,MAAM,OAAO,GAAG,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;QAC7C,IAAI,OAAO;YAAE,OAAO,OAAO,CAAA;QAE3B,iGAAiG;QACjG,kGAAkG;QAClG,6FAA6F;QAC7F,mEAAmE;QACnE,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;QAC9C,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,CAAA;QAE5B,OAAO,oBAAoB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE;YACrC,8FAA8F;YAC9F,gGAAgG;YAChG,wBAAwB;YACxB,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM;YAClC,6FAA6F;YAC7F,6FAA6F;YAC7F,yFAAyF;YACzF,mEAAmE;YACnE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE;YAC5B,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YAC7D,gGAAgG;YAChG,+FAA+F;YAC/F,qEAAqE;YACrE,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,WAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1F,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC1B,4FAA4F;gBAC5F,wFAAwF;gBACxF,0FAA0F;gBAC1F,uFAAuF;gBACvF,GAAG,CAAC,IAAI,CAAC,4BAA4B,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;YAC9D,CAAC;SACF,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/modules/publicApi/decisions/approvalRoutes.d.ts

@@ -0,0 +1,4 @@
+import type { Hono } from 'hono';
+import type { AppEnv } from '../../../http/env.js';
+export declare function registerApprovalDecisionRoutes(app: Hono<AppEnv>): void;
+//# sourceMappingURL=approvalRoutes.d.ts.map

package/dist/modules/publicApi/decisions/approvalRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvalRoutes.d.ts","sourceRoot":"","sources":["../../../../src/modules/publicApi/decisions/approvalRoutes.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAsBlD,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAoGtE"}

package/dist/modules/publicApi/decisions/approvalRoutes.js

@@ -0,0 +1,96 @@
+import { approvePublicRunStepContract, rejectPublicRunStepContract, requestPublicRunStepChangesContract, resolvePublicRunAgentDecisionContract, resolvePublicRunStepExceededContract, } from '@cat-factory/contracts';
+import { buildHonoRoute } from '@toad-contracts/hono';
+import { runWithInitiator } from '../../../github/runInitiatorContext.js';
+import { buildDecisionList } from './projection.js';
+import { failureBody, gateDecisionAction } from './scope.js';
+// The GENERIC approval gate — "pause a run until a human approves" — plus the decisions an agent
+// raises mid-work. Both are answered by an id the caller read from `GET .../decisions`, and both
+// delegate to the SAME `StepDecisionController` methods the SPA's rail calls, so the engine's
+// arbitration decides who wins when a person and an integration answer at once.
+//
+// Every route here runs under the RUN'S OWN initiator, for the reason the fork and judge routes
+// do: releasing the park wakes the durable driver, and a board run started in the SPA carries a
+// `usr_*` initiator whose per-user credentials the resumed container work must keep using.
+// Answering such a run over the API must not silently demote its clone/push to the deployment
+// default. A genuinely headless run has `initiatedBy: null`, where this is a no-op.
+//
+// What is deliberately NOT re-implemented: the SPA's `activateForInteraction` re-mint of a
+// personal credential before the engine dispatches the next step. It exists so a browser client
+// can be 428'd into re-prompting a human for a password, and there is no human here to prompt — a
+// key-authenticated caller has no personal credential to unlock, which is the same reason the
+// public start paths refuse a task pinned to an individual-usage model.
+export function registerApprovalDecisionRoutes(app) {
+    // Approve the gated proposal (optionally replacing it with an edited one) and advance the run.
+    buildHonoRoute(app, approvePublicRunStepContract, async (c) => {
+        const { runId, approvalId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.approveStep(workspaceId, scoped.execution.id, approvalId, {
+            proposal: c.req.valid('json').proposal,
+        }));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Request changes: the gated step re-runs with the caller's guidance folded in.
+    buildHonoRoute(app, requestPublicRunStepChangesContract, async (c) => {
+        const { runId, approvalId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.requestStepChanges(workspaceId, scoped.execution.id, approvalId, {
+            feedback: c.req.valid('json').feedback,
+        }));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Reject: the run stops entirely. No initiator scope — nothing is dispatched, and the terminal
+    // `rejected` failure is exactly what the board offers a retry on.
+    buildHonoRoute(app, rejectPublicRunStepContract, async (c) => {
+        const { runId, approvalId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.rejectStep(workspaceId, scoped.execution.id, approvalId, c.req.valid('json').reason);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Resolve a companion gate parked at its automatic-rework cap. A DIFFERENT route from approve on
+    // purpose: the engine refuses the generic verbs on this park (`assertNotIterativeGate`), and the
+    // decision projection flags it as `exceeded` so a caller reaches for this one.
+    buildHonoRoute(app, resolvePublicRunStepExceededContract, async (c) => {
+        const { runId, approvalId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.resolveCompanionExceeded(workspaceId, scoped.execution.id, approvalId, c.req.valid('json').choice));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Answer a decision an agent raised: the asking step RE-RUNS with the choice folded in.
+    buildHonoRoute(app, resolvePublicRunAgentDecisionContract, async (c) => {
+        const { runId, decisionId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.resolveDecision(workspaceId, scoped.execution.id, decisionId, c.req.valid('json').choice));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+}
+//# sourceMappingURL=approvalRoutes.js.map

package/dist/modules/publicApi/decisions/approvalRoutes.js.map

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

package/dist/modules/publicApi/decisions/dialogueRoutes.d.ts

@@ -0,0 +1,5 @@
+import type { Hono } from 'hono';
+import type { AppEnv } from '../../../http/env.js';
+export declare function registerClarityDecisionRoutes(app: Hono<AppEnv>): void;
+export declare function registerBrainstormDecisionRoutes(app: Hono<AppEnv>): void;
+//# sourceMappingURL=dialogueRoutes.d.ts.map

package/dist/modules/publicApi/decisions/dialogueRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialogueRoutes.d.ts","sourceRoot":"","sources":["../../../../src/modules/publicApi/decisions/dialogueRoutes.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAelD,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAoFrE;AAED,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAkGxE"}

package/dist/modules/publicApi/decisions/dialogueRoutes.js

@@ -0,0 +1,161 @@
+import { incorporatePublicRunBrainstormContract, incorporatePublicRunClarityContract, proceedPublicRunBrainstormContract, proceedPublicRunClarityContract, replyPublicRunBrainstormOptionContract, replyPublicRunClarityFindingContract, reReviewPublicRunBrainstormContract, reReviewPublicRunClarityContract, resolvePublicRunBrainstormExceededContract, resolvePublicRunClarityExceededContract, setPublicRunBrainstormOptionStatusContract, setPublicRunClarityFindingStatusContract, } from '@cat-factory/contracts';
+import { buildHonoRoute } from '@toad-contracts/hono';
+import { buildDecisionList } from './projection.js';
+import { failureBody, gateBrainstormAction, gateClarityAction } from './scope.js';
+// The two iterative-review loops beside requirements: CLARITY (bug-report triage) and the two
+// BRAINSTORM dialogues. Both mirror the requirements routes verb for verb, because they are the
+// same loop over a different subject — the engine drives all three through one
+// `ReviewGateController`, so exposing them differently here would invent a distinction the
+// platform does not have.
+//
+// Both are addressed the way requirements is: by ITEM id, with the live entity resolved from the
+// run's block (and, for a brainstorm, its stage). The INTERNAL routes for both are entity-keyed
+// (`/clarity-reviews/:reviewId/items/:itemId`, `/brainstorms/:sessionId/items/:itemId`); copying
+// that here would make a headless caller thread through an id it never chose.
+export function registerClarityDecisionRoutes(app) {
+    // Answer one triage finding.
+    buildHonoRoute(app, replyPublicRunClarityFindingContract, async (c) => {
+        const { runId, itemId } = c.req.valid('param');
+        const gated = await gateClarityAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped, clarity, review } = gated;
+        await clarity.service.replyToItem(workspaceId, review.id, itemId, c.req.valid('json').reply);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Dismiss a finding as not applicable, or reopen one dismissed by mistake.
+    buildHonoRoute(app, setPublicRunClarityFindingStatusContract, async (c) => {
+        const { runId, itemId } = c.req.valid('param');
+        const gated = await gateClarityAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped, clarity, review } = gated;
+        await clarity.service.setItemStatus(workspaceId, review.id, itemId, c.req.valid('json').status);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Fold the recorded answers into a standardized bug report. ASYNCHRONOUS, as requirements.
+    buildHonoRoute(app, incorporatePublicRunClarityContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateClarityAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.clarityReview.incorporate(workspaceId, scoped.blockId, c.req.valid('json').feedback);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // One more triage pass over the clarified report.
+    buildHonoRoute(app, reReviewPublicRunClarityContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateClarityAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c.get('container').executionService.clarityReview.reReview(workspaceId, scoped.blockId);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Settle the clarity phase and advance the parked run.
+    buildHonoRoute(app, proceedPublicRunClarityContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateClarityAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c.get('container').executionService.clarityReview.proceed(workspaceId, scoped.blockId);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Resolve a review that hit its iteration cap (extra round / proceed / stop and reset).
+    buildHonoRoute(app, resolvePublicRunClarityExceededContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateClarityAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.clarityReview.resolveExceeded(workspaceId, scoped.blockId, c.req.valid('json').choice);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+}
+export function registerBrainstormDecisionRoutes(app) {
+    // Respond to one proposed option (pick it, or steer it).
+    buildHonoRoute(app, replyPublicRunBrainstormOptionContract, async (c) => {
+        const { runId, stage, itemId } = c.req.valid('param');
+        const gated = await gateBrainstormAction(c, runId, stage);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped, brainstorm, review } = gated;
+        await brainstorm.services[stage].replyToItem(workspaceId, review.id, itemId, c.req.valid('json').reply);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Dismiss a proposed option, or reopen one dismissed by mistake.
+    buildHonoRoute(app, setPublicRunBrainstormOptionStatusContract, async (c) => {
+        const { runId, stage, itemId } = c.req.valid('param');
+        const gated = await gateBrainstormAction(c, runId, stage);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped, brainstorm, review } = gated;
+        await brainstorm.services[stage].setItemStatus(workspaceId, review.id, itemId, c.req.valid('json').status);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Fold the picks into one converged direction. ASYNCHRONOUS, as requirements.
+    buildHonoRoute(app, incorporatePublicRunBrainstormContract, async (c) => {
+        const { runId, stage } = c.req.valid('param');
+        const gated = await gateBrainstormAction(c, runId, stage);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.brainstorm.incorporate(workspaceId, scoped.blockId, stage, c.req.valid('json').feedback);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // One more brainstorm pass against the converged direction.
+    buildHonoRoute(app, reReviewPublicRunBrainstormContract, async (c) => {
+        const { runId, stage } = c.req.valid('param');
+        const gated = await gateBrainstormAction(c, runId, stage);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.brainstorm.reReview(workspaceId, scoped.blockId, stage);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Settle the brainstorm (the last converged direction wins downstream) and advance the run.
+    buildHonoRoute(app, proceedPublicRunBrainstormContract, async (c) => {
+        const { runId, stage } = c.req.valid('param');
+        const gated = await gateBrainstormAction(c, runId, stage);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c.get('container').executionService.brainstorm.proceed(workspaceId, scoped.blockId, stage);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Resolve a session that hit its iteration cap (extra round / proceed / stop and reset).
+    buildHonoRoute(app, resolvePublicRunBrainstormExceededContract, async (c) => {
+        const { runId, stage } = c.req.valid('param');
+        const gated = await gateBrainstormAction(c, runId, stage);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.brainstorm.resolveExceeded(workspaceId, scoped.blockId, stage, c.req.valid('json').choice);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+}
+//# sourceMappingURL=dialogueRoutes.js.map

package/dist/modules/publicApi/decisions/dialogueRoutes.js.map

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

package/dist/modules/publicApi/decisions/gateRoutes.d.ts

@@ -0,0 +1,5 @@
+import type { Hono } from 'hono';
+import type { AppEnv } from '../../../http/env.js';
+export declare function registerPrReviewDecisionRoutes(app: Hono<AppEnv>): void;
+export declare function registerHumanVerdictGateRoutes(app: Hono<AppEnv>): void;
+//# sourceMappingURL=gateRoutes.d.ts.map

package/dist/modules/publicApi/decisions/gateRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateRoutes.d.ts","sourceRoot":"","sources":["../../../../src/modules/publicApi/decisions/gateRoutes.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAChC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAqBlD,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CA2DtE;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAoEtE"}

package/dist/modules/publicApi/decisions/gateRoutes.js

@@ -0,0 +1,120 @@
+import { approvePublicRunVisualConfirmContract, challengePublicRunPrReviewFindingContract, confirmPublicRunHumanTestContract, dismissPublicRunPrReviewFindingContract, requestPublicRunHumanTestFixContract, requestPublicRunVisualConfirmFixContract, resolvePublicRunPrReviewContract, } from '@cat-factory/contracts';
+import { buildHonoRoute } from '@toad-contracts/hono';
+import { runWithInitiator } from '../../../github/runInitiatorContext.js';
+import { buildDecisionList } from './projection.js';
+import { failureBody, gateDecisionAction } from './scope.js';
+// The three CONTAINER-BACKED parks: the PR deep review's finding curation, and the two
+// human-verdict gates (human-test, visual-confirmation).
+//
+// All three are reachable only through `POST /api/v1/tasks/:taskId/start`, since each is produced
+// by a container step and the jobs surface is inline-only. That is also why a route here that can
+// DISPATCH runs under the run's own initiator: standing up a container agent (a fixer, a challenge
+// investigator) or writing to the pull request must keep using the credentials the run was started
+// with rather than the deployment default. `dismiss` is the one route that does not, and the
+// omission is deliberate rather than missed: dropping a finding from the parked review writes the
+// step and nothing else, so there is no outbound work for an initiator to credential.
+//
+// The human-verdict gates are addressed by RUN, not by the parked step, because their service
+// methods are block-scoped (the SPA drives them from the task's window). That makes the `runId`
+// decorative to everything downstream, which is safe for the reason `loadScopedRun` documents: a
+// run that is no longer its block's live run is not resolvable, so resolution IS the check.
+export function registerPrReviewDecisionRoutes(app) {
+    // Resolve the parked review with the curated selection. `fix` and `post` act on the real pull
+    // request — the one place this surface has an effect outside the platform.
+    buildHonoRoute(app, resolvePublicRunPrReviewContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        // The public body leaves both fields plainly optional (a schema `default` on a REQUEST field
+        // emits four SDKs whose types insist on a value the API does not require), so the same
+        // fallbacks the internal schema declares are applied here.
+        const { action, findingIds } = c.req.valid('json');
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c.get('container').executionService.resolvePrReview(workspaceId, scoped.execution.id, {
+            action: action ?? 'finish',
+            findingIds: findingIds ?? [],
+        }));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Drop one finding from the review entirely. Curation, not a resolution: the run stays parked,
+    // and nothing is dispatched, hence no initiator scope (see the note at the top of this file).
+    buildHonoRoute(app, dismissPublicRunPrReviewFindingContract, async (c) => {
+        const { runId, findingId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await c
+            .get('container')
+            .executionService.dismissPrReviewFinding(workspaceId, scoped.execution.id, findingId);
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Challenge one finding: dispatch the read-only investigator to re-examine it. The review
+    // returns to `awaiting_selection` carrying the verdict, so the caller polls for the outcome.
+    buildHonoRoute(app, challengePublicRunPrReviewFindingContract, async (c) => {
+        const { runId, findingId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.challengePrReviewFinding(workspaceId, scoped.execution.id, findingId, c.req.valid('json')));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+}
+export function registerHumanVerdictGateRoutes(app) {
+    // Human-test: the change works. Tear the ephemeral environment down and advance the run.
+    buildHonoRoute(app, confirmPublicRunHumanTestContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c.get('container').executionService.humanTest.confirm(workspaceId, scoped.blockId));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Human-test: submit findings and dispatch the fixer, then rebuild the environment.
+    buildHonoRoute(app, requestPublicRunHumanTestFixContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.humanTest.requestFix(workspaceId, scoped.blockId, c.req.valid('json').findings));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Visual confirmation: the screenshots match. Advance the run.
+    buildHonoRoute(app, approvePublicRunVisualConfirmContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c.get('container').executionService.visualConfirm.approve(workspaceId, scoped.blockId));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+    // Visual confirmation: submit findings and dispatch the fixer, then re-park.
+    buildHonoRoute(app, requestPublicRunVisualConfirmFixContract, async (c) => {
+        const { runId } = c.req.valid('param');
+        const gated = await gateDecisionAction(c, runId);
+        if ('fail' in gated) {
+            return c.json(failureBody(gated.fail), gated.fail.status);
+        }
+        const { workspaceId, scoped } = gated;
+        await runWithInitiator({ workspaceId, initiatedBy: scoped.execution.initiatedBy }, () => c
+            .get('container')
+            .executionService.visualConfirm.requestFix(workspaceId, scoped.blockId, c.req.valid('json').findings));
+        return c.json(await buildDecisionList(c, workspaceId, scoped), 200);
+    });
+}
+//# sourceMappingURL=gateRoutes.js.map

package/dist/modules/publicApi/decisions/gateRoutes.js.map

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

package/dist/modules/publicApi/decisions/projection.d.ts

@@ -0,0 +1,62 @@
+import type { BrainstormSession, ClarityReview, Decision, ForkDecisionStepState, HumanTestStepState, JudgeStepState, PipelineStep, PrReviewStepState, PublicDecision, PublicDecisionList, RequirementReview, RunInputGate, StepApproval, VisualConfirmStepState } from '@cat-factory/contracts';
+import type { Context } from 'hono';
+import type { AppEnv } from '../../../http/env.js';
+import type { ScopedRun } from './scope.js';
+/** Project a live requirements review onto the external decision resource. */
+export declare function toRequirementsDecision(review: RequirementReview): PublicDecision;
+/** Project a live clarity (bug-triage) review — the requirements twin over its own document. */
+export declare function toClarityDecision(review: ClarityReview): PublicDecision;
+/** Project a live brainstorm session for one stage. */
+export declare function toBrainstormDecision(session: BrainstormSession): PublicDecision;
+/** Project a run's fork-decision step state onto the external decision resource. */
+export declare function toForkDecision(state: ForkDecisionStepState): PublicDecision;
+/**
+ * Project a run's JUDGE step state onto the external decision resource. The rubric body is
+ * deliberately omitted (see `publicJudgeDecisionSchema`) — a caller answers the findings.
+ */
+export declare function toJudgeDecision(stepKind: string, state: JudgeStepState): PublicDecision;
+/**
+ * Project a step's APPROVAL GATE. `exceeded` is read off the step's companion state rather than
+ * the approval itself, because that is where the engine records it — and it is what tells a caller
+ * to answer with `resolve-exceeded` instead of `approve`. Reading it as a plain boolean (rather
+ * than only when a companion exists) means an ordinary pipeline gate reports `false`, which is the
+ * true statement, not an omission.
+ */
+export declare function toApprovalDecision(step: PipelineStep, stepIndex: number, approval: StepApproval): PublicDecision;
+/** Project a decision an agent raised mid-work. */
+export declare function toAgentDecision(step: PipelineStep, decision: Decision): PublicDecision;
+/**
+ * Project a parked PR deep review's curation state.
+ *
+ * The slices and findings go through their own projections rather than crossing the wire as the
+ * engine holds them: the internal shapes are mid-evolution (per-slice resume reports) while the
+ * published ones must not move, and the `optional | null` internals collapse to always-present
+ * nullables so four generated clients have one shape to check.
+ */
+export declare function toPrReviewDecision(state: PrReviewStepState): PublicDecision;
+/** Project a parked human-test gate: what to test against, and how much fix budget is left. */
+export declare function toHumanTestDecision(state: HumanTestStepState): PublicDecision;
+/** Project a parked visual-confirmation gate: the pairings awaiting a verdict. */
+export declare function toVisualConfirmDecision(state: VisualConfirmStepState): PublicDecision;
+/**
+ * Project the PRE-DISPATCH INPUT GATE's verdict for an external caller. The issue CODES are the same
+ * closed vocabulary the SPA renders, so an integration maps them to its own copy (or hands them to
+ * whoever filed the ticket) rather than parsing our prose.
+ */
+export declare function toInputGateDecision(gate: RunInputGate): PublicDecision;
+/**
+ * Build the run's decision list: whatever it is currently asking a human, plus the run status so a
+ * caller can distinguish "parked, answer me" from "still working".
+ *
+ * The run is RE-READ rather than taken from the `ScopedRun` the caller was gated with, because
+ * every mutating route builds its response through here AFTER acting: a `proceed` that advanced the
+ * run, or an `incorporate` that flipped it out of `blocked`, must not report the pre-action status.
+ * A run that vanished between the gate and here (a concurrent delete) falls back to the gated
+ * snapshot rather than 500-ing on an action that already succeeded.
+ *
+ * Everything that rides the run's STEPS is read off the instance already in hand; only the
+ * separately-stored iterative reviews cost a round-trip, and those are bounded by what the run's
+ * own step chain can produce (see {@link liveDialogueDecisions}).
+ */
+export declare function buildDecisionList<E extends AppEnv>(c: Context<E>, workspaceId: string, scoped: ScopedRun): Promise<PublicDecisionList>;
+//# sourceMappingURL=projection.d.ts.map

package/dist/modules/publicApi/decisions/projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.d.ts","sourceRoot":"","sources":["../../../../src/modules/publicApi/decisions/projection.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,iBAAiB,EAEjB,aAAa,EACb,QAAQ,EAER,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,YAAY,EAGZ,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAGlB,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACvB,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAgB3C,8EAA8E;AAC9E,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,cAAc,CAWhF;AAED,gGAAgG;AAChG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAWvE;AAED,uDAAuD;AACvD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAY/E;AAoBD,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,cAAc,CAO3E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,cAAc,CAYvF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,YAAY,GACrB,cAAc,CAWhB;AAED,mDAAmD;AACnD,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAQtF;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAU3E;AAuCD,+FAA+F;AAC/F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,cAAc,CAY7E;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,sBAAsB,GAAG,cAAc,CAarF;AAwGD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAQtE;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EACtD,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,EACb,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,kBAAkB,CAAC,CAsC7B"}