@method-ai-hq/sdk 0.15.1 → 0.17.0

package/dist/packages/sdk/src/method-help.js

@@ -13,7 +13,7 @@ export const commandHelp = {
     "new-id": { usage: "method new-id FILE", purpose: "Make a copied Method file a new Method.", arguments: "Writes a new id: line. A copy that keeps its id: saves to the same Method.", result: "JSON with file and method_id.", errors: "Missing file.", example: "method new-id copy.method" },
     bind: { usage: "method bind FILE_OR_ID NAME (--file FOLDER | --connection URL) [--upload]", purpose: "Save a named input location or connection.", arguments: "Default: this computer only, in ~/.config/method/computer.json under the Method's ID (a FILE gets its id: line). A folder named NAME beside the Method needs no binding. --upload saves only the selected input folder or connection URL in the account. It never scans your disk. Keep credentials in the service's normal sign-in store.", result: "Saved binding and scope.", errors: "Missing input, invalid name, or unsafe path.", example: "method bind METHOD_ID prepared_day --file day-records --upload", remote: true },
     state: { usage: "method state ID [--enable --file state.json | --release RUN_ID]", purpose: "Read or explicitly enable shared account state.", arguments: "Accepted state updates use revision checks. Inspect a stopped run's external actions before releasing its ownership.", result: "Current revision, value, and owner run.", errors: "Concurrent ownership or stale revision. Existing state is never silently overwritten.", example: "method state METHOD_ID --enable --file initial-state.json", remote: true },
-    wait: { usage: "method wait RUN_DIRECTORY", purpose: "Reconnect to the same local worker.", arguments: "Use the directory returned by run. Closing this output connection leaves the worker active.", result: "Live output, then the final worker status with the dashboard link of a synced run.", errors: "Stopped process or missing run.", example: "method wait .runs/example" },
+    wait: { usage: "method wait RUN_DIRECTORY", purpose: "Reconnect to the same local worker.", arguments: "Use the directory returned by run. Closing this output connection leaves the worker active.", result: "Live output, then a final line with the run status (succeeded, unconfirmed, waiting_for_you, or failed), the headline of a failure, and the dashboard link of a synced run.", errors: "Stopped process or missing run.", example: "method wait .runs/example" },
     'run-status': { usage: "method run-status RUN_DIRECTORY", purpose: "Read worker status without waiting.", arguments: "Local run directory.", result: "Worker status and whether its process is active.", errors: "Unreadable run directory.", example: "method run-status .runs/example" },
     cancel: { usage: "method cancel RUN_DIRECTORY", purpose: "Stop a local run process.", arguments: "Inspect uncertain external actions before any explicit retry.", result: "Cancellation request. The checkpoint remains available.", errors: "Unreadable run directory.", example: "method cancel .runs/example" },
     progress: { usage: "method progress --message TEXT [--completed N --total N --unit NAME] [--child NAME]\nmethod progress --codex --child NAME", purpose: "Report public progress from a running script or relay a child Codex JSON stream.", arguments: "METHOD_PROGRESS_FD is supplied by the executor. --codex reads JSON lines from stdin; --message sends one message. Do not include secrets or source contents.", result: "Writes to the separate progress pipe. No stdout output. No-op outside a Method process.", errors: "Invalid arguments. Malformed Codex events are ignored.", example: "method progress --message 'Rendered 12 of 40 pages' --completed 12 --total 40 --unit pages" },
@@ -36,9 +36,10 @@ export const commandHelp = {
     get: { usage: "method get WORKFLOW_ID [--version VERSION_ID] [--out FILE] [--server URL]", purpose: "Read an online method; optionally make a local draft for editing.", arguments: "Default: latest version. --out must name a new file. Use a version ID to read an exact saved version.", result: "Without --out: {workflow_id,version_id,version_number,workflow}. With --out: {workflow_id,version_id,version_number,file}; writes the workflow with its id: line and the saved files.", errors: "Missing method or version; output file already exists.", example: "method get wf_example --out edit.method", remote: true },
     explain: { usage: "method explain FILE [--step ID] [--no-round-trip] [--server URL]", purpose: "Explain each script step of the saved version in a script card.", arguments: "FILE is a local Method whose current content is a saved version (run or publish it while signed in). For each run step whose script has no card, code analysis finds the hosts, secrets, environment variables, files, and commands the script uses; a hosted model writes a one-sentence summary and 3 to 8 steps; every number, quoted name, and host in that text must appear in the code (one retry). The round trip writes a program from the steps alone and replays up to 3 recorded inputs of the step from local runs through both programs without network access. A script that calls the network is not replayed. --step explains one step. --no-round-trip skips the replay. A signed-in run starts this in the background; publish waits for it.", result: "One line per step with its summary and check results. Cards upload to the version; the dashboard shows them beside each script. A failed check is shown on the card and never blocks publish.", errors: "No saved version, local files that differ from the saved version, or no hosted-model credit. Without sign-in it prints one line and makes no card.", example: "method explain leads.method --step score", remote: true },
     publish: { usage: "method publish FILE [--reason TEXT] [--accept-failing-case ID[,ID]] [--cloud|--workers] [--env NAME] [--server URL]", purpose: "Mark a version as published, for sharing, schedules, and production runs.", arguments: "Runs the Method's cases first; a version that breaks an approved case is refused unless --accept-failing-case names it, and the version records that. Uses the version of the file's current content: it finishes that upload (no time limit while bytes move), checks the cases, then marks it published with the reason (default: Published.). --accept-failing-case needs --reason. The first save of a new file creates the Method. --cloud runs the production runs of the environment on Method Cloud; --workers runs them on your workers again. --env NAME selects the environment (default production).", result: "JSON with workflow_id, version_id, url, published_at, the cases line, and the open warnings and notes (issues). With --cloud or --workers: placement. Warnings and notes never block a publish.", errors: "An error issue (nothing is published), failing case, --accept-failing-case without --reason, or no network.", example: "method publish task.method --reason 'Shorter introduction'", remote: true },
-    improve: { usage: "method improve FILE [--case ID] [--note TEXT] [--step ID] [--server URL]", purpose: "Ask Method to propose a better version of a Method.", arguments: "--note: the correction, in your words; it is about the newest run of the Method on this computer, which the improvement reads and a suggested case records. --step: improve only this step. --case: the case the change must pass. A Method with account run data improves in your account; see the progress on the dashboard. A Method with run_data: device improves on this computer, so its run content stays here; the result is a local proposal in .method/proposals/.", result: "JSON with the improvement and the dashboard link, or the local proposal ID. Nothing is published, and the file does not change.", errors: "No id: line (run the file once while signed in), an unknown step, or an improvement that is already running.", example: "method improve task.method --step summary --note 'Name the customer in the first sentence.'", remote: true },
-    proposals: { usage: "method proposals FILE [--wait] [--server URL]", purpose: "List the proposals of a Method.", arguments: "Lists the proposals in your account and the local proposals beside the file. --wait: when an improvement is running, wait until it ends (usually a few minutes), printing each step it reaches.", result: "JSON list of proposals with id, source, status, kind, cause, and steps, and the newest improvement that has no proposal yet, with its status. An improvement that found no safe change has outcome none, and next says what to do instead. No changes.", errors: "", example: "method proposals task.method", remote: true },
-    apply: { usage: "method apply FILE [PROPOSAL_ID] [--resolved] [--server URL]", purpose: "Merge a proposal into the local file.", arguments: "Default: the newest accepted proposal, or else the newest local proposal. The merge is per step: a part that only the proposal changed takes the change; a part that you and the proposal both changed is a conflict. --resolved: you merged a conflict by hand; this marks the proposal applied. Commands that take a signed-in FILE apply an accepted proposal first and print one line.", result: "JSON with status applied and the changed steps; the file changes and the proposal is marked applied. Nothing is published. A conflict lists each part with the base, your, and the proposed value, changes nothing, and exits 1.", errors: "No proposal, a proposal that is not accepted, or a conflict.", example: "method apply task.method", remote: true },
+    judge: { usage: "method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE] [--json] [--server URL]", purpose: "Record the person's reaction to a run's result.", arguments: "RUN_ID is the run_id of the run's start line, or the run ID on the dashboard. right: the person used or approved the result. wrong: the person corrected it, or asked to change the Method because of it. --note: the person's words (at most 4000 characters). --corrected FILE: the result that the person says is right; JSON is sent as JSON, other text as text (at most 1 MB). --step: the step whose output was wrong. A wrong judgment makes Method fix the Method in the background: it applies a tested change that the person can undo, or changes nothing. Do not ask the person to confirm a judgment.", result: "One line, for example Recorded: wrong on step choose. Method is fixing it in the background. --json prints the judgment and fixing.", errors: "An unknown run, a run of a Method that is not in your account, or no sign-in.", example: "method judge 6f1c… wrong --step summary --note 'Name the customer in the first sentence.'", remote: true },
+    changes: { usage: "method changes FILE [--json] [--server URL]", purpose: "List the changes that Method applied to a Method.", arguments: "Lists the changes that Method made from wrong judgments, newest first, and the local proposals applied on this computer. Commands that take a signed-in FILE merge a new change into the file first and print one line.", result: "One line per change: its date, its version, and its cause. --json prints {file, method_id, changes: [{id, source, cause, date, version_id, steps}]}. No changes.", errors: "No id: line and no local change.", example: "method changes task.method", remote: true },
+    improve: { usage: "method improve FILE [--case ID] [--note TEXT] [--step ID] [--server URL]", purpose: "Improve a Method that keeps its run content on this computer.", arguments: "For a Method with run_data: device, or in an organization that keeps run content on devices: runs Method's improvement on this computer, so the run content stays here. --note: the correction, in the person's words; it is about the newest run of the Method on this computer, which the improvement reads and a suggested case records. --step: improve only this step. --case: the case the change must pass. For a Method that keeps run content in the account, it starts nothing and says to use method judge: Method fixes those Methods from the person's judgments.", result: "JSON with the local proposal ID and the next step; the proposal is in .method/proposals/. Nothing is published, and the file does not change. For an account Method, one line.", errors: "An unknown step, or a step of the improvement that fails.", example: "method improve task.method --step summary --note 'Name the customer in the first sentence.'", remote: true },
+    apply: { usage: "method apply FILE [PROPOSAL_ID] [--resolved] [--server URL]", purpose: "Merge a local proposal from method improve into the file.", arguments: "Default: the newest open local proposal. The merge is per step: a part that only the proposal changed takes the change; a part that you and the proposal both changed is a conflict. --resolved: you merged a conflict by hand; this marks the proposal applied. When a change that Method applied conflicts with your edits, the line before the command names it; give its ID to see both versions.", result: "JSON with status applied and the changed steps; the file changes and the proposal is marked applied. Nothing is published. A conflict lists each part with the base, your, and the proposed value, changes nothing, and exits 1.", errors: "No open proposal, or a conflict.", example: "method apply task.method", remote: true },
     secret: { usage: "method secret find [FILE]\nmethod secret import FILE NAME...\nmethod secret set NAME\nmethod secret list [NAME...]", purpose: "Give this computer the values of a Method's declared secrets.", arguments: "find lists the KEY=VALUE files in this folder (3 levels down) and in the parent folder (2 levels down) with the key names in each, never values; for the Method FILE (or the only Method here) it says which declared secrets each file holds and prints the import command. import copies the named values from a KEY=VALUE file that the user names, without printing them. set opens a private form on 127.0.0.1 in the browser for one value. list shows names and where each value is found (shell, this computer, or missing), never values. Values are kept in ~/.config/method/secrets.json (mode 0600) and are never sent to Method. A value exported in the shell is used first. Every script of the Method receives all of its declared secrets.", result: "JSON with the saved names, or the list.", errors: "A name is missing from the file, or no value was entered.", example: "method secret find\nmethod secret import ../service/.env ARCHIVE_TOKEN" },
     connect: { usage: "method connect [APP_FOLDER] [--file METHOD_FILE]", purpose: "Connect an app to the Method in this folder, so the app runs it in production.", arguments: "Run it in the Method's folder. APP_FOLDER (default: this folder) is the app's folder. It makes a service key named after the app folder and writes METHOD_API_KEY to the app's .env (a new file, or a new or replaced line); it never prints the key. It adds .env to .gitignore in a git repository. When the Method has no published version, it publishes the current file. It detects Node (package.json) or Python (pyproject.toml, requirements.txt), and prints the install line and the code to add. Run it again: an app with a working key keeps it.", result: "JSON with the method_id, the published version, where the key is, install, code, secrets_to_set_on_the_host, and next.", errors: "No or several .method files (give --file), an app folder with no language marker, or a failing case at publish.", example: "method connect ../app", remote: true },
     answer: { usage: "method answer RUN_ID [--answer JSON]", purpose: "Show or answer the question of a production run that waits on an ask step.", arguments: "Without --answer it prints the question and its form (the fields of the answer). With --answer it checks the answer against the form and sends it; the run continues. A run that keeps its content on devices has a sealed question: run this where the app's METHOD_API_KEY is (the environment, or the .env of this folder), or on the laptop that started the run with its sign-in. Local runs (method run FILE) take answers with --human FILE as before.", result: "The question and form, or the run after the answer.", errors: "The run is not waiting, the answer does not match the form, or the key cannot open a sealed question (wrong_key).", example: "method answer 6f1c… --answer '{\"approved\":true}'", remote: true },
@@ -66,7 +67,7 @@ export const commandHelp = {
 --fresh: run every step; reuse nothing.
 --human FILE: answers for ask steps, as {steps: {"STEP": {outputs: {...}}}} (STEP:ITERATION, counted from 0, for a step with each or repeat).
 --verbose: print runtime events.
-Use method doctor to check the installed Node and configured tools.`, result: "When signed in, the start line and the final result have dashboard: the link to the run's page; give it to the user when the run starts. Progress and final status text; local result.json and run evidence. The runtime executes the method's declared scripts, calls, agents, and checks. Executes trusted local processes; changes declarations do not enforce permissions. Runs exit 0 on completion, 1 on failure, 2 when human input is needed, and 3 when an observer could not confirm an external change (unconfirmed).", errors: "Missing inputs/access, failed check, timeout, unsafe resume/version mismatch, upload failure. See recovery. Never retry a business write without inspecting its saved changes.", example: "method run wf_example --version v_example --inputs inputs.json", remote: true },
+Use method doctor to check the installed Node and configured tools.`, result: "When signed in, the start line and the final result have dashboard: the link to the run's page; give it to the user when the run starts. Progress, then the final result as JSON on stdout; a run that stopped has failure (owner, headline, step, next), and a failed run also prints Failed, Whose problem, and Next lines on stderr. Local result.json and run evidence. The runtime executes the method's declared scripts, calls, agents, and checks. Executes trusted local processes; changes declarations do not enforce permissions. Runs exit 0 on completion, 1 on failure, 2 when human input is needed, and 3 when an observer could not confirm an external change (unconfirmed).", errors: "Missing inputs/access, failed check, timeout, unsafe resume/version mismatch, upload failure. See recovery. Never retry a business write without inspecting its saved changes.", example: "method run wf_example --version v_example --inputs inputs.json", remote: true },
     observe: { usage: "method observe [RUN_DIRECTORY...] [--pending ROOT]...", purpose: "Make the effect observations that are due for finished runs.", arguments: "Without directories, checks runs with open effects under .method-runs and the Method cache. Runs only observers and judges; never repeats an action. Schedule it, for example hourly, so late evidence such as a bounce reaches the run.", result: "JSON with each run's new verdicts, status, and next observation time. A synced run whose status changed is uploaded again.", errors: "Locked run, changed bundle, or a missing observer credential.", example: "method observe --pending .method-runs" },
     test: { usage: "method test FILE [--case ID]... [--baseline OLD_FILE] [--new ID]... [--cases DIR] [--agent codex|claude]", purpose: "Replay recorded cases against this version of a Method. Every case must pass.", arguments: "Cases are in cases/ beside the Method. Unchanged steps return their recorded outputs; changed steps run; files connections are scratch folders, so a changed step that writes files runs safely. A changed step that asks a person or acts on a service makes the case unverifiable. --baseline also runs each case on the old version, to show what the change fixed or broke.", result: "JSON report with a verdict per case and passed:true when no case blocks the change. Exit 0 or 1.", errors: "Unknown case, invalid Method, or setup errors.", example: "method test task.method --baseline task-before.method --new bounce-reported" },
     case: { usage: "method case new|retire|list FILE ...", purpose: "Keep a correction as a recorded case that every later version must pass.", arguments: "Use method help case new, method help case retire, or method help case list.", result: "See the subcommand.", errors: "Unknown action. Choose new, retire, or list.", example: "method help case new" },
@@ -299,7 +300,7 @@ const recipes = `# Recipes
 ## Corrections become cases
 
 When the user says a result was wrong:
-1. Read the run (result.json, events.jsonl) and fix the Method. Run it again and show the user the new result.
+1. Record it: method judge RUN_ID wrong --note "the user's words" (--corrected FILE when they gave the right result). Do not ask them to confirm it. Then read the run (result.json, events.jsonl) and fix the Method. Run it again and show the user the new result.
 2. If the user wants the fix to stay, ask once: "Keep this as a rule: <the rule in plain words>?"
 3. On yes, record it: method case new FILE --id ID --run BAD_RUN --passing-run NEW_RUN --note "the user's words" --rubric "plain sentence that must be true" (repeat --rubric for each rule). --ref names the output to judge (default: the Method's result; a path to a file that the run saved is judged by that file's contents). When a rule compares the output with the sources, add --context with the step output that holds them, for example --context outputs.material. Make each sentence fail on the bad run; case new warns about one that does not. For an exact value, use --expect instead.
 4. Run method test FILE. Every case must pass. method publish refuses a version that breaks a case.
@@ -337,7 +338,7 @@ A save never blocks a run: a run that cannot save says "Will save when online",
 State commits after checks. A local checkpoint cannot roll back an external write. Inspect external state before an explicit retry.
 Two computers can save different content of one Method; each becomes a version with its parent. Going back to earlier content finds its existing version. The id: line keeps a renamed or moved file on its Method; method new-id FILE makes a copy a new Method. On one computer a Method is saved from one file (every checkout of one Git repository counts as one): a copy in another folder or a temporary folder does not run while that file exists, and the error names the file to change. When that file is unchanged since its last save and the account has a newer version, a run takes that version first.
 Use method sync RUN_DIRECTORY to repair a dashboard upload without executing the method again.
-After a failed action with effects, the failure lists what the observers saw. A confirmed effect means the change happened: do not retry the action. A run that is unconfirmed finished all its steps; inspect effects.jsonl and the external system before relying on its result.
+After a failed action with effects, failure.next.text lists what the observers saw. A confirmed effect means the change happened: do not retry the action. A run that is unconfirmed finished all its steps; inspect effects.jsonl and the external system before relying on its result.
 `;
 export const guideTopics = ["start", "concepts", "execution", "examples", "example", "recipes", "recovery", "commands"];
 export function authoringGuide(topic = "start", exampleId) {
@@ -370,7 +371,7 @@ Learn: method authoring                 Start the installed guide.
 Local drafts: init, show, set, remove, step add/update/remove/move,
               check set/remove, validate, diff.
 Online documents: list, get, steps, step, publish, explain.
-Improvements: improve, proposals, apply.
+Results and improvements: judge, changes, improve, apply.
 Keys for scripts: secret find, secret import, secret set, secret list.
 Execution and evidence: run, run-status, wait, cancel, runs, logs, sync, observe.
 Effects and corrections: effect add/list, case new/retire/list, test.

package/dist/packages/sdk/src/method-sync.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import { inspectRun } from "./inspect.js";
+import { setupFailure, unreadableRecord } from "./failure.js";
 import { writePrivateJson } from "./files.js";
 import { MethodClient } from "./method-client.js";
 import { InspectionSchema, deviceOnly, } from "../../workflow-language/src/inspection.js";
@@ -216,10 +217,8 @@ export class MethodSync {
                 inspection = {
                     ...this.initial,
                     events: existsSync(join(this.directory, "setup.json")) ? JSON.parse(readFileSync(join(this.directory, "setup.json"), "utf8")) : this.initial.events,
-                    status: "needs_attention",
-                    error: failure instanceof Error
-                        ? failure.message
-                        : String(failure ?? error),
+                    // A run that failed before its first step has the failure record of its setup error; otherwise Method could not read the record.
+                    ...((record => ({ status: record.code === "needs_input" ? "waiting_for_you" : "failed", failure: record }))(failure ? setupFailure(failure) : unreadableRecord(error))),
                 };
                 // A run that failed before its first step keeps this record for a later sync.
                 writePrivateJson(join(this.directory, "setup-inspection.json"), inspection);

package/dist/packages/sdk/src/method.d.ts

@@ -1,5 +1,3 @@
 #!/usr/bin/env node
 import { MethodClient } from "./method-client.js";
-/** The next step for a failure before the first step. */
-export declare function setupFix(error: any): any;
 export declare function methodMain(args?: string[], clientFactory?: (server: string) => MethodClient): Promise<boolean | void>;

package/dist/packages/sdk/src/method.js

@@ -20,15 +20,7 @@ import { parse, localMain } from "./local-cli.js";
 import { writePrivateJson } from "./files.js";
 import { loadWorkflow } from "../../workflow-language/src/validate.js";
 import { methodHelp, overviewHelp as help } from "./method-help.js";
-import { fixFor } from "@withmethod/runtime/runner.js";
 /** The next step for a failure before the first step. */
-export function setupFix(error) {
-    if (error.code === 'missing_secret') {
-        const names = (error.missing ?? []).join(' ');
-        return `No step ran. Run method secret find to see which nearby files hold ${names}, then method secret import FILE ${names}; or ask the user to enter each one with method secret set NAME (a private form in their browser). Never open or print a key file, and never ask for a value in chat.`;
-    }
-    return fixFor(error);
-}
 function safePath(path) {
     return authoringPath(path);
 }
@@ -70,7 +62,9 @@ export async function methodMain(args = process.argv.slice(2), clientFactory = s
         process.stdout.write(earlyHelp);
         return;
     }
-    if (['improve', 'proposals', 'apply'].includes(args[0] ?? ''))
+    if (args[0] === 'judge')
+        return (await import('./judge.js')).judgeCommand(args.slice(1), clientFactory);
+    if (['improve', 'changes', 'apply'].includes(args[0] ?? ''))
         return (await import('./proposals.js')).proposalCommand(args, clientFactory);
     await (await import('./proposals.js')).autoApply(args, clientFactory);
     if (args[0] === 'worker' || args[0] === 'keys')
@@ -99,9 +93,13 @@ export async function methodMain(args = process.argv.slice(2), clientFactory = s
         }
         catch (error) {
             // A run that fails before its first step still prints one result that says why and what to do.
-            const failed = { status: error.code === 'needs_input' ? 'needs_input' : 'failed', run_dir: directory, code: error.code ?? 'setup_failed', error: error.message, ...(error.missing ? { missing: error.missing } : {}), fix: setupFix(error) };
+            const { setupFailure, failureLines } = await import('./failure.js');
+            const failure = setupFailure(error);
+            const failed = { status: error.code === 'needs_input' ? 'needs_input' : 'failed', run_dir: directory, failure, ...(error.missing ? { missing: error.missing } : {}) };
             if (!existsSync(join(directory, 'summary.json')))
                 writePrivateJson(join(directory, 'summary.json'), failed);
+            if (failed.status === 'failed')
+                process.stderr.write(failureLines(failure));
             process.stdout.write(JSON.stringify(failed, null, 2) + '\n');
             process.exitCode = error.code === 'needs_input' ? 2 : 1;
         }

package/dist/packages/sdk/src/model-checks.d.ts

@@ -25,11 +25,21 @@ type Check = {
     /** Which part of the step the check reads; undefined when the check does not apply to the step. */
     script?: (step: Step) => string | undefined;
     applies: (step: Step) => boolean;
+    /** More inputs for Jev, from the Method (for example the definitions of an agent step's tools). */
+    context?: (step: Step, method: any) => Record<string, string>;
+    /** A finding (true) or none (false) that code analysis decides without a question to Jev; undefined asks Jev. */
+    decide?: (inputs: Record<string, string>) => boolean | undefined;
     field: string;
     message: (id: string) => string;
     fix: string;
 };
 export declare const checks: Record<string, Check>;
+/**
+ * The script scan of a run step (explain-effects): a network host or a write is a finding with no model call. No host,
+ * no write, and no library that can send: no finding. A library that can send or a subprocess with no host found:
+ * undefined, so Jev answers.
+ */
+export declare function scanDecision(stepYaml: string, script: string): boolean | undefined;
 /**
  * Checks shown to the user. A check moves here from shadow mode only with a results.json that shows its precision
  * on the frozen held-out set meets its level (warning >= 0.90, note >= 0.75). Run npm run eval:checks first.
@@ -78,7 +88,14 @@ export declare function askCheck(provider: ClassificationProvider, question: str
     probability: number;
     model: string;
 }>;
-export declare function evaluateTarget(provider: ClassificationProvider, target: Target, signal: AbortSignal): Promise<Result>;
+/** The answer of code analysis, when the check has one for these inputs. */
+export declare function decided(check: string, inputs: Record<string, string>): {
+    answer: boolean;
+    probability: number;
+    model: string;
+} | undefined;
+/** Answer one target: code analysis when it decides, or else Jev. scanned: code analysis already found it cannot decide. */
+export declare function evaluateTarget(provider: ClassificationProvider | undefined, target: Target, signal: AbortSignal, scanned?: boolean): Promise<Result>;
 /**
  * Run the targets in parallel. Cached answers come at once; new ones get waitMs in all. The others are returned as
  * pending, so the caller can finish them in the background. A failed check is left out and is tried again next time.

package/dist/packages/sdk/src/model-checks.js

@@ -8,7 +8,11 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFile
 import { join } from 'node:path';
 import { serializeWorkflow } from '../../workflow-language/src/validate.js';
 import { methodCache } from './prepare.js';
+import { scriptLanguage, staticEffects } from './explain-effects.js';
 const promptKinds = ['call', 'agent'];
+/** A step that declares a change outside the run: a connection or service in changes, or an effect. */
+const declaresWorldChange = (step) => (step.changes ?? []).some((ref) => typeof ref === 'string' && ref.startsWith('environment.')) || Object.keys(step.effects ?? {}).length > 0;
+const agentWithTools = (step) => step.do?.kind === 'agent' && ((step.do.tools ?? []).length > 0 || !!step.do.browser);
 export const checks = {
     script_calls_model: {
         version: 1, level: 'warning', field: 'do',
@@ -52,7 +56,48 @@ export const checks = {
         message: id => `The prompt of ${id} appears to need information that the step does not give it.`,
         fix: 'Add the missing value to in: from an input or an earlier step, or write it in the prompt.',
     },
+    undeclared_change: {
+        version: 1, level: 'warning', field: 'do',
+        question: 'Can this step send, post, or change something outside its own output folder, for example send an email or a message, create or update a record in a service or an API, submit a form, or write files elsewhere, while its changes: and effects: declare no such change? Reading, searching, downloading, and returning a result are not changes.',
+        applies: step => !declaresWorldChange(step) && (step.do?.kind === 'run' || agentWithTools(step)),
+        script: step => step.do?.kind === 'run' ? step.do.entrypoint : undefined,
+        context: (step, method) => step.do?.kind === 'agent' && (step.do.tools ?? []).length
+            ? { tools: limit(serializeWorkflow(Object.fromEntries(step.do.tools.map(name => [name, method.tools?.[name] ?? null]))), 16_000) } : {},
+        decide: inputs => inputs.script === undefined ? undefined : scanDecision(inputs.step ?? "", inputs.script),
+        message: id => `${id} can send or change things that it does not declare.`,
+        fix: 'Declare what it changes in changes:, so Method can check where its data goes.',
+    },
 };
+/** Libraries and calls that can send or change something, but whose target code analysis may not find. */
+const senders = {
+    python: /^\s*(?:import|from)\s+(?:requests|httpx|aiohttp|urllib3?|http\.client|smtplib|email\.mime|boto3|slack_sdk|twilio|sendgrid|googleapiclient|subprocess)\b|\bos\.(?:system|popen)\(/m,
+    node: /\bfetch\(|\brequire\(\s*['"](?:node:)?(?:https?|child_process|axios|node-fetch|got|undici|nodemailer|@sendgrid\/mail|@slack\/web-api|twilio)['"]|\bfrom\s+['"](?:node:)?(?:https?|child_process|axios|node-fetch|got|undici|nodemailer|@sendgrid\/mail|@slack\/web-api|twilio)['"]/,
+};
+/** Temporary files are not a change in the world. */
+const temporaryPath = (path) => /^(?:\/tmp\/|\/var\/folders\/|\/private\/tmp\/)/.test(path);
+/**
+ * The script scan of a run step (explain-effects): a network host or a write is a finding with no model call. No host,
+ * no write, and no library that can send: no finding. A library that can send or a subprocess with no host found:
+ * undefined, so Jev answers.
+ */
+export function scanDecision(stepYaml, script) {
+    const entrypoint = /^\s*entrypoint:\s*["']?([^\s"']+)/m.exec(stepYaml)?.[1];
+    const language = entrypoint ? scriptLanguage(entrypoint) : undefined;
+    if (!language || !script.trim())
+        return undefined;
+    let effects;
+    try {
+        effects = staticEffects(language, [{ path: entrypoint, text: script }], undefined).effects;
+    }
+    catch {
+        return undefined;
+    }
+    if (effects.network.length || effects.writes.some(path => !temporaryPath(path)))
+        return true;
+    if (effects.runs.length || senders[language].test(script))
+        return undefined;
+    return false;
+}
 /**
  * Checks shown to the user. A check moves here from shadow mode only with a results.json that shows its precision
  * on the frozen held-out set meets its level (warning >= 0.90, note >= 0.75). Run npm run eval:checks first.
@@ -78,7 +123,7 @@ export function checkTargets(method, readText, steps) {
             if (!check.applies(step))
                 continue;
             const path = check.script?.(step);
-            const inputs = { step: stepText(id, step) };
+            const inputs = { step: stepText(id, step), ...check.context?.(step, method) };
             if (path)
                 inputs.script = limit(readText(path) ?? '', 40_000);
             targets.push({ check: name, version: check.version, step: id, inputs, key: checkKey(name, check.version, inputs) });
@@ -86,7 +131,7 @@ export function checkTargets(method, readText, steps) {
     }
     return targets;
 }
-export const checkKey = (check, version, inputs) => createHash('sha256').update(JSON.stringify([check, version, inputs.step, inputs.script ?? ''])).digest('hex');
+export const checkKey = (check, version, inputs) => createHash('sha256').update(JSON.stringify([check, version, inputs.step, inputs.script ?? '', ...(inputs.tools !== undefined ? [inputs.tools] : [])])).digest('hex');
 export const checksDir = () => join(methodCache(), 'checks');
 export function cached(key) {
     const file = join(checksDir(), `${key}.json`);
@@ -108,14 +153,24 @@ function store(result) {
  * probability is that of yes.
  */
 export const answerOptions = { yes: 'Yes: the question describes this step.', no: 'No: the question does not describe this step.' };
+const noProvider = () => { throw Error('Model checks need sign-in.'); };
 export async function askCheck(provider, question, inputs, signal) {
     const { model } = await provider.resolve(signal);
     const answer = await provider.evaluate({ request_id: randomUUID(), model, question, options: answerOptions, inputs }, signal);
     const probability = answer.probabilities.yes ?? 0;
     return { answer: probability >= findingThreshold, probability, model };
 }
-export async function evaluateTarget(provider, target, signal) {
-    const answer = await askCheck(provider, checks[target.check].question, target.inputs, signal);
+/** The answer of code analysis, when the check has one for these inputs. */
+export function decided(check, inputs) {
+    const answer = checks[check]?.decide?.(inputs);
+    return answer === undefined ? undefined : { answer, probability: answer ? 1 : 0, model: 'script-scan' };
+}
+/** Answer one target: code analysis when it decides, or else Jev. scanned: code analysis already found it cannot decide. */
+export async function evaluateTarget(provider, target, signal, scanned = false) {
+    const answer = (scanned ? undefined : decided(target.check, target.inputs)) ?? await askCheck(provider ?? noProvider(), checks[target.check].question, target.inputs, signal);
+    return record(target, answer);
+}
+function record(target, answer) {
     const result = { check: target.check, version: target.version, step: target.step, key: target.key, answer: answer.probability >= findingThreshold,
         probability: answer.probability, model: answer.model, at: new Date().toISOString() };
     store(result);
@@ -127,15 +182,20 @@ export async function evaluateTarget(provider, target, signal) {
  */
 export async function runChecks(provider, targets, waitMs = 3000) {
     const done = [], pending = [];
-    const open = targets.filter(target => { const hit = cached(target.key); if (hit)
-        done.push(hit); return !hit; });
+    // Answers that code analysis decides need no provider and no wait.
+    const open = targets.filter(target => {
+        const hit = cached(target.key) ?? (() => { const answer = decided(target.check, target.inputs); return answer && record(target, answer); })();
+        if (hit)
+            done.push(hit);
+        return !hit;
+    });
     if (!open.length)
         return { done, pending };
     if (!provider)
         return { done, pending: open };
     const controller = new AbortController();
     const settled = new Set();
-    const work = open.map(target => evaluateTarget(provider, target, controller.signal)
+    const work = open.map(target => evaluateTarget(provider, target, controller.signal, true)
         .then(result => { done.push(result); }).catch(() => { }).finally(() => settled.add(target.key)));
     let timer;
     await Promise.race([Promise.all(work), new Promise(resolve => { timer = setTimeout(resolve, waitMs); })]);

package/dist/packages/sdk/src/production.js

@@ -155,7 +155,7 @@ export class Method {
                 throw new MethodApiError(409, "not_waiting", `The run is ${run.status}; it has no question to answer.`);
             const asked = this.openQuestion(run);
             try {
-                assertSchema(asked.form, answer, "Answer");
+                assertSchema(asked.form, answer, "Answer", { producer: "the answer", owner: "needs_you" });
             }
             catch (error) {
                 throw new MethodApiError(422, "invalid_answer", error.message);

package/dist/packages/sdk/src/proposals.d.ts

@@ -58,9 +58,9 @@ type Applied = {
 /** Merge a proposal into the file. A clean merge writes the file and marks the proposal applied. Never publishes. */
 export declare function applyProposal(client: MethodClient | undefined, file: string, proposal: ProposalRecord, options?: RequestOptions): Promise<Applied>;
 /**
- * Before a command that takes a .method FILE: when this computer is signed in and the Method has an accepted proposal,
- * merge it into the file and print one line. A conflict prints what the coding agent must resolve; the command goes on.
- * Offline, signed out, or on any error, it does nothing.
+ * Before a command that takes a .method FILE: when this computer is signed in and Method applied a change to the Method
+ * (an accepted proposal, from the person's judgments), merge it into the file and print one line. A conflict prints
+ * what the coding agent must resolve; the command goes on. Offline, signed out, or on any error, it does nothing.
  */
 export declare function autoApply(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;
 /** Run folders of this Method on this computer, newest first, with the account run ID of each run that was saved to the account. */
@@ -68,6 +68,6 @@ export declare function localRuns(file: string): Promise<{
     dir: string;
     account_run_id: string | null;
 }[]>;
-/** `method improve`, `method proposals`, and `method apply`. */
+/** `method improve`, `method changes`, and `method apply`. */
 export declare function proposalCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<boolean | undefined>;
 export {};

package/dist/packages/sdk/src/proposals.js

@@ -133,11 +133,11 @@ async function markApplied(client, file, proposal, options = {}) {
     }
 }
 const serverFlag = (args) => { const at = args.findIndex(arg => arg === '--server' || arg.startsWith('--server=')); return at < 0 ? undefined : args[at].startsWith('--server=') ? args[at].slice(9) : args[at + 1]; };
-const skipAutoApply = new Set(['apply', 'proposals', 'improve', 'init', 'new-id', 'diff', 'help', 'authoring', 'schema', '__worker', '__checks', 'worker', 'keys', 'secret', 'models', 'login', 'logout', 'sync', 'progress']);
+const skipAutoApply = new Set(['apply', 'changes', 'judge', 'improve', 'init', 'new-id', 'diff', 'help', 'authoring', 'schema', '__worker', '__checks', 'worker', 'keys', 'secret', 'models', 'login', 'logout', 'sync', 'progress']);
 /**
- * Before a command that takes a .method FILE: when this computer is signed in and the Method has an accepted proposal,
- * merge it into the file and print one line. A conflict prints what the coding agent must resolve; the command goes on.
- * Offline, signed out, or on any error, it does nothing.
+ * Before a command that takes a .method FILE: when this computer is signed in and Method applied a change to the Method
+ * (an accepted proposal, from the person's judgments), merge it into the file and print one line. A conflict prints
+ * what the coding agent must resolve; the command goes on. Offline, signed out, or on any error, it does nothing.
  */
 export async function autoApply(args, clientFactory) {
     if (!args[0] || skipAutoApply.has(args[0]) || args.includes('--help') || process.env.METHOD_RUN_WORKER === '1')
@@ -159,12 +159,12 @@ export async function autoApply(args, clientFactory) {
         const result = await applyProposal(client, file, proposal, options);
         if (result.status === 'applied') {
             if (result.steps.length || result.warning)
-                process.stderr.write(`Applied accepted proposal ${proposal.id} to ${target}: ${proposal.cause}${result.steps.length ? ` Changed steps: ${result.steps.join(', ')}.` : ''} Not published.${result.warning ? ` ${result.warning}` : ''}\n`);
+                process.stderr.write(`Method changed ${target} (${proposal.id}): ${proposal.cause}${result.steps.length ? ` Changed steps: ${result.steps.join(', ')}.` : ''}${result.warning ? ` ${result.warning}` : ''}\n`);
         }
         else
             process.stderr.write(result.status === 'conflict'
-                ? `Accepted proposal ${proposal.id} conflicts with your edits of ${target} in ${result.conflicts.map(c => c.path).join(', ')}. The file is not changed. Run method apply ${target} ${proposal.id} to see both versions, merge them in the file, then run method apply ${target} ${proposal.id} --resolved.\n`
-                : `Accepted proposal ${proposal.id} does not merge into a valid Method: ${result.error} The file is not changed. Run method apply ${target} ${proposal.id} to see it.\n`);
+                ? `Method's change ${proposal.id} conflicts with your edits of ${target} in ${result.conflicts.map(c => c.path).join(', ')}. The file is not changed. Run method apply ${target} ${proposal.id} to see both versions, merge them in the file, then run method apply ${target} ${proposal.id} --resolved.\n`
+                : `Method's change ${proposal.id} does not merge into a valid Method: ${result.error} The file is not changed. Run method apply ${target} ${proposal.id} to see it.\n`);
     }
     catch { /* offline or signed out: the command goes on without the proposal. */ }
 }
@@ -196,55 +196,36 @@ function manualStep(file, proposal, runFolder) {
     return 'This proposal has no change to apply.';
 }
 const print = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
-function summary(p) {
-    return { id: p.id, source: p.source, status: p.status, kind: p.evidence?.kind ?? null, cause: p.cause, steps: p.evidence?.steps ?? [], base_version_id: p.base_version_id, created_at: p.created_at };
+const changeLine = (change) => `${change.date.slice(0, 10)}  ${change.version_id ?? 'not saved as a version'}  ${change.cause}`;
+/** `method changes FILE`: the changes that Method applied to the Method, newest first, and those applied on this computer. */
+async function changesCommand(file, target, methodId, client, json) {
+    const local = localProposals(file).filter(p => p.status === 'applied').map((p) => ({ id: p.id, source: 'local', cause: p.cause, date: String(p.applied_at ?? p.created_at), version_id: p.applied_version_id ?? null, steps: p.evidence?.steps ?? [] }));
+    let account = [];
+    if (methodId) {
+        const { proposals } = await client.request(`/api/methods/${encodeURIComponent(methodId)}/proposals?status=accepted`);
+        account = (proposals ?? []).map(p => ({ id: p.id, source: 'account', cause: String(p.cause ?? ''), date: String(p.created_at ?? ''), version_id: p.published_version_id ?? null, steps: p.evidence?.steps ?? [] }));
+    }
+    else if (!local.length)
+        throw Error(`${target} has no id: line, so Method has not changed it. Run it once while signed in.`);
+    const changes = [...account, ...local].sort((a, b) => b.date.localeCompare(a.date));
+    if (json)
+        return print({ file, method_id: methodId, changes });
+    process.stdout.write(changes.length ? changes.map(changeLine).join('\n') + '\n' : `Method has not changed ${target} yet.\n`);
 }
-/** `method improve`, `method proposals`, and `method apply`. */
+/** `method improve`, `method changes`, and `method apply`. */
 export async function proposalCommand(args, clientFactory) {
     if (args[0] === 'improve')
         return (await import('./improve.js')).improveCommand(args.slice(1), clientFactory);
-    const { values, positionals } = parseArgs({ args: args.slice(1), allowPositionals: true, options: { server: { type: 'string' }, resolved: { type: 'boolean' }, wait: { type: 'boolean' } } });
+    const { values, positionals } = parseArgs({ args: args.slice(1), allowPositionals: true, options: { server: { type: 'string' }, resolved: { type: 'boolean' }, json: { type: 'boolean' } } });
     const [target, wanted] = positionals;
     if (!target || positionals.length > (args[0] === 'apply' ? 2 : 1))
-        throw Error(args[0] === 'apply' ? 'Use method apply FILE [PROPOSAL_ID] [--resolved].' : 'Use method proposals FILE.');
+        throw Error(args[0] === 'apply' ? 'Use method apply FILE [PROPOSAL_ID] [--resolved].' : 'Use method changes FILE [--json].');
     const file = authoringPath(target), id = readDocument(file).id;
     const methodId = typeof id === 'string' && methodIdPattern.test(id) ? id : null;
     const client = clientFactory(values.server ?? DEFAULT_SERVER);
     const signedIn = !!client.token();
-    if (args[0] === 'proposals') {
-        const local = localProposals(file).map(summary);
-        if (!methodId || !signedIn)
-            return print({ file, method_id: methodId, proposals: local, ...(methodId ? { next: 'Run method login to see the proposals in your account too.' } : {}) });
-        const read = async () => {
-            const [{ proposals }, { improvements }] = await Promise.all([
-                client.request(`/api/methods/${encodeURIComponent(methodId)}/proposals`),
-                client.request(`/api/methods/${encodeURIComponent(methodId)}/improvements`)
-            ]);
-            // The newest improvement that has no proposal: still running, failed, or ended with no safe change (outcome none).
-            const latest = (improvements ?? []).find(i => !i.proposal_id);
-            return { proposals, pending: latest && (latest.created_at ?? '') > String((proposals ?? [])[0]?.created_at ?? '') ? latest : undefined };
-        };
-        let { proposals, pending } = await read();
-        // --wait: one line each time the improvement reaches a new step, until it ends.
-        let shown = '';
-        while (values.wait && pending && ['queued', 'running'].includes(pending.status)) {
-            const step = pending.steps?.find((s) => s.status === 'running')?.step_id ?? pending.status;
-            if (step !== shown) {
-                process.stderr.write(`Improvement ${pending.id}: ${step}\n`);
-                shown = step;
-            }
-            await new Promise(resolve => setTimeout(resolve, 5000));
-            ({ proposals, pending } = await read());
-        }
-        const failedStep = pending?.steps?.find((s) => s.status === 'failed')?.step_id;
-        const next = !pending ? undefined
-            : ['queued', 'running'].includes(pending.status) ? `Improvement ${pending.id} is ${pending.status}. Run method proposals ${target} --wait: it returns when the proposal is ready.`
-                : pending.outcome === 'none' ? `The improvement found no safe change. Say what is wrong in a note on a run (method improve ${target} --note TEXT), or record a case with method case new.`
-                    : pending.status === 'failed' || pending.status === 'cancelled' ? `Improvement ${pending.id} ${pending.status}${failedStep ? ` at step ${failedStep}` : ''}${pending.error?.message ? `: ${pending.error.message}` : ''}. Run method improve ${target} again, or record the correction with method case new.`
-                        : undefined;
-        return print({ file, method_id: methodId, proposals: [...(proposals ?? []).map(p => summary({ ...p, source: 'account' })), ...local].sort((a, b) => String(b.created_at).localeCompare(String(a.created_at))),
-            ...(pending ? { improvement: { id: pending.id, status: pending.status, ...(pending.outcome === 'none' ? { outcome: 'none' } : {}), ...(failedStep ? { failed_step: failedStep } : {}), ...(pending.error ? { error: pending.error } : {}) } } : {}), ...(next ? { next } : {}) });
-    }
+    if (args[0] === 'changes')
+        return changesCommand(file, target, methodId, client, !!values.json);
     const local = localProposals(file);
     let proposal = wanted ? local.find(p => p.id === wanted) : undefined;
     if (!proposal && wanted) {
@@ -254,15 +235,13 @@ export async function proposalCommand(args, clientFactory) {
         if (methodId && proposal.method_id !== methodId)
             throw Error(`Proposal ${wanted} is for another Method.`);
     }
-    if (!proposal && methodId && signedIn)
-        proposal = await newestAccepted(client, methodId);
     proposal ??= local.find(p => p.status === 'open');
     if (!proposal)
-        throw Error(`${target} has no accepted proposal. Run method proposals ${target}.`);
+        throw Error(`${target} has no open proposal. Run method improve ${target} --note TEXT first.`);
     if (proposal.status === 'applied')
         return print({ status: 'applied', file, proposal_id: proposal.id, next: 'This proposal is already applied.' });
     if (proposal.source === 'account' && proposal.status !== 'accepted')
-        throw Error(`Proposal ${proposal.id} is ${proposal.status}. Accept it on the dashboard first: ${client.server}/methods/${proposal.method_id}`);
+        throw Error(`Change ${proposal.id} is ${proposal.status}, so it has nothing to merge.`);
     if (proposal.source === 'local' && proposal.status !== 'open')
         throw Error(`Proposal ${proposal.id} is ${proposal.status}.`);
     if (values.resolved)

package/dist/packages/sdk/src/run-saved.d.ts

@@ -1,5 +1,5 @@
 import { MethodClient } from './method-client.js';
 import type { parse } from './local-cli.js';
 /** A run whose steps all finished: completed, or unconfirmed (an external change could not be confirmed). */
-export declare const finishedRun: (status: string) => status is "completed" | "unconfirmed";
+export declare const finishedRun: (status: string) => status is "unconfirmed" | "completed";
 export declare function runSaved(saved: any, flags: ReturnType<typeof parse>['values'], client: MethodClient): Promise<any>;

package/dist/packages/sdk/src/run-saved.js

@@ -12,8 +12,9 @@ import { writePrivateJson } from './files.js';
 import { workerRunId } from './run-worker.js';
 import { readDocument } from './authoring.js';
 import { withInputsFrom } from './inputs-from.js';
+import { setupFailure } from './failure.js';
 // Older versions are listed only after their saved-package tests pass.
-const supportedPackageRuntimes = new Set([runtimeVersion, '0.11.1', '0.11.0', '0.10.0', '0.9.5', '0.9.4', '0.9.3', '0.7.0', '0.7.1', '0.7.2', '0.8.0', '0.8.1', '0.8.2', '0.8.3']);
+const supportedPackageRuntimes = new Set([runtimeVersion, '0.12.0', '0.11.1', '0.11.0', '0.10.0', '0.9.5', '0.9.4', '0.9.3', '0.7.0', '0.7.1', '0.7.2', '0.8.0', '0.8.1', '0.8.2', '0.8.3']);
 /** A run whose steps all finished: completed, or unconfirmed (an external change could not be confirmed). */
 export const finishedRun = (status) => status === 'completed' || status === 'unconfirmed';
 export async function runSaved(saved, flags, client) {
@@ -124,7 +125,8 @@ export async function runSaved(saved, flags, client) {
         return { run_id: request.run_id, directory, ...result };
     }
     catch (error) {
-        writePrivateJson(join(directory, 'setup-error.json'), { code: error.code ?? 'setup_failed', error: error.message, ...(error.missing ? { missing: error.missing } : {}) });
+        // The run stopped before its first step: setup-error.json holds its failure record.
+        writePrivateJson(join(directory, 'setup-error.json'), setupFailure(error));
         setupEvents.push({ at: new Date().toISOString(), type: 'setup_failed', detail: error.message });
         writePrivateJson(setupFile, setupEvents);
         await sync.finish(error);

package/dist/packages/sdk/src/run-worker.js

@@ -5,6 +5,8 @@ import { resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { writePrivateJson } from './files.js';
 import { runDashboard } from './method-sync.js';
+import { runStatus } from './current-inspection.js';
+import { unreadableRecord } from './failure.js';
 /** server: the signed-in Method server, so that the start line links to the run's dashboard page. */
 export async function startRunWorker(args, directory, background = false, server) {
     directory = resolve(directory);
@@ -117,8 +119,15 @@ export async function waitForRun(directory) {
             const status = JSON.parse(readFileSync(file, 'utf8'));
             const dashboard = runDashboard(directory), link = dashboard ? { dashboard } : {};
             if (status.status !== 'running') {
+                // The final line gives the run's own status, and the headline of a failure.
                 process.exitCode = status.exit_code ?? 1;
-                return { ...status, ...link };
+                const summary = existsSync(join(directory, 'summary.json')) ? JSON.parse(readFileSync(join(directory, 'summary.json'), 'utf8')) : undefined;
+                const result = runStatus(summary?.status);
+                // A worker command that is not a run (no run record) and exits 0 only finished.
+                if (!result && process.exitCode === 0)
+                    return { ...status, ...link };
+                const failure = result ? summary.failure : unreadableRecord(Error('The run has no readable summary.json.'));
+                return { status: result ?? 'failed', run_dir: directory, exit_code: process.exitCode, ...(failure && result !== 'succeeded' ? { headline: failure.headline } : {}), ...link };
             }
             if (!workerAlive(directory)) {
                 process.exitCode = 1;

package/dist/packages/sdk/src/worker.js

@@ -359,13 +359,14 @@ export function cliExecutor(options = {}) {
                 catch { /* Default. */ }
                 return { status: "waiting", question, ...(typeof timeoutMs === "number" ? { timeoutMs } : {}) };
             }
-            return { status: "failed", error: { code: "needs_input", message: String(summary.error ?? "The run needs input that a production worker cannot give.") } };
+            return { status: "failed", error: { code: "needs_input", message: String(summary.failure?.headline ?? "The run needs input that a production worker cannot give.") } };
         }
+        // Production keeps its own run statuses; the failure record gives the code and the headline.
         if (summary?.status === "failed")
-            return { status: "failed", error: { code: summary.code ?? "execution_failed", message: String(summary.error ?? "The run failed.") } };
+            return { status: "failed", error: { code: summary.failure?.code ?? "execution_failed", message: String(summary.failure?.headline ?? "The run failed.") } };
         const setup = read("setup-error.json");
         if (setup)
-            return { status: "failed", error: { code: setup.code, message: String(setup.error) }, retryable: !finalCodes.has(setup.code) };
+            return { status: "failed", error: { code: setup.code, message: String(setup.headline) }, retryable: !finalCodes.has(setup.code) };
         return { status: "failed", error: { code: "worker_failed", message: `The run process stopped (exit ${code}). See ${join(dir, "worker.stderr.log")}.` }, retryable: true };
     };
 }