@danceiny/gotry 0.2.0-rc.29 → 0.2.0-rc.30

package/ts/src/index.ts

@@ -65,6 +65,7 @@ import { factsFromFlyai, factsFromHotel, factsFromSession, factsFromSessionTrain
 import { hasRecognizedAvailableSeat } from '../capabilities/session/adapters/rail-12306.ts'
 import { gateArtifact, type AirlineAirportMap } from './artifact-gate.ts'
 import { installTurnDeadline, listTurnHandoffTickets } from './turn-deadline.ts'
+import { startTurnHandoffJob } from './turn-handoff-job.ts'
 import { noteChannelVerdict, recordChannelEvent, readLatestChannelEvents } from '../capabilities/channel-health.ts'
 import { routingAdvice, renderRoutingCard, toolRoutingHeadline, persistedDownChannels, type ChannelIntent } from '../capabilities/channel-registry.ts'
 import { registerBenchmarkEnvironmentBridge, type BenchmarkSubprocessService } from './benchmark-environment-bridge.ts'
@@ -524,7 +525,11 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
     ? { fixedPolicy: { softMs: 300_000, hardMs: 900_000, exit: 'converge' } }
     : rawBenchmarkEnvironmentConfigPath.trim()
       ? { fixedPolicy: benchmarkPinnedPolicy() }
-      : { stateRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.' })
+      : { stateRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.',
+        // A one-shot headless process exits after its final response and cannot
+        // own ongoing work. Keep that ticket queued for explicit collection.
+        startHandoff: (ticket, agent, root) => typeof ctx.get === 'function' && ctx.get('connection')
+          ? startTurnHandoffJob(ctx, ticket, agent, root) : Promise.resolve(ticket) })
   if (rawBenchmarkEnvironmentConfigPath.trim()) {
     // Benchmark mode is a deliberately minimal kernel: only the model
     // override and the environment bridge are installed besides the pinned
@@ -1104,8 +1109,8 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
     name: 'gotry_turn_handoff_list',
     description:
       'List background deep-planning handoff tickets (read-only). Call this whenever the user asks about '
-      + 'a previously handed-off plan («规划好了吗» / «上次那个行程»): open = still being worked in the '
-      + 'background (ETA ' + '约 1 小时' + '), settled = deliverable ready (excerpt included, full text in the '
+      + 'a previously handed-off plan («规划好了吗» / «上次那个行程»): open = queued, worker not started; '
+      + 'running = started with a native job id (use job_list for live status); settled = deliverable ready (excerpt included, full text in the '
       + 'ticket\'s .deliverable.md), failed = honest failure note. Never fabricate a deliverable that is not here.',
     // D-30 第三刀(issue #112):query blob → 平铺 typed;全字段可选 → interpretArgs 容忍层(同 session 刀法)
     parameters: {
@@ -1115,9 +1120,10 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: String((value as { summary?: string }).summary ?? '') }],
     },
-    async execute(args, _exec: unknown) {
+    async execute(args, exec: unknown) {
       const q = interpretArgs<{ ticketId?: string }>(args)
-      const root = process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.'
+      const configuredRoot = process.env.GOTRY_TURN_HANDOFF_ROOT ?? config.stateRoot ?? '.'
+      const root = configuredRoot === '.' ? sessionCwd(exec) ?? '.' : configuredRoot
       const all = await listTurnHandoffTickets(root)
       const tickets = (q.ticketId ? all.filter(t => t.id === q.ticketId) : all).slice(0, 10)
       if (tickets.length === 0) {
@@ -1130,9 +1136,18 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       }
       const lines = tickets.map(t => {
         const head = `[${t.status}] ${t.id} ${t.objective.slice(0, 40)}`
-        if (t.status === 'open') return `${head}——后台规划中,ETA ${t.etaLabel}`
+        if (t.status === 'open') return `${head}——待启动，后台尚未运行`
+        if (t.status === 'running') {
+          const owner = (exec as { agent?: import('@deepseek-ai/dsh-agent').Agent }).agent
+          // Native counters restart with the host. A recycled id alone is not
+          // the durable ticket's identity and must not offer another trip's job.
+          const live = owner && ctx.get('jobs')?.list(owner.id).some(job => job.id === t.jobId
+            && job.owner === owner.id && job.kind === 'gotry-planning' && job.label.startsWith(`${t.id}: `)
+            && (job.status === 'running' || job.status === 'stopping'))
+          return `${head}——${live ? `后台任务 ${t.jobId}，预计 ${t.etaLabel}` : '运行记录已中断，当前没有活跃后台任务'} `
+        }
         if (t.status === 'failed') return `${head}——失败:${t.error ?? '未知原因'}(请重新发起规划)`
-        return `${head}——已交付,摘要:${(t.deliverableExcerpt ?? '').slice(0, 120).replace(/\n/g, ' ')}`
+        return `${head}——${t.deliverablePath ? `已交付：${t.deliverablePath}` : '交付文件缺失'}，摘要:${(t.deliverableExcerpt ?? '').slice(0, 120).replace(/\n/g, ' ')}`
       })
       return {
         ok: true, count: tickets.length, tickets,
@@ -2490,6 +2505,7 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       try {
         r = await listArtifacts({
           stateRoot: config.stateRoot ?? '.',
+          handoffRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? ((config.stateRoot ?? '.') === '.' ? sessionCwd(exec) ?? '.' : config.stateRoot),
           cwd: sessionCwd(exec),
           limit: q.limit,
           offset: q.offset,
@@ -2582,7 +2598,7 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       const q = args
       if (!q.path) throw new Error('gotry_artifacts_read requires path')
       if (!q.path) return JSON.parse(JSON.stringify({ ok: false, error: 'path 必填(来自 gotry_artifacts_list)' })) as Record<string, never>
-      const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', cwd: sessionCwd(exec), path: q.path, offset: q.offset, limit: q.limit })
+      const r = await readArtifact({ stateRoot: config.stateRoot ?? '.', handoffRoot: process.env.GOTRY_TURN_HANDOFF_ROOT ?? ((config.stateRoot ?? '.') === '.' ? sessionCwd(exec) ?? '.' : config.stateRoot), cwd: sessionCwd(exec), path: q.path, offset: q.offset, limit: q.limit })
       if (!r.ok) return JSON.parse(JSON.stringify(r)) as Record<string, never>
       // 身份/来源展示(issue #285 第 1 条「显示身份/来源」):行号视图保留 read 卡的
       // path/offset/lines/totalLines/lang;fallback content 用 source label 前缀,

package/ts/src/turn-deadline.ts

@@ -13,19 +13,19 @@
  *   `gotry_turn_handoff.v1` 工单并指令模型告知用户 ETA 与回访方式。
  * - handoff 工单是**新的独立格式**,落在 `<stateRoot>/gotry-state/
  *   turn-handoffs/`,不与 `async/` 的 loop 求解工单混用——async-collect
- *   对无 spec 的 state 会立即结算 failed(假失败),收集器是未来的
- *   agent tick(loopx),不是 async-collect。
+ *   对无 spec 的 state 会立即结算 failed(假失败)。产品通过原生 jobs
+ *   启动独立收集器;仅落单不代表后台已开始。
  */
 
 import { randomUUID } from 'node:crypto'
 import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 // 类型面显式依赖:session/event、session/disposed 的事件表声明在 dsh-session 的
 // cordis Events augmentation 里——不显式导入时,该声明只在 peer 恰好物化进
 // ts/node_modules 的机器上可见(legacy-peer-deps 安装则缺,5 个 TS2345/TS7006)。
-import type {} from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
 import { classifyTurn, TURN_HANDOFF_ETA_LABEL, turnPolicyFor, type TurnPolicy } from './turn-policy.ts'
 
@@ -41,7 +41,11 @@ export interface TurnHandoffTicket {
   userMessage: string
   requestedAt: string
   etaLabel: string
-  status: 'open' | 'settled' | 'failed'
+  status: 'open' | 'running' | 'settled' | 'failed'
+  jobId?: string
+  workspaceCwd?: string
+  ownerSessionId?: string
+  context?: string
   /** 结算时间(ISO);open 时缺省。 */
   settledAt?: string
   /** 结算交付物文件名(与工单同目录的 .deliverable.md)。 */
@@ -57,6 +61,8 @@ export interface TurnHandoffTicketView {
   objective: string
   requestedAt: string
   etaLabel: string
+  jobId?: string
+  deliverablePath?: string
   settledAt?: string
   error?: string
   deliverableExcerpt?: string
@@ -71,9 +77,37 @@ export interface TurnDeadlineOptions {
   stateRoot?: string
   /** Wall-clock source — overridden by tests for determinism. */
   now?: () => number
+  /** Product host owns dispatch and native job tracking. Absent means queued. */
+  startHandoff?: (ticket: TurnHandoffTicket, agent: Agent, stateRoot: string) => Promise<TurnHandoffTicket>
 }
 
-export async function writeTurnHandoffTicket(stateRoot: string, userMessage: string): Promise<TurnHandoffTicket> {
+function handoffContext(events: readonly SessionEvent[]): string | undefined {
+  const questionIds = new Set(events.filter(event => event.type === 'tool/call' && event.data.name === 'ask_user_question')
+    .map(event => event.type === 'tool/call' ? event.data.callId : ''))
+  // Human constraints are lossless. Refuse dispatch if they exceed the input
+  // budget; silently cutting an accessibility/budget answer changes the task.
+  const answers = events.filter(event => (event.type === 'user/message' && event.data.source.kind === 'user')
+    || (event.type === 'tool/call' && questionIds.has(event.data.callId))
+    || (event.type === 'tool/result' && event.data.message.source.kind === 'tool' && questionIds.has(event.data.message.source.callId)))
+    .map(event => JSON.stringify(event.data)).join('\n')
+  if (answers.length > 64_000) throw new Error('Prior user answers exceed the handoff context limit; planning paused without dropping constraints. Start a new session with the complete trip constraints.')
+  let remaining = 18_000
+  const evidence: string[] = []
+  for (const event of [...events].reverse()) {
+    if (event.type !== 'tool/result' || (event.data.message.source.kind === 'tool' && questionIds.has(event.data.message.source.callId))) continue
+    const row = JSON.stringify(event.data)
+    // Evidence may be excerpted, with an explicit marker and valid JSON.
+    const excerpt = row.length > remaining
+      ? JSON.stringify({ truncated: true, excerpt: row.slice(-Math.floor(remaining / 2)) }) : row
+    if (excerpt.length + 1 > remaining) break
+    evidence.unshift(excerpt)
+    remaining -= excerpt.length + 1
+    if (remaining < 100) break
+  }
+  return answers || evidence.length ? `${answers}\n${evidence.join('\n')}` : undefined
+}
+
+export async function writeTurnHandoffTicket(stateRoot: string, userMessage: string, details: Pick<TurnHandoffTicket, 'workspaceCwd' | 'ownerSessionId' | 'context'> = {}): Promise<TurnHandoffTicket> {
   const ticket: TurnHandoffTicket = {
     schema: TURN_HANDOFF_SCHEMA,
     id: `th-${Date.now().toString(36)}-${randomUUID().slice(0, 6)}`,
@@ -82,6 +116,7 @@ export async function writeTurnHandoffTicket(stateRoot: string, userMessage: str
     requestedAt: new Date().toISOString(),
     etaLabel: TURN_HANDOFF_ETA_LABEL,
     status: 'open',
+    ...details,
   }
   await writeTicketJson(stateRoot, ticket)
   return ticket
@@ -92,7 +127,7 @@ function handoffDir(stateRoot: string): string {
   return join(root, 'gotry-state', 'turn-handoffs')
 }
 
-async function writeTicketJson(stateRoot: string, ticket: TurnHandoffTicket): Promise<string> {
+export async function writeTicketJson(stateRoot: string, ticket: TurnHandoffTicket): Promise<string> {
   const dir = handoffDir(stateRoot)
   await mkdir(dir, { recursive: true })
   const path = join(dir, `${ticket.id}.json`)
@@ -151,12 +186,14 @@ export async function listTurnHandoffTickets(stateRoot: string): Promise<TurnHan
         objective: raw.objective,
         requestedAt: raw.requestedAt,
         etaLabel: raw.etaLabel,
+        ...(raw.jobId ? { jobId: raw.jobId } : {}),
         ...(raw.settledAt ? { settledAt: raw.settledAt } : {}),
         ...(raw.error ? { error: raw.error } : {}),
       }
-      if (raw.status !== 'open' && raw.deliverableFile) {
+      if ((raw.status === 'settled' || raw.status === 'failed') && raw.deliverableFile === `${raw.id}.deliverable.md`) {
         try {
           const text = await readFile(join(dir, raw.deliverableFile), 'utf-8')
+          view.deliverablePath = resolve(dir, raw.deliverableFile)
           view.deliverableExcerpt = text.length > 600 ? `${text.slice(0, 600)}…` : text
         } catch { /* 交付物缺失时视图降级,不阻塞列表 */ }
       }
@@ -200,7 +237,12 @@ function exhaustionResult(reason: string): ToolExecutionResult {
 }
 
 function handoffResult(ticket: TurnHandoffTicket): ToolExecutionResult {
-  const instruction = `Turn handed off to background planning. Async ticket ${ticket.id} created (ETA ${ticket.etaLabel}). Stop dispatching tools and tell the user in one short message: the deep planning continues in the background, the expected time, and to check back later (mention ticket ${ticket.id}).`
+  const state = ticket.status === 'running' && ticket.jobId
+    ? `Background planning started as native background job ${ticket.jobId} (estimated ${ticket.etaLabel}; not a guarantee). Track or cancel with job_list/job_output/job_kill.`
+    : ticket.status === 'failed'
+      ? `Background planning could not start: ${ticket.error ?? 'unknown failure'}. Tell the user it failed; do not promise later delivery.`
+      : 'The ticket is queued; the background worker has not started. Tell the user it is pending, not running; do not promise a completion time.'
+  const instruction = `Async ticket ${ticket.id} persisted. ${state} Stop research and answer from existing results. Never claim a file was created when its tool call failed or was refused. For any successfully written output, call present with its exact existing path before the final response. Mention ticket ${ticket.id}.`
   return {
     isError: true,
     error: {
@@ -221,6 +263,7 @@ type AgentTurnState = {
   startedAt: number
   policy: TurnPolicy
   userMessage?: string
+  handoff?: Promise<TurnHandoffTicket>
 }
 
 /**
@@ -250,6 +293,7 @@ export function installTurnDeadline(ctx: Context, options: TurnDeadlineOptions =
 
   const stateByAgent = new Map<string, AgentTurnState>()
   const softExecutions = new Map<ToolExecutionToken, { agentId: string; exit: string }>()
+  const handoffExecutions = new Map<ToolExecutionToken, { agentId: string; contexts: NonNullable<ToolExecutionResult['additionalContexts']> }>()
   const finalOnlyDisposers = new Map<string, () => void>()
 
   const clearAgent = (agentId: string) => {
@@ -257,6 +301,9 @@ export function installTurnDeadline(ctx: Context, options: TurnDeadlineOptions =
     for (const [token, owner] of softExecutions) {
       if (owner.agentId === agentId) softExecutions.delete(token)
     }
+    for (const [token, owner] of handoffExecutions) {
+      if (owner.agentId === agentId) handoffExecutions.delete(token)
+    }
     finalOnlyDisposers.get(agentId)?.()
     finalOnlyDisposers.delete(agentId)
   }
@@ -273,7 +320,7 @@ export function installTurnDeadline(ctx: Context, options: TurnDeadlineOptions =
     }
     const inheritedNames = globalTools.schemas()
       .map(schema => schema.name)
-      .filter(name => name !== 'run_code')
+      .filter(name => name !== 'run_code' && name !== 'present')
     if (inheritedNames.length === 0) return
     finalOnlyDisposers.set(agentId, scopedTools.restrict({ deny: inheritedNames }))
   }
@@ -324,18 +371,61 @@ export function installTurnDeadline(ctx: Context, options: TurnDeadlineOptions =
       ?? { startedAt: now(), policy: { ...defaultPolicy, softMs: softPin ?? defaultPolicy.softMs, hardMs: hardPin ?? defaultPolicy.hardMs } }
     stateByAgent.set(agentId, state)
 
+    // Present validates files on disk and publishes native deliverable events;
+    // it must remain callable after the research window closes.
+    if (exec.name === 'present') return next()
+
     const elapsed = now() - state.startedAt
     if (elapsed > state.policy.hardMs) {
-      // Synchronous schema suppression so same-step follow-up calls cannot
-      // loop on refusal results (the 2026-09-02 trajectory failure).
-      enterFinalOnly(exec.agent)
       if (state.policy.exit === 'handoff' && state.userMessage && options.stateRoot) {
-        return writeTurnHandoffTicket(options.stateRoot, state.userMessage)
-          .then(ticket => handoffResult(ticket))
+        const root = options.stateRoot === '.'
+          ? (exec.agent.session?.header.cwd ?? process.cwd()) : resolve(options.stateRoot)
+        const written = exec.name === 'write' && !state.handoff ? Promise.resolve().then(() => next()) : undefined
+        if (!state.handoff) {
+          const session = exec.agent.session
+          // Reserve the handoff before executing the write body. Parallel or
+          // repeated calls see the same promise and cannot write/dispatch twice.
+          state.handoff = (async () => {
+            try { await written } finally { enterFinalOnly(exec.agent!) }
+            let context: string | undefined
+            let contextError: string | undefined
+            try { context = handoffContext(session?.snapshotEvents() ?? []) }
+            catch (error) { contextError = error instanceof Error ? error.message : 'handoff context unavailable' }
+            const ticket = await writeTurnHandoffTicket(root, state.userMessage!, {
+              workspaceCwd: session?.header.cwd,
+              ownerSessionId: session ? String(session.id) : undefined,
+              context,
+            })
+            if (contextError) {
+              await settleTurnHandoffTicket(root, ticket, 'failed', `# Planning paused\n\n${contextError}`, contextError)
+              return { ...ticket, status: 'failed', error: contextError }
+            }
+            return options.startHandoff ? options.startHandoff(ticket, exec.agent!, root) : ticket
+          })()
+        }
+        // The triggering call may be the output write itself. Execute it once,
+        // preserve its actual outcome, then require native present. Attach a
+        // rejection handler now even if the pending tool itself rejects.
+        const handoff = state.handoff.then(handoffResult, () => exhaustionResult(`${TURN_DEADLINE_EXHAUSTED}: ticket persistence failed; no background worker was started`))
+        return (async () => {
+          const output = await written
+          const guidance = await handoff
+          if (output) {
+            handoffExecutions.set(exec.token, { agentId, contexts: guidance.additionalContexts ?? [] })
+            // Keep the registry's canonical result object. Rebuilding it after
+            // restricting inherited schemas would make DSH re-resolve a tool
+            // that has just been hidden and report UNKNOWN_TOOL after saving.
+            return output
+          }
+          return guidance
+        })()
           .catch(() => exhaustionResult(
             `${TURN_DEADLINE_EXHAUSTED}: hard deadline ${state.policy.hardMs}ms reached (ticket persistence failed; degraded to converge)`,
           ))
       }
+      // Suppress inherited research schemas immediately on refusal; DSH's
+      // scoped schemas remain visible but hit this same per-call guard.
+      enterFinalOnly(exec.agent)
       return Promise.resolve(exhaustionResult(
         `${TURN_DEADLINE_EXHAUSTED}: turn exceeded hard deadline of ${state.policy.hardMs}ms (elapsed ${elapsed}ms); provide a final answer using existing results`,
       ))
@@ -349,16 +439,19 @@ export function installTurnDeadline(ctx: Context, options: TurnDeadlineOptions =
   ctx.on('tools/post-execute', (exec, _result, next) => {
     return next().then(decision => {
       const owner = softExecutions.get(exec.token)
-      if (!owner) return decision
+      const handoff = handoffExecutions.get(exec.token)
+      handoffExecutions.delete(exec.token)
+      if (!owner && !handoff) return decision
       softExecutions.delete(exec.token)
-      const text = owner.exit === 'handoff'
+      const text = owner?.exit === 'handoff'
         ? 'Turn has crossed the soft deadline of a deep-planning turn. Wrap up context gathering now; the turn will hand off to background planning at the hard deadline.'
         : 'Turn has crossed the soft deadline. Stop dispatching new tools and produce the final answer from gathered evidence.'
       return {
         ...decision,
         additionalContexts: [
           ...(decision.additionalContexts ?? []),
-          convergenceContext(TURN_DEADLINE_SOFT, text) as never,
+          ...(handoff?.contexts ?? []),
+          ...(owner ? [convergenceContext(TURN_DEADLINE_SOFT, text) as never] : []),
         ],
       }
     })

package/ts/src/turn-handoff-job.ts

@@ -0,0 +1,120 @@
+/** Connect durable planning tickets to DSH's owned jobs and managed processes. */
+import { createRequire } from 'node:module'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { JobOutcome } from '@deepseek-ai/dsh-jobs'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
+import { settleTurnHandoffTicket, writeTicketJson, type TurnHandoffTicket } from './turn-deadline.ts'
+
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap { 'gotry-planning': 'gotry-planning' }
+}
+
+const require = createRequire(import.meta.url)
+
+export async function startTurnHandoffJob(
+  ctx: Context, ticket: TurnHandoffTicket, owner: Agent, stateRoot: string,
+): Promise<TurnHandoffTicket> {
+  if (ticket.status !== 'open') return ticket
+  const jobs = ctx.get('jobs')
+  const subprocess = ctx.get('subprocess')
+  if (!jobs || !subprocess) return ticket // Queued, never announced as running.
+  let current = ticket
+  let handle: SubprocessHandle | undefined
+  let cancelled = false
+  let release!: (ok: boolean) => void
+  const prepared = new Promise<boolean>(resolve => { release = resolve })
+  let announceStarted!: () => void
+  const started = new Promise<void>(resolve => { announceStarted = resolve })
+  const fail = async (reason: string) => {
+    await settleTurnHandoffTicket(stateRoot, current, 'failed', `# Planning failed\n\n${reason}\n\nNo completed plan was produced.`, reason)
+    current = { ...current, status: 'failed', error: reason }
+  }
+  try {
+    const jobId = jobs.start({
+      kind: 'gotry-planning', owner: owner.id, label: `${ticket.id}: ${ticket.objective.slice(0, 100)}`, outputLimitBytes: 12_000,
+      run() {
+        return {
+          cancel() { cancelled = true; handle?.terminate() },
+          done: (async (): Promise<JobOutcome> => {
+            if (!await prepared) { announceStarted(); return { status: 'failed', detail: 'ticket persistence failed' } }
+            let timer: ReturnType<typeof setTimeout> | undefined
+            try {
+              if (cancelled) throw new Error('planning cancelled')
+              const extension = import.meta.url.endsWith('.ts') ? 'ts' : 'js'
+              const collector = join(import.meta.dirname, '..', 'scripts', `turn-handoff-collect.${extension}`)
+              const argv = extension === 'ts'
+                ? [process.execPath, require.resolve('tsx/cli'), collector, ticket.id, stateRoot]
+                : [process.execPath, collector, ticket.id, stateRoot]
+              handle = subprocess.spawn({
+                argv, cwd: ticket.workspaceCwd ?? stateRoot,
+                stdio: { stdin: 'ignore', stdout: { maxBytes: 16_000 }, stderr: { maxBytes: 16_000 } },
+                // Collector cleanup includes the wrapper's detached DSH group
+                // (5s+1s), then its own 8s+1s bound and durable settlement.
+                graceMs: 11_000,
+                // This dedicated planning child inherits the configured model
+                // environment explicitly; secrets never enter tickets or output.
+                env: { GOTRY_HANDOFF_JOB_ID: current.jobId,
+                  GOTRY_HANDOFF_PLANNER_BIN: process.env.GOTRY_HANDOFF_PLANNER_BIN,
+                  GOTRY_HANDOFF_PLANNER_TIMEOUT_MS: process.env.GOTRY_HANDOFF_PLANNER_TIMEOUT_MS,
+                  DSH_HOME: process.env.DSH_HOME,
+                  LLM_API_KEY: process.env.LLM_API_KEY, LLM_BASE_URL: process.env.LLM_BASE_URL,
+                  LLM_MODEL: process.env.LLM_MODEL, GOTRY_LLM_MODEL: process.env.GOTRY_LLM_MODEL,
+                  DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL },
+              })
+              announceStarted()
+              const plannerTimeout = Number(process.env.GOTRY_HANDOFF_PLANNER_TIMEOUT_MS)
+              const timeout = Number.isSafeInteger(plannerTimeout) && plannerTimeout > 0 ? plannerTimeout : 900_000
+              timer = setTimeout(() => handle!.terminate(), timeout + 12_000)
+              const direct = await handle.done.then(
+                outcome => ({ ok: true as const, outcome }),
+                error => ({ ok: false as const, error }),
+              )
+              // Direct success or failure does not prove managed-range exit.
+              if (!direct.ok) handle.terminate()
+              try { await handle.waitForExit() }
+              catch (cleanupError) {
+                handle.terminate()
+                const cleanupDiagnostic = cleanupError instanceof Error ? cleanupError.message : 'unknown cleanup error'
+                const cleanupReason = `managed-range cleanup could not be confirmed: ${cleanupDiagnostic}`
+                if (!direct.ok) {
+                  const diagnostic = direct.error instanceof Error ? direct.error.message : 'planning failed'
+                  throw new AggregateError([direct.error, cleanupError], `${diagnostic}; ${cleanupReason}`)
+                }
+                throw new Error(cleanupReason, { cause: cleanupError })
+              }
+              if (!direct.ok) throw direct.error
+              const outcome = direct.outcome
+              const path = join(stateRoot, 'gotry-state', 'turn-handoffs', `${ticket.id}.json`)
+              const settled = JSON.parse(await readFile(path, 'utf8')) as TurnHandoffTicket
+              if (cancelled) throw new Error('planning cancelled')
+              if (outcome.exitCode !== 0 || settled.status !== 'settled' || settled.deliverableFile !== `${ticket.id}.deliverable.md`) {
+                throw new Error(settled.error ?? `planning collector failed (exit ${outcome.exitCode ?? outcome.signal})`)
+              }
+              const deliverablePath = join(stateRoot, 'gotry-state', 'turn-handoffs', settled.deliverableFile)
+              const content = await readFile(deliverablePath, 'utf8')
+              if (!content.trim()) throw new Error('planning collector produced an empty deliverable')
+              current = settled
+              return { status: 'completed', detail: `ticket ${ticket.id} settled`, result: `Planning completed: ${ticket.id}. Deliverable: ${deliverablePath}\nCall present with this exact path, then report the result.\n\n${content.slice(0, 8_000)}` }
+            } catch (error) {
+              const reason = error instanceof Error ? error.message : 'planning failed'
+              await fail(reason)
+              return { status: cancelled ? 'killed' : 'failed', detail: reason, result: `Ticket ${ticket.id} failed: ${reason}` }
+            } finally { if (timer) clearTimeout(timer); announceStarted() }
+          })(),
+        }
+      },
+    })
+    current = { ...ticket, status: 'running', jobId }
+    await writeTicketJson(stateRoot, current)
+    release(true)
+    await started
+    return current
+  } catch (error) {
+    release(false)
+    await fail(error instanceof Error ? error.message : 'background job registration failed')
+    return current
+  }
+}