@method-ai-hq/sdk 0.18.2 → 0.19.0

package/README.md

@@ -3,7 +3,7 @@
 MIT-licensed JavaScript API and the `method` CLI. Source and releases: https://github.com/method-ai-hq/method-sdk
 
 ```sh
-npm install https://github.com/method-ai-hq/method-sdk/releases/download/v0.18.2/method-ai-hq-sdk-0.18.2.tgz
+npm install https://github.com/method-ai-hq/method-sdk/releases/download/v0.19.0/method-ai-hq-sdk-0.19.0.tgz
 npx method --version
 ```
 

package/dist/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@method-ai-hq/sdk",
-    "version": "0.18.2",
+    "version": "0.19.0",
     "description": "Build and run reusable .method files with checked steps and saved results.",
     "license": "MIT",
     "type": "module",
@@ -157,6 +157,11 @@
             "import": "./dist/packages/sdk/src/versions.js",
             "default": "./dist/packages/sdk/src/versions.js"
         },
+        "./merge": {
+            "types": "./dist/packages/sdk/src/merge.d.ts",
+            "import": "./dist/packages/sdk/src/merge.js",
+            "default": "./dist/packages/sdk/src/merge.js"
+        },
         "./outbox": {
             "types": "./dist/packages/sdk/src/outbox.d.ts",
             "import": "./dist/packages/sdk/src/outbox.js",

package/dist/packages/sdk/src/current-runtime.d.ts

@@ -5,6 +5,11 @@ import type { parse } from "./local-cli.js";
 export { executeMethod as runCurrentMethod };
 /** Recent run folders on this computer, newest first. The runtime reuses only iterations whose key matches. */
 export declare function recentRuns(exclude: string, limit?: number): string[];
+/**
+ * A step that stopped because a file is not there (ENOENT, or FileNotFoundError in Python) needs that file on this
+ * computer: the failure names the file and who saved this version, with owner setup.
+ */
+export declare function missingFileFailure(failure: any, file: string, savedBy: string | null): any;
 /** Answers for ask steps: a key without an iteration ("confirm") answers its first iteration ("confirm:0"). */
 export declare function answers(human: any): any;
 /**
@@ -13,4 +18,4 @@ export declare function answers(human: any): any;
  * runSecrets are values that the SDK gives this run only (such as the signed-in key for improve.method); they come
  * before the shell and the secret store, and are never saved.
  */
-export declare function runCurrentFile(file: string, flags: ReturnType<typeof parse>["values"], syncFactory?: () => MethodSync, onEvent?: (event: any) => Promise<void>, client?: MethodClient, baseConfig?: any, runSecrets?: Record<string, string>): Promise<import("@withmethod/runtime/api-types.js").RunResult>;
+export declare function runCurrentFile(file: string, flags: ReturnType<typeof parse>["values"], syncFactory?: () => MethodSync, onEvent?: (event: any) => Promise<void>, client?: MethodClient, baseConfig?: any, runSecrets?: Record<string, string>, savedBy?: string | null): Promise<import("@withmethod/runtime/api-types.js").RunResult>;

package/dist/packages/sdk/src/current-runtime.js

@@ -2,7 +2,10 @@ import { managedClassification } from './classification-client.js';
 import { MethodClient } from './method-client.js';
 import { openBrowser } from './browser.js';
 import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
-import { join, dirname, resolve } from 'node:path';
+import { join, dirname, resolve, relative, isAbsolute } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { lastSaved } from './outbox.js';
+import { loadWorkflow } from '../../workflow-language/src/validate.js';
 import { hostedModelsFor, managedModels } from './hosted-models.js';
 import { localAgent } from '@withmethod/runtime/agents.js';
 import { resolveSecrets } from './secrets.js';
@@ -41,6 +44,32 @@ export function recentRuns(exclude, limit = 20) {
     }
     return [...found].sort((a, b) => b[1] - a[1]).slice(0, limit).map(([dir]) => dir);
 }
+/** Who saved the version that a file holds, when this computer got or saved that version last. */
+function savedByOf(server, method) {
+    try {
+        if (typeof method?.id !== 'string')
+            return null;
+        const { id: _id, ...content } = method, record = lastSaved(server, method.id);
+        return record?.saved_by && isDeepStrictEqual(loadWorkflow(content), record.workflow) ? record.saved_by : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A step that stopped because a file is not there (ENOENT, or FileNotFoundError in Python) needs that file on this
+ * computer: the failure names the file and who saved this version, with owner setup.
+ */
+export function missingFileFailure(failure, file, savedBy) {
+    const text = [failure.details, failure.diagnostics, ...(failure.evidence ?? [])].filter(Boolean).join('\n');
+    const found = /ENOENT: no such file or directory, \w+ '([^']+)'/.exec(text)?.[1] ?? /FileNotFoundError: \[Errno 2\] No such file or directory: '([^']+)'/.exec(text)?.[1];
+    if (!found)
+        return failure;
+    const folder = dirname(resolve(file)), inside = relative(folder, resolve(folder, found));
+    const shown = !inside.startsWith('..') && !isAbsolute(inside) ? inside : found;
+    return { ...failure, owner: 'setup', headline: `This Method reads ${shown}. It is not on this computer and is not saved in the Method.${savedBy ? ` Ask ${savedBy} (who saved this version) for it.` : ''}`,
+        next: { action: 'fix_setup', text: `Put ${shown} on this computer, then run again. Steps that finished are reused.` } };
+}
 /** Answers for ask steps: a key without an iteration ("confirm") answers its first iteration ("confirm:0"). */
 export function answers(human) {
     if (!human?.steps)
@@ -53,7 +82,7 @@ export function answers(human) {
  * runSecrets are values that the SDK gives this run only (such as the signed-in key for improve.method); they come
  * before the shell and the secret store, and are never saved.
  */
-export async function runCurrentFile(file, flags, syncFactory, onEvent, client = new MethodClient(flags.server), baseConfig, runSecrets = {}) {
+export async function runCurrentFile(file, flags, syncFactory, onEvent, client = new MethodClient(flags.server), baseConfig, runSecrets = {}, savedBy) {
     if (flags.resume && !flags['run-dir'])
         throw Error('Resume needs --run-dir.');
     flags = { ...flags, 'run-dir': flags['run-dir'] ?? join(process.cwd(), '.method-runs', randomUUID()) };
@@ -84,6 +113,10 @@ export async function runCurrentFile(file, flags, syncFactory, onEvent, client =
         }
         catch { /* the run's setup failure */ }
         await sync?.start(method, inputs, {}, false);
+        // Every key that this computer lacks, in one list, before any setup or step.
+        const missingKeys = Object.keys(method.secrets ?? {}).filter(key => !runSecrets[key] && !resolveSecrets([key])[key]);
+        if (missingKeys.length)
+            throw Object.assign(Error(`This Method needs ${missingKeys.length === 1 ? 'a key that is' : 'keys that are'} not on this computer: ${missingKeys.join(', ')}. Run ${missingKeys.map(key => `\`method secret set ${key}\``).join(', then ')}`), { code: 'missing_secret', owner: 'setup', missing: missingKeys });
         const setup = await localSetup(file, flags, baseConfig);
         let config = setup.config;
         const sourceRoot = setup.sourceRoot;
@@ -156,6 +189,18 @@ export async function runCurrentFile(file, flags, syncFactory, onEvent, client =
                 process.stderr.write(JSON.stringify(event) + "\n"); },
         });
         runFailed = !['completed', 'unconfirmed'].includes(result.status);
+        if (result.status === 'failed' && result.failure) {
+            const named = missingFileFailure(result.failure, file, savedBy !== undefined ? savedBy : savedByOf(client.server, method));
+            // The run's record says it too, so the dashboard and method wait show the same failure.
+            const summary = join(authoringPath(flags['run-dir']), 'summary.json');
+            if (named !== result.failure) {
+                result.failure = named;
+                try {
+                    writePrivateJson(summary, { ...JSON.parse(readFileSync(summary, 'utf8')), failure: named });
+                }
+                catch { /* no record to change */ }
+            }
+        }
         const synced = await sync?.finish();
         let display = synced ? { ...result, dashboard: sync.dashboard, dashboard_sync: synced } : result;
         // A run that waits for a person shows the question itself, so the agent can ask the user and pass on the answer.

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

@@ -1,46 +1,50 @@
 /**
  * Each Method has one home file on this computer: the file its versions are saved from. A copy in a temporary folder,
  * or in another folder while the home file still exists, is not saved, so one Method never grows two histories.
- * Git worktrees and clones of one repository share a home. The home record also holds what the last save or checkout
- * wrote, so an unchanged home file can take a newer version from the account.
+ * Git worktrees and clones of one repository share a home.
  */
 export type Home = {
     path: string;
     key: string;
-    version_id?: string;
-    files?: Record<string, string>;
 };
 export declare function readHome(server: string, methodId: string): Home | undefined;
 export declare const temporary: (path: string) => boolean;
 /** The same file in every checkout of one repository has the same key. */
 export declare function homeKey(file: string): string;
-/** What a save or checkout wrote: the Method file and each package file, by hash. */
-export declare function writtenFiles(file: string, packageFiles: Array<{
-    path: string;
-    sha256: string;
-}>): {
-    [x: string]: string;
-};
-export declare function recordHome(server: string, methodId: string, file: string, version?: {
-    version_id: string;
-    files: Record<string, string>;
-}): void;
+export declare function recordHome(server: string, methodId: string, file: string): void;
 /**
  * Throws, with the home file named, when this file may not save the Method. Otherwise this file is the home after
  * the call. A home that is gone, holds another Method, or is a temporary copy gives way to a file outside a
  * temporary folder.
  */
 export declare function claimHome(server: string, methodId: string, file: string): void;
-/** True when every file that the last save or checkout wrote is still unchanged in the home folder. */
-export declare function unchangedSinceSave(home: Home): boolean;
+type Client = Pick<import('./method-client.js').MethodClient, 'server' | 'token' | 'request' | 'transfer'>;
+/** Both texts of one part that this computer and a teammate changed in different ways. */
+export type CombineConflict = {
+    part: string;
+    file: string;
+    yours: unknown;
+    theirs: unknown;
+};
+export type CatchUp = {
+    status: 'skipped' | 'current';
+} | {
+    status: 'offline' | 'updated';
+    line: string;
+} | {
+    status: 'conflict';
+    result: {
+        status: 'needs_you';
+        failure: import('../../workflow-language/src/inspection.js').RunFailure;
+        conflicts: CombineConflict[];
+    };
+};
 /**
- * Before a run of the home file: when nothing in it changed since the last save or checkout on this computer and the
- * account has a newer version (saved from another computer or folder), write that version here first. Says nothing;
- * any problem leaves the files as they are.
+ * Before a run, a fix or a publish of a Method file: bring the file to the newest version of its Method. base is the
+ * version this computer last saved or got, ours the file, theirs the newest version. An unchanged file takes theirs;
+ * a changed one combines step by step and file by file (an empty base when this computer has none). A part that both
+ * sides changed in different ways is a conflict: nothing changes, and the result has both texts. Offline, the file
+ * runs as it is. Signed out, a file with no id: line, or a Method with no version yet: nothing.
  */
-export declare function followAccount(client: {
-    server: string;
-    token(): string | null | undefined;
-    request<T>(path: string): Promise<T>;
-    transfer(path: string): Promise<Uint8Array>;
-}, file: string): Promise<boolean>;
+export declare function catchUp(client: Client, file: string, doing?: string): Promise<CatchUp>;
+export {};

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

@@ -43,13 +43,8 @@ export function homeKey(file) {
     const path = real(authoringPath(file)), repo = repository(path);
     return repo ? `${repo.main}:${relative(repo.root, path)}` : path;
 }
-/** What a save or checkout wrote: the Method file and each package file, by hash. */
-export function writtenFiles(file, packageFiles) {
-    const path = authoringPath(file);
-    return { [relative(dirname(path), path)]: fileHash(readFileSync(path)), ...Object.fromEntries(packageFiles.map(f => [f.path, f.sha256])) };
-}
-export function recordHome(server, methodId, file, version) {
-    writePrivateJson(homeFile(server, methodId), { path: authoringPath(file), key: homeKey(file), ...version });
+export function recordHome(server, methodId, file) {
+    writePrivateJson(homeFile(server, methodId), { path: authoringPath(file), key: homeKey(file) });
 }
 /**
  * Throws, with the home file named, when this file may not save the Method. Otherwise this file is the home after
@@ -60,7 +55,7 @@ export function claimHome(server, methodId, file) {
     const home = readHome(server, methodId), key = homeKey(file);
     if (home && home.key === key) {
         if (home.path !== authoringPath(file))
-            recordHome(server, methodId, file, home.version_id ? { version_id: home.version_id, files: home.files ?? {} } : undefined);
+            recordHome(server, methodId, file);
         return;
     }
     const homeLives = (() => { try {
@@ -73,65 +68,174 @@ export function claimHome(server, methodId, file) {
         throw Object.assign(Error(`This Method is saved from ${home.path}. Make the change in that file and run it there; this copy was not run or saved.`), { code: 'other_home', home: home.path });
     recordHome(server, methodId, file);
 }
-/** True when every file that the last save or checkout wrote is still unchanged in the home folder. */
-export function unchangedSinceSave(home) {
-    if (!home.version_id || !home.files)
-        return false;
-    const root = dirname(home.path);
-    return Object.entries(home.files).every(([name, hash]) => { try {
-        return fileHash(readFileSync(join(root, name))) === hash;
-    }
-    catch {
-        return false;
-    } });
-}
+const list = (word, items) => items.length ? `${word}${items.length === 1 ? '' : 's'} ${items.join(', ')}` : '';
+const parts = (steps, files) => [list('step', steps), list('file', files)].filter(Boolean).join(' and ');
+const clock = (at) => { const date = at ? new Date(at) : undefined; return date && !isNaN(+date) ? ` from ${String(date.getHours()).padStart(2, '0')}:${String(date.getMinutes()).padStart(2, '0')}` : ''; };
+const clip = (text) => text.length > 20_000 ? `${text.slice(0, 20_000)}…` : text;
+const unreachable = (error) => error?.code === 'network' || error?.code === 'stalled' || error?.name === 'TimeoutError' || error?.name === 'AbortError' || error?.status >= 500 || error?.status === 429;
 /**
- * Before a run of the home file: when nothing in it changed since the last save or checkout on this computer and the
- * account has a newer version (saved from another computer or folder), write that version here first. Says nothing;
- * any problem leaves the files as they are.
+ * Before a run, a fix or a publish of a Method file: bring the file to the newest version of its Method. base is the
+ * version this computer last saved or got, ours the file, theirs the newest version. An unchanged file takes theirs;
+ * a changed one combines step by step and file by file (an empty base when this computer has none). A part that both
+ * sides changed in different ways is a conflict: nothing changes, and the result has both texts. Offline, the file
+ * runs as it is. Signed out, a file with no id: line, or a Method with no version yet: nothing.
  */
-export async function followAccount(client, file) {
-    const path = authoringPath(file);
+export async function catchUp(client, file, doing = 'running') {
+    const path = authoringPath(file), root = dirname(path);
+    const { methodContent, methodIdPattern, versionIdFor } = await import('./versions.js');
+    let document;
+    try {
+        document = readDocument(path);
+        if (typeof document.id !== 'string' || !methodIdPattern.test(document.id) || !client.token())
+            return { status: 'skipped' };
+    }
+    catch {
+        return { status: 'skipped' };
+    }
+    const id = document.id, options = { signal: AbortSignal.timeout(5000), stallMs: 5000 };
+    const methodPath = `/api/cli/methods/${encodeURIComponent(id)}`;
+    const { lastSaved, recordCheckout } = await import('./outbox.js');
+    const record = lastSaved(client.server, id);
+    // merge_base: the newest version that the server has as an ancestor of both this computer's version and the newest one.
+    let theirs;
+    try {
+        theirs = await client.request(record?.version_id ? `${methodPath}?base=${encodeURIComponent(record.version_id)}` : methodPath, 'GET', undefined, true, options);
+    }
+    catch (error) {
+        return unreachable(error) ? { status: 'offline', line: `Could not check for a newer version; ${doing} this file.` } : { status: 'skipped' };
+    }
+    const { loadWorkflow } = await import('../../workflow-language/src/validate.js');
+    const { buildPackage } = await import('./method-files.js');
+    // A file that does not load fails its run with its own error.
+    let ours;
     try {
-        const id = (await import('./authoring.js')).readDocument(path).id;
-        if (typeof id !== 'string' || !client.token())
-            return false;
-        const home = readHome(client.server, id);
-        if (!home || home.key !== homeKey(path) || !unchangedSinceSave(home))
-            return false;
-        const latest = await client.request(`/api/cli/methods/${encodeURIComponent(id)}`);
-        if (!latest?.version_id || latest.version_id === home.version_id)
-            return false;
-        const { mkdtempSync, rmSync, copyFileSync, mkdirSync } = await import('node:fs');
-        const { restorePackage } = await import('./method-files.js');
-        const staging = mkdtempSync(join(methodCache(), 'follow-'));
+        const workflow = loadWorkflow(methodContent(document)), { pack } = await buildPackage(path, workflow);
+        ours = { workflow, files: pack.files, version_id: versionIdFor(id, pack.digest) };
+    }
+    catch {
+        return { status: 'skipped' };
+    }
+    const savedBy = theirs.saved_by ?? null;
+    if (ours.version_id === theirs.version_id) {
+        if (record?.version_id !== theirs.version_id)
+            recordCheckout(client.server, id, theirs.version_id, theirs.version_number, theirs.workflow, { saved_by: savedBy });
+        return { status: 'current' };
+    }
+    if (record?.version_id === theirs.version_id)
+        return { status: 'current' };
+    let base = { workflow: {}, files: [] };
+    // An older server sends no merge_base: then the version this computer last saved or got is the base.
+    const baseId = theirs.merge_base !== undefined ? theirs.merge_base : record?.version_id;
+    // This computer's version was kept beside the newest one (an earlier CLI recorded it as its last save): it is combined now.
+    const beside = record?.version_id && baseId !== record.version_id ? record.version_id : undefined;
+    if (record?.version_id && baseId) {
         try {
-            await restorePackage(latest, staging, client);
-            const root = dirname(path), incoming = latest.package?.files ?? [];
-            // A local file that the last save did not write, and that differs, is the user's: then nothing changes.
-            for (const f of incoming) {
-                const local = join(root, f.path);
-                if (existsSync(local) && !home.files?.[f.path] && fileHash(readFileSync(local)) !== f.sha256)
-                    return false;
-            }
-            for (const f of incoming) {
-                mkdirSync(dirname(join(root, f.path)), { recursive: true, mode: 0o700 });
-                copyFileSync(join(staging, f.path), join(root, f.path));
-            }
+            const saved = await client.request(`${methodPath}?version=${encodeURIComponent(baseId)}`, 'GET', undefined, true, options);
+            base = { workflow: saved.workflow, files: saved.package?.files ?? [] };
         }
-        finally {
-            rmSync(staging, { recursive: true, force: true });
+        catch (error) {
+            if (unreachable(error))
+                return { status: 'offline', line: `Could not check for a newer version; ${doing} this file.` };
+            base = { workflow: record.workflow ?? {}, files: [] };
         }
-        const { writeDocument } = await import('./authoring.js');
-        const { methodContent, writeMethodId } = await import('./versions.js');
-        writeDocument(path, methodContent(latest.workflow));
-        (await import('./legacy.js')).convertLegacy(path);
-        writeMethodId(path, id);
-        (await import('./outbox.js')).recordCheckout(client.server, id, latest.version_id, latest.version_number, methodContent(latest.workflow));
-        recordHome(client.server, id, path, { version_id: latest.version_id, files: writtenFiles(path, latest.package?.files ?? []) });
-        return true;
+    }
+    const { mergeMethod, mergeFiles, changedSteps } = await import('./merge.js');
+    const theirFiles = theirs.package?.files ?? [];
+    const steps = mergeMethod(base.workflow, ours.workflow, theirs.workflow), files = mergeFiles(base.files, ours.files, theirFiles);
+    const ourHashes = new Map(ours.files.map(f => [f.path, f.sha256]));
+    // Files that come from theirs. A file here that no save wrote and that differs is the person's own: a conflict too.
+    const incoming = files.files.filter(f => ourHashes.get(f.path) !== f.sha256);
+    const local = (name) => { try {
+        return fileHash(readFileSync(join(root, name)));
     }
     catch {
-        return false;
+        return undefined;
+    } };
+    const { isDeepStrictEqual } = await import('node:util');
+    // After a combine stopped, a part whose text changed on this computer since then is combined by the person: theirs is used.
+    const stop = record?.conflict?.theirs === theirs.version_id ? record.conflict : undefined;
+    const combinedStep = (at, now) => !!stop && at in stop.parts && !isDeepStrictEqual(now, stop.parts[at]);
+    const combinedFile = (at) => !!stop && at in stop.files && (local(at) ?? null) !== stop.files[at];
+    const fileConflicts = [...files.conflicts.map(c => c.path), ...incoming.filter(f => !ourHashes.has(f.path) && local(f.path) !== undefined && local(f.path) !== f.sha256).map(f => f.path)];
+    const stepConflicts = steps.clean ? [] : steps.conflicts;
+    const openSteps = stepConflicts.filter(c => !combinedStep(c.path, c.ours)), openFiles = fileConflicts.filter(at => !combinedFile(at));
+    const keepLocal = new Set(fileConflicts.filter(combinedFile));
+    const take = incoming.filter(f => !keepLocal.has(f.path));
+    const download = async (f) => {
+        const bytes = await client.transfer(`${methodPath}/files/${f.sha256}?version=${encodeURIComponent(theirs.version_id)}`);
+        if (fileHash(bytes) !== f.sha256)
+            throw Error(`The newer version's file ${f.path} does not match its checksum.`);
+        return bytes;
+    };
+    const who = savedBy ?? 'A teammate', name = relative(root, path);
+    if (openSteps.length || openFiles.length) {
+        // Remember this computer's text of each part, so that the next run sees which parts the person combined.
+        const { recordCombineStop } = await import('./outbox.js');
+        recordCombineStop(client.server, id, {
+            theirs: theirs.version_id,
+            parts: Object.fromEntries(stepConflicts.map(c => [c.path, combinedStep(c.path, c.ours) ? stop.parts[c.path] : c.ours])),
+            files: Object.fromEntries(fileConflicts.map(at => [at, combinedFile(at) ? stop.files[at] : local(at) ?? null])),
+        });
+        const conflicts = [];
+        for (const c of openSteps)
+            conflicts.push({ part: c.path.replace(/^steps\./, 'step '), file: name, yours: c.ours, theirs: c.theirs });
+        for (const at of openFiles) {
+            const theirFile = theirFiles.find(f => f.path === at);
+            const text = async () => { try {
+                return clip(Buffer.from(await download(theirFile)).toString('utf8'));
+            }
+            catch (error) {
+                return `(not read: ${error.message})`;
+            } };
+            conflicts.push({ part: `file ${at}`, file: at, yours: (() => { try {
+                    return clip(readFileSync(join(root, at), 'utf8'));
+                }
+                catch {
+                    return null;
+                } })(), theirs: theirFile ? await text() : null });
+        }
+        const where = [...new Set(conflicts.map(c => c.file))];
+        const headline = `${who} also changed ${conflicts.map(c => c.part).join(', ')}. Combine the two texts in ${where.join(' and ')}, then run again.`;
+        return { status: 'conflict', result: { status: 'needs_you', failure: combineFailure(headline, conflicts, who), conflicts } };
     }
+    try {
+        loadWorkflow(steps.workflow);
+    }
+    catch (error) {
+        const headline = `Your changes and ${savedBy ? `${savedBy}'s` : 'the newest'} version combine into a Method that does not load: ${error.message} Combine them in ${name} by hand, then run again.`;
+        return { status: 'conflict', result: { status: 'needs_you', failure: combineFailure(headline, [], who), conflicts: [] } };
+    }
+    // Every file is read before any file changes, so a failed download changes nothing.
+    let written;
+    try {
+        written = await Promise.all(take.map(async (f) => ({ path: f.path, bytes: await download(f) })));
+    }
+    catch (error) {
+        return unreachable(error) ? { status: 'offline', line: `Could not check for a newer version; ${doing} this file.` } : { status: 'skipped' };
+    }
+    const { mkdirSync, renameSync, writeFileSync } = await import('node:fs');
+    const { packagePath } = await import('../../contracts/src/method-package.js');
+    for (const f of written) {
+        const target = resolve(root, packagePath(f.path));
+        mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+        writeFileSync(`${target}.download`, f.bytes, { mode: 0o600 });
+        renameSync(`${target}.download`, target);
+    }
+    if (!isDeepStrictEqual(steps.workflow, ours.workflow))
+        (await import('./proposals.js')).writeMethodFile(path, id, steps.workflow);
+    (await import('./legacy.js')).convertLegacy(path);
+    const fileChanges = (from, to) => [...new Set([...from, ...to].map(f => f.path))].filter(at => from.find(f => f.path === at)?.sha256 !== to.find(f => f.path === at)?.sha256);
+    const yours = parts(changedSteps(base.workflow, ours.workflow), fileChanges(base.files, ours.files));
+    const kept = !isDeepStrictEqual(ours.workflow, base.workflow) || fileChanges(base.files, ours.files).length > 0;
+    // theirs is the parent of the next save; a side version of this computer that the file now combines goes with it.
+    recordCheckout(client.server, id, theirs.version_id, theirs.version_number, theirs.workflow, { saved_by: savedBy, ...(kept && (record?.side_version_id ?? beside) ? { merged_version_id: (record?.side_version_id ?? beside) } : {}) });
+    const changed = parts(changedSteps(base.workflow, theirs.workflow), fileChanges(base.files, theirFiles));
+    return { status: 'updated', line: `Updated to ${savedBy ? `${savedBy}'s` : 'the newest'} version${clock(theirs.saved_at)}${changed ? ` (changed ${changed})` : ''}.${kept ? ` Your changes${yours ? ` to ${yours}` : ''} are kept.` : ''}` };
+}
+/** The failure record of a combine that needs the person: needs_you, with both texts of each part as evidence. */
+function combineFailure(headline, conflicts, who) {
+    const text = (value) => typeof value === 'string' ? value : JSON.stringify(value);
+    return { owner: 'needs_you', code: 'combine_versions', headline, step: null, step_name: null, iteration: null, failed_iterations: [], total: null, phase: 'setup', check_name: null,
+        next: { action: 'fix_method', text: 'Edit the file so that each part keeps both changes, then run again. No run started and no file changed.' },
+        evidence: conflicts.flatMap(c => [`Your ${c.part}: ${text(c.yours)}`, `${who}'s ${c.part}: ${text(c.theirs)}`]) };
 }

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

@@ -14,6 +14,12 @@ export type ImproveJudgment = {
     new?: boolean;
     run?: unknown;
 };
+/** What the loop did with one correction, as the account records it. */
+export type CorrectionOutcome = {
+    id: string;
+    outcome: 'fixed' | 'no_change' | 'already_changed' | 'held';
+    detail?: string;
+};
 /** 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;
@@ -37,6 +43,7 @@ export type ImproveProposal = {
 };
 export type FixOutcome = {
     file: string;
+    judgments: string[];
     corrections: number;
     from_dashboard: number;
     kind: 'change' | 'none';
@@ -64,6 +71,7 @@ export type FixOutcome = {
     capped: string;
     log: string;
     changed?: string;
+    outcomes?: CorrectionOutcome[];
 };
 /**
  * Read the result of improve.method: {proposal: <SubmitProposal as JSON text>, kind, proposal_id, capped}. A change has
@@ -114,6 +122,7 @@ export declare function caseFromCorrection(file: string, judgment: {
     id: string;
     note: string | null;
     corrected?: unknown;
+    noted_by?: string | null;
 }, runDir: string): Promise<{
     id: string;
     made: boolean;
@@ -128,5 +137,21 @@ export declare function fixCorrections(client: MethodClient, file: string, optio
     run?: RunFile;
     waitMs?: number;
 }): Promise<FixOutcome | undefined>;
+/**
+ * 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 declare function fixWaiting(client: MethodClient, file: string, options?: {
+    run?: RunFile;
+    waitMs?: number;
+}): Promise<FixOutcome[] | undefined>;
+/**
+ * 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 declare function fixCorrection(client: MethodClient, file: string, judgmentId: string, options?: {
+    run?: RunFile;
+    pollMs?: 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;