@defrex/autobuild 0.8.0 → 0.9.0

package/packages/core/src/operator/registry.ts

@@ -15,7 +15,8 @@
  * carried as base64 strings at the entry level (`builds.artifact`'s
  * `contentBase64` is the base64 of the exact artifact bytes), so a binding's
  * `JSON.stringify` can never silently corrupt bytes. The contract suite
- * (registry.contract.test.ts) asserts the round-trip for every tool.
+ * (packages/hosted-store-service/src/registry.contract.test.ts) asserts the
+ * round-trip for every tool.
  *
  * Risk classes live in `operator/annotations.ts` (checked in, enforced by the
  * contract suite). The registry itself enforces only what every binding needs
@@ -428,6 +429,25 @@ const sandboxWriteFileInput = z.strictObject({
 
 const sandboxResetInput = z.strictObject({ repo: repoField })
 
+const sandboxPublishInput = z.strictObject({
+  repo: repoField,
+  title: z.string().min(1).max(200).describe('Pull-request title, 1-200 characters.'),
+  body: z
+    .string()
+    .max(65_536)
+    .optional()
+    .describe(
+      'Optional pull-request body, at most 65,536 characters; an attribution block naming the operator and session is appended automatically.',
+    ),
+  commit: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Optional commit-ish to publish instead of the checkout HEAD; must resolve to a commit that is a descendant of the base head recorded at provision or reset time.',
+    ),
+})
+
 // ── The closed version-one table ─────────────────────────────────────────────
 
 function defineTool(
@@ -455,7 +475,7 @@ function defineTool(
 
 /** The closed version-one tool table. Adding a tool means adding an entry
  * here and a row in `operator/annotations.ts`; the contract suite proves the
- * two stay in lockstep. Sandbox and publish tools are later tickets. */
+ * two stay in lockstep. */
 export const TOOLS: readonly ToolEntry[] = [
   defineTool(
     'builds.list',
@@ -893,6 +913,22 @@ export const TOOLS: readonly ToolEntry[] = [
       return { ok: true as const }
     },
   ),
+  defineTool(
+    'sandbox.publish',
+    "Publish your operator sandbox's work as a pull request: push the checkout's current head commit (or an explicit commit) to your operator's dedicated branch and open or update a PR against the base branch. Refuses when the checkout has uncommitted changes (tracked or untracked; the sandbox's own provisioning marker is excluded), when the commit is not a descendant of the base head recorded at provision or reset time, or when the base branch head itself would be published. The sandbox itself never pushes and holds no credential — the push and PR creation are kernel plumbing; a publication is a durable repository-journal fact. PR only: the base branch is never pushed to.",
+    sandboxPublishInput,
+    '{branch, sha, pr: {number, url, headSha}}: the publication branch, the published commit, and the opened or updated pull request.',
+    async (raw, ctx) => {
+      const input = raw as z.infer<typeof sandboxPublishInput>
+      return sandboxOf(ctx).publish(attributed(ctx), {
+        repo: input.repo,
+        title: input.title,
+        ...(input.body !== undefined ? { body: input.body } : {}),
+        ...(input.commit !== undefined ? { commit: input.commit } : {}),
+        ...(ctx.via !== undefined ? { via: ctx.via } : {}),
+      })
+    },
+  ),
 ]
 
 // ── The registry constructor ─────────────────────────────────────────────────
@@ -900,8 +936,9 @@ export const TOOLS: readonly ToolEntry[] = [
 export interface RegistryOptions {
   store: BuildStore
   tickets?: OperatorTicketBackend
-  /** The operator-sandbox backend; when absent the six sandbox tools are
-   * neither advertised nor callable (the compatibility case). */
+  /** The operator-sandbox backend; when absent the sandbox tools are
+   * neither advertised nor callable (the compatibility case). When present
+   * but `canPublish` is false, only `sandbox.publish` is filtered. */
   sandbox?: OperatorSandboxService
   clock?: Clock
   /** Constrain every call to this repository identity (the `ab mcp --repo` flag). */
@@ -917,7 +954,8 @@ export interface OperatorToolRegistry {
 }
 
 /** Map a service error to the registry's operator-API-shaped failure body —
- * the same kind mapping as the catch block in operator/server.ts. */
+ * the same kind mapping as the catch block in the hosted package's
+ * operator-server.ts. */
 function mapDomainError(error: unknown): RegistryError {
   if (error instanceof RegistryError) return error
   if (error instanceof RouteRefusalError) {
@@ -976,15 +1014,22 @@ function mapDomainError(error: unknown): RegistryError {
 /** Bind the closed table to an opened store (and optional ticket and sandbox
  * backends). The returned registry is the in-process binding; every other
  * binding is generated from `entries`. Advertisement and dispatch share ONE
- * table: without a sandbox backend the six sandbox tools are filtered from
- * `entries` AND from `call()` dispatch, so a binding that cannot provision
- * sandboxes never advertises or serves them. */
+ * table: a filtered tool is neither advertised nor served. */
 export function buildRegistry(options: RegistryOptions): OperatorToolRegistry {
   const sandboxToolNames = new Set(
     Object.keys(OPERATOR_TOOL_ANNOTATIONS).filter((name) => name.startsWith('sandbox.')),
   )
-  const table =
-    options.sandbox === undefined ? TOOLS.filter((tool) => !sandboxToolNames.has(tool.name)) : TOOLS
+  // Without a sandbox backend every sandbox tool is filtered; with a backend
+  // that cannot publish (no forge or no provider publication capability),
+  // only `sandbox.publish` is filtered. Filtered tools are absent from
+  // `entries` AND from `call()` dispatch.
+  const filtered = new Set<string>()
+  if (options.sandbox === undefined) {
+    for (const name of sandboxToolNames) filtered.add(name)
+  } else if (options.sandbox.canPublish === false) {
+    filtered.add('sandbox.publish')
+  }
+  const table = filtered.size === 0 ? TOOLS : TOOLS.filter((tool) => !filtered.has(tool.name))
   return {
     entries: table,
     async call(name, input, partial = {}) {

package/packages/core/src/operator/requests.ts

@@ -4,9 +4,10 @@
  *
  * This module is registry-owned on purpose: the operator API routes were
  * declared out of scope for the registry ticket, so the parity between a
- * tool and its route is *proven* by the contract suite (registry.contract
- * .test.ts) rather than obtained by extraction. Every refusal text here is
- * load-bearing — it must stay byte-identical to `operator/server.ts` so the
+ * tool and its route is *proven* by the contract suite
+ * (packages/hosted-store-service/src/registry.contract.test.ts) rather than
+ * obtained by extraction. Every refusal text here is load-bearing — it must
+ * stay byte-identical to the hosted package's `operator-server.ts` so the
  * suite's full-body comparisons hold.
  */
 import { reduceBuild } from '../kernel/reducer'
@@ -34,7 +35,8 @@ export class RouteRefusalError extends Error {
   }
 }
 
-/** `requireRouteBuild` (operator/server.ts): 404 unless the slug exists and
+/** `requireRouteBuild` (the hosted package's operator-server.ts): 404 unless
+ * the slug exists and
  * belongs to the named repository. */
 export async function requireRouteBuild(
   store: BuildStore,
@@ -61,7 +63,7 @@ export function parseArtifactRevision(raw: string): number {
 /**
  * The route's control-request prechecks: build existence/repo, then the
  * pending-state checks for pause and cancel-pause. Byte-identical to the
- * `POST …/control` branch in operator/server.ts.
+ * `POST …/control` branch in the hosted package's operator-server.ts.
  */
 export async function controlPrechecks(
   store: BuildStore,
@@ -97,7 +99,8 @@ export async function controlPrechecks(
 
 /**
  * The route's answer request → `BuildControlAction` translation, byte-identical
- * to the `POST …/answer` branch in operator/server.ts. The ticket-origin body
+ * to the `POST …/answer` branch in the hosted package's operator-server.ts.
+ * The ticket-origin body
  * reader travels separately, exactly as the route passes `readTicketBody`.
  */
 export function answerAction(request: OperatorAnswerRequest): {

package/packages/core/src/operator/sandbox-host.ts

@@ -0,0 +1,140 @@
+/**
+ * The checkout-less operator-sandbox composition helper (AUT-584): builds the
+ * same `createOperatorSandboxService` backend `ab mcp` builds from a checkout,
+ * but from a deposited effective config plus injected seams — for hosted
+ * serving processes that hold no host checkout and never touch host git.
+ *
+ * The module is a SEPARATE subpath (`@defrex/autobuild/operator-sandbox-host`)
+ * on purpose: it pulls the workspace-provider/forge construction closure, and
+ * existing `./operator` consumers (the hosted operator server among them) must
+ * not grow that closure. The hosted store service imports only this subpath.
+ *
+ * Containment contract: every construction failure THROWS. The callers (the
+ * hosted store service's runner factory and the dispatcher tick) contain it —
+ * a broken or unsupported config degrades the sandbox tools of one binding,
+ * never the orchestrator itself.
+ */
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { Config } from '../config/schema'
+import type { Forge } from '../ports/types'
+import { createForge } from '../ports/forge/create'
+import { GitHubApiError } from '../ports/forge/github-transport'
+import { createWorkspaceProvider } from '../ports/workspace/create'
+import { createPluginRegistry } from '../plugins/registry'
+import type { BuildStore, Clock } from '../store/types'
+import { createOperatorSandboxService, type OperatorSandboxService } from './sandbox'
+
+export interface HostedOperatorSandboxOptions {
+  store: BuildStore
+  /** The repository identity — already the normalized HTTPS origin the
+   * sandbox providers parse with `cleanGithubOrigin`; passed through as the
+   * provider's `origin` seam so no host git is ever probed. */
+  repo: string
+  /** The repository's effective config (the deposited
+   * `dispatcher-effective-config` artifact, or the checkout's parsed config).
+   * `[orchestrator].enabled` is the CALLER's gate; this helper composes the
+   * backend for any config handed to it. */
+  config: Config
+  /** The serving process's environment. The Vercel SDK credential must be
+   * reachable here for a `vercel-sandbox` workspace (`VERCEL_OIDC_TOKEN`, or
+   * the durable `VERCEL_TOKEN`/`VERCEL_TEAM_ID`/`VERCEL_PROJECT_ID` triple);
+   * a hosted caller merges the request's `x-vercel-oidc-token` under
+   * `VERCEL_OIDC_TOKEN` before calling, with an explicit env token keeping
+   * precedence. */
+  env: Record<string, string | undefined>
+  /** The provider's store authority: an HTTPS store ref reachable from the
+   * sandbox plus a repo-scoped token. The guest environment is always built
+   * from an empty record plus the configured forwarded names, so neither
+   * value ever reaches the sandbox guest. */
+  storeRef: string
+  storeToken: string
+  /** Scratch root for the composition's filesystem seams (worktree root,
+   * repo root, sandbox root). Default: a fresh `mkdtemp` under the OS temp
+   * directory. The builtin providers only touch these paths through host-git
+   * or local-scratch paths the injected seams bypass; a plugin-provider config
+   * fails construction before any path use. */
+  scratchRoot?: string
+  clock?: Clock
+  /** Test seam: an already-constructed forge. Production passes nothing and
+   * the configured forge is built here. The forge is REQUIRED either way —
+   * unlike `ab mcp`, which degrades to `canPublish: false` because its
+   * provider can fall back to host git, a hosted host has no checkout, so a
+   * backend without a forge cannot resolve base heads at all. */
+  forge?: Forge
+}
+
+/** Map a forge onto the provider's checkout-less `remoteBranchHead` seam:
+ * a `GitHubApiError` with status 404 means the branch does not exist and
+ * reads as `undefined`; every other error is rethrown (a transient GitHub
+ * failure must never masquerade as an absent branch and refuse provision).
+ * The forge must expose `remoteBranchSha`; the caller enforces that before
+ * calling with a diagnostic that names the forge. */
+export function remoteBranchHeadFromForge(
+  forge: Forge,
+): (branch: string) => Promise<string | undefined> {
+  const remoteBranchSha = forge.remoteBranchSha
+  if (remoteBranchSha === undefined) {
+    throw new Error('forge does not resolve remote branch heads')
+  }
+  return async (branch: string): Promise<string | undefined> => {
+    try {
+      return await remoteBranchSha.call(forge, branch)
+    } catch (error) {
+      if (error instanceof GitHubApiError && error.status === 404) return undefined
+      throw error
+    }
+  }
+}
+
+/** Build the hosted operator-sandbox backend from the effective config and
+ * injected seams. Throws on every construction failure (unknown provider or
+ * forge, missing Vercel SDK credential, forbidden forwarded env name,
+ * capability-less provider, forge without `remoteBranchSha`) — the caller
+ * contains and degrades to serving without the sandbox tools. */
+export async function createHostedOperatorSandboxService(
+  options: HostedOperatorSandboxOptions,
+): Promise<OperatorSandboxService> {
+  const scratch = options.scratchRoot ?? (await mkdtemp(join(tmpdir(), 'autobuild-sandbox-host-')))
+  const forge =
+    options.forge ??
+    (await createForge({
+      name: options.config.forge,
+      registry: createPluginRegistry(),
+      env: options.env,
+      repoRoot: scratch,
+      repository: options.repo,
+    }))
+  if (forge.remoteBranchSha === undefined) {
+    throw new Error(
+      `the configured forge "${options.config.forge}" does not resolve remote branch heads; ` +
+        'the hosted sandbox backend has no checkout to resolve base heads against',
+    )
+  }
+  // Builtin-only registry: a plugin-provider config fails construction here
+  // (unknown provider in the empty registry) and the caller contains it.
+  const provider = await createWorkspaceProvider(options.config.workspace, {
+    registry: createPluginRegistry(),
+    worktreeRoot: scratch,
+    repoRoot: scratch,
+    env: options.env,
+    storeRef: options.storeRef,
+    storeToken: options.storeToken,
+    origin: async () => options.repo,
+    remoteBranchHead: remoteBranchHeadFromForge(forge),
+    sandboxSetupCommand: options.config.commands.setup,
+    sandboxRoot: join(scratch, 'orchestrator-sandboxes'),
+    sandboxEnvironmentVariables: options.config.orchestrator.sandbox.environmentVariables,
+    orchestratorSandboxEnabled: true,
+  })
+  return createOperatorSandboxService({
+    store: options.store,
+    repo: options.repo,
+    provider,
+    sandbox: options.config.orchestrator.sandbox,
+    baseBranch: options.config.baseBranch,
+    forge,
+    ...(options.clock !== undefined ? { clock: options.clock } : {}),
+  })
+}

package/packages/core/src/operator/sandbox.ts

@@ -10,7 +10,11 @@
  * environments from empty records); redaction here keeps credential VALUES
  * out of typed error messages that travel to tool callers.
  */
+import { createHash } from 'node:crypto'
 import { humanActor } from '../events/envelope'
+import type { Via } from '../events/envelope'
+import type { RepositoryEvent } from '../events/repository'
+import type { Forge } from '../ports/types'
 import {
   SANDBOX_FORBIDDEN_ENV,
   SandboxOperationError,
@@ -19,6 +23,7 @@ import {
   type SandboxWaitResult,
 } from '../ports/workspace/operator-sandbox'
 import type { WorkspaceProvider } from '../ports/types'
+import { readRepoEventsIfRecorded } from '../processes/harvest'
 import { sandboxStates } from '../processes/sandbox-state'
 import { systemClock, type BuildStore, type Clock } from '../store/types'
 
@@ -107,12 +112,41 @@ function describeError(error: unknown): string {
   return redactSandboxMessage(error instanceof Error ? error.message : String(error))
 }
 
+/** The canonical publication branch grammar every provider adapter enforces. */
+const PUBLICATION_BRANCH_PATTERN = /^ab\/[a-z0-9][a-z0-9-]*$/
+
+/** Deterministic PR branch name for one operator × repository:
+ * `ab/orch-<operator-slug>-<hash8>` where hash8 is the first 8 hex chars of
+ * sha256(`<repo>\0<operator>`) and the slug is the operator lowercased with
+ * non-`[a-z0-9]` runs collapsed to `-` and trimmed. One operator always maps
+ * to one branch per repository, so a later publish updates the same PR's
+ * head. An identity with no `[a-z0-9]` characters yields `ab/orch--<hash8>`,
+ * which still matches the canonical grammar — no fallback token. */
+export function sandboxPublicationBranch(repo: string, operator: string): string {
+  const slug = operator
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  const hash8 = createHash('sha256').update(`${repo}\0${operator}`).digest('hex').slice(0, 8)
+  const branch = `ab/orch-${slug}-${hash8}`
+  if (!PUBLICATION_BRANCH_PATTERN.test(branch)) {
+    throw new SandboxOperationError(
+      'publish',
+      `derived publication branch ${JSON.stringify(branch)} is not a canonical branch name`,
+    )
+  }
+  return branch
+}
+
 export interface OperatorSandboxConfig {
   idleMinutes: number
   environmentVariables: readonly string[]
 }
 
 export interface OperatorSandboxService {
+  /** True when both a forge and the provider's sandbox publication
+   * capability are present, i.e. `publish` is callable. */
+  readonly canPublish: boolean
   exec(
     identity: string,
     input: { repo: string; command: string; cwd?: string; timeoutSeconds?: number },
@@ -133,6 +167,20 @@ export interface OperatorSandboxService {
   /** Destructive: journal `reset`, full teardown + snapshot purge, then a
    * fresh provision from the CURRENT base head. */
   reset(identity: string, input: { repo: string }): Promise<void>
+  /** PR-only publication (AUT-343): push the sandbox checkout's head (or an
+   * explicit commit) to a deterministic operator branch and open or update
+   * the PR against the base branch. The base branch itself is never pushed
+   * to; the sandbox performs no push and receives no credential. */
+  publish(
+    identity: string,
+    input: {
+      repo: string
+      title: string
+      body?: string
+      commit?: string
+      via?: Via
+    },
+  ): Promise<{ branch: string; sha: string; pr: { number: number; url: string; headSha: string } }>
   /** Full teardown + snapshot purge of the operator's environment, without
    * provisioning. A no-op when the journal shows no environment. Used by
    * `reset` and the session-archive hook. */
@@ -148,6 +196,9 @@ export interface OperatorSandboxServiceOptions {
    * branch's current head. A hot baseBranch reload is picked up when the
    * `ab mcp` process restarts. */
   baseBranch: string
+  /** The forge used to open or update the PR. Absent = publication is
+   * unavailable and the service reports `canPublish: false`. */
+  forge?: Forge
   clock?: Clock
   capability?: WorkspaceProvider['orchestratorSandbox']
 }
@@ -165,6 +216,7 @@ export async function createOperatorSandboxService(
     )
   }
   const clock = options.clock ?? systemClock
+  const canPublish = options.forge !== undefined && provider.sandboxPublication !== undefined
   await store.ensureRepo(repo)
 
   /** Per-environment serialization: one in-process promise chain keyed by
@@ -188,7 +240,9 @@ export async function createOperatorSandboxService(
       | 'orchestrator.sandbox.resumed'
       | 'orchestrator.sandbox.activity'
       | 'orchestrator.sandbox.released'
-      | 'orchestrator.sandbox.reset',
+      | 'orchestrator.sandbox.reset'
+      | 'orchestrator.sandbox.published'
+      | 'orchestrator.sandbox.publish-failed',
     payload: Record<string, unknown>,
   ): Promise<void> => {
     await store.appendRepo(repo, {
@@ -198,13 +252,8 @@ export async function createOperatorSandboxService(
     })
   }
 
-  const journalEvents = async (): Promise<Awaited<ReturnType<typeof store.getRepoEvents>>> => {
-    if ((await store.getRepo(repo)) === null) return []
-    return store.getRepoEvents(repo)
-  }
-
   /** The operator's journal state, or undefined when no environment exists. */
-  const operatorState = (identity: string, events: Awaited<ReturnType<typeof journalEvents>>) =>
+  const operatorState = (identity: string, events: RepositoryEvent[]) =>
     sandboxStates(events)
       .filter((state) => state.operator === identity && state.state !== 'released')
       .at(-1)
@@ -227,6 +276,7 @@ export async function createOperatorSandboxService(
         provider: resolved.provider,
         ...(resolved.sessionId !== undefined ? { sessionId: resolved.sessionId } : {}),
         workspacePath: resolved.workspacePath,
+        ...(resolved.baseSha !== undefined ? { baseSha: resolved.baseSha } : {}),
       })
     } else if (state.state === 'stopped') {
       await append(identity, 'orchestrator.sandbox.resumed', {
@@ -255,10 +305,13 @@ export async function createOperatorSandboxService(
     })
   }
 
-  const requireRepo = (inputRepo: string | undefined): void => {
+  const requireRepo = (
+    inputRepo: string | undefined,
+    stage: SandboxOperationError['stage'] = 'exec',
+  ): void => {
     if (inputRepo !== undefined && inputRepo !== repo) {
       throw new SandboxOperationError(
-        'exec',
+        stage,
         `sandbox tools serve repository "${repo}"; refusing "${inputRepo}"`,
       )
     }
@@ -266,7 +319,7 @@ export async function createOperatorSandboxService(
 
   const run = async <T>(
     identity: string,
-    stage: 'provision' | 'resume' | 'exec',
+    stage: 'provision' | 'resume' | 'exec' | 'publish',
     operation: (
       resolved: SandboxEnvironmentIdentity,
       state: ReturnType<typeof operatorState>,
@@ -274,7 +327,7 @@ export async function createOperatorSandboxService(
   ): Promise<T> => {
     const key = `${repo}\0${identity}`
     return serialize(key, async () => {
-      const events = await journalEvents()
+      const events = await readRepoEventsIfRecorded(store, repo)
       const state = operatorState(identity, events)
       const resolved = await ensureWithFacts(identity, state).catch((error: unknown) => {
         if (error instanceof SandboxOperationError) throw error
@@ -284,7 +337,7 @@ export async function createOperatorSandboxService(
           { cause: error },
         )
       })
-      const freshEvents = await journalEvents()
+      const freshEvents = await readRepoEventsIfRecorded(store, repo)
       const freshState = operatorState(identity, freshEvents)
       try {
         const result = await operation(resolved, freshState)
@@ -298,6 +351,10 @@ export async function createOperatorSandboxService(
   }
 
   return {
+    /** True only when both a forge and a sandbox publication capability are
+     * wired; the registry filters `sandbox.publish` when false. */
+    canPublish,
+
     async exec(identity, input) {
       requireRepo(input.repo)
       const timeoutSeconds = validateBoundedInt(
@@ -393,11 +450,187 @@ export async function createOperatorSandboxService(
       })
     },
 
+    async publish(
+      identity,
+      input: {
+        repo: string
+        title: string
+        body?: string
+        commit?: string
+        via?: Via
+      },
+    ) {
+      requireRepo(input.repo, 'publish')
+      const title = input.title.trim()
+      if (title === '') {
+        throw new SandboxOperationError('publish', 'title must not be empty')
+      }
+      if (title.length > 200) {
+        throw new SandboxOperationError('publish', 'title must be at most 200 characters')
+      }
+      if (input.body !== undefined && input.body.length > 65_536) {
+        throw new SandboxOperationError('publish', 'body must be at most 65,536 characters')
+      }
+      if (input.commit !== undefined && input.commit.trim() === '') {
+        throw new SandboxOperationError('publish', 'commit must be a nonempty commit-ish')
+      }
+      if (!canPublish) {
+        throw new SandboxOperationError(
+          'publish',
+          'publication is unavailable: no forge or no sandbox publication capability is wired',
+        )
+      }
+      const forge = options.forge!
+      const publication = provider.sandboxPublication!
+      // run() already serializes per environment; wrapping it in another
+      // serialize on the same key would deadlock the chain.
+      return run(identity, 'publish', async (resolved, freshState) => {
+        let stage: 'checks' | 'push' | 'pr' = 'checks'
+        try {
+          // 1. Resolve the commit inside the sandbox checkout.
+          const commitExpr = input.commit?.trim() || 'HEAD'
+          const resolveResult = await capability.exec(resolved, {
+            // --quiet makes an unresolvable commit-ish exit 1 (the documented
+            // refusal signal below); without it git exits 128 and the refusal
+            // branch is unreachable.
+            command: `git rev-parse --verify --quiet ${commitExpr}^{commit}`,
+            timeoutSeconds: 30,
+          })
+          if (resolveResult.exitCode === 1) {
+            throw new SandboxOperationError(
+              'publish',
+              `commit ${JSON.stringify(commitExpr)} does not resolve to a commit in the sandbox checkout`,
+            )
+          }
+          if (resolveResult.exitCode !== 0) {
+            throw new Error(
+              `git rev-parse --verify ${commitExpr}^{commit} exited ${resolveResult.exitCode}: ${resolveResult.stderr.trim() || resolveResult.stdout.trim() || '(no output)'}`,
+            )
+          }
+          const sha = resolveResult.stdout.trim()
+          // 2. Refuse a dirty checkout: staged or unstaged changes to
+          // tracked files, and untracked files — a new file the operator
+          // never committed would otherwise be silently left out of the
+          // published commit. The providers exclude their own
+          // provisioning marker in the checkout's info/exclude, so the
+          // marker itself never counts as dirt (f_c748dc6a).
+          const statusResult = await capability.exec(resolved, {
+            command: 'git status --porcelain',
+            timeoutSeconds: 30,
+          })
+          if (statusResult.exitCode !== 0) {
+            throw new Error(
+              `git status --porcelain exited ${statusResult.exitCode}: ${statusResult.stderr.trim() || statusResult.stdout.trim() || '(no output)'}`,
+            )
+          }
+          if (statusResult.stdout.trim() !== '') {
+            throw new SandboxOperationError(
+              'publish',
+              'the sandbox checkout has uncommitted changes; commit or discard them before publishing',
+            )
+          }
+          // 3. Refuse a commit that is not a descendant of the base head
+          // at provision or reset time.
+          const baseSha = freshState?.baseSha
+          if (baseSha === undefined) {
+            throw new SandboxOperationError(
+              'publish',
+              'this environment has no recorded base head; run sandbox.reset to re-provision before publishing',
+            )
+          }
+          if (sha === baseSha) {
+            throw new SandboxOperationError(
+              'publish',
+              'the checkout head is the base commit itself; there is nothing to publish',
+            )
+          }
+          const ancestorResult = await capability.exec(resolved, {
+            command: `git merge-base --is-ancestor ${baseSha} ${sha}`,
+            timeoutSeconds: 30,
+          })
+          if (ancestorResult.exitCode === 1) {
+            throw new SandboxOperationError(
+              'publish',
+              `the commit is not a descendant of the base head ${baseSha} recorded at provision time; rebase onto the current base or run sandbox.reset`,
+            )
+          }
+          if (ancestorResult.exitCode !== 0) {
+            throw new Error(
+              `git merge-base --is-ancestor ${baseSha} ${sha} exited ${ancestorResult.exitCode}: ${ancestorResult.stderr.trim() || ancestorResult.stdout.trim() || '(no output)'}`,
+            )
+          }
+          // 4. Deterministic branch; the helper self-validates the grammar.
+          const branch = sandboxPublicationBranch(repo, identity)
+          if (branch === options.baseBranch) {
+            throw new SandboxOperationError(
+              'publish',
+              'the derived publication branch collides with the base branch; refusing',
+            )
+          }
+          // 5. Push-before-fact crash safety, mirroring
+          // publication-settlement: a crashed prior attempt is owed its
+          // completion, not a re-push.
+          const alreadyPublished =
+            (await publication.isPublished?.({
+              ref: resolved.environmentId,
+              sha,
+              branch,
+            })) === true
+          stage = 'push'
+          if (!alreadyPublished) {
+            await publication.publish({ ref: resolved.environmentId, sha, branch })
+          }
+          // 6. Open (or adopt) the PR against the base branch; a later
+          // publish to the same branch moves the same PR's head.
+          stage = 'pr'
+          const session =
+            input.via !== undefined && input.via.kind === 'session' ? input.via.id : undefined
+          const body =
+            (input.body ?? '') +
+            (input.body !== undefined && input.body !== '' ? '\n\n' : '') +
+            `Published from an Autobuild operator sandbox by ${identity}` +
+            (session !== undefined ? ` via orchestrator session ${session}` : '') +
+            ' — agent-authored, not a pipeline build.'
+          const pr = await forge.openPr({
+            workspacePath: resolved.workspacePath,
+            head: branch,
+            base: options.baseBranch,
+            title,
+            body,
+          })
+          // 7. The publication is a repository-journal fact.
+          await append(identity, 'orchestrator.sandbox.published', {
+            operator: identity,
+            environmentId: resolved.environmentId,
+            branch,
+            sha,
+            ...(session !== undefined ? { session } : {}),
+            pr: { number: pr.number, url: pr.url, headSha: pr.headSha },
+          })
+          return { branch, sha, pr: { number: pr.number, url: pr.url, headSha: pr.headSha } }
+        } catch (error) {
+          // 8. Every refusal or failure at steps 1-6 is a journal fact
+          // naming the stage, with credential values redacted from the
+          // message.
+          const message = describeError(error)
+          await append(identity, 'orchestrator.sandbox.publish-failed', {
+            operator: identity,
+            environmentId: resolved.environmentId,
+            stage,
+            message,
+          }).catch(() => {})
+          throw new SandboxOperationError('publish', message, {
+            cause: error instanceof SandboxOperationError ? error.cause : error,
+          })
+        }
+      })
+    },
+
     async reset(identity, input) {
       requireRepo(input.repo)
       const key = `${repo}\0${identity}`
       await serialize(key, async () => {
-        const events = await journalEvents()
+        const events = await readRepoEventsIfRecorded(store, repo)
         const state = operatorState(identity, events)
         const resolved = await capability.describe({ repo, operator: identity })
         await append(identity, 'orchestrator.sandbox.reset', {
@@ -429,7 +662,7 @@ export async function createOperatorSandboxService(
       requireRepo(input.repo)
       const key = `${repo}\0${identity}`
       await serialize(key, async () => {
-        const events = await journalEvents()
+        const events = await readRepoEventsIfRecorded(store, repo)
         const state = operatorState(identity, events)
         // No environment ever provisioned: a no-op, with no fact and no
         // provider traffic beyond the pure describe.