@cjhyy/code-shell-capability-coding 0.8.0

package/dist/external-runtimes/shared/session-context-store.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Maps a Codex thread to the CodeShell session tool host that serves it.
+ *
+ * One loopback MCP bridge serves every concurrent Codex thread, so this map is
+ * what keeps two sessions apart. Identity arrives as `_meta.threadId`, injected
+ * by the Codex app-server and — verified empirically against codex-cli 0.145.0,
+ * see `docs/todo/evidence/` — not influenceable by the model. Tool *arguments*
+ * are the opposite: fully model-controlled, and therefore never consulted here.
+ *
+ * Every failure mode is a refusal. There is no "use the foreground session",
+ * no "most recent thread", and no "there's only one, so it must be that one" —
+ * §11.3 and §22.5 reject all of those, because each turns a background run into
+ * a cross-session action.
+ *
+ * Memory-only by design (§13.6): hosts hold live executors and approval routes,
+ * so the map is rebuilt after a restart rather than persisted.
+ */
+/** Anything the bridge can dispatch a tool call to. Structural on purpose so
+ *  this file stays free of a hard dependency on the host implementation. */
+export interface ToolHostRef {
+    readonly businessSessionId: string;
+}
+export type SessionContextMissReason = "missing_thread_id" | "unknown_thread" | "stale_generation" | "ambiguous_thread";
+export type SessionContextResult<T> = {
+    ok: true;
+    host: T;
+} | {
+    ok: false;
+    reason: SessionContextMissReason;
+};
+export interface ResolveRequest {
+    /** From `_meta.threadId` (or `_meta["x-codex-turn-metadata"].thread_id`). */
+    threadId: string | undefined;
+    /** App-server generation the request belongs to; see {@link bumpGeneration}. */
+    generation: number;
+}
+export declare class SessionContextStore<T extends ToolHostRef = ToolHostRef> {
+    /** Non-enumerable so a stray `JSON.stringify(store)` cannot leak live hosts. */
+    private readonly byThread;
+    private currentGeneration;
+    get size(): number;
+    get generation(): number;
+    /**
+     * Bind a thread to its host, in the store's CURRENT generation.
+     *
+     * The generation is a property of the store (one app-server lifetime), not of
+     * an individual entry, and callers deliberately cannot choose it. An earlier
+     * revision took it as a parameter and raised the counter to match, which made
+     * one registration reorder reachability for every other thread: registering at
+     * a lower generation stranded the new thread immediately, and registering at a
+     * higher one mass-evicted every healthy thread. Both were invisible to the
+     * suite because its only fencing test walked the happy sequence.
+     */
+    register(threadId: string, host: T): void;
+    /** Drop a thread. Call this BEFORE closing the host, so a late request finds
+     *  nothing rather than a disposed host (§13.4 ordering). */
+    unregister(threadId: string): void;
+    clear(): void;
+    /**
+     * Advance the generation, e.g. after an app-server restart. Requests stamped
+     * with an older generation are refused even if their thread id was re-used,
+     * which is what stops a late reply from the dead process landing on the new
+     * session (§13.6).
+     */
+    bumpGeneration(): number;
+    resolve(request: ResolveRequest): SessionContextResult<T>;
+    /**
+     * Resolve a batch that must belong to exactly one thread.
+     *
+     * Resolving each item separately would let a mixed batch touch two sessions
+     * on the strength of a single authorization, so a batch spanning threads is
+     * refused as a whole. An empty batch is refused too: there is no thread to
+     * attribute it to, and "nothing to do" is not a reason to hand back a host.
+     */
+    resolveBatch(threadIds: readonly (string | undefined)[], generation: number): SessionContextResult<T>;
+    /** Threads currently bound, for diagnostics. Ids only — never hosts. */
+    threadIds(): readonly string[];
+    /** Keep live hosts out of any accidental serialization (§12.4 logging rules). */
+    toJSON(): {
+        generation: number;
+        threadCount: number;
+    };
+}

package/dist/external-runtimes/shared/session-context-store.js

@@ -0,0 +1,114 @@
+/**
+ * Maps a Codex thread to the CodeShell session tool host that serves it.
+ *
+ * One loopback MCP bridge serves every concurrent Codex thread, so this map is
+ * what keeps two sessions apart. Identity arrives as `_meta.threadId`, injected
+ * by the Codex app-server and — verified empirically against codex-cli 0.145.0,
+ * see `docs/todo/evidence/` — not influenceable by the model. Tool *arguments*
+ * are the opposite: fully model-controlled, and therefore never consulted here.
+ *
+ * Every failure mode is a refusal. There is no "use the foreground session",
+ * no "most recent thread", and no "there's only one, so it must be that one" —
+ * §11.3 and §22.5 reject all of those, because each turns a background run into
+ * a cross-session action.
+ *
+ * Memory-only by design (§13.6): hosts hold live executors and approval routes,
+ * so the map is rebuilt after a restart rather than persisted.
+ */
+export class SessionContextStore {
+    /** Non-enumerable so a stray `JSON.stringify(store)` cannot leak live hosts. */
+    byThread = new Map();
+    currentGeneration = 1;
+    get size() {
+        return this.byThread.size;
+    }
+    get generation() {
+        return this.currentGeneration;
+    }
+    /**
+     * Bind a thread to its host, in the store's CURRENT generation.
+     *
+     * The generation is a property of the store (one app-server lifetime), not of
+     * an individual entry, and callers deliberately cannot choose it. An earlier
+     * revision took it as a parameter and raised the counter to match, which made
+     * one registration reorder reachability for every other thread: registering at
+     * a lower generation stranded the new thread immediately, and registering at a
+     * higher one mass-evicted every healthy thread. Both were invisible to the
+     * suite because its only fencing test walked the happy sequence.
+     */
+    register(threadId, host) {
+        this.byThread.set(threadId, { host, generation: this.currentGeneration });
+    }
+    /** Drop a thread. Call this BEFORE closing the host, so a late request finds
+     *  nothing rather than a disposed host (§13.4 ordering). */
+    unregister(threadId) {
+        this.byThread.delete(threadId);
+    }
+    clear() {
+        this.byThread.clear();
+    }
+    /**
+     * Advance the generation, e.g. after an app-server restart. Requests stamped
+     * with an older generation are refused even if their thread id was re-used,
+     * which is what stops a late reply from the dead process landing on the new
+     * session (§13.6).
+     */
+    bumpGeneration() {
+        this.currentGeneration += 1;
+        // Drop the entries the bump just made unreachable. Leaving them would pin
+        // live SessionToolHost objects — each holding an executor and an approval
+        // route — against GC for the process lifetime, growing with every restart.
+        // Callers re-register the threads they successfully resume.
+        this.byThread.clear();
+        return this.currentGeneration;
+    }
+    resolve(request) {
+        if (!request.threadId)
+            return { ok: false, reason: "missing_thread_id" };
+        const entry = this.byThread.get(request.threadId);
+        if (!entry)
+            return { ok: false, reason: "unknown_thread" };
+        // The load-bearing half is `request.generation`: it fences a request that was
+        // already in flight when the app-server restarted. Comparing the request
+        // against `entry.generation` instead would let a caller resurrect a stale
+        // entry by handing the stale number back in — the caller's word is not
+        // evidence about which generation is live.
+        //
+        // The `entry.generation` half is unreachable belt-and-braces today, because
+        // `bumpGeneration()` clears the map, so a surviving entry is always current.
+        // It is kept so that a future change which stops clearing cannot silently
+        // reopen the hole — but a mutation test will NOT flag its removal, and
+        // claiming otherwise would overstate the guard.
+        if (entry.generation !== this.currentGeneration ||
+            request.generation !== this.currentGeneration) {
+            return { ok: false, reason: "stale_generation" };
+        }
+        return { ok: true, host: entry.host };
+    }
+    /**
+     * Resolve a batch that must belong to exactly one thread.
+     *
+     * Resolving each item separately would let a mixed batch touch two sessions
+     * on the strength of a single authorization, so a batch spanning threads is
+     * refused as a whole. An empty batch is refused too: there is no thread to
+     * attribute it to, and "nothing to do" is not a reason to hand back a host.
+     */
+    resolveBatch(threadIds, generation) {
+        if (threadIds.length === 0)
+            return { ok: false, reason: "missing_thread_id" };
+        if (threadIds.some((id) => !id))
+            return { ok: false, reason: "missing_thread_id" };
+        const unique = new Set(threadIds);
+        if (unique.size > 1)
+            return { ok: false, reason: "ambiguous_thread" };
+        return this.resolve({ threadId: [...unique][0], generation });
+    }
+    /** Threads currently bound, for diagnostics. Ids only — never hosts. */
+    threadIds() {
+        return [...this.byThread.keys()];
+    }
+    /** Keep live hosts out of any accidental serialization (§12.4 logging rules). */
+    toJSON() {
+        return { generation: this.currentGeneration, threadCount: this.byThread.size };
+    }
+}

package/dist/external-runtimes/shared/spawn-env.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Environment for a spawned Codex process.
+ *
+ * The one non-obvious entry is `NO_PROXY`. Codex's Rust MCP client (reqwest)
+ * honours `HTTP_PROXY`/`HTTPS_PROXY`, and on a corporate network or behind a PAC
+ * file it will route even a `127.0.0.1` request through the upstream proxy. The
+ * proxy does not understand localhost, answers with an HTML error page, and every
+ * MCP transport dies with `UnexpectedContentType`. The user-visible symptom is
+ * "Codex cannot see any CodeShell tools" with nothing in the bridge log, because
+ * the request never arrives.
+ *
+ * Learned from the `makecindy/cindy` reference implementation (design §16)
+ * rather than the hard way.
+ */
+export interface RuntimeSpawnEnvOptions {
+    /** Base environment; defaults to the current process env. */
+    base?: NodeJS.ProcessEnv;
+    /** Bearer token env var name and value for the loopback MCP bridge. */
+    bridgeToken?: {
+        name: string;
+        value: string;
+    };
+}
+/**
+ * Merge the loopback hosts into `NO_PROXY`, preserving whatever the user already
+ * set. The lowercase `no_proxy` twin is deleted rather than also updated: Rust
+ * and Go read both, and leaving two spellings behind lets one silently override
+ * the other depending on which library looks first.
+ */
+export declare function buildRuntimeSpawnEnv(options?: RuntimeSpawnEnvOptions): NodeJS.ProcessEnv;

package/dist/external-runtimes/shared/spawn-env.js

@@ -0,0 +1,41 @@
+/**
+ * Environment for a spawned Codex process.
+ *
+ * The one non-obvious entry is `NO_PROXY`. Codex's Rust MCP client (reqwest)
+ * honours `HTTP_PROXY`/`HTTPS_PROXY`, and on a corporate network or behind a PAC
+ * file it will route even a `127.0.0.1` request through the upstream proxy. The
+ * proxy does not understand localhost, answers with an HTML error page, and every
+ * MCP transport dies with `UnexpectedContentType`. The user-visible symptom is
+ * "Codex cannot see any CodeShell tools" with nothing in the bridge log, because
+ * the request never arrives.
+ *
+ * Learned from the `makecindy/cindy` reference implementation (design §16)
+ * rather than the hard way.
+ */
+const LOOPBACK_NO_PROXY = ["127.0.0.1", "localhost", "::1"];
+/**
+ * Merge the loopback hosts into `NO_PROXY`, preserving whatever the user already
+ * set. The lowercase `no_proxy` twin is deleted rather than also updated: Rust
+ * and Go read both, and leaving two spellings behind lets one silently override
+ * the other depending on which library looks first.
+ */
+export function buildRuntimeSpawnEnv(options = {}) {
+    const base = options.base ?? process.env;
+    const env = { ...base };
+    const existing = [env.NO_PROXY, env.no_proxy]
+        .filter((value) => typeof value === "string" && value.length > 0)
+        .flatMap((value) => value.split(","))
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const merged = [...existing];
+    for (const host of LOOPBACK_NO_PROXY) {
+        if (!merged.some((entry) => entry.toLowerCase() === host))
+            merged.push(host);
+    }
+    env.NO_PROXY = merged.join(",");
+    delete env.no_proxy;
+    if (options.bridgeToken) {
+        env[options.bridgeToken.name] = options.bridgeToken.value;
+    }
+    return env;
+}

package/dist/git/parse-log.d.ts

@@ -0,0 +1,14 @@
+/** One coding-repository git log entry. */
+export interface GitLogEntry {
+    hash: string;
+    message: string;
+    author: string;
+    date: string;
+}
+/**
+ * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
+ * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * to "" rather than destructuring `undefined` and crashing on `.slice`
+ * (review-2026-05-30). Blank lines are skipped.
+ */
+export declare function parseGitLog(raw: string): GitLogEntry[];

package/dist/git/parse-log.js

@@ -0,0 +1,21 @@
+/**
+ * Parse `git log --format=%H|%s|%an|%ci` output into entries. Tolerates
+ * malformed/short lines (missing `|` separators) by defaulting absent fields
+ * to "" rather than destructuring `undefined` and crashing on `.slice`
+ * (review-2026-05-30). Blank lines are skipped.
+ */
+export function parseGitLog(raw) {
+    return raw
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => {
+        const parts = line.split("|");
+        const hash = parts[0] ?? "";
+        return {
+            hash: hash.slice(0, 8),
+            message: parts[1] ?? "",
+            author: parts[2] ?? "",
+            date: parts[3] ?? "",
+        };
+    });
+}

package/dist/git/utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Git utility functions for the git workflow commands.
+ *
+ * Every call goes through execFileSync with an argv array — no command
+ * strings, no shell interpolation. Even arguments that look "safe" (already
+ * quoted, hard-coded) are passed as separate argv tokens so a future caller
+ * can't accidentally widen the attack surface by interpolating user input
+ * into the string form.
+ */
+import { type GitLogEntry } from "./parse-log.js";
+export interface GitStatusEntry {
+    status: string;
+    path: string;
+}
+export type { GitLogEntry };
+export declare function isGitRepo(cwd: string): boolean;
+/**
+ * Resolve a directory to its PROJECT ROOT: the enclosing git repository's
+ * top-level dir if `cwd` is inside a git repo, otherwise `cwd` unchanged.
+ *
+ * This is the project-boundary rule the desktop uses when adding/identifying a
+ * project: picking a SUBDIRECTORY of a git repo should belong to that one repo
+ * (its root), not spawn a separate project per subdir — mirrors how editors
+ * (and Claude Code) treat a repo as one workspace. A non-git folder is its own
+ * project (returned as-is). Never throws; on any git failure falls back to cwd.
+ * Returns the git-reported toplevel (already absolute, forward-slashed on win).
+ */
+export declare function resolveProjectRoot(cwd: string): string;
+export declare function getCurrentBranch(cwd: string): string;
+export declare function getGitStatus(cwd: string): GitStatusEntry[];
+export declare function getGitDiff(cwd: string, opts?: {
+    staged?: boolean;
+    file?: string;
+}): string;
+export declare function getGitDiffStat(cwd: string, opts?: {
+    staged?: boolean;
+    file?: string;
+}): string;
+export declare function getGitLog(cwd: string, n?: number): GitLogEntry[];
+export declare function getRemoteUrl(cwd: string): string | undefined;
+export declare function gitAdd(cwd: string, files?: string[]): void;
+export declare function gitCommit(cwd: string, message: string): string;
+export declare function gitListBranches(cwd: string): {
+    name: string;
+    current: boolean;
+}[];
+export declare function gitCheckout(cwd: string, branch: string, create?: boolean): void;
+export declare function ghAvailable(): boolean;
+export declare function ghPrComments(cwd: string, prUrl: string): string;

package/dist/git/utils.js

@@ -0,0 +1,161 @@
+/**
+ * Git utility functions for the git workflow commands.
+ *
+ * Every call goes through execFileSync with an argv array — no command
+ * strings, no shell interpolation. Even arguments that look "safe" (already
+ * quoted, hard-coded) are passed as separate argv tokens so a future caller
+ * can't accidentally widen the attack surface by interpolating user input
+ * into the string form.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { parseGitLog } from "./parse-log.js";
+import { resolveExecutable, resolveGit } from "@cjhyy/code-shell-core/extension";
+// Resolve git/gh through PATH×PATHEXT on Windows so a .cmd/.exe shim is found
+// (bare execFile doesn't walk PATHEXT). No-op on POSIX. See utils/exec.ts.
+const GH_BIN = resolveExecutable("gh");
+/** Run git with an argv array and return its trimmed stdout. */
+function git(cwd, args, timeoutMs = 10000) {
+    return execFileSync(resolveGit(), args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+}
+/** Run gh with an argv array and return its trimmed stdout. */
+function gh(cwd, args, timeoutMs = 10000) {
+    return execFileSync(GH_BIN, args, { cwd, encoding: "utf-8", timeout: timeoutMs }).trim();
+}
+export function isGitRepo(cwd) {
+    try {
+        git(cwd, ["rev-parse", "--is-inside-work-tree"], 5000);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a directory to its PROJECT ROOT: the enclosing git repository's
+ * top-level dir if `cwd` is inside a git repo, otherwise `cwd` unchanged.
+ *
+ * This is the project-boundary rule the desktop uses when adding/identifying a
+ * project: picking a SUBDIRECTORY of a git repo should belong to that one repo
+ * (its root), not spawn a separate project per subdir — mirrors how editors
+ * (and Claude Code) treat a repo as one workspace. A non-git folder is its own
+ * project (returned as-is). Never throws; on any git failure falls back to cwd.
+ * Returns the git-reported toplevel (already absolute, forward-slashed on win).
+ */
+export function resolveProjectRoot(cwd) {
+    let realCwd = cwd;
+    try {
+        realCwd = realpathSync(cwd);
+    }
+    catch {
+        // Non-existent paths are allowed to fall back unchanged below.
+    }
+    try {
+        const top = git(realCwd, ["rev-parse", "--show-toplevel"], 5000);
+        return top ? realpathSync(top) : realCwd;
+    }
+    catch {
+        return realCwd;
+    }
+}
+export function getCurrentBranch(cwd) {
+    return git(cwd, ["branch", "--show-current"], 5000);
+}
+export function getGitStatus(cwd) {
+    const raw = git(cwd, ["status", "--porcelain"], 10000);
+    if (!raw)
+        return [];
+    return raw.split("\n").map((line) => ({
+        status: line.slice(0, 2).trim(),
+        path: line.slice(3),
+    }));
+}
+export function getGitDiff(cwd, opts) {
+    const args = ["diff", "--no-color"];
+    if (opts?.staged)
+        args.push("--staged");
+    // `--` terminates option parsing so a file path starting with `-` can't
+    // be re-interpreted as a flag.
+    if (opts?.file)
+        args.push("--", opts.file);
+    return git(cwd, args, 30000);
+}
+export function getGitDiffStat(cwd, opts) {
+    const args = ["diff", "--stat", "--no-color"];
+    if (opts?.staged)
+        args.push("--staged");
+    if (opts?.file)
+        args.push("--", opts.file);
+    return git(cwd, args, 10000);
+}
+export function getGitLog(cwd, n = 10) {
+    // `n` is numeric — coerce/validate to keep the argv clean even if a caller
+    // hands us a string.
+    const count = Number.isFinite(n) && n > 0 ? Math.floor(n) : 10;
+    const raw = git(cwd, ["log", "--oneline", "--format=%H|%s|%an|%ci", `-${count}`], 10000);
+    if (!raw)
+        return [];
+    return parseGitLog(raw);
+}
+export function getRemoteUrl(cwd) {
+    try {
+        return git(cwd, ["remote", "get-url", "origin"], 5000);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function gitAdd(cwd, files = ["."]) {
+    // `--` ensures a path starting with `-` cannot be parsed as a flag.
+    // Each file is its own argv token, so spaces / quotes / non-ASCII pass
+    // through verbatim with no shell parsing.
+    execFileSync(resolveGit(), ["add", "--", ...files], { cwd, timeout: 10000 });
+}
+export function gitCommit(cwd, message) {
+    // Pre-fix this used `JSON.stringify(message)` which only happened to be
+    // safe because JSON.stringify covers most shell metacharacters — but it's
+    // not real escaping. The argv form is.
+    return execFileSync(resolveGit(), ["commit", "-m", message], {
+        cwd,
+        encoding: "utf-8",
+        timeout: 30000,
+    }).trim();
+}
+export function gitListBranches(cwd) {
+    const raw = git(cwd, ["branch", "--no-color"], 5000);
+    if (!raw)
+        return [];
+    return raw.split("\n").map((line) => ({
+        current: line.startsWith("*"),
+        name: line.replace(/^\*?\s+/, "").trim(),
+    }));
+}
+export function gitCheckout(cwd, branch, create = false) {
+    // argv form defeats shell injection. We additionally reject branch names
+    // that start with `-` so a value like `--orphan` can't slip through git's
+    // own option parser (the trailing `--` trick doesn't help on checkout:
+    // git interprets it as the option's value, not as an option terminator).
+    if (typeof branch !== "string" || branch.length === 0) {
+        throw new Error("branch must be a non-empty string");
+    }
+    if (branch.startsWith("-")) {
+        throw new Error(`refusing branch name that starts with '-': ${branch}`);
+    }
+    const args = create ? ["checkout", "-b", branch] : ["checkout", branch];
+    execFileSync(resolveGit(), args, { cwd, timeout: 10000 });
+}
+export function ghAvailable() {
+    try {
+        execFileSync(GH_BIN, ["--version"], { encoding: "utf-8", timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function ghPrComments(cwd, prUrl) {
+    // Pre-fix `gh pr view ${prUrl}` interpolated the URL directly. argv form
+    // means even a value like "$(rm -rf ~)" is sent to gh as a literal
+    // positional argument (which gh will then reject as a bad PR URL).
+    return gh(cwd, ["pr", "view", prUrl, "--comments", "--json", "comments", "-q", ".comments[].body"], 30000);
+}

package/dist/git/worktree/crud.d.ts

@@ -0,0 +1,108 @@
+import { type SandboxBackend } from "@cjhyy/code-shell-core/extension";
+export interface WorktreeSession {
+    originalCwd: string;
+    worktreePath: string;
+    worktreeName: string;
+    worktreeBranch: string;
+    originalBranch?: string;
+    /** Immutable commit used to create the branch. Safe for later ahead checks. */
+    baseRef?: string;
+    /** User-facing ref selector (`head`, `fresh`, or an explicit ref). */
+    baseRefLabel?: string;
+    /** Gitignored files copied from `.worktreeinclude` / DriveAgent include patterns. */
+    includedFiles?: string[];
+    sessionId: string;
+    createdAt: number;
+}
+/** Per-platform setup/cleanup scripts (a project's localEnvironment). */
+export interface PlatformScripts {
+    default?: string;
+    macos?: string;
+    linux?: string;
+    windows?: string;
+}
+export interface CreateWorktreeOptions {
+    prefix?: string;
+    signal?: AbortSignal;
+    /** `head`, `fresh` (local origin/HEAD), or an explicit git ref. */
+    baseRef?: string;
+    /** Extra gitignore-style patterns, combined with a root `.worktreeinclude`. */
+    include?: string[];
+}
+/**
+ * Best-effort rollback for an aborted `git worktree add`.
+ *
+ * `allowRecursiveDelete` gates the `rm -rf` fallback. It must stay `false`
+ * whenever the worktree path already existed before this call: a `git worktree
+ * add` that fails with "already exists" never registered the path, so the
+ * fallback would recursively delete a directory (and any uncommitted work in
+ * it) that this call did not create. Only genuine partial-creation states —
+ * where `worktree add` succeeded and a later step failed — may fall back to a
+ * recursive delete.
+ */
+export declare function cleanupAbortedWorktree(gitRoot: string, worktreePath: string, branchName: string, allowRecursiveDelete?: boolean): Promise<void>;
+/**
+ * Pick the setup/cleanup script for the running platform, falling back to
+ * `default`. Empty/whitespace-only scripts are treated as absent so a project
+ * can leave a platform key blank without spawning an empty shell. `platform`
+ * defaults to `process.platform` so callers usually omit it; tests pass a
+ * fixed value.
+ */
+export declare function selectPlatformScript(scripts: PlatformScripts | undefined, platform?: NodeJS.Platform): string | undefined;
+/**
+ * Create an isolated git worktree for an agent session.
+ */
+export declare function createWorktree(cwd: string, slug: string, sessionId: string, opts?: CreateWorktreeOptions): Promise<WorktreeSession>;
+/** Copy gitignored configuration selected by `.worktreeinclude` and explicit
+ * patterns. Only regular files reported by `git ls-files --ignored` are copied,
+ * so patterns cannot escape the repository or overwrite tracked checkout data. */
+export declare function copyWorktreeIncludes(sourceRoot: string, worktreePath: string, explicitPatterns: readonly string[] | undefined): string[];
+export interface WorktreeSetupResult {
+    /** True if no setup script was configured for this platform (nothing ran). */
+    skipped: boolean;
+    /** True if a script ran and exited 0. */
+    ok: boolean;
+    /** Combined stdout/stderr, for surfacing to the user on failure. */
+    output: string;
+    /** Exit code when a script ran; undefined when skipped. */
+    exitCode?: number | null;
+}
+/**
+ * Run a project's `localEnvironment.setupScripts` once, in the freshly-created
+ * worktree's root, right after `git worktree add`.
+ */
+export declare function runWorktreeSetup(worktreePath: string, script: string | undefined, opts?: {
+    sandbox?: SandboxBackend;
+    shellEnv?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<WorktreeSetupResult>;
+export interface RemoveWorktreeResult {
+    /** True once `git worktree remove` completed and the directory is gone. */
+    dirRemoved: boolean;
+    /** The branch targeted for deletion when removeBranch=true. */
+    branch?: string;
+    /** True when removeBranch=true and branch deletion completed. */
+    branchDeleted?: boolean;
+    /** Non-empty when the worktree directory is gone but branch deletion failed. */
+    branchError?: string;
+}
+export interface RemoveWorktreeOptions {
+    prefix?: string;
+}
+export interface WorktreeChangeState {
+    uncommitted: boolean;
+    commitsAhead: number;
+    hasChanges: boolean;
+}
+/** Inspect both working-tree changes and commits made since the immutable base
+ * commit captured at creation time. */
+export declare function inspectWorktreeChanges(worktreePath: string, baseRef?: string): WorktreeChangeState;
+/** Prevent pruning/removal while an external agent owns the worktree. */
+export declare function lockWorktree(worktreePath: string, reason: string): void;
+/** Unlock is idempotent for lifecycle cleanup/keep paths. */
+export declare function unlockWorktree(worktreePath: string): void;
+/**
+ * Remove a worktree and optionally its branch.
+ */
+export declare function removeWorktree(worktreePath: string, removeBranch?: boolean, opts?: RemoveWorktreeOptions): RemoveWorktreeResult;