typeclaw 0.48.10 → 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 (68) hide show
  1. package/package.json +2 -2
  2. package/scripts/apparmor/typeclaw-bwrap +43 -0
  3. package/scripts/verify-apparmor-signals.sh +161 -0
  4. package/scripts/verify-mask-fd-sandbox.sh +86 -16
  5. package/src/agent/index.ts +11 -1
  6. package/src/agent/live-subagents.ts +98 -0
  7. package/src/agent/session-origin.ts +5 -1
  8. package/src/agent/tools/channel-reply.ts +30 -2
  9. package/src/agent/tools/channel-send.ts +19 -2
  10. package/src/agent/tools/spawn-subagent.ts +37 -1
  11. package/src/bundled-plugins/github-cli-auth/gh-command.ts +7 -1
  12. package/src/bundled-plugins/github-cli-auth/index.ts +2 -1
  13. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +9 -1
  14. package/src/bundled-plugins/memory/dreaming.ts +21 -6
  15. package/src/channels/adapters/github/inbound.ts +195 -25
  16. package/src/channels/adapters/github/index.ts +16 -18
  17. package/src/channels/adapters/github/reconcile-cooldown-store.ts +15 -1
  18. package/src/channels/adapters/github/recover-failed-deliveries.ts +7 -2
  19. package/src/channels/adapters/github/review-submitter.ts +28 -0
  20. package/src/channels/adapters/kakaotalk-channel-resolver.ts +86 -16
  21. package/src/channels/adapters/kakaotalk.ts +7 -8
  22. package/src/channels/adapters/teams-classify.ts +21 -0
  23. package/src/channels/adapters/teams-edit.ts +2 -1
  24. package/src/channels/adapters/teams-format.ts +16 -0
  25. package/src/channels/adapters/teams.ts +12 -5
  26. package/src/channels/github-repo.ts +11 -0
  27. package/src/channels/github-review-verdict-coordinator.ts +179 -29
  28. package/src/channels/github-verdict-activity.ts +10 -6
  29. package/src/channels/manager.ts +9 -0
  30. package/src/channels/persistence.ts +28 -2
  31. package/src/channels/router.ts +284 -61
  32. package/src/channels/schema.ts +18 -0
  33. package/src/channels/types.ts +1 -0
  34. package/src/cli/compose.ts +3 -3
  35. package/src/cli/docker-preflight.ts +8 -4
  36. package/src/cli/restart.ts +89 -23
  37. package/src/cli/start.ts +68 -16
  38. package/src/cli/status.ts +38 -6
  39. package/src/cli/stop.ts +5 -2
  40. package/src/compose/stop.ts +5 -4
  41. package/src/config/config.ts +9 -1
  42. package/src/container/build-cache.ts +807 -0
  43. package/src/container/compose-project.ts +4 -0
  44. package/src/container/docker-app.ts +74 -0
  45. package/src/container/log-archive.ts +33 -5
  46. package/src/container/memory-limit.ts +80 -0
  47. package/src/container/memory-oversubscription.ts +125 -0
  48. package/src/container/restart.ts +6 -1
  49. package/src/container/shared.ts +43 -16
  50. package/src/container/start.ts +313 -77
  51. package/src/container/stop.ts +19 -13
  52. package/src/container/verify-running.ts +12 -0
  53. package/src/cron/scheduler.ts +12 -4
  54. package/src/doctor/apparmor.ts +101 -0
  55. package/src/doctor/bounded-exec.ts +14 -0
  56. package/src/doctor/checks.ts +42 -15
  57. package/src/doctor/index.ts +14 -2
  58. package/src/doctor/plugin-bridge.ts +15 -3
  59. package/src/hostd/paths.ts +4 -0
  60. package/src/init/dockerfile.ts +7 -6
  61. package/src/init/windows-dev-link.ts +34 -2
  62. package/src/run/index.ts +17 -0
  63. package/src/run/resource-sample.ts +171 -0
  64. package/src/sandbox/availability.ts +7 -5
  65. package/src/sandbox/index.ts +8 -1
  66. package/src/sandbox/session-tmp.ts +26 -1
  67. package/src/skills/typeclaw-channel-github/SKILL.md +4 -2
  68. package/typeclaw.schema.json +7 -0
@@ -36,11 +36,20 @@ import {
36
36
  type GithubCliProvisionResult,
37
37
  type ProvisionGithubCliStoreOptions,
38
38
  } from '@/secrets/provision-github-cli-store'
39
+ import { SecretsBackend } from '@/secrets/storage'
39
40
  import { isWindows } from '@/shared'
40
41
  import { hostLocaleIsCjk } from '@/shared/host-locale'
41
42
 
42
43
  import { type AgentOperationLease, type WithAgentOperationLock, withAgentOperationLock } from './agent-operation-lock'
43
- import { archiveContainerLogs, type DockerLogArchiver } from './log-archive'
44
+ import { acquireManagedBuildCache, type ManagedBuildCacheLease } from './build-cache'
45
+ import { COMPOSE_PROJECT } from './compose-project'
46
+ import { archiveContainerLogs, dockerLogsUnavailableWarning, type DockerLogArchiver } from './log-archive'
47
+ import { formatMemorySize, readDockerTotalMemory, resolveMemoryLimit } from './memory-limit'
48
+ import {
49
+ decideMemoryOversubscription,
50
+ formatOversubscriptionWarning,
51
+ readRunningAgentMemoryClaims,
52
+ } from './memory-oversubscription'
44
53
  import { CONTAINER_PORT, TUI_TOKEN_LABEL, findFreePort, isPortAllocatedError, resolveTuiToken } from './port'
45
54
  import {
46
55
  buildxAvailable,
@@ -59,7 +68,12 @@ import {
59
68
  sanitizeDockerConfigJson,
60
69
  sanitizeDockerStderr,
61
70
  } from './shared'
62
- import { buildCrashReason, createVerifyRunning, type VerifyRunningFn } from './verify-running'
71
+ import {
72
+ buildCrashReason,
73
+ createVerifyRunning,
74
+ describeUnremovableContainer,
75
+ type VerifyRunningFn,
76
+ } from './verify-running'
63
77
 
64
78
  const PACKAGE_FILE = 'package.json'
65
79
  const TYPECLAW_PACKAGE = 'typeclaw'
@@ -67,7 +81,6 @@ const DEV_SOURCE_CONTAINER_PATH = '/agent/node_modules/typeclaw'
67
81
  const BUN_LOCK_FILE = 'bun.lock'
68
82
  const DEPENDENCY_FILES = [PACKAGE_FILE, BUN_LOCK_FILE] as const
69
83
  const ENV_FILE = '.env'
70
- const COMPOSE_PROJECT = 'typeclaw'
71
84
  const CONTAINER_HOSTD_HOST = 'host.docker.internal'
72
85
  const HOST_GATEWAY_ALIAS = `${CONTAINER_HOSTD_HOST}:host-gateway`
73
86
 
@@ -82,6 +95,7 @@ export type StartPlan = {
82
95
  needsBuild: boolean
83
96
  hostPort: number
84
97
  tuiToken: string | null
98
+ memoryLimitBytes: number
85
99
  }
86
100
 
87
101
  export type PlanStartOptions = {
@@ -99,6 +113,12 @@ export type PlanStartOptions = {
99
113
  // Omitted when unavailable (native Windows and unusual JS hosts).
100
114
  hostIdentity?: { uid: number; gid: number } | null
101
115
  gitIdentity?: GitIdentity | null
116
+ // Total memory of the machine the CONTAINER runs on, used only to clamp the
117
+ // default memory limit down when it will not fit. On macOS and Windows that
118
+ // is the Docker VM, not the workstation, so start() reads it from the daemon
119
+ // rather than from os.totalmem(). Omitted by callers that have no exec (and
120
+ // by tests), in which case the default applies unclamped.
121
+ totalMemoryBytes?: number | undefined
102
122
  }
103
123
 
104
124
  export type HostDaemonControl = {
@@ -197,6 +217,8 @@ export type StartOptions = {
197
217
  archiveLogs?: DockerLogArchiver
198
218
  operationLock?: WithAgentOperationLock
199
219
  operationLease?: AgentOperationLease
220
+ buildCacheStateDir?: string
221
+ acquireBuildCache?: typeof acquireManagedBuildCache | null
200
222
  }
201
223
 
202
224
  export type HostDaemonStatus =
@@ -267,16 +289,30 @@ async function runStart({
267
289
  assertConfigWritable = assertAgentConfigWritable,
268
290
  provisionGithubCliStore: provisionGithubCliStoreForAgent = provisionGithubCliStore,
269
291
  archiveLogs = archiveContainerLogs,
292
+ buildCacheStateDir,
293
+ acquireBuildCache = acquireManagedBuildCache,
270
294
  }: StartOptions): Promise<StartResult> {
271
295
  try {
272
296
  const containerName = containerNameFromCwd(cwd)
273
297
  const imageTagValue = imageTagFromCwd(cwd)
274
- const archiveBeforeRemove = async (containerId: string) =>
275
- await archiveLogs({
298
+ const archiveBeforeRemove = async (containerId: string) => {
299
+ const archive = await archiveLogs({
276
300
  agentDir: cwd,
277
301
  containerId,
278
302
  retentionDays: (await loadTypeclawConfig(cwd)).logs.retentionDays,
279
303
  })
304
+ if (archive.ok) return { ok: true as const }
305
+ if (archive.kind === 'failed') return { ok: false as const, reason: archive.reason }
306
+ // Dispatch on the callback, NOT on streamOutput. `streamOutput` defaults
307
+ // to true, and standalone start/restart both stream Docker build output
308
+ // AND pass a collector so they can render warnings after their spinner
309
+ // settles; keying on streamOutput writes under the live spinner and
310
+ // leaves that collector empty. stderr stays the no-callback fallback.
311
+ const warning = dockerLogsUnavailableWarning(containerId)
312
+ if (onWarning !== undefined) onWarning(warning)
313
+ else if (streamOutput) process.stderr.write(`${warning}\n`)
314
+ return { ok: true as const }
315
+ }
280
316
 
281
317
  // Probe container state BEFORE refreshing Dockerfile/.gitignore: when the
282
318
  // container is already running, start() is a no-op and must not produce
@@ -525,14 +561,16 @@ async function runStart({
525
561
  }
526
562
  }
527
563
  if (cleanup === 'stuck') {
564
+ const reason = `Container ${containerName} could not be safely inspected or removed; preserving it and refusing to docker run --name to avoid a conflict.`
565
+ const diagnosis = await describeUnremovableContainer(exec, state.containerId)
528
566
  return {
529
567
  ok: false,
530
- reason: `Container ${containerName} could not be safely inspected or removed; preserving it and refusing to docker run --name to avoid a conflict.`,
568
+ reason: diagnosis === null ? reason : `${reason} ${diagnosis}`,
531
569
  }
532
570
  }
533
571
  }
534
572
 
535
- const imageExisted = await imageExists(exec, imageTagValue)
573
+ const previousImageId = await inspectImageId(exec, imageTagValue)
536
574
 
537
575
  // First attempt uses the user's preferred host port (8973 by default, or
538
576
  // whatever they passed via --port / typeclaw.json). If it's already bound
@@ -549,28 +587,64 @@ async function runStart({
549
587
 
550
588
  const publishHost = await resolvePublishHost(exec)
551
589
  const tuiToken = randomBytes(32).toString('base64url')
590
+ const totalMemoryBytes = await readDockerTotalMemory(exec)
552
591
  let plan = await planStart({
553
592
  cwd,
554
593
  hostPort,
555
- imageExists: imageExisted,
594
+ imageExists: previousImageId !== null,
556
595
  forceBuild: forceBuild || dockerfileRefresh.changed,
557
596
  hostdControl,
558
597
  publishHost,
559
598
  tuiToken,
560
599
  platform,
561
600
  hostIdentity,
601
+ totalMemoryBytes,
602
+ })
603
+
604
+ await warnOnMemoryOversubscription({
605
+ exec,
606
+ containerName,
607
+ memoryLimitBytes: plan.memoryLimitBytes,
608
+ totalMemoryBytes,
609
+ onWarning,
610
+ streamOutput,
562
611
  })
563
612
 
564
613
  let built = false
565
614
  if (plan.needsBuild) {
566
- const buildResult = await runImageBuild({
567
- exec,
568
- cwd,
569
- imageTag: plan.imageTag,
570
- buildContext: plan.buildContext,
571
- hasBuildx,
572
- streamOutput,
573
- })
615
+ const buildWarning = (warning: string): void => {
616
+ if (streamOutput) process.stderr.write(`typeclaw: ${warning}\n`)
617
+ else onWarning?.(warning)
618
+ }
619
+ const protection = await protectImageForRebuild(exec, plan.imageTag, previousImageId)
620
+ if (protection.warning !== null) {
621
+ if (streamOutput) process.stderr.write(`typeclaw: ${protection.warning}\n`)
622
+ else onWarning?.(protection.warning)
623
+ }
624
+
625
+ let buildResult: Awaited<ReturnType<typeof runImageBuild>>
626
+ try {
627
+ buildResult = await runImageBuild({
628
+ exec,
629
+ cwd,
630
+ cacheScope: containerName,
631
+ imageTag: plan.imageTag,
632
+ buildContext: plan.buildContext,
633
+ hasBuildx,
634
+ acquireBuildCache,
635
+ buildCacheStateDir,
636
+ streamOutput,
637
+ onWarning: buildWarning,
638
+ })
639
+ } finally {
640
+ if (protection.tag !== null) {
641
+ const releaseWarning = await releaseImageProtection(exec, protection.tag)
642
+ if (releaseWarning !== null) {
643
+ if (streamOutput) process.stderr.write(`typeclaw: ${releaseWarning}\n`)
644
+ else onWarning?.(releaseWarning)
645
+ }
646
+ }
647
+ }
574
648
  if (!buildResult.ok) {
575
649
  await cleanupHostDaemonRegistration(containerName, hostd)
576
650
  const retryDetail = buildResult.credentialHelperRetried
@@ -625,6 +699,7 @@ async function runStart({
625
699
  tuiToken,
626
700
  platform,
627
701
  hostIdentity,
702
+ totalMemoryBytes,
628
703
  })
629
704
  }
630
705
  } catch (error) {
@@ -697,6 +772,12 @@ async function runStart({
697
772
  publishHost,
698
773
  tuiToken,
699
774
  platform,
775
+ // Every replan must carry the daemon total. planStart resolves the
776
+ // memory limit from it, so dropping it here silently replaces a
777
+ // clamped limit with the unconditional default right before
778
+ // `docker run` — the launch would exceed what the VM can honor while
779
+ // the already-emitted warning still described the clamped figure.
780
+ totalMemoryBytes,
700
781
  })
701
782
  run = await execRunWithConflictRetry(exec, plan.runArgs, cwd, containerName, archiveBeforeRemove)
702
783
  }
@@ -745,6 +826,16 @@ async function refreshGithubCliStore(
745
826
  }
746
827
  if (refreshed) return null
747
828
 
829
+ // Only a failure that leaves an EXISTING store to go stale is worth an
830
+ // operator warning; with no store nothing regressed. This credential is
831
+ // OPTIONAL — authenticated `git push` and PR review ride the agent's own
832
+ // per-repo App token (`github.resolveTokenForRepo`, injected via GIT_ASKPASS
833
+ // by `github-cli-auth` and the backup runner), and the host store only backs
834
+ // `gh` invocations the broker cannot scope to a literal owner/repo. Warning
835
+ // unconditionally told every agent to run `gh auth login` for a capability
836
+ // most never use, citing a persisted store that did not exist.
837
+ if (!hasPersistedGithubCliStore(agentDir)) return null
838
+
748
839
  return (
749
840
  'typeclaw: warning: Could not refresh GitHub CLI credentials from the host. ' +
750
841
  'Keeping the previously persisted credential store. Run `gh auth login --hostname github.com` on the host, ' +
@@ -752,6 +843,16 @@ async function refreshGithubCliStore(
752
843
  )
753
844
  }
754
845
 
846
+ // An unreadable or malformed secrets.json cannot prove the store is absent, so
847
+ // it takes the warning — silence is reserved for a confirmed no-store agent.
848
+ function hasPersistedGithubCliStore(agentDir: string): boolean {
849
+ try {
850
+ return new SecretsBackend(join(agentDir, 'secrets.json')).tryReadGithubCliSync() !== undefined
851
+ } catch {
852
+ return true
853
+ }
854
+ }
855
+
755
856
  function resolveGithubCliDeniedRoots(cwd: string, config: Config): string[] {
756
857
  return [
757
858
  realpathSync(cwd),
@@ -808,6 +909,7 @@ export async function planStart({
808
909
  platform = process.platform,
809
910
  hostIdentity = currentHostIdentity(),
810
911
  gitIdentity,
912
+ totalMemoryBytes,
811
913
  }: PlanStartOptions): Promise<StartPlan> {
812
914
  const containerName = containerNameFromCwd(cwd)
813
915
  const imageTag = imageTagFromCwd(cwd)
@@ -815,6 +917,8 @@ export async function planStart({
815
917
  const devSourcePath = await detectDevSource(cwd)
816
918
  const cfg = await loadTypeclawConfig(cwd)
817
919
  const mounts = cfg.mounts
920
+ const memoryLimit = resolveMemoryLimit({ totalMemoryBytes })
921
+ const memoryLimitArg = formatMemorySize(memoryLimit.bytes)
818
922
 
819
923
  // No `--rm`: a crashed container's logs MUST survive past exit. Lifecycle
820
924
  // cleanup archives them under host-stage <agent>/.typeclaw/logs/ before
@@ -870,21 +974,28 @@ export async function planStart({
870
974
  // Operators must `typeclaw restart` (removes and recreates), not
871
975
  // `docker restart` (reuses the old HostConfig).
872
976
  //
873
- // `seccomp=unconfined` lets `bwrap(1)` (installed in baseline; see
874
- // BASELINE_APT_PACKAGES in src/init/dockerfile.ts) create user/pid/mount
875
- // namespaces from inside the container. Docker's default seccomp profile
876
- // rejects `unshare(CLONE_NEWUSER)` and `clone(CLONE_NEWUSER)` for
877
- // non-privileged containers, which is the right default for multi-tenant
878
- // hosts (Kubernetes nodes, CI runners) but wrong for typeclaw: the outer
879
- // container is a single-tenant trust boundary — the user trusts everything
880
- // inside it equally, the .env and agent folder are already mounted in —
881
- // so the multi-tenant protections seccomp adds are not load-bearing for
882
- // typeclaw's threat model. The per-tool sandbox bwrap builds for subagents
883
- // IS the real boundary against prompt-injected commands; that boundary is
884
- // what `--security-opt seccomp=unconfined` exists to enable. See
885
- // `docs/internals/sandbox.mdx` for the full rationale including why
886
- // `--cap-add=SYS_ADMIN` was rejected as an alternative (narrower in
887
- // syscalls but strictly worse in capability semantics).
977
+ // These two security options are a load-bearing pair for `bwrap(1)`
978
+ // (installed in baseline; see BASELINE_APT_PACKAGES in
979
+ // src/init/dockerfile.ts). Docker's default seccomp profile rejects the
980
+ // namespace syscalls, while moby's docker-default AppArmor profile has an
981
+ // explicit `deny mount,` rule that rejects bwrap's opening
982
+ // mount(NULL, "/", MS_SLAVE|MS_REC). Selecting `apparmor=unconfined` removes
983
+ // that mount denial; it selects a profile, it does NOT grant a capability.
984
+ // On stock Ubuntu 23.10+ the host's `unprivileged_userns` catch-all then
985
+ // denies bwrap's /proc/<pid>/uid_map write when
986
+ // kernel.apparmor_restrict_unprivileged_userns=1. The complete path there is
987
+ // the shipped host-loaded `typeclaw-bwrap` profile plus
988
+ // sandbox.apparmorProfile="typeclaw-bwrap"; doctor reports the exact install
989
+ // and restart commands.
990
+ //
991
+ // CAP_SYS_ADMIN is not an alternative: the entrypoint drops to the host's
992
+ // non-root UID with an empty capability set, so Docker's --cap-add grant is
993
+ // void in the production process. These outer defaults are appropriate
994
+ // because the container is a single-tenant trust boundary — the user trusts
995
+ // everything inside it equally, and the .env and agent folder are already
996
+ // mounted in. Seccomp/AppArmor's multi-tenant protections are therefore not
997
+ // load-bearing for this threat model; the per-tool bwrap sandbox is the real
998
+ // boundary against prompt-injected commands. See docs/internals/sandbox.mdx.
888
999
  const runArgs = [
889
1000
  'run',
890
1001
  '-d',
@@ -892,8 +1003,25 @@ export async function planStart({
892
1003
  '--name',
893
1004
  containerName,
894
1005
  '--shm-size=2g',
1006
+ // `--memory-swap` equal to `--memory` disables swap for the container, and
1007
+ // that equality is the load-bearing half. Without a cgroup limit at all,
1008
+ // growth is charged to the host VM, and the guest kernel answers memory
1009
+ // pressure by writing to swap: every vCPU ends up in direct reclaim
1010
+ // (shrink_folio_list -> swap_writeout) while the OOM killer frees nothing
1011
+ // reclaimable, and the VM livelocks instead of killing one process. With
1012
+ // the limit the charge fails at the cgroup boundary and a single agent is
1013
+ // killed. Letting the container swap would restore the original livelock
1014
+ // inside the cgroup, which is why these are set as a pair.
1015
+ //
1016
+ // A cgroup limit also makes /dev/shm pages count against the container
1017
+ // rather than the host, which matters because shm is not reclaimable by
1018
+ // killing a process — see the --shm-size note above.
1019
+ `--memory=${memoryLimitArg}`,
1020
+ `--memory-swap=${memoryLimitArg}`,
895
1021
  '--security-opt',
896
1022
  'seccomp=unconfined',
1023
+ '--security-opt',
1024
+ `apparmor=${cfg.sandbox.apparmorProfile}`,
897
1025
  '-p',
898
1026
  `${publishHost}:${hostPort}:${CONTAINER_PORT}`,
899
1027
  ]
@@ -919,17 +1047,17 @@ export async function planStart({
919
1047
  // sandbox.realProc (default FALSE) opts into the per-tool bwrap sandbox's
920
1048
  // 'real-proc' strategy (src/sandbox/build.ts), which prefixes the sandbox with
921
1049
  // `unshare --pid --fork --mount --mount-proc`. Mounting a fresh procfs for the
922
- // new PID namespace needs real CAP_SYS_ADMIN — seccomp=unconfined alone is not
923
- // enough (it only unblocks the unshare/clone SYSCALLS; the kernel still
924
- // rejects mount(2) of proc without the capability). So the grant is gated on
925
- // the flag and is OFF by default: external-package execution (`bunx agent-*`)
1050
+ // new PID namespace needs real CAP_SYS_ADMIN, so the Docker grant remains
1051
+ // gated on the flag and is OFF by default. The entrypoint's production
1052
+ // non-root UID clears that cap before the agent starts today, and the runtime
1053
+ // capability probe consequently falls back to proc-bind. External-package
1054
+ // execution (`bunx agent-*`)
926
1055
  // no longer needs it — the default 'proc-bind' strategy gives the runner real
927
1056
  // /proc without any outer capability (see docs/internals/sandbox.mdx). Setting
928
- // realProc:true adds the stricter PID-isolation posture at the cost of this
929
- // broad "new root" grant. The container-side strategy resolution still probes
930
- // whether the mount actually works (canMountRealProc) and falls back to
931
- // proc-bind on runtimes where the cap is a no-op (e.g. OrbStack), so this grant
932
- // is necessary-but-not-sufficient by design. Placed before the image tag (like
1057
+ // realProc:true requests the stricter PID-isolation posture. The
1058
+ // container-side strategy resolution probes whether the mount actually works
1059
+ // (canMountRealProc) and falls back to proc-bind when the cap is absent or the
1060
+ // runtime rejects the mount (e.g. OrbStack). Placed before the image tag (like
933
1061
  // --cap-add=NET_ADMIN) so docker applies it at run time.
934
1062
  if (cfg.sandbox.realProc) {
935
1063
  runArgs.push('--cap-add=SYS_ADMIN')
@@ -1038,9 +1166,36 @@ export async function planStart({
1038
1166
  needsBuild: forceBuild || !imageExists,
1039
1167
  hostPort,
1040
1168
  tuiToken,
1169
+ memoryLimitBytes: memoryLimit.bytes,
1041
1170
  }
1042
1171
  }
1043
1172
 
1173
+ // Surfaces the arithmetic when every agent's cap together exceeds what Docker
1174
+ // actually has. Never blocks: a fleet that has run fine at a nominal
1175
+ // oversubscription must not be bricked by an upgrade, and a refused start is a
1176
+ // worse failure than a crowded host.
1177
+ async function warnOnMemoryOversubscription(options: {
1178
+ exec: DockerExec
1179
+ containerName: string
1180
+ memoryLimitBytes: number
1181
+ totalMemoryBytes: number | undefined
1182
+ onWarning: ((warning: string) => void) | undefined
1183
+ streamOutput: boolean
1184
+ }): Promise<void> {
1185
+ const { exec, containerName, memoryLimitBytes, totalMemoryBytes, onWarning, streamOutput } = options
1186
+ const running = await readRunningAgentMemoryClaims(exec)
1187
+ const warning = decideMemoryOversubscription({
1188
+ running,
1189
+ incoming: { containerName, bytes: memoryLimitBytes },
1190
+ totalMemoryBytes,
1191
+ })
1192
+ if (warning === null) return
1193
+
1194
+ const text = formatOversubscriptionWarning(warning).join('\n')
1195
+ if (onWarning !== undefined) onWarning(text)
1196
+ else if (streamOutput) process.stderr.write(`${text}\n`)
1197
+ }
1198
+
1044
1199
  async function resolvePublishHost(exec: DockerExec): Promise<string> {
1045
1200
  const result = await exec(['version', '--format', '{{.Server.Platform.Name}}'])
1046
1201
  if (result.exitCode === 0 && result.stdout.toLowerCase().includes('docker desktop')) return '0.0.0.0'
@@ -1081,13 +1236,10 @@ export async function refreshDockerfile(
1081
1236
  return { changed: true, warnings }
1082
1237
  }
1083
1238
 
1084
- // Builds the agent image with a seamless buildx->legacy fallback. The preferred
1085
- // frontend is chosen from `hasBuildx`; if a buildx build FAILS (e.g. the plugin
1086
- // is installed but there is no usable builder/driver), we transparently rewrite
1087
- // the Dockerfile to its BuildKit-stripped form and retry once with the legacy
1088
- // `docker build`. The user sees one successful `typeclaw start` instead of a
1089
- // buildx-specific dead end. A genuine Dockerfile error fails both paths, so the
1090
- // retry costs at most one extra attempt before the real error surfaces.
1239
+ // Builds the agent image with a managed-buildx -> current-buildx -> legacy
1240
+ // fallback. A managed builder failure first releases all isolated state and
1241
+ // retries the unchanged BuildKit Dockerfile on Docker's current builder. Only
1242
+ // when that also fails do we strip BuildKit syntax and try `docker build`.
1091
1243
  //
1092
1244
  // Layered on top is a credential-helper recovery: typeclaw only pulls PUBLIC
1093
1245
  // images (the BuildKit syntax frontend + the typeclaw-base FROM), but a broken
@@ -1101,56 +1253,105 @@ export async function refreshDockerfile(
1101
1253
  async function runImageBuild(args: {
1102
1254
  exec: DockerExec
1103
1255
  cwd: string
1256
+ cacheScope: string
1104
1257
  imageTag: string
1105
1258
  buildContext: string
1106
1259
  hasBuildx: boolean
1260
+ acquireBuildCache: typeof acquireManagedBuildCache | null
1261
+ buildCacheStateDir?: string
1107
1262
  streamOutput: boolean
1263
+ onWarning: (warning: string) => void
1108
1264
  }): Promise<{ ok: true } | { ok: false; exitCode: number; credentialHelperRetried: boolean }> {
1109
- const { exec, cwd, imageTag, buildContext, hasBuildx, streamOutput } = args
1265
+ const {
1266
+ exec,
1267
+ cwd,
1268
+ cacheScope,
1269
+ imageTag,
1270
+ buildContext,
1271
+ hasBuildx,
1272
+ acquireBuildCache,
1273
+ buildCacheStateDir,
1274
+ streamOutput,
1275
+ onWarning,
1276
+ } = args
1277
+ let lease: ManagedBuildCacheLease | undefined
1110
1278
  const buildArgv = (frontend: 'buildx' | 'legacy'): string[] =>
1111
1279
  frontend === 'buildx'
1112
- ? ['buildx', 'build', '--load', '-t', imageTag, buildContext]
1280
+ ? [
1281
+ 'buildx',
1282
+ 'build',
1283
+ ...(lease !== undefined ? ['--builder', lease.builder.builderName, ...lease.cacheArgs] : []),
1284
+ '--load',
1285
+ '-t',
1286
+ imageTag,
1287
+ buildContext,
1288
+ ]
1113
1289
  : ['build', '-t', imageTag, buildContext]
1114
1290
 
1115
1291
  let sanitizedConfig: SanitizedDockerConfig | null = null
1116
- const attempt = async (frontend: 'buildx' | 'legacy'): Promise<DockerExecResult> =>
1292
+ const attempt = async (
1293
+ frontend: 'buildx' | 'legacy',
1294
+ config: SanitizedDockerConfig | null,
1295
+ ): Promise<DockerExecResult> =>
1117
1296
  exec(buildArgv(frontend), {
1118
1297
  cwd,
1119
1298
  ...(streamOutput ? { inheritStdio: true, captureStderr: true } : {}),
1120
1299
  ...(streamOutput ? {} : { captureStdout: false, maxCapturedStderrBytes: 32 * 1024 }),
1121
- env: sanitizedConfig?.env,
1300
+ env: { ...(frontend === 'buildx' ? lease?.builder.env : {}), ...config?.env },
1122
1301
  })
1302
+ const attemptWithCredentialRecovery = async (
1303
+ frontend: 'buildx' | 'legacy',
1304
+ config: SanitizedDockerConfig | null,
1305
+ ): Promise<{ result: DockerExecResult; config: SanitizedDockerConfig | null }> => {
1306
+ let result = await attempt(frontend, config)
1307
+ if (result.exitCode !== 0 && config === null && isMissingDockerCredentialHelper(result.stderr)) {
1308
+ config = await createSanitizedDockerConfig()
1309
+ if (config !== null) result = await attempt(frontend, config)
1310
+ }
1311
+ return { result, config }
1312
+ }
1123
1313
 
1124
1314
  try {
1125
1315
  let frontend: 'buildx' | 'legacy' = hasBuildx ? 'buildx' : 'legacy'
1126
- let result = await attempt(frontend)
1127
- if (result.exitCode === 0) return { ok: true }
1128
-
1129
- // Same-frontend retry: a broken credential helper aborts the pull before
1130
- // the builder ever matters, so strip it and retry the identical build.
1131
- if (sanitizedConfig === null && isMissingDockerCredentialHelper(result.stderr)) {
1132
- sanitizedConfig = await createSanitizedDockerConfig()
1133
- if (sanitizedConfig) {
1134
- result = await attempt(frontend)
1135
- if (result.exitCode === 0) return { ok: true }
1316
+ let result: DockerExecResult
1317
+ if (frontend === 'buildx' && acquireBuildCache !== null) {
1318
+ const acquired = await acquireBuildCache({
1319
+ exec,
1320
+ cacheScope,
1321
+ ...(buildCacheStateDir !== undefined ? { stateDir: buildCacheStateDir } : {}),
1322
+ })
1323
+ if (acquired.ok) {
1324
+ lease = acquired.lease
1325
+ for (const warning of acquired.warnings) onWarning(warning)
1326
+ } else onWarning(`managed build cache unavailable; using Docker's current builder: ${acquired.reason}`)
1327
+ }
1328
+ if (frontend === 'buildx' && lease !== undefined) {
1329
+ const managedLease = lease
1330
+ let managedSuccess = false
1331
+ try {
1332
+ ;({ result, config: sanitizedConfig } = await attemptWithCredentialRecovery(frontend, sanitizedConfig))
1333
+ managedSuccess = result.exitCode === 0
1334
+ } finally {
1335
+ const finished = await managedLease.finish(managedSuccess)
1336
+ for (const warning of finished.warnings) onWarning(warning)
1337
+ lease = undefined
1338
+ }
1339
+ if (result.exitCode !== 0) {
1340
+ onWarning("managed buildx build failed; retrying with Docker's current builder")
1341
+ ;({ result, config: sanitizedConfig } = await attemptWithCredentialRecovery(frontend, sanitizedConfig))
1136
1342
  }
1343
+ } else {
1344
+ ;({ result, config: sanitizedConfig } = await attemptWithCredentialRecovery(frontend, sanitizedConfig))
1137
1345
  }
1346
+ if (result.exitCode === 0) return { ok: true }
1138
1347
 
1139
1348
  if (frontend === 'buildx') {
1140
- // buildx failed for a non-cred reason — fall back to the legacy builder
1141
- // against a stripped Dockerfile so a misconfigured-buildx host still ends
1142
- // up with an image. The sanitized config (if any) carries into the retry.
1349
+ // Both managed and current buildx failed. Strip BuildKit-only syntax only
1350
+ // now, preserving the current builder as the first compatibility fallback.
1143
1351
  await refreshDockerfile(cwd, { buildKit: false })
1144
1352
  frontend = 'legacy'
1145
- result = await attempt(frontend)
1353
+ ;({ result, config: sanitizedConfig } = await attemptWithCredentialRecovery(frontend, sanitizedConfig))
1146
1354
  if (result.exitCode === 0) return { ok: true }
1147
- if (sanitizedConfig === null && isMissingDockerCredentialHelper(result.stderr)) {
1148
- sanitizedConfig = await createSanitizedDockerConfig()
1149
- if (sanitizedConfig) {
1150
- result = await attempt(frontend)
1151
- if (result.exitCode === 0) return { ok: true }
1152
- }
1153
- }
1154
1355
  }
1155
1356
 
1156
1357
  if (sanitizedConfig !== null && streamOutput) {
@@ -1214,9 +1415,45 @@ export async function refreshGitignore(cwd: string): Promise<void> {
1214
1415
  // the migration write with a commit on every read path, not only here.
1215
1416
  export const commitSystemFile = commitSystemFileShared
1216
1417
 
1217
- async function imageExists(exec: DockerExec, tag: string): Promise<boolean> {
1218
- const result = await exec(['image', 'inspect', tag])
1219
- return result.exitCode === 0
1418
+ async function inspectImageId(exec: DockerExec, tag: string): Promise<string | null> {
1419
+ const result = await exec(['image', 'inspect', '--format', '{{.Id}}', tag])
1420
+ if (result.exitCode !== 0) return null
1421
+ return result.stdout.trim() || null
1422
+ }
1423
+
1424
+ async function protectImageForRebuild(
1425
+ exec: DockerExec,
1426
+ imageTag: string,
1427
+ previousImageId: string | null,
1428
+ ): Promise<{ tag: string | null; warning: string | null }> {
1429
+ if (previousImageId === null) return { tag: null, warning: null }
1430
+
1431
+ const protectionTag = `${imageTag}:rebuild-${randomBytes(8).toString('hex')}`
1432
+ try {
1433
+ const result = await exec(['image', 'tag', previousImageId, protectionTag])
1434
+ if (result.exitCode === 0) return { tag: protectionTag, warning: null }
1435
+ const detail = sanitizeDockerStderr(result.stderr) || `docker image tag exited with code ${result.exitCode}`
1436
+ return {
1437
+ tag: null,
1438
+ warning: `Could not protect existing Docker image ${previousImageId} for cleanup: ${detail}`,
1439
+ }
1440
+ } catch (error) {
1441
+ return {
1442
+ tag: null,
1443
+ warning: `Could not protect existing Docker image ${previousImageId} for cleanup: ${error instanceof Error ? error.message : String(error)}`,
1444
+ }
1445
+ }
1446
+ }
1447
+
1448
+ async function releaseImageProtection(exec: DockerExec, protectionTag: string): Promise<string | null> {
1449
+ try {
1450
+ const result = await exec(['image', 'rm', '--no-prune', protectionTag])
1451
+ if (result.exitCode === 0) return null
1452
+ const detail = sanitizeDockerStderr(result.stderr) || `docker image rm exited with code ${result.exitCode}`
1453
+ return `Could not remove temporary Docker image protection tag ${protectionTag}: ${detail}`
1454
+ } catch (error) {
1455
+ return `Could not remove temporary Docker image protection tag ${protectionTag}: ${error instanceof Error ? error.message : String(error)}`
1456
+ }
1220
1457
  }
1221
1458
 
1222
1459
  type InspectedState =
@@ -1252,8 +1489,7 @@ async function inspectContainer(exec: DockerExec, name: string): Promise<Inspect
1252
1489
  // container record behind, and start()'s own port-TOCTOU retry triggers
1253
1490
  // this path against that corpse).
1254
1491
  //
1255
- // cleanupRunCorpse refuses to touch a running container and uses non-force rm,
1256
- // so a container that starts after its inspect probe is also preserved. A concurrent
1492
+ // cleanupRunCorpse refuses to touch a running container and uses non-force rm. A concurrent
1257
1493
  // legitimate start of the same name (or a foreign-but-named container the
1258
1494
  // user wants alive) is surfaced as a hard failure rather than silently
1259
1495
  // killed. 'stuck' likewise surfaces — a wedged daemon that won't drain a