@prohost/cli 0.13.3 → 0.14.0

package/dist/codehost/checkouts.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Which local checkout a Code thread's `repo` means, and its worktree.
+ *
+ * A thread names its repository the way the server knows it (`Owner/name`);
+ * this machine knows checkouts by path — the `--repos` the operator gave
+ * `agent run`. A checkout matches when its `origin` remote is that repository,
+ * or, failing any remote match, when its directory has the repository's name.
+ *
+ * Each thread gets its own worktree through the harness's existing
+ * {@link WorktreeManager} conventions — `$PROHOST_HOME/worktrees/<lane>/<repo>`,
+ * detached at the remote's default branch, pruned after two idle weeks only if
+ * clean — on a lane of its own (`code-thread/<terminal>`), and is then switched
+ * to the thread's branch.
+ */
+import { WorktreeManager } from '../agent/worktrees.js';
+export type CheckoutResult = {
+    ok: true;
+    path: string;
+    source: string;
+    /**
+     * The worktree carries nothing the owner's checkout doesn't already have: made by this very
+     * call (never one kept from an earlier start, where an agent may have left files), clean
+     * (`git status --porcelain --ignored` empty: no untracked or ignored file, no edit), and on
+     * a commit that is the source's local HEAD or an ancestor of it. `false` otherwise, or
+     * when anything is unknown.
+     */
+    fromLocalHistory?: boolean;
+    /**
+     * A folder start: the opened folder the thread works in (its realpath), moved to the front
+     * of the opened-folders list once the thread's window is open. In place, `path` is this
+     * folder itself; with a separate copy, `path` is in a worktree of its checkout.
+     */
+    folder?: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export type Git = (args: string[]) => Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+}>;
+/** `owner/name` from a GitHub-style remote URL or slug, lower-cased; `undefined` if it has no such shape. */
+export declare function repoSlug(value: string): string | undefined;
+export declare function repoName(value: string): string;
+/**
+ * The `--repos` source for `repo`, or `undefined`.
+ *
+ * A checkout whose `origin` names a repository is that repository and no
+ * other: the directory-name fallback only considers checkouts with no
+ * readable `origin`, so `Other/app` never lands in an `app/` that is
+ * `Acme/app` (an agent there would commit and push to the wrong place).
+ */
+export declare function resolveSource(repo: string, sources: string[], git?: Git): Promise<string | undefined>;
+/**
+ * How a checkout is offered to Code threads: its `origin` as `Owner/name`, as
+ * written there, or its directory name when it has no GitHub-style `origin`.
+ * The server matches a thread's repository the way {@link resolveSource}
+ * does, so what is offered is exactly what a start can find.
+ */
+export declare function offeredName(source: string, git?: Git): Promise<string>;
+/** What a person reads when a thread names a repository this Mac has no checkout of. */
+export declare function notOfferedReason(repo: string, offered: string[]): string;
+/** Why a separate copy can't open in `relative`: the branch it checked out has no such folder. */
+export declare function separateCopyMissingReason(relative: string, branch?: string): string;
+export interface CodeThreadCheckoutsOptions {
+    repos: string[];
+    env?: NodeJS.ProcessEnv;
+    log?: (line: string) => void;
+    git?: Git;
+    /** Seam for tests: the manager for one source. */
+    manager?: (source: string) => Pick<WorktreeManager, 'prepare'>;
+}
+export declare class CodeThreadCheckouts {
+    private readonly options;
+    private readonly managers;
+    private readonly git;
+    constructor(options: CodeThreadCheckoutsOptions);
+    private managerFor;
+    /**
+     * The repositories this Mac offers Code threads, in `--repos` order, each
+     * once ({@link offeredName}). Declared to the server, which lists them for
+     * the person picking a repository and refuses a start for any other.
+     */
+    /** Every checkout's name, unbounded: for telling a person what this Mac has. */
+    names(): Promise<string[]>;
+    offered(): Promise<string[] | undefined>;
+    /**
+     * A folder start (`folder` in `code_thread.start_requested`): only a folder this Mac has opened,
+     * or one inside it (`folders.ts`). In place, the thread runs in that folder: no worktree, no
+     * branch. With `separateCopy`, the folder must be in a git work tree, and the thread gets that
+     * checkout's own worktree and branch, exactly as a repository thread does — in the same
+     * subfolder of it. A subfolder the branch doesn't have (untracked, ignored, or not on that
+     * branch) is refused, never swapped for the worktree's root; so is one that resolves outside the
+     * worktree on that branch (a symlink there), which would put the thread back in the owner's files.
+     */
+    prepareFolder(folder: string, terminalId: string, options?: {
+        separateCopy?: boolean;
+        branch?: string;
+    }): Promise<CheckoutResult>;
+    /**
+     * Remove a worktree this very start made (never one it reused: an earlier start of this thread
+     * may have left work in it) and then refused, before anything ran in it — and only while it
+     * holds nothing but its commit: `git worktree remove` deletes ignored files (a `.env`, build
+     * output) even from a tree git calls clean. Never `--force`. The branch stays.
+     */
+    private discardWorktree;
+    /** A start in `folder` (a realpath) succeeded: it goes to the front of the opened folders. */
+    folderStarted(folder: string): void;
+    prepare(repo: string, terminalId: string, branch?: string): Promise<CheckoutResult>;
+    /**
+     * The thread's own worktree of `source`, on `branch` when there is one, and whether this call
+     * made it (`git worktree add`) rather than reusing one an earlier start of the thread left.
+     */
+    private worktreeOf;
+    /**
+     * Whether what the worktree has checked out is in the source checkout's own history, decided
+     * from the commit itself (never from how the branch was chosen): its HEAD is the source's
+     * local HEAD or an ancestor of it. A remote branch, a tracked branch that moved on, a reused
+     * worktree with commits of its own, a default branch the owner hasn't pulled: all `false`.
+     */
+    /** Nothing in the worktree but its commit: no edit, no untracked or ignored file. */
+    private isClean;
+    private inSourceHistory;
+    /**
+     * Onto `branch`: a local branch of that name, else the remote's (tracked, explicitly), else a
+     * new one cut from here. Returns why it couldn't, or `undefined`.
+     */
+    private switchBranch;
+}

package/dist/codehost/checkouts.js

@@ -0,0 +1,270 @@
+/**
+ * Which local checkout a Code thread's `repo` means, and its worktree.
+ *
+ * A thread names its repository the way the server knows it (`Owner/name`);
+ * this machine knows checkouts by path — the `--repos` the operator gave
+ * `agent run`. A checkout matches when its `origin` remote is that repository,
+ * or, failing any remote match, when its directory has the repository's name.
+ *
+ * Each thread gets its own worktree through the harness's existing
+ * {@link WorktreeManager} conventions — `$PROHOST_HOME/worktrees/<lane>/<repo>`,
+ * detached at the remote's default branch, pruned after two idle weeks only if
+ * clean — on a lane of its own (`code-thread/<terminal>`), and is then switched
+ * to the thread's branch.
+ */
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { WorktreeManager } from '../agent/worktrees.js';
+import { isWithin, realDirectory, resolveOpenedFolder, SEPARATE_COPY_NEEDS_GIT, touchFolder } from './folders.js';
+const defaultGit = (args) => new Promise((resolve) => {
+    execFile('git', args, { timeout: 60_000, maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+        resolve({ ok: error === null, stdout: String(stdout), stderr: String(stderr) || (error?.message ?? '') });
+    });
+});
+/** `owner/name` from a GitHub-style remote URL or slug, lower-cased; `undefined` if it has no such shape. */
+export function repoSlug(value) {
+    const trimmed = value.trim().replace(/\.git$/i, '').replace(/\/+$/, '');
+    const match = /([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(trimmed.replace(/^[^:]+:(?!\/\/)/, '/'));
+    return match ? `${match[1]}/${match[2]}`.toLowerCase() : undefined;
+}
+export function repoName(value) {
+    const slug = repoSlug(value);
+    return (slug ? slug.split('/')[1] : value.trim()).toLowerCase();
+}
+/**
+ * The `--repos` source for `repo`, or `undefined`.
+ *
+ * A checkout whose `origin` names a repository is that repository and no
+ * other: the directory-name fallback only considers checkouts with no
+ * readable `origin`, so `Other/app` never lands in an `app/` that is
+ * `Acme/app` (an agent there would commit and push to the wrong place).
+ */
+export async function resolveSource(repo, sources, git = defaultGit) {
+    const wantedSlug = repoSlug(repo);
+    const anonymous = [];
+    for (const source of sources) {
+        const remote = await git(['-C', source, 'remote', 'get-url', 'origin']);
+        const slug = remote.ok ? repoSlug(remote.stdout) : undefined;
+        if (!slug)
+            anonymous.push(source);
+        else if (wantedSlug && slug === wantedSlug)
+            return source;
+    }
+    const wantedName = repoName(repo);
+    return anonymous.find((source) => path.basename(source).toLowerCase() === wantedName);
+}
+/**
+ * How a checkout is offered to Code threads: its `origin` as `Owner/name`, as
+ * written there, or its directory name when it has no GitHub-style `origin`.
+ * The server matches a thread's repository the way {@link resolveSource}
+ * does, so what is offered is exactly what a start can find.
+ */
+export async function offeredName(source, git = defaultGit) {
+    const remote = await git(['-C', source, 'remote', 'get-url', 'origin']);
+    const trimmed = remote.ok ? remote.stdout.trim().replace(/\.git$/i, '').replace(/\/+$/, '') : '';
+    const match = /([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(trimmed.replace(/^[^:]+:(?!\/\/)/, '/'));
+    return match ? `${match[1]}/${match[2]}` : path.basename(source);
+}
+/** Bounds on what is declared, within the server's own (`MAX_CODE_HOST_REPOS`, and a status frame's 8 KB). */
+const MAX_OFFERED_REPOS = 50;
+const MAX_OFFERED_CHARS = 4_000;
+const OFFERED_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)?$/;
+/** What a person reads when a thread names a repository this Mac has no checkout of. */
+export function notOfferedReason(repo, offered) {
+    if (offered.length === 0) {
+        return `This Mac isn't set up with any repositories for Code threads yet, so it can't work on ${repo}.`;
+    }
+    return `This Mac isn't set up for ${repo}. Pick one of its repositories: ${offered.join(', ')}.`;
+}
+/** Why a separate copy can't open in `relative`: the branch it checked out has no such folder. */
+export function separateCopyMissingReason(relative, branch) {
+    return (`${relative} isn't in ${branch ? `the branch ${branch}` : 'the separate copy'} (it may be untracked or ignored), ` +
+        'so a separate copy can’t start there. Start it in the repository’s folder, or work in place.');
+}
+export class CodeThreadCheckouts {
+    options;
+    managers = new Map();
+    git;
+    constructor(options) {
+        this.options = options;
+        this.git = options.git ?? defaultGit;
+    }
+    managerFor(source) {
+        let manager = this.managers.get(source);
+        if (!manager) {
+            manager =
+                this.options.manager?.(source) ??
+                    new WorktreeManager({ repos: [source], env: this.options.env, log: this.options.log });
+            this.managers.set(source, manager);
+        }
+        return manager;
+    }
+    /**
+     * The repositories this Mac offers Code threads, in `--repos` order, each
+     * once ({@link offeredName}). Declared to the server, which lists them for
+     * the person picking a repository and refuses a start for any other.
+     */
+    /** Every checkout's name, unbounded: for telling a person what this Mac has. */
+    async names() {
+        const names = [];
+        for (const source of this.options.repos) {
+            const name = await offeredName(source, this.git);
+            if (!names.some((seen) => seen.toLowerCase() === name.toLowerCase()))
+                names.push(name);
+        }
+        return names;
+    }
+    async offered() {
+        const names = [];
+        let chars = 0;
+        for (const source of this.options.repos) {
+            const name = await offeredName(source, this.git);
+            if (names.some((seen) => seen.toLowerCase() === name.toLowerCase()))
+                continue;
+            // A list the server would cut short (a name it drops, or more than a frame carries) would
+            // have it refuse the checkouts left out: then none is declared, and nothing is refused.
+            if (name.length > 200 || !OFFERED_NAME.test(name))
+                return undefined;
+            if (names.length >= MAX_OFFERED_REPOS || chars + name.length + 3 > MAX_OFFERED_CHARS)
+                return undefined;
+            names.push(name);
+            chars += name.length + 3;
+        }
+        return names;
+    }
+    /**
+     * A folder start (`folder` in `code_thread.start_requested`): only a folder this Mac has opened,
+     * or one inside it (`folders.ts`). In place, the thread runs in that folder: no worktree, no
+     * branch. With `separateCopy`, the folder must be in a git work tree, and the thread gets that
+     * checkout's own worktree and branch, exactly as a repository thread does — in the same
+     * subfolder of it. A subfolder the branch doesn't have (untracked, ignored, or not on that
+     * branch) is refused, never swapped for the worktree's root; so is one that resolves outside the
+     * worktree on that branch (a symlink there), which would put the thread back in the owner's files.
+     */
+    async prepareFolder(folder, terminalId, options = {}) {
+        const resolved = resolveOpenedFolder(folder, this.options.env);
+        if (!resolved.ok)
+            return resolved;
+        const real = resolved.path;
+        if (!options.separateCopy)
+            return { ok: true, path: real, source: real, fromLocalHistory: false, folder: real };
+        const inside = await this.git(['-C', real, 'rev-parse', '--is-inside-work-tree', '--show-toplevel']);
+        const [isWorkTree, top] = inside.ok ? inside.stdout.trim().split('\n') : [];
+        const toplevel = isWorkTree === 'true' && top ? realDirectory(top) : undefined;
+        if (!toplevel)
+            return { ok: false, reason: SEPARATE_COPY_NEEDS_GIT };
+        const made = await this.worktreeOf(toplevel, terminalId, options.branch);
+        const prepared = made.checkout;
+        if (!prepared.ok)
+            return prepared;
+        const relative = path.relative(toplevel, real);
+        if (!relative)
+            return { ...prepared, folder: real };
+        const worktree = realDirectory(prepared.path) ?? prepared.path;
+        const sub = realDirectory(path.join(worktree, relative));
+        const refusal = !sub
+            ? separateCopyMissingReason(relative, options.branch)
+            : !isWithin(sub, worktree)
+                ? `${relative} leads out of the separate copy on ${options.branch || 'its branch'}, so a thread can't start there.`
+                : undefined;
+        if (refusal || !sub) {
+            // Nothing ran in it: the copy goes, so it neither lingers nor keeps its branch checked out.
+            if (made.created)
+                await this.discardWorktree(toplevel, prepared.path);
+            return { ok: false, reason: refusal ?? separateCopyMissingReason(relative, options.branch) };
+        }
+        // Trust and history are judged on what the thread opens in: that subfolder.
+        return { ...prepared, path: sub, source: real, folder: real };
+    }
+    /**
+     * Remove a worktree this very start made (never one it reused: an earlier start of this thread
+     * may have left work in it) and then refused, before anything ran in it — and only while it
+     * holds nothing but its commit: `git worktree remove` deletes ignored files (a `.env`, build
+     * output) even from a tree git calls clean. Never `--force`. The branch stays.
+     */
+    async discardWorktree(source, worktree) {
+        if (!(await this.isClean(worktree))) {
+            this.options.log?.(`    ! kept the refused separate copy ${worktree}: it holds files besides its commit`);
+            return;
+        }
+        const removed = await this.git(['-C', source, 'worktree', 'remove', worktree]);
+        if (!removed.ok)
+            this.options.log?.(`    ! kept the refused separate copy ${worktree}: ${lastLine(removed.stderr)}`);
+    }
+    /** A start in `folder` (a realpath) succeeded: it goes to the front of the opened folders. */
+    folderStarted(folder) {
+        touchFolder(folder, this.options.env);
+    }
+    async prepare(repo, terminalId, branch) {
+        // Read back by the person who started the thread: what this Mac can work on, never a flag.
+        if (this.options.repos.length === 0)
+            return { ok: false, reason: notOfferedReason(repo, []) };
+        const source = await resolveSource(repo, this.options.repos, this.git);
+        if (!source)
+            return { ok: false, reason: notOfferedReason(repo, await this.names()) };
+        return (await this.worktreeOf(source, terminalId, branch)).checkout;
+    }
+    /**
+     * The thread's own worktree of `source`, on `branch` when there is one, and whether this call
+     * made it (`git worktree add`) rather than reusing one an earlier start of the thread left.
+     */
+    async worktreeOf(source, terminalId, branch) {
+        const prepared = await this.managerFor(source).prepare(`code-thread/${terminalId}`);
+        const checkout = prepared.checkouts[0];
+        if (!checkout) {
+            return { checkout: { ok: false, reason: prepared.failures[0]?.reason ?? 'the worktree could not be made' }, created: false };
+        }
+        const created = checkout.created === true;
+        if (branch) {
+            // An agent started anywhere but the thread's branch would commit to the wrong place.
+            const failure = await this.switchBranch(checkout.path, branch);
+            if (failure)
+                return { checkout: { ok: false, reason: failure }, created };
+        }
+        const fromLocalHistory = created && (await this.isClean(checkout.path)) && (await this.inSourceHistory(source, checkout.path));
+        return { checkout: { ok: true, path: checkout.path, source, fromLocalHistory }, created };
+    }
+    /**
+     * Whether what the worktree has checked out is in the source checkout's own history, decided
+     * from the commit itself (never from how the branch was chosen): its HEAD is the source's
+     * local HEAD or an ancestor of it. A remote branch, a tracked branch that moved on, a reused
+     * worktree with commits of its own, a default branch the owner hasn't pulled: all `false`.
+     */
+    /** Nothing in the worktree but its commit: no edit, no untracked or ignored file. */
+    async isClean(worktree) {
+        const status = await this.git(['-C', worktree, 'status', '--porcelain', '--ignored']);
+        return status.ok && status.stdout.trim() === '';
+    }
+    async inSourceHistory(source, worktree) {
+        const head = await this.git(['-C', worktree, 'rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+        const sha = head.ok ? head.stdout.trim() : '';
+        if (!/^[0-9a-f]{40,64}$/.test(sha))
+            return false;
+        return (await this.git(['-C', source, 'merge-base', '--is-ancestor', sha, 'HEAD'])).ok;
+    }
+    /**
+     * Onto `branch`: a local branch of that name, else the remote's (tracked, explicitly), else a
+     * new one cut from here. Returns why it couldn't, or `undefined`.
+     */
+    async switchBranch(checkout, branch) {
+        const valid = await this.git(['check-ref-format', '--branch', branch]);
+        if (!valid.ok)
+            return `${JSON.stringify(branch)} is not a valid branch name`;
+        const current = await this.git(['-C', checkout, 'symbolic-ref', '--quiet', '--short', 'HEAD']);
+        if (current.ok && current.stdout.trim() === branch)
+            return undefined;
+        // `--no-guess`: a local branch only; a remote one is tracked below, by name, not by guess.
+        if ((await this.git(['-C', checkout, 'switch', '--no-guess', branch])).ok)
+            return undefined;
+        const remote = await this.git(['-C', checkout, 'rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`]);
+        const switched = remote.ok
+            ? await this.git(['-C', checkout, 'switch', '-c', branch, '--track', `origin/${branch}`])
+            : await this.git(['-C', checkout, 'switch', '-c', branch]);
+        if (switched.ok)
+            return undefined;
+        return `could not switch the worktree to ${branch} (${lastLine(switched.stderr)})`;
+    }
+}
+function lastLine(stderr) {
+    return stderr.trim().split('\n').pop() || 'git switch failed';
+}

package/dist/codehost/claude_trust.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Claude Code's workspace trust, for the worktrees this host makes.
+ *
+ * Every Code thread runs in a worktree of its own, a directory Claude Code has
+ * never seen, so it opens on "Is this a project you created or one you
+ * trust?" before the goal runs. The dialog is a security check: a folder's
+ * `.claude/` settings and hooks run code. So a worktree is recorded as trusted
+ * (`projects[<path>].hasTrustDialogAccepted` in that account's global config,
+ * `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json`, as Claude Code
+ * itself does when the dialog is accepted) only when it carries nothing the
+ * owner hasn't already trusted: its checkout is one they trust in Claude Code
+ * ({@link claudeTrusts}), and what the worktree has checked out is that
+ * checkout's own history (the caller's check: its HEAD is an ancestor of, or
+ * is, the checkout's local HEAD). Otherwise the dialog shows, and the host
+ * tells the thread it is waiting on it.
+ *
+ * That file is Claude Code's, and running sessions rewrite it. So the write
+ * takes the same lock Claude Code does (an exclusive `<file>.lock` directory),
+ * changes only that one project's flag, and lands by rename. It never steals
+ * the lock and never creates the file: when it can't do it safely it does
+ * nothing, and the dialog shows as before.
+ */
+/**
+ * The config dir Claude Code runs on for this environment: `CLAUDE_CONFIG_DIR`, else its default
+ * `~/.claude`. Where it keeps its sessions (`projects/`).
+ */
+export declare function claudeConfigDir(env: NodeJS.ProcessEnv): string;
+/** The global config Claude Code reads for this environment (beside its dir by default: `~/.claude.json`). */
+export declare function claudeConfigPath(env: NodeJS.ProcessEnv): string;
+/**
+ * Whether the owner already trusts `workspace` in Claude Code (they ran it there and accepted
+ * the dialog): its own entry, by real path, as Claude Code keys a repository.
+ */
+export declare function claudeTrusts(workspace: string, env: NodeJS.ProcessEnv): boolean;
+/**
+ * Record `workspace` as trusted in Claude Code's config for `env`. Returns
+ * whether it is trusted afterwards (already, or now). `false` means nothing
+ * was written; Claude Code will ask, as it would anyway.
+ */
+export declare function trustClaudeWorkspace(workspace: string, env: NodeJS.ProcessEnv, waitMs?: number): Promise<boolean>;

package/dist/codehost/claude_trust.js

@@ -0,0 +1,129 @@
+/**
+ * Claude Code's workspace trust, for the worktrees this host makes.
+ *
+ * Every Code thread runs in a worktree of its own, a directory Claude Code has
+ * never seen, so it opens on "Is this a project you created or one you
+ * trust?" before the goal runs. The dialog is a security check: a folder's
+ * `.claude/` settings and hooks run code. So a worktree is recorded as trusted
+ * (`projects[<path>].hasTrustDialogAccepted` in that account's global config,
+ * `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json`, as Claude Code
+ * itself does when the dialog is accepted) only when it carries nothing the
+ * owner hasn't already trusted: its checkout is one they trust in Claude Code
+ * ({@link claudeTrusts}), and what the worktree has checked out is that
+ * checkout's own history (the caller's check: its HEAD is an ancestor of, or
+ * is, the checkout's local HEAD). Otherwise the dialog shows, and the host
+ * tells the thread it is waiting on it.
+ *
+ * That file is Claude Code's, and running sessions rewrite it. So the write
+ * takes the same lock Claude Code does (an exclusive `<file>.lock` directory),
+ * changes only that one project's flag, and lands by rename. It never steals
+ * the lock and never creates the file: when it can't do it safely it does
+ * nothing, and the dialog shows as before.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, realpathSync, renameSync, rmdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** How long to wait for Claude Code to finish a config write of its own. */
+const LOCK_WAIT_MS = 3_000;
+const LOCK_POLL_MS = 50;
+/**
+ * The config dir Claude Code runs on for this environment: `CLAUDE_CONFIG_DIR`, else its default
+ * `~/.claude`. Where it keeps its sessions (`projects/`).
+ */
+export function claudeConfigDir(env) {
+    return env.CLAUDE_CONFIG_DIR?.trim() || path.join(env.HOME || os.homedir(), '.claude');
+}
+/** The global config Claude Code reads for this environment (beside its dir by default: `~/.claude.json`). */
+export function claudeConfigPath(env) {
+    const dir = env.CLAUDE_CONFIG_DIR?.trim();
+    return dir ? path.join(dir, '.claude.json') : path.join(env.HOME || os.homedir(), '.claude.json');
+}
+/**
+ * Whether the owner already trusts `workspace` in Claude Code (they ran it there and accepted
+ * the dialog): its own entry, by real path, as Claude Code keys a repository.
+ */
+export function claudeTrusts(workspace, env) {
+    try {
+        const parsed = JSON.parse(readFileSync(claudeConfigPath(env), 'utf8'));
+        const projects = parsed?.projects;
+        return projects?.[realpathSync(workspace)]?.hasTrustDialogAccepted === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Record `workspace` as trusted in Claude Code's config for `env`. Returns
+ * whether it is trusted afterwards (already, or now). `false` means nothing
+ * was written; Claude Code will ask, as it would anyway.
+ */
+export async function trustClaudeWorkspace(workspace, env, waitMs = LOCK_WAIT_MS) {
+    let key;
+    try {
+        // Claude Code keys a project by its real path (a worktree under /tmp is /private/tmp/... on macOS).
+        key = realpathSync(workspace);
+    }
+    catch {
+        return false;
+    }
+    const file = claudeConfigPath(env);
+    const lock = `${file}.lock`;
+    const deadline = Date.now() + waitMs;
+    for (;;) {
+        try {
+            mkdirSync(lock);
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST' || Date.now() >= deadline)
+                return false;
+            // Waited without blocking: the daemon keeps serving acks, terminals and approvals meanwhile.
+            await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+        }
+    }
+    try {
+        let config;
+        let mode;
+        try {
+            mode = statSync(file).mode & 0o777;
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                return false;
+            config = parsed;
+        }
+        catch {
+            // No config yet, or one that doesn't parse: Claude Code's to create or repair, not ours.
+            return false;
+        }
+        const projects = config.projects && typeof config.projects === 'object' && !Array.isArray(config.projects)
+            ? config.projects
+            : {};
+        const current = projects[key];
+        const entry = current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+        if (entry.hasTrustDialogAccepted === true)
+            return true;
+        const next = { ...config, projects: { ...projects, [key]: { ...entry, hasTrustDialogAccepted: true } } };
+        const temp = `${file}.prohost-${randomBytes(6).toString('hex')}`;
+        try {
+            writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { mode });
+            renameSync(temp, file);
+        }
+        catch {
+            rmSync(temp, { force: true });
+            return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            rmdirSync(lock);
+        }
+        catch {
+            /* gone already */
+        }
+    }
+}

package/dist/codehost/command.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `prohost agent code-host …` — the machine owner's switches for hosting Code
+ * threads on this Mac. Only someone with a shell on this machine can run it;
+ * nothing the server sends can change them.
+ *
+ *     prohost agent code-host status
+ *     prohost agent code-host enable [--allow-remote-terminal]
+ *     prohost agent code-host remote on|off
+ *     prohost agent code-host disable
+ *     prohost agent code-host folders add <path> | list [--json] | remove <path>
+ *
+ * A running `agent run` reads the switches at start, and the remote switch
+ * again on every attach: `remote off` refuses the next viewer at once; `enable`
+ * and `disable` take effect when the agent restarts.
+ *
+ * `folders` is the list of folders this Mac has opened for Code threads
+ * (`folders.ts`): a thread started from a phone or the web may only run in one
+ * of them, or in a folder inside one. The desktop app adds each folder picked
+ * in its folder picker; a running agent reads the list at every start.
+ */
+type Flags = Record<string, string | boolean>;
+export declare function codeHostCommand(args: string[], flags: Flags, out?: (line: string) => void, err?: (line: string) => void): number;
+/** `prohost agent code-host folders …`. Prints paths only; nothing in the list is secret. */
+export declare function foldersCommand(args: string[], flags: Flags, out: (line: string) => void, err: (line: string) => void): number;
+export {};