@defrex/autobuild 0.12.0 → 0.13.0

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

@@ -211,7 +211,7 @@ export class DashboardBuildPollCache {
         // both the cached reduction and projected row untouched.
         next.set(
           record.slug,
-          configChanged
+          configChanged || current.build?.ticketId !== record.ticket?.id
             ? {
                 ...current,
                 build: await this.projectRow(record, current.state, current.events, config),

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

@@ -1,3 +1,4 @@
+import { issueTicketGrant, ticketGrantRequest } from '../ports/tickets/grants'
 import { RemoteBuildStore } from '../store/remote/client'
 import { delegateCredential } from '../store/remote/credentials'
 import { isRemoteStoreRef } from './repo-state'
@@ -205,7 +206,8 @@ export function slugNamingPrompt(spec: string): string {
 function definedEnv(env: Record<string, string | undefined>): Record<string, string> {
   const defined: Record<string, string> = {}
   for (const [key, value] of Object.entries(env)) {
-    if (value !== undefined && key !== 'AB_TOKEN') defined[key] = value
+    if (value !== undefined && !['AB_TOKEN', 'AB_TICKET_TOKEN', 'AB_TICKET_URL'].includes(key))
+      defined[key] = value
   }
   return defined
 }
@@ -811,6 +813,7 @@ class DispatchLoop {
       forge: wiring.forge,
       config,
       getConfig: () => this.liveConfig.current().config,
+      repairBuildConfig: (slug) => this.publishBuildConfig(slug),
       repo: this.repoIdentity,
       // Origin mode: the forge answers remote base-branch questions; no
       // checkout git is probed for the served repository's origin.
@@ -2248,6 +2251,110 @@ class DispatchLoop {
 
     let tracked: Promise<void>
     tracked = (async () => {
+      const ticketUrl =
+        harvestDeps.config.tickets.source === 'hosted'
+          ? (harvestDeps.config.tickets.url ?? (/^https?:/i.test(storeRef) ? storeRef : undefined))
+          : undefined
+      if (ticketUrl && ticketUrl.replace(/\/+$/, '') !== storeRef.replace(/\/+$/, '')) {
+        const ticketToken = projectToken(ticketUrl, this.repoIdentity, {
+          ...this.opts.env,
+          AB_TOKEN: undefined,
+        })
+        if (!ticketToken)
+          throw new Error('Independent hosted harvest requires a ticket-service project credential')
+        const issued = await issueTicketGrant(
+          ticketUrl,
+          ticketToken,
+          this.repoIdentity,
+          harvestDeps.instance,
+          'runner',
+        )
+        let remoteRunnerStore: RemoteBuildStore | undefined
+        let preparedRun: { run: string } | undefined
+        let buildScoped: string | undefined
+        let renew: ReturnType<typeof setInterval> | undefined
+        try {
+          if (/^https?:/i.test(storeRef)) {
+            const prepared = await new HarvestRunner(harvestDeps).run(true)
+            if (prepared.outcome !== 'prepared') {
+              return prepared
+            }
+            preparedRun = { run: prepared.run }
+            await this.repoView.appendRepo(this.repoIdentity, {
+              actor: DISPATCHER,
+              type: 'harvest.execution.authorized',
+              payload: {
+                execution: harvestDeps.instance,
+                run: prepared.run,
+                launch: prepared.launch,
+                leaseHolder: this.repoLeaseHolder ?? harvestDeps.instance,
+              },
+            })
+            buildScoped = await (this.wiring.credentialIssuer ?? delegateCredential)(
+              storeRef,
+              token,
+              {
+                kind: 'harvest-runner',
+                execution: harvestDeps.instance,
+                repo: this.repoIdentity,
+                id: prepared.run,
+                leaseHolder: this.repoLeaseHolder ?? harvestDeps.instance,
+              },
+            )
+            remoteRunnerStore = new RemoteBuildStore({ url: storeRef, token: buildScoped })
+          }
+          const sessionEnv = {
+            ...harvestDeps.sessionEnv,
+            ...(buildScoped ? { AB_TOKEN: buildScoped } : {}),
+            AB_TICKET_URL: ticketUrl,
+            AB_TICKET_TOKEN: issued.token,
+          }
+          let renewalFailure: unknown
+          renew = setInterval(() => {
+            void ticketGrantRequest(ticketUrl, issued.token, {
+              action: 'renew',
+              repo: this.repoIdentity,
+              id: issued.grant.id,
+            }).catch((error) => {
+              renewalFailure = error
+            })
+          }, 60_000)
+          const runnerTickets = await createTicketSource(
+            harvestDeps.config.tickets,
+            { ...this.opts.env, ...sessionEnv, AB_TOKEN: undefined },
+            this.opts.targetRepo,
+            undefined,
+            this.wiring.plugins,
+          )
+          const result = await new HarvestRunner({
+            ...harvestDeps,
+            ...(remoteRunnerStore ? { store: remoteRunnerStore } : {}),
+            ...(preparedRun ? { preparedRun } : {}),
+            tickets: runnerTickets,
+            sessionEnv,
+          }).run()
+          if (renewalFailure) throw renewalFailure
+          return result
+        } finally {
+          if (renew) clearInterval(renew)
+          try {
+            if (remoteRunnerStore && preparedRun) {
+              await remoteRunnerStore.appendRepo(this.repoIdentity, {
+                actor: DISPATCHER,
+                type: 'harvest.execution.ended',
+                payload: { execution: harvestDeps.instance, run: preparedRun.run },
+              })
+              await remoteRunnerStore.close()
+            }
+          } finally {
+            await ticketGrantRequest(ticketUrl, ticketToken, {
+              action: 'revoke',
+              repo: this.repoIdentity,
+              id: issued.grant.id,
+            })
+          }
+        }
+      }
       if (!/^https?:/i.test(storeRef)) return new HarvestRunner(harvestDeps).run()
       const prepared = await new HarvestRunner(harvestDeps).run(true)
       if (prepared.outcome !== 'prepared') return prepared
@@ -2274,7 +2381,12 @@ class DispatchLoop {
           harvestDeps.config.tickets.source === 'hosted'
             ? await createTicketSource(
                 harvestDeps.config.tickets,
-                { ...this.opts.env, AB_STORE: storeRef, AB_TOKEN: scoped },
+                {
+                  ...this.opts.env,
+                  AB_STORE: storeRef,
+                  AB_TOKEN: scoped,
+                  AB_HARVEST: prepared.run,
+                },
                 this.opts.targetRepo,
                 resolveRepoStatePaths({
                   repo: this.repoIdentity,
@@ -2369,6 +2481,8 @@ class DispatchLoop {
     const repo = this.repoIdentity
     let handle: BuildExecutionHandle | undefined
     let startedSeq: number | undefined
+    let ticketAuthority: { url: string; token: string; id: string } | undefined
+    let renewTickets: ReturnType<typeof setInterval> | undefined
     // Shared with `stopHostedHarvest` through the `hostedHarvest` entry: a
     // detach must stay observable to the completion chain even after the
     // entry is cleared, or the chain would classify and reap a live guest.
@@ -2438,6 +2552,36 @@ class DispatchLoop {
             ),
           }
         : undefined
+      const ticketConfig = this.currentConfig().config.tickets
+      if (
+        ticketConfig.source === 'hosted' &&
+        ticketConfig.url &&
+        ticketConfig.url.replace(/\/+$/, '') !== storeRef.replace(/\/+$/, '')
+      ) {
+        const ticketToken = projectToken(ticketConfig.url, repo, {
+          ...this.opts.env,
+          AB_TOKEN: undefined,
+        })
+        if (!ticketToken || !launchAuth)
+          throw new Error('Independent harvest requires scoped build and ticket credentials')
+        const issued = await issueTicketGrant(
+          ticketConfig.url,
+          ticketToken,
+          repo,
+          execution,
+          'runner',
+        )
+        ticketAuthority = { url: ticketConfig.url, token: issued.token, id: issued.grant.id }
+        renewTickets = setInterval(() => {
+          void ticketGrantRequest(ticketConfig.url!, issued.token, {
+            action: 'renew',
+            repo,
+            id: issued.grant.id,
+          }).catch(() => {
+            // Expiry fails subsequent reads closed; the guest cannot regain project authority.
+          })
+        }, 60_000)
+      }
       handle = await harvestExecution.start(
         {
           preparedRun: { run: prepared.run },
@@ -2447,7 +2591,9 @@ class DispatchLoop {
           baseBranch: this.currentConfig().config.baseBranch,
           ...(this.repoLeaseHolder !== undefined ? { leaseHolder: this.repoLeaseHolder } : {}),
         },
-        launchAuth,
+        launchAuth && ticketAuthority
+          ? { ...launchAuth, tickets: { url: ticketAuthority.url, token: ticketAuthority.token } }
+          : launchAuth,
       )
       const identity = handle.identity
       if (
@@ -2525,6 +2671,13 @@ class DispatchLoop {
         )
       }
     } finally {
+      if (renewTickets) clearInterval(renewTickets)
+      if (ticketAuthority && !detached.value)
+        await ticketGrantRequest(ticketAuthority.url, ticketAuthority.token, {
+          action: 'revoke',
+          repo,
+          id: ticketAuthority.id,
+        })
       this.hostedHarvest = undefined
     }
   }

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

@@ -184,10 +184,20 @@ export async function buildHarvestContext(deps: HarvestCliDeps): Promise<Harvest
 }
 
 async function readJsonFile(path: string): Promise<unknown> {
-  const file = Bun.file(path)
-  if (!(await file.exists())) throw new Error(`file not found: ${path}`)
+  let text: string
   try {
-    return JSON.parse(await file.text())
+    text = await Bun.file(path).text()
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`file not found: ${path}`, { cause: error })
+    }
+    throw new Error(
+      `cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    )
+  }
+  try {
+    return JSON.parse(text)
   } catch (error) {
     throw new Error(
       `${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,

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

@@ -74,14 +74,14 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
     audience: 'human',
     summary: 'Connect this project to a hosted service with browser approval.',
     detail:
-      'Usage: ab connect [url]\nWith a URL, approve the printed URL and code in your browser. Stores the credential in user configuration and adds [store] url to autobuild.toml. Without a URL, reports the saved credential status. Runs outside sessions.',
+      'Usage: ab connect [--tickets] [url]\nWith a URL, approve the printed URL and code in your browser. Stores the credential in user configuration and adds [store] url to autobuild.toml. Use --tickets to save [tickets] url and keep builds local. Without a URL, reports every service connection and its uses. Runs outside sessions.',
   },
   {
     name: 'disconnect',
     audience: 'human',
     summary: 'Revoke and remove this project’s saved credential.',
     detail:
-      'Usage: ab disconnect\nRevokes the saved credential remotely before removing it locally. Keeps project registration, data and [store] url. Runs outside sessions.',
+      'Usage: ab disconnect [--tickets | --builds]\nRevokes the saved credential remotely before removing it locally. Keeps project registration, data and [store] url. Runs outside sessions.',
   },
   {
     name: 'upgrade',
@@ -173,20 +173,26 @@ export const HELP_CATALOG: readonly HelpEntry[] = [
     detail: page([
       'Usage:',
       '  ab ticket create <title> --body <file> [--state <state>] [--labels a,b] [--blocked-by id,id] [--json]',
-      '  ab ticket update <id> [--title <title>] [--body <file>] [--labels a,b] [--json]',
-      '  ab ticket block <id> <blocker-id[,blocker-id...]> [--json]',
-      '  ab ticket unblock <id> <blocker-id[,blocker-id...]> [--json]',
+      '  ab ticket edit <id>',
+      '  ab ticket export <dir> [--store <ref>]',
+      '  ab ticket import <dir> [--store <ref>]',
+      '  ab ticket update <id> [--title <title>] [--body <file>] [--labels a,b] [--expected-revision <opaque>] [--json]',
+      '  ab ticket block <id> <blocker-id[,blocker-id...]> [--expected-revision <opaque>] [--json]',
+      '  ab ticket unblock <id> <blocker-id[,blocker-id...]> [--expected-revision <opaque>] [--json]',
       '  ab ticket list [--state <state>] [--labels a,b] [--json]',
       '  ab ticket show <id> [--store <ref>] [--json]',
-      '  ab ticket move <id> <state> [--json]',
+      '  ab ticket move <id> <state> [--expected-revision <opaque>] [--json]',
       '  ab ticket states [--json]',
       '  ab ticket state create <name> [--about <text>] [--json]',
       '  ab ticket attach <id> <kind> <path> [--name <name>] [--store <ref>] [--json]',
       '  ab ticket asset get <id> <kind> <name> <dest> [--rev <n>] [--store <ref>] [--json]',
       '  ab ticket asset rm <id> <kind> <name> [--store <ref>] [--json]',
       '',
-      'Operate on the configured [tickets] source (§8.8); all ticket commands run',
-      'outside sessions. create files a ticket and may establish initial blockers.',
+      'Operate on the configured [tickets] source (§8.8); commands run outside sessions.',
+      'Every JSON ticket read includes an opaque revision. update, move, block and',
+      'unblock accept --expected-revision to refuse stale writes. Linear refuses checks.',
+      'edit opens VISUAL or EDITOR, checks the opening revision, and preserves failed buffers.',
+      'create files a ticket and may establish initial blockers.',
       '--state overrides [tickets].createState (or the provider default) for that',
       'create only; it is passed through unchanged and validated by the source.',
       'update partially replaces editable fields: omitted fields survive, --labels',

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

@@ -1,5 +1,5 @@
 import { stat, readFile, realpath } from 'node:fs/promises'
-import { join, resolve, sep } from 'node:path'
+import { dirname, join, resolve, sep } from 'node:path'
 import semver from 'semver'
 import { PLUGIN_API_VERSION } from '../plugins/manifest'
 import { defaultDistRoot } from './init'
@@ -155,6 +155,57 @@ function ownerRootForPackage(identity: DistributionIdentity): string | undefined
   return owner === '' ? sep : owner
 }
 
+/** Store-internal fallback links cannot establish project ownership. */
+function inBunStore(path: string): boolean {
+  return path
+    .split(sep)
+    .some((part, index, parts) => part === '.bun' && parts[index - 1] === 'node_modules')
+}
+
+function ancestors(path: string): string[] {
+  const result: string[] = []
+  for (let current = resolve(path); ; current = dirname(current)) {
+    result.push(current)
+    if (dirname(current) === current) return result
+  }
+}
+
+async function discoverOwner(
+  identity: DistributionIdentity,
+  cwd: string,
+): Promise<string | undefined> {
+  const direct = ownerRootForPackage(identity)
+  if (direct !== undefined && !inBunStore(direct)) return direct
+  // Reject invalid package names before constructing candidate public paths.
+  if (identity.packageName.split('/').some((part) => part === '' || part === '.' || part === '..'))
+    return undefined
+  const candidates = new Set([...ancestors(identity.root), ...ancestors(cwd)])
+  for (const candidate of candidates) {
+    if (inBunStore(candidate)) continue
+    if (!(await samePath(join(candidate, 'node_modules', identity.packageName), identity.root)))
+      continue
+    const manifestPath = join(candidate, 'package.json')
+    if (!(await exists(manifestPath))) continue
+    const manifest = await parseJson(manifestPath)
+    if (declaredSection(manifest, identity.packageName) !== undefined) return candidate
+  }
+  return undefined
+}
+
+async function readMetadata(path: string): Promise<string> {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`${path} does not exist`, { cause: error })
+    }
+    throw new Error(
+      `cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    )
+  }
+}
+
 function githubDependency(value: unknown): { owner: string; repository: string } | undefined {
   if (typeof value !== 'string') return undefined
   const match = /^github:([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)(?:#([^\s]+))?$/.exec(value)
@@ -172,8 +223,9 @@ function registryDependency(value: unknown, installedVersion: string): boolean {
 }
 
 async function parseJson(path: string): Promise<Record<string, unknown>> {
+  const text = await readMetadata(path)
   try {
-    return object(JSON.parse(await readFile(path, 'utf8'))) ?? {}
+    return object(JSON.parse(text)) ?? {}
   } catch (error) {
     throw new Error(
       `${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
@@ -182,8 +234,9 @@ async function parseJson(path: string): Promise<Record<string, unknown>> {
 }
 
 async function parseJsonc(path: string): Promise<Record<string, unknown>> {
+  const text = await readMetadata(path)
   try {
-    const value = Bun.JSONC.parse(await readFile(path, 'utf8'))
+    const value = Bun.JSONC.parse(text)
     return object(value) ?? {}
   } catch (error) {
     throw new Error(
@@ -241,6 +294,7 @@ async function samePath(left: string, right: string): Promise<boolean> {
 export async function inspectInstallation(options: {
   distRoot?: string
   globalBin: string
+  cwd?: string
 }): Promise<InstallationInspection> {
   const identity = await readDistributionIdentity(options.distRoot)
   if (identity.sourceCheckout) {
@@ -251,18 +305,18 @@ export async function inspectInstallation(options: {
     }
   }
 
-  const ownerRoot = ownerRootForPackage(identity)
-  if (ownerRoot === undefined) {
-    return {
-      kind: 'unknown',
-      identity,
-      reason: 'the distribution is not a direct Bun node_modules package',
+  try {
+    const ownerRoot = await discoverOwner(identity, options.cwd ?? process.cwd())
+    if (ownerRoot === undefined) {
+      return {
+        kind: 'unknown',
+        identity,
+        reason: 'the distribution is not a direct Bun node_modules package',
+      }
     }
-  }
-  const ownerManifest = join(ownerRoot, 'package.json')
-  const ownerLock = join(ownerRoot, 'bun.lock')
+    const ownerManifest = join(ownerRoot, 'package.json')
+    const ownerLock = join(ownerRoot, 'bun.lock')
 
-  try {
     const manifest = await parseJson(ownerManifest)
     const lock = await parseJsonc(ownerLock)
     const declared = declaredSection(manifest, identity.packageName)

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

@@ -1,3 +1,5 @@
+import { preparePinnedAssets } from '../store/ticket-assets'
+import type { PinnedAsset } from '../events/payloads'
 import { abConnect, abDisconnect } from './connect'
 /**
  * `ab` — the only channel between agents and the store, and the enforcement
@@ -308,6 +310,7 @@ async function runBuildControl(
   action: BuildControlAction,
   storeRef?: string,
   readTicketBody?: (ref: TicketRef) => Promise<string>,
+  prepareTicketAssets?: (ref: TicketRef, store: BuildStore, repo: string) => Promise<PinnedAsset[]>,
 ): Promise<void> {
   if (deps.exec === undefined) {
     throw new Error(
@@ -322,6 +325,7 @@ async function runBuildControl(
     action,
     ...(storeRef !== undefined ? { storeRef } : {}),
     ...(readTicketBody !== undefined ? { readTicketBody } : {}),
+    ...(prepareTicketAssets ? { prepareTicketAssets } : {}),
     ...(deps.openStore !== undefined ? { openStore: deps.openStore } : {}),
   })
   deps.stdout(buildControlConfirmation(result))
@@ -451,9 +455,11 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
     case 'connect':
     case 'disconnect': {
       const usage = command === 'connect' ? 'usage: ab connect [url]' : 'usage: ab disconnect'
-      const parsed = parseArgs(rest, {}, usage)
+      const parsed = parseArgs(rest, { tickets: 'boolean', builds: 'boolean' }, usage)
       if (parsed.positionals.length > (command === 'connect' ? 1 : 0)) throw new Error(usage)
       const options = {
+        tickets: parsed.flags.get('tickets') === true,
+        builds: parsed.flags.get('builds') === true,
         cwd: deps.workspacePath,
         env: deps.processEnv ?? process.env,
         exec: deps.exec ?? spawnExec,
@@ -1127,6 +1133,7 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
           : parsed.flags.has('revise-spec-from-ticket')
             ? ({ kind: 'revise-spec', body: { kind: 'ticket' } } as const)
             : undefined
+      let revisionTicketSource: import('../ports/types').TicketSource | undefined
       const readTicketBody =
         resolve?.kind === 'revise-spec' && resolve.body.kind === 'ticket'
           ? async (ref: TicketRef): Promise<string> => {
@@ -1140,6 +1147,7 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
                 },
                 'ab answer --revise-spec-from-ticket',
               )
+              revisionTicketSource = source
               if (source.name !== ref.source) {
                 throw new Error(
                   `build ticket source is "${ref.source}", but this repository is configured for "${source.name}"; refusing to read a same-id ticket from a different source`,
@@ -1151,7 +1159,10 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
                   `ticket "${ref.id}" was not found in the configured ${source.name} source`,
                 )
               }
-              if (ticket.ref.source !== ref.source || ticket.ref.id !== ref.id) {
+              if (
+                ticket.ref.source !== ref.source ||
+                (source.name !== 'hosted' && ticket.ref.id !== ref.id)
+              ) {
                 throw new Error(
                   `ticket adapter returned ${ticket.ref.source}:${ticket.ref.id}, expected ${ref.source}:${ref.id}`,
                 )
@@ -1170,6 +1181,13 @@ async function dispatch(argv: string[], deps: SessionlessCliDeps): Promise<numbe
         },
         storeRef,
         readTicketBody,
+        readTicketBody
+          ? async (ref, store, repo) => {
+              if (!revisionTicketSource)
+                throw new Error('ticket body must be read before preparing assets')
+              return preparePinnedAssets(revisionTicketSource, store, repo, ref.id)
+            }
+          : undefined,
       )
       return 0
     }

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

@@ -120,7 +120,8 @@ export async function buildMcpTicketBackend(
       }
       return source
     },
-    statesFor: async () => states,
+    statesFor: async (_context, source) =>
+      source.listStates ? (await source.listStates()).map((s) => s.name) : states,
   }
 }
 

package/packages/core/src/cli/self-update.ts

@@ -1,3 +1,4 @@
+import { join } from 'node:path'
 import { checkUpgradeCompatibility, type CompatibilityFetch } from './upgrade-compatibility'
 import { readFile, writeFile } from 'node:fs/promises'
 import semver from 'semver'
@@ -363,6 +364,7 @@ export async function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdate
   const inspection = await inspectInstallation({
     distRoot,
     globalBin: globalBinResult.stdout.trim(),
+    cwd: options.targetRepo,
   })
   if (inspection.kind !== 'bun-forge' && inspection.kind !== 'npm-registry') {
     return explicit ? fail(options, inspection.reason) : warn(options, inspection.reason)
@@ -469,7 +471,9 @@ export async function selfUpdate(options: SelfUpdateOptions): Promise<SelfUpdate
 
   let updated: DistributionIdentity
   try {
-    updated = await readDistributionIdentity(distRoot)
+    updated = await readDistributionIdentity(
+      join(install.ownerRoot, 'node_modules', ...install.packageName.split('/')),
+    )
     // Injected command fixtures do not rewrite disk; a real successful Bun
     // operation must. Keep the check injectable by accepting the old identity
     // only when the command seam itself was supplied.

package/packages/core/src/cli/ticket-assets.ts

@@ -42,6 +42,7 @@ export function ticketAssetNote(
   event: TicketAssetNoteEvent,
   meta: TicketAssetMeta,
   cli = 'ab',
+  hosted = false,
 ): string {
   const fileCount = meta.entries.filter((entry) => entry.type === 'file').length
   const label = `\`${meta.kind}/${meta.name}\``
@@ -52,7 +53,9 @@ export function ticketAssetNote(
       return [
         `Ticket asset attached: ${label} (revision ${meta.revision}, ${contents}).`,
         '',
-        'The contents live in the Autobuild store, not in this ticket.',
+        hosted
+          ? 'The contents live in the ticket service storage.'
+          : 'The contents live in the Autobuild store, not in this ticket.',
         `Download the latest revision: \`${get}\``,
         `Download this exact revision: \`${get} --rev ${meta.revision}\``,
       ].join('\n')
@@ -60,7 +63,9 @@ export function ticketAssetNote(
       return [
         `Ticket asset replaced: ${label} is now revision ${meta.revision} (${contents}).`,
         '',
-        'The contents live in the Autobuild store, not in this ticket. Earlier revisions stay retrievable.',
+        hosted
+          ? 'The contents live in the ticket service storage. Earlier revisions stay retrievable.'
+          : 'The contents live in the Autobuild store, not in this ticket. Earlier revisions stay retrievable.',
         `Download the latest revision: \`${get}\``,
         `Download this exact revision: \`${get} --rev ${meta.revision}\``,
       ].join('\n')

package/packages/core/src/cli/ticket-editor.ts

@@ -0,0 +1,82 @@
+import { mkdtemp, readFile, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { TicketSource, TicketUpdate } from '../ports/types'
+import { parseTicketFile, serializeTicketFile } from '../ports/tickets/file-codec'
+import { TicketRevisionUnsupported } from '../ports/tickets/revision'
+import { requireTicket, updateTicket } from '../ports/tickets/operations'
+
+export type TicketEditorRunner = (command: string, path: string) => Promise<number>
+
+/** The configured editor is a shell command; only our generated path is quoted. */
+export const runTicketEditor: TicketEditorRunner = async (command, path) => {
+  const quoted = `'${path.replaceAll("'", "'\\''")}'`
+  return Bun.spawn(['sh', '-c', `${command} ${quoted}`], {
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+  }).exited
+}
+
+export async function editTicket(
+  source: TicketSource,
+  id: string,
+  env: Record<string, string | undefined>,
+  stdout: (line: string) => void,
+  runner: TicketEditorRunner = runTicketEditor,
+): Promise<void> {
+  if (!source.mutateIfRevision) throw new TicketRevisionUnsupported(source.name)
+  const command = env.VISUAL?.trim() || env.EDITOR?.trim()
+  if (!command) throw new Error('set VISUAL or EDITOR to edit a ticket')
+  const ticket = await requireTicket(source, id)
+  const front = {
+    id,
+    title: ticket.title,
+    labels: [...ticket.labels],
+    blockedBy: [...(ticket.blockedBy ?? [])],
+    ...(ticket.creationKey !== undefined ? { idempotencyKey: ticket.creationKey } : {}),
+  }
+  // Reference comments remain part of the frontmatter, outside the editable keys.
+  const reference = `# Read-only reference\n# state = ${JSON.stringify(ticket.state ?? null)}\n# revision = ${JSON.stringify(ticket.revision)}\n`
+  const serialized = serializeTicketFile(front, ticket.body)
+  const original = serialized.replace('+++\n', `+++\n${reference}`)
+  const directory = await mkdtemp(join(tmpdir(), 'ab-ticket-edit-'))
+  const path = join(directory, 'ticket.md')
+  await writeFile(path, original, { mode: 0o600 })
+  try {
+    const code = await runner(command, path)
+    if (code !== 0) throw new Error(`editor exited with status ${code}`)
+    const edited = await readFile(path, 'utf8')
+    if (edited !== original) {
+      const parsed = parseTicketFile(path, edited)
+      const close = edited.indexOf('\n+++\n', 4)
+      const comments = edited
+        .slice(4, close)
+        .split('\n')
+        .filter((line) => line.trimStart().startsWith('#'))
+        .join('\n')
+      if (comments !== reference.trimEnd())
+        throw new Error('read-only reference comments cannot change')
+      if (
+        parsed.front.id !== id ||
+        parsed.front.idempotencyKey !== front.idempotencyKey ||
+        JSON.stringify(parsed.front.blockedBy ?? []) !== JSON.stringify(front.blockedBy)
+      )
+        throw new Error('id, idempotencyKey and blockedBy are read-only')
+      const patch: TicketUpdate = {}
+      if (parsed.front.title !== ticket.title) patch.title = parsed.front.title
+      if (parsed.body !== ticket.body) patch.body = parsed.body
+      if (JSON.stringify(parsed.front.labels) !== JSON.stringify(ticket.labels))
+        patch.labels = parsed.front.labels
+      if (Object.keys(patch).length > 0)
+        await updateTicket(source, id, patch, false, ticket.revision)
+    }
+    await rm(directory, { recursive: true })
+    stdout(`ticket edit complete: ${source.name}:${id}`)
+  } catch (error) {
+    throw new Error(
+      `${error instanceof Error ? error.message : String(error)}; edited text kept at ${path}`,
+      { cause: error },
+    )
+  }
+}