@method-ai-hq/sdk 0.18.1 → 0.19.0

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

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve, sep } from 'node:path';
 import { randomBytes, randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
@@ -9,7 +9,8 @@ import { fileHash } from './method-files.js';
 import { methodCache } from './prepare.js';
 import { writePrivateJson } from './files.js';
 import { currentVersion, methodContent, methodIdPattern } from './versions.js';
-import { changedSteps, localRuns, saveLocalProposal, writeMethodFile } from './proposals.js';
+import { localRuns, saveLocalProposal, writeMethodFile } from './proposals.js';
+import { changedSteps } from './merge.js';
 import { localJudgments, runFolderIndex } from './local-judgments.js';
 /**
  * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id, capped}. A change has
@@ -154,7 +155,7 @@ export async function caseFromCorrection(file, judgment, runDir) {
             continue;
         }
         try {
-            await createCase({ methodFile: file, runDir, id, note, rubric: criteria, ref: `outputs.${ref}`, acceptConflict: note, config: prepared.config,
+            await createCase({ methodFile: file, runDir, id, note, author: judgment.noted_by ?? null, rubric: criteria, ref: `outputs.${ref}`, acceptConflict: note, config: prepared.config,
                 options: { runOptions: { processPath: prepared.processPath, ...(prepared.hostedModels ? { hostedModels: prepared.hostedModels } : {}) } } });
             return { id, made: true };
         }
@@ -195,14 +196,26 @@ export async function fixCorrections(client, file, options = {}) {
         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)
+    const claimed = waiting.filter(j => taken.has(j.id));
+    if (!claimed.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;
+    const outcomes = [];
+    const report = () => reportOutcomes(client, methodId, outcomes);
     try {
+        // A correction of a step whose text changed since its run is not fixed: the change may already answer it.
+        const stale = await changedSinceRun(client, methodId, claimed, base);
+        outcomes.push(...stale);
+        const fresh = claimed.filter(j => !stale.some(c => c.id === j.id));
+        const fromDashboard = fresh.filter(j => j.source === 'dashboard').length;
+        if (!fresh.length) {
+            decided = true;
+            await report();
+            return { file, judgments: claimed.map(j => j.id), corrections: claimed.length, from_dashboard: claimed.filter(j => j.source === 'dashboard').length, kind: 'none', cause: '', steps: [], cases: { made: [], not_made: [] }, earlier_passed: 0,
+                usage: null, capped: '', log: '', outcomes, line: `Not fixed: ${stale.map(c => c.detail).join(' ')}` };
+        }
+        process.stderr.write(`Fixing ${basename(file)} from ${plural(fresh.length, 'correction')} on this computer. This takes a few minutes.\n`);
         // A regression case per correction, so every later change is checked against it.
         const cases = { made: [], not_made: [] };
         for (const j of fresh) {
@@ -238,11 +251,21 @@ export async function fixCorrections(client, file, options = {}) {
         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 outcome = { file, judgments: claimed.map(j => j.id), corrections: fresh.length, from_dashboard: fromDashboard, cause: improved.cause, cases, earlier_passed: earlier, usage, capped: improved.capped, log: improved.log, outcomes };
         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 });
+        // A change that passes only by breaking another person's case is held: two people want different results.
+        const held = heldBy(file, fresh, evidence);
+        if (held.length) {
+            record('none', { reason: 'held' });
+            outcomes.push(...fresh.map(j => held.find(h => h.id === j.id) ?? { id: j.id, outcome: 'no_change' }));
+            await report();
+            return { ...outcome, kind: 'none', steps: evidence.steps ?? [], line: `Held, nothing changed: ${held.map(h => h.detail).join(' ')} Decide which result is right with them.` };
+        }
         if (evidence.kind !== 'change') {
             record('none');
+            outcomes.push(...fresh.map(j => ({ id: j.id, outcome: 'no_change' })));
+            await report();
             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}` };
         }
@@ -258,6 +281,8 @@ export async function fixCorrections(client, file, options = {}) {
         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 } : {}) });
+        outcomes.push(...fresh.map(j => ({ id: j.id, outcome: 'fixed' })));
+        await report();
         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}` };
@@ -265,10 +290,231 @@ export async function fixCorrections(client, file, options = {}) {
     catch (error) {
         // Stopped before it decided: the corrections wait for the next loop.
         if (!decided)
-            await handled([...taken], false).catch(() => undefined);
-        throw error;
+            await handled([...taken].filter(id => !outcomes.some(o => o.id === id)), false).catch(() => undefined);
+        if (!decided && outcomes.length)
+            await report();
+        throw Object.assign(error instanceof Error ? error : Error(String(error)), { judgments: [...taken] });
     }
 }
+// One fix at a time per Method on this computer. A correction that arrives while a fix runs joins it: the running fix
+// takes every waiting correction in one more pass before it finishes, and writes the outcome of each correction to a
+// file that the method judge command of that correction waits for.
+const fixFolder = (methodId) => join(methodCache(), 'fixes', methodId);
+const fileMethodId = (file) => { const id = readDocument(file).id; return typeof id === 'string' && methodIdPattern.test(id) ? id : undefined; };
+/** Take the Method's lock: a file with this process ID. A lock whose process has stopped is taken over. */
+function takeLock(path) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(path, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 });
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        let pid;
+        try {
+            pid = JSON.parse(readFileSync(path, 'utf8')).pid;
+        }
+        catch { /* written now, or gone */ }
+        if (pid === undefined) {
+            try {
+                if (Date.now() - statSync(path).mtimeMs < 10_000)
+                    return false;
+            }
+            catch {
+                continue;
+            }
+        }
+        else {
+            try {
+                process.kill(pid, 0);
+                return false;
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    return false;
+            }
+        }
+        rmSync(path, { force: true });
+    }
+    return false;
+}
+function saveOutcome(folder, id, outcome) { writePrivateJson(join(folder, `${id}.json`), outcome); }
+/** The saved outcome of a correction, removed once read: a function that returns the fix or throws its error. */
+function takeOutcome(folder, id) {
+    const path = join(folder, `${id}.json`);
+    let saved;
+    try {
+        saved = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    rmSync(path, { force: true });
+    return () => { if ('fix' in saved)
+        return saved.fix; throw Object.assign(Error(saved.error), saved.log ? { log: saved.log } : {}); };
+}
+/**
+ * Fix the waiting corrections of a Method file while holding its lock, pass after pass until none waits, so the
+ * corrections that arrive during a pass join the next. Returns undefined when another fix of the Method holds the lock.
+ */
+export async function fixWaiting(client, file, options = {}) {
+    const methodId = fileMethodId(file);
+    if (!methodId || !client.token())
+        return [];
+    const folder = fixFolder(methodId), lock = join(folder, 'lock');
+    if (!takeLock(lock))
+        return undefined;
+    const fixes = [];
+    try {
+        for (const name of readdirSync(folder)) {
+            const path = join(folder, name);
+            if (name !== 'lock')
+                try {
+                    if (Date.now() - statSync(path).mtimeMs > 86_400_000)
+                        rmSync(path, { force: true });
+                }
+                catch { /* gone */ }
+        }
+        for (;;) {
+            let fix;
+            try {
+                fix = await fixCorrections(client, file, options);
+            }
+            catch (error) {
+                for (const id of error.judgments ?? [])
+                    saveOutcome(folder, id, { error: error.message, ...(error.log ? { log: error.log } : {}) });
+                throw error;
+            }
+            if (!fix)
+                return fixes;
+            for (const id of fix.judgments)
+                saveOutcome(folder, id, { fix });
+            fixes.push(fix);
+        }
+    }
+    finally {
+        rmSync(lock, { force: true });
+    }
+}
+/**
+ * Fix the Method for one correction: run the fix, or, when a fix of the Method already runs on this computer, wait for
+ * the fix that takes this correction. Returns the outcome of the fix that took it, or undefined when no fix here took it.
+ */
+export async function fixCorrection(client, file, judgmentId, options = {}) {
+    const methodId = fileMethodId(file);
+    if (!methodId || !client.token())
+        return undefined;
+    const folder = fixFolder(methodId);
+    let joined = false;
+    for (;;) {
+        const saved = takeOutcome(folder, judgmentId);
+        if (saved)
+            return saved();
+        let ran, failure;
+        try {
+            ran = await fixWaiting(client, file, options);
+        }
+        catch (error) {
+            failure = error;
+            ran = [];
+        }
+        if (ran) {
+            const done = takeOutcome(folder, judgmentId);
+            if (done)
+                return done();
+            if (failure)
+                throw failure;
+            return undefined;
+        }
+        if (!joined) {
+            process.stderr.write(`Method is fixing ${basename(file)} on this computer; this correction joins that fix.\n`);
+            joined = true;
+        }
+        await new Promise(done => setTimeout(done, options.pollMs ?? 500));
+    }
+}
+/** Send what the loop did with each correction. An older server without the route keeps today's record. */
+async function reportOutcomes(client, methodId, outcomes) {
+    if (!outcomes.length)
+        return;
+    try {
+        await client.request(`/api/cli/methods/${encodeURIComponent(methodId)}/judgments/outcomes`, 'POST', { outcomes: outcomes.map(o => ({ id: o.id, outcome: o.outcome, ...(o.detail ? { detail: o.detail.slice(0, 500) } : {}) })) });
+    }
+    catch (error) {
+        if (error?.status !== 404 && !/^404:/.test(String(error?.message)))
+            process.stderr.write(`The account did not record what happened to the corrections: ${error.message}\n`);
+    }
+}
+/** The version that a judged run ran: from its run folder here, else from its account record. */
+async function runVersion(client, j) {
+    if (j.run_dir) {
+        try {
+            const sync = JSON.parse(readFileSync(join(j.run_dir, 'method-sync.json'), 'utf8'));
+            if (typeof sync.version_id === 'string')
+                return sync.version_id;
+        }
+        catch { /* no account link */ }
+    }
+    try {
+        return (await client.request(`/api/workspace/runs/${encodeURIComponent(j.run_id)}`)).run?.workflow_version_id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The corrections of a step whose text in the run's version differs from the file: outcome already_changed, with the
+ * person who saved the newest version when that version has the file's text of the step.
+ */
+async function changedSinceRun(client, methodId, judgments, current) {
+    const changed = [], versions = new Map();
+    let file;
+    try {
+        file = loadWorkflow(current);
+    }
+    catch {
+        return changed;
+    }
+    const saved = (version) => {
+        const key = version ?? '';
+        if (!versions.has(key))
+            versions.set(key, client.request(`/api/cli/methods/${encodeURIComponent(methodId)}${version ? `?version=${encodeURIComponent(version)}` : ''}`).catch(() => undefined));
+        return versions.get(key);
+    };
+    for (const j of judgments) {
+        if (!j.step_id || !Object.hasOwn(file.steps ?? {}, j.step_id))
+            continue;
+        const version = await runVersion(client, j), ran = version ? await saved(version) : undefined;
+        if (!ran?.workflow?.steps || isDeepStrictEqual(ran.workflow.steps[j.step_id], file.steps[j.step_id]))
+            continue;
+        const newest = await saved();
+        const by = newest?.saved_by && isDeepStrictEqual(newest.workflow?.steps?.[j.step_id], file.steps[j.step_id]) ? newest.saved_by : undefined;
+        changed.push({ id: j.id, outcome: 'already_changed', detail: by ? `${by} changed step ${j.step_id} after this run.` : `Step ${j.step_id} changed after this run.` });
+    }
+    return changed;
+}
+/**
+ * The corrections whose tested change breaks a case that another person made (a case that passed before and fails
+ * after), with both names. A case or a correction with no name is not held.
+ */
+function heldBy(file, fresh, evidence) {
+    const broken = (Array.isArray(evidence?.cases) ? evidence.cases : []).filter((c) => !c.target && c.before === 'pass' && c.after !== 'pass').map((c) => {
+        try {
+            const made = JSON.parse(readFileSync(join(dirname(file), 'cases', c.id, 'case.json'), 'utf8'));
+            return { id: c.id, author: made.author, note: String(made.note ?? '') };
+        }
+        catch {
+            return undefined;
+        }
+    }).filter((c) => c?.author);
+    return fresh.flatMap(j => {
+        const other = j.noted_by ? broken.find((c) => c.author !== j.noted_by) : undefined;
+        return other ? [{ id: j.id, outcome: 'held', detail: `A fix for ${j.noted_by}'s correction breaks ${other.author}'s case ${other.id}: ${other.note.slice(0, 200)}`.replace(/[.\s]*$/, '.') }] : [];
+    });
+}
 /** 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));

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

@@ -20,9 +20,21 @@ export declare function judgmentLine(judgment: Pick<Judgment, 'verdict' | 'step_
  * 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.
+ * own Claude Code or Codex, and applies it only when it fixes the run and breaks no earlier correction. When a fix of
+ * the same Method already runs on this computer, the correction joins it: that fix takes it in one more pass, and this
+ * command waits for it. It prints one line: what changed, or why nothing did.
  */
 export declare function judgeCommand(args: string[], clientFactory: (server: string) => MethodClient, options?: {
     run?: RunFile;
 }): Promise<void>;
+/** Two judgments of the same run and step by two people with opposite verdicts: neither is fixed until one is kept. */
+export type HeldPair = {
+    run_id: string;
+    step_id: string | null;
+    judgments: Array<{
+        id: string;
+        verdict: string;
+        noted_by: string | null;
+        note: string | null;
+    }>;
+};

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

@@ -3,8 +3,8 @@ 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';
+import { fixCorrection, waitingLine } from './improve.js';
+import { catchUp, 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. */
@@ -36,15 +36,20 @@ export function judgmentLine(judgment) {
  * 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.
+ * own Claude Code or Codex, and applies it only when it fixes the run and breaks no earlier correction. When a fix of
+ * the same Method already runs on this computer, the correction joins it: that fix takes it in one more pass, and this
+ * command waits for it. It prints one line: what changed, or why nothing did.
  */
 export async function judgeCommand(args, clientFactory, options = {}) {
-    const usage = 'Use method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE].';
+    // The output stream at the start: a fix that runs in this process sends its run's own output to a log meanwhile.
+    const print = process.stdout.write.bind(process.stdout);
+    const usage = 'Use method judge RUN_ID right|wrong [--step STEP_ID] [--note TEXT] [--corrected FILE], or method judge RUN_ID keep JUDGMENT_ID.';
     const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
             step: { type: 'string' }, note: { type: 'string' }, corrected: { type: 'string' }, json: { type: 'boolean' }, server: { type: 'string' }
         } });
     const [runId, verdict] = positionals;
+    if (runId && verdict === 'keep' && positionals.length === 3)
+        return keepCommand(runId, positionals[2], values, clientFactory, options);
     if (!runId || !verdict || positionals.length !== 2)
         throw Error(usage);
     if (verdict !== 'right' && verdict !== 'wrong')
@@ -73,23 +78,78 @@ export async function judgeCommand(args, clientFactory, options = {}) {
             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');
+    // A judgment that contradicts another person's judgment of the same step is held: show both, with the two choices.
+    const pairs = response.held ? await heldPairs(client, response.judgment.method_id, response.judgment.id) : [];
+    if (verdict === 'right' || response.held) {
+        print(values.json ? JSON.stringify({ judgment: response.judgment, ...(pairs.length ? { held: pairs } : {}) }, null, 2) + '\n' : [recorded, ...pairs.map(heldLine)].join('\n') + '\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;
+    return fixAfter(client, response.judgment, recorded, runFile, values, options, pairs, print);
+}
+/** The run's Method file fixes the correction: the file that ran the run, else the Method's home file on this computer. */
+async function fixAfter(client, judgment, recorded, runFile, values, options, pairs, print = process.stdout.write.bind(process.stdout)) {
+    const home = judgment.method_id ? readHome(client.server, judgment.method_id)?.path : undefined;
     const file = runFile ?? (home && existsSync(home) ? home : undefined);
+    const held = pairs.map(heldLine), extra = pairs.length ? { held: pairs } : {};
     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');
+        print(values.json ? JSON.stringify({ judgment, fix: null, ...extra }, null, 2) + '\n' : [line, ...held].join('\n') + '\n');
+        return;
+    }
+    // The fix starts from the newest version; a teammate's change of the same step stops it until the person combines them.
+    const caught = await catchUp(client, file, 'fixing');
+    if (caught.status === 'conflict') {
+        print(values.json ? JSON.stringify({ judgment, fix: null, stopped: caught.result, ...extra }, null, 2) + '\n' : [`${recorded} ${caught.result.failure.headline}`, ...held].join('\n') + '\n');
+        process.exitCode = 2;
         return;
     }
-    const fix = await fixCorrections(client, file, options);
+    if ('line' in caught)
+        process.stderr.write(caught.line + '\n');
+    const fix = await fixCorrection(client, file, judgment.id, options);
     if (values.json) {
-        process.stdout.write(JSON.stringify({ judgment: response.judgment, fix: fix ?? null }, null, 2) + '\n');
+        print(JSON.stringify({ judgment, fix: fix ?? null, ...extra }, null, 2) + '\n');
         return;
     }
     const line = !fix ? `${recorded} Another loop is fixing it.` : fix.corrections > 1 ? `${recorded} ${waitingLine(fix)}` : `${recorded} ${fix.line}`;
-    process.stdout.write(line + '\n');
+    print([line, ...held].join('\n') + '\n');
+}
+/** The held pairs of a Method, from its judgments in the account. Nothing when they cannot be read. */
+async function heldPairs(client, methodId, mine) {
+    if (!methodId)
+        return [];
+    let judgments;
+    try {
+        judgments = (await client.request(`/api/cli/methods/${encodeURIComponent(methodId)}/judgments`)).judgments ?? [];
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map(judgments.map(j => [j.id, j])), pairs = [], seen = new Set();
+    for (const j of judgments) {
+        const other = j.outcome === 'held' && j.held_with ? byId.get(j.held_with) : undefined;
+        if (!other || seen.has(j.id) || seen.has(other.id))
+            continue;
+        seen.add(j.id);
+        seen.add(other.id);
+        const [first, second] = mine === other.id ? [other, j] : [j, other];
+        pairs.push({ run_id: j.run_id, step_id: j.step_id ?? null, judgments: [first, second].map(x => ({ id: x.id, verdict: x.verdict, noted_by: x.noted_by ?? null, note: x.note ?? null })) });
+    }
+    return pairs;
+}
+const heldLine = (pair) => {
+    const said = (j) => `${j.noted_by ?? 'Someone'} says it is ${j.verdict}${j.note ? ` ("${j.note.slice(0, 200)}")` : ''}`;
+    return `Held: ${pair.step_id ? `step ${pair.step_id} of run ${pair.run_id}` : `run ${pair.run_id}`}. ${pair.judgments.map(said).join('; ')}. Nothing is fixed until one is kept: ${pair.judgments.map(j => `method judge ${pair.run_id} keep ${j.id} (${j.noted_by ?? 'this one'}'s)`).join(' or ')}.`;
+};
+/** `method judge RUN keep JUDGMENT_ID`: keep this judgment of a held pair; the other one is set aside. A kept wrong judgment is fixed. */
+async function keepCommand(runId, judgmentId, values, clientFactory, options) {
+    const client = clientFactory(values.server ?? DEFAULT_SERVER);
+    const response = await client.request(`/api/judgments/${encodeURIComponent(judgmentId)}/settle`, 'POST', { keep: true });
+    const kept = response.judgment;
+    const recorded = `Kept ${kept?.noted_by ? `${kept.noted_by}'s judgment` : 'this judgment'}${kept?.verdict ? ` (${kept.verdict})` : ''}; the other one is set aside.`;
+    if (kept?.verdict !== 'wrong' || !kept.method_id) {
+        process.stdout.write(values.json ? JSON.stringify({ judgment: kept ?? { id: judgmentId } }, null, 2) + '\n' : recorded + '\n');
+        return;
+    }
+    const runDir = findRunFolder(runId);
+    return fixAfter(client, kept, recorded, runDir ? methodFileOfRun(runDir) : undefined, values, options, []);
 }

package/dist/packages/sdk/src/local-cli.js

@@ -33,8 +33,6 @@ export function parse(args) {
 export async function run(target, flags, syncFactory) {
     const path = isWorkflowLink(target) ? (await saveWorkflowLink(target, process.cwd())).path : resolve(target);
     (await import("./legacy.js")).convertLegacyOrThrow(path);
-    if (!syncFactory)
-        await (await import("./home.js")).followAccount(new MethodClient(flags.server), path);
     loadWorkflow(methodContent(readDocument(path)));
     const notice = await (await import("./quality.js")).casesNotice(path);
     if (notice)
@@ -85,12 +83,12 @@ async function accountSync(path, flags) {
             return { client, outbox, version, sync: () => new Sync(client, runDir, state.workflow_id, state.version_id, state.id, readDocument(path).run_data === "device", outbox) };
         }
         const method = readDocument(path);
-        const setup = await localSetup(path, flags);
-        const needs = accountNeeds(method, setup.config);
-        if (needs.classification && !client.token())
+        // A setup that fails here fails the run too, and the run sends its failed record.
+        const needs = await localSetup(path, flags).then(setup => accountNeeds(method, setup.config), () => undefined);
+        if (needs?.classification && !client.token())
             await client.login();
         if (!client.token()) {
-            process.stderr.write(`Sign in to keep versions and runs in your account${needs.models ? " and to use hosted models" : ""}: method login\n`);
+            process.stderr.write(`Sign in to keep versions and runs in your account${needs?.models ? " and to use hosted models" : ""}: method login\n`);
             return undefined;
         }
         const version = await prepareVersion(client, outbox, path);

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

@@ -0,0 +1,38 @@
+export type MergeConflict = {
+    path: string;
+    base: unknown;
+    ours: unknown;
+    theirs: unknown;
+};
+/** Not clean: workflow keeps ours at each conflict. */
+export type MergeResult = {
+    clean: true;
+    workflow: any;
+} | {
+    clean: false;
+    conflicts: MergeConflict[];
+    workflow: any;
+};
+/**
+ * Three-way merge of Method documents, per step and per top-level key. base is the version both sides started from
+ * (an empty base when there is none), ours is the local file, and theirs is the other version.
+ */
+export declare function mergeMethod(base: any, ours: any, theirs: any): MergeResult;
+export type PackageFile = {
+    path: string;
+    sha256: string;
+};
+export type FilesMergeResult<T extends PackageFile = PackageFile> = {
+    clean: boolean;
+    files: T[];
+    conflicts: {
+        path: string;
+    }[];
+};
+/**
+ * Three-way merge of a Method's package files, by path and sha256. A file that only one side added, changed or removed
+ * takes that change; a file that both sides changed in different ways is a conflict (ours stays in files).
+ */
+export declare function mergeFiles<T extends PackageFile>(base: T[], ours: T[], theirs: T[]): FilesMergeResult<T>;
+/** The steps whose definition differs between two documents. */
+export declare function changedSteps(before: any, after: any): string[];

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

@@ -0,0 +1,65 @@
+import { isDeepStrictEqual } from 'node:util';
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Keys of ours in their order; a key that only theirs has goes after the key before it in theirs. */
+function keyOrder(ours, theirs) {
+    const keys = Object.keys(ours), theirKeys = Object.keys(theirs);
+    theirKeys.forEach((key, index) => {
+        if (keys.includes(key))
+            return;
+        const before = theirKeys.slice(0, index).reverse().find(other => keys.includes(other));
+        keys.splice(before === undefined ? 0 : keys.indexOf(before) + 1, 0, key);
+    });
+    return keys;
+}
+/**
+ * Three-way merge of Method documents, per step and per top-level key. base is the version both sides started from
+ * (an empty base when there is none), ours is the local file, and theirs is the other version.
+ */
+export function mergeMethod(base, ours, theirs) {
+    if (isDeepStrictEqual(ours, base))
+        return { clean: true, workflow: theirs };
+    if (isDeepStrictEqual(theirs, base) || isDeepStrictEqual(ours, theirs))
+        return { clean: true, workflow: ours };
+    const conflicts = [];
+    const pick = (path, b, o, t) => {
+        if (isDeepStrictEqual(o, t) || isDeepStrictEqual(b, t))
+            return o;
+        if (isDeepStrictEqual(b, o))
+            return t;
+        conflicts.push({ path, base: b, ours: o, theirs: t });
+        return o;
+    };
+    const merge = (path, b, o, t, nested) => {
+        const result = {};
+        for (const key of keyOrder(o, t)) {
+            const at = path ? `${path}.${key}` : key;
+            const value = nested(key) && isObject(o[key]) && isObject(t[key]) && isObject(b?.[key] ?? {})
+                ? merge(at, b?.[key] ?? {}, o[key], t[key], () => false) : pick(at, b?.[key], o[key], t[key]);
+            if (value !== undefined)
+                result[key] = value;
+        }
+        return result;
+    };
+    const workflow = merge('', isObject(base) ? base : {}, ours, theirs, key => key === 'steps');
+    return conflicts.length ? { clean: false, conflicts, workflow } : { clean: true, workflow };
+}
+/**
+ * Three-way merge of a Method's package files, by path and sha256. A file that only one side added, changed or removed
+ * takes that change; a file that both sides changed in different ways is a conflict (ours stays in files).
+ */
+export function mergeFiles(base, ours, theirs) {
+    const byPath = (list) => new Map(list.map(f => [f.path, f]));
+    const b = byPath(base), o = byPath(ours), t = byPath(theirs);
+    const files = [], conflicts = [];
+    for (const path of [...new Set([...o.keys(), ...t.keys(), ...b.keys()])].sort()) {
+        const [bs, os, ts] = [b.get(path)?.sha256, o.get(path)?.sha256, t.get(path)?.sha256];
+        const kept = os === ts || bs === ts ? o.get(path) : bs === os ? t.get(path) : (conflicts.push({ path }), o.get(path));
+        if (kept)
+            files.push(kept);
+    }
+    return { clean: !conflicts.length, files, conflicts };
+}
+/** The steps whose definition differs between two documents. */
+export function changedSteps(before, after) {
+    return [...new Set([...Object.keys(before?.steps ?? {}), ...Object.keys(after?.steps ?? {})])].filter(id => !isDeepStrictEqual(before?.steps?.[id], after?.steps?.[id]));
+}

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

@@ -90,7 +90,7 @@ export class MethodClient {
             throw Object.assign(Error(`${status}: ${title || statusText || "Method returned a non-JSON response"} (${method} ${path}). Local run files are preserved.`), { status });
         }
         if (!ok)
-            throw Object.assign(Error(`${status}: ${String(result.message ?? result.error ?? "Method request failed").slice(0, 1000)}`), { status, code: typeof result.code === 'string' ? result.code.slice(0, 100) : 'method_request_failed' });
+            throw Object.assign(Error(`${status}: ${String(result.message ?? result.error ?? "Method request failed").slice(0, 1000)}`), { status, code: typeof result.code === 'string' ? result.code.slice(0, 100) : 'method_request_failed', body: result });
         return result;
     }
     /** Upload (data) or download bytes. Retries a lost connection or a server error twice; stops only when no bytes move. */