@defrex/autobuild 0.8.0 → 0.10.0

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

@@ -21,13 +21,25 @@ export type InstallScope = 'local' | 'global'
  * forge dependency, or a version range satisfied from the npm registry. */
 export type InstallChannel = 'github' | 'npm'
 
+/** The owning manifest sections a self-update target may be declared in. */
+export type DependencySection = 'dependencies' | 'devDependencies'
+
+/** Searched in this order; when a manifest declares the package in both, the
+ * first wins (the runtime declaration, which a plain `bun add` would rewrite). */
+const DEPENDENCY_SECTIONS: readonly DependencySection[] = ['dependencies', 'devDependencies']
+const SEARCHED_SECTIONS = DEPENDENCY_SECTIONS.join(' or ')
+
 interface ManagedInstallationBase extends DistributionIdentity {
   sourceCheckout: false
   ownerRoot: string
   ownerManifest: string
   ownerLock: string
-  /** The owning manifest's direct dependency value, byte for byte. */
+  /** The owning manifest's direct dependency value in `section`, byte for byte. */
   dependency: string
+  /** The manifest section the dependency was chosen from. */
+  section: DependencySection
+  /** The manifest also declares the package in the other section. */
+  dual: boolean
   scope: InstallScope
 }
 
@@ -180,9 +192,27 @@ async function parseJsonc(path: string): Promise<Record<string, unknown>> {
   }
 }
 
-function lockDependency(lock: Record<string, unknown>, packageName: string): unknown {
+function lockDependency(
+  lock: Record<string, unknown>,
+  packageName: string,
+  section: DependencySection,
+): unknown {
   const workspace = object(object(lock.workspaces)?.[''])
-  return object(workspace?.dependencies)?.[packageName]
+  return object(workspace?.[section])?.[packageName]
+}
+
+/** Pick the section that declares the package: a pure function of the
+ * manifest, in fixed `DEPENDENCY_SECTIONS` order. */
+function declaredSection(
+  manifest: Record<string, unknown>,
+  packageName: string,
+): { section: DependencySection; value: string; dual: boolean } | undefined {
+  const declared = DEPENDENCY_SECTIONS.flatMap((section) => {
+    const value = object(manifest[section])?.[packageName]
+    return typeof value === 'string' ? [{ section, value }] : []
+  })
+  const first = declared[0]
+  return first === undefined ? undefined : { ...first, dual: declared.length > 1 }
 }
 
 function lockPackageRecord(
@@ -235,21 +265,29 @@ export async function inspectInstallation(options: {
   try {
     const manifest = await parseJson(ownerManifest)
     const lock = await parseJsonc(ownerLock)
-    const dependency = object(manifest.dependencies)?.[identity.packageName]
+    const declared = declaredSection(manifest, identity.packageName)
+    if (declared === undefined) {
+      return {
+        kind: 'unknown',
+        identity,
+        reason: `${ownerManifest} does not declare ${identity.packageName} under ${SEARCHED_SECTIONS} as a direct github: dependency or an npm registry version range satisfied by ${identity.version}`,
+      }
+    }
+    const { section, value: dependency, dual } = declared
     const repository = githubDependency(dependency)
     const registry = repository === undefined && registryDependency(dependency, identity.version)
-    if ((repository === undefined && !registry) || typeof dependency !== 'string') {
+    if (repository === undefined && !registry) {
       return {
         kind: 'unknown',
         identity,
-        reason: `${ownerManifest} does not declare ${identity.packageName} as a direct github: dependency or an npm registry version range satisfied by ${identity.version}`,
+        reason: `${ownerManifest} declares ${identity.packageName} under ${section} as "${dependency}", which is neither a direct github: dependency nor an npm registry version range satisfied by ${identity.version}`,
       }
     }
-    if (lockDependency(lock, identity.packageName) !== dependency) {
+    if (lockDependency(lock, identity.packageName, section) !== dependency) {
       return {
         kind: 'unknown',
         identity,
-        reason: `${ownerLock} does not agree with the direct dependency in ${ownerManifest}`,
+        reason: `${ownerLock} does not agree with the direct ${section} entry in ${ownerManifest}`,
       }
     }
     const scope: InstallScope = (await samePath(join(options.globalBin, 'ab'), identity.binaryPath))
@@ -280,6 +318,8 @@ export async function inspectInstallation(options: {
           ownerManifest,
           ownerLock,
           dependency,
+          section,
+          dual,
           scope,
         },
       }
@@ -320,6 +360,8 @@ export async function inspectInstallation(options: {
         owner: repository.owner,
         repository: repository.repository,
         dependency,
+        section,
+        dual,
         scope,
       },
     }

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

@@ -19,7 +19,7 @@ import type { Forge } from '../ports/types'
 import type { Exec } from '../ports/workspace/git-worktree'
 import type { IdSource } from '../ids'
 import { reduceBuild } from '../kernel/reducer'
-import { artifactDownload, artifactGet, artifactPut } from './artifact'
+import { artifactDownload, artifactDownloadStream, artifactGet, artifactPut } from './artifact'
 import { multiFlag, parseArgs, stringFlag, type ParsedArgs } from './args'
 import { abBuildControl, type BuildControlAction, type BuildControlResult } from './build-control'
 import {
@@ -45,7 +45,7 @@ import { observe } from './observe'
 import { abPlugin, type PluginContractSubprocess } from './plugin'
 import { preparePrAttachments } from './pr-attachments'
 import { renderPrSummary } from './pr-summary'
-import { abBuilds, abBuildStatus } from './status'
+import { abBuildAssetGet, abBuilds, abBuildStatus } from './status'
 import { abRepositoryStatus } from './repository-status'
 import { abWatch, WATCH_USAGE } from './watch'
 import { abWait, WAIT_USAGE } from './wait'
@@ -478,6 +478,7 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
         const report = await (deps.initValidation ?? validateInitReadiness)({
           targetRepo,
           env,
+          processEnv: deps.processEnv ?? process.env,
           stdout,
           ...(deps.exec !== undefined ? { exec: deps.exec } : {}),
           ...(deps.initRuntimes !== undefined ? { runtimes: deps.initRuntimes } : {}),
@@ -790,9 +791,44 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
     }
 
     case 'build': {
-      const usage = 'usage: ab build status <slug> [--events <n>] [--json] [--store <ref>] (§8.2)'
+      const usage =
+        'usage: ab build status <slug> [--events <n>] [--json] [--store <ref>] (§8.2)\n' +
+        '       ab build asset get <slug> <kind> <name> <dest> [--rev <n>] [--json] [--store <ref>] (§8.8)'
       const [sub, ...more] = rest
-      // Only `status` today; the subcommand shape keeps room for `ab build <verb>`.
+      if (sub === 'asset') {
+        const [action, ...assetArgs] = more
+        if (action !== 'get') throw new Error(usage)
+        const assetParsed = parseArgs(
+          assetArgs,
+          { rev: 'value', json: 'boolean', store: 'value' },
+          usage,
+        )
+        const [slug, kind, name, dest, ...extra] = assetParsed.positionals
+        if (!slug || !kind || !name || !dest || extra.length > 0) throw new Error(usage)
+        const rawRev = stringFlag(assetParsed, 'rev')
+        if (rawRev !== undefined && !/^\d+$/.test(rawRev)) {
+          throw new Error(`--rev must be a nonnegative integer, got "${rawRev}" — ${usage}`)
+        }
+        const assetStore = stringFlag(assetParsed, 'store')
+        if (deps.exec === undefined) {
+          throw new Error("'ab build' needs an exec seam — this is a wiring bug in the ab binary")
+        }
+        await abBuildAssetGet({
+          targetRepo: deps.workspacePath,
+          env: deps.processEnv ?? {},
+          exec: deps.exec,
+          stdout,
+          slug,
+          kind,
+          name,
+          dest,
+          json: assetParsed.flags.has('json'),
+          ...(rawRev !== undefined ? { rev: Number(rawRev) } : {}),
+          ...(assetStore !== undefined ? { storeRef: assetStore } : {}),
+          ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+        })
+        return 0
+      }
       if (sub !== 'status') {
         throw new Error(usage)
       }
@@ -1211,8 +1247,37 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
         const usage =
           'usage: ab artifact download <build> <kind>[@rev] --output <file> [--store <ref>] (§8.2)'
         const parsed = parseArgs(more, { output: 'value', store: 'value' }, usage)
-        const [build, spec] = parsed.positionals
+        const [first, second] = parsed.positionals
         const outputPath = stringFlag(parsed, 'output')
+        const storeRef = stringFlag(parsed, 'store')
+        if (deps.exec === undefined) {
+          throw new Error(
+            "'ab artifact download' needs an exec seam — this is a wiring bug in the ab binary",
+          )
+        }
+        // A stream-addressed first positional can never be a build slug: the
+        // dispatcher's slug charset forbids ':'. Repo-scoped streams take the
+        // one-positional operator form; everything else stays on the unchanged
+        // build-scoped path.
+        if (first?.startsWith('stream:')) {
+          const streamUsage =
+            'usage: ab artifact download stream:<id>[@rev] --output <file> [--store <ref>] (§8.2)'
+          if (second !== undefined || outputPath === undefined) throw new Error(streamUsage)
+          const downloaded = await artifactDownloadStream({
+            targetRepo: deps.workspacePath,
+            env: deps.processEnv ?? {},
+            exec: deps.exec,
+            spec: first,
+            outputPath,
+            ...(storeRef !== undefined ? { storeRef } : {}),
+            ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
+          })
+          stdout(
+            `downloaded ${downloaded.artifact.meta.kind}@${downloaded.artifact.meta.revision} to ${downloaded.outputPath}`,
+          )
+          return 0
+        }
+        const [build, spec] = parsed.positionals
         if (
           build === undefined ||
           spec === undefined ||
@@ -1221,12 +1286,6 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
         ) {
           throw new Error(usage)
         }
-        const storeRef = stringFlag(parsed, 'store')
-        if (deps.exec === undefined) {
-          throw new Error(
-            "'ab artifact download' needs an exec seam — this is a wiring bug in the ab binary",
-          )
-        }
         const downloaded = await artifactDownload({
           targetRepo: deps.workspacePath,
           env: deps.processEnv ?? {},

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

@@ -26,6 +26,8 @@ import type { Config } from '../config/schema'
 import type { Via } from '../events/envelope'
 import { defaultTriageState } from '../processes/dispatcher'
 import { createWorkspaceProvider } from '../ports/workspace/create'
+import { createForge } from '../ports/forge/create'
+import type { Forge } from '../ports/types'
 import { createTicketSource } from '../ports/tickets/create'
 import { loadPlugins } from '../plugins/load'
 import { AUTOBUILD_VERSION } from '../store/remote/version'
@@ -221,8 +223,9 @@ export async function abMcp(opts: AbMcpOpts): Promise<number> {
         throw error
       }
       if (mcpConfig.orchestrator.enabled) {
+        const plugins = await loadPlugins(mcpConfig.plugins, context.checkout)
         const provider = await createWorkspaceProvider(mcpConfig.workspace, {
-          registry: await loadPlugins(mcpConfig.plugins, context.checkout),
+          registry: plugins,
           worktreeRoot: context.worktreeRoot,
           repoRoot: context.checkout,
           env: opts.env,
@@ -231,13 +234,32 @@ export async function abMcp(opts: AbMcpOpts): Promise<number> {
           sandboxSetupCommand: mcpConfig.commands.setup,
           sandboxRoot: join(context.localStateRoot, 'orchestrator-sandboxes'),
           sandboxEnvironmentVariables: mcpConfig.orchestrator.sandbox.environmentVariables,
+          orchestratorSandboxEnabled: true,
         })
+        // The forge is needed only for sandbox.publish; a construction
+        // failure must not drop every sandbox tool, so it is contained here
+        // and publication is silently omitted (canPublish stays false).
+        let forge: Forge | undefined
+        try {
+          forge = await createForge({
+            name: mcpConfig.forge,
+            registry: plugins,
+            env: opts.env,
+            repoRoot: context.checkout,
+            repository: context.repo,
+          })
+        } catch (forgeError) {
+          opts.stderr(
+            `ab mcp: forge unavailable, sandbox.publish omitted: ${forgeError instanceof Error ? forgeError.message : String(forgeError)}`,
+          )
+        }
         sandbox = await createOperatorSandboxService({
           store: context.store,
           repo: context.repo,
           provider,
           sandbox: mcpConfig.orchestrator.sandbox,
           baseBranch: mcpConfig.baseBranch,
+          ...(forge !== undefined ? { forge } : {}),
           ...(opts.clock !== undefined ? { clock: opts.clock } : {}),
         })
       }

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

@@ -77,6 +77,9 @@ function renderModuleReport(report: PluginDiagnosis['reports'][number]): string
     report.api === undefined
       ? ''
       : ` api=${report.api.declaredRange} host=${report.api.hostVersion} ${report.api.status}`
+  if (report.status === 'skipped') {
+    return `SKIP ${report.module} kind=${report.resolutionKind} stage=${report.stage}${location}${source}${plugin}${api}: ${report.notice}`
+  }
   return report.status === 'loaded'
     ? `OK ${report.module} kind=${report.resolutionKind}${location}${source}${plugin}${api}`
     : `FAIL ${report.module} kind=${report.resolutionKind} stage=${report.stage}${location}${source}${plugin}${api}: ${report.error}`
@@ -149,8 +152,8 @@ export async function abPlugin(argv: readonly string[], opts: PluginCliOpts): Pr
     if (diagnosis.reports.length === 0) opts.stdout('  (none)')
     for (const report of diagnosis.reports) {
       const line = `  ${renderModuleReport(report)}`
-      if (report.status === 'loaded') opts.stdout(line)
-      else opts.stderr(line)
+      if (report.status === 'failed') opts.stderr(line)
+      else opts.stdout(line)
     }
     opts.stdout('adapters:')
     for (const port of PLUGIN_PORTS) {
@@ -170,8 +173,8 @@ export async function abPlugin(argv: readonly string[], opts: PluginCliOpts): Pr
     }
     for (const report of diagnosis.reports) {
       const line = renderModuleReport(report)
-      if (report.status === 'loaded') opts.stdout(line)
-      else opts.stderr(line)
+      if (report.status === 'failed') opts.stderr(line)
+      else opts.stdout(line)
     }
     return diagnosis.healthy ? 0 : 1
   }

package/packages/core/src/cli/remote-poll.ts

@@ -0,0 +1,277 @@
+/**
+ * The shared remote long-poll task machinery behind `ab watch` and `ab wait`
+ * (AUT-334, corrected for `ab wait` in AUT-368, extracted in AUT-403). One
+ * long-poll task per tracked stream runs concurrently against an `http(s)`
+ * store: a held `getEvents` request per stream is always in flight, gap-fill
+ * spaces request starts at least one interval apart, and every stop — a
+ * domain condition, an external abort, or an elapsed deadline — cancels the
+ * in-flight holds and wakes the gap sleeps instead of waiting out a full
+ * hold. A hold's own bound is capped at the remaining time budget.
+ *
+ * The two commands keep their different semantics through injected
+ * callbacks (`shouldStop`, per-task `endCheck`, the discovery step) and two
+ * explicit configuration points (`drain` mode, `deadlineMs`); everything
+ * mechanical lives here, so a fix to streak or stop handling cannot land in
+ * one command and silently miss the other.
+ *
+ * Timing is fully injected (`now`, `sleep`): the module never reads the wall
+ * clock and never schedules a real timer, so tests drive every wait
+ * deterministically.
+ */
+import { REMOTE_EVENT_WAIT_SECONDS } from '../store/remote/client'
+
+/** The read options one held long-poll request carries. */
+export interface RemotePollReadOpts {
+  waitSeconds?: number
+  signal?: AbortSignal
+}
+
+/**
+ * The default abortable sleep: resolves after `ms`, or as soon as `signal`
+ * aborts. Shared verbatim by `ab watch` and `ab wait` as the `delay` default.
+ */
+export function defaultDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted === true) {
+      resolve()
+      return
+    }
+    const finish = (): void => {
+      clearTimeout(timer)
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }
+    const timer = setTimeout(finish, ms)
+    const onAbort = (): void => finish()
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+/**
+ * A failed read is reported once per failure streak, advances nothing, and
+ * is retried at the next interval (local) or next request (remote); a
+ * success on the same source re-arms the report. Each read source — per
+ * stream task, plus discovery — carries its own streak, so a persistent
+ * failure on one stream interleaved with successes elsewhere is still
+ * reported only once.
+ */
+export function makeFailureStreak(
+  command: string,
+  stderr: (line: string) => void,
+): { onFailure: (error: unknown) => void; onSuccess: () => void } {
+  let reported = false
+  return {
+    onFailure: (error: unknown): void => {
+      if (reported) return
+      reported = true
+      const message = error instanceof Error ? error.message : String(error)
+      stderr(`ab ${command}: a store read failed (${message}); retrying at the next interval`)
+    },
+    onSuccess: (): void => {
+      reported = false
+    },
+  }
+}
+
+export interface RemotePollRunnerOpts {
+  /** `'watch' | 'wait'` — the streak message's command prefix. */
+  command: string
+  stderr: (line: string) => void
+  /** Injected clock; never the wall clock directly. */
+  now: () => Date
+  /** Injected delay; every wait the runner makes goes through this. */
+  sleep: (ms: number, signal?: AbortSignal) => Promise<void>
+  /** The gap-fill floor between request starts. */
+  intervalMs: number
+  /** Epoch ms at which reads stop; `Number.POSITIVE_INFINITY` for an
+   * unbounded `--timeout 0`. */
+  deadlineMs: number
+  /** The external signal only (SIGINT) — never widened to the domain stop
+   * terms, so a failure observed as the deadline elapses is still reported. */
+  aborted: () => boolean
+  /** The loop-guard predicate: `aborted() || deadline elapsed || domain
+   * stop`. Evaluated at the top of every task cycle. */
+  shouldStop: () => boolean
+  /** Invoked on every runner stop — a task's endCheck, the discovery task's
+   * endCheck, or a caller-initiated `requestStop`. `ab watch` trips its
+   * shared `stop` flag here: `pollBuild`/`pollRepository` gate their batch
+   * loops on that flag (`if (stop) break`), so a sibling task whose held
+   * read has already resolved must stop delivering its batch the moment any
+   * task observes the terminal condition — exactly what the pre-extraction
+   * command-scoped `requestStop` did (f_42263f38). May fire more than once
+   * (every `requestStop` call fires it); the callback must be idempotent. */
+  onStop?: () => void
+  /** How `drain()` treats tasks launched while it is awaiting.
+   * `'snapshot'`: await only the tasks present when `drain()` is called
+   * (`ab watch`'s one-shot semantics). `'quiesce'`: keep awaiting until no
+   * task remains (`ab wait`'s semantics — the exit decision must observe
+   * every task settled). */
+  drain: 'snapshot' | 'quiesce'
+}
+
+export interface RemotePollRunner {
+  /** Whether a stop has been requested — by `requestStop` or a task's own
+   * `endCheck`. */
+  readonly stopped: boolean
+  /** Abort every in-flight held read, wake the gap sleeps, mark stopped. */
+  requestStop(): void
+  /** Launch one per-stream long-poll task; idempotent per key. `endCheck`
+   * runs after each successful poll; true ⇒ requestStop + return. */
+  launch(
+    key: string,
+    poll: (readOpts: RemotePollReadOpts) => Promise<unknown>,
+    endCheck?: () => boolean,
+  ): void
+  /** The interval-cadence discovery task, self-tracked for drain. `step`
+   * (the discovery read) runs inside the try/catch; `launchPending` (the
+   * launch-everything loop) runs UNCONDITIONALLY after the catch, so streams
+   * registered before a mid-discovery throw are still launched; `endCheck`
+   * (wait only) runs after `launchPending`, throw or not. */
+  runDiscovery(opts: {
+    step: () => Promise<void>
+    launchPending: () => void
+    endCheck?: () => boolean
+  }): Promise<void>
+  /** Await launched tasks per the configured strategy. */
+  drain(): Promise<void>
+}
+
+/**
+ * Build the per-command runner over the shared machinery. Every piece is
+ * moved verbatim from the command-local copies this module replaces; the
+ * commands' different stop and drain semantics enter only through `opts`.
+ */
+export function createRemotePollRunner(opts: RemotePollRunnerOpts): RemotePollRunner {
+  // Held reads in flight right now, each with its own controller. When the
+  // command stops for any reason, every in-flight read is cancelled —
+  // otherwise a stop during a quiet window would wait out a full wait
+  // window (up to the remote hold) before the command could exit.
+  const inFlightReads = new Set<AbortController>()
+  // Wakes stop-aware gap sleeps the moment the command stops.
+  const stopController = new AbortController()
+  let stopped = false
+  const requestStop = (): void => {
+    stopped = true
+    opts.onStop?.()
+    stopController.abort()
+    for (const controller of inFlightReads) controller.abort()
+  }
+
+  /** The wait bound for one held read: the remote default, capped at the
+   * command's remaining time budget. With an unbounded deadline the same
+   * expression yields exactly the remote default, so one form covers both. */
+  const readWaitSeconds = (atMs: number): number => {
+    const remaining = Math.floor((opts.deadlineMs - atMs) / 1000)
+    return Math.max(0, Math.min(REMOTE_EVENT_WAIT_SECONDS, remaining))
+  }
+
+  // One self-cleaning task set for both commands. Awaiting a snapshot that
+  // omits already-settled tasks is equivalent to awaiting the plain array
+  // the one-shot drain used before the extraction.
+  const tasks = new Set<Promise<void>>()
+  /** Track a task and keep the set accurate as tasks settle, so the quiesce
+   * drain also waits for tasks launched while it is awaiting. */
+  const track = (task: Promise<void>): void => {
+    tasks.add(task)
+    void task.then(
+      () => tasks.delete(task),
+      () => tasks.delete(task),
+    )
+  }
+
+  const runStreamTask = async (
+    poll: (readOpts: RemotePollReadOpts) => Promise<unknown>,
+    endCheck?: () => boolean,
+  ): Promise<void> => {
+    const streak = makeFailureStreak(opts.command, opts.stderr)
+    while (!stopped && !opts.shouldStop()) {
+      const started = opts.now().getTime()
+      const controller = new AbortController()
+      inFlightReads.add(controller)
+      try {
+        await poll({ waitSeconds: readWaitSeconds(started), signal: controller.signal })
+        streak.onSuccess()
+        if (endCheck?.()) {
+          requestStop()
+          return
+        }
+      } catch (error) {
+        // A cancelled held read is the command stopping, not a store
+        // failure — never report it. The check stays on the external signal
+        // (not the full guard), so a failure observed as the deadline
+        // elapses is still reported.
+        if (!stopped && !opts.aborted() && !controller.signal.aborted) streak.onFailure(error)
+      } finally {
+        inFlightReads.delete(controller)
+      }
+      if (stopped || opts.aborted()) return
+      const elapsed = opts.now().getTime() - started
+      if (elapsed < opts.intervalMs) {
+        await opts.sleep(opts.intervalMs - elapsed, stopController.signal)
+      }
+    }
+  }
+
+  const launched = new Set<string>()
+  const launch = (
+    key: string,
+    poll: (readOpts: RemotePollReadOpts) => Promise<unknown>,
+    endCheck?: () => boolean,
+  ): void => {
+    if (launched.has(key)) return
+    launched.add(key)
+    track(runStreamTask(poll, endCheck))
+  }
+
+  const runDiscovery = (discovery: {
+    step: () => Promise<void>
+    launchPending: () => void
+    endCheck?: () => boolean
+  }): Promise<void> => {
+    const task = (async (): Promise<void> => {
+      const streak = makeFailureStreak(opts.command, opts.stderr)
+      while (!stopped && !opts.shouldStop()) {
+        try {
+          await discovery.step()
+          streak.onSuccess()
+        } catch (error) {
+          streak.onFailure(error)
+        }
+        // Unconditional — after the catch: streams registered before a
+        // mid-discovery throw still get tasks whose polls then run
+        // independently.
+        discovery.launchPending()
+        if (discovery.endCheck?.()) {
+          requestStop()
+          return
+        }
+        if (stopped || opts.aborted()) return
+        await opts.sleep(opts.intervalMs, stopController.signal)
+      }
+    })()
+    track(task)
+    return task
+  }
+
+  const drain = async (): Promise<void> => {
+    if (opts.drain === 'quiesce') {
+      // Await every task — including ones launched while awaiting: the
+      // discovery task adds stream tasks mid-wait, and the caller's exit
+      // decision must observe every task settled.
+      while (tasks.size > 0) await Promise.all(tasks)
+      return
+    }
+    // One-shot snapshot: tasks launched during the await are NOT awaited.
+    await Promise.all([...tasks])
+  }
+
+  return {
+    get stopped(): boolean {
+      return stopped
+    },
+    requestStop,
+    launch,
+    runDiscovery,
+    drain,
+  }
+}

package/packages/core/src/cli/repo-state.ts

@@ -190,6 +190,28 @@ export async function buildInRepository(
   return normalizeGitRemoteUrl(record.repoOrigin) === identity
 }
 
+/**
+ * Whether a repo-scoped stream's recorded scope belongs to `identity` — the
+ * same origin-aware first arm `buildInRepository` applies to builds, with the
+ * recorded side normalized like `record.repoOrigin` there so the guard never
+ * depends on the writer's normalizer vintage (an scp-like ssh-spelled scope
+ * equals the https identity of the same origin).
+ *
+ * Full parity with `buildInRepository` is impossible by construction:
+ * `StreamScope` carries no `repoOrigin`, so a legacy physical-path
+ * `scope.repo` (which `normalizeGitRemoteUrl` passes through unchanged) has no
+ * recorded origin to compare and can never match an origin identity — it stays
+ * rejected. That is the accepted AUT-314-class limitation, not something this
+ * guard can forgive.
+ *
+ * No `exec` parameter: the caller's identity is already resolved (the
+ * context's `repo` is `origin ?? resolved checkout` from `resolveRepoState`),
+ * so re-running git would be redundant.
+ */
+export function streamInRepository(scopeRepo: string, identity: string): boolean {
+  return normalizeGitRemoteUrl(scopeRepo) === identity
+}
+
 /** Resolve repository identity, then select all state paths from it.
  *
  * Identity is the resolved main checkout's normalized origin remote, falling