typeclaw 0.48.11 → 0.48.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/package.json +2 -2
  2. package/src/agent/index.ts +11 -1
  3. package/src/bundled-plugins/github-cli-auth/gh-command.ts +7 -1
  4. package/src/bundled-plugins/github-cli-auth/index.ts +1 -1
  5. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -1
  6. package/src/bundled-plugins/memory/dreaming.ts +21 -6
  7. package/src/channels/adapters/kakaotalk-channel-resolver.ts +86 -16
  8. package/src/channels/adapters/kakaotalk.ts +7 -8
  9. package/src/channels/adapters/teams-classify.ts +21 -0
  10. package/src/channels/adapters/teams-edit.ts +2 -1
  11. package/src/channels/adapters/teams-format.ts +16 -0
  12. package/src/channels/adapters/teams.ts +12 -5
  13. package/src/cli/compose.ts +3 -3
  14. package/src/cli/docker-preflight.ts +8 -4
  15. package/src/cli/restart.ts +89 -23
  16. package/src/cli/start.ts +68 -16
  17. package/src/cli/status.ts +38 -6
  18. package/src/cli/stop.ts +5 -2
  19. package/src/compose/stop.ts +5 -4
  20. package/src/container/build-cache.ts +807 -0
  21. package/src/container/compose-project.ts +4 -0
  22. package/src/container/docker-app.ts +74 -0
  23. package/src/container/log-archive.ts +33 -5
  24. package/src/container/memory-limit.ts +80 -0
  25. package/src/container/memory-oversubscription.ts +125 -0
  26. package/src/container/restart.ts +6 -1
  27. package/src/container/shared.ts +43 -16
  28. package/src/container/start.ts +280 -53
  29. package/src/container/stop.ts +19 -13
  30. package/src/container/verify-running.ts +12 -0
  31. package/src/cron/scheduler.ts +12 -4
  32. package/src/doctor/bounded-exec.ts +14 -0
  33. package/src/doctor/checks.ts +40 -15
  34. package/src/doctor/index.ts +14 -2
  35. package/src/doctor/plugin-bridge.ts +15 -3
  36. package/src/hostd/paths.ts +4 -0
  37. package/src/run/index.ts +16 -0
  38. package/src/run/resource-sample.ts +171 -0
  39. package/src/sandbox/index.ts +8 -1
  40. package/src/sandbox/session-tmp.ts +26 -1
@@ -0,0 +1,14 @@
1
+ import { defaultDockerExec, type DockerExec } from '@/container'
2
+
3
+ // Every Docker call reachable from `doctor` must carry a deadline.
4
+ //
5
+ // The bounded availability probe only proves the daemon answered ONCE; it can
6
+ // wedge immediately afterward, so gating on it is necessary but not sufficient.
7
+ // This is the whole point of the command: an operator runs `doctor` precisely
8
+ // when the host is sick, and a diagnostic that blocks forever on the thing it
9
+ // is diagnosing is worse than useless.
10
+ export const DOCTOR_DOCKER_TIMEOUT_MS = 5_000
11
+
12
+ export function boundedExec(exec: DockerExec = defaultDockerExec, timeoutMs = DOCTOR_DOCKER_TIMEOUT_MS): DockerExec {
13
+ return (args, options) => exec(args, { ...options, signal: options?.signal ?? AbortSignal.timeout(timeoutMs) })
14
+ }
@@ -13,6 +13,7 @@ import {
13
13
  refreshDockerfile,
14
14
  refreshGitignore,
15
15
  resolveHostPort,
16
+ type DockerAvailability,
16
17
  type DockerExec,
17
18
  } from '@/container'
18
19
  import { homeRoot, isDaemonReachable, send } from '@/hostd'
@@ -23,6 +24,7 @@ import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
23
24
  import { detectWsl, isWindows, isWindowsDriveMount, type WslInfo } from '@/shared'
24
25
 
25
26
  import { apparmorSandbox } from './apparmor'
27
+ import { boundedExec } from './bounded-exec'
26
28
  import { buildChannelChecks } from './channel-checks'
27
29
  import { agentFileOwnership, type FileOwnershipDeps } from './file-ownership'
28
30
  import { buildOperationalIncidentChecks } from './operational-incidents'
@@ -32,7 +34,7 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } & FileOwners
32
34
  const dockerExec = opts.dockerExec ?? defaultDockerExec
33
35
 
34
36
  return [
35
- dockerDaemon(dockerExec),
37
+ dockerDaemon(boundedExec(dockerExec)),
36
38
  bunRuntime(),
37
39
  agentFolderInitialized(),
38
40
  agentFolderDockerfileTemplate(),
@@ -48,8 +50,8 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } & FileOwners
48
50
  hostdReachable(),
49
51
  hostdRegistration(),
50
52
  windowsBindMount(),
51
- containerState(dockerExec),
52
- containerHostPort(),
53
+ containerState(boundedExec(dockerExec)),
54
+ containerHostPort(dockerExec),
53
55
  ...buildOperationalIncidentChecks(),
54
56
  ...buildChannelChecks(),
55
57
  ]
@@ -65,20 +67,38 @@ function dockerDaemon(exec: DockerExec): DoctorCheck {
65
67
  if (result.ok) return { status: 'ok', message: 'docker info responded' }
66
68
  return {
67
69
  status: 'error',
68
- message: result.reason === 'binary-missing' ? 'docker binary missing on $PATH' : 'docker daemon not reachable',
70
+ message: dockerDaemonMessage(result.reason),
69
71
  details: [result.detail],
70
- fix:
71
- result.reason === 'binary-missing'
72
- ? { description: 'Install Docker (Docker Desktop, OrbStack, or docker-ce).' }
73
- : {
74
- description:
75
- 'Start the Docker runtime (Docker Desktop, OrbStack, or `systemctl start docker`). If it is already running, check `docker context ls`, `DOCKER_CONTEXT`, and `DOCKER_HOST`.',
76
- },
72
+ fix: { description: dockerDaemonFix(result.reason) },
77
73
  }
78
74
  },
79
75
  }
80
76
  }
81
77
 
78
+ type DockerUnavailableReason = Extract<DockerAvailability, { ok: false }>['reason']
79
+
80
+ function dockerDaemonMessage(reason: DockerUnavailableReason): string {
81
+ switch (reason) {
82
+ case 'binary-missing':
83
+ return 'docker binary missing on $PATH'
84
+ case 'unresponsive':
85
+ return 'docker daemon accepted the request but never responded'
86
+ case 'daemon-down':
87
+ return 'docker daemon not reachable'
88
+ }
89
+ }
90
+
91
+ function dockerDaemonFix(reason: DockerUnavailableReason): string {
92
+ switch (reason) {
93
+ case 'binary-missing':
94
+ return 'Install Docker (Docker Desktop, OrbStack, or docker-ce), or if it is already installed, add its bin directory to PATH — a non-interactive or SSH shell often misses it.'
95
+ case 'unresponsive':
96
+ return 'Restart the Docker runtime (`orb stop` then reopen OrbStack, restart Docker Desktop, or `systemctl restart docker`). A daemon that answers nothing is usually host or VM memory exhaustion, so check memory pressure or it will recur.'
97
+ case 'daemon-down':
98
+ return 'Start the Docker runtime (Docker Desktop, OrbStack, or `systemctl start docker`). If it is already running, check `docker context ls`, `DOCKER_CONTEXT`, and `DOCKER_HOST`.'
99
+ }
100
+ }
101
+
82
102
  function bunRuntime(): DoctorCheck {
83
103
  return {
84
104
  name: 'runtime.bun-available',
@@ -451,7 +471,7 @@ function containerState(exec: DockerExec): DoctorCheck {
451
471
  return { status: 'skipped', message: 'docker unavailable (covered by docker.daemon-reachable)' }
452
472
  }
453
473
  const name = containerNameFromCwd(ctx.cwd)
454
- const state = await inspectContainer(name)
474
+ const state = await inspectContainer(name, { exec })
455
475
  if (!state.exists) {
456
476
  return {
457
477
  status: 'info',
@@ -469,20 +489,25 @@ function containerState(exec: DockerExec): DoctorCheck {
469
489
  }
470
490
  }
471
491
 
472
- function containerHostPort(): DoctorCheck {
492
+ function containerHostPort(exec: DockerExec): DoctorCheck {
473
493
  return {
474
494
  name: 'container.host-port-resolves',
475
495
  category: 'container',
476
496
  description: 'running container exposes its host port',
477
497
  applies: (ctx) => ctx.hasAgentFolder,
478
498
  async run(ctx) {
499
+ const bounded = boundedExec(exec)
500
+ const available = await checkDockerAvailable(bounded)
501
+ if (!available.ok) {
502
+ return { status: 'skipped', message: 'docker unavailable (covered by docker.daemon-reachable)' }
503
+ }
479
504
  const name = containerNameFromCwd(ctx.cwd)
480
- const state = await inspectContainer(name)
505
+ const state = await inspectContainer(name, { exec: bounded })
481
506
  if (!state.exists || !state.running) {
482
507
  return { status: 'skipped', message: 'container not running' }
483
508
  }
484
509
  try {
485
- const port = await resolveHostPort({ cwd: ctx.cwd })
510
+ const port = await resolveHostPort({ cwd: ctx.cwd, exec: bounded })
486
511
  return { status: 'ok', message: `host port ${port} -> container` }
487
512
  } catch (err) {
488
513
  return {
@@ -1,3 +1,4 @@
1
+ import type { DockerExec } from '@/container'
1
2
  import { findAgentDir } from '@/init'
2
3
  import type { DoctorCheckPayload } from '@/shared'
3
4
 
@@ -38,6 +39,10 @@ export type RunDoctorOptions = {
38
39
  cwd?: string
39
40
  only?: string[]
40
41
  fix?: boolean
42
+ // Docker executor used by BOTH the static checks and plugin discovery, so a
43
+ // test can drive the whole command against one wedged daemon and prove the
44
+ // real sequencing terminates — not just each half in isolation.
45
+ dockerExec?: DockerExec
41
46
  staticChecks?: DoctorCheck[]
42
47
  fetchPluginChecks?: PluginBridgeFetchChecks
43
48
  fetchPluginFix?: PluginBridgeFetchFix
@@ -49,10 +54,17 @@ export async function runDoctor(opts: RunDoctorOptions = {}): Promise<DoctorRunR
49
54
  const hasAgentFolder = findAgentDir(cwd) === cwd
50
55
  const ctx: CheckContext = { cwd, hasAgentFolder }
51
56
 
52
- const staticChecks = (opts.staticChecks ?? buildStaticChecks()).filter((c) => isAllowed(c, opts.only, c.category))
57
+ const staticChecks = (
58
+ opts.staticChecks ?? buildStaticChecks(opts.dockerExec === undefined ? {} : { dockerExec: opts.dockerExec })
59
+ ).filter((c) => isAllowed(c, opts.only, c.category))
53
60
  const staticResults = await runStaticChecks(staticChecks, ctx)
54
61
 
55
- const fetchPluginChecks = opts.fetchPluginChecks ?? defaultFetchPluginDoctorChecks
62
+ const fetchPluginChecks =
63
+ opts.fetchPluginChecks ??
64
+ ((bridgeOpts) =>
65
+ defaultFetchPluginDoctorChecks(
66
+ opts.dockerExec === undefined ? bridgeOpts : { ...bridgeOpts, exec: opts.dockerExec },
67
+ ))
56
68
  const pluginResults = await collectPluginChecks(fetchPluginChecks, ctx, opts.only)
57
69
 
58
70
  const initial = buildReport(ctx, staticResults, pluginResults)
@@ -1,10 +1,15 @@
1
- import { resolveHostPort, resolveTuiToken } from '@/container'
1
+ import { resolveHostPort, resolveTuiToken, type DockerExec } from '@/container'
2
2
  import type { ClientMessage, DoctorCheckPayload, DoctorFixPayload, ServerMessage } from '@/shared'
3
3
 
4
+ import { boundedExec } from './bounded-exec'
5
+
4
6
  export type PluginBridgeOptions = {
5
7
  cwd: string
6
8
  url?: string
7
9
  timeoutMs?: number
10
+ // Injectable so a regression test can prove the late discovery path is
11
+ // bounded too, not just the static checks.
12
+ exec?: DockerExec
8
13
  }
9
14
 
10
15
  export type PluginBridgeFetchChecks = (opts: PluginBridgeOptions) => Promise<PluginBridgeChecksResult>
@@ -79,8 +84,15 @@ async function dial(opts: PluginBridgeOptions): Promise<DialResult> {
79
84
  let url = opts.url
80
85
  if (url === undefined) {
81
86
  try {
82
- const port = await resolveHostPort({ cwd: opts.cwd })
83
- const token = await resolveTuiToken({ cwd: opts.cwd })
87
+ // Plugin discovery runs AFTER the static checks, so it is the last place
88
+ // a wedged daemon can still hang the command: `docker port` and
89
+ // `docker inspect` here would otherwise block with no deadline of their
90
+ // own, long after the earlier `docker info` probes succeeded.
91
+ // Wrap unconditionally rather than only defaulting: an injected exec is
92
+ // no safer than the default one, and the deadline is the invariant here.
93
+ const exec = boundedExec(opts.exec)
94
+ const port = await resolveHostPort({ cwd: opts.cwd, exec })
95
+ const token = await resolveTuiToken({ cwd: opts.cwd, exec })
84
96
  url = buildBridgeUrl(port, token)
85
97
  } catch (err) {
86
98
  return { kind: 'unreachable', reason: err instanceof Error ? err.message : String(err) }
@@ -87,6 +87,10 @@ export function modelsDir(): string {
87
87
  return join(homeRoot(), 'models')
88
88
  }
89
89
 
90
+ export function buildCacheDir(): string {
91
+ return join(homeRoot(), 'build-cache')
92
+ }
93
+
90
94
  export function versionCachePath(): string {
91
95
  return join(homeRoot(), 'version-cache.json')
92
96
  }
package/src/run/index.ts CHANGED
@@ -92,6 +92,7 @@ import { installFatalGuard } from './fatal-guard'
92
92
  import { installLlmFetchObserver } from './llm-fetch-observer'
93
93
  import { createPluginRuntime, type PluginRuntime, type PluginSubagentEntry } from './plugin-runtime'
94
94
  import { logResourceReport } from './resource-report'
95
+ import { startResourceSampler } from './resource-sample'
95
96
  import { acquireSubagentCoalesceLease } from './subagent-coalescing'
96
97
 
97
98
  type BunServer = ReturnType<Server['start']>
@@ -136,6 +137,9 @@ export type StartAgentOptions = {
136
137
  // a refresh that holds the real secrets lock on a gate, proving the boot
137
138
  // barrier settles this before any session-producing consumer starts.
138
139
  refreshProviderOAuth?: (options: { agentDir: string; log: (message: string) => void }) => Promise<unknown>
140
+ // Injectable so a test can prove the sampler's disposer is wired into BOTH
141
+ // teardown paths without waiting out a real sampling interval.
142
+ startResourceSampler?: () => () => void
139
143
  }
140
144
 
141
145
  export type StartAgentResult = {
@@ -200,6 +204,7 @@ async function startAgentRuntime(
200
204
  exportClaudeCredentialsFile = exportClaudeCredentialsFileForAgent,
201
205
  exportGithubCliStore = exportGithubCliStoreForAgent,
202
206
  refreshProviderOAuth = refreshProviderOAuthForAgent,
207
+ startResourceSampler: startResourceSamplerFor = startResourceSampler,
203
208
  }: StartAgentOptions,
204
209
  registerBootCleanup: (cleanup: () => void | Promise<void>) => void,
205
210
  ): Promise<StartAgentResult> {
@@ -322,6 +327,16 @@ async function startAgentRuntime(
322
327
  // startup index build is itself an OOM path; if it kills the process, this
323
328
  // line must already be in the log so the ceiling is still recorded.
324
329
  logResourceReport(cwd)
330
+ // The boot line names the ceiling; this names the climb toward it. Without a
331
+ // series there is no way to tell a leak from a spike after the fact, which is
332
+ // exactly the question an OOM post-mortem opens with.
333
+ //
334
+ // Registered for boot-failure cleanup the instant it exists, and torn down by
335
+ // stop() on the normal path. `unref()` only keeps it from holding the process
336
+ // open; without an explicit clear, repeated start/stop cycles accumulate
337
+ // intervals that scan /proc and log after their runtime is gone.
338
+ const stopResourceSampler = startResourceSamplerFor()
339
+ registerBootCleanup(() => stopResourceSampler())
325
340
  const vectorStartupPromise = runVectorStartup(cwd)
326
341
  let pluginsLoaded: LoadPluginsResult
327
342
  try {
@@ -1082,6 +1097,7 @@ async function startAgentRuntime(
1082
1097
  // rejection cannot strand process-global listeners or plugin-owned handles
1083
1098
  // into the next `startAgent`.
1084
1099
  try {
1100
+ stopResourceSampler()
1085
1101
  scheduler?.stop()
1086
1102
  cronConsumer.stop()
1087
1103
  subagentConsumer.stop()
@@ -0,0 +1,171 @@
1
+ import { readdirSync, readFileSync, statfsSync } from 'node:fs'
2
+
3
+ const BYTES_PER_MB = 1024 * 1024
4
+
5
+ export type ResourceSample = {
6
+ rssBytes: number
7
+ shmUsedBytes: number | null
8
+ shmTotalBytes: number | null
9
+ detachedProcesses: number | null
10
+ }
11
+
12
+ // Processes reparented to PID 1 inside the container: anything the agent
13
+ // detached on purpose (a tmux server, a background dev server) plus anything
14
+ // left behind by a call that died. This count is the cheapest signal that
15
+ // something is accumulating across a container's life, and unlike
16
+ // /proc/<pid>/environ it is readable regardless of the per-tool sandbox's child
17
+ // user namespace — /proc/<pid>/stat is world-readable, environ is not.
18
+ export function countDetachedProcesses(procRoot = '/proc', selfPid = process.pid): number | null {
19
+ let entries: string[]
20
+ try {
21
+ entries = readdirSync(procRoot)
22
+ } catch {
23
+ return null
24
+ }
25
+
26
+ let count = 0
27
+ for (const entry of entries) {
28
+ if (!/^\d+$/.test(entry)) continue
29
+ const pid = Number(entry)
30
+ // PID 1 is the init shim itself, never its own orphan.
31
+ if (pid === 1) continue
32
+ // The agent runtime is itself a child of the init shim: the container runs
33
+ // with `--init` and the entrypoint execs Bun, so the agent normally sits at
34
+ // PID 2 with PPID 1. Counting it would give every clean container a
35
+ // permanent floor of 1 and bury the first real orphan in the noise.
36
+ if (pid === selfPid) continue
37
+ let raw: string
38
+ try {
39
+ raw = readFileSync(`${procRoot}/${entry}/stat`, 'utf8')
40
+ } catch {
41
+ // The process exited between readdir and read. Normal, not an error.
42
+ continue
43
+ }
44
+ if (parsePpidFromStat(raw) === 1) count++
45
+ }
46
+ return count
47
+ }
48
+
49
+ // `/proc/<pid>/stat` is `pid (comm) state ppid ...`, and `comm` is the raw
50
+ // executable name — it can contain spaces AND parentheses, so neither a plain
51
+ // whitespace split nor a search for the FIRST ')' is correct. The kernel's own
52
+ // documented parse is to seek the LAST ')' and read fields after it, which is
53
+ // what this does: field 0 is state, field 1 is ppid.
54
+ export function parsePpidFromStat(raw: string): number | null {
55
+ const close = raw.lastIndexOf(')')
56
+ if (close < 0) return null
57
+ const fields = raw
58
+ .slice(close + 1)
59
+ .trim()
60
+ .split(/\s+/)
61
+ const ppid = Number(fields[1])
62
+ return Number.isInteger(ppid) && ppid >= 0 ? ppid : null
63
+ }
64
+
65
+ export function readShmUsage(path = '/dev/shm'): { usedBytes: number; totalBytes: number } | null {
66
+ try {
67
+ const fs = statfsSync(path)
68
+ const totalBytes = fs.blocks * fs.bsize
69
+ const usedBytes = (fs.blocks - fs.bfree) * fs.bsize
70
+ return { usedBytes, totalBytes }
71
+ } catch {
72
+ return null
73
+ }
74
+ }
75
+
76
+ export function collectResourceSample(
77
+ options: { procRoot?: string; shmPath?: string; selfPid?: number } = {},
78
+ ): ResourceSample {
79
+ const shm = readShmUsage(options.shmPath)
80
+ return {
81
+ rssBytes: process.memoryUsage().rss,
82
+ shmUsedBytes: shm?.usedBytes ?? null,
83
+ shmTotalBytes: shm?.totalBytes ?? null,
84
+ detachedProcesses: countDetachedProcesses(options.procRoot, options.selfPid),
85
+ }
86
+ }
87
+
88
+ export function formatResourceSample(sample: ResourceSample): string {
89
+ const mb = (bytes: number | null): string => (bytes === null ? '?' : String(Math.round(bytes / BYTES_PER_MB)))
90
+ return [
91
+ `rss_mb=${mb(sample.rssBytes)}`,
92
+ `shm_used_mb=${mb(sample.shmUsedBytes)}`,
93
+ `shm_total_mb=${mb(sample.shmTotalBytes)}`,
94
+ `detached_procs=${sample.detachedProcesses ?? '?'}`,
95
+ ].join(' ')
96
+ }
97
+
98
+ export type SampleWatermark = {
99
+ rssBytes: number
100
+ shmUsedBytes: number
101
+ detachedProcesses: number
102
+ emittedAt: number
103
+ }
104
+
105
+ // Emit on growth, not on a clock.
106
+ //
107
+ // A steady heartbeat drowns the signal in identical lines and still misses the
108
+ // moment a number moved, while emitting every sample makes a 14-day log mostly
109
+ // noise. A leak is precisely a sequence of new high-water marks, so emitting
110
+ // only when one is set — with a margin so ordinary churn stays quiet — turns the
111
+ // log into the growth curve an OOM post-mortem actually needs. The periodic
112
+ // floor keeps a flat container from going completely silent, which is itself
113
+ // evidence.
114
+ export const RSS_GROWTH_MARGIN_BYTES = 128 * BYTES_PER_MB
115
+ export const SHM_GROWTH_MARGIN_BYTES = 64 * BYTES_PER_MB
116
+ export const HEARTBEAT_MS = 30 * 60 * 1000
117
+
118
+ export function shouldEmitSample(previous: SampleWatermark | null, sample: ResourceSample, now: number): boolean {
119
+ if (previous === null) return true
120
+ if (now - previous.emittedAt >= HEARTBEAT_MS) return true
121
+ if (sample.rssBytes >= previous.rssBytes + RSS_GROWTH_MARGIN_BYTES) return true
122
+ if ((sample.shmUsedBytes ?? 0) >= previous.shmUsedBytes + SHM_GROWTH_MARGIN_BYTES) return true
123
+ if ((sample.detachedProcesses ?? 0) > previous.detachedProcesses) return true
124
+ return false
125
+ }
126
+
127
+ export function nextWatermark(previous: SampleWatermark | null, sample: ResourceSample, now: number): SampleWatermark {
128
+ return {
129
+ rssBytes: Math.max(previous?.rssBytes ?? 0, sample.rssBytes),
130
+ shmUsedBytes: Math.max(previous?.shmUsedBytes ?? 0, sample.shmUsedBytes ?? 0),
131
+ detachedProcesses: Math.max(previous?.detachedProcesses ?? 0, sample.detachedProcesses ?? 0),
132
+ emittedAt: now,
133
+ }
134
+ }
135
+
136
+ export const SAMPLE_INTERVAL_MS = 60_000
137
+
138
+ export type ResourceSamplerOptions = {
139
+ intervalMs?: number
140
+ collect?: () => ResourceSample
141
+ emit?: (line: string) => void
142
+ now?: () => number
143
+ }
144
+
145
+ // Returns a stop function rather than running forever so the caller owns the
146
+ // lifetime. `unref` keeps a container that is otherwise done from being held
147
+ // open by the sampler alone.
148
+ export function startResourceSampler(options: ResourceSamplerOptions = {}): () => void {
149
+ const intervalMs = options.intervalMs ?? SAMPLE_INTERVAL_MS
150
+ const collect = options.collect ?? (() => collectResourceSample())
151
+ const emit = options.emit ?? ((line: string) => console.info(line))
152
+ const now = options.now ?? (() => Date.now())
153
+
154
+ let watermark: SampleWatermark | null = null
155
+ const tick = (): void => {
156
+ try {
157
+ const sample = collect()
158
+ const at = now()
159
+ if (!shouldEmitSample(watermark, sample, at)) return
160
+ watermark = nextWatermark(watermark, sample, at)
161
+ emit(`[resource-sample] ${formatResourceSample(sample)}`)
162
+ } catch (err) {
163
+ // A sampler must never be able to take the agent down.
164
+ emit(`[resource-sample] failed: ${err instanceof Error ? err.message : String(err)}`)
165
+ }
166
+ }
167
+
168
+ const timer = setInterval(tick, intervalMs)
169
+ timer.unref?.()
170
+ return () => clearInterval(timer)
171
+ }
@@ -46,7 +46,14 @@ export {
46
46
  verifyPrivilegedSandboxRuntime,
47
47
  type PrivilegedSandboxRuntime,
48
48
  } from './privileged-runtime'
49
- export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
49
+ export {
50
+ ensureSessionTmpDir,
51
+ isUnderTmp,
52
+ mapVirtualTmpPath,
53
+ SESSION_TMP_ROOT,
54
+ enterSubagentTmpScope,
55
+ sessionTmpDir,
56
+ } from './session-tmp'
50
57
  export {
51
58
  DEPENDENCY_BIN_SANDBOX_DIR,
52
59
  DEPENDENCY_BIN_SANDBOX_PATH,
@@ -15,8 +15,33 @@ const { isAbsolute, join, relative, resolve } = posix
15
15
  // anything into the project surface.
16
16
  export const SESSION_TMP_ROOT = '/tmp/typeclaw-session'
17
17
 
18
+ // A subagent tree shares one scratch dir: its top-level subagent's. Runtime-
19
+ // owned scratch (a reviewer checkout) is handed to child subagents by `/tmp`
20
+ // path, and a child with its own `/tmp` cannot resolve it. The scope is anchored
21
+ // BELOW the spawning channel/TUI/cron session on purpose: that session persists
22
+ // across turns and speakers, so subagent artifacts must never land in its
23
+ // scratch. Unrelated sessions stay isolated. Each entry is resolved to its
24
+ // anchor at registration, so releasing an intermediate parent never re-routes a
25
+ // still-running grandchild.
26
+ const subagentTmpScopes = new Map<string, { scope: string; refs: number }>()
27
+
18
28
  export function sessionTmpDir(sessionId: string): string {
19
- return join(SESSION_TMP_ROOT, sessionId)
29
+ return join(SESSION_TMP_ROOT, subagentTmpScopes.get(sessionId)?.scope ?? sessionId)
30
+ }
31
+
32
+ export function enterSubagentTmpScope(sessionId: string, parentSessionId: string): () => void {
33
+ const existing = subagentTmpScopes.get(sessionId)
34
+ const scope = existing?.scope ?? subagentTmpScopes.get(parentSessionId)?.scope ?? sessionId
35
+ subagentTmpScopes.set(sessionId, { scope, refs: (existing?.refs ?? 0) + 1 })
36
+ let released = false
37
+ return () => {
38
+ if (released) return
39
+ released = true
40
+ const entry = subagentTmpScopes.get(sessionId)
41
+ if (entry === undefined) return
42
+ if (entry.refs <= 1) subagentTmpScopes.delete(sessionId)
43
+ else entry.refs -= 1
44
+ }
20
45
  }
21
46
 
22
47
  export async function ensureSessionTmpDir(sessionId: string): Promise<string> {