@defrex/autobuild 0.8.0 → 0.10.0

package/packages/core/src/config/schema.ts

@@ -14,9 +14,16 @@
 import { z } from 'zod'
 import { prImageHostSchema } from '../ontology'
 import { SANDBOX_FORBIDDEN_ENV } from '../ports/workspace/operator-sandbox'
+import {
+  runtimeProvisioningMap,
+  runtimeProvisioningMissingMessage,
+  sandboxForbiddenEnvMessage,
+} from '../ports/workspace/provider-capabilities'
 import { defineEntry, openMap, ownEntries, parseEntry } from '../open-map'
 import { forwardIssues } from '../zod-issues'
-import { displayName, effectiveRuntimeReferences, tomlKey } from './roles'
+import { compileEventGlobs } from '../events/globs'
+import { REPOSITORY_ATTENTION_EVENTS } from '../events/repository'
+import { effectiveRuntimeReferences } from './roles'
 
 // ── Open maps ────────────────────────────────────────────────────────────────
 
@@ -242,6 +249,70 @@ export const workspaceSchema = z.strictObject({
 })
 export type WorkspaceConfig = z.infer<typeof workspaceSchema>
 
+/**
+ * The parse-time subset of workspace-provider behavior a builtin declares
+ * (AUT-516). This table lives in `config/schema.ts` because the
+ * `[workspace.config]` validation runs inside `configSchema`'s
+ * `superRefine` — at parse time, long before plugins load, in processes that
+ * never touch the registry. The full capability objects (including the
+ * registry-seam declarations) are assembled in
+ * `ports/workspace/builtin-capabilities.ts`, which takes this subset from
+ * here — a parity now enforced by
+ * `ports/workspace/builtin-capabilities.test.ts` (AUT-573), so a builtin
+ * added to only one table fails tests rather than compiling silently. The
+ * construction-site refusal text differs by design from the
+ * parse-site one, so it is NOT copied from this table.
+ */
+export interface WorkspaceProviderConfigDeclaration {
+  /** Strict schema applied to `[workspace.config]`. A builtin declaration
+   * carries EXACTLY ONE of `configSchema` / `configRefusalMessage`: when the
+   * schema is absent, the declaration must carry `configRefusalMessage` for
+   * nonempty provider config to be refused (the neither-key side is pinned by
+   * the AUT-565 test in config.test.ts), and carrying BOTH is forbidden —
+   * `configSchema`'s superRefine checks `configRefusalMessage` first, so the
+   * refusal branch would win and the schema would silently never apply (the
+   * both-keys side is pinned by its sibling test). Providers absent from
+   * `BUILTIN_WORKSPACE_PROVIDER_CONFIG` are plugin-owned pass-throughs and
+   * are never refused here. */
+  configSchema?: z.ZodType
+  /** Parse-site refusal text for a provider that rejects `[workspace.config]`
+   * outright. This is the sole parse-site refusal key: a declaration without
+   * it never refuses `[workspace.config]` here, with or without a schema.
+   * Distinct from the capability's construction-site `configRefusal`. */
+  configRefusalMessage?: string
+  /** Referenced runtimes must have `[workspace.config.runtimeProvisioning]`
+   * entries (checked only once roles, verify, and finalize are all present). */
+  requireRuntimeProvisioning?: boolean
+  /** Names added to the operator-sandbox forbidden-forwarding set beyond
+   * `SANDBOX_FORBIDDEN_ENV`. */
+  sandboxForbiddenEnv?: readonly string[]
+}
+
+/** Parse-time behavior of every builtin workspace provider, keyed by the
+ * provider name an operator writes in `[workspace].provider`. No provider
+ * name appears in any validation branch — every check reads this table. */
+export const BUILTIN_WORKSPACE_PROVIDER_CONFIG: ReadonlyMap<
+  string,
+  WorkspaceProviderConfigDeclaration
+> = new Map([
+  [
+    'git-worktree',
+    {
+      configRefusalMessage:
+        '[workspace.config] is not supported by the builtin "git-worktree" provider — remove it or select a plugin workspace provider',
+    },
+  ],
+  [
+    'vercel-sandbox',
+    {
+      configSchema: vercelSandboxConfigSchema,
+      requireRuntimeProvisioning: true,
+      // Its credentials are already in SANDBOX_FORBIDDEN_ENV.
+      sandboxForbiddenEnv: [],
+    },
+  ],
+])
+
 // ── [commands] ───────────────────────────────────────────────────────────────
 //
 // Open map of deterministic verbs the kernel may run. `setup`, `lint`,
@@ -485,6 +556,20 @@ export const ticketsSchema = z.strictObject({
       (s) => s.trim().length > 0,
       '[tickets].readyState must not be blank — name the one workflow state a ticket must sit in to be dispatched (e.g. "ready").',
     ),
+  /**
+   * Narrows readiness to tickets assigned to one Linear user — a third
+   * conjunctive gate beside readyState and readyLabels. `"me"` is the owner of
+   * the dispatcher's LINEAR_API_KEY; an email names a specific user (for a
+   * shared or bot key). Unassigned tickets are never ready while it is set.
+   * Linear only; absent leaves readiness unchanged.
+   */
+  readyAssignee: z
+    .string()
+    .refine(
+      (s) => s === 'me' || (s === s.trim() && /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s)),
+      '[tickets].readyAssignee must be "me" (the owner of the API key) or a user email address (e.g. "person@example.com")',
+    )
+    .optional(),
   /** Backend team key (e.g. "ENG") — required for linear and hosted. */
   teamKey: z.string().min(1).optional(),
   /** Workflow state claim() moves an issue to (§12); Linear and hosted. */
@@ -534,9 +619,107 @@ export const orchestratorSandboxSchema = z.strictObject({
 })
 export type OrchestratorSandboxConfig = z.infer<typeof orchestratorSandboxSchema>
 
+/** The turn runner lives inside the hosted operator route and the dispatcher
+ * tick, both of which run under a Vercel function duration limit the config's
+ * invocation budget can never exceed: a value above this is clamped (not
+ * rejected) at parse time so a mis-set budget degrades to the limit instead of
+ * failing every deploy. The operator route pins `maxDuration` to this same
+ * constant, so one number is cited by the config, the route, and the docs. */
+export const ORCHESTRATOR_ROUTE_LIMIT_SECONDS = 300
+
+/** Turn budget floor for the dispatcher tick's orchestrator step: when less
+ * than this many seconds of tick budget remain, the step skips the pass
+ * entirely (suspension state is durable, so skipping is always safe). */
+export const ORCHESTRATOR_MIN_TURN_SECONDS = 30
+
+/** The turn approval entries' shape: a registry tool name, optionally
+ * qualified by the discriminator field's accepted value (`tool:qualifier`).
+ * Validation is syntactic only — an entry naming an absent or unknown tool is
+ * inert by design (documented in docs/configuration.md), because the list
+ * is meant to stay stable while the registry grows — e.g. `sandbox.publish`
+ * was named here before its ticket landed, and stays inert in bindings
+ * where no sandbox backend is bound (the hosted default). */
+const ORCHESTRATOR_APPROVAL_ENTRY = /^[a-z][a-z0-9_.]*(:[a-z0-9_-]+)?$/
+
+/** The attention set a new session's wake settings inherit when the
+ * repository does not override `wake`: the build events an operator or agent
+ * must wake up for (the same set `ab watch` filters on by default) plus the
+ * repository-journal attention events (the same set `ab watch --repository`
+ * follows), spelled as literal globs. Both halves of the attention set can
+ * wake a session. */
+export const defaultOrchestratorWakeGlobs: readonly string[] = [
+  'escalation.raised',
+  'phase.failed',
+  'infrastructure.failed',
+  'runner.setup-failed',
+  'dispatch.failed',
+  'publication.lost',
+  'finalize.completed',
+  'pr.conflicted',
+  'pr.merged',
+  'pr.closed',
+  'build.completed',
+  'build.aborted',
+  ...REPOSITORY_ATTENTION_EVENTS,
+]
+
+/** The registry tools a turn asks its operator about before executing.
+ * The maintainer sets this to `[]` for autonomous operation. */
+export const defaultOrchestratorApprovals: readonly string[] = [
+  'builds.control:abort',
+  'builds.control:discard',
+  'builds.answer:revise-spec',
+  'sandbox.publish',
+  'tickets.move:ready',
+]
+
+/** A session's effective wake globs: the configured `wake` when declared
+ * (an explicit `[]` means never wake), else the default attention set. Kept
+ * as a resolver rather than a schema default so `wake`'s absence (inherit)
+ * and emptiness (never wake) stay distinct. */
+export function orchestratorWakeGlobs(config: OrchestratorConfig): string[] {
+  return [...(config.wake ?? defaultOrchestratorWakeGlobs)]
+}
+
 export const orchestratorSchema = z.strictObject({
   enabled: z.boolean().default(false),
   sandbox: orchestratorSandboxSchema.prefault({}),
+  /** Provider-qualified model string for the turn runner, in the same
+   * vocabulary as `[roles]` model strings (nonblank; a leading
+   * `vercel-ai-gateway/` prefix is stripped before the gateway provider).
+   * Resolved through the deployment's gateway credential. Required when
+   * `enabled = true` (cross-validated below); the runner never starts a turn
+   * on a repository whose config omits it. */
+  model: z.string().min(1).optional(),
+  /** Wall-clock budget for one turn invocation, in seconds. Clamped — not
+   * rejected — to ORCHESTRATOR_ROUTE_LIMIT_SECONDS, the hosted function
+   * duration the runner runs under. */
+  invocationBudgetSeconds: z
+    .number()
+    .int()
+    .positive()
+    .default(240)
+    .transform((value) => Math.min(value, ORCHESTRATOR_ROUTE_LIMIT_SECONDS)),
+  /** Registry tool names (optionally `tool:qualifier`) whose calls suspend a
+   * turn until the operator answers. Empty means none. Entries naming an
+   * absent or unknown tool are inert by design, which is what keeps the
+   * default list stable while the registry grows. */
+  approvals: z
+    .array(
+      z
+        .string()
+        .regex(
+          ORCHESTRATOR_APPROVAL_ENTRY,
+          'approval entries look like "tool" or "tool:qualifier"',
+        ),
+    )
+    .default([...defaultOrchestratorApprovals]),
+  /** Wake-filter globs a NEW session inherits. Kept schema-optional (not
+   * `.default()`) so absent ("inherit the default attention set") and `[]`
+   * ("never wake") stay distinct. Each glob must match at least one build
+   * or repository-journal event type — validated below with the shared
+   * `ab watch` compiler. */
+  wake: z.array(z.string().min(1)).optional(),
 })
 export type OrchestratorConfig = z.infer<typeof orchestratorSchema>
 
@@ -614,33 +797,34 @@ export const configSchema = configRootSchema.superRefine((config, ctx) => {
     })
   })
 
-  if (
-    config.workspace.provider === 'git-worktree' &&
-    Object.keys(config.workspace.config).length > 0
-  ) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['workspace', 'config'],
-      message:
-        '[workspace.config] is not supported by the builtin "git-worktree" provider — remove it or select a plugin workspace provider',
-    })
-  } else if (config.workspace.provider === 'vercel-sandbox') {
-    const parsed = vercelSandboxConfigSchema.safeParse(config.workspace.config)
+  const workspaceDeclaration = BUILTIN_WORKSPACE_PROVIDER_CONFIG.get(config.workspace.provider)
+  // The parse-site refusal fires only for a declaration carrying
+  // `configRefusalMessage`; providers absent from the table are plugin-owned
+  // pass-throughs and are never refused here.
+  if (workspaceDeclaration?.configRefusalMessage !== undefined) {
+    if (Object.keys(config.workspace.config).length > 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['workspace', 'config'],
+        message: workspaceDeclaration.configRefusalMessage,
+      })
+    }
+  } else if (workspaceDeclaration?.configSchema !== undefined) {
+    const parsed = workspaceDeclaration.configSchema.safeParse(config.workspace.config)
     if (!parsed.success) {
       forwardIssues(parsed.error.issues, ctx, ['workspace', 'config'])
     } else if (
+      workspaceDeclaration.requireRuntimeProvisioning === true &&
       config.roles !== undefined &&
       config.verify !== undefined &&
       config.finalize !== undefined
     ) {
       for (const group of effectiveRuntimeReferences(config)) {
-        if (Object.hasOwn(parsed.data.runtimeProvisioning, group.runtime)) continue
+        if (Object.hasOwn(runtimeProvisioningMap(parsed.data), group.runtime)) continue
         ctx.addIssue({
           code: 'custom',
           path: ['workspace', 'config', 'runtimeProvisioning', group.runtime],
-          message:
-            `runtime ${displayName(group.runtime)} is selected by ${group.references.join(', ')} but has no sandbox provisioning; add ` +
-            `[workspace.config.runtimeProvisioning.${tomlKey(group.runtime)}] with nonblank install and preflight commands`,
+          message: runtimeProvisioningMissingMessage(group),
         })
       }
     }
@@ -753,18 +937,66 @@ export const configSchema = configRootSchema.superRefine((config, ctx) => {
       }
     }
   }
+  if (tickets.source !== 'linear' && tickets.readyAssignee !== undefined) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['tickets', 'readyAssignee'],
+      message: `[tickets].readyAssignee applies only to source = "linear" — remove it or select that source (selected source: "${tickets.source}")`,
+    })
+  }
   // Plugin sources receive the existing ticket lifecycle/configuration fields
   // unchanged; adapter-specific validation belongs to their factory.
 
   // The credential-free sandbox rule (AUT-340): a forwarded variable name may
   // never name a store, forge, ticket-provider, model, or Vercel credential.
+  // A workspace provider can declare additional forbidden names beyond the
+  // shared set. This check is deliberately builtin-only: plugins are not
+  // loaded when config is parsed, so a plugin provider's declared names cannot
+  // be seen here (AUT-536). The deferral is accepted, not an oversight — the
+  // declared extras are enforced at the registry-aware seams instead,
+  // `createWorkspaceProvider` (construction) and `validateInitReadiness`
+  // (init validation), both of which run after plugin load; no site loads
+  // plugins earlier to widen parse-time coverage.
+  // Wake globs are validated with the same compiler `ab watch` uses, over the
+  // build AND repository-journal catalogs — the wake pass scans both — so a
+  // typo'd glob fails at parse time instead of silently matching nothing —
+  // regardless of `enabled`, since a later enablement would inherit the
+  // already-broken value.
+  if (config.orchestrator.wake !== undefined) {
+    try {
+      compileEventGlobs(config.orchestrator.wake, {
+        repository: true,
+        usage: '[orchestrator].wake',
+      })
+    } catch (error) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['orchestrator', 'wake'],
+        message: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
   if (config.orchestrator.enabled) {
+    // The turn runner's model is not optional when the orchestrator is on:
+    // an enabled table without one would fail at first turn start, far from
+    // the edit that caused it.
+    if (config.orchestrator.model === undefined) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['orchestrator', 'model'],
+        message:
+          '[orchestrator].enabled = true requires [orchestrator].model — name the provider-qualified model string the turn runner uses (same vocabulary as [roles], resolved through the deployment gateway credential)',
+      })
+    }
+    const providerForbidden =
+      BUILTIN_WORKSPACE_PROVIDER_CONFIG.get(config.workspace.provider)?.sandboxForbiddenEnv ?? []
     config.orchestrator.sandbox.environmentVariables.forEach((name, index) => {
-      if (SANDBOX_FORBIDDEN_ENV.includes(name)) {
+      if (SANDBOX_FORBIDDEN_ENV.includes(name) || providerForbidden.includes(name)) {
         ctx.addIssue({
           code: 'custom',
           path: ['orchestrator', 'sandbox', 'environmentVariables', index],
-          message: `environment variable ${JSON.stringify(name)} is a store, forge, ticket-provider, model, or Vercel credential and may never be forwarded into an operator sandbox`,
+          message: sandboxForbiddenEnvMessage(name),
         })
       }
     })

package/packages/core/src/events/catalog.ts

@@ -67,6 +67,7 @@ export const allowedActorKinds: Record<EventType, readonly ActorKind[]> = {
   'build.discard-requested': ['human'],
   'build.auto-merge-requested': ['human'],
   'build.auto-merge-cancelled': ['human'],
+  'build.auto-merge-default-observed': ['dispatcher'],
   'build.paused': ['kernel'],
   'build.resumed': ['kernel'],
   'build.aborted': ['kernel', 'dispatcher'],

package/packages/core/src/events/globs.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared event-glob compilation (§15.3, AUT-342): the anchored glob matcher
+ * `ab watch`, `ab wait`, and the `[orchestrator].wake` configuration use.
+ * `*` matches any run of characters, `?` exactly one, everything else
+ * verbatim (so the dots inside event type names are escaped). Every glob
+ * must match at least one event type in one of the given catalogs, else a
+ * validation error naming the glob is thrown.
+ */
+import { EVENT_TYPES } from './payloads'
+import { REPOSITORY_EVENT_TYPES } from './repository'
+
+export interface CompileEventGlobsOptions {
+  /** Also accept matches in the repository-journal catalog (the `--repository`
+   * behavior of `ab watch`/`ab wait`). */
+  repository?: boolean
+  usage: string
+}
+
+export function compileEventGlobs(
+  globs: readonly string[],
+  opts: CompileEventGlobsOptions,
+): RegExp[] {
+  return globs.map((glob) => {
+    const source =
+      '^' +
+      [...glob]
+        .map((char) => {
+          if (char === '*') return '.*'
+          if (char === '?') return '.'
+          return char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        })
+        .join('') +
+      '$'
+    const regex = new RegExp(source)
+    const inBuildCatalog = EVENT_TYPES.some((type) => regex.test(type))
+    const inRepositoryCatalog =
+      opts.repository === true && REPOSITORY_EVENT_TYPES.some((type) => regex.test(type))
+    if (!inBuildCatalog && !inRepositoryCatalog) {
+      throw new Error(
+        `--event "${glob}" matches no known event type${
+          opts.repository ? ' in the build or repository catalogs' : ' in the build event catalog'
+        } — ${opts.usage}`,
+      )
+    }
+    return regex
+  })
+}

package/packages/core/src/events/payloads.ts

@@ -36,6 +36,23 @@ import {
 
 const empty = z.strictObject({})
 const reasonOnly = z.strictObject({ reason: z.string().optional() })
+/** Fan-out provenance shared by the auto-merge command facts: the repository
+ * seq of the `dispatcher.auto-merge-default-set` fact that caused the command,
+ * when one did. Per-build commands omit it. `{}` stays valid, so existing
+ * producers and logs replay unchanged. */
+const autoMergeCommand = z.strictObject({
+  defaultSeq: z.number().int().positive().optional(),
+})
+/** A fan-out reconciliation marker: the repository seq of the newest
+ * `dispatcher.auto-merge-default-set` fact a build has observed when that fact
+ * already matched the build's requested state. It advances the build's
+ * provenance without appending a duplicate request/cancel command, so a later
+ * per-build toggle stands until a strictly newer default fact arrives
+ * (f_28b3fba1). Dispatcher-authored: it records a reconciliation, not a
+ * human command. */
+const autoMergeDefaultObserved = z.strictObject({
+  defaultSeq: z.number().int().positive(),
+})
 const round = z.number().int().positive()
 const attempt = z.number().int().positive()
 const dispatchStage = z.enum(['create', 'workspace', 'spec', 'comment', 'launch'])
@@ -175,6 +192,20 @@ const finalizeStepCompletedPayloadSchema = z.discriminatedUnion('ok', [
   }),
 ])
 
+/** One ticket asset revision a build froze (SPEC §6.3): the identity and
+ * shape of what `listTicketAssets` returned at the pinning moment. */
+export const pinnedAssetSchema = z.strictObject({
+  kind: z.string().min(1),
+  name: z.string().min(1),
+  revision: z.number().int().nonnegative(),
+  layout: z.enum(['file', 'tree']),
+  size: z.number().int().nonnegative(),
+  fileCount: z.number().int().nonnegative(),
+  dirCount: z.number().int().nonnegative(),
+})
+
+export type PinnedAsset = z.infer<typeof pinnedAssetSchema>
+
 /** Shared by `plan-review.verdict` and `code-review.verdict` (symmetric by design). */
 const reviewVerdictPayload = z.strictObject({
   round,
@@ -194,12 +225,20 @@ export const eventPayloadSchemas = {
     /** Claim-time auto-merge intent retained across dispatch recovery until the
      * ordinary human-authored command fact can be materialized. */
     autoMergeRequestedBy: z.string().min(1).optional(),
+    /** Claim-time auto-merge intent provenance: the repository seq of the
+     * `dispatcher.auto-merge-default-set` fact the claim sampled. Retained for
+     * the same recovery window as `autoMergeRequestedBy`; omitted when the
+     * claim sampled no default fact. */
+    autoMergeDefaultSeq: z.number().int().positive().optional(),
     /** Frozen at claim time. Historical logs and disabled installs omit it. */
     pr: z
       .strictObject({
         imageHost: prImageHostSchema.optional(),
       })
       .optional(),
+    /** Ticket assets frozen at claim time. Omitted when the ticket had none
+     * and in historical logs. */
+    assets: z.array(pinnedAssetSchema).optional(),
   }),
   'build.completed': z.strictObject({ outcome: buildOutcomeSchema }),
   'runner.attached': z.strictObject({
@@ -223,6 +262,10 @@ export const eventPayloadSchemas = {
     path: z.string().min(1).optional(),
     /** Dispatcher-reachable path. Remote providers intentionally omit it. */
     localPath: z.string().min(1).optional(),
+    /** True when the provider reported a remote publication capability at
+     * provision time. Absent ⇒ local (historical journals). AUT-505 removes
+     * the legacy fallback that reads absent as the provider name. */
+    remote: z.boolean().optional(),
     branch: z.string().min(1),
     base: workspaceBaseSchema,
   }),
@@ -363,8 +406,9 @@ export const eventPayloadSchemas = {
   'build.resume-requested': reasonOnly,
   'build.abort-requested': reasonOnly,
   'build.discard-requested': empty,
-  'build.auto-merge-requested': empty,
-  'build.auto-merge-cancelled': empty,
+  'build.auto-merge-requested': autoMergeCommand,
+  'build.auto-merge-cancelled': autoMergeCommand,
+  'build.auto-merge-default-observed': autoMergeDefaultObserved,
   'build.paused': empty,
   'build.resumed': empty,
   'build.aborted': empty,
@@ -382,6 +426,9 @@ export const eventPayloadSchemas = {
     artifact: artifactRefSchema,
     /** seq of the `escalation.raised` event that forced the revision. */
     escalation: z.number().int().positive(),
+    /** Present (possibly empty) when the revision re-pins the build to the
+     * ticket's then-current assets; absent leaves the pinned set unchanged. */
+    assets: z.array(pinnedAssetSchema).optional(),
   }),
 
   // ── Sessions (every agent run is bracketed by these) ──────────────────────
@@ -552,6 +599,9 @@ export const eventPayloadSchemas = {
     resolution: escalationResolutionSchema,
     /** Exact replacement spec authorized by a `revise-spec` answer. */
     artifact: artifactRefSchema.optional(),
+    /** The ticket's assets sampled with a revise-from-ticket authorization, so a
+     * retry re-pins the set that was authorized. Absent otherwise. */
+    assets: z.array(pinnedAssetSchema).optional(),
     /** Absolute per-loop/current-spec review budget selected by the operator. */
     reviewRoundCeiling: z.number().int().positive().optional(),
   }),

package/packages/core/src/events/repository.ts

@@ -76,6 +76,10 @@ const tickCountersSchema = z.strictObject({
   sandboxIdleStops: z.number().int().nonnegative().optional(),
   /** Contained idle-settlement failures this tick; retried next tick. */
   sandboxSettleFailures: z.number().int().nonnegative().optional(),
+  /** Contained sandbox-backend construction failures this tick; re-reported
+   * every tick until the config is repaired. Optional so historical tick
+   * facts replay. */
+  orchestratorSandboxFailures: z.number().int().nonnegative().optional(),
   harvestStarted: z.number().int().nonnegative(),
   harvestResumed: z.number().int().nonnegative(),
   harvestCompleted: z.number().int().nonnegative(),
@@ -264,13 +268,20 @@ export const harvestEventPayloadSchemas = {
  * `processes/sandbox-state.ts`, mirroring harvest execution settlement. */
 export const orchestratorSandboxEventPayloadSchemas = {
   /** First use of one operator's environment for this repository, or a
-   * post-reset reprovision. Carries the full environment identity. */
+   * post-reset reprovision. Carries the full environment identity, plus the
+   * base branch head the fresh provision selected — the publication
+   * precondition's reference point (a publish must be a descendant of it).
+   * Optional so historical journals replay unchanged. */
   'orchestrator.sandbox.provisioned': z.strictObject({
     operator: z.string().min(1),
     environmentId: z.string().min(1),
     provider: z.string().min(1),
     sessionId: z.string().min(1).optional(),
     workspacePath: z.string().min(1),
+    baseSha: z
+      .string()
+      .regex(/^[0-9a-f]{40,64}$/i)
+      .optional(),
   }),
   /** A stopped environment resumed for a later tool call. */
   'orchestrator.sandbox.resumed': z.strictObject({
@@ -311,6 +322,34 @@ export const orchestratorSandboxEventPayloadSchemas = {
     operator: z.string().min(1),
     environmentId: z.string().min(1),
   }),
+  /** One PR-only publication from an operator sandbox: the operator, the
+   * delegated orchestrator session when one triggered the tool, the
+   * deterministic branch the commit was pushed to, the published commit, and
+   * the opened-or-adopted PR. Written after both the push and the forge call
+   * succeed; the push-before-fact discipline makes a retry complete the
+   * journal rather than re-push. */
+  'orchestrator.sandbox.published': z.strictObject({
+    operator: z.string().min(1),
+    environmentId: z.string().min(1),
+    branch: z.string().min(1),
+    sha: z.string().regex(/^[0-9a-f]{40,64}$/i),
+    session: z.string().min(1).optional(),
+    pr: z.strictObject({
+      number: z.number().int().positive(),
+      url: z.string().min(1),
+      headSha: z.string().min(1),
+    }),
+  }),
+  /** A refused or failed publication attempt. `stage` names where it stopped
+   * (the precondition checks, the push, or the forge PR call); `message` is
+   * the provider's or forge's text, redacted of credential values by the
+   * service. */
+  'orchestrator.sandbox.publish-failed': z.strictObject({
+    operator: z.string().min(1),
+    environmentId: z.string().min(1),
+    stage: z.enum(['checks', 'push', 'pr']),
+    message: z.string().min(1),
+  }),
 } as const
 
 export const dispatcherStatusEventPayloadSchemas = {
@@ -421,6 +460,16 @@ export type RepositoryEventType = keyof typeof repositoryEventPayloadSchemas
 export const REPOSITORY_EVENT_TYPES = Object.keys(
   repositoryEventPayloadSchemas,
 ) as RepositoryEventType[]
+
+/** The repository-journal attention set, followed only under `--repository`
+ * by `ab watch` and scanned by the orchestrator wake pass. */
+export const REPOSITORY_ATTENTION_EVENTS = [
+  'harvest.escalated',
+  'harvest.failed',
+  'dispatcher.tick-failed',
+  'dispatcher.config-rejected',
+  'dispatcher.harvest-runner-failed',
+] as const satisfies readonly RepositoryEventType[]
 export type RepositoryEventPayload<T extends RepositoryEventType> = z.infer<
   (typeof repositoryEventPayloadSchemas)[T]
 >
@@ -487,6 +536,8 @@ const allowedActorKinds: Record<RepositoryEventType, readonly ActorKind[]> = {
   // `harvest.execution.released` is dispatcher-authored.
   'orchestrator.sandbox.released': ['human', 'dispatcher'],
   'orchestrator.sandbox.reset': ['human'],
+  'orchestrator.sandbox.published': ['human'],
+  'orchestrator.sandbox.publish-failed': ['human'],
   'dispatcher.run-started': ['dispatcher'],
   'dispatcher.run-stopped': ['dispatcher'],
   'dispatcher.tick-yielded': ['dispatcher'],