@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/ports/workspace/fake.ts

@@ -28,7 +28,12 @@ import {
   type SandboxEnvironmentIdentity,
   type SandboxWaitResult,
 } from './operator-sandbox'
-import type { WorkspaceHandle, WorkspaceProvider, WorkspaceProvisionResult } from '../types'
+import type {
+  WorkspaceHandle,
+  WorkspaceProvider,
+  WorkspaceProvisionResult,
+  WorkspacePublication,
+} from '../types'
 
 export interface ProvisionRecord {
   repo: string
@@ -51,10 +56,23 @@ async function pathExists(path: string): Promise<boolean> {
 export class FakeWorkspaceProvider implements WorkspaceProvider {
   readonly name = 'fake'
   readonly orchestratorSandbox: OperatorSandboxExecution
+  readonly sandboxPublication: WorkspacePublication
 
   /** Journals — public so tests assert directly on call order and args. */
   readonly provisions: ProvisionRecord[] = []
   readonly releases: WorkspaceHandle[] = []
+  /** Journal — per-spawn guest environments, recorded by the operator-sandbox
+   * capability's spawn sites (`exec`, `start`, and the setup-command spawn)
+   * just before the child launches. Credential-freeness is asserted against
+   * these records directly: what the provider constructed, not what a shell
+   * reported. */
+  readonly sandboxExecEnvironments: Array<{
+    op: 'exec' | 'start' | 'setup'
+    command: string
+    env: Record<string, string>
+  }> = []
+  /** Journal — sandbox publication pushes, in call order. */
+  readonly publications: Array<{ ref: string; sha: string; branch: string }> = []
 
   private readonly root: string
   private readonly initialBase: WorkspaceBase
@@ -68,6 +86,12 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
   /** Durable fake branch heads survive release, like real Git branches. */
   private readonly branchHeads = new Map<string, string>()
   private readonly failures = new Map<'provision' | 'release', Error>()
+  /** Injectable publication failure: while set, `sandboxPublication.publish`
+   * throws it on every call (pass `null` to clear). */
+  private publicationFailure: Error | null = null
+  /** environmentId → the base branch the fresh provision selected, so the
+   * publication capability can refuse the base branch as defense in depth. */
+  private readonly sandboxBaseBranches = new Map<string, string>()
 
   constructor(
     opts: {
@@ -102,6 +126,30 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
       stop: () => Promise.resolve({ outcome: 'stopped' as const }),
       release: (input) => this.sandboxRelease(input),
     }
+    this.sandboxPublication = {
+      isPublished: (input) =>
+        Promise.resolve(
+          this.publications.some(
+            (entry) => entry.branch === input.branch && entry.sha === input.sha,
+          ),
+        ),
+      publish: (input) => this.publishSandbox(input),
+    }
+  }
+
+  /** Injectable publication failure: while set, the sandbox publication push
+   * throws `error` on every call (pass `null` to clear). */
+  setPublicationFailure(error: Error | null): void {
+    this.publicationFailure = error
+  }
+
+  private async publishSandbox(input: { ref: string; sha: string; branch: string }): Promise<void> {
+    if (this.publicationFailure) throw this.publicationFailure
+    const baseBranch = this.sandboxBaseBranches.get(input.ref)
+    if (baseBranch !== undefined && input.branch === baseBranch) {
+      throw new Error(`publication refuses the base branch ${baseBranch}`)
+    }
+    this.publications.push({ ...input })
   }
 
   /**
@@ -240,6 +288,12 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
   }): Promise<SandboxEnvironmentIdentity> {
     const identity = this.sandboxIdentity(input.repo, input.operator)
     if (await pathExists(join(identity.workspacePath, '.autobuild-sandbox-provisioned'))) {
+      // Pre-existing sandboxes provisioned before the info/exclude write
+      // landed (AUT-580) keep an unexcluded marker; write the exclusion on
+      // every ensure, mirroring GitWorktreeProvider, so the publish
+      // service's untracked-inclusive dirty check never counts the marker
+      // as dirt.
+      await this.excludeProvisioningMarker(identity.workspacePath)
       return identity
     }
     if (this.mode !== 'filesystem') {
@@ -252,7 +306,55 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
     await rm(identity.workspacePath, { recursive: true, force: true })
     await cp(input.repo, identity.workspacePath, { recursive: true })
     try {
+      // Real git checkout (publish-service parity): the three git checks the
+      // publish service runs through capability.exec (rev-parse, status,
+      // merge-base) must work against the fake exactly as against the real
+      // providers, which serve a genuine checkout. A plain fixture source is
+      // not a git repository, so the fake initializes one from the base
+      // branch and makes a seed commit; a source that already IS a git
+      // repository is used as-is. baseSha is the base branch's head after
+      // provisioning — the same value the real providers resolve.
+      if (!(await pathExists(join(identity.workspacePath, '.git')))) {
+        await this.runSandboxGit(identity.workspacePath, ['init', '-b', input.baseBranch])
+        await this.runSandboxGit(identity.workspacePath, ['config', 'user.name', 'autobuild[bot]'])
+        await this.runSandboxGit(identity.workspacePath, [
+          'config',
+          'user.email',
+          'autobuild[bot]@users.noreply.github.com',
+        ])
+        await this.runSandboxGit(identity.workspacePath, ['add', '-A'])
+        const committed = await this.runSandboxGit(identity.workspacePath, [
+          'commit',
+          '--allow-empty',
+          '-q',
+          '-m',
+          'sandbox seed',
+        ])
+        if (committed.exitCode !== 0) {
+          throw new SandboxOperationError(
+            'provision',
+            `operator sandbox git seed failed: ${committed.stderr.trim() || committed.stdout.trim()}`,
+          )
+        }
+      }
+      const head = await this.runSandboxGit(identity.workspacePath, [
+        'rev-parse',
+        `refs/heads/${input.baseBranch}`,
+      ])
+      if (head.exitCode !== 0 || head.stdout.trim() === '') {
+        throw new SandboxOperationError(
+          'provision',
+          `operator sandbox could not resolve base branch ${input.baseBranch}: ${head.stderr.trim() || head.stdout.trim() || `exit ${head.exitCode}`}`,
+        )
+      }
+      const baseSha = head.stdout.trim()
+      this.sandboxBaseBranches.set(identity.environmentId, input.baseBranch)
       if (this.sandboxSetupCommand !== undefined && this.sandboxSetupCommand.trim() !== '') {
+        this.sandboxExecEnvironments.push({
+          op: 'setup',
+          command: this.sandboxSetupCommand,
+          env: this.sandboxEnv(),
+        })
         const proc = Bun.spawn(['sh', '-c', this.sandboxSetupCommand], {
           cwd: identity.workspacePath,
           stdin: 'ignore',
@@ -272,12 +374,71 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
           )
         }
       }
+      await this.excludeProvisioningMarker(identity.workspacePath)
+      // The marker file write deliberately stays outside
+      // excludeProvisioningMarker: that helper is the info/exclude exclusion
+      // logic alone (the early-return heal runs it too), while this write is
+      // provisioning-specific.
       await fsWriteFile(join(identity.workspacePath, '.autobuild-sandbox-provisioned'), '')
+      return { ...identity, baseSha }
     } catch (error) {
       await rm(identity.workspacePath, { recursive: true, force: true })
       throw error
     }
-    return identity
+  }
+
+  /** Idempotently exclude the provisioning marker in the checkout's
+   * info/exclude so the publish service's untracked-inclusive dirty check
+   * never counts it as dirt (f_c748dc6a). Runs on both ensure paths —
+   * fresh provisioning and the marker-exists early return — so sandboxes
+   * provisioned before the write landed are healed the next time they are
+   * ensured. Mirrors GitWorktreeProvider. */
+  private async excludeProvisioningMarker(workspacePath: string): Promise<void> {
+    const exclude = await this.runSandboxGit(workspacePath, [
+      'rev-parse',
+      '--git-path',
+      'info/exclude',
+    ])
+    if (exclude.exitCode !== 0 || exclude.stdout.trim() === '') {
+      throw new SandboxOperationError(
+        'provision',
+        `operator sandbox could not resolve info/exclude: ${exclude.stderr.trim() || `exit ${exclude.exitCode}`}`,
+      )
+    }
+    const excludePath = resolve(workspacePath, exclude.stdout.trim())
+    await mkdir(dirname(excludePath), { recursive: true })
+    const existingExclude = await fsReadFile(excludePath, 'utf8').then(
+      (content) => content,
+      () => '',
+    )
+    if (!existingExclude.split('\n').includes('.autobuild-sandbox-provisioned')) {
+      const prefix =
+        existingExclude === '' || existingExclude.endsWith('\n')
+          ? existingExclude
+          : `${existingExclude}\n`
+      await fsWriteFile(excludePath, `${prefix}.autobuild-sandbox-provisioned\n`)
+    }
+  }
+
+  /** One git invocation inside the sandbox checkout with the same
+   * credential-free guest environment as every exec. */
+  private async runSandboxGit(
+    cwd: string,
+    args: string[],
+  ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+    const proc = Bun.spawn(['git', ...args], {
+      cwd,
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'pipe',
+      env: this.sandboxEnv(),
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ])
+    return { exitCode: exitCode ?? -1, stdout, stderr }
   }
 
   private sandboxCwd(handle: SandboxEnvironmentIdentity, cwd: string | undefined): string {
@@ -289,12 +450,14 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
     request: { command: string; cwd?: string; timeoutSeconds?: number },
   ): Promise<SandboxCommandResult> {
     const timeoutSeconds = Math.min(Math.max(request.timeoutSeconds ?? 120, 1), 300)
+    const env = this.sandboxEnv()
+    this.sandboxExecEnvironments.push({ op: 'exec', command: request.command, env })
     const proc = Bun.spawn(['sh', '-c', request.command], {
       cwd: this.sandboxCwd(handle, request.cwd),
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'pipe',
-      env: this.sandboxEnv(),
+      env,
     })
     const timer = AbortSignal.timeout(timeoutSeconds * 1000)
     const outcome = await Promise.race([
@@ -331,12 +494,14 @@ export class FakeWorkspaceProvider implements WorkspaceProvider {
     handle: SandboxEnvironmentIdentity,
     request: { command: string; cwd?: string },
   ): Promise<{ commandId: string }> {
+    const env = this.sandboxEnv()
+    this.sandboxExecEnvironments.push({ op: 'start', command: request.command, env })
     const proc = Bun.spawn(['sh', '-c', request.command], {
       cwd: this.sandboxCwd(handle, request.cwd),
       stdin: 'ignore',
       stdout: 'pipe',
       stderr: 'pipe',
-      env: this.sandboxEnv(),
+      env,
     })
     const commandId = `sbcmd-${Math.random().toString(36).slice(2, 12)}`
     const tracked = { proc, stdout: '', stderr: '', exitCode: null as number | null }

package/packages/core/src/ports/workspace/git-worktree.ts

@@ -19,7 +19,12 @@ import {
   type SandboxEnvironmentIdentity,
   type SandboxWaitResult,
 } from './operator-sandbox'
-import type { WorkspaceHandle, WorkspaceProvider, WorkspaceProvisionResult } from '../types'
+import type {
+  WorkspaceHandle,
+  WorkspaceProvider,
+  WorkspaceProvisionResult,
+  WorkspacePublication,
+} from '../types'
 
 export interface ExecResult {
   stdout: string
@@ -107,6 +112,7 @@ function parseWorktreeList(porcelain: string): WorktreeEntry[] {
 export class GitWorktreeProvider implements WorkspaceProvider {
   readonly name = 'git-worktree'
   readonly orchestratorSandbox: OperatorSandboxExecution
+  readonly sandboxPublication: WorkspacePublication
   private readonly root: string
   private readonly sandboxRoot: string
   private readonly setupCommand: string | undefined
@@ -124,6 +130,10 @@ export class GitWorktreeProvider implements WorkspaceProvider {
   constructor(opts: {
     root: string
     exec?: Exec
+    /** Test-only override of the exit-stamp drain grace
+     * (`DEFAULT_SANDBOX_EXIT_DRAIN_GRACE_MS`); production behavior is
+     * unchanged. */
+    exitDrainGraceMs?: number
     /** Operator-sandbox worktree root; defaults to a sibling of the build
      * worktree root inside the local state tree. */
     sandboxRoot?: string
@@ -141,6 +151,8 @@ export class GitWorktreeProvider implements WorkspaceProvider {
     this.setupCommand = opts.setupCommand
     this.sandboxEnvironmentVariables = opts.sandboxEnvironmentVariables ?? []
     this.sandboxEnvSource = opts.envSource ?? {}
+    this.exitDrainGraceMs =
+      opts.exitDrainGraceMs ?? GitWorktreeProvider.DEFAULT_SANDBOX_EXIT_DRAIN_GRACE_MS
     this.exec = opts.exec ?? spawnExec
     this.orchestratorSandbox = {
       describe: (input) => Promise.resolve(this.sandboxIdentity(input.repo, input.operator)),
@@ -153,6 +165,10 @@ export class GitWorktreeProvider implements WorkspaceProvider {
       stop: () => Promise.resolve({ outcome: 'unsupported' as const }),
       release: (input) => this.sandboxRelease(input),
     }
+    this.sandboxPublication = {
+      isPublished: (input) => this.sandboxIsPublished(input),
+      publish: (input) => this.publishSandbox(input),
+    }
   }
 
   private async realRoot(): Promise<string> {
@@ -477,10 +493,25 @@ export class GitWorktreeProvider implements WorkspaceProvider {
 
   /** Main-repo directory owning the worktree at `path`, or null if the path
    * is gone or not a worktree — the release-is-a-no-op cases. Needed when a
-   * restarted process releases a worktree it did not provision (§7.4). */
+   * restarted process releases a worktree it did not provision (§7.4).
+   * A successful `rev-parse --git-common-dir` with empty stdout is a
+   * degenerate input — feeding it to `resolve` would target the worktree
+   * directory itself and misdirect the subsequent `worktree remove` — so it
+   * fails loudly with a `GitError` (same posture as `shaFrom`'s empty-SHA
+   * guard) rather than masquerading as a release-is-a-no-op case. The error
+   * type diverges deliberately from `excludeProvisioningMarker`'s
+   * `SandboxOperationError`: this is provider-level discovery shared by
+   * `release` and `sandboxRelease`, not a sandbox operation. */
   private async discoverRepo(path: string): Promise<string | null> {
     const result = await this.git(path, ['rev-parse', '--git-common-dir'])
     if (result.exitCode !== 0) return null
+    if (result.stdout.trim() === '') {
+      throw new GitError(['-C', path, 'rev-parse', '--git-common-dir'], {
+        ...result,
+        exitCode: 1,
+        stderr: 'git returned no common directory',
+      })
+    }
     const commonDir = resolve(path, result.stdout.trim())
     // The common dir is the main repo's `.git`; worktree commands need the
     // repo directory itself (a bare common dir already is one).
@@ -536,7 +567,15 @@ export class GitWorktreeProvider implements WorkspaceProvider {
     baseBranch: string
   }): Promise<SandboxEnvironmentIdentity> {
     const identity = this.sandboxIdentity(input.repo, input.operator)
-    if (await this.isRegisteredWorktree(identity.environmentId, input.repo)) return identity
+    if (await this.isRegisteredWorktree(identity.environmentId, input.repo)) {
+      // Pre-existing sandboxes provisioned before the info/exclude write
+      // landed (AUT-580) keep an unexcluded marker; write the exclusion on
+      // every ensure so the publish service's untracked-inclusive dirty
+      // check never counts the marker as dirt and the correct baseSha /
+      // reset-required diagnostic surfaces.
+      await this.excludeProvisioningMarker(identity.workspacePath)
+      return identity
+    }
     await mkdir(this.sandboxRoot, { recursive: true })
     const baseHead = await this.resolveCommit(input.repo, `refs/heads/${input.baseBranch}`)
     await this.gitOrThrow(input.repo, [
@@ -547,6 +586,7 @@ export class GitWorktreeProvider implements WorkspaceProvider {
       baseHead,
     ])
     try {
+      await this.excludeProvisioningMarker(identity.workspacePath)
       const marker = join(identity.workspacePath, '.autobuild-sandbox-provisioned')
       const provisioned = await stat(marker).then(
         () => true,
@@ -572,7 +612,45 @@ export class GitWorktreeProvider implements WorkspaceProvider {
       await this.git(input.repo, ['worktree', 'prune'])
       throw error
     }
-    return identity
+    return { ...identity, baseSha: baseHead }
+  }
+
+  /** Idempotently exclude the provisioning marker in the worktree's
+   * info/exclude so it never counts as dirt for the publish service's
+   * untracked-inclusive dirty check (f_c748dc6a). Runs on both ensure
+   * paths — fresh provisioning and the registered-worktree early return —
+   * so sandboxes provisioned before the write landed are healed the next
+   * time they are ensured. Errors propagate: a failed exclusion write
+   * aborts provisioning, mirroring fail-closed behavior. A successful
+   * `rev-parse --git-path` with empty stdout is a degenerate input — feeding
+   * it to `resolve` would target the workspace directory itself — so it fails
+   * loudly with the same `SandboxOperationError` — and the identical
+   * failure string — the fake workspace uses for the same case, keeping
+   * the two workspace-port implementations aligned. */
+  private async excludeProvisioningMarker(workspacePath: string): Promise<void> {
+    const markerName = '.autobuild-sandbox-provisioned'
+    const exclude = await this.gitOrThrow(workspacePath, [
+      'rev-parse',
+      '--git-path',
+      'info/exclude',
+    ])
+    if (exclude.stdout.trim() === '') {
+      throw new SandboxOperationError(
+        'provision',
+        `operator sandbox could not resolve info/exclude: ${exclude.stderr.trim() || `exit ${exclude.exitCode}`}`,
+      )
+    }
+    const excludePath = resolve(workspacePath, exclude.stdout.trim())
+    await mkdir(excludePath.slice(0, excludePath.lastIndexOf(sep)), { recursive: true })
+    const existing = await fsReadFile(excludePath, 'utf8').then(
+      (content) => content,
+      () => '',
+    )
+    const lines = existing.split('\n')
+    if (!lines.includes(markerName)) {
+      const prefix = existing === '' || existing.endsWith('\n') ? existing : `${existing}\n`
+      await fsWriteFile(excludePath, `${prefix}${markerName}\n`)
+    }
   }
 
   /** One `sh -c` command inside the sandbox worktree with the credential-free
@@ -650,9 +728,25 @@ export class GitWorktreeProvider implements WorkspaceProvider {
    * this cap covers the fire-and-forget case — commands that finish but are
    * never waited on — so the map (and its retained stdout/stderr strings)
    * stays bounded at ~cap entries' worth of output regardless of how many
-   * commands the process ever runs. Running entries are never evicted. */
+   * commands the process ever runs. Running entries are never evicted, and
+   * cap-evicted commands fail `wait` typed `not-found`: the legitimate
+   * not-found population under the cap is entries trimmed as the oldest
+   * finished, entries already consumed by a terminal wait, and ids from a
+   * restarted host. */
   private static readonly MAX_RETAINED_SANDBOX_COMMANDS = 50
 
+  /** Bound on how long the exit stamp waits for the stdout/stderr pipe
+   * readers to drain after the process exits. A normal child closes its
+   * pipes on exit and drains immediately; a grandchild that inherited the
+   * write end (e.g. `sleep 30 &`) keeps the pipe open long past the
+   * child's exit, so the grace bounds the stamp instead of stalling the
+   * delivered `exited` result until the grandchild dies. Because the race
+   * outcome varies (reader drain vs. grace), stamp landing times are also
+   * variable — which is why `evictFinishedBeyondCap` stops at
+   * exited-but-unstamped entries instead of treating them as running. */
+  private static readonly DEFAULT_SANDBOX_EXIT_DRAIN_GRACE_MS = 250
+  private readonly exitDrainGraceMs: number
+
   /** Detached children tracked in-process only; a restarted host reports a
    * recorded command as gone (`wait` fails typed `not-found`). Eviction uses
    * the same semantics: the first `wait` that observes `exited` consumes the
@@ -680,38 +774,75 @@ export class GitWorktreeProvider implements WorkspaceProvider {
 
   /** While the map exceeds the retention cap, delete the oldest finished
    * entries in insertion order (`Map` iterates in insertion order). Running
-   * entries are never evicted — the live procs themselves are the resource. */
+   * entries are never evicted — the live procs themselves are the resource.
+   * A pass also stops at the first tracked command that has exited but whose
+   * drain-gated exit stamp has not yet landed: such an entry is finished,
+   * not running, so the stamped entries older than it are unambiguously
+   * safe to evict (and are deleted by the walk reaching it), but nothing
+   * newer may be selected ahead of it — deleting a newer finished entry
+   * while an older one's stamp is still pending would make the victim
+   * choice depend on when stamps happen to land. When the pending entry is
+   * itself the oldest evictable entry, the pass deletes nothing and defers
+   * to its stamp. The stop always resolves — every exited entry is stamped
+   * within the drain grace, and every stamp runs this pass again — so the
+   * map settles to the cap with victims chosen as the oldest finished
+   * entries in insertion order, independent of stamp timing; while a stamp
+   * is pending the map may transiently hold the cap plus the entries that
+   * finished after that pending entry. */
   private evictFinishedBeyondCap(): void {
     if (this.sandboxChildren.size <= GitWorktreeProvider.MAX_RETAINED_SANDBOX_COMMANDS) return
     for (const [id, tracked] of this.sandboxChildren) {
-      if (this.sandboxChildren.size <= GitWorktreeProvider.MAX_RETAINED_SANDBOX_COMMANDS) break
+      if (this.sandboxChildren.size <= GitWorktreeProvider.MAX_RETAINED_SANDBOX_COMMANDS) return
+      // An exited-but-unstamped entry is finished, not running: stop here so
+      // no entry newer than it is evicted ahead of it.
+      if (tracked.exitCode === null && this.hasExitedProcess(tracked)) return
       if (tracked.exitCode !== null) this.sandboxChildren.delete(id)
     }
   }
 
+  /** Synchronous exit probe for a tracked child: `exitCode` covers a normal
+   * exit, `signalCode` a signal kill (where `exitCode` stays null). Both are
+   * synchronous on `Bun.Subprocess`, so an eviction pass reads real state at
+   * pass time rather than the drain-delayed stamp. */
+  private hasExitedProcess(tracked: { proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'> }): boolean {
+    return tracked.proc.exitCode !== null || tracked.proc.signalCode !== null
+  }
+
   private trackChildStreams(
     commandId: string,
     child: { proc: Bun.Subprocess<'ignore', 'pipe', 'pipe'> },
   ): void {
-    void (async () => {
-      const reader = child.proc.stdout.getReader()
-      const decoder = new TextDecoder()
-      for (;;) {
-        const { done, value } = await reader.read()
-        if (done) break
-        this.appendChildStream(commandId, 'stdout', decoder.decode(value, { stream: true }))
-      }
-    })()
-    void (async () => {
-      const reader = child.proc.stderr.getReader()
-      const decoder = new TextDecoder()
-      for (;;) {
-        const { done, value } = await reader.read()
-        if (done) break
-        this.appendChildStream(commandId, 'stderr', decoder.decode(value, { stream: true }))
-      }
-    })()
-    void child.proc.exited.then((code) => {
+    const drained = Promise.all([
+      (async () => {
+        const reader = child.proc.stdout.getReader()
+        const decoder = new TextDecoder()
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          this.appendChildStream(commandId, 'stdout', decoder.decode(value, { stream: true }))
+        }
+      })(),
+      (async () => {
+        const reader = child.proc.stderr.getReader()
+        const decoder = new TextDecoder()
+        for (;;) {
+          const { done, value } = await reader.read()
+          if (done) break
+          this.appendChildStream(commandId, 'stderr', decoder.decode(value, { stream: true }))
+        }
+      })(),
+    ]).catch(() => {})
+    void child.proc.exited.then(async (code) => {
+      // Stamp `exited` only once the pipe readers have drained what the
+      // child wrote, so a terminal `wait` never snapshots truncated output —
+      // under load the exit can otherwise be observed before the readers
+      // finish appending (seen as a flaky empty `stdout` in the retention
+      // test's full-suite run). The grace bounds the stamp when a grandchild
+      // keeps the write end open past the child's own exit.
+      await Promise.race([
+        drained,
+        new Promise((resolve) => setTimeout(resolve, this.exitDrainGraceMs)),
+      ])
       const tracked = this.sandboxChildren.get(commandId)
       if (tracked === undefined) return
       tracked.exitCode = code ?? -1
@@ -845,4 +976,93 @@ export class GitWorktreeProvider implements WorkspaceProvider {
     // A local worktree has no snapshot concept; release is always complete.
     return { snapshots: { outcome: 'confirmed' } }
   }
+
+  // ── Operator-sandbox publication (PR-only) ──────────────────
+  //
+  // The push and its probe run host-side in the sandbox worktree with the
+  // host's own forge configuration — exactly the transport a local build's
+  // finalize push uses (GitHubForge.pushBranch runs `git push` in the
+  // worktree); the only difference is an exact sha rather than HEAD, because
+  // publish accepts an explicit commit. No credential is ever handed to the
+  // sandbox itself: the sandbox performs no push, the provider does.
+
+  /** Same shape validation as the vercel publication adapter: an exact
+   * commit SHA and a canonical publication branch. */
+  private static assertPublicationInput(input: { sha: string; branch: string }): void {
+    if (!/^[0-9a-f]{40,64}$/i.test(input.sha) || !/^ab\/[a-z0-9][a-z0-9-]*$/.test(input.branch)) {
+      throw new Error('publication requires an exact commit SHA and canonical build branch')
+    }
+  }
+
+  /** Linked worktrees share the origin remote configuration with the main
+   * repository, so the probe runs from the worktree path itself. */
+  private async hasOriginRemote(cwd: string): Promise<boolean> {
+    const result = await this.git(cwd, ['remote'])
+    if (result.exitCode !== 0) return false
+    return result.stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .includes('origin')
+  }
+
+  private async sandboxIsPublished(input: {
+    ref?: string
+    sha: string
+    branch: string
+  }): Promise<boolean> {
+    GitWorktreeProvider.assertPublicationInput(input)
+    if (input.ref === undefined || input.ref === '') {
+      throw new Error('the git-worktree publication probe requires the workspace ref')
+    }
+    const ref = resolve(input.ref)
+    if (await this.hasOriginRemote(ref)) {
+      const result = await this.git(ref, ['ls-remote', 'origin', `refs/heads/${input.branch}`])
+      if (result.exitCode !== 0) {
+        throw new GitError(['-C', ref, 'ls-remote', 'origin', `refs/heads/${input.branch}`], result)
+      }
+      return result.stdout
+        .split('\n')
+        .some((line) => line.trim() === `${input.sha}\trefs/heads/${input.branch}`)
+    }
+    // No origin remote (local-git-forge deployments, where a local finalize
+    // performs no network push): compare the branch locally. Linked
+    // worktrees share all refs with the main repository, so no bookkeeping
+    // beyond the worktree path is needed.
+    const head = await this.resolveOptionalCommit(ref, `refs/heads/${input.branch}`)
+    return head === input.sha
+  }
+
+  private async publishSandbox(input: { ref: string; sha: string; branch: string }): Promise<void> {
+    GitWorktreeProvider.assertPublicationInput(input)
+    const ref = resolve(input.ref)
+    if (await this.hasOriginRemote(ref)) {
+      const args = [
+        '-C',
+        ref,
+        'push',
+        '--no-verify',
+        'origin',
+        `${input.sha}:refs/heads/${input.branch}`,
+      ]
+      const result = await this.exec(['git', ...args], {})
+      if (result.exitCode !== 0) throw new GitError(args, result)
+      return
+    }
+    // Local equivalent of the finalize push for deployments without an
+    // origin remote: a ref move guarded so it can never be a
+    // non-fast-forward. The service refuses the base branch before this
+    // seam is reached.
+    const existing = await this.resolveOptionalCommit(ref, `refs/heads/${input.branch}`)
+    if (existing !== null && existing !== input.sha) {
+      if (!(await this.isAncestor(ref, existing, input.sha))) {
+        throw new Error(
+          `refusing to move refs/heads/${input.branch}: its current tip ${existing} ` +
+            `is not an ancestor of ${input.sha}`,
+        )
+      }
+    }
+    const args = ['-C', ref, 'update-ref', `refs/heads/${input.branch}`, input.sha]
+    const result = await this.git(ref, ['update-ref', `refs/heads/${input.branch}`, input.sha])
+    if (result.exitCode !== 0) throw new GitError(args, result)
+  }
 }

package/packages/core/src/ports/workspace/github-origin.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure GitHub origin validation for the remote workspace provider. String
+ * logic only — no SDK, no git, no provider module — so capability declarations
+ * can reference it without pulling the provider implementation into import
+ * graphs that must stay light.
+ */
+import { basename } from 'node:path'
+
+export function validateVercelGithubOrigin(raw: string): {
+  url: string
+  host: string
+  path: string
+  directory: string
+} {
+  let url: URL
+  try {
+    url = new URL(raw)
+  } catch {
+    throw new Error('vercel-sandbox requires an HTTPS GitHub origin')
+  }
+  if (url.protocol !== 'https:' || url.hostname.toLowerCase() !== 'github.com') {
+    throw new Error('vercel-sandbox requires an HTTPS github.com origin')
+  }
+  url.username = ''
+  url.password = ''
+  url.search = ''
+  url.hash = ''
+  const path = url.pathname.replace(/\.git$/, '').replace(/^\//, '')
+  if (!/^[^/]+\/[^/]+$/.test(path)) throw new Error('GitHub origin must name owner/repository')
+  return {
+    url: `https://github.com/${path}.git`,
+    host: 'github.com',
+    path: `/${path}.git`,
+    directory: basename(path),
+  }
+}

package/packages/core/src/ports/workspace/operator-sandbox.ts

@@ -49,6 +49,11 @@ export interface SandboxEnvironmentIdentity {
   sessionId?: string
   /** Checkout root inside the environment; tool file paths are rooted here. */
   workspacePath: string
+  /** The base branch head the fresh provision selected, present only on the
+   * fresh-provision path (absent on reuse/resume, which never re-resolves
+   * it). The publication preconditions compare against it: a publish must
+   * be a descendant of the base head at provision or reset time. */
+  baseSha?: string
 }
 
 export interface SandboxCommandRequest {
@@ -87,7 +92,8 @@ export class SandboxOperationError extends Error {
       | 'not-found'
       | 'environment'
       | 'reset'
-      | 'release',
+      | 'release'
+      | 'publish',
     message: string,
     options?: { cause?: unknown },
   ) {