@bridge4dev/runner 0.11.0

package/dist/auth-relay.js

@@ -0,0 +1,289 @@
+import { execFile, spawn } 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 { log } from './log.js';
+import { maskString } from './policy.js';
+import { adoptLoginResult, discardStagingHome, prepareStagingHome, repairCodexAuth, stagingCodexHomePath, } from './adapters/codex-home.js';
+const execFileAsync = promisify(execFile);
+/* eslint-disable no-control-regex -- this module parses raw pty output, so
+   matching ANSI/OSC escape bytes (\x1b, \x07) is exactly the point. */
+const URL_START_TIMEOUT_MS = 25_000;
+const CODE_EXCHANGE_TIMEOUT_MS = 60_000;
+// Longer than codex's own device-auth window (15 min) so we never kill a login
+// the provider still considers live.
+const RELAY_MAX_LIFETIME_MS = 16 * 60_000;
+const URL_PATTERNS = {
+    claude: /https:\/\/(?:claude\.com|claude\.ai)\/[^\s\x07\x1b"']+/,
+    codex: /https:\/\/[^\s\x07\x1b"']+/,
+};
+/** Strip ANSI/OSC control sequences so text matching sees plain output. */
+export function stripControl(raw) {
+    return raw
+        .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, ' ') // OSC (hyperlinks etc.)
+        .replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
+        .replace(/\x1b[()][A-Z0-9]/g, '')
+        .replace(/\r/g, '\n');
+}
+export function extractLoginUrl(agent, raw) {
+    // OSC-8 hyperlinks carry the pristine URL in the escape target — prefer it.
+    const osc = raw.match(/\x1b\]8;[^;]*;(https:\/\/[^\x07\x1b]+)(?:\x07|\x1b\\)/);
+    const candidate = osc?.[1] ?? stripControl(raw).match(URL_PATTERNS[agent])?.[0] ?? null;
+    if (!candidate)
+        return null;
+    return candidate.replace(/[.,)\]}>'"]+$/, '');
+}
+export function extractDeviceCode(raw) {
+    // Device-auth user codes look like XXXX-XXXX (letters/digits).
+    return stripControl(raw).match(/\b[A-Z0-9]{4,8}-[A-Z0-9]{4,8}\b/)?.[0] ?? null;
+}
+const LOGIN_COMMANDS = {
+    claude: 'claude setup-token',
+    codex: 'codex login --device-auth',
+};
+export class AuthRelay {
+    commands;
+    active = null;
+    constructor(commands = LOGIN_COMMANDS) {
+        this.commands = commands;
+    }
+    /** Start (or restart) a login flow and wait until the sign-in URL appears. */
+    async start(agent) {
+        this.cancel();
+        // Codex logs into a THROWAWAY home and is promoted only on success. The
+        // old flow deleted the shared credential link up front, so abandoning the
+        // sign-in (or letting it time out) left the server permanently signed out
+        // with no way back except restarting the daemon — and writing through the
+        // link would have overwritten the host user's own account (QA-100 MINOR-5).
+        const stagingHome = agent === 'codex' ? prepareStagingHome() : null;
+        const proc = spawn('script', ['-qec', this.commands[agent], '/dev/null'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // Codex must log in to a home WE control, never the host user's ~/.codex.
+            ...(stagingHome ? { env: { ...process.env, CODEX_HOME: stagingHome } } : {}),
+        });
+        const relay = {
+            agent,
+            proc,
+            buffer: '',
+            exited: false,
+            exitCode: null,
+            killTimer: setTimeout(() => this.cancel(), RELAY_MAX_LIFETIME_MS),
+        };
+        relay.killTimer.unref();
+        this.active = relay;
+        const append = (chunk) => {
+            relay.buffer = (relay.buffer + chunk.toString()).slice(-64_000);
+        };
+        proc.stdout?.on('data', append);
+        proc.stderr?.on('data', append);
+        proc.on('exit', (code) => {
+            relay.exited = true;
+            relay.exitCode = code;
+            // The Codex device flow has no callback into the dashboard: the CLI just
+            // exits once the browser side is confirmed. That exit IS the completion
+            // signal — promote the staging credential, or throw it away.
+            //
+            // Only when this relay is still the current one: the staging home is a
+            // single fixed path, so a cancelled login's exit handler firing late
+            // would otherwise delete the home a NEW login is already writing into.
+            if (relay.agent !== 'codex' || this.active !== relay)
+                return;
+            try {
+                if (code === 0 && adoptLoginResult(stagingCodexHomePath())) {
+                    log.info('codex: device login completed — credential adopted');
+                }
+                else {
+                    discardStagingHome();
+                }
+            }
+            catch (error) {
+                log.warn('codex: could not finish the device login', { error: String(error) });
+                discardStagingHome();
+            }
+        });
+        proc.on('error', (error) => {
+            relay.buffer += `\nspawn error: ${String(error)}`;
+            relay.exited = true;
+            relay.exitCode = -1;
+        });
+        const deadline = Date.now() + URL_START_TIMEOUT_MS;
+        for (;;) {
+            const url = extractLoginUrl(agent, relay.buffer);
+            if (url) {
+                const code = agent === 'codex' ? extractDeviceCode(relay.buffer) : null;
+                return { url, ...(code ? { code } : {}), expectsCode: agent === 'claude' };
+            }
+            if (relay.exited) {
+                const tail = maskString(stripControl(relay.buffer)).slice(-400);
+                this.cancel();
+                throw new Error(`${agent} login exited before printing a sign-in URL: ${tail}`);
+            }
+            if (Date.now() > deadline) {
+                this.cancel();
+                throw new Error(`${agent} login did not print a sign-in URL in time`);
+            }
+            await sleep(200);
+        }
+    }
+    /** Paste the confirmation code back into the waiting CLI (Claude flow). */
+    async submitCode(agent, code) {
+        const relay = this.active;
+        if (!relay || relay.agent !== agent) {
+            return { ok: false, detail: 'No login in progress — start again' };
+        }
+        if (relay.exited) {
+            this.cancel();
+            return { ok: false, detail: 'The login process has already exited — start again' };
+        }
+        relay.proc.stdin?.write(`${code.trim()}\n`);
+        const deadline = Date.now() + CODE_EXCHANGE_TIMEOUT_MS;
+        const bufferMark = relay.buffer.length;
+        while (Date.now() < deadline) {
+            const fresh = stripControl(relay.buffer.slice(bufferMark));
+            if (relay.exited) {
+                this.cancel();
+                if (relay.exitCode === 0)
+                    return { ok: true };
+                return { ok: false, detail: maskString(fresh).slice(-400) || 'Login failed' };
+            }
+            if (/invalid|error|failed|expired/i.test(fresh)) {
+                // The CLI usually re-prompts after a bad code; surface it and keep
+                // the relay alive so the user can retry with a corrected code.
+                return { ok: false, detail: maskString(fresh).trim().slice(-400) };
+            }
+            await sleep(300);
+        }
+        this.cancel();
+        return { ok: false, detail: 'Timed out waiting for the login to complete' };
+    }
+    cancel() {
+        const relay = this.active;
+        if (!relay)
+            return;
+        this.active = null;
+        clearTimeout(relay.killTimer);
+        try {
+            relay.proc.kill('SIGKILL');
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── Auth health probe ───────────────────────────────────────────────
+/**
+ * Claude: the subscription token's expiry is recorded in the CLI's own
+ * credentials file. The RUNNER reads it (its own host user's file) — the
+ * agent itself is still denied this path by layer-1 policy.
+ */
+export async function claudeAuthStatus(homedir = os.homedir()) {
+    if (process.env['CLAUDE_CODE_OAUTH_TOKEN']) {
+        return { status: 'ok', detail: 'CLAUDE_CODE_OAUTH_TOKEN is configured' };
+    }
+    const file = path.join(homedir, '.claude', '.credentials.json');
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        const oauth = parsed.claudeAiOauth;
+        if (!oauth)
+            return { status: 'missing', detail: 'No subscription login found' };
+        const expiresAt = oauth.expiresAt ? new Date(oauth.expiresAt).toISOString() : undefined;
+        if (oauth.expiresAt && oauth.expiresAt < Date.now()) {
+            return { status: 'expired', ...(expiresAt ? { expiresAt } : {}) };
+        }
+        return {
+            status: 'ok',
+            ...(expiresAt ? { expiresAt } : {}),
+            ...(oauth.subscriptionType ? { detail: `subscription ${oauth.subscriptionType}` } : {}),
+        };
+    }
+    catch {
+        return { status: 'missing', detail: 'No Claude login on this server' };
+    }
+}
+/**
+ * Codex reports its own login state via an exit code (0 signed in / 1 not).
+ * Probed against the RUNNER's home: the host user can be signed in while our
+ * isolated home is not, and it is ours that sessions use.
+ */
+export async function codexAuthStatus() {
+    // Re-assert the credential before judging it. The link into the shared store
+    // can disappear under a live daemon (codex has its own auth.json removal
+    // path), and reporting "login expired" about a credential that is merely
+    // unlinked — while the user's own file is valid for another week — is the
+    // exact complaint this fixes.
+    const home = repairCodexAuth();
+    const local = readCodexCredential(home.path);
+    if (home.auth === 'missing' && !local) {
+        return { status: 'missing', detail: 'not signed in on this server' };
+    }
+    try {
+        await execFileAsync('codex', ['login', 'status'], {
+            timeout: 10_000,
+            env: { ...process.env, CODEX_HOME: home.path },
+        });
+        return {
+            status: 'ok',
+            detail: home.auth === 'linked' ? 'signed in with ChatGPT (shared login)' : 'signed in with ChatGPT',
+            ...(local?.expiresAt ? { expiresAt: local.expiresAt } : {}),
+        };
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT')
+            return { status: 'missing', detail: 'codex CLI is not installed' };
+        if (typeof err.code === 'number') {
+            // Exit 1 means "no usable credential here" — which is "never signed in",
+            // not "your login expired". Only call it expired when we can see a
+            // credential that is genuinely past its date.
+            if (local?.expired) {
+                return {
+                    status: 'expired',
+                    detail: 'the stored login has expired',
+                    expiresAt: local.expiresAt,
+                };
+            }
+            return { status: 'missing', detail: 'not signed in on this server' };
+        }
+        // Timeout, signal, spawn failure — we learned nothing. Saying "expired"
+        // here sent users to re-login over a slow probe.
+        log.warn('auth-relay: codex login status probe failed', { error: String(error) });
+        return { status: 'unknown', detail: 'could not check the login on this server' };
+    }
+}
+/**
+ * Read what the runner's own auth.json says, without ever logging a token.
+ * Used only to tell "no credential" apart from "credential past its date" —
+ * the CLI probe is local and cannot detect a server-side revocation.
+ */
+function readCodexCredential(homePath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(homePath, 'auth.json'), 'utf8'));
+        const access = raw.tokens?.access_token;
+        if (!access)
+            return null;
+        // A refresh token means the access token's own expiry is not the whole
+        // story — codex renews it on its own.
+        if (raw.tokens?.refresh_token)
+            return { expired: false };
+        const payload = access.split('.')[1];
+        if (!payload)
+            return { expired: false };
+        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        if (typeof claims.exp !== 'number')
+            return { expired: false };
+        const expiresAt = new Date(claims.exp * 1000).toISOString();
+        return { expiresAt, expired: claims.exp * 1000 < Date.now() };
+    }
+    catch {
+        return null;
+    }
+}
+export async function agentAuthStatuses() {
+    const [claude, codex] = await Promise.all([claudeAuthStatus(), codexAuthStatus()]);
+    return { claude, codex };
+}
+//# sourceMappingURL=auth-relay.js.map

package/dist/config.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+declare const ConfigSchema: z.ZodObject<{
+    api: z.ZodObject<{
+        url: z.ZodString;
+        ws_url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        ws_url: string;
+    }, {
+        url: string;
+        ws_url: string;
+    }>;
+    server: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        token: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        name: string;
+        token: string;
+    }, {
+        id: string;
+        name: string;
+        token: string;
+    }>;
+    mcp: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        token: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        token: string;
+    }, {
+        url: string;
+        token: string;
+    }>>;
+    codex: z.ZodOptional<z.ZodObject<{
+        auth: z.ZodDefault<z.ZodEnum<["link", "own"]>>;
+    }, "strip", z.ZodTypeAny, {
+        auth: "link" | "own";
+    }, {
+        auth?: "link" | "own" | undefined;
+    }>>;
+    limits: z.ZodOptional<z.ZodObject<{
+        max_sessions: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        max_sessions: number;
+    }, {
+        max_sessions: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    api: {
+        url: string;
+        ws_url: string;
+    };
+    server: {
+        id: string;
+        name: string;
+        token: string;
+    };
+    codex?: {
+        auth: "link" | "own";
+    } | undefined;
+    mcp?: {
+        url: string;
+        token: string;
+    } | undefined;
+    limits?: {
+        max_sessions: number;
+    } | undefined;
+}, {
+    api: {
+        url: string;
+        ws_url: string;
+    };
+    server: {
+        id: string;
+        name: string;
+        token: string;
+    };
+    codex?: {
+        auth?: "link" | "own" | undefined;
+    } | undefined;
+    mcp?: {
+        url: string;
+        token: string;
+    } | undefined;
+    limits?: {
+        max_sessions: number;
+    } | undefined;
+}>;
+export type RunnerConfig = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): RunnerConfig | null;
+export declare function requireConfig(): RunnerConfig;
+export declare function saveConfig(config: RunnerConfig): void;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse, stringify } from 'smol-toml';
+import { z } from 'zod';
+import { configDir, configFilePath } from './paths.js';
+// config.toml holds the runner token — the file itself is the secret store
+// (0600, plan §8.1: provider/runner tokens never leave the user's server).
+const ConfigSchema = z.object({
+    api: z.object({
+        url: z.string().url(),
+        ws_url: z.string().url(),
+    }),
+    server: z.object({
+        id: z.string().min(1),
+        name: z.string().min(1),
+        token: z.string().regex(/^dbr_[A-Za-z0-9_-]+$/, 'runner token must start with dbr_'),
+    }),
+    // Optional: lets sessions reach DevBridge tickets over MCP. The dbk_ key is
+    // provisioned by the user (dashboard → API keys) until pairing issues one.
+    mcp: z
+        .object({
+        url: z.string().url(),
+        token: z.string().min(1),
+    })
+        .optional(),
+    // How the runner's isolated CODEX_HOME gets its credential.
+    //   link (default) — share the host user's ~/.codex/auth.json, so a token
+    //                    refresh on either side keeps both working;
+    //   own            — the runner keeps its own device login. Recommended when
+    //                    the owner also uses codex interactively on this machine:
+    //                    OpenAI rotates refresh tokens, and two processes sharing
+    //                    one credential store can invalidate each other.
+    codex: z
+        .object({
+        auth: z.enum(['link', 'own']).default('link'),
+    })
+        .optional(),
+    // Layer-1 resource guard (plan §8.6): a ceiling the dashboard cannot raise.
+    // The API also sends a per-server ceiling; the runner honours whichever is
+    // stricter, so the machine's owner always has the last word on how many agent
+    // processes and worktrees may exist at once.
+    limits: z
+        .object({
+        max_sessions: z.number().int().min(1).max(64),
+    })
+        .optional(),
+});
+export function loadConfig() {
+    const file = configFilePath();
+    if (!fs.existsSync(file))
+        return null;
+    const raw = fs.readFileSync(file, 'utf8');
+    return ConfigSchema.parse(parse(raw));
+}
+export function requireConfig() {
+    const config = loadConfig();
+    if (!config) {
+        throw new Error(`Runner is not paired: ${configFilePath()} not found. Run \`devbridge-runner pair <code> --api <url>\` first.`);
+    }
+    return config;
+}
+export function saveConfig(config) {
+    ConfigSchema.parse(config);
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = configFilePath();
+    const tmp = path.join(dir, `.config.toml.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, stringify(config) + '\n', { mode: 0o600 });
+    fs.renameSync(tmp, file);
+    // rename keeps the tmp file's mode, but harden in case the file pre-existed.
+    fs.chmodSync(file, 0o600);
+}
+//# sourceMappingURL=config.js.map

package/dist/fsview.d.ts

@@ -0,0 +1,20 @@
+export type FsViewResult = {
+    kind: 'dir';
+    path: string;
+    entries: FsEntry[];
+    truncated: boolean;
+} | {
+    kind: 'file';
+    path: string;
+    content?: string;
+    size: number;
+    truncated: boolean;
+    binary: boolean;
+};
+export interface FsEntry {
+    name: string;
+    type: 'dir' | 'file';
+    size: number | null;
+}
+export declare function fsView(root: string, relPath?: string): FsViewResult;
+//# sourceMappingURL=fsview.d.ts.map

package/dist/fsview.js

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSecretPath, maskString } from './policy.js';
+// Read-only file browser for the dashboard's Files tab (plan §5, session 4).
+// Same hard rules as the agent policy: secret paths are hidden from listings
+// and refused on read, symlinks are resolved, escaping the root is forbidden.
+const FILE_CAP_BYTES = 256 * 1024;
+const MAX_ENTRIES = 500;
+const BINARY_SNIFF_BYTES = 8 * 1024;
+/**
+ * The Files tab may only ever be pointed at a git work tree. Without this the
+ * root is whatever the API sent, and an org admin could retarget a workspace at
+ * `/home` and browse the box (QA-99 MAJOR-4 — the server-side half validates
+ * the path before storing it).
+ */
+function assertRepoRoot(rootReal) {
+    if (!fs.existsSync(path.join(rootReal, '.git'))) {
+        throw new Error('The workspace path is not a git repository');
+    }
+}
+function resolveInsideRoot(root, relPath) {
+    let rootReal;
+    try {
+        rootReal = fs.realpathSync(root);
+    }
+    catch {
+        throw new Error('The workspace path is not available on this server');
+    }
+    assertRepoRoot(rootReal);
+    const target = path.resolve(rootReal, relPath.replace(/^\/+/, ''));
+    // Lexical containment FIRST: resolving a non-existent outside path used to
+    // surface `ENOENT … '/root/x'`, i.e. an existence oracle plus absolute-path
+    // disclosure for anything outside the root (QA-99 MINOR-3).
+    const lexicalRel = path.relative(rootReal, target);
+    if (lexicalRel.startsWith('..') || path.isAbsolute(lexicalRel)) {
+        throw new Error('Path escapes the workspace root');
+    }
+    // Resolve symlinks so a link cannot smuggle a read outside the root.
+    let real;
+    try {
+        real = fs.realpathSync(target);
+    }
+    catch {
+        throw new Error('Path not found');
+    }
+    const rel = path.relative(rootReal, real);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        throw new Error('Path escapes the workspace root');
+    }
+    // `.git` is hidden from listings AND blocked from direct navigation —
+    // .git/config can carry remote-URL credentials (QA-98 F2).
+    if (rel.split(path.sep).includes('.git')) {
+        throw new Error('This path is protected by runner policy');
+    }
+    return real;
+}
+function isHiddenFromView(fullPath, name) {
+    return name === '.git' || isSecretPath(fullPath) || isSecretPath(name);
+}
+export function fsView(root, relPath = '.') {
+    const target = resolveInsideRoot(root, relPath);
+    if (isSecretPath(target))
+        throw new Error('This path is protected by runner policy');
+    let stat;
+    try {
+        stat = fs.statSync(target);
+    }
+    catch {
+        throw new Error('Path not found');
+    }
+    const rootReal = fs.realpathSync(root);
+    const displayPath = path.relative(rootReal, target) || '.';
+    if (stat.isDirectory()) {
+        const dirents = fs.readdirSync(target, { withFileTypes: true });
+        const visible = dirents.filter((d) => !isHiddenFromView(path.join(target, d.name), d.name));
+        visible.sort((a, b) => {
+            const dirDiff = Number(b.isDirectory()) - Number(a.isDirectory());
+            return dirDiff !== 0 ? dirDiff : a.name.localeCompare(b.name);
+        });
+        const truncated = visible.length > MAX_ENTRIES;
+        const entries = visible.slice(0, MAX_ENTRIES).map((d) => {
+            const isDir = d.isDirectory();
+            let size = null;
+            if (!isDir) {
+                try {
+                    size = fs.statSync(path.join(target, d.name)).size;
+                }
+                catch {
+                    size = null;
+                }
+            }
+            return { name: d.name, type: isDir ? 'dir' : 'file', size };
+        });
+        return { kind: 'dir', path: displayPath, entries, truncated };
+    }
+    if (!stat.isFile())
+        throw new Error('Not a regular file');
+    const size = stat.size;
+    const fd = fs.openSync(target, 'r');
+    try {
+        const sniff = Buffer.alloc(Math.min(BINARY_SNIFF_BYTES, size));
+        fs.readSync(fd, sniff, 0, sniff.length, 0);
+        if (sniff.includes(0)) {
+            return { kind: 'file', path: displayPath, size, truncated: false, binary: true };
+        }
+        const readLength = Math.min(FILE_CAP_BYTES, size);
+        const buffer = Buffer.alloc(readLength);
+        fs.readSync(fd, buffer, 0, readLength, 0);
+        return {
+            kind: 'file',
+            path: displayPath,
+            content: maskString(buffer.toString('utf8')),
+            size,
+            truncated: size > FILE_CAP_BYTES,
+            binary: false,
+        };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=fsview.js.map

package/dist/git.d.ts

@@ -0,0 +1,54 @@
+export interface PathValidation {
+    ok: boolean;
+    exists: boolean;
+    isGitRepo: boolean;
+    branch?: string;
+    error?: string;
+}
+export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
+export declare function sessionShortId(sessionId: string): string;
+export declare function sessionWorktreePath(sessionId: string): string;
+/**
+ * A stable key identifying the *shared* repository behind any path inside it.
+ *
+ * A linked worktree and its main checkout are the same repo: they share one
+ * object store, one index lock namespace and one branch namespace. Locking a
+ * commit by worktree path while locking a squash-merge by workspace path gave
+ * two different keys and therefore no mutual exclusion at all — a commit inside
+ * the worktree could interleave with a merge reading that same branch tip.
+ * `git rev-parse --git-common-dir` collapses both to the main `.git` directory.
+ */
+export declare function repoKeyFor(pathInsideRepo: string): Promise<string>;
+export interface SessionWorktree {
+    branch: string;
+    worktreePath: string;
+}
+/**
+ * Accept a branch name from the API only if git would accept it too. The value
+ * reaches a `git worktree add -b` argument, so anything odd — a leading dash, a
+ * `..`, a control character, a trailing `.lock` — is rejected in favour of the
+ * id-derived default rather than passed through.
+ */
+export declare function sanitizeBranch(hint: string | undefined): string | null;
+/**
+ * One branch + worktree per session (plan §7). The worktree lives under the
+ * runner's state dir so the user's checkout stays untouched; the branch lives
+ * in the workspace repo, so the work survives worktree cleanup.
+ */
+export declare function ensureSessionWorktree(workspacePath: string, sessionId: string, branchHint?: string, options?: {
+    requireExistingBranch?: boolean;
+}): Promise<SessionWorktree>;
+/**
+ * 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
+ * «Применить» is a squash-merge, which git never recognises as a merge, so `-d`
+ * would refuse exactly the branches that ARE safe to delete.
+ */
+export declare function deleteSessionBranch(workspacePath: string, branch: string): Promise<void>;
+/**
+ * Remove the session worktree (the branch — and the work — stays in the
+ * repo). The main repo is recovered from the worktree's `.git` pointer file,
+ * so the caller only needs the session id.
+ */
+export declare function removeSessionWorktree(sessionId: string): Promise<void>;
+//# sourceMappingURL=git.d.ts.map