@danceiny/gotry 0.2.0-rc.31 → 0.2.0-rc.33

package/ts/src/booking-surface/dsh-planner.ts

@@ -15,6 +15,8 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { BOOKING_READ_ACTION_KINDS, type ActionReceipt, type BookingCopilotTurn, type BookingReadAction, type SearchCriteriaPatch } from './contracts.ts'
 import { buildTimeAnchor } from '../time-anchor.ts'
+import { assertPromptCachePartition } from '../tenant-state/ids.ts'
+import type { LlmTicketIssuer } from '../tenant-seam/llm-broker.ts'
 export { formatUtcOffsetLabel } from '../time-anchor.ts'
 import {
   actionsForEmbeddedCapability,
@@ -26,7 +28,7 @@ import {
   validateBookingIntentProjection,
   bookingSurfaceSchema,
 } from './validation.ts'
-import { createManagedDshRunPort } from './managed-dsh-run-port.ts'
+import { assertManagedDshLimitsEnforceable, createManagedDshRunPort, ManagedDshResourceLimitError, type ManagedDshResourceLimits } from './managed-dsh-run-port.ts'
 import {
   BOOKING_INTENT_SCHEMA_VERSION,
   BOOKING_INTENT_TARGET_ACTION,
@@ -103,7 +105,7 @@ export interface DshPlannerRunPort {
 export type DshPlannerClock = Date | (() => Date)
 
 export interface DshPlannerTurnMetric {
-  outcome: 'operation' | 'terminal' | 'provider_error' | 'timeout' | 'boot_timeout' | 'typed_decision_required' | 'failed'
+  outcome: 'operation' | 'terminal' | 'provider_error' | 'timeout' | 'boot_timeout' | 'typed_decision_required' | 'failed' | 'resource_limit'
   decisionSource: 'runtime' | 'model'
   elapsedMs: number
   /** Calls across the Harness run/session seam; one run can contain repairs. */
@@ -138,6 +140,8 @@ export interface DshEmbeddedBookingPlannerOptions {
   dshBin?: string
   provider?: string
   model?: string
+  /** Explicit path for the chat-completions gateway LLM plugin; defaults to the sibling dsh-llm-gateway-chat.js. */
+  gatewayLlmPluginPath?: string
   reasoningEffort?: 'off' | 'low' | 'high' | 'max'
   maxTokens?: number
   /** Total wall-clock budget across all repair attempts for one planner turn. */
@@ -154,6 +158,25 @@ export interface DshEmbeddedBookingPlannerOptions {
   onMetric?: (metric: DshPlannerTurnMetric) => void
   env?: Record<string, string | undefined>
   pluginPath?: string
+  /**
+   * Credential custody (AaaS, docs/rfc/aaas-rfc.md §4.8, threat S-18). When set, no Harness process ever holds the
+   * upstream key or base URL: each real port is given a short-lived loopback ticket from this issuer instead, revoked
+   * when the port closes, and any key in `env` is stripped from the child. Requires the chat-completions route
+   * (`DEEPSEEK_PROVIDER=gateway-chat`), the only wire dialect the broker carries. Absent: the child holds the key, as before.
+   */
+  llmTickets?: LlmTicketIssuer
+  /**
+   * The tenant's prompt cache partition label (AaaS, docs/rfc/aaas-rfc.md §4.8, threat S-16). When set, every prompt
+   * carries it right after the shared instructions and ahead of all tenant-derived content, so a provider that caches
+   * by prefix cannot share a cached prefix between two tenants past that point. Absent (the shared form): no label,
+   * and the prompt is byte-identical to what it was.
+   */
+  cachePartition?: string
+  /**
+   * Ceilings for each real Harness process tree (AaaS, docs/rfc/aaas-rfc.md §4.8). A tree over a ceiling is killed and
+   * the turn ends as a non-retryable `PLANNER_FAILED`; it is never retried on a fresh port. Absent: none, as before.
+   */
+  resourceLimits?: ManagedDshResourceLimits
 }
 
 export interface DshEmbeddedBookingPlannerHandle {
@@ -208,6 +231,10 @@ export function buildDshPlannerEnvironment(
   if (baseUrl) target.DEEPSEEK_BASE_URL = baseUrl
   if (model) target.DEEPSEEK_MODEL = model
   if (maxTokens) target.DEEPSEEK_MAX_TOKENS = maxTokens
+  // Wire-protocol selection rides the same namespace: 'gateway-chat' routes the
+  // child at the chat-completions adapter plugin (dsh-llm-gateway-chat.js)
+  // instead of the SDK's bundled Messages adapter.
+  if (source.DEEPSEEK_PROVIDER) target.DEEPSEEK_PROVIDER = source.DEEPSEEK_PROVIDER
   return target
 }
 
@@ -232,8 +259,8 @@ function quoteYaml(value: string): string {
 }
 
 /** Runtime patch over dsh's sdk-minimal profile: one typed planner tool per action kind. */
-export function buildDshEmbeddedBookingPatch(pluginPath: string): string {
-  return `# GoTry embedded Booking Copilot: typed planning only; no browser, shell, files, Book, or persisted chat.\n\
+export function buildDshEmbeddedBookingPatch(pluginPath: string, gatewayLlmPluginPath = ''): string {
+  const patchBody = `# GoTry embedded Booking Copilot: typed planning only; no browser, shell, files, Book, or persisted chat.\n\
 - id: deepseek-llm-api-extensions\n  disabled: true\n\
 - id: session-log-deepseek\n  disabled: true\n\
 - id: plugin-package-inventory-deepseek\n  disabled: true\n\
@@ -292,10 +319,14 @@ export function buildDshEmbeddedBookingPatch(pluginPath: string): string {
     skills:\n\
       enabled: false\n\
     toolBash: false\n\
-    toolJobs: false\n\
-- insert:\n\
-    - id: gotry-embedded-booking\n\
-      name: ${quoteYaml(pluginPath)}\n`
+    toolJobs: false\n`
+  const inserts = [
+    `- insert:\n    - id: gotry-embedded-booking\n      name: ${quoteYaml(pluginPath)}\n`,
+    ...(gatewayLlmPluginPath
+      ? [`- insert:\n    - id: llm-gateway-chat\n      name: ${quoteYaml(gatewayLlmPluginPath)}\n`]
+      : []),
+  ]
+  return patchBody + inserts.join('')
 }
 
 interface ResolvedRealRunPortConfig {
@@ -312,9 +343,21 @@ interface ResolvedRealRunPortConfig {
 // DEEPSEEK_MODEL could otherwise be absorbed silently.
 export function resolveRealRunPortConfig(options: DshEmbeddedBookingPlannerOptions): ResolvedRealRunPortConfig {
   const sourceEnv = options.env ?? process.env
-  const childEnv = buildDshPlannerEnvironment(sourceEnv)
-  if (!childEnv.DEEPSEEK_API_KEY) throw new Error('booking_planner_model_key_required')
-  const provider = options.provider?.trim() || 'deepseek-official'
+  // The route settings (provider, model, token budget) are read from the namespace the credential selects. A deployment
+  // that keeps the key in the broker may have none in its environment; the DeepSeek namespace is then the route's, and
+  // the placeholder below only selects it: it is removed from the child's environment before anything uses it.
+  const routeSource = options.llmTickets && !sourceEnv.DEEPSEEK_API_KEY && !sourceEnv.LLM_API_KEY
+    ? { ...sourceEnv, DEEPSEEK_API_KEY: 'namespace-selector-only' }
+    : sourceEnv
+  const childEnv = buildDshPlannerEnvironment(routeSource)
+  if (options.llmTickets) {
+    // The credential reaches the child only as a ticket, issued per port. Whatever the environment held is not forwarded,
+    // so an ambient key cannot slip past the broker; the ticket's own values are set where the port is created.
+    delete childEnv.DEEPSEEK_API_KEY
+    delete childEnv.DEEPSEEK_BASE_URL
+  } else if (!childEnv.DEEPSEEK_API_KEY) throw new Error('booking_planner_model_key_required')
+  const provider = options.provider?.trim() || childEnv.DEEPSEEK_PROVIDER || 'deepseek-official'
+  if (options.llmTickets && provider !== 'gateway-chat') throw new Error('booking_planner_llm_tickets_require_gateway_chat')
   const configuredModel = options.model ?? childEnv.DEEPSEEK_MODEL
   if (provider !== 'deepseek-official' && !configuredModel) {
     throw new Error('booking_planner_model_required_for_nondefault_provider')
@@ -336,9 +379,33 @@ export function resolveRealRunPortConfig(options: DshEmbeddedBookingPlannerOptio
   return { childEnv, provider, model, modelSource, reasoningEffort, maxTokens }
 }
 
+/**
+ * The names under which an ambient LLM credential or address could reach a child through the runtime's inherited
+ * environment. The runtime merges the explicit environment onto the parent's with names that look secret removed, so an
+ * address (`LLM_BASE_URL`) would otherwise pass; an explicit `undefined` removes an inherited entry.
+ */
+const AMBIENT_LLM_CREDENTIAL_NAMES = ['LLM_API_KEY', 'LLM_BASE_URL'] as const
+
+/**
+ * The environment of a real planner process tree. With a ticket it carries the ticket in place of the key and base URL,
+ * and removes the ambient names that could carry the real ones; without one it is the resolved environment, unchanged.
+ */
+export function plannerChildEnvironment(
+  resolved: Record<string, string>,
+  ticket?: { readonly token: string; readonly baseUrl: string },
+): NodeJS.ProcessEnv {
+  if (!ticket) return resolved
+  const tombstones: NodeJS.ProcessEnv = {}
+  for (const name of AMBIENT_LLM_CREDENTIAL_NAMES) tombstones[name] = undefined
+  return { ...resolved, ...tombstones, DEEPSEEK_API_KEY: ticket.token, DEEPSEEK_BASE_URL: ticket.baseUrl }
+}
+
 /** Shared by the planner and real-subprocess proofs; owns its scratch directory. */
 export async function createRealRunPort(options: DshEmbeddedBookingPlannerOptions): Promise<DshPlannerRunPort> {
-  const { childEnv, provider, model, modelSource, reasoningEffort, maxTokens } = resolveRealRunPortConfig(options)
+  const resolved = resolveRealRunPortConfig(options)
+  const { provider, model, modelSource, reasoningEffort, maxTokens } = resolved
+  // Every real port, not only the first one of a process, starts a child only where the tree limits can be enforced.
+  if (options.resourceLimits) await assertManagedDshLimitsEnforceable(options.resourceLimits)
   // Name the resolved route on every real port. A deployment that forgot
   // DEEPSEEK_MODEL used to be indistinguishable from one that set it, and the
   // substituted model is exactly what a later diagnosis needs to see.
@@ -350,8 +417,14 @@ export async function createRealRunPort(options: DshEmbeddedBookingPlannerOption
   const dshHome = join(scratch, 'home')
   mkdirSync(dshHome, { recursive: true })
   const pluginPath = options.pluginPath ?? fileURLToPath(new URL('./dsh-plugin.js', import.meta.url))
+  const gatewayLlmPluginPath = options.gatewayLlmPluginPath ?? fileURLToPath(new URL('./dsh-llm-gateway-chat.js', import.meta.url))
   const patchPath = join(scratch, 'embedded-booking.cordis.yml')
-  writeFileSync(patchPath, buildDshEmbeddedBookingPatch(pluginPath), { encoding: 'utf8', mode: 0o600 })
+  writeFileSync(patchPath, buildDshEmbeddedBookingPatch(pluginPath, gatewayLlmPluginPath), { encoding: 'utf8', mode: 0o600 })
+
+  // One ticket per port, shared with its warmer, revoked when the port closes or fails to come up. It is issued only now,
+  // after the steps above that can fail (a full disk, no descriptors), so none of them can leave a live ticket behind.
+  const ticket = options.llmTickets?.issue()
+  const childEnv = plannerChildEnvironment(resolved.childEnv, ticket)
 
   let managedPort: DshPlannerRunPort
   try {
@@ -381,9 +454,11 @@ export async function createRealRunPort(options: DshEmbeddedBookingPlannerOption
       disposeEofGraceMs: 500,
       disposeGraceMs: 500,
       env: childEnv,
+      ...(options.resourceLimits ? { limits: options.resourceLimits } : {}),
       ...(options.dshBin ? { dshBin: options.dshBin } : {}),
     })
   } catch (error) {
+    ticket?.revoke()
     rmSync(scratch, { recursive: true, force: true })
     throw error
   }
@@ -424,9 +499,11 @@ export async function createRealRunPort(options: DshEmbeddedBookingPlannerOption
         disposeEofGraceMs: 500,
         disposeGraceMs: 500,
         env: childEnv,
+        ...(options.resourceLimits ? { limits: options.resourceLimits } : {}),
         ...(options.dshBin ? { dshBin: options.dshBin } : {}),
       })
     } catch (error) {
+      ticket?.revoke()
       try {
         await managedPort.close()
       } catch (cleanupError) {
@@ -459,6 +536,8 @@ export async function createRealRunPort(options: DshEmbeddedBookingPlannerOption
       if (closePromise) return closePromise
       closePromise = (async () => {
         const results = await Promise.allSettled([managedPort.close(), closeWarmer()])
+        // Whatever the cleanup did, the credential stops working with the port.
+        ticket?.revoke()
         const failures = results.flatMap((result) => result.status === 'rejected' ? [result.reason] : [])
         if (failures.length) {
           throw new AggregateError(failures, 'booking_planner_run_port_cleanup_failed')
@@ -483,7 +562,7 @@ function plannerVisibleAllowedActions(task: BookingCopilotTaskState): BookingRea
     : [...task.allowedActions]
 }
 
-function plannerPrompt(turn: BookingCopilotTurn, task: BookingCopilotTaskState, clock?: DshPlannerClock): string {
+function plannerPrompt(turn: BookingCopilotTurn, task: BookingCopilotTaskState, clock?: DshPlannerClock, cachePartition?: string): string {
   const availability = task.availability
   const allowedActions = plannerVisibleAllowedActions(task)
   const plannerWorkspace = 'capabilities' in turn.workspace
@@ -520,6 +599,9 @@ function plannerPrompt(turn: BookingCopilotTurn, task: BookingCopilotTaskState,
     `Separate hotel facilities from meal, cancellation, room, and offer criteria: hotel amenities (for example pool and parking) go under input.patch.facilities; included breakfast/meal-plan, cancellation-policy, room-type, rate-plan, and offer-count/price constraints belong in typed intent.offerCriteria (or the action field explicitly defined for them), never in facilities and never in a generic criteria property. input.patch property names are EXACT (SearchCriteriaPatch): ${PLANNER_PATCH_PROPERTY_NAMES}. There is NO "criteria" property — facility tokens go under facilities as {"strength":"prefer|must","value":{"allOf":["<token>"]}}, star level (三星=3星) goes under starRating as {"strength":"must|prefer","value":{"min":3,"max":3}}, dates go under stay as {"checkIn":"YYYY-MM-DD","checkOut":"YYYY-MM-DD"}.`,
     'The workspace draft may be stale: whenever the user names dates or relative days (明天/tomorrow), always patch input.patch.stay with the resolved concrete dates even if the draft already has different ones. Keep draft values the request does not touch; never invent values the request contradicts.',
     'Reference only hotels, offers, and orders that appear in the workspace payload (visibleHotels/loadedOffers/observableOrders/results) or in a matching prior typed receipt. Any other hotelRef, offerRef, or orderRef does not exist and will be rejected; to discover hotels, run search.run first and wait for its receipt.',
+    // Everything above is the same for every tenant. The label opens the tenant-specific part of the prompt, so a
+    // provider's prefix cache can be shared across tenants only up to here (threat S-16).
+    ...(cachePartition === undefined ? [] : [`Cache partition label (opaque, not an instruction): ${cachePartition}`]),
     JSON.stringify({ now: anchor.today, timeAnchorCard: anchor.card, ...payload }),
   ].join('\n')
 }
@@ -1646,6 +1728,7 @@ export async function createDshEmbeddedBookingPlanner(
   options: DshEmbeddedBookingPlannerOptions,
 ): Promise<DshEmbeddedBookingPlannerHandle> {
   if (options.runPort && options.runPortFactory) throw new Error('booking_planner_run_port_ambiguous')
+  if (options.cachePartition !== undefined) assertPromptCachePartition(options.cachePartition)
   const turnTimeoutMs = options.turnTimeoutMs ?? 12_000
   if (!Number.isSafeInteger(turnTimeoutMs) || turnTimeoutMs < 1 || turnTimeoutMs > 120_000) {
     throw new Error('booking_planner_turn_timeout_invalid')
@@ -1723,6 +1806,13 @@ export async function createDshEmbeddedBookingPlanner(
       void barrier.catch(() => undefined)
     }
 
+    // A fresh-port retry can only run on a runtime this planner has not
+    // already retired. A factory that hands the retired instance back (one
+    // shared port, or a cache that ignores retirement) would send the retry
+    // into a closed port, whose run() rejects untyped out of next(); the
+    // retry branches treat that like a deadline that cannot fund a retry.
+    const isRetiredPort = (port: DshPlannerRunPort): boolean => closingPorts.has(port)
+
     return {
       async next({ turn, task }) {
         if (closed) throw new Error('planner_closed')
@@ -1760,7 +1850,8 @@ export async function createDshEmbeddedBookingPlanner(
           // bounded planner attempt. Any returned decision crosses the same
           // typed authority path.
           let attempt = 0
-          let nextPrompt = plannerPrompt(turn, task, options.now)
+          let schemaRepairAttempted = false
+          let nextPrompt = plannerPrompt(turn, task, options.now, options.cachePartition)
           // A run that goes silent must not be allowed to silently consume the
           // whole turn deadline: the idle stall budget fires only when the run
           // stops emitting notifications entirely, the child is retired, and
@@ -1782,10 +1873,29 @@ export async function createDshEmbeddedBookingPlanner(
                 deadlineAt,
               )
               modelStepCount += observedModelStepCount(result.events)
-              schemaRejectedCallCount += result.events
+              const schemaRejectionsThisRun = result.events
                 .map((event, index) => toolResultObservation(event, index))
                 .filter((observation) => observation?.kind === 'schema-rejection').length
-              decisions = scanDshToolDecisionEvents(result.events, task)
+              schemaRejectedCallCount += schemaRejectionsThisRun
+              try {
+                decisions = scanDshToolDecisionEvents(result.events, task)
+              } catch (scanError) {
+                // hotel-be#33640: a provider can emit a tool call whose
+                // arguments miss the declared schema and then stop. Treat one
+                // schema-shaped rejection as a repairable provider mistake:
+                // retry once with a stricter prompt on the same session
+                // instead of surfacing PLANNER_PROVIDER_RESPONSE_INVALID to the
+                // user. Safety errors and unproven rejections still fail closed.
+                if (!schemaRepairAttempted && schemaRejectionsThisRun > 0 && attempt < 3 && isSchemaShapeError(scanError)) {
+                  schemaRepairAttempted = true
+                  console.error('[booking-copilot] planner tool call failed schema validation; retrying with a repair prompt:', JSON.stringify({
+                    attempt, schemaRejectionsThisRun,
+                  }))
+                  nextPrompt = 'Your previous booking capability tool call was rejected because its arguments did not match the declared parameter schema. Emit exactly one corrected booking capability tool call that satisfies the schema; do not repeat the rejected arguments and do not add prose.'
+                  continue
+                }
+                throw scanError
+              }
               // A valid capability decision is already receipt-gated and is
               // the authority for this interval. Some providers fail a later
               // post-tool model step; that must not erase the accepted action.
@@ -1834,8 +1944,12 @@ export async function createDshEmbeddedBookingPlanner(
                   attempt, softStallBudgetMs, remainingMs,
                 }))
                 retire(runPort)
-                runPort = await beforePlannerDeadline(taskPort(), deadlineAt)
+                const stallRetryPort = await beforePlannerDeadline(taskPort(), deadlineAt)
                 if (closed || sessionClosePromise) throw new Error(closed ? 'planner_closed' : 'planner_session_closed')
+                if (isRetiredPort(stallRetryPort)) {
+                  throw bootNeverCompleted(runPort) ? new PlannerBootTimeoutExceeded() : new PlannerTurnDeadlineExceeded()
+                }
+                runPort = stallRetryPort
                 // The stalled run produced no decision; it must not consume a
                 // prose-nudge attempt.
                 attempt -= 1
@@ -1843,7 +1957,27 @@ export async function createDshEmbeddedBookingPlanner(
               }
               // The SDK reports an expired local handshake as its own typed
               // failure; no provider request was ever made.
-              if (error instanceof Error && error.message === 'HARNESS_BOOT_TIMEOUT') throw new PlannerBootTimeoutExceeded()
+              if (error instanceof Error && error.message === 'HARNESS_BOOT_TIMEOUT') {
+                // A cold OS page cache routinely pushes the first boot past
+                // the local budget (observed 6.5–8s after idle on UAT,
+                // Danceiny/gotry#660): the failed boot warms the very pages
+                // the next port reads, so one fresh-port retry converges and
+                // only a genuinely stuck runtime burns both. Same shape as
+                // the soft-stall retry above; a boot that never reached a
+                // provider request must not consume an attempt.
+                const bootRemainingMs = deadlineAt - Date.now()
+                if (bootRemainingMs < PLANNER_MIN_VIABLE_RUN_MS) throw new PlannerBootTimeoutExceeded()
+                console.error('[booking-copilot] planner boot exceeded the local budget; retrying on a fresh run port:', JSON.stringify({
+                  attempt, bootRemainingMs,
+                }))
+                retire(runPort)
+                const bootRetryPort = await beforePlannerDeadline(taskPort(), deadlineAt)
+                if (closed || sessionClosePromise) throw new Error(closed ? 'planner_closed' : 'planner_session_closed')
+                if (isRetiredPort(bootRetryPort)) throw new PlannerBootTimeoutExceeded()
+                runPort = bootRetryPort
+                attempt -= 1
+                continue
+              }
               if (error instanceof PlannerTurnDeadlineExceeded) {
                 // The turn deadline can expire while our own runtime is still
                 // starting; that phase is ours, not the provider's.
@@ -1883,6 +2017,14 @@ export async function createDshEmbeddedBookingPlanner(
           retire(runPort)
           return [{ kind: 'error', error: { code: 'PLANNER_ATTEMPT_BUDGET_EXHAUSTED', message: 'GoTry exhausted the planner attempt budget without a decision.', retryable: true } }]
         } catch (error) {
+          // A port that fails its own initialize (createManagedDshRunPort with
+          // initializeTimeoutMs) rejects with the SDK's raw typed message,
+          // never reaching the run loop; classify it as the boot timeout it is
+          // instead of surfacing an untyped failure.
+          if (!(error instanceof PlannerBootTimeoutExceeded)
+            && error instanceof Error && error.message === 'HARNESS_BOOT_TIMEOUT') {
+            error = new PlannerBootTimeoutExceeded()
+          }
           if (error instanceof PlannerBootTimeoutExceeded) {
             metricOutcome = 'boot_timeout'
             logPlannerBootTimeout(runPort)
@@ -1894,6 +2036,14 @@ export async function createDshEmbeddedBookingPlanner(
             retire(runPort)
             return [{ kind: 'error', error: { code: 'PLANNER_PROVIDER_TIMEOUT', message: providerFailureMessage('PLANNER_PROVIDER_TIMEOUT'), retryable: true } }]
           }
+          if (error instanceof ManagedDshResourceLimitError) {
+            // The tree was killed for taking too much of the replica. Running the same turn again on a fresh port would
+            // only let it take that much again, so this is terminal for the turn: not retried, not a provider fault.
+            metricOutcome = 'resource_limit'
+            console.error('[booking-copilot] planner child exceeded a resource limit:', JSON.stringify(error.breach))
+            retire(runPort)
+            return [{ kind: 'error', error: { code: 'PLANNER_FAILED', message: providerFailureMessage('PLANNER_FAILED'), retryable: false } }]
+          }
           retire(runPort)
           throw error
         } finally {

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

@@ -7,3 +7,4 @@ export * from './startup.ts'
 export * from './validation.ts'
 export * from './availability-policy.ts'
 export * from './booking-intent.ts'
+export * from './tenancy.ts'

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

@@ -14,6 +14,65 @@ import {
   type ManagedDshProcessGroupSnapshot,
   type ManagedDshWorkerOutcome,
 } from './managed-dsh-cleanup-diagnostic.ts'
+import { sharedProcessTreeGovernor, type ProcessTreeGovernor, type TreeBreach } from '../tenant-seam/process-governor.ts'
+
+/**
+ * What one worker tree may take (AaaS, docs/rfc/aaas-rfc.md §4.8, threat S-17). Every field is opt-in: a port built
+ * without `limits` behaves exactly as before.
+ */
+export interface ManagedDshResourceLimits {
+  /** V8 old-space ceiling in MiB for the worker and every Node process below it (`NODE_OPTIONS`). An allocation spike dies in-process. */
+  heapMb?: number
+  /** Resident set of the whole worker tree in bytes (sampled; see `ProcessTreeGovernor`). Covers what the heap cap cannot see, such as buffers. */
+  maxRssBytes?: number
+  /** CPU seconds of the whole worker tree (sampled). */
+  maxCpuSeconds?: number
+  /** The longest line, in characters, the worker may write to the parent without a newline. The parent buffers a line until it ends. */
+  maxLineChars?: number
+  /**
+   * How long a worker may take to say who it is (its `worker_started` line) before the missing governor is reported. The
+   * sampler learns which process to watch from that line alone: without it the tree limits are silently off. Default 10 s.
+   */
+  attachDeadlineMs?: number
+  /** Sampler shared by ports. Default: the process-wide governor. */
+  governor?: ProcessTreeGovernor
+}
+
+/**
+ * `memory` and `cpu` come from the tree sampler, `output` from the line cap, `heap` from the worker's own V8 ceiling
+ * (recognised from its stderr tail after it died, where only the ceiling is known and `observed` repeats it).
+ */
+export type ManagedDshResourceBreach = TreeBreach | { readonly kind: 'output' | 'heap'; readonly limit: number; readonly observed: number }
+
+/** The worker tree went over a resource limit and was killed. Closed shape: kind and numbers only, never worker output. */
+export class ManagedDshResourceLimitError extends Error {
+  readonly breach: ManagedDshResourceBreach
+
+  constructor(breach: ManagedDshResourceBreach) {
+    super(breach.kind === 'blind' ? 'managed DSH worker tree could not be observed' : `managed DSH worker exceeded its ${breach.kind} limit`)
+    this.name = 'ManagedDshResourceLimitError'
+    this.breach = breach
+  }
+}
+
+/**
+ * Proves that the sampler can see before a child is started: with a tree limit set, a process table that cannot be read
+ * would let the limit govern nothing, so it fails first and by name. A port with no tree limit has nothing to check.
+ */
+export async function assertManagedDshLimitsEnforceable(limits: ManagedDshResourceLimits): Promise<void> {
+  if (limits.maxRssBytes === undefined && limits.maxCpuSeconds === undefined) return
+  await (limits.governor ?? sharedProcessTreeGovernor()).probe()
+}
+
+function assertPositiveLimit(name: string, value: number | undefined): void {
+  if (value !== undefined && (!Number.isFinite(value) || value <= 0)) throw new RangeError(`managed DSH limit ${name} must be a positive number`)
+}
+
+function limitedEnvironment(env: NodeJS.ProcessEnv | undefined, heapMb: number | undefined): NodeJS.ProcessEnv | undefined {
+  if (heapMb === undefined) return env
+  const existing = (env?.NODE_OPTIONS ?? '').split(/\s+/).filter((option) => option !== '' && !option.startsWith('--max-old-space-size='))
+  return { ...env, NODE_OPTIONS: [...existing, `--max-old-space-size=${Math.floor(heapMb)}`].join(' ') }
+}
 
 export interface ManagedDshRunPortOptions {
   cwd?: string
@@ -21,6 +80,8 @@ export interface ManagedDshRunPortOptions {
   graceMs?: number
   cleanupRole?: 'task' | 'warmer'
   env?: NodeJS.ProcessEnv
+  /** Resource ceilings for the worker tree. Absent: none, as before. */
+  limits?: ManagedDshResourceLimits
   /** Test seam overriding the failure-path group snapshot; production uses the safe ps snapshot. */
   groupObserver?: typeof snapshotManagedDshGroup
   /**
@@ -38,14 +99,17 @@ const WORKER_FAILURE_CODES = new Set(['HARNESS_BOOT_TIMEOUT', 'HARNESS_START_FAI
 
 const requireFromModule = createRequire(import.meta.url)
 
-function workerLaunch(path: string): readonly string[] {
+function workerLaunch(path: string, heapMb?: number): readonly string[] {
+  // The V8 ceiling is given on the worker's own command line as well as in NODE_OPTIONS (which carries it to the
+  // processes below the worker), so the worker's ceiling does not depend on its environment surviving a scrub.
+  const heap = heapMb === undefined ? [] : [`--max-old-space-size=${Math.floor(heapMb)}`]
   // 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]
+    ? [process.execPath, ...heap, '--import', requireFromModule.resolve('tsx/esm'), path]
+    : [process.execPath, ...heap, path]
 }
 
 /** Run DeepSeekHarness in a child tree owned by dsh-subprocess-local. */
@@ -66,7 +130,13 @@ export class ManagedDshRunPort implements DshPlannerRunPort {
   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
+    const { workerPath: _worker, graceMs = 500, cleanupRole, env, groupObserver, bootLog, limits, ...harnessOptions } = options
+    assertPositiveLimit('heapMb', limits?.heapMb)
+    assertPositiveLimit('maxRssBytes', limits?.maxRssBytes)
+    assertPositiveLimit('maxCpuSeconds', limits?.maxCpuSeconds)
+    assertPositiveLimit('maxLineChars', limits?.maxLineChars)
+    assertPositiveLimit('attachDeadlineMs', limits?.attachDeadlineMs)
+    this.limits = limits
     this.cleanupRole = cleanupRole ?? 'unspecified'
     this.graceMs = graceMs
     this.groupObserver = groupObserver ?? snapshotManagedDshGroup
@@ -74,22 +144,32 @@ export class ManagedDshRunPort implements DshPlannerRunPort {
     this.constructedAtMs = Date.now()
     this.runtime = new LocalSubprocessRuntime(new Context())
     this.handle = this.runtime.spawn({
-      argv: workerLaunch(workerPath),
+      argv: workerLaunch(workerPath, limits?.heapMb),
       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,
+      env: limitedEnvironment(env, limits?.heapMb),
     })
     this.handle.stdout!.setEncoding('utf8')
     this.handle.stdout!.on('data', (chunk: string) => this.consume(chunk))
+    if (limits && (limits.maxRssBytes !== undefined || limits.maxCpuSeconds !== undefined)) {
+      const deadlineMs = limits.attachDeadlineMs ?? 10_000
+      this.attachTimer = setTimeout(() => {
+        this.emitBootLog(`RESOURCE_GOVERNOR_UNATTACHED ${JSON.stringify({ role: this.cleanupRole, afterMs: deadlineMs })}`)
+      }, deadlineMs)
+      this.attachTimer.unref()
+    }
     this.handle.done.then(
       (outcome) => {
+        this.stopWatching()
         this.workerOutcome = { state: 'exited', exitCode: outcome.exitCode, signal: outcome.signal }
+        this.noteHeapExhaustion()
         this.markTerminal('managed DSH worker exited')
       },
       () => {
+        this.stopWatching()
         this.workerOutcome = { state: 'failed' }
         this.markTerminal('managed DSH worker failed')
       },
@@ -100,6 +180,9 @@ export class ManagedDshRunPort implements DshPlannerRunPort {
     this.cleanupDeadlineMs = Math.max(1_000, graceMs * 4)
   }
 
+  private readonly limits: ManagedDshResourceLimits | undefined
+  private attachTimer: NodeJS.Timeout | undefined
+  private unwatchTree: (() => void) | undefined
   private readonly harnessOptions: Record<string, unknown>
   private readonly cleanupDeadlineMs: number
   private readonly groupObserver: typeof snapshotManagedDshGroup
@@ -130,17 +213,76 @@ export class ManagedDshRunPort implements DshPlannerRunPort {
     return this.booted
   }
 
+  /**
+   * A resource ceiling was crossed: say why before anything else can say something vaguer, fail what is waiting with
+   * that reason, and let the provider-owned range cleanup run. The governor (or the line cap) then kills the tree.
+   */
+  private resourceBreach(breach: ManagedDshResourceBreach): void {
+    this.terminalError ??= new ManagedDshResourceLimitError(breach)
+    this.failPending(this.terminalError)
+    this.stopWatching()
+    this.inputBuffer = ''
+    try { this.handle.terminate() } catch { /* the governor's kill below is what must happen */ }
+  }
+
+  private stopWatching(): void {
+    clearTimeout(this.attachTimer)
+    this.attachTimer = undefined
+    const unwatch = this.unwatchTree
+    this.unwatchTree = undefined
+    unwatch?.()
+  }
+
+  /**
+   * A worker that died of its own V8 ceiling is a resource-limit death, not a mystery crash. Only the fixed V8 message is
+   * looked for in the bounded stderr tail; nothing from it is kept or reported.
+   */
+  private noteHeapExhaustion(): void {
+    const heapMb = this.limits?.heapMb
+    if (heapMb === undefined || this.terminalError) return
+    let tail = ''
+    try { tail = this.handle.collected.stderr?.readFrom(0).text ?? '' } catch { return }
+    if (!tail.includes('JavaScript heap out of memory')) return
+    const bytes = Math.floor(heapMb) * 1024 * 1024
+    this.terminalError = new ManagedDshResourceLimitError({ kind: 'heap', limit: bytes, observed: bytes })
+  }
+
+  private watchTree(workerPid: number): void {
+    const limits = this.limits
+    if (!limits || (limits.maxRssBytes === undefined && limits.maxCpuSeconds === undefined)) return
+    clearTimeout(this.attachTimer)
+    this.attachTimer = undefined
+    const governor = limits.governor ?? sharedProcessTreeGovernor()
+    // The worker is this process's own child (the lifecycle line was checked for that), so the governor also requires
+    // the parent to match: a pid the operating system reused for something else is never sampled or killed.
+    this.unwatchTree = governor.watch(
+      { rootPid: workerPid, parentPid: process.pid },
+      { maxRssBytes: limits.maxRssBytes, maxCpuSeconds: limits.maxCpuSeconds },
+      (breach) => this.resourceBreach(breach),
+    )
+  }
+
   private consume(chunk: string): void {
+    if (this.terminalError instanceof ManagedDshResourceLimitError) return
     this.inputBuffer += chunk
     for (;;) {
       const newline = this.inputBuffer.indexOf('\n')
-      if (newline < 0) return
+      if (newline < 0) {
+        // The parent holds a line until it ends; a worker that never ends one would grow this process without bound.
+        const maxLineChars = this.limits?.maxLineChars
+        if (maxLineChars !== undefined && this.inputBuffer.length > maxLineChars) {
+          this.resourceBreach({ kind: 'output', limit: maxLineChars, observed: this.inputBuffer.length })
+          // The worker stays up until the provider range cleanup lands; this port no longer reads from it.
+        }
+        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!
+            this.watchTree(this.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) => {
@@ -225,6 +367,7 @@ export class ManagedDshRunPort implements DshPlannerRunPort {
     if (this.closePromise) return this.closePromise
     this.closePromise = (async () => {
       const started = performance.now()
+      this.stopWatching()
       this.failPending(new Error('managed DSH run port closed'))
       this.handle.terminate()
       // Observe worker failure even if range observation rejects or times out