@defrex/autobuild 0.10.1 → 0.12.0

package/packages/core/src/cli/binary.ts

@@ -53,7 +53,7 @@ export async function withDispatchTerminalRestore<T>(
   terminal: TerminalOut,
   run: () => Promise<T>,
   boundary: TerminalRestoreProcess = process as unknown as TerminalRestoreProcess,
-  requestStop: () => void = () => {},
+  requestStop: (signal: NodeJS.Signals) => void = () => {},
 ): Promise<T> {
   const hook =
     command === 'dispatch'
@@ -96,7 +96,7 @@ export async function runBinary(
     // cleanly at the next tick boundary (§15.6-C: in-flight leases expire and
     // a future dispatch re-attaches).
     const controller = new AbortController()
-    const onSigint = (): void => controller.abort()
+    const onSigint = (): void => controller.abort('SIGINT')
     const ownsSigint = usesGenericSessionlessSigintHandler(command)
     const terminal = processTerminal(process.stdout)
     const removeSigint = installSessionlessSigintHandler(command, onSigint)
@@ -119,7 +119,7 @@ export async function runBinary(
             ...(resolveDashboardRenderer !== undefined ? { resolveDashboardRenderer } : {}),
           }),
         process as unknown as TerminalRestoreProcess,
-        onSigint,
+        (signal) => controller.abort(signal),
       )
     } finally {
       removeSigint()

package/packages/core/src/cli/configured-store.ts

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parse } from 'smol-toml'
+import { storeSchema } from '../config/schema'
+
+/** Store selection happens before full dispatch configuration is loaded. */
+export function configuredStore(checkout: string): string | undefined {
+  let text: string
+  try {
+    text = readFileSync(join(checkout, 'autobuild.toml'), 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined
+    throw error
+  }
+  const table = parse(text)
+  return table.store === undefined ? undefined : storeSchema.parse(table.store).url
+}

package/packages/core/src/cli/connect.ts

@@ -0,0 +1,261 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto'
+import { access, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { constants } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { parse } from 'smol-toml'
+import {
+  normalizeConnectionRepository,
+  normalizeServiceURL,
+  type ConnectionStarted,
+  type ConnectionOutcome,
+} from '../connection'
+import type { Exec } from '../ports/workspace/git-worktree'
+import { resolveMainRepo } from './repo-state'
+import { ProjectCredentials } from './project-credentials'
+
+interface ConnectOptions {
+  cwd: string
+  env: Record<string, string | undefined>
+  exec: Exec
+  print: (message: string) => void
+  signal?: AbortSignal
+  fetch?: (input: string, init?: RequestInit) => Promise<Response>
+  browser?: (url: string) => Promise<void>
+  sleep?: (ms: number) => Promise<void>
+  now?: () => number
+}
+function requireOperator(env: ConnectOptions['env']) {
+  if (
+    ['AB_BUILD', 'AB_PHASE', 'AB_SESSION', 'AB_HARVEST', 'AB_REPO'].some(
+      (key) => env[key] !== undefined,
+    )
+  )
+    throw new Error('connect and disconnect are unavailable inside build or harvest sessions')
+}
+async function project(opts: ConnectOptions) {
+  requireOperator(opts.env)
+  const checkout = await resolveMainRepo(opts.cwd, opts.exec)
+  const remote = await opts.exec(['git', 'remote', 'get-url', 'origin'], { cwd: checkout })
+  if (remote.exitCode !== 0 || !remote.stdout.trim())
+    throw new Error('A network origin remote is required; add an origin before running ab connect')
+  const repo = normalizeConnectionRepository(remote.stdout.trim())
+  const path = join(checkout, 'autobuild.toml')
+  const text = await readFile(path, 'utf8')
+  const table = parse(text)
+  const store = table.store as { url?: unknown } | undefined
+  if (store && (typeof store !== 'object' || Array.isArray(store)))
+    throw new Error('Invalid [store] configuration')
+  const service = store?.url === undefined ? undefined : normalizeServiceURL(String(store.url))
+  return { checkout, repo, path, text, table, service }
+}
+async function request(
+  opts: ConnectOptions,
+  service: string,
+  path: string,
+  body?: unknown,
+  token?: string,
+) {
+  const response = await (opts.fetch ?? fetch)(`${service}/connect/v1/${path}`, {
+    method: body === undefined ? 'GET' : 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    signal: AbortSignal.timeout(15000),
+    redirect: 'error',
+  })
+  return response
+}
+async function revoke(opts: ConnectOptions, service: string, token: string) {
+  const response = await request(opts, service, 'revoke', {}, token)
+  if (!response.ok && response.status !== 401)
+    throw new Error('Remote revocation failed; retry ab disconnect when the service is reachable')
+}
+async function atomicConfig(path: string, before: string, after: string) {
+  const temporary = `${path}.${randomUUID()}.tmp`
+  try {
+    await writeFile(temporary, after, { flag: 'wx' })
+    if ((await readFile(path, 'utf8')) !== before)
+      throw new Error('autobuild.toml changed during connection; retry ab connect')
+    await rename(temporary, path)
+  } finally {
+    await unlink(temporary).catch(() => {})
+  }
+}
+export async function abConnect(raw: string | undefined, opts: ConnectOptions): Promise<void> {
+  const p = await project(opts)
+  const credentials = new ProjectCredentials(opts.env)
+  if (raw === undefined) {
+    if (!p.service) {
+      opts.print(
+        `Project: ${p.repo}\nService: unconfigured\nCredential: missing; run ab connect <url>`,
+      )
+      return
+    }
+    const entry = credentials.load(p.service, p.repo)
+    let status = 'missing; run ab connect'
+    if (entry) {
+      try {
+        const response = await request(opts, p.service, 'status', undefined, entry.token)
+        if (response.ok) {
+          const body = (await response.json()) as {
+            repo?: string
+            credentialId?: string
+            accepted?: boolean
+          }
+          if (body.repo !== p.repo || body.credentialId !== entry.id || body.accepted !== true)
+            throw new Error('Invalid status response')
+        }
+        status = response.ok
+          ? 'accepted'
+          : response.status === 401 || response.status === 403
+            ? 'rejected; run ab connect'
+            : 'unreachable'
+      } catch {
+        status = 'unreachable'
+      }
+    }
+    opts.print(`Service: ${p.service}\nProject: ${p.repo}\nCredential: ${status}`)
+    return
+  }
+  const service = normalizeServiceURL(raw)
+  if (p.service && p.service !== service)
+    throw new Error(
+      'Configured [store] url differs; update it explicitly before connecting to another service',
+    )
+  await access(p.path, constants.W_OK)
+  await access(dirname(p.path), constants.W_OK)
+  const previous = credentials.load(service, p.repo)
+  const id = randomBytes(16).toString('hex'),
+    secret = randomBytes(32).toString('hex')
+  const token = `abp_1_${id}_${secret}`
+  const response = await request(opts, service, 'requests', {
+    repo: p.repo,
+    credentialId: id,
+    digest: createHash('sha256').update(secret).digest('hex'),
+  })
+  if (!response.ok)
+    throw new Error('Could not start connection approval; verify the web-enabled service URL')
+  const started = (await response.json()) as ConnectionStarted
+  if (
+    !/^[a-f0-9]{32}$/.test(started.id) ||
+    !/^[a-f0-9]{64}$/.test(started.capability) ||
+    !/^[A-F0-9]{10}$/.test(started.code) ||
+    !Number.isFinite(Date.parse(started.expiresAt))
+  )
+    throw new Error('Invalid connection response')
+  const verification = `${service}/connect?code=${started.code}`
+  opts.print(`Approve project ${p.repo}\nOpen ${verification}\nCode: ${started.code}`)
+  try {
+    if (opts.browser) await opts.browser(verification)
+    else {
+      const command =
+        process.platform === 'darwin'
+          ? ['open', verification]
+          : process.platform === 'win32'
+            ? ['rundll32', 'url.dll,FileProtocolHandler', verification]
+            : ['xdg-open', verification]
+      const child = Bun.spawn(command, { stdout: 'ignore', stderr: 'ignore' })
+      child.unref()
+    }
+  } catch {
+    opts.print('Browser could not be opened. Use the URL and code on another device.')
+  }
+  const capability = { id: started.id, capability: started.capability }
+  const now = opts.now ?? Date.now
+  const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+  const interval = Math.max(5, Math.min(30, started.interval || 5)) * 1000
+  let approved = false
+  let configChanged = false
+  let saved = false
+  try {
+    let outcome: ConnectionOutcome | undefined
+    while (!opts.signal?.aborted && now() <= Date.parse(started.expiresAt) + interval) {
+      await sleep(interval)
+      const polled = await request(opts, service, 'poll', capability)
+      if (polled.status === 429) continue
+      if (!polled.ok) throw new Error('Approval polling failed; retry ab connect')
+      outcome = (await polled.json()) as ConnectionOutcome
+      if (outcome.status !== 'pending') break
+    }
+    if (!outcome || outcome.status === 'pending' || opts.signal?.aborted) {
+      const cancelled = await request(opts, service, 'cancel', capability)
+      if (!cancelled.ok)
+        throw new Error(
+          'Could not confirm cancellation; use the owner credential list to check this connection',
+        )
+      opts.print(
+        opts.signal?.aborted
+          ? 'Connection cancelled; local configuration unchanged.'
+          : 'Connection timed out; local configuration unchanged.',
+      )
+      return
+    }
+    if (outcome.status !== 'approved') {
+      opts.print(`Connection ${outcome.status}; local configuration unchanged.`)
+      return
+    }
+    approved = true
+    if (outcome.repo !== p.repo || outcome.credentialId !== id)
+      throw new Error('Approval identity mismatch')
+    if (!p.service) {
+      // Dotted root key also supports an existing empty [store] table after it.
+      const after = `store.url = ${JSON.stringify(service)}\n${p.text}`
+      const parsed = parse(after)
+      if ((parsed.store as { url?: string })?.url !== service)
+        throw new Error('Cannot safely update [store] url; add it manually and retry')
+      await atomicConfig(p.path, p.text, after)
+      configChanged = true
+    }
+    credentials.save({ service, repo: p.repo, id, token })
+    saved = true
+    if (previous) {
+      try {
+        await revoke(opts, service, previous.token)
+      } catch {
+        opts.print(
+          `Connected, but the previous credential ${previous.id} could not be revoked; revoke it using the service administrative tools.`,
+        )
+      }
+    }
+    opts.print(`Connected ${p.repo} to ${service}.`)
+    if (configChanged) opts.print(`Updated ${p.path}; review and commit this non-secret setting.`)
+  } catch (error) {
+    if (!saved) {
+      try {
+        const cancelled = await request(opts, service, 'cancel', capability)
+        if (!cancelled.ok) throw new Error()
+      } catch {
+        opts.print(
+          `Could not confirm remote cleanup for credential ${id}; check the service administrative credential list.`,
+        )
+      }
+      if (configChanged) {
+        try {
+          await atomicConfig(p.path, `store.url = ${JSON.stringify(service)}\n${p.text}`, p.text)
+        } catch {
+          opts.print('Restore [store] url manually if needed; configuration changed concurrently.')
+        }
+      }
+    }
+    throw new Error(
+      approved
+        ? 'Connection could not be saved; previous credential retained. Repair local storage and run ab connect again.'
+        : (error as Error).message,
+    )
+  }
+}
+export async function abDisconnect(opts: ConnectOptions): Promise<void> {
+  const p = await project(opts)
+  if (!p.service) throw new Error('No configured service')
+  const credentials = new ProjectCredentials(opts.env)
+  const entry = credentials.load(p.service, p.repo)
+  if (!entry) {
+    opts.print('No stored credential; project configuration and service data retained.')
+    return
+  }
+  await revoke(opts, p.service, entry.token)
+  credentials.remove(p.service, p.repo)
+  opts.print('Disconnected; project registration, data, and [store] url retained.')
+}

package/packages/core/src/cli/dashboard/model.ts

@@ -116,11 +116,9 @@ export interface PipelineStep {
   /** Absent ⇒ the step has never run in the current spec scope ⇒ no time is
    * shown (AC 6). The renderer composes the elapsed segment from this. */
   timing?: StepTiming
-  /** Display-only, like `qualifier`, and never consulted for routing: the
-   * parked merge step's no-consent explanation — why nothing will happen
-   * without operator action, and which control unblocks it. Attached when the
-   * build is current at merge with effective auto-merge off; the terminal
-   * row/detail and the web row/detail render the same words. */
+  /** Display-only policy skip reason or parked merge explanation. The shared
+   * row/detail renderers use this wrapping prose segment for longer reasons;
+   * it is never consulted for routing. */
   reason?: string
 }
 
@@ -268,6 +266,8 @@ export interface DashboardModel {
   harvestPaused: boolean
   /** Stable row identity, never a row index. */
   selection?: DashboardSelection
+  /** Invocation-local standby identity, independent of notices and build rows. */
+  standby?: string
   /** Release courtesy, separate from transient and startup warnings so those
    * notices can never overwrite one another. Store-only frontends project it
    * from their correlated dispatcher run. */
@@ -750,6 +750,7 @@ export function projectBuildFromFacts(
           : stepResults.some((r) => r.outcome === 'skipped')
             ? 'skipped'
             : undefined,
+        reason: stepResults.find((r) => r.skipCause === 'post-reconcile-policy')?.reason,
         count,
         timing: timingFor(intervals, phase, cycleSince, frozenNow),
       }),
@@ -1090,6 +1091,7 @@ interface DashboardFrameHeader {
   queued: number
   observationCount: number
   selection?: DashboardSelection
+  standby?: string
   availableUpgrade?: string
   warningLines?: readonly string[]
   resumeInput?: ResumeInputView
@@ -1125,6 +1127,7 @@ export function buildDashboardFromProjected(
     defaultAutoMerge: settings.defaultAutoMerge,
     harvestPaused: harvestProjection.harvestPaused,
     ...(header.selection !== undefined ? { selection: header.selection } : {}),
+    ...(header.standby !== undefined ? { standby: header.standby } : {}),
     ...(header.availableUpgrade !== undefined ? { availableUpgrade: header.availableUpgrade } : {}),
     ...(header.warningLines !== undefined && header.warningLines.length > 0
       ? { warningLines: header.warningLines }

package/packages/core/src/cli/dashboard/render.ts

@@ -722,6 +722,21 @@ interface DetailGeometry extends DetailBodyLayout {
   limit: number
 }
 
+function standbyLine(model: DashboardModel, color: boolean, width: number): string[] {
+  return model.standby === undefined
+    ? []
+    : [
+        truncate(
+          paint(
+            `  Dispatcher on standby: repository held by ${displayText(model.standby)}`,
+            'yellow',
+            color,
+          ),
+          width,
+        ),
+      ]
+}
+
 function upgradeNoticeLine(
   model: DashboardModel,
   color: boolean,
@@ -749,7 +764,8 @@ function detailGeometry(
   const build = model.builds.find((candidate) => candidate.slug === view.slug)
   if (build === undefined) return undefined
   const layout = detailBody(build, view, { color: false, width, height, now: 0 })
-  const topLength = 2 + (model.availableUpgrade === undefined ? 0 : 1)
+  const topLength =
+    2 + (model.standby === undefined ? 0 : 1) + (model.availableUpgrade === undefined ? 0 : 1)
   const controls =
     model.resumeInput !== undefined || model.abortConfirmation !== undefined
       ? dashboardControls(model, false, width, controlsCapacity(height, topLength))
@@ -808,6 +824,7 @@ function renderDetail(model: DashboardModel, opts: RenderOpts): string[] {
       `  status ${paint(build.status.toUpperCase(), STATUS_COLOR[build.status], color)}${paused}`,
       width,
     ),
+    ...standbyLine(model, color, width),
     ...(notice === undefined ? [] : [notice]),
   ]
   const { body } = detailBody(build, view, opts)
@@ -862,11 +879,12 @@ export function transcriptScrollLimit(
   terminalWidth: number,
   height: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
   const contentLines = transcriptContent(presentation, dashboardContentWidth(terminalWidth)).length
-  // Transcript chrome is two header rows, the optional upgrade row, two
+  // Transcript chrome is two header rows, optional standby/upgrade rows, two
   // separators, and controls. Keep this in lockstep with renderTranscript.
-  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0))
+  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0) - (hasStandby ? 1 : 0))
   return Math.max(0, contentLines - capacity)
 }
 
@@ -877,8 +895,15 @@ export function moveTranscriptScroll(
   current: number,
   delta: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
-  const limit = transcriptScrollLimit(presentation, terminalWidth, height, hasUpgradeNotice)
+  const limit = transcriptScrollLimit(
+    presentation,
+    terminalWidth,
+    height,
+    hasUpgradeNotice,
+    hasStandby,
+  )
   // Clamp current first because a resize, or state from an older controller,
   // may leave it beyond the freshly wrapped viewport's end.
   return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
@@ -909,6 +934,7 @@ function renderTranscript(model: DashboardModel, opts: RenderOpts): string[] {
   const top = [
     truncate(`${paint('Transcript', 'bold', color)}  ${displayText(view.slug)}`, width),
     truncate(`  session ${displayText(view.sessionId)}`, width),
+    ...standbyLine(model, color, width),
     ...(notice === undefined ? [] : [notice]),
   ]
   const content = transcriptContent(view.transcript, width).map((line) => truncate(line, width))
@@ -948,11 +974,12 @@ export function sessionScrollLimit(
   terminalWidth: number,
   height: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
   const contentLines = sessionContentLines(view, dashboardContentWidth(terminalWidth)).length
-  // Session chrome is two header rows, the optional upgrade row, two
+  // Session chrome is two header rows, optional standby/upgrade rows, two
   // separators, and controls — the transcript's exact arithmetic.
-  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0))
+  const capacity = Math.max(0, height - 5 - (hasUpgradeNotice ? 1 : 0) - (hasStandby ? 1 : 0))
   return Math.max(0, contentLines - capacity)
 }
 
@@ -963,8 +990,9 @@ export function moveSessionScroll(
   current: number,
   delta: number,
   hasUpgradeNotice = false,
+  hasStandby = false,
 ): number {
-  const limit = sessionScrollLimit(view, terminalWidth, height, hasUpgradeNotice)
+  const limit = sessionScrollLimit(view, terminalWidth, height, hasUpgradeNotice, hasStandby)
   // Clamp current first: a resize, a feed apply, or state from an older
   // controller may leave it beyond the freshly wrapped viewport's end.
   return Math.max(0, Math.min(limit, Math.min(current, limit) + delta))
@@ -983,6 +1011,7 @@ function renderSessionView(model: DashboardModel, opts: RenderOpts): string[] {
       }`,
       width,
     ),
+    ...standbyLine(model, color, width),
     ...(notice === undefined ? [] : [notice]),
   ]
   const content = sessionContentLines(view, width).map((line) => truncate(line, width))
@@ -1417,6 +1446,7 @@ function renderDashboardContent(model: DashboardModel, opts: RenderOpts): string
   const top = [
     summary,
     toggles,
+    ...standbyLine(model, color, width),
     ...(upgradeNotice === undefined ? [] : [upgradeNotice]),
     ...warnings,
   ]

package/packages/core/src/cli/dispatch-frontend.ts

@@ -1,3 +1,4 @@
+import { StandbyIdentityResolver } from './dispatcher-liveness'
 import { configSchema, type Config } from '../config/schema'
 import { humanActor } from '../events/envelope'
 import type { RepositoryEvent } from '../events/repository'
@@ -114,6 +115,7 @@ export interface DispatchFrontendOptions {
 /** Terminal controller with a deliberately narrow wiring surface: terminal,
  * BuildStore, immutable repository identity, clock, and child supervision. */
 export class DispatchFrontend {
+  private readonly standbyResolver: StandbyIdentityResolver
   private readonly runId = crypto.randomUUID()
   private readonly clock: Clock
   private readonly region: LiveRegion
@@ -153,6 +155,7 @@ export class DispatchFrontend {
   private operatorStopRequested = false
 
   constructor(private readonly opts: DispatchFrontendOptions) {
+    this.standbyResolver = new StandbyIdentityResolver(opts.store, opts.repo)
     this.clock = opts.clock ?? systemClock
     this.keyboard = createKeyboardProtocol(
       (chunk) => opts.terminal.write(chunk),
@@ -191,6 +194,7 @@ export class DispatchFrontend {
                 this.opts.store.getRepoEvents(this.opts.repo, 0),
               )
             : await this.opts.store.getRepoEvents(this.opts.repo, 0)
+        this.standbyResolver.ingest(seed)
         this.repositorySeq = seed.at(-1)?.seq ?? 0
         this.dispatchStatus = reduceDispatchStatus(seed, this.runId)
         this.repositoryEvents.push(...seed.filter(isDashboardRepositoryEvent))
@@ -199,6 +203,7 @@ export class DispatchFrontend {
       }
       const delta = await this.opts.store.getRepoEvents(this.opts.repo, this.repositorySeq)
       if (delta.length === 0) return
+      this.standbyResolver.ingest(delta)
       this.repositorySeq = delta.at(-1)!.seq
       this.dispatchStatus = reduceDispatchStatus(delta, this.runId, this.dispatchStatus)
       this.repositoryEvents.push(...delta.filter(isDashboardRepositoryEvent))
@@ -367,10 +372,14 @@ export class DispatchFrontend {
       ...status.roleWarnings,
       ...(status.warningNotice !== undefined ? [status.warningNotice] : []),
     ]
+    const standby = this.opts.once
+      ? undefined
+      : await this.standbyResolver.refresh(this.runId, status.yieldedHolder, this.clock())
     const projected = buildDashboardFromProjected(
       snapshot.builds,
       {
         repo: this.opts.repo,
+        ...(standby !== undefined ? { standby } : {}),
         queued: status.queued ?? 0,
         activeCount: [...snapshot.states.values()].filter(
           (state) => state.status !== 'done' && state.status !== 'aborted',
@@ -409,6 +418,7 @@ export class DispatchFrontend {
         this.opts.terminal.columns,
         paintableRows(this.opts.terminal.rows),
         upgrade,
+        this.model?.standby !== undefined,
       )
       const current = view.follow ? limit : view.scroll
       const scroll = moveSessionScroll(
@@ -418,6 +428,7 @@ export class DispatchFrontend {
         current,
         delta,
         upgrade,
+        this.model?.standby !== undefined,
       )
       let follow = view.follow
       if (delta < 0 && follow && scroll < limit) follow = false
@@ -437,6 +448,7 @@ export class DispatchFrontend {
           this.view.scroll,
           delta,
           this.model?.availableUpgrade !== undefined,
+          this.model?.standby !== undefined,
         ),
       }
     } else if (this.view?.kind === 'detail' && this.model !== undefined) {
@@ -598,6 +610,7 @@ export class DispatchFrontend {
             terminal.columns,
             paintableRows(terminal.rows),
             this.model?.availableUpgrade !== undefined,
+            this.model?.standby !== undefined,
           )
           this.view = {
             ...next,
@@ -977,7 +990,9 @@ export class DispatchFrontend {
   private requestOperatorStop(): void {
     this.operatorStopRequested = true
     this.restorePresentationForStop()
-    void this.child?.stop()
+    void this.child?.stop(
+      typeof this.opts.signal?.reason === 'string' ? this.opts.signal.reason : undefined,
+    )
   }
 
   /** Stop terminal ownership synchronously before awaiting a kernel that may

package/packages/core/src/cli/dispatch-process.ts

@@ -25,7 +25,7 @@ export interface DispatchChildResult {
 
 export interface DispatchChildHandle {
   completed: Promise<DispatchChildResult>
-  stop(): Promise<void>
+  stop(signal?: string): Promise<void>
 }
 
 export interface DispatchSubprocess {
@@ -57,16 +57,20 @@ export interface DispatchKernelSignalBoundary {
  * one-shot handlers would expose the child to the default disposition on a
  * repeated Ctrl-C while it is still crossing an unsafe claim boundary. */
 export function installDispatchKernelSignalHandlers(
-  onStop: () => void,
+  onStop: (signal: DispatchKernelSignal) => void,
   boundary: DispatchKernelSignalBoundary = process,
 ): DispatchProcessHook {
-  for (const signal of DISPATCH_KERNEL_SIGNALS) boundary.on(signal, onStop)
+  const listeners = DISPATCH_KERNEL_SIGNALS.map((signal) => ({
+    signal,
+    listener: () => onStop(signal),
+  }))
+  for (const { signal, listener } of listeners) boundary.on(signal, listener)
   let closed = false
   return {
     close(): void {
       if (closed) return
       closed = true
-      for (const signal of DISPATCH_KERNEL_SIGNALS) boundary.removeListener(signal, onStop)
+      for (const { signal, listener } of listeners) boundary.removeListener(signal, listener)
     },
   }
 }
@@ -156,13 +160,14 @@ export function superviseDispatchChild(deps: DispatchChildSupervisorDeps): Dispa
   env[DISPATCH_CHILD_OPTIONS_ENV] = JSON.stringify(deps.options)
   const child = (deps.spawn ?? defaultSpawn)({ entrypoint, cwd: deps.cwd ?? deps.repo, env })
 
+  let requestedSignal: string | undefined
   let stopping = false
   let forced = false
   let stopPromise: Promise<void> | undefined
   // This is the sole supervisor writer of a missing stop fact. `stop()` only
   // chooses/awaits process termination, avoiding check-then-append races.
   const completed = child.exited.then(async (exitCode): Promise<DispatchChildResult> => {
-    const processSignal = child.signalCode === null ? undefined : String(child.signalCode)
+    const processSignal = child.signalCode === null ? requestedSignal : String(child.signalCode)
     const events = await deps.store.getRepoEvents(deps.repo)
     const recorded = events.findLast(
       (event) => event.type === 'dispatcher.run-stopped' && event.payload.run === deps.run,
@@ -179,7 +184,7 @@ export function superviseDispatchChild(deps: DispatchChildSupervisorDeps): Dispa
 
     const outcome: DispatchChildOutcome = forced
       ? 'forced'
-      : stopping && exitCode === 0 && processSignal === undefined
+      : stopping && exitCode === 0 && child.signalCode === null
         ? 'normal'
         : 'abnormal'
     const error =
@@ -209,11 +214,24 @@ export function superviseDispatchChild(deps: DispatchChildSupervisorDeps): Dispa
 
   return {
     completed,
-    stop(): Promise<void> {
+    stop(signal?: string): Promise<void> {
       if (stopPromise !== undefined) return stopPromise
       stopPromise = (async () => {
         if (child.exitCode !== null) return
         stopping = true
+        requestedSignal = signal
+        if (signal !== undefined) {
+          try {
+            await deps.store.appendRepo(deps.repo, {
+              actor: DISPATCHER,
+              type: 'dispatcher.stop-requested',
+              payload: { run: deps.run, signal },
+            })
+          } catch {
+            // Signal delivery must survive a transient Store failure. The
+            // kernel can still record its own abort reason after draining.
+          }
+        }
         child.kill('SIGINT')
         const timeout = deps.stopTimeoutMs ?? DEFAULT_STOP_TIMEOUT_MS
         const stopped = await Promise.race([