@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.28

package/ts/src/booking-surface/error-codes.ts

@@ -0,0 +1,241 @@
+/** Closed, non-sensitive error vocabulary for planner/runtime boundaries. */
+export const BOOKING_TYPED_ERROR_CODES = [
+  'PAYLOAD_TOO_LARGE',
+  'TASK_NOT_FOUND',
+  'TASK_TERMINAL',
+  'RECEIPT_REQUIRED',
+  'RECEIPT_CONFLICT',
+  'UNSUPPORTED_ACTION',
+  'PLANNER_SURFACE_ACTION_UNSUPPORTED',
+  'PLANNER_NO_DECISION',
+  'PLANNER_TYPED_DECISION_REQUIRED',
+  'PLANNER_PROVIDER_AUTH_FAILED',
+  'PLANNER_PROVIDER_QUOTA_EXHAUSTED',
+  'PLANNER_PROVIDER_RATE_LIMITED',
+  'PLANNER_PROVIDER_UNAVAILABLE',
+  'PLANNER_PROVIDER_REQUEST_REJECTED',
+  'PLANNER_PROVIDER_RESPONSE_INVALID',
+  'PLANNER_PROVIDER_TIMEOUT',
+  'PLANNER_BOOT_TIMEOUT',
+  'PLANNER_CONFIGURATION_INVALID',
+  'PLANNER_FAILED',
+  'INVALID_ACTION',
+  'INVALID_EVENT',
+  'CONTEXT_MISMATCH',
+  'WORKSPACE_MISMATCH',
+  'ACTION_CONFLICT',
+  'STALE_REVISION',
+  'OPERATION_LIMIT_REACHED',
+  'AVAILABILITY_TERMINAL_POLICY_OWNED',
+  'TRUSTED_INGRESS_BINDING_REQUIRED',
+  'INVALID_INGRESS_BINDING',
+  'BOOKING_SURFACE_SCHEMA_MISMATCH',
+  'UNAUTHORIZED',
+  'NOT_FOUND',
+] as const
+
+export type BookingTypedErrorCode = typeof BOOKING_TYPED_ERROR_CODES[number]
+
+/** Exact, closed reasons safe to expose in dispatch diagnostics. */
+export const BOOKING_DISPATCH_REJECTION_REASONS = [
+  'approval_expired',
+  'approval_mismatch',
+  'approval_not_awaiting',
+  'approval_not_presented',
+  'approval_replayed',
+  'approval_required',
+  'availability_attempt_mismatch',
+  'availability_attempt_unknown',
+  'availability_criteria_changed',
+  'availability_criteria_invalid',
+  'availability_criteria_mismatch',
+  'availability_criteria_required',
+  'availability_duplicate_offer_ref',
+  'availability_duplicate_offer_version_ref',
+  'availability_expected_revision_missing',
+  'availability_generation_mismatch',
+  'availability_hotel_limit_exceeded',
+  'availability_hotel_not_active',
+  'availability_hotel_unknown',
+  'availability_observation_required',
+  'availability_offer_limit_exceeded',
+  'availability_offers_count_mismatch',
+  'availability_offers_hotel_mismatch',
+  'availability_offers_observation_required',
+  'availability_offers_receipt_incoherent',
+  'availability_offers_unreported',
+  'availability_offers_workspace_mismatch',
+  'availability_query_not_reserved',
+  'availability_query_provenance_mismatch',
+  'availability_query_receipt_mismatch',
+  'availability_receipt_digest_mismatch',
+  'availability_receipt_incoherent',
+  'availability_stale_receipt',
+  'availability_terminal',
+  'booking_malformed_workspace',
+  'context_mismatch',
+  'invalid_task_id',
+  'receipt_action_mismatch',
+  'receipt_conflict',
+  'receipt_observation_action_mismatch',
+  'receipt_relaxation_unauthorized',
+  'receipt_required',
+  'receipt_source_action_mismatch',
+  'receipt_source_digest_mismatch',
+  'receipt_target_mismatch',
+  'receipt_verified_offer_expired',
+  'reanchor_turn_required',
+  'request_conflict',
+  'request_key_invalidated',
+  'revision_mismatch',
+  'revision_regression',
+  'task_not_found',
+  'task_terminal',
+  'turn_conflict',
+  'unexpected_receipt',
+  'unsafe_opaque_ref',
+  'workspace_mismatch',
+] as const
+
+export type BookingDispatchRejectionReason = typeof BOOKING_DISPATCH_REJECTION_REASONS[number]
+export const BOOKING_DISPATCH_UNKNOWN_REASON = 'UNCLASSIFIED' as const
+export type BookingDispatchLogReason = BookingDispatchRejectionReason | typeof BOOKING_DISPATCH_UNKNOWN_REASON
+
+const DISPATCH_REJECTION_REASON_SET = new Set<string>(BOOKING_DISPATCH_REJECTION_REASONS)
+
+/** Returns a reason only when the complete boundary error is one known token. */
+export function extractBookingDispatchReason(error: unknown): BookingDispatchLogReason {
+  const message = typeof error === 'string' ? error : error instanceof Error ? error.message : undefined
+  return message !== undefined && DISPATCH_REJECTION_REASON_SET.has(message)
+    ? message as BookingDispatchRejectionReason
+    : BOOKING_DISPATCH_UNKNOWN_REASON
+}
+
+const ALIASES: Record<string, BookingTypedErrorCode> = {
+  payload_too_large: 'PAYLOAD_TOO_LARGE',
+  task_not_found: 'TASK_NOT_FOUND',
+  task_terminal: 'TASK_TERMINAL',
+  receipt_required: 'RECEIPT_REQUIRED',
+  receipt_conflict: 'RECEIPT_CONFLICT',
+  unsupported_action: 'UNSUPPORTED_ACTION',
+  planner_surface_action_unsupported: 'PLANNER_SURFACE_ACTION_UNSUPPORTED',
+  planner_no_decision: 'PLANNER_NO_DECISION',
+  planner_typed_decision_required: 'PLANNER_TYPED_DECISION_REQUIRED',
+  planner_provider_auth_failed: 'PLANNER_PROVIDER_AUTH_FAILED',
+  planner_provider_quota_exhausted: 'PLANNER_PROVIDER_QUOTA_EXHAUSTED',
+  planner_provider_rate_limited: 'PLANNER_PROVIDER_RATE_LIMITED',
+  planner_provider_unavailable: 'PLANNER_PROVIDER_UNAVAILABLE',
+  planner_provider_request_rejected: 'PLANNER_PROVIDER_REQUEST_REJECTED',
+  planner_provider_response_invalid: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_provider_timeout: 'PLANNER_PROVIDER_TIMEOUT',
+  planner_boot_timeout: 'PLANNER_BOOT_TIMEOUT',
+  planner_configuration_invalid: 'PLANNER_CONFIGURATION_INVALID',
+  planner_failed: 'PLANNER_FAILED',
+  planner_invalid_tool_arguments: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_invalid_typed_decision: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_invalid_action: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_booking_intent_required: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_invalid_booking_intent: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_ambiguous_booking_intent: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_multiple_typed_decisions: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_typed_decision_after_candidate: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_typed_decision_missing: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_unresolved_tool_call_before_candidate: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_tool_call_duplicate_call_id: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_tool_call_missing_call_id: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_tool_call_rejected: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_tool_result_malformed: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_tool_result_out_of_order: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_tool_result_unmatched: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_checkpoint_mismatch: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_checkpoint_unavailable: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_intent_criteria_unachieved: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_intent_target_unachieved: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_intent_unjustified: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_search_checkpoint_mismatch: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_search_patch_not_ready: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_search_results_not_ready: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_terminal_search_workspace_mismatch: 'PLANNER_PROVIDER_RESPONSE_INVALID',
+  planner_forbidden_action: 'UNSUPPORTED_ACTION',
+  planner_forbidden_tool: 'UNSUPPORTED_ACTION',
+  planner_capability_action_mismatch: 'UNSUPPORTED_ACTION',
+  planner_intent_target_unsupported: 'PLANNER_SURFACE_ACTION_UNSUPPORTED',
+  planner_context_mismatch: 'CONTEXT_MISMATCH',
+  planner_revision_mismatch: 'STALE_REVISION',
+  booking_intent_required: 'INVALID_ACTION',
+  invalid_booking_intent: 'INVALID_ACTION',
+  action_intent_mismatch: 'INVALID_ACTION',
+  intent_mutation_forbidden: 'INVALID_ACTION',
+  invalid_action: 'INVALID_ACTION',
+  invalid_event: 'INVALID_EVENT',
+  context_mismatch: 'CONTEXT_MISMATCH',
+  workspace_mismatch: 'WORKSPACE_MISMATCH',
+  action_conflict: 'ACTION_CONFLICT',
+  approval_replayed: 'ACTION_CONFLICT',
+  request_conflict: 'ACTION_CONFLICT',
+  turn_conflict: 'ACTION_CONFLICT',
+  stale_revision: 'STALE_REVISION',
+  operation_limit_reached: 'OPERATION_LIMIT_REACHED',
+  availability_terminal_policy_owned: 'AVAILABILITY_TERMINAL_POLICY_OWNED',
+  trusted_ingress_binding_required: 'TRUSTED_INGRESS_BINDING_REQUIRED',
+  invalid_ingress_binding: 'INVALID_INGRESS_BINDING',
+  booking_surface_schema_mismatch: 'BOOKING_SURFACE_SCHEMA_MISMATCH',
+  unauthorized: 'UNAUTHORIZED',
+  not_found: 'NOT_FOUND',
+}
+
+const SAFE_MESSAGES: Record<BookingTypedErrorCode, string> = {
+  PAYLOAD_TOO_LARGE: 'Request payload exceeds the configured limit.',
+  TASK_NOT_FOUND: 'The requested task was not found.',
+  TASK_TERMINAL: 'The task is already terminal.',
+  RECEIPT_REQUIRED: 'A matching receipt is required before another action.',
+  RECEIPT_CONFLICT: 'The receipt conflicts with the durable task record.',
+  UNSUPPORTED_ACTION: 'The requested action is outside the trusted action policy.',
+  PLANNER_SURFACE_ACTION_UNSUPPORTED: 'The planner action is outside the trusted surface policy.',
+  PLANNER_NO_DECISION: 'The planner returned no typed decision.',
+  PLANNER_TYPED_DECISION_REQUIRED: 'The planner returned no typed capability decision.',
+  PLANNER_PROVIDER_AUTH_FAILED: 'The planner provider rejected authentication.',
+  PLANNER_PROVIDER_QUOTA_EXHAUSTED: 'The planner provider quota is exhausted.',
+  PLANNER_PROVIDER_RATE_LIMITED: 'The planner provider rate-limited the request.',
+  PLANNER_PROVIDER_UNAVAILABLE: 'The planner provider is temporarily unavailable.',
+  PLANNER_PROVIDER_REQUEST_REJECTED: 'The planner provider rejected the model request.',
+  PLANNER_PROVIDER_RESPONSE_INVALID: 'The planner provider returned an invalid response.',
+  PLANNER_PROVIDER_TIMEOUT: 'The planner did not respond within the booking turn deadline.',
+  PLANNER_BOOT_TIMEOUT: 'The planner runtime did not finish starting within its local boot budget.',
+  PLANNER_CONFIGURATION_INVALID: 'The planner provider configuration is invalid.',
+  PLANNER_FAILED: 'The planner stopped unexpectedly before producing a usable action.',
+  INVALID_ACTION: 'The planner action failed contract validation.',
+  INVALID_EVENT: 'The planner event failed contract validation.',
+  CONTEXT_MISMATCH: 'The request context does not match the trusted task.',
+  WORKSPACE_MISMATCH: 'The request workspace does not match the trusted task.',
+  ACTION_CONFLICT: 'The request conflicts with the durable action checkpoint.',
+  STALE_REVISION: 'The request revision is stale.',
+  OPERATION_LIMIT_REACHED: 'The task operation limit has been reached.',
+  AVAILABILITY_TERMINAL_POLICY_OWNED: 'Availability policy owns the terminal decision.',
+  TRUSTED_INGRESS_BINDING_REQUIRED: 'A trusted ingress binding is required.',
+  INVALID_INGRESS_BINDING: 'The trusted ingress binding is invalid.',
+  BOOKING_SURFACE_SCHEMA_MISMATCH: 'The booking surface schema is not supported.',
+  UNAUTHORIZED: 'The request is not authorized.',
+  NOT_FOUND: 'The requested resource was not found.',
+}
+
+function rawCode(error: unknown): string {
+  if (typeof error === 'string') return error.split(':', 1)[0]!
+  if (error instanceof Error && error.message) return error.message.split(':', 1)[0]!
+  return 'planner_failed'
+}
+
+export function normalizeBookingErrorCode(error: unknown): BookingTypedErrorCode {
+  const raw = rawCode(error)
+  const normalized = raw.trim().toLowerCase()
+  const aliased = ALIASES[normalized]
+  if (aliased) return aliased
+  const uppercase = raw.trim().replace(/[^A-Za-z0-9]+/g, '_').toUpperCase()
+  return (BOOKING_TYPED_ERROR_CODES as readonly string[]).includes(uppercase)
+    ? uppercase as BookingTypedErrorCode
+    : 'PLANNER_FAILED'
+}
+
+export function safeBookingErrorMessage(code: string): string {
+  return SAFE_MESSAGES[(BOOKING_TYPED_ERROR_CODES as readonly string[]).includes(code) ? code as BookingTypedErrorCode : 'PLANNER_FAILED']
+}

package/ts/src/booking-surface/index.ts

@@ -0,0 +1,9 @@
+export * from './contracts.ts'
+export * from './dsh-planner.ts'
+export * from './profile.ts'
+export * from './runtime.ts'
+export * from './server.ts'
+export * from './startup.ts'
+export * from './validation.ts'
+export * from './availability-policy.ts'
+export * from './booking-intent.ts'

package/ts/src/booking-surface/managed-dsh-cleanup-diagnostic.ts

@@ -0,0 +1,151 @@
+import { execFile } from 'node:child_process'
+
+export type ManagedDshWorkerOutcome =
+  | { state: 'pending' }
+  | { state: 'exited'; exitCode: number | null; signal: string | null }
+  | { state: 'failed' }
+
+export interface ManagedDshGroupMember {
+  pid: number
+  ppid: number
+  pgid: number
+  state: string
+  /** Read-only `ps lstart` identity evidence; zombies keep their original start time. */
+  startedAt: string | null
+  zombie: boolean
+}
+
+/**
+ * `has-live-members`: at least one non-zombie member remains. `zombie-only`:
+ * every remaining member is a dead-but-unreaped zombie. `empty`: the group has
+ * no visible member. On Darwin the detached-fallback observation
+ * (`kill(-pgid, 0)`) cannot distinguish these: it returns EPERM for
+ * zombie-only groups, which the runtime maps to "alive".
+ */
+export type ManagedDshGroupClassification = 'empty' | 'zombie-only' | 'has-live-members'
+
+export interface ManagedDshProcessGroupSnapshot {
+  status: 'observed' | 'unavailable' | 'unsupported' | 'unknown_worker'
+  expectedPgid: number | null
+  members: ManagedDshGroupMember[]
+  truncated: boolean
+  classification: ManagedDshGroupClassification | null
+  liveMemberCount: number | null
+  zombieMemberCount: number | null
+  /** Start-time anchor captured while the worker was alive, for identity comparison. */
+  workerStartedAt: string | null
+  workerIdentity: 'match' | 'mismatch' | 'worker-absent' | 'unknown' | null
+}
+
+export interface ManagedDshCleanupDiagnostic {
+  schemaVersion: 'managed-dsh-cleanup.v2'
+  role: 'task' | 'warmer' | 'unspecified'
+  workerPid: number | null
+  elapsedMs: number
+  deadlineMs: number
+  graceMs: number
+  workerOutcome: ManagedDshWorkerOutcome
+  processGroup: ManagedDshProcessGroupSnapshot
+}
+
+/** Diagnostics never include argv, environment, provider output or request data. */
+export class ManagedDshCleanupError extends Error {
+  constructor(message: string, readonly diagnostic: ManagedDshCleanupDiagnostic) {
+    // Keep the safe snapshot visible even when nested AggregateError inspection
+    // collapses custom object properties in an uncaught-error log.
+    super(`${message}; diagnostic=${JSON.stringify(diagnostic)}`)
+    this.name = 'ManagedDshCleanupError'
+  }
+}
+
+const MEMBER_LINE = /^(\d+)\s+(\d+)\s+(\d+)\s+([A-Za-z+<NsLlEWXU-]+)\s+(.+?)\s*$/
+const MAX_MEMBERS = 32
+
+/**
+ * Classify one `ps -axo pid=,ppid=,pgid=,stat=,lstart=` table for the owned
+ * group. Pure so proofs can feed crafted tables without signalling anything.
+ */
+export function parseManagedDshGroupSnapshot(
+  stdout: string,
+  expectedPgid: number | null,
+  workerStartedAt: string | null = null,
+): ManagedDshProcessGroupSnapshot {
+  const empty = {
+    status: 'unknown_worker', expectedPgid, members: [], truncated: false, classification: null,
+    liveMemberCount: null, zombieMemberCount: null, workerStartedAt, workerIdentity: null,
+  } as ManagedDshProcessGroupSnapshot
+  if (expectedPgid === null) return { ...empty, status: 'unknown_worker' }
+  const members: ManagedDshGroupMember[] = []
+  for (const line of stdout.split('\n')) {
+    const match = line.trim().match(MEMBER_LINE)
+    if (!match || Number(match[3]) !== expectedPgid) continue
+    members.push({
+      pid: Number(match[1]), ppid: Number(match[2]), pgid: Number(match[3]),
+      state: match[4], startedAt: match[5] ?? null, zombie: match[4].startsWith('Z'),
+    })
+  }
+  const liveMemberCount = members.filter((member) => !member.zombie).length
+  const zombieMemberCount = members.length - liveMemberCount
+  const classification: ManagedDshGroupClassification =
+    members.length === 0 ? 'empty' : liveMemberCount === 0 ? 'zombie-only' : 'has-live-members'
+  let workerIdentity: ManagedDshProcessGroupSnapshot['workerIdentity'] = 'unknown'
+  if (workerStartedAt !== null) {
+    const workerRow = members.find((member) => member.pid === expectedPgid)
+    workerIdentity = workerRow === undefined
+      ? 'worker-absent'
+      : workerRow.startedAt === workerStartedAt ? 'match' : 'mismatch'
+  }
+  return {
+    status: 'observed', expectedPgid,
+    members: members.slice(0, MAX_MEMBERS), truncated: members.length > MAX_MEMBERS,
+    classification, liveMemberCount, zombieMemberCount,
+    workerStartedAt, workerIdentity,
+  }
+}
+
+/** Whether the snapshot proves the owned group holds no live member. */
+export function managedDshGroupIsQuiescent(group: ManagedDshProcessGroupSnapshot): boolean {
+  return group.status === 'observed' && (group.classification === 'empty' || group.classification === 'zombie-only')
+}
+
+/** Read-only one-shot start-time anchor for the live worker (Darwin only). */
+export function readManagedDshWorkerStart(pid: number): Promise<string | null> {
+  if (process.platform !== 'darwin') return Promise.resolve(null)
+  return new Promise((resolve) => {
+    execFile('/bin/ps', ['-p', String(pid), '-o', 'lstart='], {
+      encoding: 'utf8', timeout: 250, maxBuffer: 4096,
+      env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' },
+    }, (error, stdout) => resolve(error ? null : stdout.trim() || null))
+  })
+}
+
+/**
+ * Observe only the detached worker's group, without signalling any process.
+ * Snapshot fields are limited to pid/ppid/pgid/state/start time — never argv,
+ * environment, or request content.
+ */
+export async function snapshotManagedDshGroup(
+  workerPid: number | null,
+  workerStartedAt: string | null = null,
+): Promise<ManagedDshProcessGroupSnapshot> {
+  const empty = {
+    status: 'unknown_worker', expectedPgid: null, members: [], truncated: false, classification: null,
+    liveMemberCount: null, zombieMemberCount: null, workerStartedAt, workerIdentity: null,
+  } as ManagedDshProcessGroupSnapshot
+  if (workerPid === null) return { ...empty, status: 'unknown_worker' }
+  // Only Darwin's installed detached fallback establishes PID == PGID here.
+  // Linux native scopes and Windows Jobs require a provider range identity,
+  // so an unsupported platform claims no expected group at all.
+  if (process.platform !== 'darwin') return { ...empty, status: 'unsupported' }
+  return new Promise((resolve) => {
+    // A separate, bounded failure-only observation; it does not extend the
+    // provider's cleanup deadline or change its success/failure verdict.
+    execFile('/bin/ps', ['-axo', 'pid=,ppid=,pgid=,stat=,lstart='], {
+      encoding: 'utf8', timeout: 250, maxBuffer: 1024 * 1024,
+      env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' },
+    }, (error, stdout) => {
+      if (error) return resolve({ ...empty, expectedPgid: workerPid, status: 'unavailable' })
+      resolve(parseManagedDshGroupSnapshot(stdout, workerPid, workerStartedAt))
+    })
+  })
+}

package/ts/src/booking-surface/managed-dsh-run-port.ts

@@ -0,0 +1,273 @@
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { createRequire } from 'node:module'
+import { Context } from '@deepseek-ai/cordis'
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
+import type { SubprocessHandle } from '@deepseek-ai/dsh-subprocess'
+import type { DshBootObservation, DshPlannerRunPort, DshPlannerRunResult } from './dsh-planner.ts'
+import {
+  ManagedDshCleanupError,
+  managedDshGroupIsQuiescent,
+  readManagedDshWorkerStart,
+  snapshotManagedDshGroup,
+  type ManagedDshProcessGroupSnapshot,
+  type ManagedDshWorkerOutcome,
+} from './managed-dsh-cleanup-diagnostic.ts'
+
+export interface ManagedDshRunPortOptions {
+  cwd?: string
+  workerPath?: string
+  graceMs?: number
+  cleanupRole?: 'task' | 'warmer'
+  env?: NodeJS.ProcessEnv
+  /** Test seam overriding the failure-path group snapshot; production uses the safe ps snapshot. */
+  groupObserver?: typeof snapshotManagedDshGroup
+  /**
+   * Boot-marker channel (#511): receives one `HARNESS_BOOT_STAGE …` line per
+   * completed initialize handshake and one `HARNESS_BOOT_TIMEOUT …` line when
+   * the worker's own handshake deadline expires. Defaults to process stderr —
+   * the serving process log surface these markers were missing from.
+   */
+  bootLog?: (line: string) => void
+  [key: string]: unknown
+}
+
+/** The only worker failure classifications allowed to cross the process boundary. */
+const WORKER_FAILURE_CODES = new Set(['HARNESS_BOOT_TIMEOUT', 'HARNESS_START_FAILED', 'HARNESS_RUN_FAILED'])
+
+const requireFromModule = createRequire(import.meta.url)
+
+function workerLaunch(path: string): readonly string[] {
+  // The worker cwd is the isolated booking state root, so a bare `tsx/esm`
+  // loader would resolve from the wrong dependency tree and exit before the
+  // first request. Resolve the loader from this package once and pass its
+  // absolute installed path to Node.
+  return path.endsWith('.ts')
+    ? [process.execPath, '--import', requireFromModule.resolve('tsx/esm'), path]
+    : [process.execPath, path]
+}
+
+/** Run DeepSeekHarness in a child tree owned by dsh-subprocess-local. */
+export class ManagedDshRunPort implements DshPlannerRunPort {
+  private readonly handle: SubprocessHandle
+  private readonly runtime: LocalSubprocessRuntime
+  private readonly pending = new Map<number, { ok: (value?: DshPlannerRunResult) => void; fail: (error: Error) => void; progress?: () => void }>()
+  private sequence = 0
+  private closePromise: Promise<void> | undefined
+  private terminalError: Error | undefined
+  private inputBuffer = ''
+  private workerPid: number | null = null
+  private workerStartedAt: string | null = null
+  private workerOutcome: ManagedDshWorkerOutcome = { state: 'pending' }
+  private readonly cleanupRole: 'task' | 'warmer' | 'unspecified'
+  private readonly graceMs: number
+
+  constructor(options: ManagedDshRunPortOptions = {}) {
+    const defaultWorker = join(dirname(fileURLToPath(import.meta.url)), 'dsh-worker.js')
+    const workerPath = options.workerPath ?? (existsSync(defaultWorker) ? defaultWorker : defaultWorker.replace(/\.js$/, '.ts'))
+    const { workerPath: _worker, graceMs = 500, cleanupRole, env, groupObserver, bootLog, ...harnessOptions } = options
+    this.cleanupRole = cleanupRole ?? 'unspecified'
+    this.graceMs = graceMs
+    this.groupObserver = groupObserver ?? snapshotManagedDshGroup
+    this.bootLog = bootLog ?? ((line: string) => { process.stderr.write(`${line}\n`) })
+    this.constructedAtMs = Date.now()
+    this.runtime = new LocalSubprocessRuntime(new Context())
+    this.handle = this.runtime.spawn({
+      argv: workerLaunch(workerPath),
+      cwd: options.cwd ?? process.cwd(),
+      // Provider diagnostics may contain request fragments. Keep a bounded
+      // private tail for ownership without inheriting it into service logs.
+      stdio: { stdin: 'pipe', stdout: 'pipe', stderr: { maxBytes: 64 * 1024 } },
+      graceMs,
+      env,
+    })
+    this.handle.stdout!.setEncoding('utf8')
+    this.handle.stdout!.on('data', (chunk: string) => this.consume(chunk))
+    this.handle.done.then(
+      (outcome) => {
+        this.workerOutcome = { state: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+        this.markTerminal('managed DSH worker exited')
+      },
+      () => {
+        this.workerOutcome = { state: 'failed' }
+        this.markTerminal('managed DSH worker failed')
+      },
+    )
+    // Credentials are already in the managed worker environment. Never copy
+    // them into the JSON-lines protocol or a thrown worker error.
+    this.harnessOptions = harnessOptions
+    this.cleanupDeadlineMs = Math.max(1_000, graceMs * 4)
+  }
+
+  private readonly harnessOptions: Record<string, unknown>
+  private readonly cleanupDeadlineMs: number
+  private readonly groupObserver: typeof snapshotManagedDshGroup
+  private readonly bootLog: (line: string) => void
+  private readonly constructedAtMs: number
+  private booted: DshBootObservation | undefined
+
+  /**
+   * #511: surface the boot markers in the serving process. The four startup
+   * marker families previously existed only in build-time proof output, so a
+   * recurrence in service runtime left nothing to grep. Payloads are closed
+   * shapes only — role, timings; never prompts, provider fragments, or
+   * credentials.
+   */
+  private emitBootLog(line: string): void {
+    try {
+      this.bootLog(line)
+    } catch { /* boot markers must never break the worker protocol */ }
+  }
+
+  /**
+   * What the most recent worker request paid for the initialize handshake: the
+   * measured wall time when that request started the runtime, and zero when an
+   * earlier request in the same worker already had. Read by the planner to keep
+   * our own boot cost separate from the provider budget it must not consume.
+   */
+  bootObservation(): DshBootObservation | undefined {
+    return this.booted
+  }
+
+  private consume(chunk: string): void {
+    this.inputBuffer += chunk
+    for (;;) {
+      const newline = this.inputBuffer.indexOf('\n')
+      if (newline < 0) return
+      const line = this.inputBuffer.slice(0, newline); this.inputBuffer = this.inputBuffer.slice(newline + 1)
+      try {
+        const message = JSON.parse(line) as { id: number; ok?: boolean; progress?: boolean; result?: DshPlannerRunResult; error?: string; lifecycle?: string; workerPid?: number; parentPid?: number; boot?: DshBootObservation }
+        if (message.lifecycle === 'worker_started') {
+          if (this.workerPid === null && Number.isSafeInteger(message.workerPid) && message.workerPid! > 0 && message.parentPid === process.pid) {
+            this.workerPid = message.workerPid!
+            // One bounded read-only start-time anchor, captured while the worker
+            // is alive, so a later failure snapshot can disprove PID reuse.
+            void readManagedDshWorkerStart(this.workerPid).then((startedAt) => {
+              if (this.workerStartedAt === null) this.workerStartedAt = startedAt
+            })
+          }
+          continue
+        }
+        if (message.progress) {
+          this.pending.get(message.id)?.progress?.()
+          continue
+        }
+        // A boot checkpoint carries the initialize handshake the worker already
+        // completed; the terminal reply for the same request still follows, and
+        // a request killed after booting has left this measurement behind.
+        if (message.boot) {
+          this.booted = message.boot
+          // One line per real subprocess boot (#511): only a 'started'
+          // handshake measured an initialize; 'reused' rode an earlier one.
+          if (message.boot.mode === 'started') {
+            this.emitBootLog(`HARNESS_BOOT_STAGE ${JSON.stringify({ role: this.cleanupRole, initializeMs: message.boot.initializeMs, mode: 'started' })}`)
+          }
+          if (message.ok === undefined) continue
+        }
+        const waiter = this.pending.get(message.id); if (!waiter) continue
+        this.pending.delete(message.id)
+        if (message.ok) waiter.ok(message.result)
+        // Worker stdout is a process boundary: an arbitrary payload must never
+        // become the error the planner classifies on.
+        else if (typeof message.error === 'string' && WORKER_FAILURE_CODES.has(message.error)) {
+          if (message.error === 'HARNESS_BOOT_TIMEOUT') {
+            // The worker's own initialize deadline expired before any handshake
+            // completed; record the closed classification plus what this port
+            // observable spent on it (closeMs belongs to cleanup diagnostics).
+            this.emitBootLog(`HARNESS_BOOT_TIMEOUT ${JSON.stringify({
+              role: this.cleanupRole,
+              elapsedMs: Date.now() - this.constructedAtMs,
+              initializeMs: this.booted?.initializeMs ?? null,
+            })}`)
+          }
+          waiter.fail(new Error(message.error))
+        }
+        else waiter.fail(new Error('HARNESS_RUN_FAILED'))
+      } catch (error) { this.failPending(error instanceof Error ? error : new Error(String(error))) }
+    }
+  }
+
+  private failPending(error: Error): void {
+    for (const waiter of this.pending.values()) waiter.fail(error)
+    this.pending.clear()
+  }
+
+  private markTerminal(message: string): void {
+    // Retain a safe terminal outcome before rejecting existing waiters: their
+    // continuations may immediately submit another request to this same port.
+    this.terminalError ??= new Error(message)
+    this.failPending(this.terminalError)
+  }
+
+  run(prompt: string, options: { sessionId: string; onProgress?: () => void }): Promise<DshPlannerRunResult> {
+    if (this.closePromise) return Promise.reject(new Error('managed DSH run port is closed'))
+    if (this.terminalError) return Promise.reject(this.terminalError)
+    const id = ++this.sequence
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { ok: (value) => resolve(value as DshPlannerRunResult), fail: reject, progress: options.onProgress })
+      this.handle.stdin!.write(`${JSON.stringify({ id, prompt, sessionId: options.sessionId, options: this.harnessOptions })}\n`)
+    })
+  }
+
+  /** Boot the in-worker harness without consuming a provider call. */
+  warmup(): Promise<void> {
+    if (this.closePromise) return Promise.reject(new Error('managed DSH run port is closed'))
+    if (this.terminalError) return Promise.reject(this.terminalError)
+    const id = ++this.sequence
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { ok: () => resolve(), fail: reject })
+      this.handle.stdin!.write(`${JSON.stringify({ id, warmup: true, options: this.harnessOptions })}\n`)
+    })
+  }
+
+  close(): Promise<void> {
+    if (this.closePromise) return this.closePromise
+    this.closePromise = (async () => {
+      const started = performance.now()
+      this.failPending(new Error('managed DSH run port closed'))
+      this.handle.terminate()
+      // Observe worker failure even if range observation rejects or times out
+      // first. This derived promise must never become an unhandled rejection.
+      const outcome = this.handle.done.then(
+        () => undefined,
+        () => new Error('managed DSH worker failed'),
+      )
+      let rangeEmpty: boolean
+      try {
+        rangeEmpty = await this.handle.waitForExit(AbortSignal.timeout(this.cleanupDeadlineMs))
+      } catch {
+        throw await this.cleanupError('managed DSH process tree observation failed', started)
+      }
+      if (!rangeEmpty) {
+        // On Darwin the installed detached fallback observes the group through
+        // kill(-pgid, 0): a zombie-only group yields EPERM, which the runtime
+        // maps to "alive", and zombies only disappear when their owner reaps
+        // them — no signal can accelerate that. The deadline has not moved;
+        // verify through the safe process table whether a live member actually
+        // remains before converting the observation deadline into a failure.
+        const processGroup = await this.groupObserver(this.workerPid, this.workerStartedAt)
+        if (!managedDshGroupIsQuiescent(processGroup)) {
+          throw await this.cleanupError('managed DSH process tree cleanup timeout', started, processGroup)
+        }
+      }
+      if (await outcome) throw await this.cleanupError('managed DSH worker failed', started)
+    })()
+    return this.closePromise
+  }
+
+  private async cleanupError(message: string, started: number, processGroup?: ManagedDshProcessGroupSnapshot): Promise<ManagedDshCleanupError> {
+    const elapsedMs = Math.round(performance.now() - started)
+    const workerOutcome = { ...this.workerOutcome }
+    const group = processGroup ?? await this.groupObserver(this.workerPid, this.workerStartedAt)
+    return new ManagedDshCleanupError(message, {
+      schemaVersion: 'managed-dsh-cleanup.v2', role: this.cleanupRole,
+      workerPid: this.workerPid, elapsedMs, deadlineMs: this.cleanupDeadlineMs,
+      graceMs: this.graceMs, workerOutcome, processGroup: group,
+    })
+  }
+}
+
+export function createManagedDshRunPort(options?: ManagedDshRunPortOptions): DshPlannerRunPort {
+  return new ManagedDshRunPort(options)
+}