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

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

@@ -0,0 +1,1392 @@
+/**
+ * Fleet-host Agent Code Session — relay impl.
+ *
+ * Implements `CodeSessionInterface` against an enrolled machine's fleet daemon,
+ * reached through the HostRelay broker: `connectRelay` → `wireConsumer` → the
+ * daemon root's `runtime/execution` kind (the daemon's `LocalExecution`).
+ *
+ * Operations use the existing invoke/stream relay wire and pass the daemon's
+ * L5 pipeline (authz + friction) — the machine grants remote execution only
+ * when its daemon runs with `--labels sandbox:code-execution`, and the platform
+ * route has already owner-checked + label-checked the host before this impl is
+ * resolved.
+ *
+ * Every dial acts for the invocation's user (`runtime.scope.actor.userId`) and
+ * names that user to the broker on every leg, which authorizes the user against
+ * the host. Dials are cached per host AND user, so one user never rides another
+ * user's authorized connection. An invocation without a user fails with
+ * `AUTH_REQUIRED` before anything is dialed. The reverse leg (callbacks) is deliberately NOT wired: v1 needs no
+ * daemon→consumer invokes, so no reverse SSE channel is ever opened.
+ *
+ * workerd-safe: imports ONLY Node-free subpaths — the interface/descriptor from
+ * `@vibesdotdev/agent-execution/code-session`, the consumer transport from
+ * `@vibesdotdev/kernel-rpc(-relay)`, and the runner-agnostic git core from
+ * `@vibesdotdev/git-operations/core`. Never the Node-only consumer impl.
+ *
+ * Session ids are self-describing: `rly.<hostId>.<random>`. hostIds are
+ * platform-validated kebab-case (`[a-z0-9-]{2,64}` — never a dot), so parsing
+ * the machine back out of a sessionId is unambiguous. That makes `attach`/
+ * `runCommand`/etc. work from a fresh isolate with no session→host lookup —
+ * the same move the cloudflare impl makes by using the sessionId as the
+ * Sandbox DO name.
+ *
+ * Workspace: `<activeHome>/code-sessions/<sessionId>` on the receiving machine,
+ * using that runtime's canonical path roots. POSIX hosts only for
+ * now (commands run via the daemon's `sh`/`git`/`base64`).
+ */
+import { getLogger } from '@vibesdotdev/logging';
+import { AgentCodeSessionDescriptorSchema } from '@vibesdotdev/agent-execution/code-session/descriptor';
+import { PersistedCodeSessionOperationSchema, codeSessionOperationFingerprint, codeSessionOperationKey, codeSessionTempName, parseCodeSessionCreateOrGetInput, parseCodeSessionId, parseCodeSessionInitializeInput, parseCodeSessionPath, parseExposePortInput, parseGitApplyInput, parseGitCommitInput, parseGitCommitOptions, parseGitPushInput, parsePatchFileInput, parseProcessId, parseProcessSignal, parsePushCredentialResolver, parseRunCommandInput, parseWriteFileInput } from '@vibesdotdev/agent-execution/code-session/interface';
+import { CODE_SESSION_METADATA_FILENAME, parseCodeSessionMetadata, serializeCodeSessionMetadata } from '@vibesdotdev/agent-execution/code-session/session-metadata';
+import { ExecuteResultSchema } from '@vibesdotdev/kernel/execution';
+import { acquireWireProcess } from '@vibesdotdev/kernel-rpc/execution';
+import { wireConsumer, asRefId, RPC_ERROR } from '@vibesdotdev/kernel-rpc';
+import { connectRelay } from '@vibesdotdev/kernel-rpc/relay';
+import * as z from 'zod/v4';
+import { gitClone, gitInit, gitStatus, gitCommit, gitPush, gitRaw } from '@vibesdotdev/git-operations/core';
+import { CapabilityError, CaughtFailureSchema, createRuntimeImplementation, isCapabilityError, valueFreeFailure } from '@vibesdotdev/kernel';
+import { getRemotePathRoots } from '@vibesdotdev/paths';
+import { toGitCredential } from "../code-session/git-credential.js";
+import { OperationLeaseSchema } from "../schemas/session-operation.js";
+import { pollUntil, withLeaseHeartbeat } from "../code-session/operation-lease.js";
+import { RELAY_ON_BEHALF_OF_HEADER, resolveRelayBrokerTarget } from "./relay-dial.js";
+/** The relay session's logger on the runtime that owns it (C083a): never an ambient default-bound one. */
+const relayLogger = (runtime) => getLogger('agent.code-session.relay', runtime);
+/** The daemon-exposed execution kind id (see fleet-daemon's daemon-root). */
+const EXECUTION_KIND_ID = 'runtime/execution';
+/** Root of every relay code-session workspace on the machine. */
+const SESSION_DIRECTORY = 'code-sessions';
+/**
+ * Per-invoke wall-clock budget. Must stay UNDER the broker DO's pending-entry
+ * timeout (PENDING_ENTRY_TIMEOUT_MS in platform-web's host-relay.do.ts) or the
+ * broker gives up on the invoke before the daemon answers.
+ */
+const RELAY_UNARY_BUDGET_MS = 290_000;
+const SESSION_ID_PATTERN = /^rly\.([a-z0-9-]{2,64})\.([a-z0-9]+)$/;
+const RelayHostIdSchema = z.string().regex(/^[a-z0-9-]{2,64}$/);
+const RelaySessionIdSchema = z.string().regex(SESSION_ID_PATTERN).transform((sessionId) => ({
+    sessionId,
+    hostId: RelayHostIdSchema.parse(sessionId.split('.').at(1))
+}));
+const RemoteExecutionProxySchema = z.custom((value) => z.object({ execute: z.function() }).safeParse(value).success);
+const RelayRemoteRootSchema = z.custom((value) => z.object({ query: z.function() }).safeParse(value).success);
+const RelayWireFailureSchema = z.object({ code: z.string(), reason: z.string().optional() });
+const REMOTE_ABSENT_EXIT_CODE = 44;
+function requestInvalid(field, failure) {
+    return new CapabilityError('The relay code-session request is invalid.', 'INVALID_INPUT', {
+        reason: 'code-session-relay-request-invalid',
+        retryable: false,
+        details: { field },
+        cause: failure
+    });
+}
+function metadataInvalid(record, failure) {
+    return new CapabilityError('Relay code-session durable state is invalid.', 'INVALID_INPUT', {
+        reason: 'code-session-metadata-invalid',
+        retryable: false,
+        details: { record },
+        cause: failure
+    });
+}
+function hostUnavailable(hostId, failure) {
+    return new CapabilityError('The selected code-session host is unavailable.', 'UNAVAILABLE', {
+        reason: 'code-session-host-unavailable',
+        details: { hostId },
+        cause: failure
+    });
+}
+/** Admit one untrusted execution reply before any relay operation reads it. */
+function parseRemoteExecuteResult(value, hostId) {
+    try {
+        const parsed = ExecuteResultSchema.safeParse(value);
+        if (!parsed.success) {
+            throw hostUnavailable(hostId, valueFreeFailure(CaughtFailureSchema.parse(parsed.error)));
+        }
+        return parsed.data;
+    }
+    catch (caught) {
+        const failure = CaughtFailureSchema.parse(caught);
+        if (isCapabilityError(failure))
+            throw failure;
+        throw hostUnavailable(hostId, valueFreeFailure(failure));
+    }
+}
+function hostOffline(hostId, failure) {
+    return new CapabilityError(`The relay machine '${hostId}' is offline.`, 'UNAVAILABLE', {
+        reason: 'code-session-host-unavailable',
+        details: { hostId },
+        cause: failure
+    });
+}
+function setupFailed(hostId, failure) {
+    return new CapabilityError('Relay code-session setup failed.', 'UNAVAILABLE', {
+        reason: 'code-session-host-unavailable',
+        details: { hostId },
+        cause: failure
+    });
+}
+function operationConflict(operationId, kind = 'state') {
+    let message = 'The code-session operation conflicts with durable state.';
+    if (kind === 'configuration') {
+        message = 'The code-session operation was already claimed with a different configuration.';
+    }
+    else if (kind === 'torn-down') {
+        message = 'The code-session operation was torn down and cannot allocate again.';
+    }
+    else if (kind === 'attention') {
+        message = 'The code-session operation requires attention after setup failed or preparation was interrupted.';
+    }
+    return new CapabilityError(message, 'CONFLICT', {
+        reason: 'code-session-operation-conflict',
+        retryable: false,
+        details: { operationId }
+    });
+}
+function cleanupUnconfirmed(operation, failures) {
+    return new CapabilityError('Code-session cleanup could not be confirmed.', 'UNAVAILABLE', {
+        reason: 'code-session-cleanup-unconfirmed',
+        retryable: true,
+        details: { operation, failureCount: failures.length },
+        cause: failures
+    });
+}
+/** The user this invocation acts for; the broker authorizes that user against the host. */
+function actingUserId(runtime, hostId) {
+    const userId = runtime.scope.actor?.userId;
+    if (userId)
+        return userId;
+    throw new CapabilityError('The relay code-session invocation has no acting user.', 'AUTH_REQUIRED', {
+        reason: 'code-session-relay-user-required',
+        recoveryHint: 'Run the call inside runtime.runInvocation with an actor that names the user.',
+        details: { hostId }
+    });
+}
+/** Cache key for one user's dial to one machine. hostIds never contain a NUL. */
+function dialKey(hostId, userId) {
+    return `${hostId}\u0000${userId}`;
+}
+async function operationOutcome(run) {
+    try {
+        return { ok: true, value: await run() };
+    }
+    catch (caught) {
+        return { ok: false, failure: CaughtFailureSchema.parse(caught) };
+    }
+}
+function newSessionId(hostId) {
+    const admittedHost = parseRelayHostId(hostId);
+    const random = globalThis.crypto.randomUUID().replaceAll('-', '').slice(0, 12);
+    return `rly.${admittedHost}.${random}`;
+}
+function parseRelayHostId(value) {
+    try {
+        const admitted = RelayHostIdSchema.safeParse(value);
+        if (!admitted.success)
+            throw requestInvalid('hostTarget.hostId');
+        return admitted.data;
+    }
+    catch (caught) {
+        const failure = CaughtFailureSchema.parse(caught);
+        if (isCapabilityError(failure))
+            throw failure;
+        throw new CapabilityError('The relay host id could not be read.', 'INVALID_INPUT', {
+            reason: 'code-session-relay-request-invalid',
+            retryable: false,
+            details: { field: 'hostTarget.hostId' },
+            cause: valueFreeFailure(failure)
+        });
+    }
+}
+/** Recover the machine a session lives on from its self-describing id. */
+export function hostIdFromSessionId(sessionId) {
+    try {
+        const admitted = RelaySessionIdSchema.safeParse(sessionId);
+        if (!admitted.success)
+            throw requestInvalid('sessionId');
+        return admitted.data.hostId;
+    }
+    catch (caught) {
+        const failure = CaughtFailureSchema.parse(caught);
+        if (isCapabilityError(failure))
+            throw failure;
+        throw new CapabilityError('The relay session id could not be read.', 'INVALID_INPUT', {
+            reason: 'code-session-relay-request-invalid',
+            retryable: false,
+            details: { field: 'sessionId' },
+            cause: valueFreeFailure(failure)
+        });
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Reject absolute paths and `..` escapes; return the workspace-relative path. */
+function normalizeRelativePath(workspaceDir, path) {
+    const stripped = path.startsWith(`${workspaceDir}/`) ? path.slice(workspaceDir.length + 1) : path;
+    if (stripped.startsWith('/')) {
+        throw new CapabilityError('The requested path escapes the session workspace.', 'INVALID_INPUT', {
+            reason: 'code-session-relay-request-invalid', retryable: false, details: { field: 'path' }
+        });
+    }
+    const parts = [];
+    for (const segment of stripped.split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (parts.length === 0) {
+                throw new CapabilityError('The requested path escapes the session workspace.', 'INVALID_INPUT', {
+                    reason: 'code-session-relay-request-invalid', retryable: false, details: { field: 'path' }
+                });
+            }
+            parts.pop();
+            continue;
+        }
+        parts.push(segment);
+    }
+    if (parts.length === 0) {
+        throw requestInvalid('path');
+    }
+    return parts.join('/');
+}
+function toBase64(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+function isDisconnected(failure) {
+    const wire = RelayWireFailureSchema.safeParse(failure);
+    return wire.success && wire.data.code === RPC_ERROR.DISCONNECTED;
+}
+/**
+ * A `GitCommandRunner` over the machine's remote `runtime/execution` — the
+ * relay-side analog of `ExecutionGitRunner`, reusing the runner-agnostic
+ * `git-operations/core` functions instead of hand-rolling git strings.
+ */
+class RemoteExecutionGitRunner {
+    exec;
+    timeoutMs;
+    constructor(exec, timeoutMs) {
+        this.exec = exec;
+        this.timeoutMs = timeoutMs;
+    }
+    async run(cwd, args, options) {
+        const execOptions = {
+            command: 'git',
+            args,
+            cwd,
+            timeout: Math.min(options?.timeoutMs ?? this.timeoutMs, RELAY_UNARY_BUDGET_MS)
+        };
+        if (options?.env)
+            execOptions.env = options.env;
+        const result = await this.exec(execOptions);
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            timedOut: result.timedOut
+        };
+    }
+}
+/**
+ * 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) {
+    if (!input.onAllocated)
+        return undefined;
+    try {
+        await input.onAllocated(sessionId);
+        return undefined;
+    }
+    catch (caught) {
+        // Declared-optional: carry a value-free outcome so allocation is not stranded.
+        return valueFreeFailure(CaughtFailureSchema.parse(caught));
+    }
+}
+const CallerBearerContextSchema = z.object({ resolve: z.function() });
+/**
+ * The bearer auth's caller-bearer context answers for the active invocation
+ * (the run-bound bearer on a run that carries one); null when the host
+ * declares no such context or nobody is signed in. Never a service credential.
+ */
+async function invocationBearer(runtime) {
+    if (!runtime.hasContext('auth/caller-bearer'))
+        return null;
+    const context = CallerBearerContextSchema.parse(await runtime.context('auth/caller-bearer'));
+    const answered = z.string().min(1).nullish().parse(await context.resolve());
+    return answered ?? null;
+}
+/** 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 }
+    });
+}
+export class RelayCodeSession {
+    descriptor;
+    runtime;
+    dialOptions;
+    pushCredentialResolver;
+    /** sessionId -> repositoryId, recorded at initialize() for the push-credential fallback. */
+    sessionRepositoryIds = new Map();
+    /** (hostId, userId) -> in-flight/settled dial; evicted on close or DISCONNECTED. */
+    hosts = new Map();
+    pinnedRoots = new Map();
+    constructor(descriptor, runtime, dialOptions = {}) {
+        this.descriptor = descriptor;
+        this.runtime = runtime;
+        this.dialOptions = dialOptions;
+    }
+    /** This session's logger, on the runtime that owns it. */
+    get log() {
+        return relayLogger(this.runtime);
+    }
+    setPushCredentialResolver(resolver) {
+        this.pushCredentialResolver = parsePushCredentialResolver(resolver);
+    }
+    // ------------------------------------------------------------------
+    // Remote execution plumbing
+    // ------------------------------------------------------------------
+    async dialHost(hostId, userId) {
+        const target = await resolveRelayBrokerTarget(this.runtime, {
+            ...this.dialOptions,
+            runBearer: this.dialOptions.runBearer ?? (() => invocationBearer(this.runtime))
+        });
+        // Read-only option fields: reassignment (not mutation) keeps the omission
+        // semantics of the previously conditional spreads.
+        let connectOptions = {
+            lifecycle: this.runtime.lifecycle,
+            headers: { [RELAY_ON_BEHALF_OF_HEADER]: userId }
+        };
+        if (target.token)
+            connectOptions = { ...connectOptions, token: target.token };
+        if (target.fetchImpl)
+            connectOptions = { ...connectOptions, fetchImpl: target.fetchImpl };
+        const connection = await connectRelay(target.brokerOrigin, hostId, connectOptions);
+        // No `onRequest`: v1 sends no function refs, so the reverse SSE channel
+        // (daemon→consumer callbacks) is never opened.
+        const { root } = wireConsumer({
+            rootRef: connection.rootRef,
+            send: (req) => connection.send(req),
+            openStream: (ref, channel) => connection.openStream(asRefId(String(ref)), channel),
+            closed: connection.closed
+        });
+        const opened = await operationOutcome(async () => {
+            const remoteRoot = RelayRemoteRootSchema.parse(root);
+            const execution = RemoteExecutionProxySchema.parse(await remoteRoot.query(EXECUTION_KIND_ID));
+            const roots = await getRemotePathRoots(remoteRoot);
+            if (!roots.activeHome.startsWith('/') || !roots.tempDir.startsWith('/'))
+                throw new CapabilityError('Relay code sessions require absolute POSIX host profile and temp roots', 'UNAVAILABLE', { retryable: false });
+            const sessionRoot = `${roots.activeHome.replace(/\/$/, '')}/${SESSION_DIRECTORY}`;
+            const key = dialKey(hostId, userId);
+            const previous = this.pinnedRoots.get(key);
+            if (previous && previous !== sessionRoot) {
+                throw new CapabilityError('Remote profile changed; explicit session recovery is required', 'CONFLICT', { retryable: false });
+            }
+            this.pinnedRoots.set(key, sessionRoot);
+            const tempRoot = roots.tempDir.replace(/\/$/, '');
+            return { connection, execution, sessionRoot, tempRoot };
+        });
+        if (opened.ok)
+            return opened.value;
+        const closed = await operationOutcome(() => connection.close());
+        if (!closed.ok) {
+            throw cleanupUnconfirmed('relay-dial', [
+                valueFreeFailure(opened.failure),
+                valueFreeFailure(closed.failure)
+            ]);
+        }
+        if (isCapabilityError(opened.failure))
+            throw opened.failure;
+        throw hostUnavailable(hostId, valueFreeFailure(opened.failure));
+    }
+    remoteHost(hostId, userId) {
+        const key = dialKey(hostId, userId);
+        let handle = this.hosts.get(key);
+        if (!handle) {
+            handle = this.dialHost(hostId, userId);
+            this.hosts.set(key, handle);
+            const pending = handle;
+            // The original pending promise carries dial failure to callers. This observer
+            // owns only cache eviction and reports closure failures value-free.
+            void pending.then((remote) => remote.connection.closed.then(() => {
+                if (this.hosts.get(key) === pending)
+                    this.hosts.delete(key);
+            }, (caught) => {
+                const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+                this.log.warn('relay connection closed with failure', { hostId, failure });
+                if (this.hosts.get(key) === pending)
+                    this.hosts.delete(key);
+                return failure;
+            }), (caught) => {
+                const failure = valueFreeFailure(CaughtFailureSchema.parse(caught));
+                if (this.hosts.get(key) === pending)
+                    this.hosts.delete(key);
+                return failure;
+            });
+        }
+        return handle;
+    }
+    /**
+     * Run `fn` against the machine's remote execution; on a DISCONNECTED wire
+     * (stale cached socket), evict + redial ONCE before giving up.
+     */
+    async withHost(hostId, fn) {
+        const userId = actingUserId(this.runtime, hostId);
+        const attempt = async () => fn(await this.remoteHost(hostId, userId));
+        const first = await operationOutcome(attempt);
+        if (first.ok)
+            return first.value;
+        if (!isDisconnected(first.failure)) {
+            if (isCapabilityError(first.failure))
+                throw first.failure;
+            throw hostUnavailable(hostId, valueFreeFailure(first.failure));
+        }
+        this.hosts.delete(dialKey(hostId, userId));
+        const retry = await operationOutcome(attempt);
+        if (retry.ok)
+            return retry.value;
+        if (isDisconnected(retry.failure)) {
+            throw hostOffline(hostId, valueFreeFailure(retry.failure));
+        }
+        if (isCapabilityError(retry.failure))
+            throw retry.failure;
+        throw hostUnavailable(hostId, valueFreeFailure(retry.failure));
+    }
+    async prepareEnvironment(hostId, host, cwd, env) {
+        const key = await codeSessionOperationKey(cwd ?? host.sessionRoot);
+        const home = `${host.sessionRoot}/.environments/${key}/home`;
+        const temp = `${host.tempRoot}/${codeSessionTempName(key)}`;
+        const prepared = parseRemoteExecuteResult(await host.execution.execute({
+            command: 'mkdir', args: ['-p', home, temp], declaration: {},
+            timeout: RELAY_UNARY_BUDGET_MS
+        }), hostId);
+        if (prepared.exitCode !== 0)
+            throw new CapabilityError('Remote session environment could not be prepared', 'UNAVAILABLE', { retryable: false });
+        return { HOME: home, TMPDIR: temp, ...env };
+    }
+    async withExecution(hostId, fn) {
+        return this.withHost(hostId, (host) => fn(async ({ env, ...options }) => {
+            const prepared = await this.prepareEnvironment(hostId, host, options.cwd, env);
+            return parseRemoteExecuteResult(await host.execution.execute({
+                ...options, declaration: { env: prepared }
+            }), hostId);
+        }));
+    }
+    async exec(hostId, options) {
+        return this.withExecution(hostId, (exec) => exec({
+            ...options,
+            timeout: Math.min(options.timeout ?? this.descriptor.timeoutMs, RELAY_UNARY_BUDGET_MS)
+        }));
+    }
+    /** Run a compound shell script on the machine (paths pre-validated). */
+    async shell(hostId, script, options = {}) {
+        return this.exec(hostId, { command: 'sh', args: ['-c', script], ...options });
+    }
+    /** A foreground Git stage owns its remote process through exit and output EOF. */
+    async execGit(hostId, options, signal) {
+        signal.throwIfAborted();
+        const { host, env } = await this.withHost(hostId, async (host) => {
+            signal.throwIfAborted();
+            const env = await this.prepareEnvironment(hostId, host, options.cwd, options.env);
+            signal.throwIfAborted();
+            return { host, env };
+        });
+        signal.throwIfAborted();
+        const started = performance.now();
+        const acquisition = acquireWireProcess(this.runtime, () => host.execution.spawn({
+            command: options.command,
+            args: options.args,
+            cwd: options.cwd,
+            stdin: 'ignore', stdout: 'pipe', stderr: 'pipe',
+            timeout: Math.min(options.timeout ?? this.descriptor.timeoutMs, RELAY_UNARY_BUDGET_MS),
+            killTree: true,
+            declaration: { env }
+        }));
+        // Setup stays owned if cancellation precedes the port. The late process is
+        // stopped gracefully, rather than abandoned with Git's lock still owned.
+        const setup = await operationOutcome(() => acquisition.ready);
+        if (!setup.ok) {
+            const cleanup = await acquisition.settled;
+            if (cleanup.outcome === 'cleanup-failed' || cleanup.outcome === 'unconfirmed') {
+                const failures = [valueFreeFailure(setup.failure)];
+                if (cleanup.failure)
+                    failures.push(valueFreeFailure(cleanup.failure));
+                throw cleanupUnconfirmed('foreground-git-setup', failures);
+            }
+            throw setup.failure;
+        }
+        const process = setup.value;
+        let stopping;
+        const stop = () => {
+            stopping ??= operationOutcome(async () => { await process.kill('SIGTERM'); });
+        };
+        signal.addEventListener('abort', stop, { once: true });
+        if (signal.aborted)
+            stop();
+        return this.withRequiredCleanup(hostId, 'foreground-git', async () => {
+            const results = await Promise.allSettled([
+                process.exited,
+                process.stdout ? new Response(process.stdout).text() : '',
+                process.stderr ? new Response(process.stderr).text() : ''
+            ]);
+            const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : []);
+            if (failures.length)
+                throw new AggregateError(failures, 'Remote Git process observation failed.');
+            const [exit, stdout, stderr] = await Promise.all([
+                process.exited,
+                results[1].status === 'fulfilled' ? results[1].value : '',
+                results[2].status === 'fulfilled' ? results[2].value : ''
+            ]);
+            signal.throwIfAborted();
+            return { exitCode: exit.code, stdout, stderr, durationMs: performance.now() - started, timedOut: false };
+        }, async () => {
+            signal.removeEventListener('abort', stop);
+            const stopped = await stopping;
+            if (stopped && !stopped.ok)
+                throw stopped.failure;
+        });
+    }
+    gitRunner(hostId, signal) {
+        return new RemoteExecutionGitRunner((options) => signal ? this.execGit(hostId, options, signal) : this.exec(hostId, options), this.descriptor.timeoutMs);
+    }
+    /** Join required cleanup to the operation without masking either failure. */
+    async withRequiredCleanup(hostId, operation, run, cleanup) {
+        const outcome = await operationOutcome(run);
+        try {
+            await cleanup();
+        }
+        catch (caught) {
+            const failures = [valueFreeFailure(CaughtFailureSchema.parse(caught))];
+            if (!outcome.ok)
+                failures.unshift(valueFreeFailure(outcome.failure));
+            throw cleanupUnconfirmed(operation, failures);
+        }
+        if (!outcome.ok) {
+            if (isCapabilityError(outcome.failure))
+                throw outcome.failure;
+            throw hostUnavailable(hostId, valueFreeFailure(outcome.failure));
+        }
+        return outcome.value;
+    }
+    // ------------------------------------------------------------------
+    // Metadata
+    // ------------------------------------------------------------------
+    async sessionRoot(hostId) {
+        return (await this.remoteHost(hostId, actingUserId(this.runtime, hostId))).sessionRoot;
+    }
+    async sessionDir(sessionId) {
+        return `${await this.sessionRoot(hostIdFromSessionId(sessionId))}/${sessionId}`;
+    }
+    async metadataPath(sessionId) {
+        return `${await this.sessionDir(sessionId)}/${CODE_SESSION_METADATA_FILENAME}`;
+    }
+    async persistSessionMetadata(sessionId, metadata, storageDirectory) {
+        await this.writeRemoteFile(sessionId, `${storageDirectory ?? await this.sessionDir(sessionId)}/${CODE_SESSION_METADATA_FILENAME}`, serializeCodeSessionMetadata(metadata));
+    }
+    async readPersistedSessionMetadata(sessionId) {
+        const hostId = hostIdFromSessionId(sessionId);
+        return parseCodeSessionMetadata(await this.readRemoteText(hostId, await this.metadataPath(sessionId)));
+    }
+    async requireReadySessionMetadata(sessionId) {
+        const metadata = await this.readPersistedSessionMetadata(sessionId);
+        if (!metadata) {
+            throw new CapabilityError('The relay code session is not ready.', 'NOT_FOUND', {
+                reason: 'code-session-workspace-not-found',
+                retryable: false,
+                details: { sessionId }
+            });
+        }
+        if (metadata.sessionId !== sessionId || metadata.hostTarget.kind !== 'host' || metadata.hostTarget.hostId !== hostIdFromSessionId(sessionId)) {
+            throw new CapabilityError('Remote session metadata identity does not match the requested session.', 'CONFLICT', {
+                reason: 'code-session-profile-conflict',
+                retryable: false,
+                details: { sessionId }
+            });
+        }
+        const hostId = hostIdFromSessionId(sessionId);
+        const operationId = metadata.operationId ?? `teardown:${sessionId}`;
+        const key = await codeSessionOperationKey(operationId);
+        if (metadata.operationId) {
+            const operation = await this.readOperationRecord(hostId, key);
+            if (!operation ||
+                operation.stage !== 'ready' ||
+                operation.sessionId !== sessionId ||
+                operation.fingerprint !== metadata.operationFingerprint) {
+                throw operationConflict(operationId);
+            }
+        }
+        else {
+            // Legacy metadata remains unchanged during adoption. Its durable owner
+            // must still prevent ordinary work once teardown has begun.
+            const adopted = await this.readOperationRecord(hostId, key);
+            if (adopted && (adopted.stage !== 'ready' || adopted.sessionId !== sessionId)) {
+                throw operationConflict(operationId);
+            }
+        }
+        return metadata;
+    }
+    async operationDirectory(hostId, key) {
+        return `${await this.sessionRoot(hostId)}/.operations/${key}`;
+    }
+    async operationRecordPath(hostId, key) {
+        return `${await this.operationDirectory(hostId, key)}/operation.json`;
+    }
+    async readRemoteText(hostId, path) {
+        const result = await this.shell(hostId, `if test ! -e ${shellQuote(path)}; then exit ${REMOTE_ABSENT_EXIT_CODE}; fi; cat ${shellQuote(path)}`);
+        if (result.exitCode === 0)
+            return result.stdout;
+        if (result.exitCode === REMOTE_ABSENT_EXIT_CODE)
+            return null;
+        throw hostUnavailable(hostId);
+    }
+    async readOperationRecord(hostId, key) {
+        const value = await this.readRemoteText(hostId, await this.operationRecordPath(hostId, key));
+        if (value === null)
+            return null;
+        let decoded;
+        try {
+            decoded = JSON.parse(value);
+        }
+        catch (caught) {
+            throw metadataInvalid('operation', valueFreeFailure(CaughtFailureSchema.parse(caught)));
+        }
+        const parsed = PersistedCodeSessionOperationSchema.safeParse(decoded);
+        if (!parsed.success) {
+            throw metadataInvalid('operation', valueFreeFailure(CaughtFailureSchema.parse(parsed.error)));
+        }
+        return parsed.data;
+    }
+    async writeOperationRecord(hostId, key, record, patch, leaseHolderPath) {
+        const updated = PersistedCodeSessionOperationSchema.parse({ ...record, ...patch, updatedAt: new Date().toISOString() });
+        const path = await this.operationRecordPath(hostId, key);
+        const temporary = `${leaseHolderPath ? leaseHolderPath + '/record' : path}.${crypto.randomUUID()}.tmp`;
+        if (leaseHolderPath) {
+            const written = await this.shell(hostId, 'printf %s "$VIBES_B64" | base64 -d > "$VIBES_DEST"', { env: { VIBES_B64: toBase64(JSON.stringify(updated, null, 2)), VIBES_DEST: temporary } });
+            if (written.exitCode !== 0)
+                throw operationConflict(record.operationId);
+        }
+        else {
+            await this.writeRemoteFile(updated.sessionId, temporary, JSON.stringify(updated, null, 2));
+        }
+        const published = await this.shell(hostId, `mv ${shellQuote(temporary)} ${shellQuote(path)}`);
+        if (published.exitCode !== 0)
+            throw hostUnavailable(hostId);
+        return updated;
+    }
+    async prepareOperation(input, hostId) {
+        const operationId = input.operationId.trim();
+        if (!operationId)
+            throw requestInvalid('operationId');
+        if (input.sessionId) {
+            throw requestInvalid('sessionId');
+        }
+        const [key, fingerprint] = await Promise.all([
+            codeSessionOperationKey(operationId),
+            codeSessionOperationFingerprint(input, { authorityId: this.descriptor.id })
+        ]);
+        const sessionId = `rly.${hostId}.${key.slice(0, 12)}`;
+        const operationDirectory = await this.operationDirectory(hostId, key);
+        const prepared = await this.shell(hostId, `mkdir -p ${shellQuote(operationDirectory)}`);
+        if (prepared.exitCode !== 0) {
+            throw hostUnavailable(hostId);
+        }
+        const record = await this.readOperationRecord(hostId, key);
+        if (record) {
+            if (record.operationId !== operationId || record.fingerprint !== fingerprint) {
+                throw operationConflict(operationId, 'configuration');
+            }
+            return { key, record };
+        }
+        const now = new Date().toISOString();
+        return this.claimOperationRecord(hostId, key, {
+            operationId, fingerprint, sessionId, stage: 'reserved',
+            generation: 1, createdAt: now, updatedAt: now
+        });
+    }
+    /** Initial publication is serialized for both create-or-get and legacy adoption. */
+    async claimOperationRecord(hostId, key, proposed) {
+        const directory = await this.operationDirectory(hostId, key);
+        const prepared = await this.shell(hostId, `mkdir -p ${shellQuote(directory)}`);
+        if (prepared.exitCode !== 0)
+            throw hostUnavailable(hostId);
+        const operation = { key, record: proposed };
+        return this.withOperationLease(hostId, operation, async (holderPath) => {
+            const existing = await this.readOperationRecord(hostId, key);
+            if (existing) {
+                if (existing.operationId !== proposed.operationId || existing.fingerprint !== proposed.fingerprint ||
+                    existing.sessionId !== proposed.sessionId)
+                    throw operationConflict(proposed.operationId, 'configuration');
+                return { key, record: existing };
+            }
+            const marker = `${directory}/fingerprints/${proposed.fingerprint.slice('sha256:'.length)}`;
+            const marked = await this.shell(hostId, `mkdir -p ${shellQuote(marker)}`);
+            if (marked.exitCode !== 0)
+                throw hostUnavailable(hostId);
+            const record = await this.writeOperationRecord(hostId, key, proposed, {}, holderPath);
+            return { key, record };
+        }, false);
+    }
+    async withOperationLease(hostId, operation, run, replayTerminal = true) {
+        const operationDirectory = await this.operationDirectory(hostId, operation.key);
+        const leaseDirectory = `${operationDirectory}/lease`;
+        const leasePath = `${leaseDirectory}/lease.json`;
+        const holderId = globalThis.crypto.randomUUID();
+        const holderPath = `${leaseDirectory}/${holderId}`;
+        const leaseDurationMs = 15_000;
+        const readLease = (value) => {
+            let decoded;
+            try {
+                decoded = JSON.parse(value);
+            }
+            catch (caught) {
+                throw metadataInvalid('operation-lease', valueFreeFailure(CaughtFailureSchema.parse(caught)));
+            }
+            const lease = OperationLeaseSchema.safeParse(decoded);
+            if (!lease.success)
+                throw metadataInvalid('operation-lease', valueFreeFailure(CaughtFailureSchema.parse(lease.error)));
+            return lease.data;
+        };
+        // Each holder has one permanent retirement destination. A second mv cannot
+        // replace its nonempty lease directory, even if a successor has acquired.
+        const retire = async (owner, expected, valuePath) => {
+            const retired = `${operationDirectory}/retired-${owner}`;
+            return this.shell(hostId, `mkdir -p ${shellQuote(retired)} && { IFS= read -r current < ${shellQuote(valuePath)} || test -n "$current"; } && test "$current" = "$VIBES_LEASE" && mv ${shellQuote(leaseDirectory)} ${shellQuote(retired)}/`, { env: { VIBES_LEASE: expected } });
+        };
+        const acquired = await pollUntil(this.runtime.lifecycle, async () => {
+            // Prepare outside the shared path. Only a complete, expiring holder
+            // becomes visible; interrupted preparation cannot block a successor.
+            const candidate = `${operationDirectory}/lease-candidate-${crypto.randomUUID()}`;
+            const candidateLease = JSON.stringify({ holderId, expiresAt: Date.now() + leaseDurationMs });
+            const attempt = await this.shell(hostId, `test ! -e ${shellQuote(leaseDirectory)} && mkdir ${shellQuote(candidate)} && mkdir ${shellQuote(candidate + '/' + holderId)} && printf '%s\n' "$VIBES_LEASE" > ${shellQuote(candidate + '/lease.json')} && printf '%s\n' "$VIBES_LEASE" > ${shellQuote(candidate + '/' + holderId + '/lease.json')} && mv ${shellQuote(candidate)} ${shellQuote(leaseDirectory)} && test -f ${shellQuote(holderPath + '/lease.json')}`, { env: { VIBES_LEASE: candidateLease } });
+            if (attempt.exitCode === 0)
+                return 'acquired';
+            const exists = await this.shell(hostId, `test -d ${shellQuote(leaseDirectory)}`);
+            if (exists.exitCode !== 0)
+                return null;
+            const latest = await this.readOperationRecord(hostId, operation.key);
+            if (replayTerminal && (latest?.stage === 'ready' || latest?.stage === 'attention-required' || latest?.stage === 'torn-down'))
+                return latest;
+            const value = await this.readRemoteText(hostId, leasePath);
+            if (value === null) {
+                // Compatibility with an old owner lost immediately after mkdir.
+                // rmdir can reclaim only the empty directory, never a live holder.
+                await this.shell(hostId, `rmdir ${shellQuote(leaseDirectory)}`);
+                return null;
+            }
+            const initial = readLease(value);
+            const renewalPath = `${leaseDirectory}/${initial.holderId}/lease.json`;
+            const renewed = await this.readRemoteText(hostId, renewalPath);
+            const lease = renewed === null ? initial : readLease(renewed);
+            if (lease.holderId !== initial.holderId)
+                throw metadataInvalid('operation-lease');
+            if (lease.expiresAt <= Date.now()) {
+                await retire(lease.holderId, (renewed ?? value).trimEnd(), renewed === null ? leasePath : renewalPath);
+            }
+            return null;
+        }, { intervalMs: 50, timeoutMs: 10 * 60_000, reason: 'code-session-relay-operation-lease' });
+        if (acquired !== 'acquired') {
+            operation.record = acquired;
+            return run();
+        }
+        const renew = async () => {
+            const temporary = `${holderPath}/renew-${crypto.randomUUID()}`;
+            const result = await this.shell(hostId, `printf '%s\n' "$VIBES_LEASE" > ${shellQuote(temporary)} && mv ${shellQuote(temporary)} ${shellQuote(holderPath + '/lease.json')}`, { env: { VIBES_LEASE: JSON.stringify({ holderId, expiresAt: Date.now() + leaseDurationMs }) } });
+            if (result.exitCode !== 0)
+                throw operationConflict(operation.record.operationId);
+        };
+        return this.withRequiredCleanup(hostId, 'operation-lease', () => withLeaseHeartbeat(this.runtime.lifecycle, { periodMs: leaseDurationMs / 3, operationId: operation.record.operationId, renew, logger: this.log }, async () => {
+            const latest = await this.readOperationRecord(hostId, operation.key);
+            if (latest)
+                operation.record = latest;
+            return run(holderPath);
+        }), async () => {
+            const value = await this.readRemoteText(hostId, `${holderPath}/lease.json`);
+            if (value === null)
+                return;
+            const released = await retire(holderId, value.trimEnd(), `${holderPath}/lease.json`);
+            if (released.exitCode !== 0) {
+                const remains = await this.readRemoteText(hostId, `${holderPath}/lease.json`);
+                if (remains !== null)
+                    throw cleanupUnconfirmed('operation-lease-release', []);
+            }
+        });
+    }
+    /** Write a file at an ABSOLUTE machine path via base64 through the env (no quoting risk). */
+    async writeRemoteFile(sessionId, absolutePath, content) {
+        const hostId = hostIdFromSessionId(sessionId);
+        // Compute the parent dir in JS — do NOT use `$(dirname …)` in the shell
+        // payload: command substitution is denied by the daemon's friction gate
+        // (it can hide a banned command), so a `$(…)` here would be vetoed. Pass
+        // the parent as a plain env var instead.
+        const slash = absolutePath.lastIndexOf('/');
+        const parentDir = slash > 0 ? absolutePath.slice(0, slash) : await this.sessionDir(sessionId);
+        const result = await this.shell(hostId, 'mkdir -p "$VIBES_DIR" && printf %s "$VIBES_B64" | base64 -d > "$VIBES_DEST"', { env: { VIBES_B64: toBase64(content), VIBES_DEST: absolutePath, VIBES_DIR: parentDir } });
+        if (result.exitCode !== 0) {
+            throw hostUnavailable(hostId);
+        }
+    }
+    // ------------------------------------------------------------------
+    // CodeSessionInterface
+    // ------------------------------------------------------------------
+    async initialize(input) {
+        input = parseCodeSessionInitializeInput(input);
+        if (input.sessionId) {
+            if (input.operationId) {
+                throw requestInvalid('sessionId');
+            }
+            const hostTarget = input.hostTarget;
+            if (hostTarget?.kind === 'host' &&
+                hostTarget.hostId &&
+                hostIdFromSessionId(input.sessionId) !== hostTarget.hostId) {
+                throw new CapabilityError('The relay session id and requested host disagree.', 'CONFLICT', {
+                    reason: 'code-session-relay-host-conflict',
+                    retryable: false,
+                    details: { sessionId: input.sessionId, hostId: hostTarget.hostId }
+                });
+            }
+            return this.attach(input.sessionId);
+        }
+        return this.createOrGet({
+            ...input,
+            operationId: input.operationId?.trim() || `initialize:${crypto.randomUUID()}`
+        });
+    }
+    async createOrGet(input) {
+        input = parseCodeSessionCreateOrGetInput(input);
+        const hostTarget = input.hostTarget;
+        if (!hostTarget || hostTarget.kind !== 'host' || !hostTarget.hostId || hostTarget.hostId === 'local') {
+            throw requestInvalid('hostTarget');
+        }
+        const hostId = parseRelayHostId(hostTarget.hostId);
+        if (input.workspacePath) {
+            throw requestInvalid('workspacePath');
+        }
+        input = {
+            ...input,
+            runtimeConfig: { ...this.descriptor.runtimeConfig, ...input.runtimeConfig },
+            exposedPorts: input.exposedPorts ?? [...this.descriptor.exposedPorts]
+        };
+        const operation = await this.prepareOperation(input, hostId);
+        return this.withOperationLease(hostId, operation, async (leaseHolderPath) => {
+            let record = operation.record;
+            const update = async (patch) => {
+                record = await this.writeOperationRecord(hostId, operation.key, record, patch, leaseHolderPath);
+                operation.record = record;
+            };
+            if (record.stage === 'cleanup-pending') {
+                throw operationConflict(record.operationId, 'cleanup-pending');
+            }
+            if (record.stage === 'torn-down') {
+                throw operationConflict(record.operationId, 'torn-down');
+            }
+            if (record.stage === 'attention-required') {
+                throw operationConflict(record.operationId, 'attention');
+            }
+            if (record.stage === 'setup-intent' || record.stage === 'setup-running') {
+                await update({
+                    stage: 'attention-required',
+                    failure: 'setup start was recorded without a durable success receipt; refusing to rerun it'
+                });
+                throw operationConflict(record.operationId, 'attention');
+            }
+            const sessionId = record.sessionId;
+            const allocationFailure = await notifyAllocated(input, sessionId);
+            if (allocationFailure) {
+                this.log.warn('onAllocated callback failed', { sessionId, failure: allocationFailure });
+            }
+            if (record.stage === 'ready')
+                return this.attach(sessionId);
+            const dir = await this.sessionDir(sessionId);
+            const readyMetadata = await this.readPersistedSessionMetadata(sessionId);
+            if (readyMetadata?.operationId === record.operationId &&
+                readyMetadata.operationFingerprint === record.fingerprint) {
+                await update({ stage: 'ready', failure: undefined });
+                return this.attach(sessionId);
+            }
+            const stagingPath = record.stagingPath ?? `${await this.sessionRoot(hostId)}/.staging/${operation.key}/generation-${record.generation}`;
+            await update({ stagingPath });
+            const runner = this.gitRunner(hostId);
+            if (record.stage === 'reserved' || record.stage === 'source-preparing') {
+                await update({ stage: 'source-preparing' });
+                const prepared = await this.shell(hostId, `mkdir -p ${shellQuote(stagingPath)}`);
+                if (prepared.exitCode !== 0) {
+                    throw hostUnavailable(hostId);
+                }
+                const gitDirectory = await this.shell(hostId, `test -d ${shellQuote(`${stagingPath}/.git`)}`);
+                const hasGit = gitDirectory.exitCode === 0;
+                if (input.cloneUrl) {
+                    if (hasGit) {
+                        const remote = await gitRaw(runner, stagingPath, ['remote', 'get-url', 'origin']);
+                        if (remote.exitCode !== 0 || remote.stdout.trim() !== input.cloneUrl) {
+                            await update({
+                                stage: 'attention-required',
+                                failure: 'the preserved staging repository does not match the requested clone URL'
+                            });
+                            throw operationConflict(record.operationId);
+                        }
+                    }
+                    else {
+                        const contents = await this.shell(hostId, `find ${shellQuote(stagingPath)} -mindepth 1 -maxdepth 1 -print -quit`);
+                        if (contents.stdout.trim()) {
+                            await update({
+                                stage: 'attention-required',
+                                failure: 'clone was interrupted and left an unverified staging workspace'
+                            });
+                            throw operationConflict(record.operationId);
+                        }
+                        const cloneInput = {
+                            url: input.cloneUrl,
+                            dir: stagingPath
+                        };
+                        if (input.checkoutRef)
+                            cloneInput.branch = input.checkoutRef;
+                        if (input.cloneCredential) {
+                            cloneInput.credential = toGitCredential(input.cloneCredential);
+                        }
+                        const clone = await gitClone(runner, cloneInput);
+                        if (clone.exitCode !== 0) {
+                            await update({
+                                stage: 'attention-required',
+                                failure: `clone failed with exit code ${clone.exitCode}`
+                            });
+                            throw hostUnavailable(hostId);
+                        }
+                    }
+                }
+                else if ((input.repositoryId || input.ephemeral) && !hasGit) {
+                    const init = await gitInit(runner, stagingPath);
+                    if (init.exitCode !== 0) {
+                        await update({
+                            stage: 'attention-required',
+                            failure: `git init failed with exit code ${init.exitCode}`
+                        });
+                        throw hostUnavailable(hostId);
+                    }
+                }
+                await update({ stage: 'source-ready', failure: undefined });
+            }
+            const setupScript = input.runtimeConfig?.setupScript?.trim();
+            if (setupScript && record.stage === 'source-ready') {
+                await update({ stage: 'setup-intent' });
+                await update({ stage: 'setup-running' });
+                let setup;
+                try {
+                    setup = await this.shell(hostId, setupScript, { cwd: stagingPath, env: input.initialEnv });
+                }
+                catch (caught) {
+                    const failure = CaughtFailureSchema.parse(caught);
+                    const facts = valueFreeFailure(failure);
+                    await update({ stage: 'attention-required', failure: `setup failed: ${facts.name}` });
+                    throw setupFailed(hostId, valueFreeFailure(failure));
+                }
+                if (setup.exitCode !== 0) {
+                    await update({
+                        stage: 'attention-required',
+                        failure: `setup failed with exit code ${setup.exitCode}`
+                    });
+                    throw setupFailed(hostId);
+                }
+                await update({ stage: 'setup-succeeded', failure: undefined });
+            }
+            else if (!setupScript && record.stage === 'source-ready') {
+                await update({ stage: 'setup-succeeded', failure: undefined });
+            }
+            if (input.exposedPorts?.length) {
+                this.log.warn?.('exposed ports are not supported on fleet hosts yet — skipping', {
+                    sessionId,
+                    ports: input.exposedPorts
+                });
+            }
+            await this.persistSessionMetadata(sessionId, {
+                sessionId,
+                operationId: record.operationId,
+                operationFingerprint: record.fingerprint,
+                createdAt: record.createdAt,
+                hostTarget,
+                repositoryId: input.repositoryId,
+                cloneUrl: input.cloneUrl,
+                ephemeral: input.ephemeral,
+                checkoutRef: input.checkoutRef
+            }, stagingPath);
+            const authoritative = await this.readOperationRecord(hostId, operation.key);
+            if (!authoritative || authoritative.generation !== record.generation) {
+                throw operationConflict(record.operationId);
+            }
+            const published = await this.shell(hostId, `if test -e ${shellQuote(dir)}; then exit 17; else mkdir -p ${shellQuote(await this.sessionRoot(hostId))} && mv ${shellQuote(stagingPath)} ${shellQuote(dir)}; fi`);
+            if (published.exitCode !== 0) {
+                if (published.exitCode !== 17)
+                    throw hostUnavailable(hostId);
+                const existing = await this.readPersistedSessionMetadata(sessionId);
+                if (existing?.operationId !== record.operationId ||
+                    existing.operationFingerprint !== record.fingerprint) {
+                    await update({
+                        stage: 'attention-required',
+                        failure: 'the final workspace exists but was not proven to belong to this operation'
+                    });
+                    throw operationConflict(record.operationId);
+                }
+            }
+            if (input.repositoryId)
+                this.sessionRepositoryIds.set(sessionId, input.repositoryId);
+            await update({ stage: 'ready', failure: undefined });
+            return {
+                sessionId,
+                operationId: record.operationId,
+                workspacePath: dir,
+                createdAt: record.createdAt,
+                hostTarget,
+                repositoryId: input.repositoryId,
+                ephemeral: input.ephemeral
+            };
+        });
+    }
+    async attach(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const hostId = hostIdFromSessionId(sessionId);
+        const liveness = await this.exec(hostId, { command: 'true', timeout: 10_000 });
+        if (liveness.exitCode !== 0) {
+            throw hostUnavailable(hostId);
+        }
+        const metadata = await this.requireReadySessionMetadata(sessionId);
+        if (metadata.repositoryId) {
+            this.sessionRepositoryIds.set(sessionId, metadata.repositoryId);
+        }
+        return {
+            sessionId,
+            operationId: metadata.operationId,
+            workspacePath: await this.sessionDir(sessionId),
+            createdAt: metadata.createdAt,
+            hostTarget: metadata.hostTarget ?? { kind: 'host', hostId },
+            repositoryId: metadata.repositoryId,
+            ephemeral: metadata.ephemeral
+        };
+    }
+    /** Persist the paused flag; the remote workspace is kept and `runCommand` refuses until resume. */
+    async pause(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const metadata = await this.requireReadySessionMetadata(sessionId);
+        if (!metadata.pausedAt) {
+            await this.persistSessionMetadata(sessionId, { ...metadata, pausedAt: new Date().toISOString() });
+        }
+        return this.attach(sessionId);
+    }
+    async resume(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const metadata = await this.requireReadySessionMetadata(sessionId);
+        if (metadata.pausedAt) {
+            await this.persistSessionMetadata(sessionId, { ...metadata, pausedAt: undefined });
+        }
+        return this.attach(sessionId);
+    }
+    async runCommand(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseRunCommandInput(input);
+        if (input.background) {
+            throw requestInvalid('background');
+        }
+        const ready = await this.requireReadySessionMetadata(sessionId);
+        if (ready.pausedAt)
+            throw sessionPaused(sessionId);
+        const hostId = hostIdFromSessionId(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        const cwd = input.cwd ? `${dir}/${normalizeRelativePath(dir, input.cwd)}` : dir;
+        const [command, ...args] = input.command;
+        const execOptions = {
+            command,
+            args,
+            cwd,
+            timeout: input.timeoutMs ?? this.descriptor.timeoutMs
+        };
+        if (input.env)
+            execOptions.env = input.env;
+        const result = await this.exec(hostId, execOptions);
+        return {
+            exitCode: result.exitCode,
+            stdout: result.stdout,
+            stderr: result.stderr,
+            timedOut: result.timedOut,
+            durationMs: result.durationMs
+        };
+    }
+    async listBackgroundProcesses(sessionId) {
+        parseCodeSessionId(sessionId);
+        throw requestInvalid('background');
+    }
+    async stopBackgroundProcess(sessionId, procId, signal) {
+        parseCodeSessionId(sessionId);
+        parseProcessId(procId);
+        parseProcessSignal(signal);
+        throw requestInvalid('background');
+    }
+    async readFile(sessionId, path) {
+        sessionId = parseCodeSessionId(sessionId);
+        path = parseCodeSessionPath(path);
+        await this.requireReadySessionMetadata(sessionId);
+        const hostId = hostIdFromSessionId(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        const result = await this.exec(hostId, {
+            command: 'cat',
+            args: [`${dir}/${normalizeRelativePath(dir, path)}`]
+        });
+        if (result.exitCode !== 0) {
+            throw hostUnavailable(hostId);
+        }
+        return result.stdout;
+    }
+    async writeFile(sessionId, path, content) {
+        sessionId = parseCodeSessionId(sessionId);
+        ({ path, content } = parseWriteFileInput(path, content));
+        await this.requireReadySessionMetadata(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        await this.writeRemoteFile(sessionId, `${dir}/${normalizeRelativePath(dir, path)}`, content);
+    }
+    async patchFile(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parsePatchFileInput(input);
+        await this.requireReadySessionMetadata(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        normalizeRelativePath(dir, input.path);
+        const result = await this.applyDiff(sessionId, input.diff, false);
+        if (!result.ok) {
+            throw hostUnavailable(hostIdFromSessionId(sessionId));
+        }
+    }
+    async gitApply(sessionId, input) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseGitApplyInput(input);
+        await this.requireReadySessionMetadata(sessionId);
+        return this.applyDiff(sessionId, input.diff, input.check ?? false);
+    }
+    async applyDiff(sessionId, diff, check) {
+        const hostId = hostIdFromSessionId(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        const patchPath = `${dir}/.vibes-patch-${newSessionId(hostId).split('.')[2]}.diff`;
+        await this.writeRemoteFile(sessionId, patchPath, diff);
+        return this.withRequiredCleanup(hostId, 'temporary-patch', async () => {
+            const args = check ? ['apply', '--check', patchPath] : ['apply', patchPath];
+            const result = await gitRaw(this.gitRunner(hostId), dir, args);
+            return {
+                ok: result.exitCode === 0,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                exitCode: result.exitCode
+            };
+        }, async () => {
+            // Direct `rm <path>` (no shell and no force flag) passes the daemon's friction gate.
+            const removed = await this.exec(hostId, { command: 'rm', args: [patchPath] });
+            if (removed.exitCode !== 0)
+                throw cleanupUnconfirmed('temporary-patch-remove', []);
+        });
+    }
+    async gitStatus(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        await this.requireReadySessionMetadata(sessionId);
+        const hostId = hostIdFromSessionId(sessionId);
+        return gitStatus(this.gitRunner(hostId), await this.sessionDir(sessionId));
+    }
+    async gitCommit(sessionId, input, options = {}) {
+        const signal = parseGitCommitOptions(options).signal;
+        signal?.throwIfAborted();
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseGitCommitInput(input);
+        await this.requireReadySessionMetadata(sessionId);
+        signal?.throwIfAborted();
+        const hostId = hostIdFromSessionId(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        const commitInput = { message: input.message };
+        if (input.author)
+            commitInput.author = input.author;
+        if (input.paths) {
+            commitInput.paths = input.paths.map((p) => normalizeRelativePath(dir, p));
+        }
+        return gitCommit(this.gitRunner(hostId, signal), dir, commitInput);
+    }
+    async gitPush(sessionId, input = {}) {
+        sessionId = parseCodeSessionId(sessionId);
+        input = parseGitPushInput(input);
+        await this.requireReadySessionMetadata(sessionId);
+        const hostId = hostIdFromSessionId(sessionId);
+        let credential = input.credential;
+        if (!credential && this.pushCredentialResolver) {
+            const repositoryId = this.sessionRepositoryIds.get(sessionId);
+            if (repositoryId) {
+                credential = (await this.pushCredentialResolver(repositoryId)) ?? undefined;
+            }
+        }
+        const pushInput = {};
+        if (input.remote)
+            pushInput.remote = input.remote;
+        if (input.branch)
+            pushInput.branch = input.branch;
+        if (input.setUpstream)
+            pushInput.setUpstream = true;
+        if (credential)
+            pushInput.credential = toGitCredential(credential);
+        await gitPush(this.gitRunner(hostId), await this.sessionDir(sessionId), pushInput);
+    }
+    async exposePort(sessionId, input) {
+        parseCodeSessionId(sessionId);
+        parseExposePortInput(input);
+        throw new CapabilityError('The relay code-session host cannot expose a preview port.', 'UNAVAILABLE', {
+            reason: 'code-session-host-unavailable',
+            retryable: false
+        });
+    }
+    /** Find durable ownership without depending on metadata inside a deleting tree. */
+    async teardownOperation(sessionId) {
+        const hostId = hostIdFromSessionId(sessionId);
+        const root = await this.sessionRoot(hostId);
+        const metadata = await this.readPersistedSessionMetadata(sessionId);
+        if (metadata && (metadata.sessionId !== sessionId || metadata.hostTarget.kind !== 'host' || metadata.hostTarget.hostId !== hostId)) {
+            throw operationConflict('teardown');
+        }
+        const directory = `${root}/.operations`;
+        const listed = await this.shell(hostId, `if test -d ${shellQuote(directory)}; then find ${shellQuote(directory)} -mindepth 2 -maxdepth 2 -name operation.json -print; fi`);
+        if (listed.exitCode !== 0)
+            throw hostUnavailable(hostId);
+        const candidates = [];
+        for (const path of listed.stdout.split('\n').filter(Boolean)) {
+            const key = path.slice(directory.length + 1, -'/operation.json'.length);
+            if (path !== `${directory}/${key}/operation.json` || !/^[0-9a-f]{64}$/.test(key))
+                throw metadataInvalid('operation');
+            const record = await this.readOperationRecord(hostId, key);
+            if (!record)
+                throw metadataInvalid('operation');
+            if (record.sessionId === sessionId || sessionId === `rly.${hostId}.${key.slice(0, 12)}`)
+                candidates.push({ key, record });
+        }
+        if (candidates.length > 1)
+            throw operationConflict('teardown');
+        if (candidates.length === 1) {
+            const operation = candidates[0];
+            const { key, record } = operation;
+            if (record.sessionId !== sessionId || await codeSessionOperationKey(record.operationId) !== key ||
+                (metadata && metadata.operationId && (metadata.operationId !== record.operationId || metadata.operationFingerprint !== record.fingerprint))) {
+                throw operationConflict('teardown');
+            }
+            const markers = `${await this.operationDirectory(hostId, key)}/fingerprints`;
+            const checked = await this.shell(hostId, `find ${shellQuote(markers)} -mindepth 1 -maxdepth 1 -print`);
+            if (checked.exitCode !== 0 || checked.stdout.trim() !== `${markers}/${record.fingerprint.slice('sha256:'.length)}`)
+                throw operationConflict('teardown');
+            return operation;
+        }
+        // Older initialized sessions have metadata but no operation record. Adopt
+        // their validated identity into the same durable owner before moving them.
+        if (!metadata || metadata.operationId)
+            throw operationConflict('teardown');
+        const operationId = `teardown:${sessionId}`;
+        const key = await codeSessionOperationKey(operationId);
+        const fingerprint = await codeSessionOperationFingerprint({ operationId, hostTarget: metadata.hostTarget }, { authorityId: this.descriptor.id });
+        const now = new Date().toISOString();
+        const record = { operationId, fingerprint, sessionId, generation: 1, stage: 'ready', createdAt: now, updatedAt: now };
+        return this.claimOperationRecord(hostId, key, record);
+    }
+    async teardown(sessionId) {
+        sessionId = parseCodeSessionId(sessionId);
+        const hostId = hostIdFromSessionId(sessionId);
+        const dir = await this.sessionDir(sessionId);
+        const operation = await this.teardownOperation(sessionId);
+        await this.withOperationLease(hostId, operation, async (leaseHolderPath) => {
+            let record = operation.record;
+            const update = async (patch) => {
+                record = await this.writeOperationRecord(hostId, operation.key, record, patch, leaseHolderPath);
+                operation.record = record;
+            };
+            const root = await this.sessionRoot(hostId);
+            const quarantine = `${await this.operationDirectory(hostId, operation.key)}/cleanup-${record.generation}/workspace`;
+            if (record.stage === 'torn-down')
+                return;
+            if (record.stage !== 'cleanup-pending') {
+                if (record.stage !== 'ready')
+                    throw operationConflict('teardown');
+                const metadata = await this.readPersistedSessionMetadata(sessionId);
+                if (!metadata || metadata.sessionId !== sessionId || metadata.hostTarget.kind !== 'host' || metadata.hostTarget.hostId !== hostId ||
+                    (metadata.operationId && (metadata.operationId !== record.operationId || metadata.operationFingerprint !== record.fingerprint)))
+                    throw operationConflict('teardown');
+                await update({ stage: 'cleanup-pending', failure: undefined, cleanup: {
+                        path: quarantine, phase: 'intent', relay: { authorityId: this.descriptor.id, hostId, sessionRoot: root, legacy: !metadata.operationId }
+                    } });
+            }
+            const cleanup = record.cleanup;
+            if (!cleanup || cleanup.path !== quarantine || cleanup.relay?.authorityId !== this.descriptor.id ||
+                cleanup.relay.hostId !== hostId || cleanup.relay.sessionRoot !== root || record.sessionId !== sessionId ||
+                (!cleanup.relay.legacy && sessionId !== `rly.${hostId}.${operation.key.slice(0, 12)}`))
+                throw operationConflict('teardown');
+            // Read back authorization before crossing the destructive boundary.
+            const durable = await this.readOperationRecord(hostId, operation.key);
+            if (!durable || JSON.stringify(durable) !== JSON.stringify(record))
+                throw operationConflict('teardown');
+            try {
+                if (cleanup.phase === 'intent') {
+                    const exists = await this.shell(hostId, `test -e ${shellQuote(dir)} || test -L ${shellQuote(dir)}`);
+                    if (exists.exitCode !== 0 && exists.exitCode !== 1)
+                        throw hostUnavailable(hostId);
+                    if (exists.exitCode === 0) {
+                        const metadata = await this.readPersistedSessionMetadata(sessionId);
+                        if (!metadata || metadata.sessionId !== sessionId || metadata.hostTarget.kind !== 'host' || metadata.hostTarget.hostId !== hostId ||
+                            (cleanup.relay.legacy ? !!metadata.operationId : metadata.operationId !== record.operationId || metadata.operationFingerprint !== record.fingerprint))
+                            throw operationConflict('teardown');
+                    }
+                    const moved = await this.shell(hostId, `if test -e ${shellQuote(dir)} || test -L ${shellQuote(dir)}; then test ! -e ${shellQuote(quarantine)} && test ! -L ${shellQuote(quarantine)} && test ! -L ${shellQuote(dir)} && mkdir -p ${shellQuote(quarantine.slice(0, -'/workspace'.length))} && mv ${shellQuote(dir)} ${shellQuote(quarantine)}; fi`);
+                    if (moved.exitCode !== 0)
+                        throw cleanupUnconfirmed('session-teardown', []);
+                    await update({ cleanup: { ...cleanup, phase: 'quarantined' } });
+                }
+                const result = await this.shell(hostId, `if test -e ${shellQuote(quarantine)}; then test ! -L ${shellQuote(quarantine)} && find ${shellQuote(quarantine)} -depth -mindepth 1 -delete && rmdir ${shellQuote(quarantine)}; fi; test ! -e ${shellQuote(quarantine)} && test ! -L ${shellQuote(quarantine)} && test ! -e ${shellQuote(dir)} && test ! -L ${shellQuote(dir)}`);
+                if (result.exitCode !== 0 || result.timedOut)
+                    throw cleanupUnconfirmed('session-teardown', []);
+                const confirmed = await this.shell(hostId, `test ! -e ${shellQuote(quarantine)} && test ! -L ${shellQuote(quarantine)} && test ! -e ${shellQuote(dir)} && test ! -L ${shellQuote(dir)}`);
+                if (confirmed.exitCode !== 0 || confirmed.timedOut)
+                    throw cleanupUnconfirmed('session-teardown', []);
+                await update({ stage: 'torn-down', cleanup: { ...cleanup, phase: 'removed' }, failure: undefined });
+            }
+            catch (caught) {
+                throw cleanupUnconfirmed('session-teardown', [valueFreeFailure(CaughtFailureSchema.parse(caught))]);
+            }
+            this.sessionRepositoryIds.delete(sessionId);
+        }, false);
+    }
+    /** Close every cached relay connection (tests + orderly shutdown). */
+    async close() {
+        const handles = await Promise.allSettled(this.hosts.values());
+        this.hosts.clear();
+        const failures = [];
+        const closing = [];
+        for (const settled of handles) {
+            if (settled.status === 'fulfilled') {
+                closing.push(settled.value.connection.close());
+            }
+            else {
+                failures.push(valueFreeFailure(CaughtFailureSchema.parse(settled.reason)));
+            }
+        }
+        const closed = await Promise.allSettled(closing);
+        for (const settled of closed) {
+            if (settled.status === 'rejected') {
+                failures.push(valueFreeFailure(CaughtFailureSchema.parse(settled.reason)));
+            }
+        }
+        if (failures.length > 0)
+            throw cleanupUnconfirmed('relay-close', failures);
+    }
+}
+import relayCodeSessionDescriptor from "./agent-code-session-relay.descriptor.js";
+class RelayCodeSessionImpl extends RelayCodeSession {
+    constructor(descriptor, context) {
+        super(AgentCodeSessionDescriptorSchema.parse(descriptor), context.runtime);
+    }
+}
+export default createRuntimeImplementation({
+    kind: 'agent/code-session',
+    id: relayCodeSessionDescriptor.id,
+    constraint: { hardware: ['cloud'] },
+    implementation: RelayCodeSessionImpl
+});
+//# sourceMappingURL=agent-code-session-relay.impl.js.map