@xingular/harness 1.0.0 → 1.1.1

package/dist/sdk/tools/checklist.js

@@ -22,8 +22,8 @@ export function checklistTool(run) {
     return {
         name: CHECKLIST_WRITE,
         label: 'Write the checklist',
-        description: 'Keep a checklist of the steps of the current work, so you and the user can see progress. Send the whole list every time; it replaces the previous one. ' +
-            'Use it when the work has three or more distinct steps, or when the user gives several things to do. Do not use it for a single, simple step or for conversation. ' +
+        description: 'Keep a checklist of the steps of the current work. The user watches this list to follow your progress, so write it early and keep it current. Send the whole list every time; it replaces the previous one. ' +
+            'Use it whenever the work has several distinct steps or will take several tool calls, when the user gives several things to do, and when a subagent brief asks for more than one thing. Do not use it for a single, simple step or for conversation. ' +
             'Statuses: pending, in_progress, completed. Keep exactly one step in_progress while you work, mark a step completed as soon as it is done (not in batches), and add steps you discover. ' +
             'Only mark a step completed when it is fully done; if something blocks it, keep it in_progress and add a step for the blocker.',
         parameters: (Type) => Type.Object({

package/dist/sdk/tools/harnessTools.d.ts

@@ -1,6 +1,8 @@
 import type { CallerContext } from "../core/caller.js";
+import type { HarnessToolDefinition } from "./definitions.js";
 import { type DispatchEnv } from "./dispatch.js";
 import type { ToolSpec } from "./types.js";
 export declare function harnessTools(env: DispatchEnv, context: CallerContext, options?: {
     variantDir?: string | null;
+    definitions?: readonly HarnessToolDefinition[];
 }): ToolSpec[];

package/dist/sdk/tools/harnessTools.js

@@ -1,7 +1,7 @@
 import { describeTool, HARNESS_TOOLS } from "./definitions.js";
 import { dispatch } from "./dispatch.js";
 export function harnessTools(env, context, options = {}) {
-    return HARNESS_TOOLS.map((tool) => ({
+    return (options.definitions ?? HARNESS_TOOLS).map((tool) => ({
         name: tool.name,
         label: tool.label,
         description: describeTool(tool, env.productName),

package/dist/sdk/tools/spawnSubagent.js

@@ -1,5 +1,5 @@
 import { HarnessError, invalid } from "../core/errors.js";
-import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT } from "../sessions/subagents.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS, SUBAGENT_RECEIPT, MAX_SUBAGENT_TITLE_WORDS, subagentTitle } from "../sessions/subagents.js";
 export { SPAWN_SUBAGENT, SUBAGENT_RELATION, DEFAULT_SUBAGENT_DEPTH, MAX_SUBAGENT_DEPTH, subagentDepth, subagentReport } from "../sessions/subagents.js";
 function reported(parentRunId, results, spawned) {
     const included = [];
@@ -27,10 +27,19 @@ export function subagentTools(service, parentRunId) {
     return [{
             name: SPAWN_SUBAGENT,
             label: 'Start a subagent',
-            description: 'Start a fresh child run for independent work: yourself, or one of your subagents when you name it in agent. Give a complete brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue working. Results arrive automatically before you finish. Use wait_subagents to join selected children, or wait: true for an inline result. Stopping you stops your children.',
-            parameters: (Type) => Type.Object({ brief: Type.String(), agent: Type.Optional(Type.String({ description: 'The name of one of your subagents; omit for a copy of yourself' })), tools: Type.Optional(Type.Array(Type.String())), wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' })) }),
+            description: 'Start a fresh child run for independent work: a copy of yourself, or an agent profile from your Subagents list when you name it in agent (for example worker to make changes, explorer to find and explain). Give a short title, which the user sees in the roster, and a complete brief: the child has no conversation history and no more capabilities than you. Returns its run ID immediately by default so you can continue working. Results arrive automatically before you finish. Use wait_subagents to join selected children, or wait: true for an inline result. Stopping you stops your children.',
+            parameters: (Type) => Type.Object({
+                title: Type.String({ description: `A short imperative title for the roster, at most ${MAX_SUBAGENT_TITLE_WORDS} words, such as "Map the auth flow"` }),
+                brief: Type.String(),
+                agent: Type.Optional(Type.String({ description: 'The name of an agent profile from your Subagents list; omit for a copy of yourself' })),
+                tools: Type.Optional(Type.Array(Type.String())),
+                wait: Type.Optional(Type.Boolean({ description: 'Wait for the child and return its result; default false' }))
+            }),
             execute: execute(async (input) => {
-                const child = await service.spawn({ parentRunId, brief: input.brief, agent: input.agent, tools: input.tools, wait: input.wait });
+                const title = subagentTitle(input.title);
+                if (!title)
+                    throw invalid(`Give the subagent a title of at most ${MAX_SUBAGENT_TITLE_WORDS} words, with no control characters.`);
+                const child = await service.spawn({ parentRunId, brief: input.brief, title, agent: input.agent, tools: input.tools, wait: input.wait });
                 if (input.wait === true)
                     return reported(parentRunId, service.results({ parentRunId, runIds: [child.runId] }), [child.runId]);
                 return { text: JSON.stringify(child), details: { [SUBAGENT_RECEIPT]: { version: 1, ownerRunId: parentRunId, spawned: [child.runId] } } };

package/dist/sdk/web/part.d.ts

@@ -0,0 +1,10 @@
+import type { SecretStore } from "../accounts/secrets.js";
+import type { WorldPart } from "../world/world.js";
+import type { WebRequest } from "./safeRequest.js";
+import { KEYLESS_SEARCH } from "./tools.js";
+export declare function webPart(options: {
+    secrets: SecretStore;
+    request?: WebRequest;
+    keyless: () => boolean;
+}): WorldPart;
+export { KEYLESS_SEARCH };

package/dist/sdk/web/part.js

@@ -0,0 +1,6 @@
+import { KEYLESS_SEARCH, WEB_PLUGIN, webTools } from "./tools.js";
+export function webPart(options) {
+    const provider = webTools({ secrets: options.secrets, request: options.request, keyless: options.keyless });
+    return { plugin: WEB_PLUGIN, tools: () => provider({}) };
+}
+export { KEYLESS_SEARCH };

package/dist/sdk/web/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function webServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/web/serverMethods.js

@@ -0,0 +1,7 @@
+import { text } from "../server/params.js";
+export function webServerMethods(harness) {
+    return {
+        'web.status': () => harness.world.searchStatus(),
+        'web.setKey': (params) => harness.world.setSearchKey(text(params, 'provider'), typeof params.key === 'string' ? params.key : null)
+    };
+}

package/dist/sdk/wiki/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function wikiServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/wiki/serverMethods.js

@@ -0,0 +1,26 @@
+import { optional, text } from "../server/params.js";
+import * as notes from "./notes.js";
+export function wikiServerMethods(harness) {
+    const root = () => harness.env.root;
+    return {
+        'wiki.list': (params) => notes.list(root(), params.project === undefined ? {} : { project: optional(params, 'project') }),
+        'wiki.read': (params) => notes.read(root(), text(params, 'path')),
+        'wiki.write': (params) => {
+            const note = notes.write(root(), text(params, 'path'), typeof params.text === 'string' ? params.text : '', { expectedUpdatedAt: optional(params, 'expectedUpdatedAt') });
+            harness.bus.emit({ type: 'wiki.changed' });
+            return note;
+        },
+        'wiki.remove': (params) => {
+            notes.remove(root(), text(params, 'path'));
+            harness.bus.emit({ type: 'wiki.changed' });
+        },
+        'wiki.search': (params) => notes.search(root(), typeof params.query === 'string' ? params.query : '', { project: optional(params, 'project'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
+        'wiki.graph': () => notes.graph(root()),
+        'wiki.versions': (params) => notes.versions(root(), text(params, 'path')),
+        'wiki.version': (params) => notes.version(root(), text(params, 'path'), text(params, 'id')),
+        'wiki.ensureProject': () => {
+            notes.ensureLayout(root(), harness.env.productName);
+            harness.bus.emit({ type: 'wiki.changed' });
+        }
+    };
+}

package/dist/sdk/worktrees/cli.d.ts

@@ -0,0 +1,11 @@
+import { Worktrees } from "./service.js";
+import type { WorktreeRecord } from "./types.js";
+export declare const WORKTREE_USAGE = "Usage: xagent worktree <command> [--state <dir>]\n\n  list                       Worktrees of the repository you are in\n  new [name] [--branch <b>] [--permanent] [--from <ref>] [--no-carry]\n                             Make a worktree (default: managed, detached, with your\n                             uncommitted changes carried over)\n  status <name|id>           Changes and commits since it started\n  branch <name|id> <branch>  Give a detached worktree a branch\n  handoff <name|id> to-main|to-worktree [--copy]\n                             Move changes between it and your main checkout\n                             (--copy leaves the origin as it was)\n  rm <name|id> [--force]     Remove it; with --force, keep a snapshot of unsaved work\n  restore <name|id>          Bring back a removed worktree, with its snapshot\n  prune [--keep <n>]         Keep the most recent managed worktrees (default 15)\n  adopt <path>               Manage an existing linked worktree\n  trust-setup                Trust this repository's .xharness/worktree-setup as it is now\n  path <name|id>             Print its folder (cd \"$(xagent worktree path name)\")\n\nStart the terminal in a new managed worktree with: xagent --worktree [name]\n";
+interface Dependencies {
+    home?: string;
+    cwd?: string;
+    write?: (text: string) => void;
+}
+export declare function findWorktree(worktrees: Worktrees, cwd: string, key: string, removed?: boolean): Promise<WorktreeRecord>;
+export declare function runWorktreeCli(argv: string[], dependencies?: Dependencies): Promise<number>;
+export {};

package/dist/sdk/worktrees/cli.js

@@ -0,0 +1,146 @@
+// `xagent worktree`: managed worktrees of the repository you are in, from a shell.
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Worktrees } from "./service.js";
+export const WORKTREE_USAGE = `Usage: xagent worktree <command> [--state <dir>]
+
+  list                       Worktrees of the repository you are in
+  new [name] [--branch <b>] [--permanent] [--from <ref>] [--no-carry]
+                             Make a worktree (default: managed, detached, with your
+                             uncommitted changes carried over)
+  status <name|id>           Changes and commits since it started
+  branch <name|id> <branch>  Give a detached worktree a branch
+  handoff <name|id> to-main|to-worktree [--copy]
+                             Move changes between it and your main checkout
+                             (--copy leaves the origin as it was)
+  rm <name|id> [--force]     Remove it; with --force, keep a snapshot of unsaved work
+  restore <name|id>          Bring back a removed worktree, with its snapshot
+  prune [--keep <n>]         Keep the most recent managed worktrees (default 15)
+  adopt <path>               Manage an existing linked worktree
+  trust-setup                Trust this repository's .xharness/worktree-setup as it is now
+  path <name|id>             Print its folder (cd "$(xagent worktree path name)")
+
+Start the terminal in a new managed worktree with: xagent --worktree [name]
+`;
+function describe(record) {
+    const state = record.branch ?? 'detached';
+    const lease = record.lease ? ' · in use' : '';
+    return `${record.name.padEnd(20)} ${record.kind.padEnd(9)} ${state.padEnd(24)} ${record.path}${lease}`;
+}
+export async function findWorktree(worktrees, cwd, key, removed = false) {
+    const repo = await worktrees.repositoryOf(cwd);
+    const pool = removed ? worktrees.removed(repo) : await worktrees.list(repo);
+    const match = pool.find((record) => record.id === key || record.name === key);
+    if (!match)
+        throw new Error(`No ${removed ? 'removed ' : ''}worktree named ${key} in this repository.`);
+    return match;
+}
+export async function runWorktreeCli(argv, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    const cwd = resolve(dependencies.cwd ?? process.cwd());
+    const args = [];
+    let stateDir = join(dependencies.home ?? homedir(), '.xingular-harness', 'state');
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] === '--state')
+            stateDir = resolve(argv[++index] ?? stateDir);
+        else
+            args.push(argv[index]);
+    }
+    const [command, ...rest] = args;
+    const flag = (name) => rest.includes(name);
+    const value = (name) => {
+        const index = rest.indexOf(name);
+        return index >= 0 ? rest[index + 1] : undefined;
+    };
+    const positional = rest.filter((item, index) => !item.startsWith('--') && !(index > 0 && ['--branch', '--from', '--keep'].includes(rest[index - 1])));
+    const worktrees = new Worktrees(stateDir);
+    switch (command) {
+        case 'list': {
+            const records = await worktrees.list(cwd);
+            write(records.length ? `${records.map(describe).join('\n')}\n` : 'No worktrees for this repository.\n');
+            return 0;
+        }
+        case 'new': {
+            const result = await worktrees.create({
+                repo: cwd,
+                ...(positional[0] ? { name: positional[0] } : {}),
+                ...(value('--branch') ? { branch: value('--branch') } : {}),
+                ...(value('--from') ? { baseRef: value('--from') } : {}),
+                kind: flag('--permanent') ? 'permanent' : 'managed',
+                ...(flag('--no-carry') ? { carryChanges: false } : {})
+            });
+            write(`${describe(result.worktree)}\n`);
+            if (result.carried.copied.length || result.carried.patched)
+                write(`Carried your uncommitted changes${result.carried.copied.length ? ` and ${result.carried.copied.length} untracked file(s)` : ''}.\n`);
+            if (result.included.copied.length)
+                write(`Copied ${result.included.copied.length} file(s) named in .worktreeinclude.\n`);
+            if (result.setup.state === 'untrusted')
+                write('The repository has a setup script you have not trusted. Read .xharness/worktree-setup, then run: xagent worktree trust-setup\n');
+            if (result.setup.state === 'failed')
+                write(`The setup script failed; see ${result.setup.log}.\n`);
+            return 0;
+        }
+        case 'status': {
+            const status = await worktrees.status((await findWorktree(worktrees, cwd, positional[0] ?? '')).id);
+            write(`${describe(status.record)}\n${status.changes} changed path(s), ${status.ahead} commit(s) since it started.\n`);
+            return 0;
+        }
+        case 'branch': {
+            const record = await worktrees.branch((await findWorktree(worktrees, cwd, positional[0] ?? '')).id, positional[1] ?? '');
+            write(`${describe(record)}\n`);
+            return 0;
+        }
+        case 'handoff': {
+            const direction = positional[1] === 'to-main' ? 'toSource' : positional[1] === 'to-worktree' ? 'toWorktree' : null;
+            if (!direction) {
+                write(WORKTREE_USAGE);
+                return 2;
+            }
+            const result = await worktrees.handoff((await findWorktree(worktrees, cwd, positional[0] ?? '')).id, direction, { move: !flag('--copy') });
+            write(result.patched || result.copied.length ? `Handed off${result.copied.length ? ` (and ${result.copied.length} untracked file(s))` : ''}.${result.stash ? ` The origin's copy is kept in git stash ${result.stash.slice(0, 12)}.` : ''}\n` : 'Nothing to hand off.\n');
+            return 0;
+        }
+        case 'rm': {
+            const { worktree, snapshot } = await worktrees.remove((await findWorktree(worktrees, cwd, positional[0] ?? '')).id, { force: flag('--force') });
+            write(`Removed ${worktree.name}.${snapshot ? ` Its unsaved work is kept; xagent worktree restore ${worktree.name} brings it back.` : ''}\n`);
+            return 0;
+        }
+        case 'restore': {
+            const record = await worktrees.restore((await findWorktree(worktrees, cwd, positional[0] ?? '', true)).id);
+            write(`${describe(record)}\n`);
+            return 0;
+        }
+        case 'prune': {
+            const keep = value('--keep') ? Number(value('--keep')) : undefined;
+            const result = await worktrees.prune({ repo: cwd, ...(keep !== undefined && Number.isFinite(keep) ? { keep } : {}) });
+            write(`Removed ${result.removed.length} worktree(s)${result.removed.some((entry) => entry.snapshot) ? ', keeping snapshots of unsaved work' : ''}.\n`);
+            for (const failure of result.failed)
+                write(`Could not remove ${failure.id}: ${failure.error}\n`);
+            return result.failed.length ? 1 : 0;
+        }
+        case 'adopt': {
+            const record = await worktrees.adopt(resolve(cwd, positional[0] ?? ''));
+            write(`${describe(record)}\n`);
+            return 0;
+        }
+        case 'trust-setup': {
+            const { setupScript } = await import("./setup.js");
+            const repo = await worktrees.repositoryOf(cwd);
+            const script = setupScript(repo);
+            if (!script) {
+                write('This repository has no .xharness/worktree-setup.\n');
+                return 1;
+            }
+            await worktrees.trustSetup(repo, script.hash);
+            write(`Trusted the setup script (sha256 ${script.hash.slice(0, 12)}…). A changed script asks again.\n`);
+            return 0;
+        }
+        case 'path': {
+            write(`${(await findWorktree(worktrees, cwd, positional[0] ?? '')).path}\n`);
+            return 0;
+        }
+        default:
+            write(WORKTREE_USAGE);
+            return command && command !== 'help' ? 2 : 0;
+    }
+}

package/dist/sdk/worktrees/copy.d.ts

@@ -0,0 +1,9 @@
+import type { CopyReport } from "./types.js";
+export declare const INCLUDE_FILE = ".worktreeinclude";
+export declare function copyFiles(from: string, to: string, paths: readonly string[]): CopyReport;
+/** Untracked files that are not ignored: new work a person has not added yet. */
+export declare function untrackedFiles(checkout: string): Promise<string[]>;
+/** All ignored user files that must be bounded and captured before a worktree is removed. */
+export declare function ignoredFiles(checkout: string): Promise<string[]>;
+/** Ignored files that match `.worktreeinclude`, matched by git itself. */
+export declare function includedFiles(checkout: string): Promise<string[]>;

package/dist/sdk/worktrees/copy.js

@@ -0,0 +1,111 @@
+// Copies files git does not track into a worktree: untracked work carried from the source, and the
+// ignored files `.worktreeinclude` names (local settings, `.env`). A file is never overwritten, a
+// symlink is never followed, and sizes are capped.
+import { copyFileSync, existsSync, lstatSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { HarnessError } from "../core/errors.js";
+import { safeRelative } from "../core/fs.js";
+import { git, nulList } from "./git.js";
+export const INCLUDE_FILE = '.worktreeinclude';
+const FILE_CAP = 5 * 1024 * 1024;
+const TOTAL_CAP = 100 * 1024 * 1024;
+const IGNORED_FILE_COUNT_CAP = 10_000;
+const IGNORED_PATH_BYTES_CAP = 1024 * 1024;
+export function copyFiles(from, to, paths) {
+    const report = { copied: [], skipped: [] };
+    let total = 0;
+    for (const path of paths) {
+        let relative;
+        try {
+            relative = safeRelative(path);
+        }
+        catch {
+            continue;
+        }
+        const source = join(from, relative);
+        const target = join(to, relative);
+        if (existsSync(target)) {
+            report.skipped.push({ path: relative, reason: 'exists' });
+            continue;
+        }
+        let stat;
+        try {
+            stat = lstatSync(source);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink()) {
+            report.skipped.push({ path: relative, reason: 'symlink' });
+            continue;
+        }
+        if (!stat.isFile()) {
+            report.skipped.push({ path: relative, reason: 'not_file' });
+            continue;
+        }
+        if (stat.size > FILE_CAP) {
+            report.skipped.push({ path: relative, reason: 'too_large' });
+            continue;
+        }
+        if (total + stat.size > TOTAL_CAP) {
+            report.skipped.push({ path: relative, reason: 'over_total' });
+            continue;
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(source, target);
+        total += stat.size;
+        report.copied.push(relative);
+    }
+    return report;
+}
+/** Untracked files that are not ignored: new work a person has not added yet. */
+export async function untrackedFiles(checkout) {
+    return nulList((await git(checkout, ['ls-files', '--others', '--exclude-standard', '-z'])).stdout);
+}
+/** All ignored user files that must be bounded and captured before a worktree is removed. */
+export async function ignoredFiles(checkout) {
+    const paths = nulList((await git(checkout, ['ls-files', '--others', '--ignored', '--exclude-standard', '-z'])).stdout);
+    if (paths.length > IGNORED_FILE_COUNT_CAP)
+        throw ignoredFilesError(`there are more than ${IGNORED_FILE_COUNT_CAP} ignored files`);
+    let total = 0;
+    let pathBytes = 0;
+    return paths.map((path) => {
+        let relative;
+        try {
+            relative = safeRelative(path);
+        }
+        catch {
+            throw ignoredFilesError('an ignored path is unsafe');
+        }
+        pathBytes += Buffer.byteLength(relative) + 10;
+        if (pathBytes > IGNORED_PATH_BYTES_CAP)
+            throw ignoredFilesError('the ignored paths exceed the snapshot limit');
+        let stat;
+        try {
+            stat = lstatSync(join(checkout, relative));
+        }
+        catch {
+            throw ignoredFilesError(`could not inspect ${relative}`);
+        }
+        if (!stat.isFile() && !stat.isSymbolicLink())
+            throw ignoredFilesError(`${relative} is not a regular file or symlink`);
+        if (stat.size > FILE_CAP)
+            throw ignoredFilesError(`${relative} exceeds the ${FILE_CAP}-byte per-file limit`);
+        total += stat.size;
+        if (total > TOTAL_CAP)
+            throw ignoredFilesError(`ignored files exceed the ${TOTAL_CAP}-byte total limit`);
+        return relative;
+    });
+}
+function ignoredFilesError(reason) {
+    return new HarnessError('worktree_has_work', `Ignored files cannot be safely preserved: ${reason}.`, 'Move or remove those files, then try again.');
+}
+/** Ignored files that match `.worktreeinclude`, matched by git itself. */
+export async function includedFiles(checkout) {
+    const patterns = join(checkout, INCLUDE_FILE);
+    if (!existsSync(patterns))
+        return [];
+    const ignored = new Set(nulList((await git(checkout, ['ls-files', '--others', '--ignored', '--exclude-standard', '-z'])).stdout));
+    const matching = nulList((await git(checkout, ['ls-files', '--others', '--ignored', `--exclude-from=${patterns}`, '-z'])).stdout);
+    return matching.filter((path) => ignored.has(path));
+}

package/dist/sdk/worktrees/git.d.ts

@@ -0,0 +1,16 @@
+export interface GitResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface GitOptions {
+    input?: string | Buffer;
+    env?: Record<string, string>;
+    /** Return a failed result instead of throwing. */
+    allowFail?: boolean;
+}
+export declare function git(cwd: string, args: readonly string[], options?: GitOptions): Promise<GitResult>;
+/** The trimmed standard output of a git command that must succeed. */
+export declare function gitText(cwd: string, args: readonly string[], options?: GitOptions): Promise<string>;
+/** NUL-separated output as a list, without the empty last entry. */
+export declare function nulList(text: string): string[];

package/dist/sdk/worktrees/git.js

@@ -0,0 +1,81 @@
+// Git, run without a shell. Every configured clean/smudge/process filter is disabled so Harness
+// operations never run repository-provided filter code, and git never stops to ask.
+import { spawn } from 'node:child_process';
+import { HarnessError } from "../core/errors.js";
+const QUIET_FILTERS = ['-c', 'filter.lfs.smudge=', '-c', 'filter.lfs.process=', '-c', 'filter.lfs.required=false', '-c', 'core.hooksPath=/dev/null'];
+const FILTER_KEYS = /^filter\.(.*)\.(?:clean|smudge|process|required)$/i;
+function configuredFilters(cwd, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['config', '--null', '--name-only', '--get-regexp', '^filter\\..*\\.(clean|smudge|process|required)$'], {
+            cwd,
+            env,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => out.push(chunk));
+        child.stderr.on('data', (chunk) => err.push(chunk));
+        child.once('error', (error) => reject(new HarnessError('git_unavailable', `Git could not be started: ${error.message}`, 'Install git and make sure it is on PATH.')));
+        child.once('close', (code) => {
+            const stdout = Buffer.concat(out).toString('utf8');
+            if (code !== 0 && code !== 1) {
+                const stderr = Buffer.concat(err).toString('utf8').trim();
+                reject(new HarnessError('git_failed', `git config failed: ${stderr || `exit ${code ?? 1}`}`));
+                return;
+            }
+            const filters = new Set();
+            for (const key of stdout.split('\0').filter(Boolean)) {
+                const match = FILTER_KEYS.exec(key);
+                if (match)
+                    filters.add(match[1]);
+            }
+            resolve([...filters].flatMap((filter) => [
+                '-c', `filter.${filter}.clean=`,
+                '-c', `filter.${filter}.smudge=`,
+                '-c', `filter.${filter}.process=`,
+                '-c', `filter.${filter}.required=false`
+            ]));
+        });
+    });
+}
+export async function git(cwd, args, options = {}) {
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0', GIT_LFS_SKIP_SMUDGE: '1', LC_ALL: 'C', ...options.env };
+    const filters = await configuredFilters(cwd, env);
+    return new Promise((resolve, reject) => {
+        const input = options.input;
+        const hasInput = input !== undefined && input.length > 0;
+        const child = spawn('git', [...QUIET_FILTERS, ...filters, ...args], {
+            cwd,
+            env,
+            stdio: [hasInput ? 'pipe' : 'ignore', 'pipe', 'pipe']
+        });
+        const out = [];
+        const err = [];
+        child.stdout.on('data', (chunk) => out.push(chunk));
+        child.stderr.on('data', (chunk) => err.push(chunk));
+        child.once('error', (error) => reject(new HarnessError('git_unavailable', `Git could not be started: ${error.message}`, 'Install git and make sure it is on PATH.')));
+        child.once('close', (code) => {
+            const result = { code: code ?? 1, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') };
+            if (result.code !== 0 && !options.allowFail) {
+                reject(new HarnessError('git_failed', `git ${args.join(' ')} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`));
+                return;
+            }
+            resolve(result);
+        });
+        if (hasInput && child.stdin) {
+            child.stdin.on('error', (error) => {
+                if (error.code !== 'EPIPE')
+                    reject(new HarnessError('git_failed', `git ${args.join(' ')} could not read input: ${error.message}`));
+            });
+            child.stdin.end(input);
+        }
+    });
+}
+/** The trimmed standard output of a git command that must succeed. */
+export async function gitText(cwd, args, options = {}) {
+    return (await git(cwd, args, options)).stdout.trim();
+}
+/** NUL-separated output as a list, without the empty last entry. */
+export function nulList(text) {
+    return text.split('\0').filter(Boolean);
+}

package/dist/sdk/worktrees/serverMethods.d.ts

@@ -0,0 +1,3 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+export declare function worktreeServerMethods(harness: Harness): Record<string, Handler>;

package/dist/sdk/worktrees/serverMethods.js

@@ -0,0 +1,30 @@
+import { invalid } from "../core/errors.js";
+import { optional, text } from "../server/params.js";
+export function worktreeServerMethods(harness) {
+    return {
+        'worktrees.list': (params) => harness.worktrees.list(optional(params, 'repo')),
+        'worktrees.removed': (params) => harness.worktrees.removed(optional(params, 'repo')),
+        'worktrees.status': (params) => harness.worktrees.status(text(params, 'id')),
+        'worktrees.create': (params) => harness.worktrees.create({
+            repo: text(params, 'repo'),
+            ...(optional(params, 'name') ? { name: optional(params, 'name') } : {}),
+            ...(optional(params, 'baseRef') ? { baseRef: optional(params, 'baseRef') } : {}),
+            ...(optional(params, 'branch') ? { branch: optional(params, 'branch') } : {}),
+            ...(params.kind === 'permanent' || params.kind === 'managed' ? { kind: params.kind } : {}),
+            ...(typeof params.carryChanges === 'boolean' ? { carryChanges: params.carryChanges } : {}),
+            ...(typeof params.setup === 'boolean' ? { setup: params.setup } : {})
+        }),
+        'worktrees.branch': (params) => harness.worktrees.branch(text(params, 'id'), text(params, 'name')),
+        'worktrees.handoff': (params) => {
+            const direction = text(params, 'direction');
+            if (direction !== 'toSource' && direction !== 'toWorktree')
+                throw invalid('direction is toSource or toWorktree.');
+            return harness.worktrees.handoff(text(params, 'id'), direction, { move: params.move !== false });
+        },
+        'worktrees.remove': (params) => harness.worktrees.remove(text(params, 'id'), { force: params.force === true }),
+        'worktrees.restore': (params) => harness.worktrees.restore(text(params, 'id')),
+        'worktrees.prune': (params) => harness.worktrees.prune({ repo: optional(params, 'repo'), ...(typeof params.keep === 'number' ? { keep: params.keep } : {}) }),
+        'worktrees.adopt': (params) => harness.worktrees.adopt(text(params, 'path')),
+        'worktrees.setup.trust': async (params) => { await harness.worktrees.trustSetup(text(params, 'repo'), text(params, 'hash')); return {}; }
+    };
+}

package/dist/sdk/worktrees/service.d.ts

@@ -0,0 +1,73 @@
+import type { CreateWorktreeInput, CreateWorktreeResult, HandoffResult, WorktreeRecord, WorktreesOptions, WorktreeStatus } from "./types.js";
+export declare class Worktrees {
+    readonly root: string;
+    readonly branchPrefix: string;
+    readonly keep: number;
+    private readonly registryFile;
+    private readonly trust;
+    private readonly leaseCounts;
+    private chain;
+    constructor(stateDir: string, options?: WorktreesOptions);
+    private read;
+    private write;
+    private update;
+    /** Runs changes one at a time, so two requests never race on the registry or on git. */
+    private serial;
+    /** Releases leases whose process is gone. At start-up, this process's own leases are stale too. */
+    recover(startup?: boolean): string[];
+    get(id: string): WorktreeRecord;
+    private active;
+    /** The folder for a registered worktree; unknown ids remain opaque to the caller. */
+    pathOf(id: string): string | null;
+    /** The top folder of the repository a folder belongs to (the main checkout, for a linked worktree). */
+    repositoryOf(folder: string): Promise<string>;
+    list(repo?: string | null): Promise<WorktreeRecord[]>;
+    /** Worktrees removed with a snapshot, which `restore` can bring back. */
+    removed(repo?: string | null): WorktreeRecord[];
+    status(id: string): Promise<WorktreeStatus>;
+    private repoKey;
+    private uniqueName;
+    private branchName;
+    create(input: CreateWorktreeInput): Promise<CreateWorktreeResult>;
+    adopt(path: string): Promise<WorktreeRecord>;
+    /** A session starts using a worktree. Another live session's lease refuses it. */
+    acquire(id: string, holder: string): Promise<WorktreeRecord>;
+    release(id: string, holder: string): Promise<void>;
+    branch(id: string, name: string): Promise<WorktreeRecord>;
+    private reachable;
+    /** Records the worktree's commits and working changes under a snapshot ref. */
+    private snapshot;
+    remove(id: string, options?: {
+        force?: boolean;
+    }): Promise<{
+        worktree: WorktreeRecord;
+        snapshot: string | null;
+    }>;
+    private removeNow;
+    restore(id: string): Promise<WorktreeRecord>;
+    /** Keeps the most recently used managed worktrees of each repository and removes the rest, with snapshots. */
+    prune(options?: {
+        repo?: string | null;
+        keep?: number;
+    }): Promise<{
+        removed: {
+            worktree: WorktreeRecord;
+            snapshot: string | null;
+        }[];
+        failed: {
+            id: string;
+            error: string;
+        }[];
+    }>;
+    /**
+     * Moves work between the worktree and the main checkout. `toSource` brings the worktree's changes
+     * since it started (commits and working changes) to the main checkout; `toWorktree` brings the
+     * main checkout's uncommitted changes to the worktree. The target must have no tracked changes,
+     * and nothing changes when the patch does not apply. With `move` (the default), what was handed
+     * off is stashed away from the origin, where `git stash` can bring it back.
+     */
+    handoff(id: string, direction: 'toSource' | 'toWorktree', options?: {
+        move?: boolean;
+    }): Promise<HandoffResult>;
+    trustSetup(repo: string, hash: string): Promise<void>;
+}