@pome-sh/cli 0.8.0 → 0.10.0

package/dist/src/cli/main.js

@@ -17,6 +17,8 @@ import { loginWithClerk } from "./login.js";
 import { runDocsCommand } from "./docs.js";
 import { runCompileSeeds } from "./compile-seeds.js";
 import { runTasksCommand } from "./tasks.js";
+import { runChecksCommand } from "./checks.js";
+import { runChecksAddCommand } from "./checks-add.js";
 import { runEvalCommand } from "./eval.js";
 import { copyAnnounceLine, ensureDefaultTask, runYoursFrameLines, trialsPinFallbackLine, } from "./default-task.js";
 import { findTwin, runnableTasks, } from "./tasks-catalog.js";
@@ -245,6 +247,32 @@ export function createProgram() {
     };
     registerTasksCommand("tasks", false);
     registerTasksCommand("scenarios", true);
+    // F-1074 — `pome checks` is a TOP-LEVEL group, not `pome tasks checks`:
+    // `pome tasks` already takes `[twin]` positionally, so `tasks checks` would
+    // parse "checks" as a twin id, and `pome task` one letter from `pome tasks`
+    // is a trap.
+    const checks = program
+        .command("checks")
+        .argument("[twin]", "Twin id (e.g. github). Omit to list twins that declare checks.")
+        .option("--json", "Emit the declaration as JSON (for skills and agents).", false)
+        .description("Browse the typed checks a twin declares — the closed set [code] criteria come from")
+        .action(async (twin, opts) => {
+        await runChecksCommand(twin, { json: opts.json });
+    });
+    checks
+        .command("add")
+        .argument("<file>", "Task markdown file to append a criterion to")
+        .option("--check <id>", "Check id (run `pome checks <twin>` to list them)")
+        .option("--arg <key=value>", "One per declared parameter. Repeat the flag.", (value, previous = []) => [...previous, value], [])
+        .option("--api-url <url>", "Control-plane URL", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
+        .description("Add one [code] criterion by picking a declared check — pome writes the English")
+        .action(async (file, opts) => {
+        await runChecksAddCommand(file, {
+            check: opts.check,
+            arg: opts.arg,
+            apiBaseUrl: opts.apiUrl,
+        });
+    });
     program
         .command("compile-seeds")
         .argument("[target]", "Task .md file or directory (defaults to ./tasks)")
@@ -272,7 +300,7 @@ export function createProgram() {
         .argument("<name>", "Human-readable agent name (e.g. \"triage-bot\")")
         .option("--api-url <url>", "Control-plane URL", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
         .option("--force", "Re-resolve the agent even when .pome/link.json already links one", false)
-        .option("--twins <list>", "Comma-separated services this agent may exercise (e.g. github,slack). Default: the cloud's default enablement.")
+        .option("--twins <list>", "Comma-separated services this agent may exercise (e.g. github,slack), unioned with the manifest's twins. Default: the manifest's twins, else the cloud's default enablement.")
         .description("Create a cloud agent under the current team and write agent.slug to pome.json")
         .action(async (name, opts) => {
         try {
@@ -360,12 +388,22 @@ export function createProgram() {
         .description("Stop a hosted session (aliased as `kill`)")
         .argument("<session-id>", "Session id (ses_…)")
         .option("--api-url <url>", "Control-plane URL", process.env.POME_API_URL ?? DEFAULT_CONTROL_PLANE_URL)
+        .option("--discard", "Confirm destroying a session whose run has not been graded (F-983)", false)
         .action(async (sessionId, opts) => {
         try {
-            await runSessionStop({ apiBaseUrl: opts.apiUrl, sessionId });
+            await runSessionStop({
+                apiBaseUrl: opts.apiUrl,
+                sessionId,
+                discard: opts.discard === true,
+            });
         }
         catch (err) {
-            console.error(friendlyHostedError(err));
+            // runSessionStop already prints the full refusal detail for
+            // HostedDiscardRefusedError; friendlyHostedError returns "" for it
+            // so we don't print a duplicate (or bare blank) line here.
+            const friendly = friendlyHostedError(err);
+            if (friendly)
+                console.error(friendly);
             process.exitCode = 2;
         }
     });
@@ -558,7 +596,7 @@ export function createProgram() {
                 // documented exit codes. Anything else falls through to Commander
                 // (treated like self-host).
                 try {
-                    // FDRS-636 — effective trial count: -n wins, else the scenario
+                    // FDRS-636 — effective trial count: -n wins, else the task
                     // config's `runs` field (both capped at 20). k>1 takes the
                     // trial-group path; k=1 stays EXACTLY the single-run path
                     // below (no group is ever stamped for it).
@@ -769,7 +807,7 @@ export function createProgram() {
         .argument("[task]", "Path to the task .md file (only with an events.jsonl target)")
         .description("Assemble a paste-into-IDE fix prompt (no LLM call, no network). With no args, reads the latest FAILED run set under ./runs: the persisted cloud verdicts (verdict.json) become grouped failure signatures over the raw traces, in one prompt. Point it at a trial run dir to target that set, or use the legacy `<events.jsonl> <task.md>` form for a single trace.")
         .action(async (target, taskArg) => {
-        // Legacy 2-arg form: <events.jsonl> <scenario.md> — unchanged
+        // Legacy 2-arg form: <events.jsonl> <task.md> — unchanged
         // (CAPTURE-ONLY, FDRS-657: raw trace + declared criteria, no verdict).
         if (target !== undefined && target.endsWith(".jsonl")) {
             if (!taskArg) {
@@ -777,7 +815,7 @@ export function createProgram() {
                 process.exitCode = 5;
                 return;
             }
-            const [eventsRaw, scenario] = await Promise.all([
+            const [eventsRaw, task] = await Promise.all([
                 readFile(resolve(target), "utf8"),
                 parseTaskFile(resolve(taskArg)),
             ]);
@@ -786,7 +824,7 @@ export function createProgram() {
                 .map((line) => line.trim())
                 .filter((line) => line.length > 0)
                 .map((line) => JSON.parse(line));
-            console.log(buildFixPrompt({ events, scenario }));
+            console.log(buildFixPrompt({ events, task }));
             return;
         }
         if (taskArg !== undefined) {
@@ -810,14 +848,14 @@ export function createProgram() {
             return;
         }
         const set = discovery.set;
-        let scenario = null;
+        let task = null;
         try {
-            scenario = await parseTaskFile(resolve(set.taskPath));
+            task = await parseTaskFile(resolve(set.taskPath));
         }
         catch {
             // Task file moved/edited since the run — the prompt degrades to the
             // verdict-embedded criteria.
-            scenario = null;
+            task = null;
         }
         const trials = [];
         for (const [idx, t] of set.trials.entries()) {
@@ -831,7 +869,7 @@ export function createProgram() {
         console.log(buildGroupFixPrompt({
             taskName: set.taskName,
             groupId: set.groupId,
-            scenario,
+            task,
             trials,
         }));
     });

package/dist/src/cli/project-config.d.ts

@@ -27,3 +27,11 @@ export declare function readRequiredManifest(startDir?: string): Promise<Manifes
  *  pretty-printed with a trailing newline; YAML carries the schema pointer as a
  *  language-server comment (the `$schema` key is dropped from the YAML body). */
 export declare function writeManifest(path: string, format: ManifestFormat, data: Record<string, unknown>): Promise<void>;
+/** Normalize the manifest's `twins` to canonical (trim + lowercase, de-duped)
+ *  twin ids for the `POST /v1/agents` body. The manifest schema keeps `twins`
+ *  open (min(1) strings, not checked against MOUNTED_TWINS), so entries are
+ *  normalized but NOT validated here — the server returns a friendly error for
+ *  an unknown twin. Returns undefined when nothing survives so the cloud's
+ *  default enablement still applies. Shared by the register command and the
+ *  run-path identity resolver (F-926). */
+export declare function normalizeManifestTwins(manifestTwins: readonly string[] | undefined): string[] | undefined;

package/dist/src/cli/project-config.js

@@ -114,6 +114,24 @@ function slugErrorMessage(raw, path) {
     const base = `Invalid agent.slug in ${path}: must match ${SLUG_RE} (lowercase kebab-case, max 64 chars).`;
     return suggestion.length > 0 ? `${base} Did you mean "${suggestion}"?` : base;
 }
+/** Normalize the manifest's `twins` to canonical (trim + lowercase, de-duped)
+ *  twin ids for the `POST /v1/agents` body. The manifest schema keeps `twins`
+ *  open (min(1) strings, not checked against MOUNTED_TWINS), so entries are
+ *  normalized but NOT validated here — the server returns a friendly error for
+ *  an unknown twin. Returns undefined when nothing survives so the cloud's
+ *  default enablement still applies. Shared by the register command and the
+ *  run-path identity resolver (F-926). */
+export function normalizeManifestTwins(manifestTwins) {
+    if (manifestTwins === undefined)
+        return undefined;
+    const out = new Set();
+    for (const twin of manifestTwins) {
+        const norm = twin.trim().toLowerCase();
+        if (norm.length > 0)
+            out.add(norm);
+    }
+    return out.size > 0 ? [...out] : undefined;
+}
 async function fileExists(path) {
     try {
         await readFile(path, "utf8");

package/dist/src/cli/register.d.ts

@@ -14,5 +14,20 @@ interface RegisterAgentOptions extends InteractiveSeams {
 }
 /** Normalize a `--twins github,slack` comma list to a validated twin array. */
 export declare function normalizeRegisterTwins(raw: string | undefined): string[] | undefined;
+/** Effective register twins = the manifest's declared `twins` (the default twin
+ *  set for runs) unioned with any `--twins` flag additions (F-926). Before this,
+ *  the CLI sent only the flag, so a manifest like `twins: ["gmail"]` never
+ *  reached `POST /v1/agents` and the server's `github` default won — the first
+ *  `pome run` then errored with "Requested twins are not enabled".
+ *
+ *  Union is the correct client shape because the server merges additively (never
+ *  removes), so there is no "reduce" semantics to preserve; sending more is
+ *  always safe. Manifest entries are normalized (trim + lowercase) to match the
+ *  flag path and the canonical lowercase twin ids; they are intentionally NOT
+ *  validated against MOUNTED_TWINS here (the manifest schema keeps `twins` open,
+ *  and the server returns a friendly error for an unknown twin). Returns
+ *  undefined when neither source contributes so the cloud's default enablement
+ *  still applies. */
+export declare function mergeRegisterTwins(manifestTwins: readonly string[] | undefined, flagTwins: readonly string[] | undefined): string[] | undefined;
 export declare function runRegisterAgent(opts: RegisterAgentOptions): Promise<void>;
 export { friendlyHostedError };

package/dist/src/cli/register.js

@@ -19,7 +19,7 @@ import { postAgentResolver, resolveSeams, } from "./agent-resolver.js";
 import { resolveCredentials } from "./credentials.js";
 import { suggestFramework } from "./frameworks.js";
 import { ensurePomeGitignored, readLinkCache, resolveCachedAgentId, writeLinkCache, } from "./link-cache.js";
-import { readRequiredManifest, writeManifest, } from "./project-config.js";
+import { normalizeManifestTwins, readRequiredManifest, writeManifest, } from "./project-config.js";
 import { friendlyHostedError } from "./session.js";
 const SCHEMA_URL = "https://pome.sh/schemas/v1/pome.json";
 /** Normalize a `--twins github,slack` comma list to a validated twin array. */
@@ -39,6 +39,26 @@ export function normalizeRegisterTwins(raw) {
     }
     return [...new Set(twins)];
 }
+/** Effective register twins = the manifest's declared `twins` (the default twin
+ *  set for runs) unioned with any `--twins` flag additions (F-926). Before this,
+ *  the CLI sent only the flag, so a manifest like `twins: ["gmail"]` never
+ *  reached `POST /v1/agents` and the server's `github` default won — the first
+ *  `pome run` then errored with "Requested twins are not enabled".
+ *
+ *  Union is the correct client shape because the server merges additively (never
+ *  removes), so there is no "reduce" semantics to preserve; sending more is
+ *  always safe. Manifest entries are normalized (trim + lowercase) to match the
+ *  flag path and the canonical lowercase twin ids; they are intentionally NOT
+ *  validated against MOUNTED_TWINS here (the manifest schema keeps `twins` open,
+ *  and the server returns a friendly error for an unknown twin). Returns
+ *  undefined when neither source contributes so the cloud's default enablement
+ *  still applies. */
+export function mergeRegisterTwins(manifestTwins, flagTwins) {
+    const merged = new Set(normalizeManifestTwins(manifestTwins) ?? []);
+    for (const twin of flagTwins ?? [])
+        merged.add(twin);
+    return merged.size > 0 ? [...merged] : undefined;
+}
 // ── Persist: manifest + link cache + gitignore ──────────────────────────────
 /** Read the manifest's existing agent block (for round-trip preservation and
  *  did-you-mean input) without forcing schema defaults. */
@@ -141,12 +161,15 @@ export async function runRegisterAgent(opts) {
             return;
         }
     }
+    // Send the manifest's declared twins (unioned with any --twins flag) so the
+    // cloud's enabled services match the manifest, not the server default (F-926).
+    const twins = mergeRegisterTwins(manifestRead.manifest.twins, opts.twins);
     const agent = await createAndPersistAgent({
         creds,
         name: opts.name,
         manifestRead,
         projectDir,
-        twins: opts.twins,
+        twins,
         seams: resolveSeams(opts),
     });
     const displayName = stripControlCharacters(agent.display_name);
@@ -156,7 +179,7 @@ export async function runRegisterAgent(opts) {
     if (agent.enabled_services !== undefined) {
         console.error(`Enabled services: ${agent.enabled_services.length > 0 ? agent.enabled_services.join(", ") : "(none)"}.`);
     }
-    else if (opts.twins && opts.twins.length > 0) {
+    else if (twins && twins.length > 0) {
         console.error("Enabled services: not reported by this pome cloud (older control plane) — twin scoping may not have taken effect.");
     }
     // Deep-link the registered agent's dashboard page. `/agents/<slug>` is the

package/dist/src/cli/session.d.ts

@@ -21,5 +21,15 @@ export declare function runSessionList(opts: {
 export declare function runSessionStop(opts: {
     apiBaseUrl: string;
     sessionId: string;
+    /** F-983: confirm destroying a session whose run has not been graded.
+     *  Off by default — a human-typed destructive command gets the refusal
+     *  printed instead of silently discarding the evidence. */
+    discard?: boolean;
 }): Promise<void>;
+/** Empty string means "already fully reported — print nothing more". Only
+ *  `HostedDiscardRefusedError` returns it today: `runSessionStop` above just
+ *  printed the complete multi-line refusal (session, task, open time, the
+ *  `--discard` escape hatch), so falling through to `err.message` here would
+ *  either duplicate that or, when the server omits `error.message`, print a
+ *  bare blank line. Callers must skip printing when this returns "". */
 export declare function friendlyHostedError(err: unknown): string;

package/dist/src/cli/session.js

@@ -4,7 +4,7 @@ import { chmod, mkdir, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { MOUNTED_TWINS } from "@pome-sh/shared-types";
 import { createHostedClient, perTwinReturnedByCloud } from "../hosted/client.js";
-import { HostedAuthError, HostedOrchError, HostedQuotaError, } from "../hosted/errors.js";
+import { HostedAuthError, HostedDiscardRefusedError, HostedOrchError, HostedQuotaError, } from "../hosted/errors.js";
 import { resolveRunAgentIdentity } from "./agent-identity.js";
 import { resolveCredentials } from "./credentials.js";
 import { DEFAULT_DASHBOARD_URL } from "./defaults.js";
@@ -242,10 +242,36 @@ export async function runSessionStop(opts) {
         baseUrl: creds.apiBaseUrl,
         apiKey: creds.apiKey,
     });
-    await client.deleteSession(opts.sessionId, false);
+    try {
+        await client.deleteSession(opts.sessionId, false, {
+            discard: opts.discard === true,
+        });
+    }
+    catch (err) {
+        if (err instanceof HostedDiscardRefusedError) {
+            console.error(`Refused to stop ${err.sessionId}: it is still open (${err.state}), so its ` +
+                `run has not been graded — Pome creates the run row at finalize, and ` +
+                `stopping now discards it.`);
+            if (err.taskName)
+                console.error(`  Task: ${err.taskName}`);
+            console.error(`  Open for ${err.openSeconds}s.`);
+            console.error(`  To keep the run, finalize it instead. To discard it anyway: ` +
+                `pome session stop ${err.sessionId} --discard`);
+        }
+        throw err;
+    }
     console.error(`Stopped session ${opts.sessionId}.`);
 }
+/** Empty string means "already fully reported — print nothing more". Only
+ *  `HostedDiscardRefusedError` returns it today: `runSessionStop` above just
+ *  printed the complete multi-line refusal (session, task, open time, the
+ *  `--discard` escape hatch), so falling through to `err.message` here would
+ *  either duplicate that or, when the server omits `error.message`, print a
+ *  bare blank line. Callers must skip printing when this returns "". */
 export function friendlyHostedError(err) {
+    if (err instanceof HostedDiscardRefusedError) {
+        return "";
+    }
     if (err instanceof HostedAuthError) {
         return `${err.message} · Run \`pome login\` or set a valid POME_API_KEY.`;
     }

package/dist/src/fix-prompt/index.d.ts

@@ -1,6 +1,6 @@
 import { type FixPromptContext, type GroupFixPromptContext } from "./prompt.js";
 /**
- * Build the paste-into-IDE fix prompt from the raw trace + the scenario's
+ * Build the paste-into-IDE fix prompt from the raw trace + the task's
  * criteria. PURE + synchronous — no network, no LLM, no local judge.
  *
  * The output is a complete prompt: the system instructions (how to write the

package/dist/src/fix-prompt/index.js

@@ -4,11 +4,11 @@
 // (FDRS-657). CAPTURE-ONLY: no LLM/judge call happens here. The former BYOK
 // CLI-side judge call (`callJudge`) that generated the handoff was removed;
 // this now returns the fully-assembled prompt (system instructions + the
-// scenario's criteria + the captured trace) for the developer to paste into
+// task's criteria + the captured trace) for the developer to paste into
 // their own coding assistant.
 import { FIX_PROMPT_SYSTEM_PROMPT, buildFixUserPrompt, buildGroupFixUserPrompt, } from "./prompt.js";
 /**
- * Build the paste-into-IDE fix prompt from the raw trace + the scenario's
+ * Build the paste-into-IDE fix prompt from the raw trace + the task's
  * criteria. PURE + synchronous — no network, no LLM, no local judge.
  *
  * The output is a complete prompt: the system instructions (how to write the

package/dist/src/fix-prompt/prompt.d.ts

@@ -6,7 +6,7 @@ export declare const FIX_PROMPT_SYSTEM_PROMPT: string;
 export declare function escapeTagContent(text: string): string;
 export interface FixPromptContext {
     events: RecorderEvent[];
-    scenario: Task;
+    task: Task;
 }
 export declare function buildFixUserPrompt(ctx: FixPromptContext): string;
 export interface TrialFixInput {
@@ -22,7 +22,7 @@ export interface GroupFixPromptContext {
     groupId: string | null;
     /** Parsed task file when it still resolves. Null degrades the prompt to
      *  the verdict-embedded criteria (the file may have moved since the run). */
-    scenario: Task | null;
+    task: Task | null;
     /** Completed trials of the run set (verdict.json present), run order. */
     trials: TrialFixInput[];
 }

package/dist/src/fix-prompt/prompt.js

@@ -3,7 +3,7 @@
 // Assembles the paste-into-IDE fix prompt for a failed run (FDRS-657).
 //
 // CAPTURE-ONLY: the OSS CLI does NOT call an LLM here. `pome fix-prompt`
-// assembles a self-contained prompt — system instructions + the scenario's
+// assembles a self-contained prompt — system instructions + the task's
 // criteria + the raw captured trace — and prints it so the developer can paste
 // it into THEIR own coding assistant (Cursor / Claude Code). The former BYOK
 // local-judge call that generated the handoff CLI-side was removed under
@@ -87,10 +87,10 @@ function renderCriteria(criteria) {
         .join("\n");
 }
 export function buildFixUserPrompt(ctx) {
-    const criteria = redactSecrets(renderCriteria(ctx.scenario.criteria));
+    const criteria = redactSecrets(renderCriteria(ctx.task.criteria));
     const trace = renderEvents(ctx.events.map((event) => redactEvent(event)));
-    const taskTitle = redactSecrets(ctx.scenario.title);
-    const taskPrompt = redactSecrets(ctx.scenario.prompt);
+    const taskTitle = redactSecrets(ctx.task.title);
+    const taskPrompt = redactSecrets(ctx.task.prompt);
     return `## Task
 ${taskTitle}
 
@@ -192,15 +192,15 @@ export function buildGroupFixUserPrompt(ctx) {
     const representative = representativeFailingTrial(ctx.trials);
     const otherFailing = ctx.trials.filter((t) => !t.verdict.passed && t !== representative);
     const signatures = redactSecrets(renderGroupedSignatures(ctx.trials));
-    const criteriaBlock = ctx.scenario
-        ? redactSecrets(renderCriteria(ctx.scenario.criteria))
+    const criteriaBlock = ctx.task
+        ? redactSecrets(renderCriteria(ctx.task.criteria))
         : redactSecrets(renderCriteria((ctx.trials[0]?.verdict.criteria_results ?? []).map((r) => ({
             type: r.criterion.type,
             text: r.criterion.text,
         }))));
-    const promptBlock = ctx.scenario
-        ? redactSecrets(ctx.scenario.prompt)
-        : `(task file not found at ${ctx.trials[0]?.verdict.scenario_path ?? "?"} — criteria above come from the cloud verdicts)`;
+    const promptBlock = ctx.task
+        ? redactSecrets(ctx.task.prompt)
+        : `(task file not found at ${ctx.trials[0]?.verdict.task_path ?? "?"} — criteria above come from the cloud verdicts)`;
     const sections = [];
     sections.push(`## Run set (cloud-judged)
 task ${redactSecrets(ctx.taskName)} · ${ctx.groupId ? `group ${ctx.groupId}` : "single run"} · ${passed} of ${completed} completed trials passed`);

package/dist/src/hosted/client.d.ts

@@ -197,7 +197,13 @@ export interface HostedClient {
      *  for the feature-detection contract (a 404 here means an older control
      *  plane; callers must tolerate it silently). */
     requestMetaUploadUrl(sessionId: string): Promise<MetaUploadUrlResponse>;
-    /** @param bestEffort default true — hosted runner swallows network errors on teardown */
-    deleteSession(sessionId: string, bestEffort?: boolean): Promise<void>;
+    /** @param bestEffort default true — hosted runner swallows network errors on teardown
+     *  @param opts.discard F-983 — set true to confirm discarding an ungraded
+     *  session after catching {@link HostedDiscardRefusedError}. Never implied
+     *  by `bestEffort`: a refusal is a deliberate server decision, not
+     *  transport noise. */
+    deleteSession(sessionId: string, bestEffort?: boolean, opts?: {
+        discard?: boolean;
+    }): Promise<void>;
 }
 export declare function createHostedClient(config: HostedClientConfig): HostedClient;

package/dist/src/hosted/client.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { createEvalSessionResponseSchema, createSessionResponseSchema, finalizeResponseSchema, sessionPublicSchema, submitResultResponseSchema, } from "../types/shared.js";
 import { z } from "zod";
-import { HostedAuthError, HostedOrchError, HostedQuotaError, } from "./errors.js";
+import { HostedAuthError, HostedOrchError, HostedQuotaError, HostedDiscardRefusedError, } from "./errors.js";
 // Multi-twin (M3): provenance marker for `per_twin`. A single-twin OLD cloud
 // ships NO `per_twin` key; `createSessionResponseSchema` then SYNTHESIZES one
 // (host-rewrites api.pome.sh→mcp.pome.sh with no `/mcp` suffix). Consumers that
@@ -98,6 +98,46 @@ class RetryableFinalizeStatusError extends HostedOrchError {
         this.name = "RetryableFinalizeStatusError";
     }
 }
+/** Read a 409 body as an F-983 discard refusal. Only ever called for status
+ *  409 — a non-409 that happens to echo `details.reason` is a server error,
+ *  not a refusal, and must keep its own status-based handling. */
+async function readDiscardRefusal(res) {
+    let body;
+    try {
+        body = await res.clone().json();
+    }
+    catch {
+        return { kind: "none" };
+    }
+    const error = body?.error;
+    const details = error?.details;
+    if (!details || details.reason !== "ungraded_session")
+        return { kind: "none" };
+    const discardToken = details.discard_token;
+    if (typeof discardToken !== "string" || discardToken.length === 0) {
+        return { kind: "unusable" };
+    }
+    return {
+        kind: "refusal",
+        refusal: {
+            message: typeof error?.message === "string" ? error.message : "",
+            sessionId: typeof details.session_id === "string" ? details.session_id : "",
+            state: typeof details.state === "string" ? details.state : "open",
+            taskName: typeof details.task_name === "string" ? details.task_name : null,
+            openSeconds: typeof details.open_seconds === "number" ? details.open_seconds : 0,
+            discardToken,
+        },
+    };
+}
+/** The delete was refused but the refusal is unreplayable. Say plainly that
+ *  the session is still running: a best-effort caller would otherwise read
+ *  silence as success. NOT HostedDiscardRefusedError — with no token to
+ *  replay, that type would be a lie. */
+function unusableRefusalError(sessionId) {
+    return new HostedOrchError(`DELETE /v1/sessions/${sessionId} → 409: the server refused to delete this ` +
+        `session but sent no usable discard_token, so the session was NOT ` +
+        `stopped. Retry, or stop it from the dashboard.`, undefined, 409);
+}
 export function createHostedClient(config) {
     const timeoutMs = config.timeoutMs ?? 30_000;
     const finalizeTimeoutMs = config.finalizeTimeoutMs ?? 5 * 60_000;
@@ -590,33 +630,75 @@ export function createHostedClient(config) {
                 state_final_json_b64: Buffer.from(input.stateFinalJson, "utf8").toString("base64"),
             }, (raw) => submitResultResponseSchema.parse(raw));
         },
-        async deleteSession(sessionId, bestEffort = true) {
-            const ctrl = new AbortController();
-            const timer = setTimeout(() => ctrl.abort(), timeoutMs);
-            let res;
-            try {
-                res = await fetch(`${config.baseUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
-                    method: "DELETE",
-                    // authHeaders, not a hardcoded x-api-key: demo teardown carries a
-                    // bearer demo_token (FDRS-643 live-run finding — the hardcoded
-                    // header made every demo DELETE an opaque 404, silently swallowed
-                    // by best-effort).
-                    headers: authHeaders,
-                    signal: ctrl.signal,
-                });
-            }
-            catch (err) {
-                if (bestEffort)
+        async deleteSession(sessionId, bestEffort = true, opts = {}) {
+            // One DELETE attempt, including the read of a 409 body. `confirmDiscard`
+            // replays the token the control plane hands back with an F-983 refusal.
+            const attempt = async (confirmDiscard) => {
+                const ctrl = new AbortController();
+                const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+                const qs = confirmDiscard
+                    ? `?confirm_discard=${encodeURIComponent(confirmDiscard)}`
+                    : "";
+                try {
+                    const res = await fetch(`${config.baseUrl}/v1/sessions/${encodeURIComponent(sessionId)}${qs}`, {
+                        method: "DELETE",
+                        // authHeaders, not a hardcoded x-api-key: demo teardown carries a
+                        // bearer demo_token (FDRS-643 live-run finding — the hardcoded
+                        // header made every demo DELETE an opaque 404, silently swallowed
+                        // by best-effort).
+                        headers: authHeaders,
+                        signal: ctrl.signal,
+                    });
+                    // Keep the timeout active while consuming a 409 body — fetch()
+                    // resolves after headers, before the body finishes (same hazard,
+                    // same fix, as postJson's readResponse above).
+                    const read = res.status === 409
+                        ? await readDiscardRefusal(res)
+                        : { kind: "none" };
+                    return { res, read };
+                }
+                catch (err) {
+                    if (bestEffort)
+                        return null;
+                    throw new HostedOrchError(err instanceof Error ? err.message : "network error");
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            };
+            let first = await attempt();
+            if (!first)
+                return; // bestEffort transport failure
+            let res = first.res;
+            // F-983: a 409 carrying reason=ungraded_session is a REFUSAL, not the
+            // already-closed race. Never fold it into the idempotent-success branch
+            // below — that swallow is exactly what made the CLI lie about stopping.
+            // Scoped to 409: a 5xx that echoes the same `details` is a server
+            // error and keeps its status-based handling.
+            if (first.read.kind === "unusable")
+                throw unusableRefusalError(sessionId);
+            if (first.read.kind === "refusal") {
+                const { refusal } = first.read;
+                if (!opts.discard) {
+                    throw new HostedDiscardRefusedError(refusal.message, refusal.sessionId || sessionId, refusal.state, refusal.taskName, refusal.openSeconds, refusal.discardToken);
+                }
+                const confirmed = await attempt(refusal.discardToken);
+                if (!confirmed)
                     return;
-                throw new HostedOrchError(err instanceof Error ? err.message : "network error");
-            }
-            finally {
-                clearTimeout(timer);
+                res = confirmed.res;
+                // No third attempt either way: the token was already spent.
+                if (confirmed.read.kind === "unusable") {
+                    throw unusableRefusalError(sessionId);
+                }
+                if (confirmed.read.kind === "refusal") {
+                    const stillRefused = confirmed.read.refusal;
+                    throw new HostedDiscardRefusedError(stillRefused.message, stillRefused.sessionId || sessionId, stillRefused.state, stillRefused.taskName, stillRefused.openSeconds, stillRefused.discardToken);
+                }
             }
             // Cloud spec (pome-cloud docs/05-api-spec.md): 204 on success. Accept
-            // 200 too in case a future control-plane returns a body. 409 keeps
-            // best-effort teardown idempotent when a concurrent reaper already
-            // closed the row.
+            // 200 too in case a future control-plane returns a body. A 409 that is
+            // NOT an F-983 refusal keeps best-effort teardown idempotent when a
+            // concurrent reaper already closed the row.
             if (res.status === 204 || res.status === 200 || res.status === 409)
                 return;
             if (res.status === 404) {
@@ -627,7 +709,7 @@ export function createHostedClient(config) {
             if (res.status === 401 || res.status === 403) {
                 throw new HostedAuthError(`DELETE /v1/sessions/${sessionId} → ${res.status}`);
             }
-            // 404 / 5xx — log via thrown but caller can swallow if mid-teardown.
+            // 5xx — thrown, but caller can swallow if mid-teardown.
             throw new HostedOrchError(`DELETE /v1/sessions/${sessionId} → ${res.status}`);
         },
     };

package/dist/src/hosted/errors.d.ts

@@ -43,4 +43,18 @@ export declare class HostedTrialError extends Error {
     readonly errorCode: string;
     constructor(message: string, errorCode: string);
 }
+/** F-983 — `DELETE /v1/sessions/:id` refused to destroy a session whose run
+ *  has not been graded. Pome creates the `runs` row at finalize, so an open
+ *  session holds an ungraded run and deleting it discards the evidence. The
+ *  control plane issues `discardToken`; replaying it confirms the discard.
+ *  Deliberately NOT swallowed by `bestEffort` — that flag covers transport
+ *  noise and already-closed races, not a deliberate server refusal. */
+export declare class HostedDiscardRefusedError extends Error {
+    readonly sessionId: string;
+    readonly state: string;
+    readonly taskName: string | null;
+    readonly openSeconds: number;
+    readonly discardToken: string;
+    constructor(message: string, sessionId: string, state: string, taskName: string | null, openSeconds: number, discardToken: string);
+}
 export declare function exitCodeFor(err: unknown): number;

package/dist/src/hosted/errors.js

@@ -87,6 +87,28 @@ export class HostedTrialError extends Error {
         this.name = "HostedTrialError";
     }
 }
+/** F-983 — `DELETE /v1/sessions/:id` refused to destroy a session whose run
+ *  has not been graded. Pome creates the `runs` row at finalize, so an open
+ *  session holds an ungraded run and deleting it discards the evidence. The
+ *  control plane issues `discardToken`; replaying it confirms the discard.
+ *  Deliberately NOT swallowed by `bestEffort` — that flag covers transport
+ *  noise and already-closed races, not a deliberate server refusal. */
+export class HostedDiscardRefusedError extends Error {
+    sessionId;
+    state;
+    taskName;
+    openSeconds;
+    discardToken;
+    constructor(message, sessionId, state, taskName, openSeconds, discardToken) {
+        super(message);
+        this.sessionId = sessionId;
+        this.state = state;
+        this.taskName = taskName;
+        this.openSeconds = openSeconds;
+        this.discardToken = discardToken;
+        this.name = "HostedDiscardRefusedError";
+    }
+}
 export function exitCodeFor(err) {
     if (err instanceof HostedAuthError)
         return 3;