@vibesdotdev/agent-execution 0.0.0-stage → 1.0.0-rc.2

package/dist/code-session/agent-code-session.impl.consumer.js

@@ -0,0 +1,2131 @@
+/**
+ * Consumer Agent Code Session — runtime-routed impl (WS3)
+ *
+ * A *persistent* code session: unlike the throwaway `agent/sandbox`, the
+ * workspace under the active Vibes profile SURVIVES across calls until
+ * an explicit `teardown`. Lifecycle:
+ *
+ *   initialize → clone repo (git CLI) into the persistent workspace, register
+ *               session metadata so `attach` can resume.
+ *   attach    → resume a known session (rehydrate from the metadata store).
+ *   runCommand→ foreground (capture stdout/stderr/exit) OR background (a
+ *               long-lived process handle kept in an in-process registry).
+ *   read/write/patch → file ops scoped under the workspace root.
+ *   gitStatus/Commit/Push → git CLI in the workspace.
+ *   exposePort → record a port + return a localhost preview URL.
+ *   teardown  → kill background procs, remove the persistent workspace.
+ *
+ * All file ops route through the `filesystem/adapter` kind and all command
+ * execution through the `runtime/execution` kind (consumer impls back both):
+ * one-shot git/foreground commands use `execute()`; a long-lived background
+ * process uses `spawn()` and keeps its `ProcessHandle` live in an in-process
+ * registry. Raw `node:fs` / `Bun.spawn` are NOT used here — the impl stays
+ * swappable.
+ *
+ * Env is composed through the handed runtime's `composeChildEnv`: only host essentials +
+ * the caller's explicit env are forwarded; nothing from the host's own environment leaks
+ * into session processes.
+ *
+ * MVP host routing: a `{ kind:'host', hostId }` target runs LOCALLY (on this
+ * consumer worker/daemon). Dispatching to a *specific remote* Host daemon by
+ * `hostId` is a documented follow-up — the `hostId` is recorded on the session
+ * handle so a future remote-dispatch layer can target it.
+ */
+import { getLogger } from '@vibesdotdev/logging';
+import { sha256Hex } from '@vibesdotdev/shared/hashing';
+import { CapabilityError, CaughtFailureSchema, composeChildEnv, createRuntimeImplementation, isCapabilityError, readEnv, settle, valueFreeFailure } from '@vibesdotdev/kernel';
+import { acquireWireProcess } from '@vibesdotdev/kernel-rpc/execution';
+import { getVibesRemoteFrom } from '@vibesdotdev/kernel-rpc';
+import { createFileExclusiveChecked, resolveFileSystemAdapter } from '@vibesdotdev/filesystem';
+import { getPathRoots, getRemotePathRoots } from '@vibesdotdev/paths';
+import * as z from 'zod/v4';
+import { CODE_SESSION_MIN_TRUST_LEVEL, AgentCodeSessionDescriptorSchema } from "./agent-code-session.descriptor.js";
+import consumerCodeSessionDescriptor from "./agent-code-session.consumer.descriptor.js";
+import { codeSessionCredentialArgs } from "./git-credential.js";
+import { DEFAULT_SESSION_HOST_TARGET } from "./host-target.js";
+import { CodeSessionOperationIdSchema, PersistedCodeSessionOperationSchema, codeSessionOperationFingerprint, codeSessionOperationKey, codeSessionTempName, parseCodeSessionCreateOrGetInput, parseCodeSessionId, parseCodeSessionInitializeInput, parseCodeSessionPath, parseExposePortInput, parseGitApplyInput, parseGitCommitInput, parseGitCommitOptions, parseGitPushInput, parsePatchFileInput, parseBackgroundProcessReadInput, parseBackgroundProcessWaitInput, parseProcessId, parseProcessSignal, parsePushCredentialResolver, parseRunCommandInput, parseWriteFileInput } from "./interfaces/code-session.js";
+import { pollUntil, withLeaseHeartbeat } from "./operation-lease.js";
+import { remoteSetupCustody } from "./remote-setup-custody.js";
+import { resolveRemoteWorkspaceFileSystem, parseRemoteFileSystemIO } from "./remote-workspace-fs.js";
+import { CODE_SESSION_METADATA_FILENAME, parseCodeSessionMetadata, serializeCodeSessionMetadata } from "./session-metadata.js";
+/** The consumer's logger on the runtime that owns the session (C083a): never an ambient default-bound one. */
+const consumerLogger = (runtime) => getLogger('agent.code-session.consumer', runtime);
+/** Directory below the active Vibes profile that owns durable local sessions. */
+const SESSION_DIRECTORY = 'code-sessions';
+/** Pre-profile local root. Read only for explicit, stable-id reattachment. */
+const LEGACY_LOCAL_SESSION_ROOT = '/tmp/vibes-code-session';
+const CONSUMER_FILESYSTEM_ADAPTER_ID = 'filesystem-adapter-bun';
+const SAFE_SESSION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+const CodeSessionOperationLeaseSchema = z
+    .object({
+    holderId: z.string().uuid(),
+    expiresAt: z.number().finite().nonnegative()
+})
+    .strict();
+const FileContentsSchema = z.union([z.string(), z.instanceof(Uint8Array)]);
+function utf8Text(contents) {
+    const admitted = FileContentsSchema.parse(contents);
+    const text = z.string().safeParse(admitted);
+    return text.success ? text.data : new TextDecoder().decode(z.instanceof(Uint8Array).parse(admitted));
+}
+function requestInvalid(field) {
+    return new CapabilityError('The code-session request is invalid.', 'INVALID_INPUT', {
+        reason: 'code-session-request-invalid',
+        retryable: false,
+        details: { field }
+    });
+}
+function metadataInvalid(cause) {
+    return new CapabilityError('Code-session control metadata is malformed.', 'INVALID_INPUT', {
+        reason: 'code-session-metadata-invalid',
+        retryable: false,
+        cause
+    });
+}
+/** Trust ladder ranks for the writable-FS escalation check. */
+const TRUST_RANK = { '0': 0, '1': 1, '2a': 2, '2b': 3, '3': 4 };
+function trustAllowsCodeSession(trustLevel) {
+    return TRUST_RANK[trustLevel] >= TRUST_RANK[CODE_SESSION_MIN_TRUST_LEVEL];
+}
+function isSafeSessionId(sessionId) {
+    return SAFE_SESSION_ID.test(sessionId);
+}
+function requireSafeSessionId(sessionId) {
+    if (!isSafeSessionId(sessionId)) {
+        throw requestInvalid('sessionId');
+    }
+    return sessionId;
+}
+function ownedWorkspacePath(fs, sessionRoot, sessionId) {
+    const safeId = requireSafeSessionId(sessionId);
+    const root = fs.normalize(fs.resolve(sessionRoot));
+    const candidate = fs.normalize(fs.resolve(root, safeId));
+    const rootWithSep = root.endsWith('/') ? root : `${root}/`;
+    if (candidate === root || !candidate.startsWith(rootWithSep)) {
+        throw requestInvalid('sessionId');
+    }
+    return candidate;
+}
+function assertOwnedWorkspacePath(fs, sessionRoot, sessionId, workspacePath) {
+    const expected = ownedWorkspacePath(fs, sessionRoot, sessionId);
+    if (fs.normalize(fs.resolve(workspacePath)) !== expected) {
+        throw new CapabilityError('Workspace cleanup is outside its owned session root.', 'CONFLICT', {
+            reason: 'code-session-cleanup-conflict',
+            retryable: false,
+            details: { sessionId }
+        });
+    }
+}
+const RemoteRuntimeExecutionSchema = z.custom((value) => z.object({ spawn: z.function() }).safeParse(value).success);
+function parseRemoteRuntimeExecution(value, hostId) {
+    try {
+        const parsed = RemoteRuntimeExecutionSchema.safeParse(value);
+        if (!parsed.success) {
+            throw new CapabilityError('The remote host exposes no execution capability.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable', retryable: false, details: { hostId }
+            });
+        }
+        return parsed.data;
+    }
+    catch (caught) {
+        const failure = CaughtFailureSchema.parse(caught);
+        if (isCapabilityError(failure))
+            throw failure;
+        throw new CapabilityError('The remote execution contract could not be read.', 'UNAVAILABLE', {
+            reason: 'code-session-host-unavailable',
+            retryable: false,
+            details: { hostId },
+            cause: valueFreeFailure(failure)
+        });
+    }
+}
+/** Output chunks a background process keeps for `readBackgroundProcess` / `waitBackgroundProcess`. */
+const MAX_BACKGROUND_CHUNKS = 512;
+/** How long a wait that saw the exit gives the pipes to deliver their last output. */
+const BACKGROUND_DRAIN_JOIN_MS = 1_000;
+/** The output a background entry produced after `since`, split by stream. */
+function backgroundOutputSince(entry, since, timedOut) {
+    const dropped = entry.produced - entry.output.length;
+    const from = Math.max(since ?? 0, dropped) - dropped;
+    const stdout = new TextDecoder();
+    const stderr = new TextDecoder();
+    let out = '';
+    let err = '';
+    for (const chunk of entry.output.slice(Math.min(from, entry.output.length))) {
+        if (chunk.stream === 'stdout')
+            out += stdout.decode(chunk.bytes, { stream: true });
+        else
+            err += stderr.decode(chunk.bytes, { stream: true });
+    }
+    out += stdout.decode();
+    err += stderr.decode();
+    return {
+        procId: entry.procId,
+        stdout: out,
+        stderr: err,
+        cursor: entry.produced,
+        running: entry.running,
+        exitCode: entry.running === false ? (entry.exitCode ?? null) : null,
+        timedOut
+    };
+}
+/** `lifecycle.wait` rejects a lapsed deadline as `CapabilityError` `TIMEOUT` `wait-timeout`. */
+function isBackgroundWaitTimeout(failure) {
+    return isCapabilityError(failure) && failure.code === 'TIMEOUT' && failure.reason === 'wait-timeout';
+}
+/** Reject paths that escape the workspace root (path-traversal guard). */
+function resolveInWorkspace(fs, workspacePath, relPath) {
+    const abs = fs.resolve(workspacePath, relPath);
+    const normalizedRoot = fs.normalize(workspacePath);
+    const rootWithSep = normalizedRoot.endsWith('/') ? normalizedRoot : `${normalizedRoot}/`;
+    if (abs !== normalizedRoot && !abs.startsWith(rootWithSep)) {
+        throw requestInvalid('path');
+    }
+    return abs;
+}
+/** Drain a (possibly null) ReadableStream into a UTF-8 string. */
+async function readStream(stream) {
+    if (!stream)
+        return '';
+    return new Response(stream).text();
+}
+/**
+ * Invoke `onAllocated` without letting it take down the initialize. A caller's
+ * bookkeeping failure must not strand an allocated workspace.
+ */
+async function notifyAllocated(input, sessionId, logger) {
+    if (!input.onAllocated)
+        return;
+    try {
+        await input.onAllocated(sessionId);
+    }
+    catch (caught) {
+        const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+        logger.warn('onAllocated threw; continuing initialization', {
+            sessionId,
+            failure
+        });
+        return failure;
+    }
+}
+export class ConsumerCodeSession {
+    descriptor;
+    /** In-process session registry, keyed by sessionId — backs `attach`. */
+    sessions = new Map();
+    /** Live background procs per session. */
+    background = new Map();
+    /** Host-supplied resolver for a push credential keyed by repositoryId. */
+    pushCredentialResolver;
+    /** In-flight attach-on-demand attempts, keyed by sessionId — collapses concurrent callers onto one attach. */
+    attachInFlight = new Map();
+    /** Cached remote execution handles per non-local hostId (fleet wire). */
+    remotes = new Map();
+    remoteActiveHomes = new Map();
+    /** Cached remote workspace filesystem adapters per non-local hostId (fleet wire). */
+    remoteFilesystems = new Map();
+    /**
+     * Same-process create retries collapse before they reach the durable operation
+     * ledger. Claims are registered synchronously, keyed by the trimmed operation
+     * id, so call order is claim order regardless of when hashing finishes.
+     */
+    operationInFlight = new Map();
+    /** Serializes git add/commit per git repository root so concurrent sessions never collide on .git/index.lock. */
+    gitCommitQueues = new Map();
+    runtime;
+    activeHome;
+    constructor(descriptor, runtime) {
+        this.descriptor = descriptor;
+        this.runtime = runtime;
+        this.activeHome = getPathRoots(this.runtime).activeHome;
+    }
+    /** This session's logger, on the runtime that owns it. */
+    get log() {
+        return consumerLogger(this.runtime);
+    }
+    now() {
+        return this.runtime.lifecycle.now();
+    }
+    nowIso() {
+        return new Date().toISOString();
+    }
+    /** Local control records stay under this runtime's active profile. */
+    sessionRoot(fs) {
+        return fs.normalize(fs.resolve(fs.join(this.activeHome, SESSION_DIRECTORY)));
+    }
+    async targetSessionRoot(fs, hostTarget) {
+        if (hostTarget.kind === 'host' && hostTarget.hostId !== 'local') {
+            const remote = await this.remoteRuntime(hostTarget.hostId);
+            const roots = await getRemotePathRoots(remote);
+            const previous = this.remoteActiveHomes.get(hostTarget.hostId);
+            if (previous && previous !== roots.activeHome) {
+                throw new CapabilityError('Remote profile changed; explicit session recovery is required.', 'CONFLICT', {
+                    reason: 'code-session-profile-conflict',
+                    retryable: false,
+                    details: { hostId: hostTarget.hostId }
+                });
+            }
+            this.remoteActiveHomes.set(hostTarget.hostId, roots.activeHome);
+            return fs.normalize(fs.resolve(fs.join(roots.activeHome, SESSION_DIRECTORY)));
+        }
+        return this.sessionRoot(fs);
+    }
+    /** The temp root of the host a session runs on, from that host's path roots. */
+    async targetTempRoot(fs, hostTarget) {
+        const roots = hostTarget.kind === 'host' && hostTarget.hostId !== 'local'
+            ? await getRemotePathRoots(await this.remoteRuntime(hostTarget.hostId))
+            : getPathRoots(this.runtime);
+        return fs.normalize(fs.resolve(roots.tempDir));
+    }
+    setPushCredentialResolver(resolver) {
+        this.pushCredentialResolver = parsePushCredentialResolver(resolver);
+    }
+    /** Workspace-local process state belongs to the control root, not source files.
+     * Keep a private home across reattachments without inheriting host credentials.
+     * TMPDIR lives under the host's temp root with a short name, so sockets bound
+     * under it fit the platform's socket path limit.
+     */
+    async processEnvironment(workspacePath, hostTarget, extra) {
+        const fs = await this.workspaceFilesystem(hostTarget);
+        const key = sha256Hex(workspacePath);
+        const root = fs.join(await this.targetSessionRoot(fs, hostTarget), '.environments', key);
+        const home = fs.join(root, 'home');
+        const temp = fs.join(await this.targetTempRoot(fs, hostTarget), codeSessionTempName(key));
+        await Promise.all([fs.mkdir(home, { recursive: true }), fs.mkdir(temp, { recursive: true })]);
+        const declared = {
+            HOME: home,
+            TMPDIR: temp,
+            VIBES_WORKSPACE_PATH: workspacePath,
+            GIT_CONFIG_COUNT: '1',
+            GIT_CONFIG_KEY_0: 'commit.gpgsign',
+            GIT_CONFIG_VALUE_0: 'false',
+            ...extra
+        };
+        if (hostTarget.kind === 'host' && hostTarget.hostId !== 'local')
+            return declared;
+        await this.seedGitAuthorIdentity(fs, home);
+        const env = composeChildEnv(this.runtime, { env: { PWD: workspacePath, ...declared } });
+        if (!readEnv({ platform: this.runtime.localEnvironment.getPlatform?.(), snapshot: env }, 'PATH')) {
+            throw new CapabilityError('The runtime that owns this child captured no PATH.', 'UNAVAILABLE', {
+                reason: 'host-path-unavailable', retryable: false
+            });
+        }
+        return env;
+    }
+    async seedGitAuthorIdentity(fs, home) {
+        const targetGitConfig = fs.join(home, '.gitconfig');
+        if (await fs.exists(targetGitConfig))
+            return;
+        const hostHome = this.runtime.getEnv('HOME');
+        if (!hostHome)
+            return;
+        const sourceGitConfig = fs.join(hostHome, '.gitconfig');
+        if (!(await fs.exists(sourceGitConfig)))
+            return;
+        const content = utf8Text(await fs.readFile(sourceGitConfig, 'utf8'));
+        let inUserSection = false;
+        let name;
+        let email;
+        for (const rawLine of content.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line || line.startsWith('#') || line.startsWith(';'))
+                continue;
+            const sectionMatch = /^\[([^\]]+)\]$/.exec(line);
+            if (sectionMatch) {
+                inUserSection = sectionMatch[1].trim().toLowerCase() === 'user';
+                continue;
+            }
+            if (!inUserSection)
+                continue;
+            const kvMatch = /^([A-Za-z0-9-]+)\s*=\s*(.*)$/.exec(line);
+            if (!kvMatch)
+                continue;
+            const key = kvMatch[1].toLowerCase();
+            const value = kvMatch[2].trim().replace(/^"(.*)"$/, '$1');
+            if (key === 'name' && value)
+                name = value;
+            else if (key === 'email' && value)
+                email = value;
+        }
+        if (!name && !email)
+            return;
+        const lines = ['[user]'];
+        if (name)
+            lines.push(`\tname = ${name}`);
+        if (email)
+            lines.push(`\temail = ${email}`);
+        await fs.writeFile(targetGitConfig, `${lines.join('\n')}\n`, 'utf8');
+    }
+    /**
+     * Resolve the `runtime/execution` impl for a session's host target.
+     *
+     * THE JOIN (D-THE-JOIN): a `{ kind:'host', hostId }` target with a NON-local
+     * hostId reaches THAT host's execution impl over the fleet wire via
+     * `getVibesRemoteFrom(runtime, hostId)` (the proven path — fleet-daemon
+     * `reach-over-daemon.test.ts`). Local + default targets keep resolving the
+     * in-process impl exactly as before. There is NO silent local fallback: an
+     * unreachable host throws a precise, actionable error.
+     */
+    async execution() {
+        const impl = await this.runtime
+            .query('runtime/execution')
+            .resolve();
+        if (!impl) {
+            throw new CapabilityError('No execution capability is registered for this runtime scope.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable',
+                retryable: false
+            });
+        }
+        return impl;
+    }
+    /**
+     * Reach a remote host's `runtime/execution` over the fleet `runtime/rpc`
+     * wire. A `RemoteRuntime` pins its socket, so one connection per hostId is
+     * cached and reused across a session's commands; a failed resolve is dropped
+     * from the cache so a later call can retry once the host is paired.
+     */
+    remoteRuntime(hostId) {
+        let pending = this.remotes.get(hostId);
+        if (!pending) {
+            pending = getVibesRemoteFrom(this.runtime, hostId);
+            this.remotes.set(hostId, pending);
+            const owned = pending;
+            const evict = () => {
+                if (this.remotes.get(hostId) === owned) {
+                    this.remotes.delete(hostId);
+                    this.remoteFilesystems.delete(hostId);
+                }
+            };
+            void pending.then((remote) => remote.connection.closed.then(evict, (caught) => {
+                const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+                this.log.warn('remote code-session connection closed with a failure', { hostId, failure });
+                evict();
+                return failure;
+            }), (caught) => {
+                const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+                evict();
+                return failure;
+            });
+        }
+        return pending;
+    }
+    /**
+     * Spawn on the session's host. With `setup`, cancellation is checked after
+     * every pre-dispatch await: a cancelled setup returns `null` and dispatches
+     * nothing. A remote dispatch is owned by an acquisition retained in this
+     * runtime's custody (plugin `onDispose` drains it), so a late port is killed
+     * once and observed rather than abandoned.
+     */
+    async spawnOnHost(workspacePath, hostTarget, options, extra, setup) {
+        const remoteTarget = hostTarget.kind === 'host' && hostTarget.hostId !== 'local';
+        const custody = remoteSetupCustody(this.runtime);
+        if (remoteTarget)
+            custody.admit();
+        const env = await this.processEnvironment(workspacePath, hostTarget, extra);
+        if (setup?.cancelled())
+            return null;
+        if (remoteTarget) {
+            const remote = await this.remoteRuntime(hostTarget.hostId);
+            if (setup?.cancelled())
+                return null;
+            const execution = parseRemoteRuntimeExecution(await remote.query('runtime/execution'), hostTarget.hostId);
+            if (setup?.cancelled())
+                return null;
+            const request = { ...options, declaration: { env } };
+            custody.admit();
+            const acquisition = custody.retain(acquireWireProcess(this.runtime, () => execution.spawn(request)));
+            setup?.dispatched(acquisition);
+            return acquisition.ready;
+        }
+        const execution = await this.execution();
+        if (setup?.cancelled())
+            return null;
+        setup?.dispatched();
+        return execution.spawn({ ...options, env, envMode: 'replace' });
+    }
+    async spawnBackground(workspacePath, hostTarget, options, extra) {
+        const handle = await this.spawnOnHost(workspacePath, hostTarget, options, extra);
+        // Without a setup control nothing can cancel before dispatch.
+        if (!handle)
+            throw new CapabilityError('Background process setup was cancelled', 'UNAVAILABLE', { reason: 'code-session-setup-cancelled', retryable: false });
+        return handle;
+    }
+    /**
+     * Reach a remote host's workspace `filesystem/adapter` over the fleet
+     * `runtime/rpc` wire (UNIT-B3 / D-DAEMON-CLIENT), mirroring
+     * {@link remoteExecution}. One connection per hostId is cached and reused; a
+     * failed resolve is dropped so a later call can retry once the host is paired.
+     */
+    remoteFilesystem(hostId) {
+        let pending = this.remoteFilesystems.get(hostId);
+        if (!pending) {
+            pending = this.resolveRemoteFilesystem(hostId).then((adapter) => adapter, (caught) => {
+                this.remoteFilesystems.delete(hostId);
+                throw CapabilityError.from(CaughtFailureSchema.parse(caught));
+            });
+            this.remoteFilesystems.set(hostId, pending);
+        }
+        return pending;
+    }
+    async resolveRemoteFilesystem(hostId) {
+        let remote;
+        try {
+            remote = await this.remoteRuntime(hostId);
+        }
+        catch (caught) {
+            const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+            this.log.warn('remote session host is unavailable', { hostId, failure });
+            throw new CapabilityError('The remote session host is unavailable.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable', retryable: true, details: { hostId }, cause: failure
+            });
+        }
+        const io = parseRemoteFileSystemIO(await remote.query('filesystem/adapter'), hostId);
+        return resolveRemoteWorkspaceFileSystem(io, hostId);
+    }
+    /**
+     * Resolve the LOCAL read/write filesystem adapter (the consumer's own disk);
+     * throw clearly if absent. This backs the session CONTROL ROOT (persisted
+     * metadata, borrowed bookkeeping, discovery) which always lives on THIS host,
+     * never a remote workspace. Workspace file ops use {@link workspaceFilesystem}.
+     */
+    async filesystem() {
+        // Code-session workspaces and their control metadata are host-managed and
+        // may intentionally live outside the currently bound user workspace.
+        const adapter = await resolveFileSystemAdapter(this.runtime, {
+            explicitId: CONSUMER_FILESYSTEM_ADAPTER_ID
+        });
+        if (!adapter) {
+            throw new CapabilityError('No workspace filesystem capability is registered for this runtime scope.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable',
+                retryable: false
+            });
+        }
+        return adapter;
+    }
+    /**
+     * Resolve the filesystem that backs a session's WORKSPACE. A `{ kind:'host',
+     * hostId }` target with a NON-local hostId reaches THAT host's workspace over
+     * the fleet wire (UNIT-B3, mirroring {@link execution}); local + default + cloud
+     * targets keep resolving the in-process adapter. There is NO silent local
+     * fallback: an unreachable host throws a precise, actionable error.
+     */
+    workspaceFilesystem(hostTarget = DEFAULT_SESSION_HOST_TARGET) {
+        if (hostTarget.kind === 'host' && hostTarget.hostId !== 'local') {
+            return this.remoteFilesystem(hostTarget.hostId);
+        }
+        return this.filesystem();
+    }
+    /**
+     * Resolve a session's metadata, attempting attach-on-demand exactly once if
+     * the id is unknown IN THIS PROCESS: a session initialized by a prior process
+     * on this host persisted its metadata under the profile-owned session root (see
+     * `attach()`), so a cold process can still serve it. Concurrent calls for the
+     * same unknown id collapse onto a single attach attempt via `attachInFlight`.
+     */
+    /**
+     * The same trust gate `initialize()` enforces, applied to every path that
+     * can hand out a workspace (attach / attach-on-demand). Without it, a
+     * below-threshold descriptor that could never CREATE a session could still
+     * run commands in one persisted by a higher-trust composition.
+     */
+    requireTrust() {
+        if (!trustAllowsCodeSession(this.descriptor.trustLevel)) {
+            throw new CapabilityError('The code-session trust level cannot edit a writable workspace.', 'PERMISSION_DENIED', {
+                reason: 'code-session-trust-denied',
+                retryable: false,
+                details: { trustLevel: this.descriptor.trustLevel, requiredTrustLevel: CODE_SESSION_MIN_TRUST_LEVEL }
+            });
+        }
+    }
+    async ensureSession(sessionId) {
+        this.requireTrust();
+        requireSafeSessionId(sessionId);
+        const known = this.sessions.get(sessionId);
+        if (known)
+            return this.requireReadySession(known);
+        let pending = this.attachInFlight.get(sessionId);
+        if (!pending) {
+            pending = this.loadPersistedSessionMeta(sessionId).finally(() => {
+                this.attachInFlight.delete(sessionId);
+            });
+            this.attachInFlight.set(sessionId, pending);
+        }
+        const meta = await pending;
+        if (!meta) {
+            throw new CapabilityError('The requested code session was not found.', 'NOT_FOUND', {
+                reason: 'code-session-workspace-not-found',
+                retryable: false,
+                details: { sessionId }
+            });
+        }
+        return this.requireReadySession(meta);
+    }
+    async requireReadySession(meta) {
+        if (meta.hostTarget.kind === 'host' && meta.hostTarget.hostId !== 'local') {
+            const fs = await this.workspaceFilesystem(meta.hostTarget);
+            const root = await this.targetSessionRoot(fs, meta.hostTarget);
+            if (meta.workspaceOwnership === 'owned' && meta.workspacePath !== ownedWorkspacePath(fs, root, meta.sessionId)) {
+                throw new CapabilityError('Remote session belongs to a different profile.', 'CONFLICT', {
+                    reason: 'code-session-profile-conflict', retryable: false, details: { sessionId: meta.sessionId }
+                });
+            }
+            if (meta.workspaceOwnership === 'owned') {
+                const contents = await fs.readFile(this.metadataPath(fs, meta.workspacePath), 'utf8');
+                const persisted = parseCodeSessionMetadata(utf8Text(contents));
+                if (!persisted || persisted.sessionId !== meta.sessionId || persisted.workspacePath !== meta.workspacePath ||
+                    persisted.operationId !== meta.operationId || persisted.operationFingerprint !== meta.operationFingerprint ||
+                    persisted.hostTarget.kind !== 'host' || persisted.hostTarget.hostId !== meta.hostTarget.hostId) {
+                    throw new CapabilityError('Remote session metadata changed; explicit recovery is required.', 'CONFLICT', {
+                        reason: 'code-session-profile-conflict', retryable: false, details: { sessionId: meta.sessionId }
+                    });
+                }
+            }
+        }
+        if (!meta.operationId)
+            return meta;
+        const fs = await this.filesystem();
+        const key = await codeSessionOperationKey(meta.operationId);
+        const record = await this.readOperationRecord(fs, key);
+        if (!record ||
+            record.stage !== 'ready' ||
+            record.sessionId !== meta.sessionId ||
+            record.fingerprint !== meta.operationFingerprint) {
+            throw new CapabilityError('The code-session operation is not ready.', 'CONFLICT', {
+                reason: 'code-session-operation-conflict', retryable: false, details: { sessionId: meta.sessionId }
+            });
+        }
+        return meta;
+    }
+    metadataPath(fs, workspacePath) {
+        return fs.join(workspacePath, CODE_SESSION_METADATA_FILENAME);
+    }
+    borrowedMetadataPath(fs, sessionId) {
+        return fs.join(this.sessionRoot(fs), '.metadata', `${requireSafeSessionId(sessionId)}.json`);
+    }
+    operationRoot(fs) {
+        return fs.join(this.sessionRoot(fs), '.operations');
+    }
+    operationDirectory(fs, key) {
+        return fs.join(this.operationRoot(fs), key);
+    }
+    operationRecordPath(fs, key) {
+        return fs.join(this.operationDirectory(fs, key), 'operation.json');
+    }
+    operationLeaseDirectory(fs, key) {
+        return fs.join(this.operationDirectory(fs, key), 'lease');
+    }
+    async readOperationLease(fs, key) {
+        const value = await this.readControlMetadata(fs, fs.join(this.operationLeaseDirectory(fs, key), 'lease.json'));
+        if (!value)
+            return null;
+        try {
+            return CodeSessionOperationLeaseSchema.parse(JSON.parse(utf8Text(value)));
+        }
+        catch (caught) {
+            throw metadataInvalid(valueFreeFailure(CaughtFailureSchema.parse(caught)));
+        }
+    }
+    async withOperationLease(operation, run, exclusive = false) {
+        const leaseDirectory = this.operationLeaseDirectory(operation.fs, operation.key);
+        const leasePath = operation.fs.join(leaseDirectory, 'lease.json');
+        const holderId = crypto.randomUUID();
+        const leaseDurationMs = 15_000;
+        // Another process holds the lease; its only signal is the lease directory
+        // going away, so this polls on the runtime's lifecycle (operation-lease.ts).
+        const acquired = await pollUntil(this.runtime.lifecycle, async () => {
+            try {
+                await operation.fs.mkdir(leaseDirectory);
+                return 'acquired';
+            }
+            catch (caught) {
+                const parsed = CaughtFailureSchema.parse(caught);
+                const failure = valueFreeFailure(parsed);
+                if (failure.code !== 'EEXIST')
+                    throw CapabilityError.from(parsed);
+                const latest = await this.readOperationRecord(operation.fs, operation.key);
+                if (!exclusive && (latest?.stage === 'ready' ||
+                    latest?.stage === 'attention-required' ||
+                    latest?.stage === 'torn-down')) {
+                    return latest;
+                }
+                const lease = await this.readOperationLease(operation.fs, operation.key);
+                if (lease && lease.expiresAt <= Date.now()) {
+                    throw new CapabilityError('The code-session operation lease expired before reconciliation.', 'CONFLICT', {
+                        reason: 'code-session-operation-conflict',
+                        retryable: false,
+                        details: { operationId: operation.record.operationId }
+                    });
+                }
+                return null;
+            }
+        }, { intervalMs: 50, timeoutMs: 10 * 60_000, reason: 'code-session-operation-lease' });
+        if (acquired !== 'acquired') {
+            operation.record = acquired;
+            return run();
+        }
+        const renew = async () => {
+            await operation.fs.writeFile(leasePath, JSON.stringify({ holderId, expiresAt: Date.now() + leaseDurationMs }), 'utf8');
+        };
+        await renew();
+        try {
+            return await withLeaseHeartbeat(this.runtime.lifecycle, { periodMs: leaseDurationMs / 3, operationId: operation.record.operationId, renew, logger: this.log }, async () => {
+                const latest = await this.readOperationRecord(operation.fs, operation.key);
+                if (latest)
+                    operation.record = latest;
+                return run();
+            });
+        }
+        finally {
+            const current = await this.readOperationLease(operation.fs, operation.key);
+            if (current?.holderId === holderId) {
+                await operation.fs.remove(leaseDirectory, { recursive: true });
+            }
+        }
+    }
+    async readOperationRecord(fs, key) {
+        const value = await this.readControlMetadata(fs, this.operationRecordPath(fs, key));
+        if (value === null)
+            return null;
+        try {
+            return PersistedCodeSessionOperationSchema.parse(JSON.parse(utf8Text(value)));
+        }
+        catch (caught) {
+            const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+            this.log.warn('operation record is malformed', { failure });
+            throw metadataInvalid(failure);
+        }
+    }
+    async writeOperationRecord(operation, patch) {
+        const updated = { ...operation.record, ...patch, updatedAt: this.nowIso() };
+        const fs = operation.fs;
+        const path = this.operationRecordPath(fs, operation.key);
+        const temporary = fs.join(fs.dirname(path), `.operation-${crypto.randomUUID()}.json`);
+        if (!await createFileExclusiveChecked(fs, temporary, JSON.stringify(updated, null, 2), 'utf8', {
+            message: 'Operation publication requires exclusive file creation'
+        })) {
+            throw new CapabilityError('Operation publication path is already occupied', 'CONFLICT', { retryable: false });
+        }
+        // Same-directory rename publishes complete bytes; failure preserves the old record and temporary evidence.
+        await fs.rename(temporary, path);
+        operation.record = updated;
+    }
+    async prepareOperation(input) {
+        const operationId = input.operationId?.trim();
+        if (!operationId)
+            return null;
+        if (input.sessionId) {
+            throw requestInvalid('sessionId');
+        }
+        const [key, fingerprint, fs] = await Promise.all([
+            codeSessionOperationKey(operationId),
+            codeSessionOperationFingerprint(input, { authorityId: this.descriptor.id }),
+            this.filesystem()
+        ]);
+        const operationDirectory = this.operationDirectory(fs, key);
+        await fs.mkdir(operationDirectory, { recursive: true });
+        let record = await this.readOperationRecord(fs, key);
+        if (record) {
+            if (record.operationId !== operationId || record.fingerprint !== fingerprint) {
+                throw new CapabilityError('The code-session operation was claimed with a different configuration.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId }
+                });
+            }
+            return { key, record, fs };
+        }
+        const claimDirectory = fs.join(operationDirectory, 'claim');
+        let ownsClaim = false;
+        try {
+            await fs.mkdir(claimDirectory);
+            ownsClaim = true;
+        }
+        catch (caught) {
+            const parsed = CaughtFailureSchema.parse(caught);
+            const failure = valueFreeFailure(parsed);
+            if (failure.code !== 'EEXIST')
+                throw CapabilityError.from(parsed);
+        }
+        if (!ownsClaim) {
+            // The claimant is another process; its only signal is the record file.
+            const claimed = await pollUntil(this.runtime.lifecycle, () => this.readOperationRecord(fs, key), {
+                intervalMs: 25,
+                timeoutMs: 10_000,
+                reason: 'code-session-operation-claim-record'
+            });
+            if (claimed.operationId !== operationId || claimed.fingerprint !== fingerprint) {
+                throw new CapabilityError('The code-session operation was claimed with a different configuration.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId }
+                });
+            }
+            return { key, record: claimed, fs };
+        }
+        // Re-read after taking the exclusive claim: a completed claimant may have
+        // released immediately before our mkdir won.
+        record = await this.readOperationRecord(fs, key);
+        if (record) {
+            await fs.remove(claimDirectory, { recursive: true });
+            if (record.operationId !== operationId || record.fingerprint !== fingerprint) {
+                throw new CapabilityError('The code-session operation was claimed with a different configuration.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId }
+                });
+            }
+            return { key, record, fs };
+        }
+        const now = this.nowIso();
+        record = {
+            operationId,
+            fingerprint,
+            sessionId: `op-${key.slice(0, 32)}`,
+            stage: 'reserved',
+            generation: 1,
+            createdAt: now,
+            updatedAt: now
+        };
+        const fingerprintMarker = fs.join(operationDirectory, 'fingerprints', fingerprint.slice('sha256:'.length));
+        await fs.mkdir(fingerprintMarker, { recursive: true });
+        await this.writeOperationRecord({ fs, key, record }, {});
+        const durable = await this.readOperationRecord(fs, key);
+        if (!durable || durable.fingerprint !== fingerprint) {
+            throw new CapabilityError('The code-session operation claim was not durably recorded.', 'CONFLICT', {
+                reason: 'code-session-operation-conflict', retryable: false, details: { operationId }
+            });
+        }
+        await fs.remove(claimDirectory, { recursive: true });
+        return { key, record, fs };
+    }
+    async persistSessionMetadata(meta, ownedStoragePath) {
+        // Borrowed bookkeeping lives on the LOCAL control root (never inside the
+        // user's repo); an OWNED workspace carries its own metadata file, which for a
+        // remote host lives on the REMOTE workspace filesystem.
+        const fs = meta.workspaceOwnership === 'borrowed'
+            ? await this.filesystem()
+            : await this.workspaceFilesystem(meta.hostTarget);
+        const metadataPath = meta.workspaceOwnership === 'borrowed'
+            ? this.borrowedMetadataPath(fs, meta.sessionId)
+            : this.metadataPath(fs, ownedStoragePath ?? meta.workspacePath);
+        if (meta.workspaceOwnership === 'borrowed') {
+            await fs.mkdir(fs.dirname(metadataPath), { recursive: true });
+        }
+        await fs.writeFile(metadataPath, serializeCodeSessionMetadata({
+            sessionId: meta.sessionId,
+            operationId: meta.operationId,
+            operationFingerprint: meta.operationFingerprint,
+            workspacePath: meta.workspacePath,
+            workspaceOwnership: meta.workspaceOwnership,
+            createdAt: meta.createdAt,
+            hostTarget: meta.hostTarget,
+            repositoryId: meta.repositoryId,
+            cloneUrl: meta.cloneUrl,
+            ephemeral: meta.ephemeral,
+            checkoutRef: meta.checkoutRef,
+            exposedPorts: meta.exposedPorts,
+            previewUrl: meta.previewUrl,
+            pausedAt: meta.pausedAt
+        }), 'utf8');
+    }
+    /** Local discovery contains identity only; the remote workspace owns full metadata. */
+    async persistRemotePointer(meta) {
+        const fs = await this.filesystem();
+        const path = this.borrowedMetadataPath(fs, meta.sessionId);
+        await fs.mkdir(fs.dirname(path), { recursive: true });
+        await fs.writeFile(path, JSON.stringify({
+            sessionId: meta.sessionId, operationId: meta.operationId,
+            operationFingerprint: meta.operationFingerprint, hostTarget: meta.hostTarget,
+            workspacePath: meta.workspacePath, workspaceOwnership: 'owned'
+        }), 'utf8');
+    }
+    cleanupPath(fs, root, key, cleanup) {
+        const parent = fs.join(root, '.cleanup', key);
+        const relative = fs.relative(parent, cleanup.path);
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/workspace$/.test(relative) ||
+            !['intent', 'quarantined', 'removed'].includes(cleanup.phase) || fs.normalize(cleanup.path) !== fs.join(parent, relative)) {
+            throw new CapabilityError('Remote cleanup authorization does not match the current profile', 'CONFLICT', { retryable: false });
+        }
+        return cleanup.path;
+    }
+    async readControlMetadata(fs, path) {
+        try {
+            return await fs.readFile(path, 'utf8');
+        }
+        catch (caught) {
+            const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+            if (failure.code === 'ENOENT')
+                return null;
+            throw new CapabilityError('Code-session control metadata could not be read.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable', retryable: false, cause: failure
+            });
+        }
+    }
+    async loadPersistedSessionMeta(sessionId, forCleanup = false, allowLegacy = true) {
+        const fs = await this.filesystem();
+        requireSafeSessionId(sessionId);
+        const persistedOwnedWorkspacePath = ownedWorkspacePath(fs, this.sessionRoot(fs), sessionId);
+        const borrowedPath = this.borrowedMetadataPath(fs, sessionId);
+        const ownedPath = this.metadataPath(fs, persistedOwnedWorkspacePath);
+        const contents = (await this.readControlMetadata(fs, borrowedPath)) ??
+            (await this.readControlMetadata(fs, ownedPath));
+        const text = contents === null ? null : utf8Text(contents);
+        let parsed = parseCodeSessionMetadata(text);
+        if (!parsed) {
+            if (text !== null)
+                throw metadataInvalid();
+            return allowLegacy ? this.reattachLegacyLocalSession(fs, sessionId) : null;
+        }
+        if (parsed.sessionId !== sessionId) {
+            throw new CapabilityError('Persisted session identity does not match the requested session.', 'CONFLICT', {
+                reason: 'code-session-profile-conflict', retryable: false, details: { sessionId }
+            });
+        }
+        const workspaceOwnership = parsed.workspaceOwnership ?? 'owned';
+        let cleanupPending = false;
+        let cleanupRecord = null;
+        if (forCleanup && parsed.operationId) {
+            const record = await this.readOperationRecord(fs, await codeSessionOperationKey(parsed.operationId));
+            cleanupRecord = record;
+            cleanupPending = !!record && (record.stage === 'cleanup-pending' || record.stage === 'torn-down') &&
+                record.sessionId === sessionId && record.fingerprint === parsed.operationFingerprint;
+        }
+        const targetFs = await this.workspaceFilesystem(parsed.hostTarget);
+        const isRemote = parsed.hostTarget.kind === 'host' && parsed.hostTarget.hostId !== 'local';
+        const workspacePath = workspaceOwnership === 'borrowed' ? parsed.workspacePath
+            : ownedWorkspacePath(targetFs, await this.targetSessionRoot(targetFs, parsed.hostTarget), sessionId);
+        if (!workspacePath)
+            return null;
+        if (isRemote && workspaceOwnership === 'owned') {
+            if (!parsed.operationId || !parsed.operationFingerprint || parsed.workspacePath !== workspacePath) {
+                throw new CapabilityError('Remote session roots or identity changed; explicit recovery is required.', 'CONFLICT', {
+                    reason: 'code-session-profile-conflict', retryable: false, details: { sessionId }
+                });
+            }
+            let cleanupAuthorized = false;
+            if (cleanupPending && cleanupRecord?.cleanup) {
+                const root = await this.targetSessionRoot(targetFs, parsed.hostTarget);
+                const path = this.cleanupPath(targetFs, root, await codeSessionOperationKey(parsed.operationId), cleanupRecord.cleanup);
+                if (cleanupRecord.cleanup.phase === 'intent') {
+                    const quarantined = await targetFs.exists(path);
+                    if (quarantined && await targetFs.exists(workspacePath)) {
+                        throw new CapabilityError('Remote cleanup rename is ambiguous; explicit recovery is required.', 'CONFLICT', {
+                            reason: 'code-session-cleanup-conflict', retryable: false, details: { sessionId }
+                        });
+                    }
+                    cleanupAuthorized = quarantined;
+                }
+                else
+                    cleanupAuthorized = true;
+            }
+            if (!cleanupAuthorized && (!cleanupPending || await targetFs.exists(workspacePath))) {
+                const remoteContents = await targetFs.readFile(this.metadataPath(targetFs, workspacePath), 'utf8');
+                const remoteMetadata = parseCodeSessionMetadata(utf8Text(remoteContents));
+                if (!remoteMetadata || remoteMetadata.sessionId !== sessionId ||
+                    remoteMetadata.operationId !== parsed.operationId || remoteMetadata.operationFingerprint !== parsed.operationFingerprint ||
+                    remoteMetadata.workspacePath !== workspacePath || remoteMetadata.workspaceOwnership !== 'owned' ||
+                    remoteMetadata.hostTarget.kind !== 'host' || parsed.hostTarget.kind !== 'host' || remoteMetadata.hostTarget.hostId !== parsed.hostTarget.hostId) {
+                    throw new CapabilityError('Remote session publication does not match its control record.', 'CONFLICT', {
+                        reason: 'code-session-profile-conflict', retryable: false, details: { sessionId }
+                    });
+                }
+                parsed = remoteMetadata;
+            }
+        }
+        if (!cleanupPending && !(await targetFs.exists(workspacePath)))
+            return null;
+        const meta = {
+            sessionId: parsed.sessionId,
+            operationId: parsed.operationId,
+            operationFingerprint: parsed.operationFingerprint,
+            workspacePath,
+            workspaceOwnership,
+            createdAt: parsed.createdAt ?? this.nowIso(),
+            hostTarget: parsed.hostTarget,
+            repositoryId: parsed.repositoryId,
+            cloneUrl: parsed.cloneUrl,
+            ephemeral: parsed.ephemeral,
+            checkoutRef: parsed.checkoutRef,
+            exposedPorts: parsed.exposedPorts ?? [],
+            previewUrl: parsed.previewUrl,
+            pausedAt: parsed.pausedAt
+        };
+        if (isRemote && workspaceOwnership === 'owned' && !cleanupPending)
+            await this.requireReadySession(meta);
+        this.sessions.set(sessionId, meta);
+        this.background.set(sessionId, this.background.get(sessionId) ?? []);
+        return meta;
+    }
+    /**
+     * Reattach exactly one requested pre-profile local session.
+     *
+     * This intentionally never participates in discover(): profile isolation
+     * remains the default and no new profile absorbs the process-global legacy
+     * roster. A successful match is copied into this profile as BORROWED, so
+     * teardown cannot delete legacy workspace bytes that may still be referenced
+     * by an older process.
+     */
+    async reattachLegacyLocalSession(fs, sessionId) {
+        const legacyRoot = fs.normalize(fs.resolve(LEGACY_LOCAL_SESSION_ROOT));
+        if (legacyRoot === this.sessionRoot(fs))
+            return null;
+        const legacyWorkspacePath = ownedWorkspacePath(fs, legacyRoot, sessionId);
+        const legacyBorrowedPath = fs.join(legacyRoot, '.metadata', `${sessionId}.json`);
+        const legacyOwnedPath = this.metadataPath(fs, legacyWorkspacePath);
+        const contents = (await this.readControlMetadata(fs, legacyBorrowedPath)) ??
+            (await this.readControlMetadata(fs, legacyOwnedPath));
+        const text = contents === null ? null : utf8Text(contents);
+        const parsed = parseCodeSessionMetadata(text);
+        if (!parsed) {
+            if (text !== null)
+                throw metadataInvalid();
+            return null;
+        }
+        if (parsed.sessionId !== sessionId) {
+            throw new CapabilityError('Legacy session identity does not match the requested session.', 'CONFLICT', {
+                reason: 'code-session-profile-conflict', retryable: false, details: { sessionId }
+            });
+        }
+        if (parsed.hostTarget.kind !== 'host' || parsed.hostTarget.hostId !== 'local') {
+            return null;
+        }
+        const legacyOwnership = parsed.workspaceOwnership ?? 'owned';
+        const workspacePath = legacyOwnership === 'borrowed' ? parsed.workspacePath : legacyWorkspacePath;
+        if (!workspacePath || !(await fs.exists(workspacePath)))
+            return null;
+        const meta = {
+            sessionId,
+            operationId: parsed.operationId,
+            operationFingerprint: parsed.operationFingerprint,
+            workspacePath,
+            workspaceOwnership: 'borrowed',
+            createdAt: parsed.createdAt ?? this.nowIso(),
+            hostTarget: parsed.hostTarget,
+            repositoryId: parsed.repositoryId,
+            cloneUrl: parsed.cloneUrl,
+            ephemeral: parsed.ephemeral,
+            checkoutRef: parsed.checkoutRef,
+            exposedPorts: parsed.exposedPorts ?? [],
+            previewUrl: parsed.previewUrl,
+            pausedAt: parsed.pausedAt
+        };
+        await this.persistSessionMetadata(meta);
+        this.sessions.set(sessionId, meta);
+        this.background.set(sessionId, this.background.get(sessionId) ?? []);
+        return meta;
+    }
+    /**
+     * Run a one-shot command, capturing output. Used internally for git ops.
+     *
+     * Uses `runtime/execution`'s `spawn()` mode + self-drain rather than
+     * `execute()` on purpose: this method owns a distinct timeout contract
+     * (SIGTERM kill, forced `exitCode:null`, and an explicit
+     * `[code-session] aborted after …` stderr suffix) that `execute()`'s
+     * SIGKILL/137 + no-suffix semantics would change. Keeping spawn()+drain
+     * preserves the exact consumer-observable behavior the characterization
+     * tests pin.
+     */
+    async exec(workspacePath, command, opts = {}, hostTarget = DEFAULT_SESSION_HOST_TARGET) {
+        const started = this.now();
+        if (opts.signal?.aborted) {
+            return {
+                exitCode: null,
+                stdout: '',
+                stderr: '[code-session] stopped before spawn',
+                timedOut: false,
+                durationMs: this.now() - started,
+                aborted: true
+            };
+        }
+        let timedOut = false;
+        const timeoutMs = Math.min(opts.timeoutMs ?? this.descriptor.timeoutMs, this.descriptor.timeoutMs);
+        const [bin, ...args] = command;
+        // One cancellation and one total deadline own the operation from here,
+        // before any host work: before dispatch they stop it; during a remote
+        // setup they cancel its acquisition; afterwards they kill the handle.
+        let handle = null;
+        let acquisition;
+        let aborted = false;
+        const cancel = (signal) => {
+            if (handle)
+                requestKill(signal);
+            else
+                acquisition?.cancel();
+        };
+        const disarmDeadline = this.runtime.lifecycle.timeout(() => {
+            timedOut = true;
+            cancel('SIGKILL');
+        }, timeoutMs);
+        // User abort (composer Stop): same cancellation as the timeout path,
+        // distinct flag so callers can tell "stopped" from "timed out".
+        const onAbort = () => {
+            if (aborted)
+                return;
+            aborted = true;
+            cancel(opts.abortKillSignal ?? 'SIGKILL');
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        let kill;
+        let killSignal;
+        let resolveKillFailure;
+        const killFailure = new Promise((resolve) => { resolveKillFailure = resolve; });
+        const requestKill = (signal) => {
+            if (!handle || killSignal === 'SIGKILL' || killSignal === signal)
+                return;
+            const owned = handle;
+            killSignal = signal;
+            // A hard deadline can escalate an earlier graceful stop without waiting for its acknowledgement.
+            const request = Promise.resolve().then(() => owned.kill(signal)).then(() => undefined, (caught) => {
+                const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+                resolveKillFailure(new CapabilityError('Code-session process cancellation failed; cleanup is unconfirmed.', 'UNAVAILABLE', {
+                    reason: 'code-session-cleanup-unconfirmed', retryable: false, cause: failure
+                }));
+                return failure;
+            });
+            kill = kill ? Promise.all([kill, request]).then(([previous, current]) => previous ?? current) : request;
+        };
+        try {
+            try {
+                handle = await this.spawnOnHost(workspacePath, hostTarget, {
+                    command: bin,
+                    args,
+                    cwd: opts.cwd ?? workspacePath,
+                    stdout: 'pipe',
+                    stderr: 'pipe',
+                    // Timeout and abort kill the command's whole tree, not only its direct process.
+                    killTree: true
+                }, opts.env, {
+                    cancelled: () => timedOut || aborted,
+                    dispatched: (remote) => { acquisition = remote; }
+                });
+            }
+            catch (caught) {
+                // A cancelled acquisition keeps observing its late port; the caller
+                // learns only that cleanup is not yet confirmed.
+                if (acquisition && (timedOut || aborted)) {
+                    throw new CapabilityError('Code-session process setup was cancelled; cleanup is unconfirmed.', 'UNAVAILABLE', {
+                        reason: 'code-session-cleanup-unconfirmed',
+                        retryable: false,
+                        cause: valueFreeFailure(CaughtFailureSchema.parse(caught))
+                    });
+                }
+                throw CapabilityError.from(CaughtFailureSchema.parse(caught));
+            }
+            if (!handle) {
+                // Cancelled before dispatch: no process was requested.
+                const cancelled = {
+                    exitCode: null,
+                    stdout: '',
+                    stderr: timedOut ? `[code-session] aborted after ${timeoutMs}ms` : '[code-session] stopped before spawn',
+                    timedOut,
+                    durationMs: this.now() - started
+                };
+                if (aborted && !timedOut)
+                    cancelled.aborted = true;
+                return cancelled;
+            }
+            // Cancellation during a local spawn (which always settles) kills now.
+            if (timedOut || aborted)
+                requestKill(timedOut ? 'SIGKILL' : (opts.abortKillSignal ?? 'SIGKILL'));
+            const outcome = await Promise.race([
+                Promise.all([readStream(handle.stdout), readStream(handle.stderr), handle.exited]).then((value) => ({ kind: 'complete', value })),
+                killFailure.then((error) => ({ kind: 'kill-failed', error }))
+            ]);
+            if (outcome.kind === 'kill-failed')
+                throw outcome.error;
+            const [stdout, stderr, exit] = outcome.value;
+            if (kill)
+                await kill;
+            const result = {
+                exitCode: timedOut || aborted ? null : exit.code,
+                stdout,
+                stderr: timedOut || aborted
+                    ? `${stderr}\n${timedOut ? `[code-session] aborted after ${timeoutMs}ms` : '[code-session] stopped by user'}`
+                    : stderr,
+                timedOut,
+                durationMs: this.now() - started
+            };
+            if (aborted)
+                result.aborted = true;
+            return result;
+        }
+        finally {
+            disarmDeadline();
+            opts.signal?.removeEventListener('abort', onAbort);
+            if (kill)
+                await kill;
+        }
+    }
+    async initialize(input) {
+        input = parseCodeSessionInitializeInput(input);
+        if (input.sessionId) {
+            if (input.operationId) {
+                throw requestInvalid('operationId');
+            }
+            if (input.workspacePath) {
+                this.requireTrust();
+                const sessionId = requireSafeSessionId(input.sessionId);
+                const hostTarget = input.hostTarget ?? this.descriptor.hostTarget ?? DEFAULT_SESSION_HOST_TARGET;
+                if (hostTarget.kind !== 'host') {
+                    throw requestInvalid('hostTarget');
+                }
+                if (input.cloneUrl || input.repositoryId || input.ephemeral) {
+                    throw requestInvalid('workspacePath');
+                }
+                const fs = await this.workspaceFilesystem(hostTarget);
+                const workspacePath = fs.resolve(input.workspacePath);
+                if (!(await fs.exists(workspacePath)) || (await fs.stat(workspacePath)).kind !== 'directory') {
+                    throw new CapabilityError('The requested workspace does not exist.', 'NOT_FOUND', {
+                        reason: 'code-session-workspace-not-found', retryable: false, details: { sessionId }
+                    });
+                }
+                const meta = {
+                    sessionId,
+                    workspacePath,
+                    workspaceOwnership: 'borrowed',
+                    createdAt: this.nowIso(),
+                    hostTarget,
+                    checkoutRef: input.checkoutRef,
+                    exposedPorts: input.exposedPorts ?? [...this.descriptor.exposedPorts]
+                };
+                await this.persistSessionMetadata(meta);
+                this.sessions.set(sessionId, meta);
+                this.background.set(sessionId, []);
+                await notifyAllocated(input, sessionId, this.log);
+                return this.toHandle(meta);
+            }
+            return this.attach(input.sessionId);
+        }
+        return this.createOrGet({
+            ...input,
+            operationId: input.operationId?.trim() || `initialize:${crypto.randomUUID()}`
+        });
+    }
+    async createOrGet(input) {
+        input = parseCodeSessionCreateOrGetInput(input);
+        this.requireTrust();
+        input = {
+            ...input,
+            hostTarget: input.hostTarget ?? this.descriptor.hostTarget ?? DEFAULT_SESSION_HOST_TARGET,
+            runtimeConfig: { ...this.descriptor.runtimeConfig, ...input.runtimeConfig },
+            exposedPorts: input.exposedPorts ?? [...this.descriptor.exposedPorts]
+        };
+        const operationId = input.operationId;
+        const admittedOperation = CodeSessionOperationIdSchema.safeParse(operationId);
+        if (!admittedOperation.success)
+            throw requestInvalid('operationId');
+        const fingerprint = codeSessionOperationFingerprint(input, { authorityId: this.descriptor.id });
+        // Claim before any await: the key's own refusals (empty, too long) still
+        // surface through codeSessionOperationKey below, on the claimant's path.
+        const claimKey = admittedOperation.data;
+        const running = this.operationInFlight.get(claimKey);
+        if (running) {
+            // A later caller is compared against the first claimant, never the reverse.
+            const [mine, theirs] = await Promise.all([fingerprint, running.fingerprint]);
+            if (mine !== theirs) {
+                throw new CapabilityError('The code-session operation was claimed with a different configuration.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId: claimKey }
+                });
+            }
+            return running.promise;
+        }
+        const pending = Promise.all([codeSessionOperationKey(operationId), fingerprint])
+            .then(() => this.createOrGetOnce(input))
+            .finally(() => {
+            if (this.operationInFlight.get(claimKey)?.promise === pending) {
+                this.operationInFlight.delete(claimKey);
+            }
+        });
+        this.operationInFlight.set(claimKey, { fingerprint, promise: pending });
+        return pending;
+    }
+    async createOrGetOnce(input) {
+        const operation = await this.prepareOperation(input);
+        if (!operation)
+            throw requestInvalid('operationId');
+        return this.withOperationLease(operation, async () => {
+            const { record } = operation;
+            if (record.stage === 'cleanup-pending' || record.stage === 'torn-down') {
+                throw new CapabilityError('The code-session operation was already torn down.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId: record.operationId }
+                });
+            }
+            if (record.stage === 'attention-required') {
+                throw new CapabilityError('The code-session operation requires explicit reconciliation.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId: record.operationId }
+                });
+            }
+            if (record.stage === 'setup-intent' || record.stage === 'setup-running') {
+                await this.writeOperationRecord(operation, {
+                    stage: 'attention-required',
+                    failure: 'setup start was recorded without a durable success receipt; refusing to rerun it'
+                });
+                throw new CapabilityError('The code-session setup may have partially run.', 'CONFLICT', {
+                    reason: 'code-session-operation-conflict', retryable: false, details: { operationId: record.operationId }
+                });
+            }
+            if (record.stage === 'ready') {
+                await notifyAllocated(input, record.sessionId, this.log);
+                return this.attach(record.sessionId);
+            }
+            const sessionId = requireSafeSessionId(record.sessionId);
+            await notifyAllocated(input, sessionId, this.log);
+            const hostTarget = input.hostTarget ?? DEFAULT_SESSION_HOST_TARGET;
+            const fs = await this.workspaceFilesystem(hostTarget);
+            const borrowedWorkspace = input.workspacePath?.trim();
+            if (borrowedWorkspace && hostTarget.kind !== 'host') {
+                throw requestInvalid('hostTarget');
+            }
+            if (borrowedWorkspace && (input.cloneUrl || input.repositoryId || input.ephemeral)) {
+                throw requestInvalid('workspacePath');
+            }
+            const sessionRoot = await this.targetSessionRoot(fs, hostTarget);
+            const workspacePath = borrowedWorkspace
+                ? fs.resolve(borrowedWorkspace)
+                : ownedWorkspacePath(fs, sessionRoot, sessionId);
+            const workspaceOwnership = borrowedWorkspace
+                ? 'borrowed'
+                : 'owned';
+            const stagingPath = borrowedWorkspace
+                ? workspacePath
+                : fs.join(sessionRoot, '.staging', operation.key, `generation-${record.generation}`);
+            const existingReady = await this.loadPersistedSessionMeta(sessionId, false, false);
+            if (existingReady?.operationId === record.operationId &&
+                existingReady.operationFingerprint === record.fingerprint) {
+                await this.writeOperationRecord(operation, { stage: 'ready', failure: undefined });
+                return this.toHandle(existingReady);
+            }
+            await this.writeOperationRecord(operation, { stagingPath });
+            if (workspaceOwnership === 'borrowed') {
+                if (!(await fs.exists(workspacePath))) {
+                    throw new CapabilityError('The requested workspace does not exist.', 'NOT_FOUND', {
+                        reason: 'code-session-workspace-not-found', retryable: false, details: { sessionId }
+                    });
+                }
+                const stat = await fs.stat(workspacePath);
+                if (stat.kind !== 'directory') {
+                    throw requestInvalid('workspacePath');
+                }
+            }
+            else {
+                await fs.mkdir(stagingPath, { recursive: true });
+            }
+            if (record.stage === 'reserved' || record.stage === 'source-preparing') {
+                await this.writeOperationRecord(operation, { stage: 'source-preparing' });
+                const gitDirectory = fs.join(stagingPath, '.git');
+                const hasGit = await fs.exists(gitDirectory);
+                if (input.cloneUrl) {
+                    if (hasGit) {
+                        const remote = await this.exec(stagingPath, ['git', 'remote', 'get-url', 'origin'], { cwd: stagingPath }, hostTarget);
+                        if (remote.exitCode !== 0 || remote.stdout.trim() !== input.cloneUrl) {
+                            await this.writeOperationRecord(operation, {
+                                stage: 'attention-required',
+                                failure: 'the preserved staging repository does not match the requested clone URL'
+                            });
+                            throw new CapabilityError('The preserved staging repository does not match this operation.', 'CONFLICT', {
+                                reason: 'code-session-operation-conflict', retryable: false, details: { operationId: record.operationId }
+                            });
+                        }
+                    }
+                    else {
+                        const entries = await fs.list(stagingPath);
+                        if (entries.length > 0) {
+                            await this.writeOperationRecord(operation, {
+                                stage: 'attention-required',
+                                failure: 'clone was interrupted and left an unverified staging workspace'
+                            });
+                            throw new CapabilityError('An interrupted clone left an unverified staging workspace.', 'CONFLICT', {
+                                reason: 'code-session-operation-conflict', retryable: false, details: { operationId: record.operationId }
+                            });
+                        }
+                        const cloneCred = codeSessionCredentialArgs(input.cloneCredential);
+                        const credEnv = Object.keys(cloneCred.env).length > 0 ? cloneCred.env : undefined;
+                        const cloneArgs = ['git', ...cloneCred.args, 'clone'];
+                        if (input.checkoutRef)
+                            cloneArgs.push('--branch', input.checkoutRef);
+                        cloneArgs.push(input.cloneUrl, stagingPath);
+                        const cloneOptions = { cwd: sessionRoot };
+                        if (credEnv)
+                            cloneOptions.env = credEnv;
+                        const result = await this.exec(sessionRoot, cloneArgs, cloneOptions, hostTarget);
+                        if (result.exitCode !== 0) {
+                            await this.writeOperationRecord(operation, {
+                                stage: 'attention-required',
+                                failure: 'clone command failed'
+                            });
+                            throw new CapabilityError('The code-session clone command failed.', 'UNAVAILABLE', {
+                                reason: 'code-session-host-unavailable', retryable: false, details: { exitCode: result.exitCode }
+                            });
+                        }
+                    }
+                }
+                else if ((input.repositoryId || input.ephemeral) && !hasGit) {
+                    const init = await this.exec(stagingPath, ['git', 'init'], {}, hostTarget);
+                    if (init.exitCode !== 0) {
+                        await this.writeOperationRecord(operation, {
+                            stage: 'attention-required',
+                            failure: 'git initialization command failed'
+                        });
+                        throw new CapabilityError('The code-session git initialization command failed.', 'UNAVAILABLE', {
+                            reason: 'code-session-host-unavailable', retryable: false, details: { exitCode: init.exitCode }
+                        });
+                    }
+                }
+                await this.writeOperationRecord(operation, { stage: 'source-ready', failure: undefined });
+            }
+            const setupScript = input.runtimeConfig?.setupScript?.trim();
+            if (setupScript && operation.record.stage === 'source-ready') {
+                await this.writeOperationRecord(operation, { stage: 'setup-intent' });
+                await this.writeOperationRecord(operation, { stage: 'setup-running' });
+                const result = await this.exec(stagingPath, ['sh', '-lc', setupScript], { cwd: stagingPath, env: input.initialEnv }, hostTarget);
+                if (result.exitCode !== 0) {
+                    await this.writeOperationRecord(operation, {
+                        stage: 'attention-required',
+                        failure: 'setup command failed'
+                    });
+                    throw new CapabilityError('The code-session setup command failed.', 'UNAVAILABLE', {
+                        reason: 'code-session-host-unavailable', retryable: false, details: { exitCode: result.exitCode }
+                    });
+                }
+                await this.writeOperationRecord(operation, { stage: 'setup-succeeded', failure: undefined });
+            }
+            else if (!setupScript && operation.record.stage === 'source-ready') {
+                await this.writeOperationRecord(operation, { stage: 'setup-succeeded', failure: undefined });
+            }
+            const meta = {
+                sessionId,
+                operationId: record.operationId,
+                operationFingerprint: record.fingerprint,
+                workspacePath,
+                workspaceOwnership,
+                createdAt: record.createdAt,
+                hostTarget,
+                repositoryId: input.repositoryId,
+                cloneUrl: input.cloneUrl,
+                checkoutRef: input.checkoutRef,
+                exposedPorts: input.exposedPorts ?? [...this.descriptor.exposedPorts],
+                ephemeral: input.ephemeral
+            };
+            await this.persistSessionMetadata(meta, workspaceOwnership === 'owned' ? stagingPath : undefined);
+            if (workspaceOwnership === 'owned') {
+                if (await fs.exists(workspacePath)) {
+                    await this.writeOperationRecord(operation, {
+                        stage: 'attention-required',
+                        failure: 'the final workspace path already exists and was not proven to belong to this operation'
+                    });
+                    throw new CapabilityError('The final workspace path is already occupied.', 'CONFLICT', {
+                        reason: 'code-session-operation-conflict', retryable: false, details: { operationId: record.operationId }
+                    });
+                }
+                await fs.rename(stagingPath, workspacePath);
+                if (hostTarget.kind === 'host' && hostTarget.hostId !== 'local') {
+                    try {
+                        const published = await fs.readFile(this.metadataPath(fs, workspacePath), 'utf8');
+                        const verified = parseCodeSessionMetadata(utf8Text(published));
+                        if (!verified || verified.sessionId !== sessionId || verified.operationId !== meta.operationId || verified.operationFingerprint !== meta.operationFingerprint || verified.workspacePath !== workspacePath) {
+                            throw new CapabilityError('Remote session publication could not be verified.', 'CONFLICT', {
+                                reason: 'code-session-profile-conflict', retryable: false, details: { sessionId }
+                            });
+                        }
+                        await this.persistRemotePointer(meta);
+                    }
+                    catch (caught) {
+                        await this.writeOperationRecord(operation, { stage: 'attention-required', failure: 'Remote workspace published; local discovery publication failed. Preserve the remote workspace for explicit recovery.' });
+                        throw new CapabilityError('Remote session control publication failed; explicit recovery is required.', 'UNAVAILABLE', {
+                            reason: 'code-session-host-unavailable',
+                            retryable: false,
+                            cause: valueFreeFailure(CaughtFailureSchema.parse(caught))
+                        });
+                    }
+                }
+            }
+            await this.writeOperationRecord(operation, { stage: 'ready', failure: undefined });
+            this.sessions.set(sessionId, meta);
+            this.background.set(sessionId, []);
+            this.log.info?.('code session initialized', {
+                sessionId,
+                operationId: record.operationId,
+                workspacePath,
+                hostKind: hostTarget.kind,
+                repositoryId: input.repositoryId
+            });
+            return this.toHandle(meta);
+        });
+    }
+    async attach(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        this.requireTrust();
+        requireSafeSessionId(sessionId);
+        const meta = this.sessions.get(sessionId) ?? (await this.loadPersistedSessionMeta(sessionId));
+        if (!meta) {
+            throw new CapabilityError('The requested code session was not found.', 'NOT_FOUND', {
+                reason: 'code-session-workspace-not-found', retryable: false, details: { sessionId }
+            });
+        }
+        return this.toHandle(await this.requireReadySession(meta));
+    }
+    async discover() {
+        this.requireTrust();
+        const fs = await this.filesystem();
+        const sessionRoot = this.sessionRoot(fs);
+        if (!(await fs.exists(sessionRoot)))
+            return [];
+        const ids = new Set();
+        for (const entry of await fs.list(sessionRoot)) {
+            if (entry.kind === 'directory' && isSafeSessionId(entry.name))
+                ids.add(entry.name);
+        }
+        const borrowedRoot = fs.join(sessionRoot, '.metadata');
+        if (await fs.exists(borrowedRoot)) {
+            for (const entry of await fs.list(borrowedRoot)) {
+                if (entry.kind === 'file' && entry.name.endsWith('.json')) {
+                    const sessionId = entry.name.slice(0, -'.json'.length);
+                    if (isSafeSessionId(sessionId))
+                        ids.add(sessionId);
+                }
+            }
+        }
+        const handles = await Promise.all([...ids].map(async (sessionId) => {
+            const meta = await this.loadPersistedSessionMeta(sessionId, false, false);
+            return meta ? this.toHandle(meta) : null;
+        }));
+        return handles
+            .filter((handle) => handle !== null)
+            .sort((a, b) => (a.createdAt ?? '').localeCompare(b.createdAt ?? ''));
+    }
+    async runCommand(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseRunCommandInput(input);
+        const meta = await this.ensureSession(sessionId);
+        if (meta.pausedAt)
+            throw sessionPaused(sessionId);
+        const fs = await this.workspaceFilesystem(meta.hostTarget);
+        const cwd = input.cwd
+            ? resolveInWorkspace(fs, meta.workspacePath, input.cwd)
+            : meta.workspacePath;
+        if (input.signal?.aborted) {
+            return {
+                exitCode: null,
+                stdout: '',
+                stderr: '[code-session] stopped before spawn',
+                timedOut: false,
+                durationMs: 0,
+                aborted: true
+            };
+        }
+        if (input.background) {
+            // Background mode needs a LONG-LIVED handle, so it uses spawn() (not
+            // execute()): the ProcessHandle stays live in `this.background`,
+            // `running` is tracked off `proc.exited`, and teardown() calls
+            // `proc.kill()`. This is the path that proves the spawn() mode must
+            // exist — execute()+session() alone has nowhere to land it.
+            const procId = crypto.randomUUID();
+            const [bin, ...args] = input.command;
+            const proc = await this.spawnBackground(meta.workspacePath, meta.hostTarget, {
+                command: bin,
+                args,
+                cwd,
+                stdout: 'pipe',
+                stderr: 'pipe',
+                // Stop and teardown take the background command's whole tree.
+                killTree: true
+            }, input.env);
+            const entry = {
+                procId,
+                proc,
+                running: true,
+                command: input.command,
+                startedAt: this.nowIso(),
+                output: [],
+                produced: 0,
+                drains: []
+            };
+            if (input.cwd)
+                entry.cwd = input.cwd;
+            // Piped output is always read: an undrained pipe blocks a chatty process once its buffer fills.
+            this.drainBackground(sessionId, entry, 'stdout', proc.stdout);
+            this.drainBackground(sessionId, entry, 'stderr', proc.stderr);
+            void proc.exited.then(({ code }) => {
+                entry.running = false;
+                entry.exitCode = code;
+            }, (caught) => {
+                const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+                entry.running = null;
+                this.log.warn('background process exit could not be observed', { sessionId, procId, failure });
+                return failure;
+            });
+            this.background.get(sessionId)?.push(entry);
+            this.log.info?.('background process spawned', { sessionId, procId, pid: proc.pid });
+            return {
+                exitCode: null,
+                stdout: '',
+                stderr: '',
+                timedOut: false,
+                durationMs: 0,
+                procId,
+                running: true
+            };
+        }
+        return this.exec(meta.workspacePath, input.command, { cwd, env: input.env, timeoutMs: input.timeoutMs, signal: input.signal }, meta.hostTarget);
+    }
+    async listBackgroundProcesses(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        await this.ensureSession(sessionId);
+        return (this.background.get(sessionId) ?? []).map((entry) => {
+            const info = {
+                procId: entry.procId,
+                command: entry.command,
+                running: entry.running,
+                startedAt: entry.startedAt,
+                pid: entry.proc.pid
+            };
+            if (entry.cwd)
+                info.cwd = entry.cwd;
+            if (entry.running === false)
+                info.exitCode = entry.exitCode ?? null;
+            return info;
+        });
+    }
+    /**
+     * Keep one background stream's chunks in the entry's ring until the stream
+     * ends. Disposal joins owned work before plugins tear sessions down, so the
+     * read stops when disposal begins instead of holding it for a live process.
+     */
+    drainBackground(sessionId, entry, stream, source) {
+        if (source === null)
+            return;
+        const reader = source.getReader();
+        const lifecycle = this.runtime.lifecycle;
+        const drained = settle(() => lifecycle.own(async () => {
+            const stop = () => void settle(() => reader.cancel());
+            lifecycle.signal.addEventListener('abort', stop, { once: true });
+            try {
+                for (;;) {
+                    const next = await reader.read();
+                    if (next.done)
+                        return;
+                    entry.produced += 1;
+                    entry.output.push({ stream, bytes: next.value });
+                    if (entry.output.length > MAX_BACKGROUND_CHUNKS)
+                        entry.output.shift();
+                }
+            }
+            finally {
+                lifecycle.signal.removeEventListener('abort', stop);
+            }
+        })).then((read) => {
+            if (read.ok)
+                return;
+            this.log.warn('background process output stopped being read', {
+                sessionId,
+                procId: entry.procId,
+                failure: valueFreeFailure(read.cause)
+            });
+        });
+        entry.drains.push(drained);
+    }
+    async backgroundEntry(sessionId, procId) {
+        await this.ensureSession(sessionId);
+        const entry = (this.background.get(sessionId) ?? []).find((candidate) => candidate.procId === procId);
+        if (!entry) {
+            throw new CapabilityError('The background process is not known in this session.', 'NOT_FOUND', {
+                reason: 'code-session-process-not-found', retryable: false, details: { procId }
+            });
+        }
+        return entry;
+    }
+    async readBackgroundProcess(sessionId, procId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        procId = parseProcessId(procId);
+        const { since } = parseBackgroundProcessReadInput(input ?? {});
+        return backgroundOutputSince(await this.backgroundEntry(sessionId, procId), since, false);
+    }
+    async waitBackgroundProcess(sessionId, procId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        procId = parseProcessId(procId);
+        const { since, timeoutMs } = parseBackgroundProcessWaitInput(input);
+        const entry = await this.backgroundEntry(sessionId, procId);
+        const waited = await settle(() => this.runtime.lifecycle.wait(async () => entry.proc.exited, {
+            timeoutMs,
+            reason: 'code-session background wait'
+        }));
+        if (!waited.ok && !isBackgroundWaitTimeout(waited.cause))
+            throw waited.cause;
+        if (waited.ok) {
+            entry.running = false;
+            entry.exitCode = waited.value.code;
+            // An ended process's last output is still in its pipes: answer once both are read. A
+            // descendant can hold a pipe open past the exit, so the join is bounded.
+            const joined = await settle(() => this.runtime.lifecycle.wait(async () => {
+                await Promise.all(entry.drains);
+            }, { timeoutMs: BACKGROUND_DRAIN_JOIN_MS, reason: 'code-session background output' }));
+            if (!joined.ok && !isBackgroundWaitTimeout(joined.cause))
+                throw joined.cause;
+        }
+        return backgroundOutputSince(entry, since, !waited.ok);
+    }
+    async stopBackgroundProcess(sessionId, procId, signal) {
+        sessionId = parseCodeSessionId(sessionId);
+        procId = parseProcessId(procId);
+        signal = parseProcessSignal(signal);
+        await this.ensureSession(sessionId);
+        const entry = (this.background.get(sessionId) ?? []).find((candidate) => candidate.procId === procId);
+        if (!entry)
+            return false;
+        if (entry.running === false)
+            return true;
+        if (entry.running === null) {
+            throw new CapabilityError('Background process liveness is unknown.', 'UNAVAILABLE', {
+                reason: 'code-session-cleanup-unconfirmed', retryable: false, details: { procId }
+            });
+        }
+        try {
+            await entry.proc.kill(signal ?? 'SIGTERM');
+        }
+        catch (caught) {
+            entry.running = null;
+            throw new CapabilityError('Background process signal submission failed.', 'UNAVAILABLE', {
+                reason: 'code-session-cleanup-unconfirmed',
+                retryable: false,
+                details: { procId },
+                cause: valueFreeFailure(CaughtFailureSchema.parse(caught))
+            });
+        }
+        return true;
+    }
+    async pause(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const meta = await this.ensureSession(sessionId);
+        if (meta.pausedAt)
+            return this.toHandle(meta);
+        for (const entry of this.background.get(sessionId) ?? []) {
+            if (entry.running !== false)
+                await this.stopBackgroundProcess(sessionId, entry.procId);
+        }
+        meta.pausedAt = this.nowIso();
+        await this.persistSessionMetadata(meta);
+        return this.toHandle(meta);
+    }
+    async resume(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const meta = await this.ensureSession(sessionId);
+        if (!meta.pausedAt)
+            return this.toHandle(meta);
+        meta.pausedAt = undefined;
+        await this.persistSessionMetadata(meta);
+        return this.attach(sessionId);
+    }
+    async readFile(sessionId, path) {
+        sessionId = parseCodeSessionId(sessionId);
+        path = parseCodeSessionPath(path);
+        const meta = await this.ensureSession(sessionId);
+        const fs = await this.workspaceFilesystem(meta.hostTarget);
+        const abs = resolveInWorkspace(fs, meta.workspacePath, path);
+        const contents = await fs.readFile(abs, 'utf8');
+        return utf8Text(contents);
+    }
+    async writeFile(sessionId, path, content) {
+        sessionId = parseCodeSessionId(sessionId);
+        ({ path, content } = parseWriteFileInput(path, content));
+        const meta = await this.ensureSession(sessionId);
+        const fs = await this.workspaceFilesystem(meta.hostTarget);
+        const abs = resolveInWorkspace(fs, meta.workspacePath, path);
+        await fs.mkdir(fs.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, content, 'utf8');
+    }
+    async patchFile(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parsePatchFileInput(input);
+        const meta = await this.ensureSession(sessionId);
+        const fs = await this.workspaceFilesystem(meta.hostTarget);
+        // Validate the target stays in-workspace before applying.
+        resolveInWorkspace(fs, meta.workspacePath, input.path);
+        // `git apply` is the safe, atomic diff applier; write the diff to a temp
+        // file in the workspace then apply it relative to the workspace root.
+        const patchPath = resolveInWorkspace(fs, meta.workspacePath, `.vibes-patch-${crypto.randomUUID()}.diff`);
+        await fs.writeFile(patchPath, input.diff, 'utf8');
+        try {
+            const result = await this.exec(meta.workspacePath, ['git', 'apply', patchPath], {}, meta.hostTarget);
+            if (result.exitCode !== 0) {
+                throw new CapabilityError('The code-session patch command failed.', 'INVALID_INPUT', {
+                    reason: 'code-session-request-invalid', retryable: false, details: { exitCode: result.exitCode }
+                });
+            }
+        }
+        finally {
+            await fs.remove(patchPath);
+        }
+    }
+    async gitApply(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseGitApplyInput(input);
+        const meta = await this.ensureSession(sessionId);
+        const fs = await this.workspaceFilesystem(meta.hostTarget);
+        // Write diff to a temp file in the workspace (git apply requires a file path).
+        const patchPath = resolveInWorkspace(fs, meta.workspacePath, `.vibes-patch-${crypto.randomUUID()}.diff`);
+        await fs.writeFile(patchPath, input.diff, 'utf8');
+        try {
+            const args = input.check
+                ? ['git', 'apply', '--check', patchPath]
+                : ['git', 'apply', patchPath];
+            const result = await this.exec(meta.workspacePath, args, {}, meta.hostTarget);
+            return {
+                ok: result.exitCode === 0,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode
+            };
+        }
+        finally {
+            await fs.remove(patchPath);
+        }
+    }
+    async gitStatus(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const meta = await this.ensureSession(sessionId);
+        const [porcelain, branch] = await Promise.all([
+            this.exec(meta.workspacePath, ['git', '--no-optional-locks', 'status', '--porcelain'], {}, meta.hostTarget),
+            this.exec(meta.workspacePath, ['git', '--no-optional-locks', 'rev-parse', '--abbrev-ref', 'HEAD'], {}, meta.hostTarget)
+        ]);
+        if (porcelain.exitCode !== 0) {
+            throw new CapabilityError('The code-session git status command failed.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable', retryable: false, details: { exitCode: porcelain.exitCode }
+            });
+        }
+        const staged = [];
+        const unstaged = [];
+        const untracked = [];
+        for (const line of porcelain.stdout.split('\n')) {
+            if (!line.trim())
+                continue;
+            const x = line[0];
+            const y = line[1];
+            const file = line.slice(3);
+            if (x === '?' && y === '?')
+                untracked.push(file);
+            else {
+                if (x && x !== ' ')
+                    staged.push(file);
+                if (y && y !== ' ')
+                    unstaged.push(file);
+            }
+        }
+        return { staged, unstaged, untracked, branch: branch.stdout.trim() || 'HEAD' };
+    }
+    async withGitRepoLock(repoRoot, fn, signal) {
+        const previous = this.gitCommitQueues.get(repoRoot);
+        const run = async () => {
+            if (previous)
+                await settle(() => previous);
+            signal?.throwIfAborted();
+            return fn();
+        };
+        const current = run();
+        const tracked = settle(() => current);
+        this.gitCommitQueues.set(repoRoot, tracked);
+        try {
+            return await current;
+        }
+        finally {
+            if (this.gitCommitQueues.get(repoRoot) === tracked) {
+                this.gitCommitQueues.delete(repoRoot);
+            }
+        }
+    }
+    async resolveGitRootForPaths(meta, paths, signal) {
+        signal?.throwIfAborted();
+        if (!paths || paths.length === 0) {
+            return { gitRoot: meta.workspacePath, relPaths: [] };
+        }
+        const fs = await this.workspaceFilesystem(meta.hostTarget);
+        signal?.throwIfAborted();
+        const rootNorm = fs.normalize(meta.workspacePath);
+        const resolved = await Promise.all(paths.map(async (rawPath) => {
+            const abs = fs.normalize(resolveInWorkspace(fs, rootNorm, rawPath));
+            let current = abs;
+            while (current.startsWith(rootNorm) && current.length >= rootNorm.length) {
+                signal?.throwIfAborted();
+                const isRepo = await fs.exists(fs.join(current, '.git'));
+                signal?.throwIfAborted();
+                if (isRepo) {
+                    return { abs, gitRoot: current };
+                }
+                const parent = fs.normalize(fs.dirname(current));
+                if (parent === current)
+                    break;
+                current = parent;
+            }
+            return { abs, gitRoot: rootNorm };
+        }));
+        const firstRoot = resolved[0].gitRoot;
+        const commonRoot = resolved.every((entry) => entry.gitRoot === firstRoot) ? firstRoot : rootNorm;
+        const relPaths = resolved.map(({ abs }) => {
+            if (abs === commonRoot)
+                return '.';
+            const prefix = commonRoot.endsWith('/') ? commonRoot : `${commonRoot}/`;
+            return abs.startsWith(prefix) ? abs.slice(prefix.length) : abs;
+        });
+        return { gitRoot: commonRoot, relPaths };
+    }
+    async gitCommit(sessionId, input, options = {}) {
+        const { signal } = parseGitCommitOptions(options);
+        signal?.throwIfAborted();
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseGitCommitInput(input);
+        const meta = await this.ensureSession(sessionId);
+        signal?.throwIfAborted();
+        const { gitRoot, relPaths } = await this.resolveGitRootForPaths(meta, input.paths, signal);
+        const hasExplicitPaths = relPaths.length > 0 && !relPaths.includes('.');
+        return this.withGitRepoLock(gitRoot, async () => {
+            const runStage = async (operation, command) => {
+                signal?.throwIfAborted();
+                const outcome = await settle(() => this.exec(gitRoot, command, { cwd: gitRoot, signal, abortKillSignal: 'SIGTERM' }, meta.hostTarget));
+                if (!outcome.ok || outcome.value.exitCode !== 0) {
+                    throw new CapabilityError('The code-session Git command failed.', 'UNAVAILABLE', {
+                        reason: 'code-session-host-unavailable',
+                        retryable: false,
+                        details: { operation, exitCode: outcome.ok ? outcome.value.exitCode : null }
+                    });
+                }
+                return outcome.value;
+            };
+            let stagedByHelper = false;
+            if (hasExplicitPaths) {
+                await runStage('git-add', ['git', 'add', '-A', '--', ...relPaths]);
+                stagedByHelper = true;
+            }
+            else {
+                const stagedCheck = await runStage('git-staged-inspection', [
+                    'git', '--no-optional-locks', 'diff', '--cached', '--name-only'
+                ]);
+                if (stagedCheck.stdout.trim().length === 0) {
+                    const addArgs = relPaths.length > 0 ? ['git', 'add', '-A', '--', ...relPaths] : ['git', 'add', '-A'];
+                    await runStage('git-add', addArgs);
+                    stagedByHelper = true;
+                }
+            }
+            const commitArgs = ['git', '-c', 'commit.gpgsign=false'];
+            if (input.author) {
+                const authorMatch = /^([^<>]+?)\s*<([^<>]+)>$/.exec(input.author.trim());
+                if (authorMatch) {
+                    commitArgs.push('-c', `user.name=${authorMatch[1].trim()}`, '-c', `user.email=${authorMatch[2].trim()}`);
+                }
+            }
+            commitArgs.push('commit', '-m', input.message);
+            if (input.author)
+                commitArgs.push('--author', input.author);
+            if (hasExplicitPaths) {
+                commitArgs.push('--', ...relPaths);
+            }
+            try {
+                await runStage('git-commit', commitArgs);
+            }
+            catch (failure) {
+                if (stagedByHelper) {
+                    const resetArgs = hasExplicitPaths
+                        ? ['git', 'reset', '-q', 'HEAD', '--', ...relPaths]
+                        : ['git', 'reset', '-q', 'HEAD'];
+                    // Reset is cleanup of this attempt, independent of its cancelled foreground lifetime.
+                    const reset = await settle(() => this.exec(gitRoot, resetArgs, { cwd: gitRoot }, meta.hostTarget));
+                    if (!reset.ok || reset.value.exitCode !== 0) {
+                        throw new CapabilityError('Code-session Git cleanup is unconfirmed.', 'UNAVAILABLE', {
+                            reason: 'code-session-cleanup-unconfirmed', retryable: false,
+                            details: { operation: 'git-reset', exitCode: reset.ok ? reset.value.exitCode : null },
+                            cause: failure
+                        });
+                    }
+                }
+                throw failure;
+            }
+            const hash = await runStage('git-hash-lookup', [
+                'git', '--no-optional-locks', 'rev-parse', 'HEAD'
+            ]);
+            return { hash: hash.stdout.trim(), message: input.message };
+        }, signal);
+    }
+    async gitPush(sessionId, input = {}) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseGitPushInput(input);
+        const meta = await this.ensureSession(sessionId);
+        // Resolve the push credential: explicit > host resolver (by repositoryId) >
+        // none (ambient workspace auth). The token never lands in argv / the URL /
+        // `.git/config` — it is fed via a credential helper from the CHILD env only.
+        let credential = input.credential;
+        if (!credential && this.pushCredentialResolver && meta.repositoryId) {
+            credential = (await this.pushCredentialResolver(meta.repositoryId)) ?? undefined;
+        }
+        const cred = codeSessionCredentialArgs(credential);
+        const args = ['git', ...cred.args, 'push'];
+        if (input.setUpstream)
+            args.push('-u');
+        if (input.remote)
+            args.push(input.remote);
+        if (input.branch)
+            args.push(input.branch);
+        const pushOptions = {};
+        if (Object.keys(cred.env).length > 0)
+            pushOptions.env = cred.env;
+        const result = await this.exec(meta.workspacePath, args, pushOptions, meta.hostTarget);
+        if (result.exitCode !== 0) {
+            throw new CapabilityError('The code-session git push command failed.', 'UNAVAILABLE', {
+                reason: 'code-session-host-unavailable', retryable: false, details: { exitCode: result.exitCode }
+            });
+        }
+    }
+    async exposePort(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseExposePortInput(input);
+        const meta = await this.ensureSession(sessionId);
+        if (!meta.exposedPorts.includes(input.port))
+            meta.exposedPorts.push(input.port);
+        // On a local Host the preview is reachable on localhost. A future remote
+        // Host daemon would publish a tunneled URL here.
+        const previewUrl = `http://localhost:${input.port}`;
+        meta.previewUrl = previewUrl;
+        await this.persistSessionMetadata(meta);
+        return { port: input.port, previewUrl };
+    }
+    async teardown(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        requireSafeSessionId(sessionId);
+        const known = this.sessions.get(sessionId);
+        const meta = known?.workspaceOwnership === 'owned' && known.hostTarget.kind === 'host' && known.hostTarget.hostId !== 'local'
+            ? await this.loadPersistedSessionMeta(sessionId, true)
+            : known ?? await this.loadPersistedSessionMeta(sessionId, true);
+        if (!meta)
+            return;
+        const controlFs = await this.filesystem();
+        const key = meta.operationId ? await codeSessionOperationKey(meta.operationId) : undefined;
+        const record = key ? await this.readOperationRecord(controlFs, key) : null;
+        const operation = key && record ? { key, record, fs: controlFs } : undefined;
+        const cleanup = async () => {
+            const current = operation?.record ?? record;
+            const resumingCleanup = current && (current.stage === 'cleanup-pending' || current.stage === 'torn-down') &&
+                current.sessionId === sessionId && current.fingerprint === meta.operationFingerprint;
+            if (!resumingCleanup)
+                await this.requireReadySession(meta);
+            for (const entry of this.background.get(sessionId) ?? []) {
+                if (entry.running === false)
+                    continue;
+                if (entry.running === null) {
+                    throw new CapabilityError('Background process liveness is unknown.', 'UNAVAILABLE', {
+                        reason: 'code-session-cleanup-unconfirmed', retryable: false, details: { procId: entry.procId }
+                    });
+                }
+                try {
+                    // The process's own exit is the owner event; the wait only bounds it.
+                    await this.runtime.lifecycle.wait(async () => {
+                        await entry.proc.kill('SIGTERM');
+                        await entry.proc.exited;
+                    }, { timeoutMs: 1_000, reason: 'code-session-background-exit' });
+                }
+                catch (caught) {
+                    entry.running = null;
+                    throw new CapabilityError('Background process cleanup is unconfirmed.', 'UNAVAILABLE', {
+                        reason: 'code-session-cleanup-unconfirmed',
+                        retryable: false,
+                        details: { procId: entry.procId },
+                        cause: valueFreeFailure(CaughtFailureSchema.parse(caught))
+                    });
+                }
+            }
+            if (operation)
+                await this.writeOperationRecord(operation, { stage: 'cleanup-pending', failure: undefined });
+            if (meta.workspaceOwnership === 'owned') {
+                const fs = await this.workspaceFilesystem(meta.hostTarget);
+                assertOwnedWorkspacePath(fs, await this.targetSessionRoot(fs, meta.hostTarget), sessionId, meta.workspacePath);
+                if (meta.hostTarget.kind === 'host' && meta.hostTarget.hostId !== 'local') {
+                    if (!operation)
+                        throw new CapabilityError('Remote owned cleanup requires its durable operation', 'CONFLICT', { retryable: false });
+                    const root = await this.targetSessionRoot(fs, meta.hostTarget);
+                    let cleanup = operation.record.cleanup;
+                    if (!cleanup) {
+                        const cleanupRoot = fs.join(root, '.cleanup', operation.key);
+                        await fs.mkdir(cleanupRoot, { recursive: true });
+                        const allocation = fs.join(cleanupRoot, crypto.randomUUID());
+                        // Exclusive parent allocation keeps rename's destination private and absent.
+                        await fs.mkdir(allocation);
+                        cleanup = { path: fs.join(allocation, 'workspace'), phase: 'intent' };
+                        await this.writeOperationRecord(operation, { cleanup });
+                    }
+                    const quarantine = this.cleanupPath(fs, root, operation.key, cleanup);
+                    if (cleanup.phase === 'intent') {
+                        const [originalExists, quarantineExists] = await Promise.all([fs.exists(meta.workspacePath), fs.exists(quarantine)]);
+                        if (originalExists && quarantineExists)
+                            throw new CapabilityError('Remote cleanup rename is ambiguous; explicit recovery is required', 'CONFLICT', { retryable: false });
+                        if (originalExists)
+                            await fs.rename(meta.workspacePath, quarantine);
+                        if (originalExists || quarantineExists) {
+                            const content = await fs.readFile(this.metadataPath(fs, quarantine), 'utf8');
+                            const moved = parseCodeSessionMetadata(utf8Text(content));
+                            if (!moved || moved.sessionId !== sessionId || moved.operationId !== meta.operationId ||
+                                moved.operationFingerprint !== meta.operationFingerprint || moved.workspacePath !== meta.workspacePath ||
+                                moved.workspaceOwnership !== 'owned' || moved.hostTarget.kind !== 'host' || moved.hostTarget.hostId !== meta.hostTarget.hostId) {
+                                throw new CapabilityError('Quarantined workspace identity changed; deletion is not authorized', 'CONFLICT', { retryable: false });
+                            }
+                        }
+                        cleanup = { ...cleanup, phase: quarantineExists || originalExists ? 'quarantined' : 'removed' };
+                        await this.writeOperationRecord(operation, { cleanup });
+                    }
+                    if (cleanup.phase === 'quarantined') {
+                        if (await fs.exists(quarantine))
+                            await fs.remove(quarantine, { recursive: true });
+                        cleanup = { ...cleanup, phase: 'removed' };
+                        await this.writeOperationRecord(operation, { cleanup });
+                    }
+                }
+                else
+                    await fs.remove(meta.workspacePath, { recursive: true });
+            }
+            else {
+                const fs = await this.filesystem();
+                try {
+                    await fs.remove(this.borrowedMetadataPath(fs, sessionId));
+                }
+                catch (caught) {
+                    const parsed = CaughtFailureSchema.parse(caught);
+                    const failure = valueFreeFailure(parsed);
+                    if (failure.code !== 'ENOENT')
+                        throw CapabilityError.from(parsed);
+                }
+            }
+            if (operation)
+                await this.writeOperationRecord(operation, { stage: 'torn-down', failure: undefined });
+            if (meta.workspaceOwnership === 'owned' && meta.hostTarget.kind === 'host' && meta.hostTarget.hostId !== 'local') {
+                const pointer = this.borrowedMetadataPath(controlFs, sessionId);
+                if (await controlFs.exists(pointer))
+                    await controlFs.remove(pointer);
+            }
+            this.background.delete(sessionId);
+            this.sessions.delete(sessionId);
+            this.log.info?.('code session torn down', { sessionId });
+        };
+        return operation ? this.withOperationLease(operation, cleanup, true) : cleanup();
+    }
+    toHandle(meta) {
+        return {
+            sessionId: meta.sessionId,
+            operationId: meta.operationId,
+            workspacePath: meta.workspacePath,
+            workspaceOwnership: meta.workspaceOwnership,
+            createdAt: meta.createdAt,
+            previewUrl: meta.previewUrl,
+            hostTarget: meta.hostTarget,
+            repositoryId: meta.repositoryId,
+            ephemeral: meta.ephemeral
+        };
+    }
+}
+/** A paused session refuses new commands until resumed. */
+function sessionPaused(sessionId) {
+    return new CapabilityError('The code session is paused; resume it to run commands.', 'CONFLICT', {
+        reason: 'code-session-paused',
+        retryable: false,
+        details: { sessionId }
+    });
+}
+class ConsumerCodeSessionImpl extends ConsumerCodeSession {
+    constructor(descriptor, context) {
+        super(AgentCodeSessionDescriptorSchema.parse(descriptor ?? consumerCodeSessionDescriptor), context.runtime);
+    }
+}
+export default createRuntimeImplementation({
+    kind: 'agent/code-session',
+    id: consumerCodeSessionDescriptor.id,
+    constraint: { hardware: ['consumer'] },
+    implementation: ConsumerCodeSessionImpl
+});
+//# sourceMappingURL=agent-code-session.impl.consumer.js.map