@pome-sh/cli 0.7.0 → 0.9.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "package": "pome-sh",
-  "version": "0.7.0",
-  "git_sha": "c07382656e095899efa7d46c96a12830869e9cbb",
-  "build_time": "2026-07-24T16:38:09.759Z"
+  "version": "0.9.0",
+  "git_sha": "2412f1350c8c75dbc179884982228467f4452bf2",
+  "build_time": "2026-07-27T16:54:03.861Z"
 }

package/dist/src/cli/agent-identity.js

@@ -13,7 +13,7 @@ import { dirname } from "node:path";
 import { postAgentResolver, resolveSeams, } from "./agent-resolver.js";
 import { resolveCredentials } from "./credentials.js";
 import { ensurePomeGitignored, readLinkCache, resolveCachedAgentId, writeLinkCache, } from "./link-cache.js";
-import { readManifest } from "./project-config.js";
+import { normalizeManifestTwins, readManifest } from "./project-config.js";
 export async function resolveRunAgentIdentity(input) {
     const manifestRead = await readManifest(input.startDir);
     if (!manifestRead) {
@@ -38,13 +38,18 @@ export async function resolveRunAgentIdentity(input) {
         if (cachedId) {
             return { ...base, agentId: cachedId };
         }
-        // Silent re-resolution — a run never prompts for a near-miss.
+        // Silent re-resolution — a run never prompts for a near-miss. Send the
+        // manifest's twins so a fork / first `pome run` that auto-creates the agent
+        // enables the declared services instead of the server's `github` default
+        // (F-926); the server merges additively, so this is safe when the agent
+        // already exists.
         const resolved = await postAgentResolver(creds, {
             name: agent.name ?? agent.slug,
             slug: agent.slug,
             description: agent.description,
             version: agent.version,
             framework: agent.framework,
+            twins: normalizeManifestTwins(manifestRead.manifest.twins),
         }, resolveSeams({ stdinIsTTY: false }));
         if (creds.teamId) {
             await writeLinkCache(projectDir, { agent_id: resolved.id, team_id: creds.teamId });

package/dist/src/cli/compile-seeds.js

@@ -18,6 +18,17 @@ import { compileSeedHosted } from "../task/seed-compiler-hosted.js";
 import { verifySeedWithTwin } from "../task/seed-verifier.js";
 import { exitCodeFor } from "../hosted/errors.js";
 const SIDECAR_META_VERSION = 1;
+/**
+ * Sidecars written by hand rather than by the compiler mark themselves with
+ * this sentinel. It is a statement of provenance, not a cache state: the seeds
+ * that carry it encode adversarial setups (a backdoored PR, a fabricated green
+ * CI status, an exfiltration lure) that a recompile would quietly rewrite,
+ * changing what the task tests while the run still reports normally. So it
+ * outranks even `--force`; to recompile one, delete the sidecar or drop its
+ * `_meta` first.
+ */
+const HAND_AUTHORED_MARKER = "hand-authored";
+const HAND_AUTHORED_SOURCE_HASH = `sha256:${HAND_AUTHORED_MARKER}`;
 export async function runCompileSeeds(target, opts) {
     const files = await resolveTaskFiles(target ?? "tasks");
     if (files.length === 0) {
@@ -56,15 +67,20 @@ async function compileOne(taskPath, opts) {
     if (seedText.length === 0) {
         return { path: taskPath, status: "skipped-no-seed", message: "no ## Seed State section" };
     }
-    // Stripe scenarios use a different schema; v1 only supports github. Check
-    // twin first so Stripe scenarios are silently skipped without surfacing
-    // misleading "still on inline JSON" warnings.
+    // Other twins use a different schema; v1 only emits a flat github seed. Check
+    // twin first so those tasks are silently skipped without surfacing misleading
+    // "still on inline JSON" warnings.
+    //
+    // A task naming github *alongside* another twin is seeded from a per-twin
+    // envelope (`{ github: {...}, linear: {...} }`), so compiling it would replace
+    // the envelope with a github-only seed and drop the other twin's half.
     const twins = readTwinsFromConfig(markdown);
-    if (twins.length > 0 && !twins.includes("github")) {
+    const githubOnly = twins.length === 1 && twins[0] === "github";
+    if (twins.length > 0 && !githubOnly) {
         return {
             path: taskPath,
             status: "skipped-unsupported-twin",
-            message: `twins=${twins.join(",")} not supported yet`
+            message: `twins=${twins.join(",")} — only single-twin github tasks are supported yet`
         };
     }
     // Heuristic: if the section is a fenced JSON block, this scenario is still
@@ -79,6 +95,16 @@ async function compileOne(taskPath, opts) {
     }
     const sidecarPath = sidecarPathFor(taskPath);
     const proseHash = hashProse(seedText);
+    // Checked ahead of `--force` and ahead of the cache: this is authorship, not
+    // staleness. The sentinel can never equal a real sha256, so without this the
+    // cache always misses and the hand-authored seed is silently overwritten.
+    if (existsSync(sidecarPath) && (await isHandAuthored(sidecarPath))) {
+        return {
+            path: taskPath,
+            status: "skipped-hand-authored",
+            message: `hand-authored seed left untouched (${sidecarPath}) — delete it or drop its _meta to recompile`
+        };
+    }
     // Cache check only applies to local compile — hosted callers may have
     // different model versions than the locally-pinned COMPILER_MODEL, and the
     // cloud has its own edge cache to avoid duplicate work anyway.
@@ -186,6 +212,24 @@ async function readSidecarMeta(path) {
         return null;
     }
 }
+/**
+ * Deliberately more lenient than `sidecarMetaSchema`: a hand-edited sidecar may
+ * carry only the sentinel and omit `version`/`compiled_at`. Failing that parse
+ * would fall through to a recompile — the exact overwrite this guards against —
+ * so any `_meta` bearing either sentinel field counts.
+ */
+async function isHandAuthored(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const meta = JSON.parse(raw)._meta;
+        if (!meta)
+            return false;
+        return meta.model === HAND_AUTHORED_MARKER || meta.source_hash === HAND_AUTHORED_SOURCE_HASH;
+    }
+    catch {
+        return false;
+    }
+}
 async function resolveTaskFiles(target) {
     const abs = resolve(target);
     if (!existsSync(abs))
@@ -202,6 +246,8 @@ function statusStamp(status) {
             return "OK  ";
         case "skipped-cached":
             return "skip";
+        case "skipped-hand-authored":
+            return "keep";
         case "skipped-no-seed":
             return "skip";
         case "skipped-unsupported-twin":

package/dist/src/cli/docs-topics.js

@@ -117,9 +117,11 @@ export const DOCS_TOPICS = [
     {
         id: "cli-tasks",
         title: "pome tasks",
-        // F-892 — `path` still points at /docs/cli/scenarios: the docs.pome.sh page
-        // is renamed by the M4 docs door, not here. Repoint once that lands.
-        path: "/docs/cli/scenarios",
+        // F-912 — the M4 docs door renamed the docs.pome.sh page from
+        // /docs/cli/scenarios to /docs/cli/tasks (a redirect keeps the old URL
+        // alive), so `path` now points at the new route. The "scenarios" keyword
+        // stays so `pome docs scenarios` still resolves to this topic.
+        path: "/docs/cli/tasks",
         keywords: ["tasks", "scenarios", "catalog", "copy", "library", "twin"],
     },
     {

package/dist/src/cli/main.js

@@ -272,7 +272,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 +360,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 +568,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 +779,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 +787,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 +796,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 +820,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 +841,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;