@method-ai-hq/sdk 0.17.3 → 0.18.1

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

@@ -1,57 +1,132 @@
-import { type MethodClient } from './method-client.js';
-/** run_id: the run folder on this computer that the note is about. */
-export type ImproveRequest = {
-    step_id?: string;
-    note?: string;
-    run_id?: string;
+import type { MethodClient } from './method-client.js';
+/** A judgment as improve.method reads it. new marks the corrections to fix now; run is the account record of a run with no folder here. */
+export type ImproveJudgment = {
+    id: string;
+    run_id: string;
+    run_dir?: string;
+    step_id: string | null;
+    verdict: 'right' | 'wrong';
+    note: string | null;
+    corrected?: unknown;
+    case_id?: string;
+    source: string;
+    created_at: string;
+    new?: boolean;
+    run?: unknown;
 };
 /** Runs a local Method file; the default is the runtime that `method run FILE` uses. */
 export type RunFile = (file: string, flags: Record<string, unknown>, syncFactory: undefined, onEvent: undefined, client: MethodClient, baseConfig: undefined, secrets: Record<string, string>) => Promise<{
     status: string;
     result?: unknown;
+    failure?: any;
 }>;
 /** The SubmitProposal that improve.method returns, read from its result. */
 export type ImproveProposal = {
     cause: string;
     workflow: unknown | null;
+    files: {
+        path: string;
+        sha256: string;
+        content_base64: string;
+    }[];
     evidence: {
-        kind: ProposalKind;
+        kind: 'change' | 'none';
         steps?: string[];
         [key: string]: unknown;
     };
 };
-type ProposalKind = 'change' | 'none';
+export type FixOutcome = {
+    file: string;
+    corrections: number;
+    from_dashboard: number;
+    kind: 'change' | 'none';
+    line: string;
+    cause: string;
+    steps: string[];
+    cases: {
+        made: string[];
+        not_made: {
+            id: string;
+            reason: string;
+        }[];
+    };
+    earlier_passed: number;
+    version?: {
+        version_id: string;
+        url: string;
+        undo: string;
+    } | undefined;
+    usage: {
+        model_calls: number;
+        usd: number | null;
+        minutes: number;
+    } | null;
+    capped: string;
+    log: string;
+    changed?: string;
+};
 /**
- * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id}. A change has the
- * tested workflow; none has no workflow.
+ * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id, capped}. A change has
+ * the tested workflow (and a changed package file for a script change); none has no workflow.
  */
-export declare function readImproveResult(result: unknown): ImproveProposal;
-export declare const judgmentsLine = "Method fixes this Method from your judgments. Record the person's reaction: method judge RUN_ID wrong --note \"...\".";
+export declare function readImproveResult(result: unknown): ImproveProposal & {
+    capped: string;
+};
 /**
- * `method improve FILE`. A Method that keeps run content in the account is fixed from the person's judgments
- * (method judge), so this prints that and starts nothing. A Method with device run data (run_data: device, or an
- * organization that keeps run content on devices) runs improve.method on this computer, so its run content stays here,
- * and saves a local proposal.
+ * Download the published improve.method and its files into the Method cache, once per version. For developers of
+ * improve.method: METHOD_IMPROVE_METHOD=PATH runs that local improve.method file instead, from its own folder.
  */
-export declare function improveCommand(args: string[], clientFactory: (server: string) => MethodClient, run?: RunFile): Promise<boolean | undefined>;
-/** Download the published improve.method and its files into the Method cache, once per version. */
 export declare function cachedImproveMethod(client: MethodClient): Promise<{
     file: string;
     root: string;
     version_id: string;
 }>;
 /**
- * Run improve.method on this computer and save its result as a local proposal of the file. The run gets the signed-in
- * key and server as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only: they stay in memory.
+ * Run improve.method on this computer. Its model steps and its scripts' model requests follow the rule of every run:
+ * the user's own Claude Code or Codex first, hosted models only without one. The run gets the signed-in key and server
+ * as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only. Its output goes to a log file.
  */
-export declare function improveOnDevice(client: MethodClient, file: string, request: ImproveRequest, run?: RunFile): Promise<{
-    proposal_id: string;
-    source: string;
-    file: string;
-    kind: ProposalKind;
+export declare function runImprovement(client: MethodClient, file: string, judgments: ImproveJudgment[], runFolders: string[], run?: RunFile): Promise<{
+    log: string;
+    summary: any;
     cause: string;
-    steps: string[];
-    proposal_file: string;
-    next: string;
+    workflow: unknown | null;
+    files: {
+        path: string;
+        sha256: string;
+        content_base64: string;
+    }[];
+    evidence: {
+        kind: "change" | "none";
+        steps?: string[];
+        [key: string]: unknown;
+    };
+    capped: string;
 }>;
-export {};
+/** The ID of the regression case that a correction makes: one per judgment, so a later loop finds it. */
+export declare const correctionCaseId: (judgmentId: string) => string;
+/**
+ * Make the regression case of a correction, even from vague words such as "it's not even redlined": a model writes 1 to
+ * 3 plain sentences from the note and the run's result, and method case new keeps them only when they fail on the run.
+ * A rule that fails nothing gets one more try with the reason. The person's words decide a conflict with an instruction.
+ */
+export declare function caseFromCorrection(file: string, judgment: {
+    id: string;
+    note: string | null;
+    corrected?: unknown;
+}, runDir: string): Promise<{
+    id: string;
+    made: boolean;
+}>;
+/**
+ * Fix the pending corrections of a Method file on this computer: the loop. Returns undefined when nothing waits. It
+ * takes the pending corrections in the account first, so two computers never fix one correction twice, and gives them
+ * back when the loop stops before it decides. A subscription limit or another failure of the model service is a plain
+ * error.
+ */
+export declare function fixCorrections(client: MethodClient, file: string, options?: {
+    run?: RunFile;
+    waitMs?: number;
+}): Promise<FixOutcome | undefined>;
+/** The one line for corrections that waited, printed before method run or method judge goes on. */
+export declare function waitingLine(outcome: FixOutcome): string;

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

@@ -1,20 +1,19 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
-import { parseArgs } from 'node:util';
+import { isDeepStrictEqual } from 'node:util';
 import { MethodPackageSchema, packageDigest, packagePath } from '../../contracts/src/method-package.js';
 import { loadWorkflow } from '../../workflow-language/src/validate.js';
-import { authoringPath, readDocument } from './authoring.js';
-import { DEFAULT_SERVER } from './method-client.js';
+import { readDocument } from './authoring.js';
 import { fileHash } from './method-files.js';
 import { methodCache } from './prepare.js';
 import { writePrivateJson } from './files.js';
-import { currentVersion, methodContent } from './versions.js';
-import { localRuns, saveLocalProposal } from './proposals.js';
-const kinds = ['change', 'none'];
+import { currentVersion, methodContent, methodIdPattern } from './versions.js';
+import { changedSteps, localRuns, saveLocalProposal, writeMethodFile } from './proposals.js';
+import { localJudgments, runFolderIndex } from './local-judgments.js';
 /**
- * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id}. A change has the
- * tested workflow; none has no workflow.
+ * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id, capped}. A change has
+ * the tested workflow (and a changed package file for a script change); none has no workflow.
  */
 export function readImproveResult(result) {
     const value = result;
@@ -30,49 +29,27 @@ export function readImproveResult(result) {
     if (typeof proposal?.cause !== 'string' || !proposal.cause.trim())
         throw Error('The improvement proposal has no cause.');
     const evidence = proposal.evidence;
-    if (!evidence || typeof evidence !== 'object' || !kinds.includes(evidence.kind))
+    if (!evidence || typeof evidence !== 'object' || !['change', 'none'].includes(evidence.kind))
         throw Error('The improvement proposal has no known kind.');
     if (value.kind !== undefined && value.kind !== evidence.kind)
         throw Error(`The improvement run says kind ${String(value.kind)}, but its proposal is kind ${evidence.kind}.`);
     if (evidence.kind === 'change' && (!proposal.workflow || typeof proposal.workflow !== 'object'))
         throw Error('The improvement proposal is a change without a workflow.');
-    return { cause: proposal.cause.trim(), workflow: evidence.kind === 'change' ? proposal.workflow : null, evidence };
+    return { cause: proposal.cause.trim(), workflow: evidence.kind === 'change' ? proposal.workflow : null, files: Array.isArray(proposal.files) ? proposal.files : [], evidence,
+        capped: typeof value.capped === 'string' ? value.capped : '' };
 }
-const nextStep = (file, id, kind) => ({
-    change: `Read the change, then run method apply ${file} ${id}. It does not publish.`,
-    none: 'No change passed the tests.',
-})[kind];
-const print = (value) => process.stdout.write(JSON.stringify(value, null, 2) + '\n');
-export const judgmentsLine = 'Method fixes this Method from your judgments. Record the person\'s reaction: method judge RUN_ID wrong --note "...".';
 /**
- * `method improve FILE`. A Method that keeps run content in the account is fixed from the person's judgments
- * (method judge), so this prints that and starts nothing. A Method with device run data (run_data: device, or an
- * organization that keeps run content on devices) runs improve.method on this computer, so its run content stays here,
- * and saves a local proposal.
+ * Download the published improve.method and its files into the Method cache, once per version. For developers of
+ * improve.method: METHOD_IMPROVE_METHOD=PATH runs that local improve.method file instead, from its own folder.
  */
-export async function improveCommand(args, clientFactory, run) {
-    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { note: { type: 'string' }, step: { type: 'string' }, server: { type: 'string' } } });
-    if (positionals.length !== 1)
-        throw Error('Use method improve FILE [--note TEXT] [--step ID].');
-    const file = authoringPath(positionals[0]), document = readDocument(file), workflow = loadWorkflow(methodContent(document));
-    if (values.step && !Object.hasOwn(workflow.steps, values.step))
-        throw Error(`Step ${values.step} is not in ${positionals[0]}.`);
-    if (values.note !== undefined && !values.note.trim())
-        throw Error('Write the correction after --note.');
-    const request = { ...(values.step ? { step_id: values.step } : {}), ...(values.note ? { note: values.note.trim() } : {}) };
-    const client = clientFactory(values.server ?? DEFAULT_SERVER);
-    if (!client.token())
-        await client.login();
-    if (document.run_data !== 'device' && !await (await import('./method-sync.js')).organizationKeepsContent(client)) {
-        process.stdout.write(judgmentsLine + '\n');
-        return;
-    }
-    // A note is about the newest run of the Method on this computer.
-    const newest = request.note ? (await localRuns(file))[0] : undefined;
-    return print(await improveOnDevice(client, file, { ...request, ...(newest ? { run_id: newest.dir } : {}) }, run));
-}
-/** Download the published improve.method and its files into the Method cache, once per version. */
 export async function cachedImproveMethod(client) {
+    const local = process.env.METHOD_IMPROVE_METHOD;
+    if (local) {
+        const file = resolve(local);
+        if (!existsSync(file))
+            throw Error(`METHOD_IMPROVE_METHOD names ${file}, which does not exist.`);
+        return { file, root: dirname(file), version_id: 'local' };
+    }
     const saved = await client.request('/api/cli/improve/method');
     if (!/^v_[a-f0-9]{32}$/.test(saved.version_id))
         throw Error('Method sent an improvement Method without a version ID.');
@@ -99,46 +76,239 @@ export async function cachedImproveMethod(client) {
     return { file, root, version_id: saved.version_id };
 }
 /**
- * Run improve.method on this computer and save its result as a local proposal of the file. The run gets the signed-in
- * key and server as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only: they stay in memory.
+ * Run improve.method on this computer. Its model steps and its scripts' model requests follow the rule of every run:
+ * the user's own Claude Code or Codex first, hosted models only without one. The run gets the signed-in key and server
+ * as its IMPROVE_API_KEY and IMPROVE_SERVER secrets, for this run only. Its output goes to a log file.
  */
-export async function improveOnDevice(client, file, request, run) {
+export async function runImprovement(client, file, judgments, runFolders, run) {
     const token = client.token();
     if (!token)
-        throw Error('Sign in with method login, then run method improve again.');
-    const secrets = { IMPROVE_API_KEY: token, IMPROVE_SERVER: client.server };
+        throw Error('Sign in with method login, then run method judge again.');
     const improve = await cachedImproveMethod(client);
     const runDir = join(methodCache(), 'runs', randomUUID());
-    const inputs = join(runDir, 'improve-inputs.json');
-    writePrivateJson(inputs, { method_file: file, note: request.note ?? '', step_id: request.step_id ?? '', grant_id: '', judgment_id: '', run_id: request.run_id ?? '' });
+    mkdirSync(runDir, { recursive: true, mode: 0o700 });
+    const judgmentsFile = join(runDir, 'judgments.json'), inputs = join(runDir, 'improve-inputs.json'), log = join(runDir, 'improve.log');
+    // The judgments with their notes go in a private file of this run; they stay on this computer.
+    writePrivateJson(judgmentsFile, judgments);
+    writePrivateJson(inputs, { method_file: file, grant_id: '', judgment_id: '', judgments_file: judgmentsFile, run_folders: runFolders });
     const runFile = run ?? (await import('./current-runtime.js')).runCurrentFile;
-    process.stderr.write(`Improving ${file} on this computer. Its run content stays here.\n`);
-    // The run prints its own result; send it to stderr so that stdout holds only the proposal.
-    const write = process.stdout.write;
-    process.stdout.write = ((chunk, ...rest) => process.stderr.write(chunk, ...rest));
+    // The run prints its own result and progress; they go to the log, so the person reads one line.
+    const out = process.stdout.write, err = process.stderr.write;
+    const toLog = ((chunk, ...rest) => { try {
+        appendFileSync(log, typeof chunk === 'string' ? chunk : Buffer.from(chunk));
+    }
+    catch { /* the log is best effort */ } const done = rest.find(r => typeof r === 'function'); done?.(); return true; });
+    process.stdout.write = toLog;
+    process.stderr.write = toLog;
     let result;
     try {
-        result = await runFile(improve.file, { inputs, 'run-dir': runDir, workspace: improve.root, server: client.server }, undefined, undefined, client, undefined, secrets);
+        result = await runFile(improve.file, { inputs, 'run-dir': join(runDir, 'run'), workspace: improve.root, server: client.server }, undefined, undefined, client, undefined, { IMPROVE_API_KEY: token, IMPROVE_SERVER: client.server });
     }
     finally {
-        process.stdout.write = write;
+        process.stdout.write = out;
+        process.stderr.write = err;
     }
     if (result.status !== 'completed')
-        throw Error(`The improvement run stopped with status ${result.status}. Its records are in ${runDir}.`);
-    let submitted;
+        throw Object.assign(Error(result.failure?.headline ?? `The improvement stopped with status ${result.status}.`), { log });
+    const summary = (() => { try {
+        return JSON.parse(readFileSync(join(runDir, 'run', 'summary.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    } })();
+    return { ...readImproveResult(result.result), log, summary };
+}
+/** The ID of the regression case that a correction makes: one per judgment, so a later loop finds it. */
+export const correctionCaseId = (judgmentId) => `correction-${judgmentId.replace(/^jdg_/, '').slice(0, 12)}`;
+const caseSchema = { type: 'object', properties: { criteria: { type: 'array', items: { type: 'string', description: 'One plain sentence that a right result meets.' } } } };
+/**
+ * Make the regression case of a correction, even from vague words such as "it's not even redlined": a model writes 1 to
+ * 3 plain sentences from the note and the run's result, and method case new keeps them only when they fail on the run.
+ * A rule that fails nothing gets one more try with the reason. The person's words decide a conflict with an instruction.
+ */
+export async function caseFromCorrection(file, judgment, runDir) {
+    const id = correctionCaseId(judgment.id);
+    if (existsSync(join(dirname(file), 'cases', id, 'case.json')))
+        return { id, made: false };
+    const { outcomeOfRun, createCase } = await import('@withmethod/runtime/cases.js');
+    const outcome = await outcomeOfRun(runDir);
+    const method = readDocument(file);
+    const ref = typeof method.result === 'string' ? method.result.split('.')[0] : undefined;
+    if (!ref)
+        throw Error('The Method has a result with several values, so the case needs an output to judge.');
+    const value = outcome.outputs?.[ref] ?? outcome.result;
+    const note = judgment.note?.trim() || 'The person marked this result wrong.';
+    const { callModel } = await import('./model-call.js');
+    const { preparedConfig } = await import('./quality.js');
+    const prepared = await preparedConfig(file, {}, { judge: true });
+    const user = [`The person's correction, in their words:\n${note}`,
+        judgment.corrected !== undefined && judgment.corrected !== null ? `The result the person says is right:\n${clip(typeof judgment.corrected === 'string' ? judgment.corrected : JSON.stringify(judgment.corrected, null, 2), 20_000)}` : '',
+        `The Method's goal: ${String(method.goal ?? '')}`, `The result of the run (${ref}):\n${clip(typeof value === 'string' ? value : JSON.stringify(value, null, 2), 40_000)}`].filter(Boolean).join('\n\n');
+    let reason = '';
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const answer = await callModel({ schema: caseSchema, user: reason ? `${user}\n\nYour last sentences could not be used: ${reason}` : user,
+            system: 'A person corrected the result of a run of a Method. Write 1 to 3 plain sentences that a right result of this run meets and that this result does not meet, so a later version can be checked against the correction. The person\'s words may be vague, such as "the Ashby one\'s wrong" or "it\'s not even redlined": use the result to find what they mean. Each sentence names one checkable thing in the result, without names or numbers that only this run has unless the correction is about them. Do not ask for anything that the correction does not ask for.' });
+        const criteria = (Array.isArray(answer.value?.criteria) ? answer.value.criteria : []).map((c) => String(c).trim()).filter(Boolean).slice(0, 3);
+        if (!criteria.length) {
+            reason = 'There were no sentences.';
+            continue;
+        }
+        try {
+            await createCase({ methodFile: file, runDir, id, note, rubric: criteria, ref: `outputs.${ref}`, acceptConflict: note, config: prepared.config,
+                options: { runOptions: { processPath: prepared.processPath, ...(prepared.hostedModels ? { hostedModels: prepared.hostedModels } : {}) } } });
+            return { id, made: true };
+        }
+        catch (error) {
+            if (!['case_not_red', 'case_vacuous', 'case_invalid'].includes(error.code))
+                throw error;
+            reason = error.message;
+        }
+    }
+    throw Object.assign(Error(reason), { code: 'case_not_made' });
+}
+const clip = (text, max) => text.length > max ? `${text.slice(0, max)}…` : text;
+/** The Method's judgments: the account's, with the notes that stay on this computer for a device Method. */
+async function methodJudgments(client, file, methodId, waitMs) {
+    const { judgments } = await client.request(`/api/cli/methods/${encodeURIComponent(methodId)}/judgments`, 'GET', undefined, true, waitMs ? { signal: AbortSignal.timeout(waitMs), stallMs: waitMs } : {});
+    const local = new Map(localJudgments(file).map(j => [j.id, j]));
+    const folders = runFolderIndex();
+    return judgments.map(j => {
+        const kept = local.get(j.id);
+        return { ...j, note: j.note ?? kept?.note ?? null, corrected: j.corrected ?? kept?.corrected ?? null, run_dir: kept?.run_dir && existsSync(kept.run_dir) ? kept.run_dir : folders.get(j.run_id) };
+    });
+}
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+/**
+ * Fix the pending corrections of a Method file on this computer: the loop. Returns undefined when nothing waits. It
+ * takes the pending corrections in the account first, so two computers never fix one correction twice, and gives them
+ * back when the loop stops before it decides. A subscription limit or another failure of the model service is a plain
+ * error.
+ */
+export async function fixCorrections(client, file, options = {}) {
+    const document = readDocument(file);
+    const methodId = typeof document.id === 'string' && methodIdPattern.test(document.id) ? document.id : undefined;
+    if (!methodId || !client.token())
+        return undefined;
+    const all = await methodJudgments(client, file, methodId, options.waitMs);
+    const waiting = all.filter(j => j.pending && j.verdict === 'wrong');
+    if (!waiting.length)
+        return undefined;
+    const handled = (ids, value) => client.request(`/api/cli/methods/${encodeURIComponent(methodId)}/judgments/handled`, 'POST', { ids, handled: value });
+    const taken = new Set((await handled(waiting.map(j => j.id), true)).changed);
+    const fresh = waiting.filter(j => taken.has(j.id));
+    if (!fresh.length)
+        return undefined;
+    const fromDashboard = fresh.filter(j => j.source === 'dashboard').length;
+    process.stderr.write(`Fixing ${basename(file)} from ${plural(fresh.length, 'correction')} on this computer. This takes a few minutes.\n`);
+    const base = methodContent(document), baseVersion = await currentVersion(file).catch(() => undefined);
+    let decided = false;
     try {
-        submitted = readImproveResult(result.result);
+        // A regression case per correction, so every later change is checked against it.
+        const cases = { made: [], not_made: [] };
+        for (const j of fresh) {
+            if (!j.run_dir) {
+                cases.not_made.push({ id: j.id, reason: 'The run is not on this computer.' });
+                continue;
+            }
+            try {
+                const made = await caseFromCorrection(file, j, j.run_dir);
+                if (made.made)
+                    cases.made.push(made.id);
+            }
+            catch (error) {
+                if (error.code !== 'case_not_made' && error.owner !== 'agent_work')
+                    throw error;
+                cases.not_made.push({ id: j.id, reason: error.message });
+            }
+        }
+        // A judged run with no folder here (a cloud run) comes as its account record.
+        const freshIds = new Set(fresh.map(j => j.id));
+        const judgments = [];
+        for (const j of all) {
+            const caseId = correctionCaseId(j.id);
+            const run = !j.run_dir && (freshIds.has(j.id) || j.verdict === 'wrong') ? await client.request(`/api/workspace/runs/${encodeURIComponent(j.run_id)}`).then(r => r.run).catch(() => undefined) : undefined;
+            judgments.push({ id: j.id, run_id: j.run_id, ...(j.run_dir ? { run_dir: j.run_dir } : {}), step_id: j.step_id, verdict: j.verdict, note: j.note, ...(j.corrected !== null ? { corrected: j.corrected } : {}),
+                ...(existsSync(join(dirname(file), 'cases', caseId, 'case.json')) ? { case_id: caseId } : {}), source: j.source, created_at: j.created_at, ...(freshIds.has(j.id) ? { new: true } : {}),
+                ...(run ? { run: { id: run.id, status: run.status, created_at: run.created_at, version_id: run.workflow_version_id, inspection: run.inspection } } : {}) });
+        }
+        const runFolders = (await localRuns(file)).map(r => r.dir);
+        const improved = await runImprovement(client, file, judgments, runFolders, options.run);
+        decided = true;
+        const evidence = improved.evidence;
+        const earlier = (evidence.cases ?? []).filter((c) => !c.target && c.after === 'pass').length;
+        const usage = evidence.budget ?? null;
+        const used = usage ? ` (${plural(usage.model_calls, 'model call')}, ${usage.minutes < 1 ? 'under a minute' : `${Math.round(usage.minutes)} min`}${typeof usage.usd === 'number' ? `, $${usage.usd.toFixed(2)}` : ''})` : '';
+        const outcome = { file, corrections: fresh.length, from_dashboard: fromDashboard, cause: improved.cause, cases, earlier_passed: earlier, usage, capped: improved.capped, log: improved.log };
+        const record = (kind, extra = {}) => saveLocalProposal(file, { id: `lp_${randomBytes(8).toString('hex')}`, method_id: methodId, base_version_id: baseVersion?.version_id ?? null,
+            status: kind, cause: improved.cause, evidence, created_at: new Date().toISOString(), base_workflow: base, proposed_workflow: improved.workflow, judgments: [...freshIds], ...extra });
+        if (evidence.kind !== 'change') {
+            record('none');
+            const why = improved.cause.replace(/^No safe change was found\.\s*/, '').split('\n')[0].slice(0, 300);
+            return { ...outcome, kind: 'none', steps: evidence.steps ?? [], line: `No safe change found: ${why}${used}` };
+        }
+        // The file must be the one the loop started from; a change made meanwhile is not overwritten.
+        if (!isDeepStrictEqual(methodContent(readDocument(file)), base)) {
+            record('none', { reason: 'The file changed while Method fixed it.' });
+            return { ...outcome, kind: 'none', steps: evidence.steps ?? [], line: `No change applied: ${basename(file)} changed while Method fixed it. Run method judge again to fix it on the new file.` };
+        }
+        // The version before the change is saved too, so the Method's history has it to restore.
+        const { Outbox } = await import('./outbox.js');
+        const outbox = new Outbox(client);
+        const before = await (await import('./versions.js')).prepareVersion(client, outbox, file).catch(() => undefined);
+        const steps = applyChange(file, methodId, improved);
+        const version = await saveFixedVersion(client, outbox, file, methodId, improved.cause, before?.version_id);
+        record('applied', { applied_at: new Date().toISOString(), ...(version ? { applied_version_id: version.version_id } : {}) });
+        const changed = `Changed ${steps.length ? `step ${steps.join(', ')}` : 'its files'} of ${basename(file)}: ${improved.cause}`, undo = version ? ` ${version.undo}` : '';
+        return { ...outcome, kind: 'change', steps, version, changed: `${changed}${undo}${used}`,
+            line: `${changed} It fixes the corrected run and passes ${plural(earlier, 'earlier correction')}.${undo}${used}` };
     }
     catch (error) {
-        throw Error(`${error.message} Its records are in ${runDir}.`);
+        // Stopped before it decided: the corrections wait for the next loop.
+        if (!decided)
+            await handled([...taken], false).catch(() => undefined);
+        throw error;
     }
-    const id = `lp_${randomBytes(8).toString('hex')}`, document = readDocument(file);
-    const path = saveLocalProposal(file, {
-        id, method_id: typeof document.id === 'string' ? document.id : null, base_version_id: (await currentVersion(file))?.version_id ?? null,
-        status: 'open', cause: submitted.cause, evidence: submitted.evidence, created_at: new Date().toISOString(),
-        base_workflow: methodContent(document), proposed_workflow: submitted.workflow,
-        improvement: { version_id: improve.version_id, run_dir: runDir },
-    });
-    const kind = submitted.evidence.kind;
-    return { proposal_id: id, source: 'local', file, kind, cause: submitted.cause, steps: submitted.evidence.steps ?? [], proposal_file: path, next: nextStep(file, id, kind) };
+}
+/** Write the tested change: the Method content (its id: line kept) and a changed package file of a script change. */
+function applyChange(file, methodId, improved) {
+    const before = methodContent(readDocument(file));
+    loadWorkflow(improved.workflow);
+    if (!isDeepStrictEqual(improved.workflow, before))
+        writeMethodFile(file, methodId, improved.workflow);
+    const folder = dirname(resolve(file));
+    for (const changed of improved.files) {
+        const path = resolve(folder, packagePath(changed.path));
+        if (!path.startsWith(folder + sep))
+            throw Error(`The change names a file outside the Method folder: ${changed.path}`);
+        const bytes = Buffer.from(changed.content_base64, 'base64');
+        if (fileHash(bytes) !== changed.sha256)
+            throw Error(`The changed file ${changed.path} does not match its sha256.`);
+        writeFileSync(path, bytes);
+    }
+    return changedSteps(before, improved.workflow);
+}
+/**
+ * Save the fixed file as a new version of the Method, with the cause as its reason. The version before stays in the
+ * Method's history: restoring it on the Method page undoes the change.
+ */
+async function saveFixedVersion(client, outbox, file, methodId, cause, previous) {
+    try {
+        const { savedVersions } = await import('./outbox.js');
+        const { prepareVersion } = await import('./versions.js');
+        const version = await prepareVersion(client, outbox, file, `Method fixed it from a correction: ${cause}`.slice(0, 500));
+        await outbox.drain();
+        if (!await outbox.whenSaved(version.version_id))
+            return undefined;
+        const number = previous && await outbox.whenSaved(previous) ? savedVersions(client.server)[previous]?.version_number : undefined;
+        const undo = previous && number ? `To undo it, restore version ${number}: ${client.server}/methods/${methodId}?version=${previous}` : 'The version before it is in its history on the Method page.';
+        return { version_id: version.version_id, url: version.url, undo };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The one line for corrections that waited, printed before method run or method judge goes on. */
+export function waitingLine(outcome) {
+    const what = outcome.from_dashboard === outcome.corrections ? `${plural(outcome.corrections, 'correction')} from the dashboard` : plural(outcome.corrections, 'correction');
+    return outcome.kind === 'change' ? `${what}: fixed, passes ${plural(outcome.earlier_passed, 'earlier correction')}. ${outcome.changed}` : `${what}: ${outcome.line}`;
 }

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

@@ -1,4 +1,5 @@
 import { type MethodClient } from './method-client.js';
+import { type RunFile } from './improve.js';
 export declare const maxNoteLength = 4000;
 export declare const maxCorrectedBytes: number;
 export type Judgment = {
@@ -11,10 +12,17 @@ export type Judgment = {
 };
 /** The corrected result in a file: its JSON value when it parses as JSON, or else its text. */
 export declare function correctedValue(path: string): unknown;
-/** The one line that says what was recorded. */
-export declare function judgmentLine(judgment: Pick<Judgment, 'verdict' | 'step_id'>, fixing: boolean): string;
+/** The line that says what was recorded. */
+export declare function judgmentLine(judgment: Pick<Judgment, 'verdict' | 'step_id'>): string;
 /**
  * `method judge RUN_ID right|wrong [--step ID] [--note TEXT] [--corrected FILE] [--json]`: record the person's reaction
- * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both.
+ * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both. When the run's
+ * content stays on this computer (run_data: device), the account gets the verdict and step only, and the judgment with
+ * its note and corrected result goes in .method/judgments.jsonl next to the Method file. A wrong judgment then fixes the
+ * Method here, in the foreground: method judge makes a regression case from the note, finds a change with the user's
+ * own Claude Code or Codex, and applies it only when it fixes the run and breaks no earlier correction. It prints one
+ * line: what changed, or why nothing did.
  */
-export declare function judgeCommand(args: string[], clientFactory: (server: string) => MethodClient): Promise<void>;
+export declare function judgeCommand(args: string[], clientFactory: (server: string) => MethodClient, options?: {
+    run?: RunFile;
+}): Promise<void>;

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

@@ -1,6 +1,10 @@
-import { readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
 import { parseArgs } from 'node:util';
 import { DEFAULT_SERVER } from './method-client.js';
+import { deviceRun, findRunFolder, methodFileOfRun, saveLocalJudgment } from './local-judgments.js';
+import { fixCorrections, waitingLine } from './improve.js';
+import { readHome } from './home.js';
 export const maxNoteLength = 4000;
 export const maxCorrectedBytes = 1024 * 1024;
 /** The corrected result in a file: its JSON value when it parses as JSON, or else its text. */
@@ -22,15 +26,20 @@ export function correctedValue(path) {
         return text;
     }
 }
-/** The one line that says what was recorded. */
-export function judgmentLine(judgment, fixing) {
-    return `Recorded: ${judgment.verdict}${judgment.step_id ? ` on step ${judgment.step_id}` : ''}.${fixing ? ' Method is fixing it in the background.' : ''}`;
+/** The line that says what was recorded. */
+export function judgmentLine(judgment) {
+    return `Recorded: ${judgment.verdict}${judgment.step_id ? ` on step ${judgment.step_id}` : ''}.`;
 }
 /**
  * `method judge RUN_ID right|wrong [--step ID] [--note TEXT] [--corrected FILE] [--json]`: record the person's reaction
- * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both.
+ * to a run's result. RUN_ID is the dashboard run ID or this computer's run ID; the server resolves both. When the run's
+ * content stays on this computer (run_data: device), the account gets the verdict and step only, and the judgment with
+ * its note and corrected result goes in .method/judgments.jsonl next to the Method file. A wrong judgment then fixes the
+ * Method here, in the foreground: method judge makes a regression case from the note, finds a change with the user's
+ * own Claude Code or Codex, and applies it only when it fixes the run and breaks no earlier correction. It prints one
+ * line: what changed, or why nothing did.
  */
-export async function judgeCommand(args, clientFactory) {
+export async function judgeCommand(args, clientFactory, options = {}) {
     const usage = 'Use method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE].';
     const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
             step: { type: 'string' }, note: { type: 'string' }, corrected: { type: 'string' }, json: { type: 'boolean' }, server: { type: 'string' }
@@ -47,13 +56,40 @@ export async function judgeCommand(args, clientFactory) {
         throw Error(`The note has ${note.length} characters; the most is ${maxNoteLength}.`);
     if (values.step !== undefined && !values.step.trim())
         throw Error('Write the step ID after --step.');
-    const body = { verdict, ...(values.step ? { step_id: values.step.trim() } : {}), ...(note ? { note } : {}),
-        ...(values.corrected !== undefined ? { corrected: correctedValue(values.corrected) } : {}) };
+    const step = values.step?.trim();
+    const corrected = values.corrected !== undefined ? correctedValue(values.corrected) : undefined;
+    // The run on this computer, and the Method file that ran it.
+    const runDir = findRunFolder(runId), device = !!runDir && deviceRun(runDir);
+    const runFile = runDir ? methodFileOfRun(runDir) : undefined;
+    if (device && !runFile && (note || corrected !== undefined))
+        throw Error(`This run's content stays on this computer, so its note stays next to the Method file. Run method judge in the folder of the Method file.`);
+    const content = device ? {} : { ...(note ? { note } : {}), ...(corrected !== undefined ? { corrected } : {}) };
+    const body = { verdict, ...(step ? { step_id: step } : {}), ...content };
     const client = clientFactory(values.server ?? DEFAULT_SERVER);
     const response = await client.request(`/api/cli/runs/${encodeURIComponent(runId)}/judgments`, 'POST', body);
+    if (device && runFile)
+        saveLocalJudgment(runFile, {
+            id: response.judgment.id, run_id: runId, account_run_id: response.judgment.run_id ?? null, run_dir: runDir, method_id: response.judgment.method_id ?? null,
+            file: basename(runFile), step_id: step ?? null, verdict, note: note ?? null, ...(corrected !== undefined ? { corrected } : {}), created_at: response.judgment.created_at,
+        });
+    const recorded = judgmentLine(response.judgment);
+    if (verdict === 'right') {
+        process.stdout.write(values.json ? JSON.stringify({ judgment: response.judgment }, null, 2) + '\n' : recorded + '\n');
+        return;
+    }
+    // The Method file: the one that ran the run, else the Method's home file on this computer.
+    const home = response.judgment.method_id ? readHome(client.server, response.judgment.method_id)?.path : undefined;
+    const file = runFile ?? (home && existsSync(home) ? home : undefined);
+    if (!file) {
+        const line = `${recorded} The Method file is not on this computer, so the next method run of it on a computer fixes it.`;
+        process.stdout.write(values.json ? JSON.stringify({ judgment: response.judgment, fix: null }, null, 2) + '\n' : line + '\n');
+        return;
+    }
+    const fix = await fixCorrections(client, file, options);
     if (values.json) {
-        process.stdout.write(JSON.stringify(response, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ judgment: response.judgment, fix: fix ?? null }, null, 2) + '\n');
         return;
     }
-    process.stdout.write(judgmentLine(response.judgment, !!response.fixing) + '\n');
+    const line = !fix ? `${recorded} Another loop is fixing it.` : fix.corrections > 1 ? `${recorded} ${waitingLine(fix)}` : `${recorded} ${fix.line}`;
+    process.stdout.write(line + '\n');
 }