V48 Gate 3 (specification-implementation): cooperative run cancel + sandbox host durability

Spec (NOTES #26 + parity matrix #26–31; QA runbook cancel/sandbox):
- Exhaustive cancel law (row authority, cooperative abort, sandbox stop, UI)
- Sandbox deposit: ephemeral boxes, OIDC/token auth fail-closed, sandboxId on context

Implementation:
- POST /api/executions/[runId]/cancel + execution-cancel helper
- Deposit route polls cancel; sandbox shouldAbort + non-persistent create
- VercelSandboxPipelineHost abort/cancel outcome; assertVercelSandboxAuthAvailable
- Deposit UI Cancel run control + deposit_synthesis_cancelled analytics
- Tests for cancel API, host abort, harness result shape, provisioning

Author: geraldarthurdavis

BITCODE_SPEC_V48_NOTES.md

@@ -1015,13 +1015,13 @@ is named in spec for closure):
 - **Config.** `BITCODE_DEPOSIT_SYNTHESIS_PIPELINE` removed (full SDIVF pipeline only;
   Validation — measurement + quality — never skipped).
 
-### Gate-3 #25 — SandboxHost in-box deposit dispatch (Garrett, 2026-06-27)
+### Gate-3 #25 — SandboxHost in-box deposit dispatch (Garrett, 2026-06-27; cancel+auth hardened 2026-07-08)
 
 SandboxHost deposit runs the synthesis pipeline INSIDE the box (the asset-pack
 harness already runs `assetPackPipeline` in-box for read-fit via a runner that imports
 the live packages and executes the full SDIVF). Deposit reuses that mechanism:
 
-- **Harness deposit mode.** `buildAssetPackSandboxHarness` accepts `synthesisMode`
+- **Harness deposit mode.** `buildAssetPackSandboxHarness` accepts `synthesizeMode`
   (`'deposit' | 'read'`) + the deposit STEERING (obfuscations, protected-IP exclusions,
   demand context); these flow into `PipelineHarnessManifest` and the in-box runner
   INPUT (`synthesizeMode`, steering). The in-box pipeline resolves deposit mode
@@ -1031,19 +1031,66 @@ the live packages and executes the full SDIVF). Deposit reuses that mechanism:
   surfaces the synthesized `implementation:options` in `evidence.json` as
   `depositOptions` (source-safe option metadata; the measure-agent's absolutes are
   already attached by the Validation phase IN the box).
-- **Route dispatch.** When the configured HostKind is `sandbox`, the deposit route
-  dispatches the deposit harness (a git `source` for the revision) via
-  `VercelSandboxPipelineHost.runHarness` (provider Vercel) instead of the in-process
-  InlineHost path; it reads `evidence.depositOptions`, runs the SAME pure projection
-  (`validateDepositSynthesisOptions` + `buildRealDepositAssetPackOptionSynthesis`) and
-  persists the deposit option synthesis to the execution row — identical to the inline
-  path. Source-safe telemetry streams from the harness telemetry artifact to
-  `execution_events`.
-- **Parity of result.** InlineHost (in current box) and SandboxHost (in the provisioned
-  box) produce the SAME deposit option synthesis; only WHERE the pipeline runs differs.
-  Real-sandbox execution is verified against deployed sandbox infra (`@vercel/sandbox`,
-  `VERCEL_*`, git in the box image); the harness plan-building + the route dispatch +
-  the option projection are unit-tested with a mocked host.
+- **Ephemeral boxes.** Deposit one-shots create sandboxes with `persistent: false`
+  (no snapshot storage on stop). Auth: prefer `VERCEL_OIDC_TOKEN` (local: `vercel env
+  pull`; automatic on Vercel); fallback `VERCEL_TOKEN` + `VERCEL_TEAM_ID` +
+  `VERCEL_PROJECT_ID`. `assertVercelSandboxAuthAvailable` fails closed before create.
+- **Route dispatch.** When `BITCODE_PIPELINE_HOST=sandbox`, the deposit route
+  dispatches via `runDepositInBoxHarness` → `VercelSandboxPipelineHost.runHarness`
+  instead of InlineHost provision + in-process SDIVF; it reads `evidence.depositOptions`,
+  runs the SAME pure projection (`validateDepositSynthesisOptions` +
+  `buildRealDepositAssetPackOptionSynthesis`) and persists the deposit option
+  synthesis. `resolveDepositPipelineHost` is **inline-only** (throws if hostKind is
+  sandbox — callers must use the harness path). On `sandbox-created`, the route
+  persists `context.sandboxId` on the running execution row for cancel.
+- **Cooperative cancel.** See Gate-3 #26.
+- **Parity of result.** InlineHost and SandboxHost produce the SAME deposit option
+  synthesis; only WHERE the pipeline runs differs. Real-sandbox execution is verified
+  against deployed sandbox infra; harness plan-building + route dispatch + projection
+  are unit-tested with a mocked host.
+
+### Gate-3 #26 — Cooperative run cancel (Garrett, 2026-07-08)
+
+Deposit (and any agentic) runs are cancelable without killing mid-token LLM streams.
+
+**Law**
+
+1. **User authority.** A depositor who owns the `executions` row may cancel while
+   `status === 'running'`. Terminal rows (`completed` | `failed` | `interrupted` |
+   `cancelled`) are not re-cancelled (already-cancelled is idempotent 200).
+2. **Row is authority.** Cancel writes `executions.status = 'cancelled'`,
+   `completed_at`, source-safe `error.message`, and `context.cancelledAt` /
+   `context.cancelReason`. Background workers MUST NOT overwrite a cancelled row
+   with `failed` or `completed`.
+3. **Event.** A source-safe `execution_events` status row (`message`, `cancelled: true`)
+   is inserted so the deposit telemetry accordion shows the cancel.
+4. **Cooperative abort.** Background deposit `runSynthesis` polls
+   `assertExecutionNotCancelled` between major stages (auth, provision, pipeline,
+   validate). Sandbox detached command polls call `shouldAbort` each interval and
+   return exit code 130 / outcome `'cancelled'`, then `sandbox.stop()`.
+5. **Sandbox stop.** If `context.sandboxId` is present, cancel best-effort stops the
+   box via `Sandbox.get` + `stop` (in addition to harness `finally` stop).
+6. **UI.** While a synthesis is running, Telemetry shows **Cancel run**; on success
+   the detail shows a Cancelled badge and analytics fires
+   `deposit_synthesis_cancelled` (duration only — no identifiers).
+7. **Not cancel.** Orphan sweep still maps silent stuck rows → `interrupted` (not
+   cancelled). Deleting activity anchors is unrelated.
+
+**API**
+
+- `POST /api/executions/[runId]/cancel` body optional `{ reason?: string }` (≤280 chars)
+- Auth: session user must own the row
+- Responses: 200 cancelled (or already cancelled), 401 unauthenticated, 404 not
+  found/not owned, 409 not running
+
+**Implementation symbols**
+
+- `uapi/lib/execution-cancel.ts` — `cancelUserExecution`, `assertExecutionNotCancelled`,
+  `ExecutionCancelledError`, `isExecutionCancelled`
+- `uapi/app/api/executions/[runId]/cancel/route.ts`
+- Deposit route cooperative checks + sandbox `shouldAbort`
+- `VercelSandboxPipelineHost` `shouldAbort` + `sandbox-cancelled` events
+- `DepositPageClient` Cancel run control
 
 ### Gate-3 depositing PARITY MATRIX (gate-closure audit; Garrett, 2026-06-27)
 
@@ -1077,17 +1124,26 @@ Parity: ✅ specified + implemented + tested · 🟦 specified + implemented as
 | 22 | HostKind selection (configured, not env) | `selectDepositHostKind` / `resolveDepositPipelineHost` | depositSourceProvisioning.test | ✅ |
 | 23 | full inventory (sources+samples) + fail-closed exclusions | `provisionDepositSourceInventory` / `applyExclusionsToInventory` | depositSourceProvisioning.test, asset-packs-synthesis.test | ✅ |
 | 24 | deposit provisions full checkout via Host | deposit route + `InlineHost` path | depositSynthesizeOptionsRoute.test | ✅ |
-| 25 | SandboxHost IN-BOX deposit dispatch (run the pipeline in the box) | harness deposit mode (`synthesizeMode` + steering → in-box runner; `depositOptions` in evidence) + `runDepositInBoxHarness` + route hostKind branch | asset-pack-harness.test, depositSourceProvisioning.test, depositSynthesizeOptionsRoute.test | ✅* |
+| 25 | SandboxHost IN-BOX deposit dispatch (run the pipeline in the box) | harness deposit mode (`synthesizeMode` + steering → in-box runner; `depositOptions` in evidence) + `runDepositInBoxHarness` + route hostKind branch; ephemeral `persistent:false`; OIDC/token auth fail-closed | asset-pack-harness.test, depositSourceProvisioning.test, depositSynthesizeOptionsRoute.test, vercel-sandbox-host.test | ✅* |
+| 26 | Cooperative run cancel | `POST /api/executions/[runId]/cancel` + `execution-cancel.ts` + deposit route polls + sandbox `shouldAbort` + UI Cancel run + `deposit_synthesis_cancelled` analytics | executionCancelRoute.test, vercel-sandbox-host.test (abort), depositPageClient (cancel control) | ✅ |
+| 27 | Run configuration locked above telemetry in run detail | `DepositPageClient` config above telemetry; `disabled` when `synthesisRunId` set | depositPageClient.test | ✅ |
+| 28 | Formal absolutes fail-closed (no placeholder catalog fallback) | `validateDepositSynthesisOptions` requires `absolutes[]` | agent-measure-absolutes.test, asset-packs-synthesis.test | ✅ |
+| 29 | Map-tree LLM token rollup | `sumLlmTokensFromExecutionTree` | asset-packs-synthesis-pipeline.test | ✅ |
+| 30 | Full deposit SDIVF integration under test (boundary LLM mock) | `BITCODE_ENABLE_ASSET_PACK_SDIVF_RUNTIME_IN_TEST` + deposit-sdivf-pipeline-integration.test | deposit-sdivf-pipeline-integration.test | ✅ |
+| 31 | Deposit implementation agent key (telemetry clarity) | `implementation:deposit-asset-pack-synthesis` | synthesize-asset-packs-phase-rosters.test | ✅ |
 
 ✅* = wired + unit-tested with a mocked host (harness plan-building, the dispatch, the
 option projection); real in-sandbox execution is verified against deployed sandbox infra.
 
 **Open items for full gate-3 depositing closure (deployment + verification, not code):**
 - **Deployment config**: the Vercel sandbox provider's runtime deps (`@vercel/sandbox`,
-  `VERCEL_*`, git in the box image); the AWS provider (#20) beyond the stub.
+  OIDC or `VERCEL_TOKEN`+team+project, git in the box image); set
+  `BITCODE_PIPELINE_HOST=sandbox` on prod for durable in-box runs; the AWS provider
+  (#20) beyond the stub.
 - **Live verification**: a real deposit run — on the InlineHost (in-process) and on the
-  SandboxHost (in-box) — confirming measured sizes + the decision panel end-to-end and
-  that both hosts produce the same deposit option synthesis.
+  SandboxHost (in-box) — confirming measured sizes + the decision panel end-to-end,
+  that both hosts produce the same deposit option synthesis, and that Cancel run stops
+  a live sandbox (Observability → Sandboxes).
 
 ## Non-goals during V48 opening
 

BITCODE_V48_QA.md

@@ -635,14 +635,23 @@ cd uapi && pnpm exec jest depositSourceProvisioning depositSynthesizeOptionsRout
 
 **5. #25 SandboxHost in-box dispatch (deployment-conditional)**
 - Local default is inline. To exercise the sandbox path: `BITCODE_PIPELINE_HOST=sandbox`
-  + `BITCODE_SANDBOX_PROVIDER=vercel` + the sandbox infra (`@vercel/sandbox`, `VERCEL_OIDC_TOKEN`
-  or `VERCEL_TOKEN`/`VERCEL_TEAM_ID`/`VERCEL_PROJECT_ID`, git in the box image).
+  + sandbox auth (`VERCEL_OIDC_TOKEN` via `vercel env pull`, or
+  `VERCEL_TOKEN`/`VERCEL_TEAM_ID`/`VERCEL_PROJECT_ID`) + `@vercel/sandbox` + git in the box image.
+  Missing auth must fail closed with a clear message (not a silent hang).
+- Deposit boxes are **non-persistent** (`persistent: false` — no snapshot billing).
 - Log: `Dispatching deposit synthesis to the sandbox host (in-box) for {repo}@{ref}…` then
   `sandbox: sandbox-create-started` / `sandbox-created` / `command-started` / … / `sandbox-stopped`.
-- PASS: the box clones + runs the deposit SDIVF in-box; `evidence.depositOptions` returns;
-  the SAME deposit option synthesis persists as an inline run of the same repo/revision
-  (modulo run-to-run LLM variance). If the sandbox infra isn't deployed, mark N/A — this is
-  the single deployment-pending item.
+  On create, `executions.context.sandboxId` must be set while status is still `running`.
+- PASS: the box clones + runs the deposit SDIVF in-box; `evidence.depositOptions` returns with
+  formal absolutes; the SAME deposit option synthesis persists as an inline run of the same
+  repo/revision (modulo run-to-run LLM variance). If the sandbox infra isn't deployed, mark N/A.
+
+**5b. #26 Cooperative cancel**
+- Start a synthesis (inline or sandbox). While Telemetry shows **Cancel run**, click it.
+- PASS: `POST /api/executions/<runId>/cancel` → 200; row `status=cancelled`; UI Cancelled badge;
+  background does not flip the row to `failed`; sandbox path stops the box (Observability →
+  Sandboxes, or `sandbox: sandbox-cancelled` / `sandbox-stopped` status lines). Completing a
+  run that finished before cancel must remain `completed` (409 not_running on cancel).
 
 **6. QA record** (fill per run)
 
@@ -657,6 +666,7 @@ cd uapi && pnpm exec jest depositSourceProvisioning depositSynthesizeOptionsRout
 | Source-safety — no leak | | | |
 | Automated baseline green | | | |
 | #25 sandbox in-box (or N/A) | | | |
+| #26 cancel run | | | |
 
 **Pulling a run's persisted output** (for the COPY targets) — Supabase SQL editor:
 ```sql

packages/pipeline-hosts/src/__tests__/vercel-sandbox-host.test.ts

@@ -69,6 +69,53 @@ class DetachedFakeSandbox extends FakeSandbox {
 }
 
 describe('VercelSandboxPipelineHost', () => {
+  it('aborts a detached poll when shouldAbort becomes true and returns cancelled', async () => {
+    let polls = 0;
+    class NeverExitSandbox extends DetachedFakeSandbox {
+      async readFileToBuffer(file: { path: string }): Promise<Buffer | null> {
+        // Never produce an exit code so the poll continues until shouldAbort.
+        if (file.path.includes('exit')) return null;
+        return super.readFileToBuffer(file);
+      }
+    }
+    const fakeSandbox = new NeverExitSandbox();
+    const host = new VercelSandboxPipelineHost({
+      sandboxFactory: {
+        create: async () => fakeSandbox,
+      },
+      shouldAbort: async () => {
+        polls += 1;
+        return polls >= 2;
+      },
+    });
+    const plan = buildAssetPackSandboxHarness({
+      read: { id: 'read-1', prompt: 'Read.' },
+      deposit: { id: 'deposit-1' },
+      sourceRevision: {
+        repositoryFullName: 'engineeredsoftware/ENGI',
+        branch: 'main',
+        commit: '31bbc0c5227b6b3aed5d107fd8507d35ec22970a',
+      },
+    });
+    plan.commands = [
+      {
+        label: 'detached-run',
+        cmd: 'sh',
+        args: ['-lc', 'long command'],
+        detached: true,
+        exitCodePath: '.bitcode/pipeline-harness/pipeline.exit-code',
+        stdoutPath: '.bitcode/pipeline-harness/pipeline.stdout.log',
+        stderrPath: '.bitcode/pipeline-harness/pipeline.stderr.log',
+        pollIntervalMs: 5,
+        maxWaitMs: 5_000,
+      },
+    ];
+
+    const result = await host.runHarness(plan);
+    expect(result.outcome).toBe('cancelled');
+    expect(fakeSandbox.stopped).toBe(true);
+  });
+
   it('creates the sandbox, writes harness files, runs commands, reads artifacts, and stops', async () => {
     const fakeSandbox = new FakeSandbox();
     const createOptions: SandboxCreateOptions[] = [];

packages/pipeline-hosts/src/asset-pack-harness.ts

@@ -53,6 +53,11 @@ export interface BuildAssetPackSandboxHarnessOptions {
     protectedIpExclusions?: string[];
     demandContext?: string[];
   };
+  /**
+   * When false, create a non-persistent (ephemeral) sandbox — no snapshot on stop.
+   * Deposit one-shot synthesis defaults to false when synthesizeMode is deposit.
+   */
+  persistent?: boolean;
 }
 
 export function buildAssetPackSandboxHarness(
@@ -113,6 +118,13 @@ export function buildAssetPackSandboxHarness(
       timeout: options.timeoutMs ?? DEFAULT_LONG_TIMEOUT_MS,
       networkPolicy: options.networkPolicy ?? 'allow-all',
       source: options.source,
+      // Deposit one-shots are ephemeral; read/QA harness may opt into persistence.
+      persistent:
+        typeof options.persistent === 'boolean'
+          ? options.persistent
+          : options.synthesizeMode === 'deposit'
+            ? false
+            : undefined,
     },
     manifest,
     files: [

packages/pipeline-hosts/src/types.ts

@@ -169,6 +169,13 @@ export interface SandboxCreateOptions {
   teamId?: string;
   projectId?: string;
   token?: string;
+  /**
+   * When false, the sandbox is ephemeral (no snapshot storage on stop).
+   * Deposit one-shot synthesis should prefer non-persistent boxes.
+   */
+  persistent?: boolean;
+  /** Optional stable name for Sandbox.get / resume (unique per project). */
+  name?: string;
 }
 
 export interface PipelineHarnessFile {
@@ -247,6 +254,14 @@ export interface SandboxSession {
 
 export interface SandboxFactory {
   create(options: SandboxCreateOptions): Promise<SandboxSession>;
+  /** Optional: resume/stop an existing sandbox by id or name (SDK-dependent). */
+  get?(options: {
+    sandboxId?: string;
+    name?: string;
+    teamId?: string;
+    projectId?: string;
+    token?: string;
+  }): Promise<SandboxSession>;
 }
 
 export type PipelineHarnessHostEvent =
@@ -262,6 +277,12 @@ export type PipelineHarnessHostEvent =
       sandboxId?: string;
       status?: string;
     }
+  | {
+      type: 'sandbox-cancelled';
+      timestamp: string;
+      sandboxId?: string;
+      reason?: string;
+    }
   | {
       type: 'harness-files-written';
       timestamp: string;
@@ -326,6 +347,6 @@ export interface PipelineHarnessRunResult {
     evidence: unknown | null;
     telemetry: string | null;
   };
-  outcome: 'completed' | 'failed';
+  outcome: 'completed' | 'failed' | 'cancelled';
   stopped: boolean;
 }