typeclaw 0.46.2 → 0.47.1

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 (42) hide show
  1. package/README.md +2 -1
  2. package/package.json +1 -1
  3. package/src/agent/git-nudge.ts +4 -12
  4. package/src/agent/session-origin.ts +8 -6
  5. package/src/agent/tools/channel-reply.ts +13 -13
  6. package/src/agent/tools/channel-send.ts +3 -3
  7. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +4 -11
  8. package/src/bundled-plugins/memory/dreaming.ts +28 -67
  9. package/src/bundled-plugins/memory/load-shards.ts +31 -3
  10. package/src/bundled-plugins/memory/memory-logger.ts +2 -1
  11. package/src/bundled-plugins/memory/memory-snapshot.ts +8 -0
  12. package/src/bundled-plugins/memory/vector/embedder.ts +28 -9
  13. package/src/bundled-plugins/security/policies/git-exfil.ts +45 -27
  14. package/src/channels/adapters/telegram-bot-classify.ts +29 -0
  15. package/src/channels/continuation-willingness.ts +2 -2
  16. package/src/channels/github-false-receipt.ts +4 -4
  17. package/src/channels/github-rereview-guard.ts +8 -8
  18. package/src/channels/router.ts +276 -58
  19. package/src/channels/types.ts +7 -0
  20. package/src/cli/command-meta.ts +2 -0
  21. package/src/cli/compose-stats.ts +103 -0
  22. package/src/cli/compose.ts +13 -0
  23. package/src/cli/index.ts +1 -0
  24. package/src/cli/stats.ts +134 -0
  25. package/src/compose/index.ts +1 -0
  26. package/src/compose/stats.ts +51 -0
  27. package/src/config/config.ts +14 -0
  28. package/src/config/index.ts +4 -0
  29. package/src/container/controller.ts +6 -0
  30. package/src/container/index.ts +1 -0
  31. package/src/container/log-archive.ts +448 -0
  32. package/src/container/shared.ts +30 -13
  33. package/src/container/start.ts +78 -63
  34. package/src/container/stats.ts +86 -0
  35. package/src/container/stop.ts +63 -36
  36. package/src/git/run.ts +60 -0
  37. package/src/init/restart-deps-preflight.ts +2 -2
  38. package/src/run/index.ts +5 -0
  39. package/src/run/resource-report.ts +226 -0
  40. package/src/sandbox/canonical-secrets.ts +1 -0
  41. package/src/skills/typeclaw-channel-github/SKILL.md +4 -4
  42. package/typeclaw.schema.json +14 -0
@@ -0,0 +1,448 @@
1
+ import { randomBytes } from 'node:crypto'
2
+ import { chmod, lstat, mkdir, open, opendir, rename, rm, type FileHandle } from 'node:fs/promises'
3
+ import { join } from 'node:path'
4
+
5
+ import { DEFAULT_LOG_RETENTION_DAYS, MAX_LOG_RETENTION_DAYS } from '@/config'
6
+
7
+ import { resolveDockerBinary, sanitizeDockerStderr } from './shared'
8
+
9
+ export type DockerLogArchiveResult = { ok: true; status: 'archived'; path: string } | { ok: false; reason: string }
10
+
11
+ export type DockerLogArchiver = (input: {
12
+ agentDir: string
13
+ containerId: string
14
+ retentionDays?: number
15
+ }) => Promise<DockerLogArchiveResult>
16
+
17
+ export type StreamCaptureInput = {
18
+ args: string[]
19
+ binary: string
20
+ cwd: string
21
+ finalSettlementMs?: number
22
+ killFallbackMs?: number
23
+ maxBytes: number
24
+ output: FileHandle
25
+ spawn?: (input: { args: string[]; binary: string; cwd: string }) => StreamingProcess
26
+ timeoutMs: number
27
+ writeChunk?: (output: FileHandle, chunk: Uint8Array, offset: number) => Promise<number>
28
+ writeSettlementMs?: number
29
+ }
30
+
31
+ export type StreamingProcess = {
32
+ exited: Promise<number>
33
+ kill(signal: NodeJS.Signals): void
34
+ stderr: ReadableStream<Uint8Array>
35
+ stdout: ReadableStream<Uint8Array>
36
+ unref(): void
37
+ }
38
+
39
+ export type StreamCaptureResult = {
40
+ exitCode: number
41
+ overflowed: boolean
42
+ stderrExcerpt: string
43
+ terminationBoundExceeded?: boolean
44
+ timedOut: boolean
45
+ }
46
+
47
+ export type DockerLogArchiveRuntime = {
48
+ capture?: (input: StreamCaptureInput) => Promise<StreamCaptureResult>
49
+ nonce?: () => string
50
+ now?: () => Date
51
+ resolveDockerBinary?: () => string | null
52
+ }
53
+
54
+ export const DOCKER_LOG_ARCHIVE_TIMEOUT_MS = 60_000
55
+ export const MAX_DOCKER_LOG_ARCHIVE_BYTES = 64 * 1024 * 1024
56
+ export const MAX_DOCKER_LOG_ARCHIVE_SNAPSHOTS = 512
57
+ export const MAX_DOCKER_LOG_ARCHIVE_TOTAL_BYTES = 512 * 1024 * 1024
58
+
59
+ const MAX_ARCHIVE_DIRECTORY_ENTRIES = 2048
60
+ const STDERR_EXCERPT_BYTES = 8 * 1024
61
+ const KILL_FALLBACK_MS = 1_000
62
+ const FINAL_SETTLEMENT_MS = 1_000
63
+ const CLEANUP_SETTLEMENT_MS = 1_000
64
+ const WRITE_SETTLEMENT_MS = 60_000
65
+ const STALE_PARTIAL_GRACE_MS = 5 * 60 * 1_000
66
+ const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1_000
67
+ const MAX_FILENAME_ATTEMPTS = 16
68
+ const CONTAINER_ID_PATTERN = /^[a-f0-9]{64}$/
69
+ const NONCE_PATTERN = /^[a-f0-9]{32}$/
70
+ const ARCHIVE_FILENAME_PATTERN = /^[a-f0-9]{64}-(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z-[a-f0-9]{32}\.log$/
71
+ const PARTIAL_FILENAME_PATTERN = /^\.[a-f0-9]{64}-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-\d{3}Z-[a-f0-9]{32}\.partial$/
72
+
73
+ export async function archiveContainerLogs(
74
+ { agentDir, containerId, retentionDays = DEFAULT_LOG_RETENTION_DAYS }: Parameters<DockerLogArchiver>[0],
75
+ runtime: DockerLogArchiveRuntime = {},
76
+ ): Promise<DockerLogArchiveResult> {
77
+ if (!CONTAINER_ID_PATTERN.test(containerId)) {
78
+ return { ok: false, reason: `Invalid full Docker container ID: ${containerId}` }
79
+ }
80
+ if (!Number.isInteger(retentionDays) || retentionDays < 1 || retentionDays > MAX_LOG_RETENTION_DAYS) {
81
+ return { ok: false, reason: `Invalid Docker log archive retention period: ${retentionDays}` }
82
+ }
83
+
84
+ const logsDir = join(agentDir, '.typeclaw', 'logs')
85
+ let temporaryPath: string | null = null
86
+ let output: FileHandle | null = null
87
+
88
+ try {
89
+ await ensurePrivateDirectory(join(agentDir, '.typeclaw'))
90
+ await ensurePrivateDirectory(logsDir)
91
+ const now = runtime.now?.() ?? new Date()
92
+ const ageCutoff = now.getTime() - retentionDays * MILLISECONDS_PER_DAY
93
+ await pruneByAgeAndRemoveStalePartials(logsDir, ageCutoff, now.getTime())
94
+
95
+ const allocation = await allocateArchive(logsDir, containerId, archiveTimestampText(now), runtime)
96
+ temporaryPath = allocation.temporaryPath
97
+ output = allocation.output
98
+
99
+ const resolver = runtime.resolveDockerBinary ?? resolveDockerBinary
100
+ const binary = resolver()
101
+ if (binary === null) throw new Error('Docker binary could not be resolved for log archival')
102
+
103
+ const capture = runtime.capture ?? streamProcessOutput
104
+ const captured = await capture({
105
+ args: ['logs', '--timestamps', containerId],
106
+ binary,
107
+ cwd: agentDir,
108
+ maxBytes: MAX_DOCKER_LOG_ARCHIVE_BYTES,
109
+ output,
110
+ timeoutMs: DOCKER_LOG_ARCHIVE_TIMEOUT_MS,
111
+ })
112
+ if (captured.terminationBoundExceeded) throw new Error('docker logs did not settle after SIGKILL')
113
+ if (captured.timedOut) throw new Error(`docker logs timed out after ${DOCKER_LOG_ARCHIVE_TIMEOUT_MS}ms`)
114
+ if (captured.overflowed) {
115
+ throw new Error(`docker logs exceeded the ${MAX_DOCKER_LOG_ARCHIVE_BYTES}-byte archive limit`)
116
+ }
117
+ if (captured.exitCode !== 0) {
118
+ const detail = sanitizeDockerStderr(captured.stderrExcerpt)
119
+ throw new Error(`docker logs exited with code ${captured.exitCode}${detail ? `: ${detail}` : ''}`)
120
+ }
121
+
122
+ await output.chmod(0o600)
123
+ const incomingSize = (await output.stat()).size
124
+ await pruneToCapacity(logsDir, incomingSize)
125
+ await output.close()
126
+ output = null
127
+
128
+ await rename(temporaryPath, allocation.finalPath)
129
+ temporaryPath = null
130
+ await chmod(allocation.finalPath, 0o600)
131
+ return { ok: true, status: 'archived', path: allocation.finalPath }
132
+ } catch (error) {
133
+ const cleanupErrors = await cleanupTemp(output, temporaryPath)
134
+ const suffix = cleanupErrors.length === 0 ? '' : ` (${cleanupErrors.join('; ')})`
135
+ return { ok: false, reason: `${errorMessage(error)}${suffix}` }
136
+ }
137
+ }
138
+
139
+ export async function streamProcessOutput(input: StreamCaptureInput): Promise<StreamCaptureResult> {
140
+ const { args, binary, cwd, maxBytes, output, timeoutMs } = input
141
+ const killFallbackMs = input.killFallbackMs ?? KILL_FALLBACK_MS
142
+ const finalSettlementMs = input.finalSettlementMs ?? FINAL_SETTLEMENT_MS
143
+ const writeChunk = input.writeChunk ?? writeFileChunk
144
+ const writeSettlementMs = input.writeSettlementMs ?? WRITE_SETTLEMENT_MS
145
+ const proc = input.spawn?.({ args, binary, cwd }) ?? spawnStreamingProcess(input)
146
+ const abortPumps = new AbortController()
147
+ const stderrChunks: Uint8Array[] = []
148
+ let stderrBytes = 0
149
+ let acceptedBytes = 0
150
+ let overflowed = false
151
+ let timedOut = false
152
+ let terminating = false
153
+ let processSettled = false
154
+ let terminationBoundExceeded = false
155
+ let pumpError: unknown
156
+ let writeError: unknown
157
+ let writeQueue = Promise.resolve()
158
+ let sigkillTimer: ReturnType<typeof setTimeout> | undefined
159
+ let finalTimer: ReturnType<typeof setTimeout> | undefined
160
+ let forceSettle: ((exitCode: number) => void) | undefined
161
+ const forcedExit = new Promise<number>((resolve) => {
162
+ forceSettle = resolve
163
+ })
164
+
165
+ const terminate = (): void => {
166
+ if (terminating || processSettled) return
167
+ terminating = true
168
+ proc.kill('SIGTERM')
169
+ sigkillTimer = setTimeout(() => {
170
+ proc.kill('SIGKILL')
171
+ finalTimer = setTimeout(() => {
172
+ terminationBoundExceeded = true
173
+ abortPumps.abort()
174
+ proc.unref()
175
+ forceSettle?.(-1)
176
+ }, finalSettlementMs)
177
+ }, killFallbackMs)
178
+ }
179
+
180
+ const enqueue = (chunk: Uint8Array, stderr: boolean): void => {
181
+ if (stderr && stderrBytes < STDERR_EXCERPT_BYTES) {
182
+ const excerpt = chunk.subarray(0, STDERR_EXCERPT_BYTES - stderrBytes)
183
+ stderrChunks.push(excerpt)
184
+ stderrBytes += excerpt.byteLength
185
+ }
186
+ if (terminating) return
187
+ if (acceptedBytes + chunk.byteLength > maxBytes) {
188
+ overflowed = true
189
+ terminate()
190
+ return
191
+ }
192
+ acceptedBytes += chunk.byteLength
193
+ writeQueue = writeQueue
194
+ .then(async () => {
195
+ await writeAll(output, chunk, writeChunk)
196
+ })
197
+ .catch((error: unknown) => {
198
+ writeError = error
199
+ terminate()
200
+ })
201
+ }
202
+
203
+ const timeout = setTimeout(() => {
204
+ timedOut = true
205
+ terminate()
206
+ }, timeoutMs)
207
+ const stdoutPump = pump(proc.stdout, (chunk) => enqueue(chunk, false), abortPumps.signal).catch((error: unknown) => {
208
+ pumpError = error
209
+ terminate()
210
+ })
211
+ const stderrPump = pump(proc.stderr, (chunk) => enqueue(chunk, true), abortPumps.signal).catch((error: unknown) => {
212
+ pumpError = error
213
+ terminate()
214
+ })
215
+ const completion = Promise.all([proc.exited, stdoutPump, stderrPump]).then(([exitCode]) => {
216
+ processSettled = true
217
+ return exitCode
218
+ })
219
+
220
+ const exitCode = await Promise.race([completion, forcedExit])
221
+ clearTimeout(timeout)
222
+ if (sigkillTimer !== undefined) clearTimeout(sigkillTimer)
223
+ if (finalTimer !== undefined) clearTimeout(finalTimer)
224
+ if (terminationBoundExceeded) await Promise.allSettled([stdoutPump, stderrPump])
225
+ await withDeadline(writeQueue, writeSettlementMs, 'Docker log archive write')
226
+ if (writeError !== undefined) throw writeError
227
+ if (pumpError !== undefined) throw pumpError
228
+ return {
229
+ exitCode,
230
+ overflowed,
231
+ stderrExcerpt: Buffer.concat(stderrChunks).toString('utf8'),
232
+ terminationBoundExceeded,
233
+ timedOut,
234
+ }
235
+ }
236
+
237
+ async function writeAll(
238
+ output: FileHandle,
239
+ chunk: Uint8Array,
240
+ writeChunk: NonNullable<StreamCaptureInput['writeChunk']>,
241
+ ): Promise<void> {
242
+ let offset = 0
243
+ while (offset < chunk.byteLength) {
244
+ const bytesWritten = await writeChunk(output, chunk, offset)
245
+ if (bytesWritten < 1) throw new Error('Docker log archive write made no progress')
246
+ offset += bytesWritten
247
+ }
248
+ }
249
+
250
+ async function writeFileChunk(output: FileHandle, chunk: Uint8Array, offset: number): Promise<number> {
251
+ return (await output.write(chunk, offset, chunk.byteLength - offset)).bytesWritten
252
+ }
253
+
254
+ function spawnStreamingProcess({ args, binary, cwd }: StreamCaptureInput): StreamingProcess {
255
+ return Bun.spawn({ cmd: [binary, ...args], cwd, stdin: 'ignore', stdout: 'pipe', stderr: 'pipe' })
256
+ }
257
+
258
+ async function pump(
259
+ stream: ReadableStream<Uint8Array>,
260
+ onChunk: (chunk: Uint8Array) => void,
261
+ signal: AbortSignal,
262
+ ): Promise<void> {
263
+ const reader = stream.getReader()
264
+ const cancel = (): void => {
265
+ void reader.cancel()
266
+ }
267
+ signal.addEventListener('abort', cancel, { once: true })
268
+ try {
269
+ for (;;) {
270
+ const { done, value } = await reader.read()
271
+ if (done) return
272
+ onChunk(value)
273
+ }
274
+ } catch (error) {
275
+ if (!signal.aborted) throw error
276
+ } finally {
277
+ signal.removeEventListener('abort', cancel)
278
+ reader.releaseLock()
279
+ }
280
+ }
281
+
282
+ async function ensurePrivateDirectory(path: string): Promise<void> {
283
+ try {
284
+ await mkdir(path, { mode: 0o700 })
285
+ } catch (error) {
286
+ if (errorCode(error) !== 'EEXIST') throw error
287
+ }
288
+ const stats = await lstat(path)
289
+ if (stats.isSymbolicLink() || !stats.isDirectory())
290
+ throw new Error(`Docker log archive path is not a real directory: ${path}`)
291
+ await chmod(path, 0o700)
292
+ }
293
+
294
+ async function pruneByAgeAndRemoveStalePartials(logsDir: string, ageCutoff: number, now: number): Promise<void> {
295
+ const stalePartialCutoff = now - DOCKER_LOG_ARCHIVE_TIMEOUT_MS - STALE_PARTIAL_GRACE_MS
296
+ for (const entry of await collectDirectoryEntries(logsDir)) {
297
+ if (!entry.isFile()) continue
298
+ const path = join(logsDir, entry.name)
299
+ const timestamp = archiveTimestamp(entry.name)
300
+ if (timestamp !== null && timestamp < ageCutoff) {
301
+ await removeRaceSafe(path)
302
+ } else if (PARTIAL_FILENAME_PATTERN.test(entry.name)) {
303
+ const stats = await lstatIfPresent(path)
304
+ if (stats !== null && stats.mtimeMs < stalePartialCutoff) await removeRaceSafe(path)
305
+ }
306
+ }
307
+ }
308
+
309
+ async function pruneToCapacity(logsDir: string, incomingSize: number): Promise<void> {
310
+ if (incomingSize > MAX_DOCKER_LOG_ARCHIVE_TOTAL_BYTES) {
311
+ throw new Error('Docker log archive exceeds total archive capacity')
312
+ }
313
+ const snapshots: Array<{ name: string; path: string; size: number; timestamp: number }> = []
314
+ for (const entry of await collectDirectoryEntries(logsDir)) {
315
+ if (!entry.isFile()) continue
316
+ const timestamp = archiveTimestamp(entry.name)
317
+ if (timestamp === null) continue
318
+ const path = join(logsDir, entry.name)
319
+ const stats = await lstatIfPresent(path)
320
+ if (stats !== null) snapshots.push({ name: entry.name, path, size: stats.size, timestamp })
321
+ }
322
+ snapshots.sort((left, right) => left.timestamp - right.timestamp || left.name.localeCompare(right.name))
323
+ let totalBytes = snapshots.reduce((total, snapshot) => total + snapshot.size, 0)
324
+ let count = snapshots.length
325
+ for (const snapshot of snapshots) {
326
+ if (
327
+ count + 1 <= MAX_DOCKER_LOG_ARCHIVE_SNAPSHOTS &&
328
+ totalBytes + incomingSize <= MAX_DOCKER_LOG_ARCHIVE_TOTAL_BYTES
329
+ )
330
+ break
331
+ await removeRaceSafe(snapshot.path)
332
+ count -= 1
333
+ totalBytes -= snapshot.size
334
+ }
335
+ }
336
+
337
+ async function collectDirectoryEntries(logsDir: string) {
338
+ const entries = []
339
+ const directory = await opendir(logsDir)
340
+ for await (const entry of directory) {
341
+ entries.push(entry)
342
+ if (entries.length > MAX_ARCHIVE_DIRECTORY_ENTRIES)
343
+ throw new Error(`Docker log archive directory exceeds ${MAX_ARCHIVE_DIRECTORY_ENTRIES} entries`)
344
+ }
345
+ return entries
346
+ }
347
+
348
+ async function allocateArchive(
349
+ logsDir: string,
350
+ containerId: string,
351
+ timestamp: string,
352
+ runtime: DockerLogArchiveRuntime,
353
+ ): Promise<{ finalPath: string; output: FileHandle; temporaryPath: string }> {
354
+ for (let attempt = 0; attempt < MAX_FILENAME_ATTEMPTS; attempt++) {
355
+ const nonce = runtime.nonce?.() ?? randomBytes(16).toString('hex')
356
+ if (!NONCE_PATTERN.test(nonce)) throw new Error(`Invalid Docker log archive nonce: ${nonce}`)
357
+ const finalPath = join(logsDir, `${containerId}-${timestamp}-${nonce}.log`)
358
+ const temporaryPath = join(logsDir, `.${containerId}-${timestamp}-${nonce}.partial`)
359
+ let output: FileHandle
360
+ try {
361
+ output = await open(temporaryPath, 'wx', 0o600)
362
+ } catch (error) {
363
+ if (errorCode(error) === 'EEXIST') continue
364
+ throw error
365
+ }
366
+ try {
367
+ await lstat(finalPath)
368
+ } catch (error) {
369
+ if (errorCode(error) === 'ENOENT') return { finalPath, output, temporaryPath }
370
+ const cleanupErrors = await cleanupTemp(output, temporaryPath)
371
+ throw new Error([errorMessage(error), ...cleanupErrors].join('; '))
372
+ }
373
+ const cleanupErrors = await cleanupTemp(output, temporaryPath)
374
+ if (cleanupErrors.length > 0)
375
+ throw new Error(['Archive filename collision cleanup failed', ...cleanupErrors].join('; '))
376
+ }
377
+ throw new Error('Could not allocate a unique Docker log archive filename')
378
+ }
379
+
380
+ async function cleanupTemp(output: FileHandle | null, path: string | null): Promise<string[]> {
381
+ const errors: string[] = []
382
+ if (output !== null) {
383
+ try {
384
+ await withDeadline(output.close(), CLEANUP_SETTLEMENT_MS, 'Docker log archive temp close')
385
+ } catch (error) {
386
+ errors.push(`temp close failed: ${errorMessage(error)}`)
387
+ }
388
+ }
389
+ if (path !== null) {
390
+ try {
391
+ await withDeadline(rm(path, { force: true }), CLEANUP_SETTLEMENT_MS, 'Docker log archive temp cleanup')
392
+ } catch (error) {
393
+ errors.push(`temp cleanup failed: ${errorMessage(error)}`)
394
+ }
395
+ }
396
+ return errors
397
+ }
398
+
399
+ async function removeRaceSafe(path: string): Promise<void> {
400
+ try {
401
+ await rm(path)
402
+ } catch (error) {
403
+ if (errorCode(error) !== 'ENOENT') throw error
404
+ }
405
+ }
406
+
407
+ async function lstatIfPresent(path: string) {
408
+ try {
409
+ return await lstat(path)
410
+ } catch (error) {
411
+ if (errorCode(error) === 'ENOENT') return null
412
+ throw error
413
+ }
414
+ }
415
+
416
+ async function withDeadline<T>(promise: Promise<T>, timeoutMs: number, operation: string): Promise<T> {
417
+ let timer: ReturnType<typeof setTimeout> | undefined
418
+ try {
419
+ return await Promise.race([
420
+ promise,
421
+ new Promise<never>((_, reject) => {
422
+ timer = setTimeout(() => reject(new Error(`${operation} timed out after ${timeoutMs}ms`)), timeoutMs)
423
+ }),
424
+ ])
425
+ } finally {
426
+ if (timer !== undefined) clearTimeout(timer)
427
+ }
428
+ }
429
+
430
+ function archiveTimestamp(filename: string): number | null {
431
+ const match = ARCHIVE_FILENAME_PATTERN.exec(filename)
432
+ if (match === null) return null
433
+ const iso = `${match[1]}T${match[2]}:${match[3]}:${match[4]}.${match[5]}Z`
434
+ const timestamp = Date.parse(iso)
435
+ return Number.isFinite(timestamp) && new Date(timestamp).toISOString() === iso ? timestamp : null
436
+ }
437
+
438
+ function archiveTimestampText(date: Date): string {
439
+ return date.toISOString().replace(/[:.]/g, '-')
440
+ }
441
+
442
+ function errorCode(error: unknown): string | undefined {
443
+ return (error as NodeJS.ErrnoException).code
444
+ }
445
+
446
+ function errorMessage(error: unknown): string {
447
+ return error instanceof Error ? error.message : String(error)
448
+ }
@@ -24,6 +24,16 @@ export type DockerExecOptions = {
24
24
 
25
25
  export type DockerExec = (args: string[], options?: DockerExecOptions) => Promise<DockerExecResult>
26
26
 
27
+ export type ParsedContainerInspect = { ok: true; containerId: string; running: boolean } | { ok: false; reason: string }
28
+
29
+ export function parseContainerInspectOutput(output: string): ParsedContainerInspect {
30
+ const match = /^([0-9a-f]{64})\|(true|false)$/.exec(output.trim())
31
+ if (match === null) {
32
+ return { ok: false, reason: 'expected <64 lowercase hex container ID>|<true|false>' }
33
+ }
34
+ return { ok: true, containerId: match[1]!, running: match[2] === 'true' }
35
+ }
36
+
27
37
  export const defaultDockerExec: DockerExec = async (args, options) => {
28
38
  const bun = getBun()
29
39
  if (!bun) return { exitCode: -1, stdout: '', stderr: 'bun runtime not available' }
@@ -388,9 +398,8 @@ export function classifyRmStderr(stderr: string): BenignRmKind {
388
398
  // sleep-only retries cannot make it go away.
389
399
  //
390
400
  // The fix is destructive: when this error fires for a non-running same-name
391
- // container, force-remove it before retrying. See cleanupRunCorpse for the
392
- // safety contract (only force-remove containers that are NOT running, so a
393
- // concurrent legitimate start of the same name is never killed).
401
+ // container, remove it before retrying. cleanupRunCorpse uses non-force rm so
402
+ // Docker still refuses if that same ID starts after the inspect probe.
394
403
  //
395
404
  // Matches case-insensitively on the canonical phrasing across Docker
396
405
  // Engine, Docker Desktop, and OrbStack. The (or rename) clause is the
@@ -403,7 +412,7 @@ export function isContainerNameConflict(stderr: string): boolean {
403
412
  // Result of probing whether a previous `docker run --name <X>` left a corpse
404
413
  // blocking the next run:
405
414
  // - 'gone' — no container with that name. Safe to `docker run --name`.
406
- // - 'removed' — corpse existed and was force-removed (and waitForRemoval
415
+ // - 'removed' — corpse existed and was removed (and waitForRemoval
407
416
  // confirmed it disappeared). Safe to `docker run --name`.
408
417
  // - 'running' — a container with that name is currently RUNNING. We did
409
418
  // NOT remove it. Caller must NOT proceed with `docker run
@@ -412,11 +421,13 @@ export function isContainerNameConflict(stderr: string): boolean {
412
421
  // - 'stuck' — corpse existed but did not disappear within waitForRemoval
413
422
  // budget. Caller should surface a clear error rather than
414
423
  // loop forever.
415
- export type CorpseCleanupOutcome = 'gone' | 'removed' | 'running' | 'stuck'
424
+ export type BeforeContainerRemove = (containerId: string) => Promise<{ ok: true } | { ok: false; reason: string }>
416
425
 
417
- // Inspects the named container; if a non-running corpse is holding the
418
- // name (the failure mode behind `typeclaw compose restart`'s persistent
419
- // Conflict errors), force-removes it and waits for the removal to drain.
426
+ export type CorpseCleanupOutcome = 'gone' | 'removed' | 'running' | 'stuck' | { archiveFailed: string }
427
+
428
+ // Inspects the named container; if a non-running corpse is holding the name,
429
+ // runs the caller's required archival hook, removes it without force, and waits for the
430
+ // removal to drain. An archival failure leaves the corpse untouched.
420
431
  // Explicitly refuses to touch a RUNNING container so that a concurrent
421
432
  // legitimate start of the same name (or a foreign-but-named container the
422
433
  // user wants kept alive) is never killed by this cleanup path. Errors from
@@ -433,13 +444,19 @@ export type CorpseCleanupOutcome = 'gone' | 'removed' | 'running' | 'stuck'
433
444
  // container" which classifyRmStderr folds into 'gone'. waitForRemoval
434
445
  // is still keyed on name because that's what the caller's next
435
446
  // `docker run --name <name>` will actually collide on.
436
- export async function cleanupRunCorpse(exec: DockerExec, name: string): Promise<CorpseCleanupOutcome> {
447
+ export async function cleanupRunCorpse(
448
+ exec: DockerExec,
449
+ name: string,
450
+ beforeRemove: BeforeContainerRemove,
451
+ ): Promise<CorpseCleanupOutcome> {
437
452
  const probe = await exec(['inspect', '--format', '{{.Id}}|{{.State.Running}}', name])
438
453
  if (probe.exitCode !== 0) return 'gone'
439
- const [id = '', running = ''] = probe.stdout.trim().split('|')
440
- if (running === 'true') return 'running'
441
- if (id === '') return 'stuck'
442
- const rm = await exec(['rm', '-f', id])
454
+ const parsed = parseContainerInspectOutput(probe.stdout)
455
+ if (!parsed.ok) return 'stuck'
456
+ if (parsed.running) return 'running'
457
+ const prepared = await beforeRemove(parsed.containerId)
458
+ if (!prepared.ok) return { archiveFailed: prepared.reason }
459
+ const rm = await exec(['rm', parsed.containerId])
443
460
  if (rm.exitCode !== 0) {
444
461
  const kind = classifyRmStderr(rm.stderr)
445
462
  if (kind === 'gone') return 'gone'