@bridge4dev/runner 0.13.1 → 0.26.0

package/dist/environment.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Everything that depends on WHICH USER the runner runs as.
+ *
+ * The install instructions offer a choice — root or a dedicated user — and both
+ * are legitimate. What is not legitimate is the way the second choice used to
+ * fail: silently, later, and in the agent's voice. A dedicated user typically
+ * owns none of the project directories, has an empty `$HOME` where the agent
+ * CLIs keep their login and settings, and reaches systemd only with
+ * `XDG_RUNTIME_DIR` set. Each of those produces a symptom that reads like a
+ * broken runner ("agent can't do anything", "not signed in", "service is fine"
+ * with exit code 0) while the real cause is a permission nobody was told about.
+ *
+ * This module turns each of them into a fact with a command next to it.
+ */
+export interface RunnerIdentity {
+    user: string;
+    uid: number;
+    gid: number;
+    home: string;
+    isRoot: boolean;
+}
+export declare function runnerIdentity(): RunnerIdentity;
+export interface PathAccess {
+    path: string;
+    exists: boolean;
+    isDirectory: boolean;
+    /** uid of the owner, or -1 when we could not stat it. */
+    ownerUid: number;
+    ownedByUs: boolean;
+    readable: boolean;
+    writable: boolean;
+    /**
+     * True when we could not even look — a directory ABOVE this one denies us
+     * traversal. Distinct from `!exists` on purpose: those are opposite answers
+     * to the person reading them («create it» vs «grant access»), and `statSync`
+     * reports both by throwing.
+     */
+    unreachable: boolean;
+}
+export declare function inspectPath(target: string): PathAccess;
+/**
+ * The first directory on this path the runner cannot enter.
+ *
+ * «Permission denied» on `/srv/apps/shop` is usually not about `shop` at all —
+ * it is about `/srv/apps`, and naming the wrong one sends the person to chmod
+ * a directory that was never the problem.
+ */
+export declare function firstUnreachableAncestor(target: string): string | null;
+/**
+ * Git refuses to work in a repository owned by somebody else — since 2022, and
+ * with no exception for root. So the "obvious" fix for a dedicated user (chown
+ * the project to it) breaks git for the person who was committing there before,
+ * and the exception has to be added on BOTH sides.
+ */
+export declare function safeDirectoryCommand(repoPath: string): string;
+export declare function looksLikeDubiousOwnership(message: string): boolean;
+/** Is this path already excused in the current user's git config? */
+export declare function hasSafeDirectory(repoPath: string): Promise<boolean>;
+export declare function addSafeDirectory(repoPath: string): Promise<void>;
+/**
+ * What the agent will find in this user's home besides a login.
+ *
+ * Copying only `.credentials.json` to a fresh user is the usual half-measure:
+ * the agent starts, and then behaves like a stranger — no permission allowlist,
+ * no slash commands, no plugins, default model. From the outside that reads as
+ * «the runner can't do anything», which is why this is worth reporting BEFORE
+ * the first session rather than diagnosing after it.
+ */
+export interface AgentConfigContour {
+    home: string;
+    claudeDir: boolean;
+    settings: boolean;
+    localSettings: boolean;
+    /** Number of entries in `permissions.allow`, or null when unreadable. */
+    allowRules: number | null;
+    commands: number;
+    plugins: boolean;
+    codexDir: boolean;
+    codexConfig: boolean;
+}
+export declare function agentConfigContour(home?: string): AgentConfigContour;
+/**
+ * Another user's home that already has an agent set up.
+ *
+ * Only reported, never copied: a copied OAuth credential means two accounts
+ * share one refresh token, and a rotation in either one silently invalidates
+ * the other. Signing in as the runner's own user is the clean answer; the copy
+ * is the fast one, and the person choosing between them deserves to be told
+ * which is which.
+ */
+export declare function otherHomeWithAgents(me?: RunnerIdentity): string | null;
+/**
+ * `systemctl --user` talks over a per-user D-Bus socket, and finds it through
+ * `XDG_RUNTIME_DIR`. Under `sudo -iu <user>` that variable is not set, and the
+ * failure is worse than an error: it prints «Failed to connect to bus» and
+ * exits **0**, so a health check reads it as success.
+ */
+export declare function systemdUserEnv(): NodeJS.ProcessEnv;
+/** True when the user bus is actually reachable — `systemctl --user` lies with exit 0. */
+export declare function systemdUserBusReachable(): Promise<boolean>;
+/** The command form that works under `sudo -iu <user>` — printed in hints. */
+export declare function systemctlHint(args: string): string;
+/**
+ * Remembered from binding and from session starts, so `doctor` can check the
+ * permissions of real projects instead of asking the person to name them.
+ * Best-effort on purpose: a runner that cannot write its own state directory
+ * has bigger problems than a diagnostic list, and none of them should turn a
+ * session start into an error.
+ */
+export declare function rememberWorkspacePath(workspacePath: string): void;
+export declare function knownWorkspacePaths(): string[];
+export interface ToolCheck {
+    /** `null` when the tool is not installed at all. */
+    path: string | null;
+    version?: string;
+    /** Set when the tool is there but this user cannot use it. */
+    problem?: string;
+}
+/**
+ * Node, as THIS user sees it.
+ *
+ * A dedicated user does not automatically inherit a Node installed for
+ * somebody else — fnm, nvm and a root-only prefix are all per-user by design.
+ * The runner itself is running, so node clearly exists somewhere; the question
+ * this answers is whether it is on the daemon user's own PATH, because that is
+ * what agent tooling and `npm install -g` will look at.
+ */
+export declare function nodeCheck(): Promise<ToolCheck>;
+/**
+ * Docker, as THIS user sees it.
+ *
+ * Reported rather than judged: plenty of projects never touch it. But when the
+ * project's own workflow is `docker compose`, a dedicated user without access
+ * to the socket produces a session that fails on its first command, and the
+ * error will be about a socket rather than about a group nobody was added to.
+ *
+ * Worth stating where it is stated: being in the `docker` group is equivalent
+ * to root on this machine. That is a fact for the owner to accept knowingly.
+ */
+export declare function dockerCheck(): Promise<ToolCheck>;
+/**
+ * Does the service survive a logout?
+ *
+ * `loginctl enable-linger` is what keeps a user's systemd services running with
+ * nobody logged in. `install-service` turns it on, but a unit installed by hand
+ * — or a user created afterwards — can miss it, and the failure looks like
+ * «the server goes offline whenever I close the terminal».
+ */
+export declare function lingerEnabled(): Promise<boolean | null>;
+/**
+ * Make the agent CLIs findable, without taking anything away.
+ *
+ * A systemd user service starts with the manager's PATH, which is the
+ * distribution default — `/usr/bin` and friends. Both agent CLIs are commonly
+ * installed somewhere else: `~/.local/bin` for a per-user install, and a
+ * node managed by fnm/nvm/volta lives under its own version directory. When
+ * `codex` sits there, the runner scans PATH, does not find it, and reports to
+ * the dashboard that this machine has no Codex at all — the agent the person
+ * installed simply never appears.
+ *
+ * Deliberately APPEND-ONLY, and deliberately in the process rather than in the
+ * unit file. Writing `Environment=PATH=…` into the unit would REPLACE whatever
+ * systemd gives the service today (`/snap/bin`, anything set through
+ * `environment.d`), trading something that works for something that is
+ * missing. Here nothing can be lost: entries are only added when they are
+ * absent and the directory actually exists.
+ *
+ * Returns what it added, so the caller can say so once at startup.
+ */
+export declare function ensureAgentPath(): string[];
+//# sourceMappingURL=environment.d.ts.map

package/dist/environment.js

@@ -0,0 +1,409 @@
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { knownWorkspacesPath } from './paths.js';
+const execFileAsync = promisify(execFile);
+export function runnerIdentity() {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : -1;
+    const gid = typeof process.getgid === 'function' ? process.getgid() : -1;
+    let user = process.env['USER'] ?? process.env['LOGNAME'] ?? '';
+    if (!user) {
+        try {
+            user = os.userInfo().username;
+        }
+        catch {
+            user = uid === 0 ? 'root' : String(uid);
+        }
+    }
+    return { user, uid, gid, home: os.homedir(), isRoot: uid === 0 };
+}
+/** As root every access check passes, which is true and worth saying out loud. */
+function canAccess(target, mode) {
+    try {
+        fs.accessSync(target, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function inspectPath(target) {
+    const me = runnerIdentity();
+    const base = {
+        path: target,
+        exists: false,
+        isDirectory: false,
+        ownerUid: -1,
+        ownedByUs: false,
+        readable: false,
+        writable: false,
+        unreachable: false,
+    };
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch (error) {
+        const code = error.code;
+        return code === 'ENOENT' || code === 'ENOTDIR' ? base : { ...base, unreachable: true };
+    }
+    return {
+        path: target,
+        exists: true,
+        isDirectory: stat.isDirectory(),
+        ownerUid: stat.uid,
+        ownedByUs: me.uid < 0 || stat.uid === me.uid,
+        readable: canAccess(target, fs.constants.R_OK),
+        writable: canAccess(target, fs.constants.W_OK),
+        unreachable: false,
+    };
+}
+/**
+ * The first directory on this path the runner cannot enter.
+ *
+ * «Permission denied» on `/srv/apps/shop` is usually not about `shop` at all —
+ * it is about `/srv/apps`, and naming the wrong one sends the person to chmod
+ * a directory that was never the problem.
+ */
+export function firstUnreachableAncestor(target) {
+    const parts = path.resolve(target).split(path.sep).filter(Boolean);
+    let current = path.sep;
+    for (const part of parts) {
+        current = path.join(current, part);
+        try {
+            fs.statSync(current);
+        }
+        catch (error) {
+            const code = error.code;
+            // ENOENT here means the path simply ends — not a permission problem.
+            return code === 'ENOENT' || code === 'ENOTDIR' ? null : current;
+        }
+        if (!canAccess(current, fs.constants.X_OK))
+            return current;
+    }
+    return null;
+}
+/**
+ * Git refuses to work in a repository owned by somebody else — since 2022, and
+ * with no exception for root. So the "obvious" fix for a dedicated user (chown
+ * the project to it) breaks git for the person who was committing there before,
+ * and the exception has to be added on BOTH sides.
+ */
+export function safeDirectoryCommand(repoPath) {
+    return `git config --global --add safe.directory ${repoPath}`;
+}
+export function looksLikeDubiousOwnership(message) {
+    return /dubious ownership|safe\.directory/i.test(message);
+}
+/** Is this path already excused in the current user's git config? */
+export async function hasSafeDirectory(repoPath) {
+    try {
+        const { stdout } = await execFileAsync('git', ['config', '--global', '--get-all', 'safe.directory'], { timeout: 10_000 });
+        const entries = stdout.split('\n').map((line) => line.trim());
+        return entries.includes(repoPath) || entries.includes('*');
+    }
+    catch {
+        // No git config at all (exit 1) — nothing is excused.
+        return false;
+    }
+}
+export async function addSafeDirectory(repoPath) {
+    await execFileAsync('git', ['config', '--global', '--add', 'safe.directory', repoPath], {
+        timeout: 10_000,
+    });
+}
+function countAllowRules(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const allow = parsed.permissions?.allow;
+        return Array.isArray(allow) ? allow.length : 0;
+    }
+    catch {
+        return null;
+    }
+}
+function countCommands(dir) {
+    let total = 0;
+    const walk = (current, depth) => {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                walk(path.join(current, entry.name), depth + 1);
+            else if (entry.name.endsWith('.md'))
+                total += 1;
+        }
+    };
+    walk(dir, 0);
+    return total;
+}
+export function agentConfigContour(home = os.homedir()) {
+    const claudeDir = path.join(home, '.claude');
+    const settings = path.join(claudeDir, 'settings.json');
+    const localSettings = path.join(claudeDir, 'settings.local.json');
+    const commandsDir = path.join(claudeDir, 'commands');
+    const codexDir = path.join(home, '.codex');
+    return {
+        home,
+        claudeDir: fs.existsSync(claudeDir),
+        settings: fs.existsSync(settings),
+        localSettings: fs.existsSync(localSettings),
+        allowRules: fs.existsSync(localSettings)
+            ? countAllowRules(localSettings)
+            : fs.existsSync(settings)
+                ? countAllowRules(settings)
+                : null,
+        commands: fs.existsSync(commandsDir) ? countCommands(commandsDir) : 0,
+        plugins: fs.existsSync(path.join(claudeDir, 'plugins')),
+        codexDir: fs.existsSync(codexDir),
+        codexConfig: fs.existsSync(path.join(codexDir, 'config.toml')),
+    };
+}
+/**
+ * Another user's home that already has an agent set up.
+ *
+ * Only reported, never copied: a copied OAuth credential means two accounts
+ * share one refresh token, and a rotation in either one silently invalidates
+ * the other. Signing in as the runner's own user is the clean answer; the copy
+ * is the fast one, and the person choosing between them deserves to be told
+ * which is which.
+ */
+export function otherHomeWithAgents(me = runnerIdentity()) {
+    const candidates = me.isRoot ? [] : ['/root'];
+    for (const home of candidates) {
+        if (home === me.home)
+            continue;
+        if (fs.existsSync(path.join(home, '.claude')) || fs.existsSync(path.join(home, '.codex'))) {
+            return home;
+        }
+    }
+    return null;
+}
+/**
+ * `systemctl --user` talks over a per-user D-Bus socket, and finds it through
+ * `XDG_RUNTIME_DIR`. Under `sudo -iu <user>` that variable is not set, and the
+ * failure is worse than an error: it prints «Failed to connect to bus» and
+ * exits **0**, so a health check reads it as success.
+ */
+export function systemdUserEnv() {
+    const env = { ...process.env };
+    if (!env['XDG_RUNTIME_DIR']) {
+        const uid = runnerIdentity().uid;
+        if (uid >= 0)
+            env['XDG_RUNTIME_DIR'] = `/run/user/${uid}`;
+    }
+    if (!env['DBUS_SESSION_BUS_ADDRESS'] && env['XDG_RUNTIME_DIR']) {
+        env['DBUS_SESSION_BUS_ADDRESS'] = `unix:path=${env['XDG_RUNTIME_DIR']}/bus`;
+    }
+    return env;
+}
+/** True when the user bus is actually reachable — `systemctl --user` lies with exit 0. */
+export async function systemdUserBusReachable() {
+    const dir = systemdUserEnv()['XDG_RUNTIME_DIR'];
+    if (!dir || !fs.existsSync(path.join(dir, 'bus')))
+        return false;
+    try {
+        const { stdout, stderr } = await execFileAsync('systemctl', ['--user', 'is-system-running'], {
+            timeout: 10_000,
+            env: systemdUserEnv(),
+        });
+        return !/Failed to connect to bus/i.test(`${stdout}${stderr}`);
+    }
+    catch (error) {
+        // A non-zero exit is normal here (`degraded`, `starting`); only a bus
+        // failure means we could not talk to systemd at all.
+        const text = String(error?.stderr ?? error);
+        return !/Failed to connect to bus|No medium found/i.test(text);
+    }
+}
+/** The command form that works under `sudo -iu <user>` — printed in hints. */
+export function systemctlHint(args) {
+    const me = runnerIdentity();
+    if (me.isRoot)
+        return `systemctl --user ${args}`;
+    return `sudo -iu ${me.user} env XDG_RUNTIME_DIR=/run/user/${me.uid} DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/${me.uid}/bus systemctl --user ${args}`;
+}
+// ─── Which project directories this machine actually works in ────────
+/**
+ * Remembered from binding and from session starts, so `doctor` can check the
+ * permissions of real projects instead of asking the person to name them.
+ * Best-effort on purpose: a runner that cannot write its own state directory
+ * has bigger problems than a diagnostic list, and none of them should turn a
+ * session start into an error.
+ */
+export function rememberWorkspacePath(workspacePath) {
+    try {
+        const file = knownWorkspacesPath();
+        const known = knownWorkspacePaths();
+        if (known.includes(workspacePath))
+            return;
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        // Newest last, capped: this is a diagnostic aid, not a registry.
+        const next = [...known, workspacePath].slice(-32);
+        fs.writeFileSync(file, JSON.stringify(next, null, 2), { mode: 0o600 });
+    }
+    catch {
+        /* diagnostics only */
+    }
+}
+export function knownWorkspacePaths() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(knownWorkspacesPath(), 'utf8'));
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function whichExecutable(name) {
+    for (const dir of (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, name);
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            return candidate;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return null;
+}
+/**
+ * Node, as THIS user sees it.
+ *
+ * A dedicated user does not automatically inherit a Node installed for
+ * somebody else — fnm, nvm and a root-only prefix are all per-user by design.
+ * The runner itself is running, so node clearly exists somewhere; the question
+ * this answers is whether it is on the daemon user's own PATH, because that is
+ * what agent tooling and `npm install -g` will look at.
+ */
+export async function nodeCheck() {
+    const found = whichExecutable('node');
+    if (!found)
+        return { path: null, problem: 'node is not on this user’s PATH' };
+    try {
+        const { stdout } = await execFileAsync(found, ['--version'], { timeout: 10_000 });
+        const version = stdout.trim();
+        const major = Number(version.replace(/^v/, '').split('.')[0]);
+        return {
+            path: found,
+            version,
+            ...(Number.isFinite(major) && major < 20 ? { problem: 'Node 20 or newer is required' } : {}),
+        };
+    }
+    catch (error) {
+        return { path: found, problem: String(error instanceof Error ? error.message : error) };
+    }
+}
+/**
+ * Docker, as THIS user sees it.
+ *
+ * Reported rather than judged: plenty of projects never touch it. But when the
+ * project's own workflow is `docker compose`, a dedicated user without access
+ * to the socket produces a session that fails on its first command, and the
+ * error will be about a socket rather than about a group nobody was added to.
+ *
+ * Worth stating where it is stated: being in the `docker` group is equivalent
+ * to root on this machine. That is a fact for the owner to accept knowingly.
+ */
+export async function dockerCheck() {
+    const found = whichExecutable('docker');
+    if (!found)
+        return { path: null };
+    const socket = '/var/run/docker.sock';
+    if (fs.existsSync(socket) && !canAccess(socket, fs.constants.R_OK | fs.constants.W_OK)) {
+        const me = runnerIdentity();
+        return {
+            path: found,
+            problem: `${me.user} cannot use the docker socket (membership of the docker group is equivalent to root here)`,
+        };
+    }
+    try {
+        await execFileAsync(found, ['info', '--format', '{{.ServerVersion}}'], { timeout: 15_000 });
+        return { path: found };
+    }
+    catch (error) {
+        return {
+            path: found,
+            problem: `docker is installed but did not answer: ${String(error instanceof Error ? error.message : error).slice(0, 160)}`,
+        };
+    }
+}
+/**
+ * Does the service survive a logout?
+ *
+ * `loginctl enable-linger` is what keeps a user's systemd services running with
+ * nobody logged in. `install-service` turns it on, but a unit installed by hand
+ * — or a user created afterwards — can miss it, and the failure looks like
+ * «the server goes offline whenever I close the terminal».
+ */
+export async function lingerEnabled() {
+    const me = runnerIdentity();
+    try {
+        const { stdout } = await execFileAsync('loginctl', ['show-user', me.user, '--property=Linger'], { timeout: 10_000 });
+        return stdout.trim().endsWith('=yes');
+    }
+    catch {
+        // No loginctl, or the user has no session recorded — unknown, not false.
+        return null;
+    }
+}
+/**
+ * Make the agent CLIs findable, without taking anything away.
+ *
+ * A systemd user service starts with the manager's PATH, which is the
+ * distribution default — `/usr/bin` and friends. Both agent CLIs are commonly
+ * installed somewhere else: `~/.local/bin` for a per-user install, and a
+ * node managed by fnm/nvm/volta lives under its own version directory. When
+ * `codex` sits there, the runner scans PATH, does not find it, and reports to
+ * the dashboard that this machine has no Codex at all — the agent the person
+ * installed simply never appears.
+ *
+ * Deliberately APPEND-ONLY, and deliberately in the process rather than in the
+ * unit file. Writing `Environment=PATH=…` into the unit would REPLACE whatever
+ * systemd gives the service today (`/snap/bin`, anything set through
+ * `environment.d`), trading something that works for something that is
+ * missing. Here nothing can be lost: entries are only added when they are
+ * absent and the directory actually exists.
+ *
+ * Returns what it added, so the caller can say so once at startup.
+ */
+export function ensureAgentPath() {
+    const entries = (process.env['PATH'] ?? '').split(path.delimiter).filter(Boolean);
+    const added = [];
+    for (const candidate of [
+        path.join(os.homedir(), '.local', 'bin'),
+        // The directory of the node running us — under fnm/nvm the agent CLIs and
+        // other globally installed tools sit next to it.
+        path.dirname(process.execPath),
+    ]) {
+        if (!candidate || entries.includes(candidate))
+            continue;
+        let usable;
+        try {
+            usable = fs.statSync(candidate).isDirectory();
+        }
+        catch {
+            usable = false;
+        }
+        if (!usable)
+            continue;
+        entries.push(candidate);
+        added.push(candidate);
+    }
+    if (added.length > 0)
+        process.env['PATH'] = entries.join(path.delimiter);
+    return added;
+}
+//# sourceMappingURL=environment.js.map

package/dist/git.d.ts

@@ -5,6 +5,16 @@ export interface PathValidation {
     branch?: string;
     error?: string;
 }
+/**
+ * Can this runner actually work in this directory — as the user it runs as?
+ *
+ * Everything here answers with the fix rather than the symptom. Binding a
+ * project is the moment the two legitimate install choices (root / dedicated
+ * user) start to differ, and until now the second one failed by forwarding
+ * git's own words to a dashboard the person may have no shell behind:
+ * «git check failed: fatal: detected dubious ownership in repository at
+ * '/opt/ids'». That sentence is true and unactionable.
+ */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
 export declare function sessionShortId(sessionId: string): string;
 export declare function sessionWorktreePath(sessionId: string): string;
@@ -22,6 +32,26 @@ export declare function repoKeyFor(pathInsideRepo: string): Promise<string>;
 export interface SessionWorktree {
     branch: string;
     worktreePath: string;
+    /** The branch this one forked from, when we created it just now. */
+    baseBranch?: string;
+    baseSha?: string;
+}
+/**
+ * What the API decided about this session's branch (session 13).
+ *
+ * Before this, the runner guessed: a branch that already existed was silently
+ * reused — so a second session on the same tickets inherited a stranger's
+ * commits — and a branch that did not was created off whatever the project
+ * folder was on. Both guesses are now errors, because both of them lose work
+ * without saying anything.
+ */
+export interface BranchPlan {
+    branch: string;
+    /** `NEW` — create it, and fail if it is already there. `CONTINUE` — the opposite. */
+    source: 'NEW' | 'CONTINUE';
+    /** Fork point for a NEW branch. `baseSha` wins when both are given. */
+    baseBranch?: string;
+    baseSha?: string;
 }
 /**
  * Accept a branch name from the API only if git would accept it too. The value
@@ -37,7 +67,58 @@ export declare function sanitizeBranch(hint: string | undefined): string | null;
  */
 export declare function ensureSessionWorktree(workspacePath: string, sessionId: string, branchHint?: string, options?: {
     requireExistingBranch?: boolean;
+    plan?: BranchPlan;
 }): Promise<SessionWorktree>;
+/**
+ * DIRECT mode (session 16): the session's workplace IS the project folder.
+ *
+ * Nothing is created and nothing is moved. The folder stays on the branch it is
+ * on, and that branch is the session's branch — which is the whole point: the
+ * work the agent does is already where the person expects to find it, with no
+ * «Apply» step in between and nothing to lose if the session is never applied.
+ *
+ * The two refusals are both about NOT guessing:
+ *
+ *  - not a git work tree — every git surface downstream would fail one call at
+ *    a time instead of once, here, with a sentence that names the folder;
+ *  - a detached HEAD — commits would land on no branch at all and be reachable
+ *    only by sha. A person who checked out a tag to look at something must not
+ *    discover an agent committed onto it.
+ *
+ * The path returned is the repository ROOT, not necessarily the folder that was
+ * configured. Every path in the Source Control panel is repo-root-relative
+ * because that is what `git status` prints, so the root is the only place the
+ * paths and the commands agree — and it is also the confinement root layer 1
+ * hands the agent.
+ */
+export declare function prepareDirectWorkspace(workspacePath: string): Promise<SessionWorktree>;
+/**
+ * One preview checkout per repository, and never the project folder itself.
+ *
+ * The honest constraint behind «show me branch B while branch A is running»:
+ * the docker build context IS the project folder, so a rebuild there replaces
+ * the single running copy. A second worktree is the only way to have both — and
+ * the runner NEVER switches the branch in the project folder, because that
+ * silently moves the base, and the target of «Apply», for every session of the
+ * project at once.
+ *
+ * Checked out DETACHED at a sha rather than on the branch: git refuses to have
+ * one branch checked out twice, and a preview is a snapshot of a commit, not a
+ * place anybody commits.
+ */
+export declare function previewWorktreePath(workspaceKey: string): string;
+export interface PreviewCheckout {
+    worktreePath: string;
+    branch: string;
+    sha: string;
+}
+export declare function ensurePreviewWorktree(input: {
+    workspacePath: string;
+    workspaceKey: string;
+    branch: string;
+}): Promise<PreviewCheckout>;
+/** Give the slot back. The branch is untouched — it was never checked out. */
+export declare function removePreviewWorktree(workspaceKey: string): Promise<boolean>;
 /**
  * Drop a session branch after its worktree is gone. Only ever called when the
  * API confirmed the work was already applied to the base branch — `-D` because