@shardflux/cli 0.24.1 → 0.25.0

package/dist/land.d.ts

@@ -0,0 +1,116 @@
+import type { Ctx } from './commands.js';
+import { conversationClient } from './conversation-commands.js';
+import type { TwinCell } from './worktree-twin.js';
+/** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
+export declare function hubScript(): string;
+export interface HubLanding {
+    state: 'landed' | 'conflict' | 'missing' | 'raced' | 'error';
+    into: string;
+    before?: string | null;
+    after?: string;
+    result?: string;
+    method?: 'ff' | 'merge' | 'already' | 'created';
+    created_result?: boolean;
+    contained?: string[];
+    merge_base?: string | null;
+    stage?: 'integrate' | 'default';
+    conflicts?: string[];
+    source?: string;
+    message?: string;
+    reason?: string;
+}
+/** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
+export declare function landOnHub(cell: TwinCell, input: {
+    result: string;
+    sources: string[];
+    title: string;
+    into?: string;
+    hub?: string;
+}, signal?: AbortSignal): Promise<HubLanding>;
+export interface FolderLanding {
+    path: string;
+    into: string;
+    state: 'landed' | 'already' | 'conflict' | 'waiting' | 'skipped';
+    sha?: string;
+    method?: string;
+    files?: number;
+    kept?: string[];
+    conflicts?: string[];
+    backup?: string | null;
+    reason?: string;
+}
+export interface FolderInput {
+    folder: string;
+    into: string;
+    name: string;
+    title: string;
+    branch: string;
+    base: string;
+    device: string;
+    stateDir: string;
+    hub?: string;
+    quietMs?: number;
+    signal?: AbortSignal;
+    /** How long a busy folder (a file just saved, a Git operation) is waited for before the answer is "waiting". */
+    patienceMs?: number;
+}
+/** The branch to land in: the one checked out in the folder, else the hub's default branch when the folder has it. */
+export declare function folderBranch(folder: string, fallback: string): Promise<string | null>;
+/**
+ * The result into the folder through the twin's landing (from the hub): the branch moves, the person's uncommitted
+ * edits stay, and the landed commit is checked to be on the branch.
+ */
+export declare function landInFolder(cell: TwinCell, f: FolderInput): Promise<FolderLanding>;
+/** The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started. */
+export declare function linkedFolder(ctx: Pick<Ctx, 'store' | 'apiUrl'>, projectId: string, conversationId?: string): string | null;
+export declare const displayPath: (path: string) => string;
+export interface LandOutcome {
+    landed: true;
+    task_id?: string;
+    conversation_id?: string;
+    title: string;
+    result: {
+        branch: string;
+        sha: string;
+    };
+    hub: {
+        into: string;
+        sha: string;
+        method: string;
+    };
+    folder: (FolderLanding & {
+        display: string;
+    }) | null;
+    recorded: boolean;
+    record_error?: string;
+    /** One line for people: "Landed in ~/code/best-todo · 3f2a1c9". */
+    message: string;
+}
+/** What a landing needs: the API, a VM that reads the project hub, the person's folder for a project, this device. */
+export interface LandDeps {
+    client: {
+        tasks: Pick<ReturnType<typeof conversationClient>['tasks'], 'get' | 'recordLanding' | 'steer'>;
+        conversations: Pick<ReturnType<typeof conversationClient>['conversations'], 'get' | 'land'>;
+    };
+    hubCell(projectId: string): Promise<{
+        cell: TwinCell;
+        close(): void;
+    }>;
+    folder(projectId: string, conversationId?: string): string | null;
+    device: string;
+    stateDir: string;
+    hub?: string;
+    quietMs?: number;
+    signal?: AbortSignal;
+}
+export declare function landDeps(ctx: Ctx): LandDeps;
+/** What a landing did, for people: the line, then what was not recorded. */
+export declare function landedText(o: LandOutcome): string;
+/** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
+export declare function landTask(d: LandDeps, taskId: string, opts?: {
+    path?: string;
+}): Promise<LandOutcome>;
+/** `shard conversations land <id> merge`: the conversation's branch into the default branch and its folder, then recorded. */
+export declare function landConversation(d: LandDeps, id: string, opts?: {
+    path?: string;
+}): Promise<LandOutcome>;

package/dist/land.js

@@ -0,0 +1,238 @@
+/**
+ * Landing a result for real (0.25.0+): `shard task land <task>` and `shard conversations land <id> merge`.
+ *
+ * A board task has one result: its master merges its workers' branches into shard/<task id> on the project hub before it
+ * seals done (a master that did not is helped here: its workers' branches are merged into it when they merge cleanly).
+ * Landing then
+ *   1. merges the result into the project's default branch on the hub, in a VM of the project (task-land-hub.py): a
+ *      fast-forward, or a merge commit when the merge is clean, never by force; and checks there that the result
+ *      commit is contained in the branch;
+ *   2. brings it into the person's linked folder on this computer through the live twin's own landing
+ *      (worktree-twin.ts landingRound from the hub): the branch moves to the new commits, uncommitted edits stay, every
+ *      rewritten file is backed up first, and a Git operation in progress or a file being edited waits;
+ *   3. only then records it (POST /v1/tasks/{id}/land with the commit; for a conversation POST /land merge into the
+ *      branch). A conflict changes nothing: the task's master is asked to merge (a steer) and nothing is recorded.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { conversationClient } from "./conversation-commands.js";
+import { localConversations } from "./conversations.js";
+import { CodedError } from "./errors.js";
+import { selectedProjects } from "./project-preparation.js";
+import { HUB_PATH, backupRoot, deviceId, git, gitText, inspectWorktree, landingRound, listWorktrees } from "./worktree-twin.js";
+import { projectHubCell } from "./worktree-twin-engine.js";
+let script;
+/** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
+export function hubScript() { return script ??= readFileSync(new URL('./task-land-hub.py', import.meta.url), 'utf8'); }
+/** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
+export async function landOnHub(cell, input, signal) {
+    const body = { hub: input.hub ?? HUB_PATH, result: input.result, sources: input.sources, title: input.title, ...(input.into ? { default: input.into } : {}) };
+    const r = await cell.exec.run(['python3', '-c', hubScript()], { stdin: JSON.stringify(body), timeoutMs: 300_000, maxOutputBytes: 1 << 20, ...(signal ? { signal } : {}) });
+    const line = r.stdout.trim().split('\n').at(-1) ?? '';
+    if (r.exitCode !== 0 || !line.startsWith('{'))
+        return { state: 'error', into: input.into ?? '', reason: 'script', message: `the landing script exited ${r.exitCode}: ${r.stderr.trim().slice(-400)}` };
+    return JSON.parse(line);
+}
+/** The branch to land in: the one checked out in the folder, else the hub's default branch when the folder has it. */
+export async function folderBranch(folder, fallback) {
+    const info = await inspectWorktree(folder);
+    const own = info.branch?.replace(/^refs\/heads\//, '');
+    if (own && !own.startsWith('shard/'))
+        return own;
+    const has = await git(folder, ['rev-parse', '-q', '--verify', `refs/heads/${fallback}^{commit}`], { ok: [0, 1, 128] });
+    return has.code === 0 ? fallback : null;
+}
+/**
+ * The result into the folder through the twin's landing (from the hub): the branch moves, the person's uncommitted
+ * edits stay, and the landed commit is checked to be on the branch.
+ */
+export async function landInFolder(cell, f) {
+    const deadline = Date.now() + (f.patienceMs ?? 20_000);
+    const target = (await listWorktrees(f.folder)).find(w => w.branch === `refs/heads/${f.into}`);
+    const repo = target?.root ?? f.folder;
+    for (let attempt = 0;; attempt++) {
+        const worktree = target ? await inspectWorktree(target.root) : null;
+        const o = await landingRound(cell, {
+            conversation: { id: f.name, name: f.name, title: f.title, summary: '', branch: f.branch, base_commit: f.base, worktree_path: '' },
+            into: f.into, mode: 'auto', device: f.device, repo, worktree, stateDir: f.stateDir, backupRoot: backupRoot(f.stateDir), fromHub: {},
+            ...(f.hub ? { hub: f.hub } : {}), ...(f.quietMs !== undefined ? { quietMs: f.quietMs } : {}), ...(f.signal ? { signal: f.signal } : {}),
+        });
+        const tip = async () => gitText(repo, ['rev-parse', `refs/heads/${f.into}`]);
+        switch (o.state) {
+            case 'landed': {
+                await o.confirmed.catch(() => undefined);
+                const landed = o.land.tip, now = await tip();
+                const on = await git(repo, ['merge-base', '--is-ancestor', landed, `refs/heads/${f.into}`], { ok: [0, 1] });
+                if (on.code !== 0)
+                    throw new CodedError('land_unverified', `${f.into} in ${f.folder} does not contain the landed commit ${landed.slice(0, 7)}.`);
+                return { path: f.folder, into: f.into, state: 'landed', sha: now, method: o.land.method ?? 'landed', files: o.applied.files.length, kept: o.applied.raced, backup: o.applied.backup };
+            }
+            case 'noop': return { path: f.folder, into: f.into, state: 'already', sha: await tip() };
+            case 'conflict': return { path: f.folder, into: f.into, state: 'conflict', conflicts: o.land.conflicts ?? [] };
+            case 'error': throw new CodedError('land_failed', `Could not land into ${f.folder}: ${o.land.message ?? o.land.reason ?? 'the landing failed'}.`);
+            case 'pr':
+            case 'deferred': return { path: f.folder, into: f.into, state: 'waiting', reason: o.state };
+            default: {
+                // paused (a Git operation), moved (the branch or a file changed while landing), busy (a file just saved).
+                const wait = o.state === 'busy' ? Math.min(o.waitMs ?? 1000, 3000) : o.state === 'moved' ? 200 : 1000;
+                if (Date.now() + wait > deadline || attempt >= 20)
+                    return { path: f.folder, into: f.into, state: 'waiting', reason: o.reason };
+                await delay(wait, undefined, f.signal ? { signal: f.signal } : {});
+            }
+        }
+    }
+}
+/** The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started. */
+export function linkedFolder(ctx, projectId, conversationId) {
+    const repo = (folder) => folder && existsSync(join(folder, '.git')) ? folder : null;
+    const records = localConversations(ctx);
+    const own = conversationId ? repo(records[conversationId]?.folder) : null;
+    if (own)
+        return own;
+    // A folder linked with `shard projects link` belongs to the signed-in project until its preparation names one.
+    const profile = ctx.store.profile(ctx.apiUrl), mine = profile.project_id ?? profile.api_key?.project_id;
+    const linked = selectedProjects(ctx).filter(p => (p.project_id ?? mine) === projectId).map(p => repo(p.folder)).find(Boolean);
+    if (linked)
+        return linked;
+    return Object.values(records).filter(r => r.project_id === projectId).map(r => repo(r.folder)).find(Boolean) ?? null;
+}
+export const displayPath = (path) => { const home = homedir(); return path === home ? '~' : path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path; };
+const short = (sha) => (sha ?? '').slice(0, 7);
+const list = (files) => files.length > 4 ? `${files.slice(0, 4).join(', ')} and ${files.length - 4} more` : files.join(', ');
+function message(o) {
+    const f = o.folder;
+    if (f && (f.state === 'landed' || f.state === 'already'))
+        return `Landed in ${f.display} · ${short(f.sha)}`;
+    const hub = `Landed in ${o.hub.into} on the project hub · ${short(o.hub.sha)}`;
+    if (f?.state === 'conflict')
+        return `${hub}. Not in ${f.display}: your commits on ${f.into} change ${list(f.conflicts ?? [])} too.`;
+    if (f?.state === 'waiting')
+        return `${hub}. ${f.display} gets it once it is not busy (${f.reason ?? 'busy'}).`;
+    return hub;
+}
+export function landDeps(ctx) {
+    return { client: conversationClient(ctx), hubCell: p => projectHubCell(ctx, p, ctx.signal, 'shard-land'), folder: (p, c) => linkedFolder(ctx, p, c),
+        device: deviceId(ctx.store.dir), stateDir: ctx.store.dir, signal: ctx.signal };
+}
+async function land(d, l, onConflict) {
+    const vm = await d.hubCell(l.projectId);
+    try {
+        const input = { result: l.result, sources: l.sources.map(s => s.branch), title: l.title, ...(d.hub ? { hub: d.hub } : {}) };
+        let hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'raced')
+            hub = await landOnHub(vm.cell, input, d.signal);
+        if (hub.state === 'conflict') {
+            await onConflict(hub);
+            throw new CodedError('land_conflict', `Not landed: ${list(hub.conflicts ?? [])} changed on both sides (${hub.stage === 'integrate' ? `${hub.source} and ${l.result}` : `${l.result} and ${hub.into}`}).`, 'its master merges them and asks to land again', { stage: hub.stage, into: hub.into, conflicts: hub.conflicts ?? [] });
+        }
+        if (hub.state === 'missing')
+            throw new CodedError('land_nothing', `Nothing to land: the project hub has no ${l.result} yet.`, 'land after the work is done', { branch: l.result });
+        if (hub.state !== 'landed')
+            throw new CodedError('land_failed', `Could not land on the project hub: ${hub.message ?? hub.reason ?? hub.state}.`, 'try again in a moment', { stage: hub.stage ?? null });
+        const contained = l.sources.filter(s => hub.contained?.includes(s.branch)).map(s => s.conversation_id);
+        let folder = null;
+        if (l.folder) {
+            const into = await folderBranch(l.folder, hub.into);
+            if (!into)
+                folder = { path: l.folder, display: displayPath(l.folder), into: hub.into, state: 'skipped', reason: 'detached' };
+            else {
+                const f = await landInFolder(vm.cell, { folder: l.folder, into, name: l.name, title: l.title, branch: l.result, base: l.base ?? hub.merge_base ?? hub.before ?? hub.result,
+                    device: d.device, stateDir: d.stateDir, ...(d.hub ? { hub: d.hub } : {}), ...(d.quietMs !== undefined ? { quietMs: d.quietMs } : {}), ...(d.signal ? { signal: d.signal } : {}) });
+                folder = { ...f, display: displayPath(f.path) };
+            }
+        }
+        return { title: l.title, result: { branch: l.result, sha: hub.result }, hub: { into: hub.into, sha: hub.after, method: hub.method }, folder, contained };
+    }
+    finally {
+        vm.close();
+    }
+}
+/** What a landing did, for people: the line, then what was not recorded. */
+export function landedText(o) {
+    return `${o.message}\n${o.recorded ? '' : `Not recorded on the board: ${o.record_error ?? 'unknown'}.\n`}`;
+}
+const recordFailure = (error) => {
+    const e = error;
+    return e.status === 404 ? 'this API does not record task landings yet' : (e.message ?? String(error));
+};
+/** The task's current result: its master's latest final report, when it is done. */
+function currentResult(d) {
+    const own = d.task.master_id ? d.reports.filter(r => r.author_id === d.task.master_id) : d.reports;
+    const final = [...own].reverse().find(r => r.milestone === 'done' || r.milestone === 'failed' || r.milestone === 'planned');
+    return final?.milestone === 'done' ? final.id : null;
+}
+const resultBranch = (taskId) => `shard/${taskId}`;
+/** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
+export async function landTask(d, taskId, opts = {}) {
+    const client = d.client, signal = d.signal ? { signal: d.signal } : {};
+    const detail = await client.tasks.get(taskId, signal);
+    const task = detail.task, title = task.title ?? task.text.split('\n')[0].slice(0, 80);
+    const report = currentResult(detail);
+    if (!report || (task.state !== 'done' && task.state !== 'unverified'))
+        throw new CodedError('task_not_done', 'This task has no finished result to land yet.', 'land it after its master’s done report', { state: task.state });
+    const workers = [];
+    for (const c of task.conversations) {
+        if (c.role === 'master' || c.role === 'reviewer')
+            continue;
+        const w = await client.conversations.get(c.id);
+        if (w.join_mode !== 'reviewer' && (w.changes?.commits ?? 0) > 0 && w.landed?.how !== 'discarded')
+            workers.push(w);
+    }
+    const folder = opts.path ?? d.folder(task.project_id);
+    const done = await land(d, { projectId: task.project_id, title, name: taskId, result: resultBranch(taskId), sources: workers.map(w => ({ branch: w.branch, conversation_id: w.id })),
+        base: workers.find(w => w.base_commit)?.base_commit ?? null, folder }, async (hub) => {
+        const what = hub.stage === 'integrate' ? `${hub.source} into ${resultBranch(taskId)}` : `${resultBranch(taskId)} into ${hub.into}`;
+        await client.tasks.steer(taskId, `Land could not merge ${what}: ${list(hub.conflicts ?? [])} changed on both sides. Merge ${hub.into} from the project hub and every worker branch into ${resultBranch(taskId)}, resolve the conflicts so both changes work (ask the person only if the choice is theirs), run the tests, push ${resultBranch(taskId)} to the hub and seal done again.`, signal);
+    });
+    let recorded = false, record_error;
+    try {
+        await client.tasks.recordLanding(taskId, { sha: done.result.sha, into: done.hub.into, branch: done.result.branch, reportId: report, conversationIds: done.contained }, signal);
+        recorded = true;
+    }
+    catch (error) {
+        record_error = recordFailure(error);
+        // An API without task landings (before train 41) keeps a land item per worker: the workers whose branches are in
+        // the landed commit are recorded as merged into the branch, which is true, so those items go.
+        if (error.status === 404 && done.contained.length) {
+            let all = true;
+            for (const id of done.contained) {
+                try {
+                    await client.conversations.land(id, 'merge', { into: done.hub.into, ...signal });
+                }
+                catch {
+                    all = false;
+                }
+            }
+            if (all) {
+                recorded = true;
+                record_error = undefined;
+            }
+        }
+    }
+    const { title: t, result, hub, folder: f } = done;
+    const o = { title: t, result, hub, folder: f, landed: true, task_id: taskId, recorded, ...(record_error ? { record_error } : {}) };
+    return { ...o, message: message(o) };
+}
+/** `shard conversations land <id> merge`: the conversation's branch into the default branch and its folder, then recorded. */
+export async function landConversation(d, id, opts = {}) {
+    const client = d.client;
+    const c = await client.conversations.get(id);
+    if (c.changes?.uncommitted)
+        throw new CodedError('uncommitted_changes', 'The conversation has uncommitted changes.', 'ask its agent to commit them, then land');
+    const folder = opts.path ?? d.folder(c.project_id, c.id);
+    const done = await land(d, { projectId: c.project_id, title: c.title || c.branch, name: c.name ?? c.branch.replace(/^shard\//, ''), result: c.branch, sources: [],
+        base: c.base_commit ?? null, folder }, () => Promise.resolve());
+    let recorded = false, record_error;
+    try {
+        await client.conversations.land(id, 'merge', { into: done.hub.into, ...(d.signal ? { signal: d.signal } : {}) });
+        recorded = true;
+    }
+    catch (error) {
+        record_error = recordFailure(error);
+    }
+    const { title: t, result, hub, folder: f } = done;
+    const o = { title: t, result, hub, folder: f, landed: true, conversation_id: id, recorded, ...(record_error ? { record_error } : {}) };
+    return { ...o, message: message(o) };
+}

package/dist/main.js

@@ -66,7 +66,11 @@ function hintFor(info, cred, file, command = '') {
     if (info.code === 'timeout' && info.operation_id)
         return `the operation continues server side; keep waiting with: shard operations wait ${info.operation_id}`;
     if (info.code === 'operation_failed' && info.retryable) {
-        return info.details?.error_code === 'capacity_unavailable' ? 'nothing was started; run the same command again' : 'the operation may succeed if you retry it later.';
+        if (info.details?.error_code === 'capacity_unavailable') {
+            const retry = info.details.retry_after_seconds;
+            return `nothing was started; run the same command again${typeof retry === 'number' && retry > 0 ? ` after ${retry} s` : ''}`;
+        }
+        return 'the operation may succeed if you retry it later.';
     }
     if (info.code === 'interrupted' && info.operation_id)
         return `keep waiting with: shard operations wait ${info.operation_id}`;
@@ -175,6 +179,8 @@ function allowanceHint(info) {
     const resets = typeof info.details?.resets_at === 'string' ? ` (the period resets ${time(info.details.resets_at)})` : '';
     switch (info.details?.reason) {
         case 'allowance_used':
+            if (info.details?.spend_cap === null)
+                return 'choose a paid plan: shard billing plans; overage is unavailable on the current plan';
             return `upgrade (shard billing plans), or turn on overage: shard billing overage on --cap <dollars>${resets}`;
         case 'spend_cap_reached':
             return `the spend cap is reached: raise it (shard billing overage cap <dollars>, at most the plan price) or upgrade${resets}`;

package/dist/onboarding.d.ts

@@ -111,7 +111,7 @@ export declare function onboardingReport(ctx: Ctx, values: Values, platform?: No
         };
         conversation: {
             id: string;
-            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
             summary: string;
         } | null;
         commands: never[];
@@ -142,7 +142,7 @@ export declare function onboardingReport(ctx: Ctx, values: Values, platform?: No
         };
         conversation: {
             id: string;
-            state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+            state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
             summary: string;
         } | null;
         commands: string[];
@@ -195,7 +195,7 @@ export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
     };
     conversation: {
         id: string;
-        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
         summary: string;
     } | null;
     commands: never[];
@@ -226,7 +226,7 @@ export declare function liveActivity(ctx: Ctx, ref: string): Promise<{
     };
     conversation: {
         id: string;
-        state: "archived" | "working" | "needs_you" | "unresolved" | "done";
+        state: "deleted" | "archived" | "working" | "needs_you" | "unresolved" | "done";
         summary: string;
     } | null;
     commands: string[];

package/dist/router-commands.d.ts

@@ -1,4 +1,5 @@
 import type { RouterResult, Shardflux, ShardfluxAccount } from '@shardflux/sdk';
+import type { Values } from './args.js';
 import type { Ctx, Handler } from './commands.js';
 /** The API's bound on one input or question (characters). */
 export declare const BOARD_TEXT_MAX = 4000;
@@ -9,6 +10,16 @@ interface BoardClient {
 }
 /** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
 export declare function boardClient(ctx: Ctx): BoardClient;
+interface Scope {
+    organizationId?: string;
+    projectId?: string;
+}
+/**
+ * Runs `call` in the board's scope. With the session and no --org/--project: the saved default organization, else the
+ * only one; when the person is in several and none is saved (422), or the saved one is gone (404), the error lists
+ * theirs and names the fix (resolveOrg), and an organization that resolves is used.
+ */
+export declare function inScope<T>(ctx: Ctx, values: Values, call: (client: Shardflux | ShardfluxAccount, scope: Scope) => Promise<T>): Promise<T>;
 /**
  * The readable form of a RouterResult: the kind and where it goes, then each part (a split's parts numbered, with
  * their titles).

package/dist/router-commands.js

@@ -43,7 +43,7 @@ async function scopeOf(ctx, values, b) {
  * only one; when the person is in several and none is saved (422), or the saved one is gone (404), the error lists
  * theirs and names the fix (resolveOrg), and an organization that resolves is used.
  */
-async function inScope(ctx, values, call) {
+export async function inScope(ctx, values, call) {
     const b = boardClient(ctx);
     const { scope, defaulted } = await scopeOf(ctx, values, b);
     try {

package/dist/task-land-hub.py

@@ -0,0 +1,150 @@
+"""Shardflux result landing on the project hub: runs in a VM of the project (shipped and started by the shard CLI,
+land.ts), next to the hub on shared storage.
+
+Input: one JSON object on stdin. Output: one JSON object on stdout (exit 0; "state" says what happened).
+
+  hub       the project hub (a bare repository)
+  result    the result branch (shard/<task id>): the master merged its workers' branches into it
+  sources   worker branches; when the result branch is missing they are merged into it here, each only when the merge
+            is clean (a conflict is the master's to resolve: state "conflict", stage "integrate")
+  default   the branch to land in (default: the hub's HEAD branch, else main or master)
+  title     for the merge commit's message
+
+The result commit T lands in the default branch D: a fast-forward when D is an ancestor of T, nothing when T is already
+in D, else a merge commit when the merge is clean (a conflict: state "conflict", stage "default"; nothing changes). The
+hub's branches move only by `git push` from a temporary repository, never by force, so a branch someone else moved
+meanwhile is refused (stage "raced") instead of overwritten. Before answering "landed" it checks on the hub itself that
+T is contained in D, and which sources are contained in T.
+"""
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+IDENTITY = {'GIT_AUTHOR_NAME': 'Shardflux', 'GIT_AUTHOR_EMAIL': 'landing@shardflux.dev',
+            'GIT_COMMITTER_NAME': 'Shardflux', 'GIT_COMMITTER_EMAIL': 'landing@shardflux.dev'}
+
+
+class Fail(Exception):
+    def __init__(self, reason, message):
+        super().__init__(message)
+        self.reason = reason
+
+
+def git(cwd, *args, ok=(0,), data=None):
+    env = dict(os.environ, GIT_TERMINAL_PROMPT='0', LC_ALL='C', **IDENTITY)
+    p = subprocess.run(['git', '-c', 'core.hooksPath=/dev/null', *args], cwd=cwd, env=env, input=data,
+                       stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    if p.returncode not in ok:
+        raise Fail('git', 'git %s failed (%d): %s' % (args[0], p.returncode, p.stderr.decode('utf-8', 'replace').strip()[-400:]))
+    return p
+
+
+def text(cwd, *args, **kw):
+    return git(cwd, *args, **kw).stdout.decode('utf-8', 'surrogateescape').strip()
+
+
+def tip(cwd, ref):
+    p = git(cwd, 'rev-parse', '-q', '--verify', ref + '^{commit}', ok=(0, 1, 128))
+    return p.stdout.decode().strip() if p.returncode == 0 else None
+
+
+def ancestor(cwd, a, b):
+    return git(cwd, 'merge-base', '--is-ancestor', a, b, ok=(0, 1)).returncode == 0
+
+
+def merge(repo, ours, theirs, message):
+    """A merge commit of theirs into ours when the merge is clean, else (None, conflicting paths)."""
+    r = git(repo, 'merge-tree', '--write-tree', '--name-only', '--no-messages', '-z', ours, theirs, ok=(0, 1))
+    parts = r.stdout.decode('utf-8', 'surrogateescape').split('\0')
+    if r.returncode == 1:
+        return None, sorted(set(p for p in parts[1:] if p))
+    tree = parts[0].strip()
+    return text(repo, 'commit-tree', tree, '-p', ours, '-p', theirs, '-m', message), []
+
+
+def push(repo, hub, sha, branch, old):
+    """Moves the hub's branch from old (None: create) to sha, never by force; False when it moved meanwhile."""
+    lease = '--force-with-lease=refs/heads/%s:%s' % (branch, old or '')
+    p = git(repo, 'push', '-q', '--no-verify', lease, hub, '%s:refs/heads/%s' % (sha, branch), ok=(0, 1))
+    return p.returncode == 0
+
+
+def default_branch(hub, wanted):
+    if wanted:
+        return wanted
+    head = git(hub, 'symbolic-ref', '-q', 'HEAD', ok=(0, 1)).stdout.decode().strip()
+    if head.startswith('refs/heads/') and tip(hub, head):
+        return head[len('refs/heads/'):]
+    for name in ('main', 'master'):
+        if tip(hub, 'refs/heads/' + name):
+            return name
+    return head[len('refs/heads/'):] if head.startswith('refs/heads/') else 'main'
+
+
+def land(a):
+    hub, result, title = a['hub'], a['result'], a.get('title') or a['result']
+    sources = [s for s in a.get('sources', []) if s and s != result]
+    into = default_branch(hub, a.get('default'))
+    work = tempfile.mkdtemp(prefix='shard-result-')
+    try:
+        git(work, 'init', '-q', '--bare')
+        wanted = [result, into] + sources
+        refs = ['+refs/heads/%s:refs/heads/%s' % (b, b) for b in wanted if tip(hub, 'refs/heads/' + b)]
+        if refs:
+            git(work, 'fetch', '-q', '--no-tags', hub, *refs)
+        have = {b: tip(work, 'refs/heads/' + b) for b in wanted}
+        before = have.get(into)
+        t, created = have.get(result), False
+        if not t:
+            # A master that did not merge its workers: merge them here, each only when it merges cleanly.
+            for s in sources:
+                st = have.get(s)
+                if not st:
+                    continue
+                if not t or ancestor(work, t, st):
+                    t = st
+                elif not ancestor(work, st, t):
+                    t, conflicts = merge(work, t, st, 'Merge %s into %s' % (s, result))
+                    if not t:
+                        return {'state': 'conflict', 'stage': 'integrate', 'into': into, 'source': s, 'conflicts': conflicts}
+            if not t:
+                return {'state': 'missing', 'into': into, 'message': 'the project hub has no %s and no worker branch to make it from' % result}
+            if not push(work, hub, t, result, None):
+                return {'state': 'raced', 'stage': 'integrate', 'into': into, 'message': '%s appeared on the project hub meanwhile' % result}
+            created = True
+        if before and ancestor(work, t, before):
+            method, after = 'already', before
+        elif not before or ancestor(work, before, t):
+            method, after = ('created' if not before else 'ff'), t
+        else:
+            after, conflicts = merge(work, before, t, 'Land %s (%s)' % (title, result))
+            if not after:
+                return {'state': 'conflict', 'stage': 'default', 'into': into, 'result': t, 'before': before, 'conflicts': conflicts}
+            method = 'merge'
+        if after != before and not push(work, hub, after, into, before):
+            return {'state': 'raced', 'stage': 'default', 'into': into, 'result': t, 'message': '%s moved on the project hub meanwhile' % into}
+        # Checked on the hub itself: the result is in the branch it landed in.
+        now = tip(hub, 'refs/heads/' + into)
+        if not now or not ancestor(hub, t, now):
+            raise Fail('unverified', '%s does not contain %s on the project hub after landing' % (into, t))
+        contained = [s for s in sources if have.get(s) and ancestor(hub, have[s], t)]
+        base = (text(hub, 'merge-base', before, t, ok=(0, 1)) or None) if before else None
+        return {'state': 'landed', 'into': into, 'before': before, 'after': now, 'result': t, 'method': method,
+                'created_result': created, 'contained': contained, 'merge_base': base}
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+
+
+def main():
+    try:
+        out = land(json.load(sys.stdin))
+    except Fail as e:
+        out = {'state': 'error', 'reason': e.reason, 'message': str(e)}
+    sys.stdout.write(json.dumps(out) + '\n')
+
+
+if __name__ == '__main__':
+    main()

package/dist/transcribe-commands.d.ts

@@ -0,0 +1,7 @@
+import type { Transcript } from '@shardflux/sdk';
+import type { Handler } from './commands.js';
+/** What one transcription holds (the API's bound; past it the rest is not transcribed and `truncated` says so). */
+export declare const TRANSCRIBE_MAX_BYTES: number;
+/** The readable form: the text, then (with --words) one line per word with its start and end. */
+export declare function transcriptText(t: Transcript, words: boolean): string;
+export declare const TRANSCRIBE_HANDLERS: Record<string, Handler>;