@shardflux/cli 0.24.0 → 0.25.0

package/dist/onboarding.js

@@ -7,9 +7,9 @@ import { AgentStateStore } from "./agent-state.js";
 import { describeError } from "./errors.js";
 import { t3PhoneLink } from "./t3-phone.js";
 import { t3NeedsProject, t3SignInProject } from "./account-scope.js";
-import { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
+import { credentialFingerprint, readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
 import { getConversation } from "./conversations.js";
-import { codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
+import { CODEX_SIGN_IN_LINE, codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
 import { applicationDirs } from "./agent-targets.js";
 import { configureT3Provider } from "./t3-provider.js";
 import { t3Install } from "./t3-mode.js";
@@ -198,8 +198,11 @@ export function claudeConnection(row) {
         return { state: 'action', fact: 'Claude no longer accepts this sign-in.', action: { ...signIn, title: 'Sign in to Claude again' } };
     return { state: 'verified', fact: 'Signed in. Works in every conversation, on web and phone.' };
 }
-/** Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected. */
-export function codexConnection(local, synced, connector, health) {
+/**
+ * Codex: this computer's Codex login is copied and the account's Codex remote device (one executor) is connected.
+ * `renewed`: this computer has a Codex login other than the one in the cloud (a new sign-in not copied yet).
+ */
+export function codexConnection(local, synced, connector, health, renewed = false) {
     const enable = { title: 'Connect Codex', command: shard(['agents', 'codex', 'enable']) };
     if (!synced) {
         return local ? { state: 'action', fact: 'Available on web and phone once connected.', action: enable }
@@ -215,6 +218,11 @@ export function codexConnection(local, synced, connector, health) {
         case 'failed': return { state: 'action', fact: 'Codex’s remote device didn’t start.', action: retry };
         case 'stuck': return { state: 'action', fact: 'Codex’s remote device is taking too long to start.', action: retry };
         case 'attention': return { state: 'action', fact: connector?.last_error ? `Codex needs attention: ${connector.last_error}` : 'Codex needs attention.', action: retry };
+        // Codex Cloud refused the copied ChatGPT login (0.25.0+): sign in to Codex again here, then copy that sign-in, which
+        // starts the device again by itself. Never Retry: a restart cannot fix a sign-in.
+        case 'sign_in': return renewed
+            ? { state: 'action', fact: 'Your new Codex sign-in is ready to copy to the cloud.', action: { title: 'Copy sign-in', command: shard(['agents', 'credentials', 'sync']) } }
+            : { state: 'action', fact: CODEX_SIGN_IN_LINE, action: { title: 'Sign in to Codex again', command: ['codex', 'login'] } };
     }
 }
 /**
@@ -237,7 +245,10 @@ export async function onboardingReport(ctx, values, platform = process.platform)
     let connector = null;
     let health = 'missing';
     const home = ctx.io.env.HOME ?? ctx.io.env.USERPROFILE;
-    const localCodex = home ? (await readAgentCredentials({ home, redact: value => ctx.addSecret(value) })).some(v => v.app === 'codex') : false;
+    const localLogin = home ? (await readAgentCredentials({ home, redact: value => ctx.addSecret(value) })).find(v => v.app === 'codex') : undefined;
+    const localCodex = localLogin !== undefined;
+    /** Whether this computer's Codex login differs from the copy in the cloud. */
+    const renewed = (rows) => localLogin !== undefined && rows.find(row => row.app === 'codex')?.fingerprint !== credentialFingerprint(localLogin.files);
     try {
         ctx.apiKey();
         const principal = await ctx.cloud().me();
@@ -284,6 +295,13 @@ export async function onboardingReport(ctx, values, platform = process.platform)
                     read = { connector: await ctx.cloud().codex.enable({ signal: ctx.signal }), workspaceState: null };
                     health = codexHealth(read.connector, null);
                 }
+                else if (connect && synced && health === 'sign_in' && renewed(credentials) && home) {
+                    // A new Codex sign-in on this computer: copy it, and the device starts again with it (never a restart).
+                    await syncAgentCredentials(ctx.cloud(), { home, redact: value => ctx.addSecret(value) });
+                    credentials = await listCredentials();
+                    read = { connector: await ctx.cloud().codex.enable({ signal: ctx.signal }), workspaceState: null };
+                    health = codexHealth(read.connector, null);
+                }
                 else if (connect && synced && values['retry-codex'] === true && (health === 'failed' || health === 'stuck' || health === 'attention')) {
                     read = { connector: await restartCodexConnector(ctx), workspaceState: null };
                     health = codexHealth(read.connector, null);
@@ -304,7 +322,7 @@ export async function onboardingReport(ctx, values, platform = process.platform)
         ...(!connected ? signIn : codexError instanceof ShardfluxApiError && codexError.reason === 'codex_chatgpt_login_required'
             ? { state: 'action', fact: codexError.message, action: { title: 'Sign in with ChatGPT', command: ['codex', 'login'] } }
             : (credentialError ?? codexError) !== undefined ? failure(credentialError ?? codexError)
-                : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health)) };
+                : codexConnection(localCodex, credentials.some(row => row.app === 'codex'), connector, health, renewed(credentials))) };
     const t3 = await t3Connection(ctx, connected || ctx.sessionSource() !== null, undefined, undefined, values['t3-connect'] === true, values);
     const connections = [account, claude, codex, ...(t3 ? [t3] : [])];
     // The cloud machine (0.20.2+), the same row `shard machine setup --status` reports: whether what is installed carries

package/dist/project-git.d.ts

@@ -1,3 +1,9 @@
 import type { Ctx } from './commands.js';
-/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+/**
+ * Prepare only the selected project root; never a nested repository. A folder without Git becomes a repository whose
+ * first commit is its files (.gitignore respected; large untracked media stay untracked, as a twin snapshot leaves
+ * them): a conversation then starts from the same commit as the folder and its work fast-forwards back, as in a
+ * repository the person made (0.25.0+; before, an empty first commit left every file to a snapshot, and landings
+ * conflicted). A repository of the person's own keeps its staged and untracked files as they are.
+ */
 export declare function ensureProjectGit(ctx: Ctx, folder: string): Promise<void>;

package/dist/project-git.js

@@ -1,8 +1,16 @@
+import { createHash } from 'node:crypto';
 import { existsSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import { gitRunner } from "./agent-git.js";
 import { GitError } from "./errors.js";
-/** Prepare only the selected project root. Never stage files or initialize a nested repository. */
+import { largeUntrackedMedia, outsideSpecs } from "./large-media.js";
+/**
+ * Prepare only the selected project root; never a nested repository. A folder without Git becomes a repository whose
+ * first commit is its files (.gitignore respected; large untracked media stay untracked, as a twin snapshot leaves
+ * them): a conversation then starts from the same commit as the folder and its work fast-forwards back, as in a
+ * repository the person made (0.25.0+; before, an empty first commit left every file to a snapshot, and landings
+ * conflicted). A repository of the person's own keeps its staged and untracked files as they are.
+ */
 export async function ensureProjectGit(ctx, folder) {
     const git = gitRunner(folder, { ...process.env, ...ctx.io.env, LC_ALL: 'C' }, ctx.signal, false);
     let initialized = false;
@@ -37,7 +45,12 @@ export async function ensureProjectGit(ctx, folder) {
             throw error;
     }
     // --only with no paths makes an empty commit even when the user already has staged files.
-    const commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '--only', '-m', 'Initial commit'];
+    let commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '--only', '-m', 'Initial commit'];
+    if (initialized) {
+        const media = await largeUntrackedMedia(folder, ctx.store.dir, `init-${createHash('sha256').update(folder).digest('hex').slice(0, 16)}`, ctx.signal);
+        await git(['add', '-A', '--', '.', ...outsideSpecs(media)]);
+        commit = ['-c', 'core.hooksPath=/dev/null', 'commit', '--allow-empty', '-m', 'Initial commit'];
+    }
     try {
         await git(commit);
     }
@@ -47,6 +60,6 @@ export async function ensureProjectGit(ctx, folder) {
         await git(['-c', 'user.name=Shardflux', '-c', 'user.email=noreply@shardflux.dev', ...commit]);
     }
     ctx.io.stderr.write(initialized
-        ? `Initialized a git repository in ${folder} (shard tracks your project with git).\n`
+        ? `Initialized a git repository in ${folder} with its files as the first commit (shard tracks your project with git).\n`
         : `Created an initial empty commit in ${folder}.\n`);
 }

package/dist/project-preparation.d.ts

@@ -38,6 +38,13 @@ export interface SetupStatus {
     }[];
 }
 export declare function setupFailure(status: SetupStatus): CodedError;
+/**
+ * A setup that failed only because the project has no build or test command (the guest's `.:checks` step, unresolved
+ * at detection) has nothing left to prepare: its files are in the cache and every other step succeeded. That is a
+ * clean ready, never an error that waits for an edit (0.25.0+; before, a plain folder from `projects link` stayed
+ * flagged).
+ */
+export declare function nothingToCheck(status: SetupStatus): boolean;
 /** New content past this, or a dependency change, makes a quiet project worth preparing again. */
 export declare const PREPARE_AGAIN_BYTES: number;
 /** Quiet this long after the last edit before preparing again. */

package/dist/project-preparation.js

@@ -40,6 +40,18 @@ export function setupFailure(status) {
     const fix = `${first}${step ? `, or set run for ${step.name} under steps in .shardflux/setup.yaml` : ''}; the project is prepared again after the change`;
     return new SetupFailed('project_setup_failed', message, fix, step ? { step: step.name, ...(step.error?.code ? { error_code: step.error.code } : {}) } : undefined);
 }
+/**
+ * A setup that failed only because the project has no build or test command (the guest's `.:checks` step, unresolved
+ * at detection) has nothing left to prepare: its files are in the cache and every other step succeeded. That is a
+ * clean ready, never an error that waits for an edit (0.25.0+; before, a plain folder from `projects link` stayed
+ * flagged).
+ */
+export function nothingToCheck(status) {
+    const failed = status.tasks?.filter(t => t.state === 'failed') ?? [];
+    return status.state === 'failed' && failed.length > 0
+        && failed.every(t => t.error?.code === 'setup_detection_unresolved' && /(^|:)checks$/.test(t.name))
+        && (status.tasks ?? []).every(t => t.state === 'failed' ? failed.includes(t) : ['succeeded', 'skipped'].includes(t.state));
+}
 /** New content past this, or a dependency change, makes a quiet project worth preparing again. */
 export const PREPARE_AGAIN_BYTES = 8 << 20;
 /** Quiet this long after the last edit before preparing again. */
@@ -158,6 +170,8 @@ export async function prepareSelectedProject(ctx, selected) {
                     if (status.exitCode !== 0)
                         throw new Error(`Project setup status failed: ${status.stderr.trim()}`);
                     const state = JSON.parse(status.stdout);
+                    if (nothingToCheck(state))
+                        break;
                     if (state.state === 'failed')
                         throw setupFailure(state);
                     if (Date.now() > deadline)

package/dist/project-template-setup.js

@@ -23,20 +23,41 @@ export function dependencyHash(folder) {
             throw error;
     }
     const files = [];
-    const walk = (relative, devcontainer) => {
-        for (const name of readdirSync(join(folder, relative)).sort()) {
-            const path = relative ? `${relative}/${name}` : name;
-            const st = lstatSync(join(folder, path));
-            const inside = devcontainer || name === '.devcontainer';
-            if (st.isDirectory()) {
-                if (!skippedDirs.has(name))
-                    walk(path, inside);
+    const wanted = (path, name, inside) => name !== '.env' && !name.startsWith('.env.') && (inside || path.startsWith('.github/workflows/') || dependencyName(name));
+    if (selected) {
+        // Git's list is the whole input: walking the folder visited every ignored and untracked tree too (a folder of
+        // agent worktrees held 1.2 million entries and cost 29 s of every start).
+        for (const path of selected) {
+            const parts = path.split('/'), name = parts.at(-1);
+            if (!name || parts.slice(0, -1).some(dir => skippedDirs.has(dir)) || !wanted(path, name, parts.includes('.devcontainer')))
+                continue;
+            let st;
+            try {
+                st = lstatSync(join(folder, path));
             }
-            else if ((st.isFile() || st.isSymbolicLink()) && (!selected || selected.has(path)) && name !== '.env' && !name.startsWith('.env.') && (inside || path.startsWith('.github/workflows/') || dependencyName(name)))
+            catch {
+                continue;
+            }
+            if (st.isFile() || st.isSymbolicLink())
                 files.push(path);
         }
-    };
-    walk('', false);
+    }
+    else {
+        const walk = (relative, devcontainer) => {
+            for (const name of readdirSync(join(folder, relative)).sort()) {
+                const path = relative ? `${relative}/${name}` : name;
+                const st = lstatSync(join(folder, path));
+                const inside = devcontainer || name === '.devcontainer';
+                if (st.isDirectory()) {
+                    if (!skippedDirs.has(name))
+                        walk(path, inside);
+                }
+                else if ((st.isFile() || st.isSymbolicLink()) && wanted(path, name, inside))
+                    files.push(path);
+            }
+        };
+        walk('', false);
+    }
     const hash = createHash('sha256').update('shardflux-deps-v2\0');
     for (const path of files.sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
         const st = lstatSync(join(folder, path));

package/dist/router-commands.d.ts

@@ -0,0 +1,33 @@
+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;
+interface BoardClient {
+    client: Shardflux | ShardfluxAccount;
+    /** The signed-in session: the organization's whole board. */
+    session: boolean;
+}
+/** 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).
+ *
+ *   2 tasks in site
+ *     1. Fix the landing page hero image
+ *        fix the hero image on the landing page
+ */
+export declare function routeText(r: RouterResult, names: ReadonlyMap<string, string>): string;
+export declare const ROUTER_HANDLERS: Record<string, Handler>;
+export {};

package/dist/router-commands.js

@@ -0,0 +1,179 @@
+/**
+ * `shard route` and `shard ask` (0.25.0+): the board's input bar from a terminal, through @shardflux/sdk's
+ * `router.route()` and `questions.stream()` / `questions.ask()`. The signed-in session reads every project of an
+ * organization; SHARDFLUX_API_KEY in the environment (or a saved key without a session) reads that key's project.
+ */
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { UUID } from "./args.js";
+import { findOrg, resolveOrg, resolveProject } from "./account-scope.js";
+import { out, str } from "./commands.js";
+import { EXIT, UsageError } from "./errors.js";
+/** The API's bound on one input or question (characters). */
+export const BOARD_TEXT_MAX = 4000;
+const TASK_ID = /^[A-Za-z0-9_-]{1,64}$/;
+/** SHARDFLUX_API_KEY in the environment wins; else the signed-in session; else the saved key (its error names both). */
+export function boardClient(ctx) {
+    if (!ctx.io.env.SHARDFLUX_API_KEY?.trim() && ctx.sessionSource() !== null)
+        return { client: ctx.account(), session: true };
+    return { client: ctx.cloud(), session: false };
+}
+/** --org / --project as ids (slugs resolved with the session); with neither, the saved default organization. */
+async function scopeOf(ctx, values, b) {
+    const org = str(values.org), project = str(values.project);
+    if (!b.session) {
+        for (const [flag, v] of [['--org', org], ['--project', project]]) {
+            if (v !== undefined && !UUID.test(v))
+                throw new UsageError(`${flag} must be an id (UUID) with a project API key`, 'or sign in (shard auth login) to name it by slug');
+        }
+        return { scope: { ...(org === undefined ? {} : { organizationId: org }), ...(project === undefined ? {} : { projectId: project }) }, defaulted: false };
+    }
+    const account = b.client;
+    const scope = {};
+    if (org !== undefined)
+        scope.organizationId = UUID.test(org) ? org : (await findOrg(account, org)).id;
+    if (project !== undefined)
+        scope.projectId = UUID.test(project) ? project : (await resolveProject(ctx, account, values)).id;
+    if (org !== undefined || project !== undefined)
+        return { scope, defaulted: false };
+    const saved = ctx.store.profile(ctx.apiUrl).organization_id;
+    return { scope: saved ? { organizationId: saved } : {}, defaulted: true };
+}
+/**
+ * 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 async function inScope(ctx, values, call) {
+    const b = boardClient(ctx);
+    const { scope, defaulted } = await scopeOf(ctx, values, b);
+    try {
+        return await call(b.client, scope);
+    }
+    catch (err) {
+        if (!b.session || !defaulted || !(err instanceof ShardfluxApiError))
+            throw err;
+        const several = err.status === 422 && scope.organizationId === undefined && /organization/i.test(err.message);
+        const gone = err.status === 404 && scope.organizationId !== undefined;
+        if (!several && !gone)
+            throw err;
+        const org = await resolveOrg(ctx, b.client, {});
+        if (org.id === scope.organizationId)
+            throw err;
+        return call(b.client, { organizationId: org.id });
+    }
+}
+function textOf(words, what, command) {
+    const text = words.join(' ').trim();
+    if (!text)
+        throw new UsageError(`missing <${what}> for "shard ${command}"`);
+    if (text.length > BOARD_TEXT_MAX)
+        throw new UsageError(`the ${what} is ${text.length} characters; the limit is ${BOARD_TEXT_MAX}`);
+    return text;
+}
+function taskOf(values) {
+    const task = str(values.task);
+    if (task !== undefined && !TASK_ID.test(task))
+        throw new UsageError('--task must be a task id (task_…)');
+    return task;
+}
+/** Project names for the readable form (GET /v1/projects/{id}); an id that cannot be read prints as itself. */
+async function projectNames(client, parts, signal) {
+    const ids = [...new Set(parts.filter((p) => !p.home && p.project_id).map((p) => p.project_id))];
+    const names = await Promise.all(ids.map((id) => client.request('GET', `/v1/projects/${encodeURIComponent(id)}`, { signal }).then((p) => p.name, () => id)));
+    return new Map(ids.map((id, i) => [id, names[i]]));
+}
+/**
+ * The readable form of a RouterResult: the kind and where it goes, then each part (a split's parts numbered, with
+ * their titles).
+ *
+ *   2 tasks in site
+ *     1. Fix the landing page hero image
+ *        fix the hero image on the landing page
+ */
+export function routeText(r, names) {
+    const where = (p) => (p.home ? 'on your home' : p.project_id ? `in ${names.get(p.project_id) ?? p.project_id}` : '');
+    const parts = r.parts;
+    const same = parts.every((p) => where(p) === where(parts[0]));
+    let head = r.kind === 'task' && parts.length > 1 ? `${parts.length} tasks` : r.kind;
+    if (r.task_ref)
+        head += r.kind === 'steer' ? ` ${r.task_ref}` : ` about ${r.task_ref}`;
+    if (same && where(parts[0]))
+        head += ` ${where(parts[0])}`;
+    const notes = [r.forced === 'question' ? 'asked as a question' : '', r.uncertain ? 'project uncertain' : ''].filter(Boolean);
+    if (notes.length)
+        head += ` (${notes.join(', ')})`;
+    const lines = [head];
+    if (parts.length === 1) {
+        const p = parts[0];
+        if (p.title)
+            lines.push(`  ${p.title}`);
+        lines.push(`  ${p.text}${same ? '' : ` (${where(p)})`}`);
+    }
+    else {
+        parts.forEach((p, i) => {
+            lines.push(`  ${i + 1}. ${p.title ?? p.text}${same ? '' : ` (${where(p)})`}`);
+            if (p.title)
+                lines.push(`     ${p.text}`);
+        });
+    }
+    return `${lines.join('\n')}\n`;
+}
+const interrupted = (ctx, err) => {
+    if (ctx.signal.aborted)
+        return EXIT.interrupted;
+    throw err;
+};
+export const ROUTER_HANDLERS = {
+    async route(ctx, values, words) {
+        const text = textOf(words, 'text', 'route');
+        const selectedTaskId = taskOf(values);
+        try {
+            const { result, client } = await inScope(ctx, values, async (client, scope) => ({
+                client,
+                result: await client.router.route({ text, ...(selectedTaskId === undefined ? {} : { selectedTaskId }), ...scope, signal: ctx.signal }),
+            }));
+            if (ctx.json) {
+                out(ctx, '', result);
+                return EXIT.ok;
+            }
+            ctx.io.stdout.write(routeText(result, await projectNames(client, result.parts, ctx.signal)));
+            return EXIT.ok;
+        }
+        catch (err) {
+            return interrupted(ctx, err);
+        }
+    },
+    async ask(ctx, values, words) {
+        const text = textOf(words, 'question', 'ask');
+        const taskId = taskOf(values);
+        const params = { text, ...(taskId === undefined ? {} : { taskId }), signal: ctx.signal };
+        try {
+            if (ctx.json) {
+                out(ctx, '', await inScope(ctx, values, (client, scope) => client.questions.ask({ ...params, ...scope })));
+                return EXIT.ok;
+            }
+            // Standard output carries the answer as it is written; the place in line (while it waits) goes to stderr.
+            await inScope(ctx, values, async (client, scope) => {
+                let written = '';
+                for await (const e of client.questions.stream({ ...params, ...scope })) {
+                    if (e.type === 'queued')
+                        ctx.io.stderr.write(`Queued: position ${e.position}, about ${Math.max(1, Math.round(e.expectedWaitMs / 1000))} s\n`);
+                    else if (e.type === 'delta') {
+                        ctx.io.stdout.write(e.text);
+                        written += e.text;
+                    }
+                    else {
+                        if (!written)
+                            ctx.io.stdout.write((written = e.answer.text));
+                        if (!written.endsWith('\n'))
+                            ctx.io.stdout.write('\n');
+                    }
+                }
+            });
+            return EXIT.ok;
+        }
+        catch (err) {
+            return interrupted(ctx, err);
+        }
+    },
+};

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>;