@namzu/sdk 34.1.0 → 35.0.0

package/src/runtime/jobs/registry.ts

@@ -57,11 +57,25 @@ export interface BackgroundJobOutput {
 	readonly exitCode?: number
 }
 
+/** A job's process, when something other than the registry starts it. */
+export interface JobProcess {
+	readonly child: ReturnType<typeof spawn>
+	/** How to stop it, when the registry's process-group kill would not reach everything. */
+	kill?(signal: NodeJS.Signals): void
+}
+
 export interface StartJobParams {
 	readonly owner: string
 	readonly command: string
 	readonly workingDirectory: string
 	readonly env?: Readonly<Record<string, string>>
+	/**
+	 * Start the process yourself — a sandbox does, so the job runs inside
+	 * its boundary. Absent, the registry runs `/bin/sh -c command` on the
+	 * host. The process must be the leader of its own group and must not
+	 * expect stdin.
+	 */
+	readonly spawn?: () => JobProcess
 }
 
 export interface BackgroundJobRegistryConfig {
@@ -106,6 +120,8 @@ export class UnknownBackgroundJobError extends Error {
 interface JobEntry {
 	record: BackgroundJob
 	child: ReturnType<typeof spawn>
+	/** The spawner's own kill, when it gave one. */
+	killProcess?: (signal: NodeJS.Signals) => void
 	/** Retained tail. */
 	buffer: string
 	/** Bytes produced in total, including the ones the cap dropped. */
@@ -113,9 +129,46 @@ interface JobEntry {
 	exit: Promise<void>
 }
 
+/** Whether any process of the group led by `pid` is still alive. */
+function groupAlive(pid: number | undefined): boolean {
+	if (pid === undefined || process.platform === 'win32') return false
+	try {
+		process.kill(-pid, 0)
+		return true
+	} catch {
+		return false
+	}
+}
+
+const GROUP_POLL_MS = 250
+
 export class BackgroundJobRegistry {
 	private readonly jobs = new Map<string, JobEntry>()
 	private counter = 0
+	private readonly exitListeners = new Set<(job: BackgroundJob) => void>()
+
+	/**
+	 * Be told when a job ends, whoever owns it. A job outlives the call that
+	 * started it, so the one thing the model could not do was learn that it
+	 * had finished without polling; a run subscribes here and turns the exit
+	 * into a notice on its next tool result. Returns the unsubscribe.
+	 */
+	onExit(listener: (job: BackgroundJob) => void): () => void {
+		this.exitListeners.add(listener)
+		return () => {
+			this.exitListeners.delete(listener)
+		}
+	}
+
+	private announceExit(job: BackgroundJob): void {
+		for (const listener of this.exitListeners) {
+			try {
+				listener(job)
+			} catch {
+				// A listener that throws is its owner's problem, not the job's.
+			}
+		}
+	}
 
 	constructor(private readonly config: BackgroundJobRegistryConfig = {}) {}
 
@@ -151,15 +204,20 @@ export class BackgroundJobRegistry {
 		// started it, which makes the leak longer-lived, not smaller.
 		const inherited = scrubInheritedEnv()
 
-		const child = spawn('/bin/sh', ['-c', params.command], {
-			cwd: params.workingDirectory,
-			env: { ...inherited.env, ...params.env },
-			// Leader of its own process group, which is what `killTree` needs
-			// to reach the command and everything it forks rather than only the
-			// wrapping shell. See `process/kill-tree.ts`.
-			detached: process.platform !== 'win32',
-			stdio: ['ignore', 'pipe', 'pipe'],
-		})
+		const started = params.spawn
+			? params.spawn()
+			: {
+					child: spawn('/bin/sh', ['-c', params.command], {
+						cwd: params.workingDirectory,
+						env: { ...inherited.env, ...params.env },
+						// Leader of its own process group, which is what `killTree` needs
+						// to reach the command and everything it forks rather than only the
+						// wrapping shell. See `process/kill-tree.ts`.
+						detached: process.platform !== 'win32',
+						stdio: ['ignore', 'pipe', 'pipe'],
+					}),
+				}
+		const child = started.child
 		// Started, not adopted: this process stays the parent for the job's
 		// whole life. `unref` would let Node exit with the job still running,
 		// which is the orphan this registry exists to prevent.
@@ -175,10 +233,11 @@ export class BackgroundJobRegistry {
 				startedAt: Date.now(),
 			},
 			child,
+			...(started.kill ? { killProcess: started.kill.bind(started) } : {}),
 			buffer: '',
 			produced: 0,
 			exit: new Promise<void>((resolve) => {
-				child.once('close', (code, signal) => {
+				const finalize = (code: number | null, signal: NodeJS.Signals | null): void => {
 					entry.record = {
 						...entry.record,
 						// A job killed by this registry says `killed`, not
@@ -190,10 +249,33 @@ export class BackgroundJobRegistry {
 						...(signal ? { signal } : {}),
 					}
 					resolve()
+					this.announceExit(entry.record)
+				}
+				child.once('close', (code, signal) => {
+					// The job is the process GROUP, not the shell. A command that
+					// backgrounds its real work (`server &`) exits the shell at
+					// once and leaves the server as the group's survivor; calling
+					// that "exited" told the model the job was over while the
+					// port was still held, and nothing stopped the survivor at
+					// session end because the job was no longer running. So a
+					// job whose shell has ended stays running while its group is
+					// alive, and ends — with the shell's exit code — when the
+					// group is empty.
+					if (entry.record.status !== 'killed' && groupAlive(child.pid)) {
+						const poll = setInterval(() => {
+							if (groupAlive(child.pid)) return
+							clearInterval(poll)
+							finalize(code, signal)
+						}, GROUP_POLL_MS)
+						poll.unref()
+						return
+					}
+					finalize(code, signal)
 				})
 				child.once('error', () => {
 					entry.record = { ...entry.record, status: 'exited', exitedAt: Date.now() }
 					resolve()
+					this.announceExit(entry.record)
 				})
 			}),
 		}
@@ -266,8 +348,10 @@ export class BackgroundJobRegistry {
 		// tell a kill from an ordinary exit. Set it after and the race decides
 		// which of two different answers a reader gets.
 		entry.record = { ...entry.record, status: 'killed' }
-		killTree(entry.child, 'SIGTERM')
-		const grace = setTimeout(() => killTree(entry.child, 'SIGKILL'), SANDBOX_KILL_GRACE_MS)
+		const signal = (sig: NodeJS.Signals) =>
+			entry.killProcess ? entry.killProcess(sig) : killTree(entry.child, sig)
+		signal('SIGTERM')
+		const grace = setTimeout(() => signal('SIGKILL'), SANDBOX_KILL_GRACE_MS)
 		// Unreffed: a job that exits on SIGTERM must not hold the process open
 		// for the remaining grace period doing nothing.
 		grace.unref?.()
@@ -317,7 +401,16 @@ export class BackgroundJobRegistry {
 export function bindOwner(
 	registry: BackgroundJobRegistry,
 	owner: string,
-	defaults: { readonly workingDirectory?: string; readonly env?: Record<string, string> } = {},
+	defaults: {
+		readonly workingDirectory?: string
+		readonly env?: Record<string, string>
+		/** See `StartJobParams.spawn`; given the resolved command, directory and env. */
+		readonly spawn?: (params: {
+			readonly command: string
+			readonly workingDirectory: string
+			readonly env?: Record<string, string>
+		}) => JobProcess
+	} = {},
 ) {
 	const mine = (id: string): BackgroundJob => {
 		const job = registry.get(id)
@@ -325,13 +418,26 @@ export function bindOwner(
 		return job
 	}
 	return {
-		start: (params: { command: string; workingDirectory?: string }) =>
-			registry.start({
+		start: (params: { command: string; workingDirectory?: string }) => {
+			const workingDirectory = params.workingDirectory ?? defaults.workingDirectory ?? process.cwd()
+			const spawnHost = defaults.spawn
+			return registry.start({
 				owner,
 				command: params.command,
-				workingDirectory: params.workingDirectory ?? defaults.workingDirectory ?? process.cwd(),
+				workingDirectory,
 				...(defaults.env ? { env: defaults.env } : {}),
-			}),
+				...(spawnHost
+					? {
+							spawn: () =>
+								spawnHost({
+									command: params.command,
+									workingDirectory,
+									...(defaults.env ? { env: defaults.env } : {}),
+								}),
+						}
+					: {}),
+			})
+		},
 		get: (id: string) => mine(id),
 		read: (id: string, opts?: { fromOffset?: number }) => {
 			mine(id)

package/src/runtime/query/checkpoint.ts

@@ -20,7 +20,7 @@ import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { CheckpointListEntry } from '../../types/run/replay.js'
 import { ZERO_COST } from '../../utils/cost.js'
 import { buildToolResultHashes } from '../../utils/hash.js'
-import { asCheckpointId, generateCheckpointId } from '../../utils/id.js'
+import { asCheckpointId, asEmergencySaveId, generateCheckpointId } from '../../utils/id.js'
 
 /**
  * Projection from a full checkpoint payload to the public listing entry.
@@ -72,9 +72,11 @@ export function toCheckpointListEntry(cp: IterationCheckpoint): CheckpointListEn
  * See ses_005-deterministic-replay design §2 + §5.2.
  */
 export function projectEmergencyToCheckpoint(dump: EmergencySaveData): IterationCheckpoint {
-	const emergencySuffix = dump.id.replace(/^esave_/, '')
+	const emergencyId = asEmergencySaveId(dump.id)
+	// The checkpoint is another view of the same snapshot and retains its key.
+	const checkpointId = asCheckpointId(emergencyId)
 	return {
-		id: asCheckpointId(`cp_emergency_${emergencySuffix}`),
+		id: checkpointId,
 		runId: dump.runId,
 		// The dump records the run's start, so this projection carries the
 		// same stamp an ordinary checkpoint of that run would — a run whose
@@ -85,6 +87,8 @@ export function projectEmergencyToCheckpoint(dump: EmergencySaveData): Iteration
 		iteration: dump.currentIteration,
 		messages: dump.messages,
 		tokenUsage: dump.tokenUsage,
+		budgetBinding: dump.budgetBinding,
+		budgetAccountId: dump.budgetAccountId,
 		costInfo: { ...ZERO_COST, unpricedTokens: dump.tokenUsage.totalTokens },
 		guardState: {
 			iterationCount: dump.currentIteration,
@@ -264,6 +268,8 @@ export class CheckpointManager {
 			iteration,
 			messages: [...runMgr.messages],
 			tokenUsage: { ...runMgr.tokenUsage },
+			budgetBinding: runMgr.budget?.binding,
+			budgetAccountId: runMgr.budget?.accountId,
 			costInfo: { ...runMgr.costInfo },
 			guardState: {
 				iterationCount: runMgr.currentIteration,
@@ -275,6 +281,7 @@ export class CheckpointManager {
 			traceContext: this.traceSource?.(),
 		}
 
+		await runMgr.budget?.flush()
 		await this.store.writeCheckpoint(this.scope, checkpoint, this.claimFence)
 		this.lastCreatedId = checkpoint.id
 		return checkpoint

package/src/runtime/query/context.ts

@@ -2,12 +2,7 @@ import { join } from 'node:path'
 import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
 import { PlanManager } from '../../manager/plan/lifecycle.js'
 import { RunPersistence } from '../../manager/run/persistence.js'
-import {
-	DefaultFilesystemMigrator,
-	type FilesystemMigrationResult,
-	type FilesystemMigrator,
-	NOOP_FILESYSTEM_MIGRATION_SINK,
-} from '../../session/migration/index.js'
+import type { TokenBudget } from '../../run/token-budget.js'
 import { DefaultPathBuilder, type PathBuilder } from '../../session/workspace/path-builder.js'
 import { ActivityStore } from '../../store/activity/memory.js'
 import { type ActivityTrackingConfig, resolveActivityTracking } from '../../types/activity/index.js'
@@ -33,20 +28,9 @@ import { type Logger, resolveLogger } from '../../utils/logger.js'
  * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
  * constructed against `{workingDirectory}/.namzu`.
  *
- * `filesystemMigrator` is optional, but note what `build` actually does
- * with it: nothing. Migration is not part of `build` — it runs once per
- * process via {@link RunContextFactory.ensureMigrated}, kept out of `build`
- * entirely so the static method stays synchronous for existing callers;
- * `query()` calls `ensureMigrated` itself, with its own migrator, before it
- * ever calls `build`. This field predates that split, and no code path
- * threads it to `ensureMigrated` on `build`'s behalf. Its sibling
- * `migrationSink` had the identical shape — declared, never read anywhere
- * in the workspace — and NZ-BOOT-04 removed it
- * (`docs/conventions/declared-but-undriven.md`) rather than invent a caller
- * for a field nothing needed; `filesystemMigrator` is the same defect, left
- * for a follow-up rather than folded into that change.
  */
 export interface RunContextConfig {
+	budget?: TokenBudget
 	/**
 	 * The mode this conversation was left in, when the run config names none.
 	 *
@@ -93,13 +77,6 @@ export interface RunContextConfig {
 	checkpointStore?: CheckpointStore
 	runStore?: RunStore
 
-	/**
-	 * Optional injected migrator — tests pass a stub; production code relies
-	 * on the {@link DefaultFilesystemMigrator}. See session-hierarchy.md
-	 * §13.4.1.
-	 */
-	filesystemMigrator?: FilesystemMigrator
-
 	runId?: RunId
 
 	parentRunId?: RunId
@@ -138,39 +115,7 @@ export interface RunContext {
 	trackingConfig: ActivityTrackingConfig
 }
 
-/**
- * Module-level first-call guard for the boot-time filesystem migration
- * (session-hierarchy.md §13.4.1). Keyed on the root directory so a single
- * process that spans multiple `.namzu` roots (unusual but legal) migrates
- * each one once. Subsequent calls short-circuit via the cached promise —
- * never re-reading the on-disk marker per call.
- */
-const migrationPromises = new Map<string, Promise<FilesystemMigrationResult>>()
-
 export class RunContextFactory {
-	/**
-	 * Run the boot-time filesystem migration for `rootDir` at most once per
-	 * process. Safe to `await` from any async entry point; concurrent callers
-	 * for the same root share a single migration promise (no duplicate work,
-	 * no race with the on-disk `.tmp` lock).
-	 */
-	static ensureMigrated(
-		rootDir: string,
-		migrator: FilesystemMigrator = new DefaultFilesystemMigrator(NOOP_FILESYSTEM_MIGRATION_SINK),
-	): Promise<FilesystemMigrationResult> {
-		const cached = migrationPromises.get(rootDir)
-		if (cached) return cached
-		const promise = migrator.migrate(rootDir)
-		migrationPromises.set(rootDir, promise)
-		// Crash-safety: if the migration rejects, drop the cached promise so
-		// the next caller gets a fresh attempt. Successful results stay cached
-		// (idempotency — further calls short-circuit without re-running).
-		promise.catch(() => {
-			migrationPromises.delete(rootDir)
-		})
-		return promise
-	}
-
 	/**
 	 * The run's one correlated logger, built once and handed to every
 	 * consumer that used to construct its own. Split out of `build` because
@@ -271,6 +216,7 @@ export class RunContextFactory {
 
 		const runMgr = new RunPersistence({
 			runId,
+			budget: config.budget,
 			agentId: config.agentId,
 			agentName: config.agentName,
 			runConfig: config.runConfig,