typeclaw 0.45.1 → 0.46.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 (163) hide show
  1. package/README.md +1 -1
  2. package/package.json +3 -2
  3. package/src/agent/git-nudge.ts +2 -1
  4. package/src/agent/index.ts +44 -30
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/multimodal/index.ts +1 -1
  7. package/src/agent/multimodal/look-at.ts +78 -44
  8. package/src/agent/multimodal/looker.ts +161 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +207 -0
  11. package/src/agent/plugin-tools.ts +377 -157
  12. package/src/agent/provider-error.ts +52 -1
  13. package/src/agent/restart/index.ts +61 -40
  14. package/src/agent/restart-handoff/index.ts +73 -4
  15. package/src/agent/reviewer-bash-policy.ts +42 -1
  16. package/src/agent/session-origin.ts +2 -0
  17. package/src/agent/subagent-drain.ts +117 -7
  18. package/src/agent/subagents.ts +49 -16
  19. package/src/agent/throttle-circuit.ts +25 -5
  20. package/src/agent/tool-error-remediation.ts +72 -0
  21. package/src/agent/tool-file-safety.ts +1310 -0
  22. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  23. package/src/agent/tools/ddg.ts +16 -2
  24. package/src/agent/tools/post-github-review.ts +199 -0
  25. package/src/agent/tools/spawn-subagent.ts +21 -18
  26. package/src/agent/tools/webfetch/fetch.ts +163 -183
  27. package/src/agent/tools/webfetch/tool.ts +2 -3
  28. package/src/agent/tools/websearch.ts +23 -2
  29. package/src/agent/tools-without-local-file-operands.ts +30 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/README.md +23 -10
  32. package/src/bundled-plugins/backup/git-auth.ts +6 -4
  33. package/src/bundled-plugins/backup/index.ts +85 -44
  34. package/src/bundled-plugins/backup/runner.ts +85 -1
  35. package/src/bundled-plugins/doc-render/render.ts +93 -12
  36. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  37. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  38. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  39. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +74 -26
  40. package/src/bundled-plugins/github-cli-auth/git-command.ts +224 -36
  41. package/src/bundled-plugins/github-cli-auth/graphql-auth-nudge.ts +9 -9
  42. package/src/bundled-plugins/github-cli-auth/index.ts +207 -132
  43. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  44. package/src/bundled-plugins/github-cli-auth/token-class.ts +4 -6
  45. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  46. package/src/bundled-plugins/memory/README.md +32 -11
  47. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  48. package/src/bundled-plugins/memory/citations.ts +22 -9
  49. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  50. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  51. package/src/bundled-plugins/memory/index.ts +0 -4
  52. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  53. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  54. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  55. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  56. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  57. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  58. package/src/bundled-plugins/memory/vector/embed-threads.ts +36 -0
  59. package/src/bundled-plugins/memory/vector/embedder.ts +19 -1
  60. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  61. package/src/bundled-plugins/researcher/write-report.ts +8 -5
  62. package/src/bundled-plugins/reviewer/index.ts +2 -2
  63. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  64. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  65. package/src/bundled-plugins/scout/scout.ts +8 -0
  66. package/src/bundled-plugins/security/index.ts +4 -4
  67. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  68. package/src/bundled-plugins/security/policies/private-surface-read.ts +787 -36
  69. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  70. package/src/bundled-plugins/security/policies/ssrf.ts +147 -42
  71. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  72. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  73. package/src/channels/adapters/discord-bot.ts +66 -6
  74. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  75. package/src/channels/adapters/discord-id.ts +4 -0
  76. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  77. package/src/channels/adapters/discord.ts +57 -7
  78. package/src/channels/adapters/github/auth-app.ts +41 -12
  79. package/src/channels/adapters/github/inbound.ts +11 -0
  80. package/src/channels/adapters/github/index.ts +71 -65
  81. package/src/channels/adapters/github/reconcile-cooldown-store.ts +178 -0
  82. package/src/channels/adapters/github/reconcile-open-prs.ts +31 -0
  83. package/src/channels/adapters/github/review-submitter.ts +302 -0
  84. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  85. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  86. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  87. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  88. package/src/channels/adapters/slack-bot-edit.ts +85 -20
  89. package/src/channels/adapters/slack-bot.ts +26 -10
  90. package/src/channels/adapters/slack-classify.ts +21 -2
  91. package/src/channels/adapters/slack-format.ts +245 -0
  92. package/src/channels/adapters/slack.ts +59 -7
  93. package/src/channels/adapters/telegram-bot.ts +18 -5
  94. package/src/channels/adapters/webex-bot.ts +8 -3
  95. package/src/channels/adapters/webex.ts +8 -3
  96. package/src/channels/fetch-attachment.ts +43 -0
  97. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  98. package/src/channels/github-token-bridge.ts +12 -6
  99. package/src/channels/manager.ts +9 -0
  100. package/src/channels/router.ts +248 -6
  101. package/src/channels/types.ts +28 -1
  102. package/src/cli/channel.ts +1 -1
  103. package/src/cli/init.ts +1 -1
  104. package/src/cli/model.ts +57 -7
  105. package/src/compose/stop.ts +17 -5
  106. package/src/config/config.ts +6 -6
  107. package/src/config/models-mutation.ts +13 -1
  108. package/src/config/providers.ts +176 -0
  109. package/src/container/docker-app.ts +42 -13
  110. package/src/container/start.ts +62 -10
  111. package/src/cron/bridge.ts +9 -2
  112. package/src/doctor/checks.ts +8 -3
  113. package/src/doctor/commit.ts +2 -1
  114. package/src/doctor/file-ownership.ts +52 -0
  115. package/src/dreams/git.ts +2 -1
  116. package/src/git/bound-gc-config.ts +82 -0
  117. package/src/git/hookless.ts +5 -0
  118. package/src/git/reconcile-ignored.ts +18 -5
  119. package/src/git/system-commit.ts +12 -6
  120. package/src/hostd/spawn.ts +133 -47
  121. package/src/init/dockerfile.ts +99 -5
  122. package/src/init/index.ts +17 -5
  123. package/src/init/models-dev.ts +4 -0
  124. package/src/init/validate-api-key.ts +2 -0
  125. package/src/inspect/replay.ts +21 -9
  126. package/src/inspect/session-list.ts +71 -33
  127. package/src/mcp/tools.ts +17 -3
  128. package/src/network/internal-destinations.ts +267 -0
  129. package/src/permissions/builtins.ts +3 -1
  130. package/src/plugin/context.ts +2 -0
  131. package/src/plugin/index.ts +1 -0
  132. package/src/plugin/manager.ts +4 -0
  133. package/src/plugin/types.ts +22 -0
  134. package/src/run/index.ts +40 -0
  135. package/src/run/llm-fetch-observer.ts +41 -4
  136. package/src/sandbox/build.ts +37 -15
  137. package/src/sandbox/canonical-secrets.ts +18 -0
  138. package/src/sandbox/env-exposure.ts +83 -0
  139. package/src/sandbox/errors.ts +13 -6
  140. package/src/sandbox/hidden-paths.ts +102 -44
  141. package/src/sandbox/index.ts +22 -4
  142. package/src/sandbox/package-install.ts +3 -27
  143. package/src/sandbox/policy.ts +16 -28
  144. package/src/sandbox/privileged-runtime.ts +256 -0
  145. package/src/sandbox/session-tmp.ts +8 -2
  146. package/src/sandbox/writable-zones.ts +204 -140
  147. package/src/secrets/index.ts +8 -0
  148. package/src/secrets/refresh-provider-oauth.ts +128 -0
  149. package/src/server/command-runner.ts +48 -4
  150. package/src/server/index.ts +4 -0
  151. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  152. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  153. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  154. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  155. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  156. package/src/skills/typeclaw-config/SKILL.md +27 -11
  157. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  158. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  159. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  160. package/src/skills/typeclaw-permissions/SKILL.md +36 -19
  161. package/src/skills/typeclaw-plugins/SKILL.md +37 -0
  162. package/src/usage/scan.ts +11 -2
  163. package/typeclaw.schema.json +25 -0
@@ -1,10 +1,11 @@
1
1
  import { randomBytes } from 'node:crypto'
2
- import { existsSync } from 'node:fs'
2
+ import { accessSync, constants as fsConstants, existsSync } from 'node:fs'
3
3
  import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
4
4
  import { tmpdir } from 'node:os'
5
5
  import { isAbsolute, join, relative, resolve } from 'node:path'
6
6
 
7
7
  import { expandMountPath, loadConfigSync, withDefaultPlugins, type Config, type PortForward } from '@/config'
8
+ import { applyBoundGcConfig } from '@/git/bound-gc-config'
8
9
  import { commitGitignoreWithUntracks, untrackTrulyIgnoredFiles } from '@/git/reconcile-ignored'
9
10
  import { commitSystemFile as commitSystemFileShared } from '@/git/system-commit'
10
11
  import { send as sendToDaemon } from '@/hostd/client'
@@ -85,6 +86,9 @@ export type PlanStartOptions = {
85
86
  // Defaults to `process.platform`; tests inject it to exercise the native-
86
87
  // Windows dev-source mount branch without running on a Windows host.
87
88
  platform?: NodeJS.Platform
89
+ // POSIX identity whose ownership bind-mounted runtime writes must retain.
90
+ // Omitted when unavailable (native Windows and unusual JS hosts).
91
+ hostIdentity?: { uid: number; gid: number } | null
88
92
  }
89
93
 
90
94
  export type HostDaemonControl = {
@@ -168,6 +172,9 @@ export type StartOptions = {
168
172
  // Defaults to `process.platform`; tests inject it to exercise the
169
173
  // native-Windows dev-link reconcile path off a non-Windows runner.
170
174
  platform?: NodeJS.Platform
175
+ hostIdentity?: { uid: number; gid: number } | null
176
+ // Test seam for the host-stage writable-config preflight.
177
+ assertConfigWritable?: (cwd: string) => void
171
178
  }
172
179
 
173
180
  export type HostDaemonStatus =
@@ -219,6 +226,8 @@ export async function start({
219
226
  verifyRunning = createVerifyRunning({ exec }),
220
227
  runBunLink,
221
228
  platform = process.platform,
229
+ hostIdentity = currentHostIdentity(),
230
+ assertConfigWritable = assertAgentConfigWritable,
222
231
  }: StartOptions): Promise<StartResult> {
223
232
  try {
224
233
  const containerName = containerNameFromCwd(cwd)
@@ -230,10 +239,21 @@ export async function start({
230
239
  // that would surprise a user invoking `compose start` against a partially-up
231
240
  // tree.
232
241
  const state = await inspectContainer(exec, containerName)
242
+
243
+ // Bound gc/repack memory even when start() is an already-running no-op below:
244
+ // the running agent's backup keeps committing, so it must not keep using the
245
+ // unbounded Git defaults until a full stop/restart. This is a machine-local
246
+ // `git config` write (never committed, no template/side effect), so unlike the
247
+ // Dockerfile/.gitignore/package.json refreshes it is safe before the running
248
+ // return — no surprise for `compose start` against a partially-up tree.
249
+ await applyBoundGcConfig(cwd)
250
+
233
251
  if (state.exists && state.running) {
234
252
  return await reportAlreadyRunning(exec, cwd, containerName)
235
253
  }
236
254
 
255
+ assertConfigWritable(cwd)
256
+
237
257
  // TypeClaw owns Dockerfile, .gitignore, and the bun-workspaces shape of
238
258
  // package.json. Refresh them from the current CLI templates on every fresh
239
259
  // start (not just --build) so version drift between the agent folder and
@@ -252,6 +272,9 @@ export async function start({
252
272
  // refreshGitignore call below reads typeclaw.json and will incidentally
253
273
  // trigger the migration commit if the file was legacy.
254
274
  await refreshGitignore(cwd)
275
+ // Machine-local `git config` that bounds gc/repack memory on the agent repo.
276
+ // Runs alongside the other managed-file refreshes; not committed (local scope).
277
+ await applyBoundGcConfig(cwd)
255
278
  const pkgRefresh = await refreshPackageJson(cwd)
256
279
  const { untracked } = await untrackTrulyIgnoredFiles(cwd, (await loadTypeclawConfig(cwd)).git.ignore.append)
257
280
  if (untracked.length > 0) {
@@ -463,6 +486,7 @@ export async function start({
463
486
  publishHost,
464
487
  tuiToken,
465
488
  platform,
489
+ hostIdentity,
466
490
  })
467
491
 
468
492
  let built = false
@@ -598,6 +622,25 @@ function installedReachesTarget(installed: string, target: string): boolean {
598
622
  return true
599
623
  }
600
624
 
625
+ function currentHostIdentity(): { uid: number; gid: number } | null {
626
+ if (typeof process.getuid !== 'function' || typeof process.getgid !== 'function') return null
627
+ return { uid: process.getuid(), gid: process.getgid() }
628
+ }
629
+
630
+ function assertAgentConfigWritable(cwd: string): void {
631
+ const configPath = join(cwd, 'typeclaw.json')
632
+ if (!existsSync(configPath)) return
633
+ try {
634
+ accessSync(configPath, fsConstants.R_OK | fsConstants.W_OK)
635
+ } catch (error) {
636
+ const detail = error instanceof Error ? error.message : String(error)
637
+ throw new Error(
638
+ `typeclaw.json is not writable by the current host user: ${configPath}. ` +
639
+ `Inspect ownership with \`ls -ln "${configPath}"\` and run \`typeclaw doctor\` for repair guidance. ${detail}`,
640
+ )
641
+ }
642
+ }
643
+
601
644
  export async function planStart({
602
645
  cwd,
603
646
  hostPort,
@@ -607,6 +650,7 @@ export async function planStart({
607
650
  publishHost = '127.0.0.1',
608
651
  tuiToken = null,
609
652
  platform = process.platform,
653
+ hostIdentity = currentHostIdentity(),
610
654
  }: PlanStartOptions): Promise<StartPlan> {
611
655
  const containerName = containerNameFromCwd(cwd)
612
656
  const imageTag = imageTagFromCwd(cwd)
@@ -694,9 +738,9 @@ export async function planStart({
694
738
  }
695
739
 
696
740
  // sandbox.symlinks: the entrypoint shim creates `from -> /agent/<to>` at the
697
- // real container HOME for the UNSANDBOXED (trusted/owner) bash path. The
698
- // low-trust path is handled separately by the per-tool bwrap --symlink op
699
- // (src/sandbox/build.ts). Passed as base64-encoded JSON because `from`/`to`
741
+ // real container HOME for runtime-owned processes. Model-driven bash creates
742
+ // its corresponding link at the bwrap HOME via src/sandbox/build.ts. Passed
743
+ // as base64-encoded JSON because `from`/`to`
700
744
  // are arbitrary operator strings — base64 sidesteps every shell-metachar and
701
745
  // env-quoting hazard; the shim decodes + JSON-parses it with bun. Omitted when
702
746
  // empty so the common case adds no env clutter and the shim's loop never runs.
@@ -729,6 +773,14 @@ export async function planStart({
729
773
  runArgs.push('-e', `TZ=${hostTz}`)
730
774
  }
731
775
 
776
+ // Run the container entrypoint as root for iptables/bootstrap work, then
777
+ // re-exec the TypeClaw runtime under the invoking POSIX host identity. Docker
778
+ // Desktop/OrbStack propagate numeric ownership through the /agent bind mount,
779
+ // so this prevents container-created files from becoming root-owned on host.
780
+ if (platform !== 'win32' && hostIdentity !== null) {
781
+ runArgs.push('-e', `TYPECLAW_HOST_UID=${hostIdentity.uid}`, '-e', `TYPECLAW_HOST_GID=${hostIdentity.gid}`)
782
+ }
783
+
732
784
  // The agent's `restart` tool needs to identify itself to hostd. Inside the
733
785
  // container, cwd is `/agent` and basename(cwd) loses the host folder name,
734
786
  // so we cannot derive containerName from cwd at runtime. Inject it as an
@@ -969,13 +1021,13 @@ async function inspectContainer(exec: DockerExec, name: string): Promise<Inspect
969
1021
  // removal needs the user to act (`docker rm -f <name>` manually, or restart
970
1022
  // Docker) instead of looping forever.
971
1023
  //
972
- // A small bounded backoff (100/200/400ms) follows each cleanup before the
1024
+ // A bounded backoff (100/200/400/800/1200ms) follows each cleanup before the
973
1025
  // next `docker run`. waitForRemoval polls `docker inspect`, which can
974
1026
  // report the container gone BEFORE Docker's internal name-reservation
975
- // table has fully released the name. Without the backoff, the three
976
- // retries can all fire inside the same daemon drain window and exhaust
977
- // uselessly. The cumulative ~700ms is small next to the docker run RTT
978
- // itself and dwarfed by the user-visible cost of a failed start.
1027
+ // table has fully released the name. Without the backoff, the retries can
1028
+ // all fire inside the same daemon drain window and exhaust uselessly. The
1029
+ // cumulative ~2.7s is small next to the docker run RTT itself and dwarfed by
1030
+ // the user-visible cost of a failed start.
979
1031
  //
980
1032
  // Only the name-conflict path engages this destructive retry. Any other
981
1033
  // non-zero exit (port-allocated, image-not-found, permission-denied) is
@@ -999,7 +1051,7 @@ async function execRunWithConflictRetry(
999
1051
  return last
1000
1052
  }
1001
1053
 
1002
- const CONFLICT_RETRY_BACKOFFS_MS = [100, 200, 400] as const
1054
+ const CONFLICT_RETRY_BACKOFFS_MS = [100, 200, 400, 800, 1200] as const
1003
1055
 
1004
1056
  // Idempotent path for `start()`: the named container is already up. Reflect
1005
1057
  // the live container's identity (id) and host port in the result so callers
@@ -5,6 +5,12 @@ export type CronListBridgeOptions = {
5
5
  cwd: string
6
6
  url?: string
7
7
  timeoutMs?: number
8
+ // Budget for the WS handshake only. Defaults to timeoutMs so production
9
+ // behavior is unchanged. Split out so the reply-timeout path can be tested
10
+ // with a tight reply budget while giving the connect phase enough slack to
11
+ // survive CPU contention under parallel tests — a slow handshake must not
12
+ // masquerade as a reply timeout (or, worse, surface as `unreachable`).
13
+ connectTimeoutMs?: number
8
14
  // Injected for tests so the in-container short-circuit can be exercised
9
15
  // without polluting process.env. Production callers omit this and the
10
16
  // bridge reads from process.env directly.
@@ -35,6 +41,7 @@ type DialResult = { kind: 'ok'; ws: WebSocket; timeoutMs: number } | { kind: 'un
35
41
 
36
42
  async function dial(opts: CronListBridgeOptions): Promise<DialResult> {
37
43
  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
44
+ const connectTimeoutMs = opts.connectTimeoutMs ?? timeoutMs
38
45
  let url = opts.url
39
46
  if (url === undefined) {
40
47
  try {
@@ -74,8 +81,8 @@ async function dial(opts: CronListBridgeOptions): Promise<DialResult> {
74
81
  try {
75
82
  ws.close()
76
83
  } catch {}
77
- reject(new Error(`timed out connecting to ${displayUrl} after ${timeoutMs}ms`))
78
- }, timeoutMs)
84
+ reject(new Error(`timed out connecting to ${displayUrl} after ${connectTimeoutMs}ms`))
85
+ }, connectTimeoutMs)
79
86
  ws.addEventListener('open', onOpen, { once: true })
80
87
  ws.addEventListener('error', onError, { once: true })
81
88
  ws.addEventListener('close', onClose, { once: true })
@@ -23,9 +23,10 @@ import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
23
23
  import { detectWsl, isWindows, isWindowsDriveMount, type WslInfo } from '@/shared'
24
24
 
25
25
  import { buildChannelChecks } from './channel-checks'
26
+ import { agentFileOwnership, type FileOwnershipDeps } from './file-ownership'
26
27
  import type { DoctorCheck } from './types'
27
28
 
28
- export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): DoctorCheck[] {
29
+ export function buildStaticChecks(opts: { dockerExec?: DockerExec } & FileOwnershipDeps = {}): DoctorCheck[] {
29
30
  const dockerExec = opts.dockerExec ?? defaultDockerExec
30
31
 
31
32
  return [
@@ -36,6 +37,7 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
36
37
  agentFolderGitignoreTemplate(),
37
38
  agentFolderNodeModules(),
38
39
  agentFolderGitRepo(),
40
+ agentFileOwnership(opts),
39
41
  configValid(),
40
42
  hostdHomeWritable(),
41
43
  wslDriveMount(),
@@ -59,12 +61,15 @@ function dockerDaemon(exec: DockerExec): DoctorCheck {
59
61
  if (result.ok) return { status: 'ok', message: 'docker info responded' }
60
62
  return {
61
63
  status: 'error',
62
- message: result.reason === 'binary-missing' ? 'docker binary missing on $PATH' : 'docker daemon down',
64
+ message: result.reason === 'binary-missing' ? 'docker binary missing on $PATH' : 'docker daemon not reachable',
63
65
  details: [result.detail],
64
66
  fix:
65
67
  result.reason === 'binary-missing'
66
68
  ? { description: 'Install Docker (Docker Desktop, OrbStack, or docker-ce).' }
67
- : { description: 'Start the Docker daemon (Docker Desktop, OrbStack, or `systemctl start docker`).' },
69
+ : {
70
+ description:
71
+ '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`.',
72
+ },
68
73
  }
69
74
  },
70
75
  }
@@ -1,3 +1,4 @@
1
+ import { hooklessGitArgs } from '@/git/hookless'
1
2
  import { resolveAgentGit } from '@/git/resolve-agent-git'
2
3
 
3
4
  import type { CommitOutcome, FixAttempt } from './types'
@@ -97,7 +98,7 @@ const defaultSpawnGit: SpawnGit = async (args, cwd) => {
97
98
  const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
98
99
  if (!bun) return { exitCode: -1, stdout: '', stderr: 'bun runtime not available' }
99
100
  try {
100
- const proc = bun.spawn({ cmd: ['git', ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
101
+ const proc = bun.spawn({ cmd: ['git', ...hooklessGitArgs(args)], cwd, stdout: 'pipe', stderr: 'pipe' })
101
102
  const exitCode = await proc.exited
102
103
  const stdout = await new Response(proc.stdout).text()
103
104
  const stderr = await new Response(proc.stderr).text()
@@ -0,0 +1,52 @@
1
+ import { existsSync, lstatSync, readdirSync } from 'node:fs'
2
+ import { join, relative } from 'node:path'
3
+
4
+ import type { DoctorCheck } from './types'
5
+
6
+ const MANAGED_PATHS = ['typeclaw.json', 'sessions', 'memory', '.typeclaw'] as const
7
+
8
+ export type FileOwnershipDeps = {
9
+ readonly platform?: NodeJS.Platform
10
+ readonly currentUid?: () => number
11
+ }
12
+
13
+ export function agentFileOwnership(deps: FileOwnershipDeps = {}): DoctorCheck {
14
+ const platform = deps.platform ?? process.platform
15
+ const currentUid = deps.currentUid ?? process.getuid
16
+
17
+ return {
18
+ name: 'agent-folder.file-ownership',
19
+ category: 'agent-folder',
20
+ description: 'agent-managed files are owned by the current host user',
21
+ applies: (ctx) => ctx.hasAgentFolder,
22
+ async run(ctx) {
23
+ if (platform === 'win32' || currentUid === undefined) {
24
+ return { status: 'ok', message: 'POSIX ownership does not apply on this host' }
25
+ }
26
+
27
+ const uid = currentUid()
28
+ const foreignPaths: string[] = []
29
+ for (const managedPath of MANAGED_PATHS) {
30
+ collectForeignPaths(join(ctx.cwd, managedPath), ctx.cwd, uid, foreignPaths)
31
+ }
32
+ if (foreignPaths.length === 0) return { status: 'ok', message: 'agent-managed files match the host user' }
33
+
34
+ return {
35
+ status: 'error',
36
+ message: `agent-managed files have a different owner: ${foreignPaths.join(', ')}`,
37
+ details: [
38
+ 'This usually means an older TypeClaw container wrote bind-mounted files as root.',
39
+ `Repair ownership from the agent folder: sudo chown -R "$(id -u):$(id -g)" ${MANAGED_PATHS.join(' ')}`,
40
+ ],
41
+ }
42
+ },
43
+ }
44
+ }
45
+
46
+ function collectForeignPaths(path: string, cwd: string, uid: number, foreignPaths: string[]): void {
47
+ if (!existsSync(path)) return
48
+ const stat = lstatSync(path)
49
+ if (stat.uid !== uid) foreignPaths.push(relative(cwd, path))
50
+ if (!stat.isDirectory()) return
51
+ for (const entry of readdirSync(path)) collectForeignPaths(join(path, entry), cwd, uid, foreignPaths)
52
+ }
package/src/dreams/git.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { hooklessGitArgs } from '@/git/hookless'
1
2
  import { resolveAgentGit } from '@/git/resolve-agent-git'
2
3
 
3
4
  export type GitResult = { exitCode: number; stdout: string; stderr: string }
@@ -87,7 +88,7 @@ const defaultSpawnGit: SpawnGit = async (args, cwd) => {
87
88
  const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
88
89
  if (!bun) return { exitCode: -1, stdout: '', stderr: 'bun runtime not available' }
89
90
  try {
90
- const proc = bun.spawn({ cmd: ['git', ...args], cwd, stdout: 'pipe', stderr: 'pipe' })
91
+ const proc = bun.spawn({ cmd: ['git', ...hooklessGitArgs(args)], cwd, stdout: 'pipe', stderr: 'pipe' })
91
92
  const exitCode = await proc.exited
92
93
  const stdout = await new Response(proc.stdout).text()
93
94
  const stderr = await new Response(proc.stderr).text()
@@ -0,0 +1,82 @@
1
+ import { hooklessGitArgs } from './hookless'
2
+ import { resolveAgentGit } from './resolve-agent-git'
3
+
4
+ // Machine-local `git config` written into the agent repo on every `typeclaw
5
+ // start` to bound git's gc/repack/pack-objects memory. Agents force-commit
6
+ // sessions/ + memory/, so packs grow to GB scale; on such a repo git's default
7
+ // auto-gc was measured at ~1.8GB RSS and OOM-killed the container. These keys cap
8
+ // the peak (git-config(1): peak ≈ pack.threads × pack.windowMemory + overhead).
9
+ // Do NOT "modernize" any back to a git default without re-checking the OOM:
10
+ // gc.auto/autoPackLimit=0 no surprise full repack from the backup's `git
11
+ // commit`; reclamation moves to the idle backup path
12
+ // (see bound-git-maintenance / Fix 2).
13
+ // pack.threads=1 default auto-detects to CPU count; windowMemory is
14
+ // PER THREAD, so N cores = N× the spike.
15
+ // pack.windowMemory=64m default is UNLIMITED — the primary per-thread bound.
16
+ // pack.deltaCacheSize=1 virtually disables the 256MB write-phase delta cache.
17
+ // core.bigFileThreshold=10m load-bearing for append-only JSONL: bigger objects
18
+ // store plain-deflated with NO delta attempt, keeping
19
+ // transcripts out of the memory-heavy delta pipeline.
20
+ // core.multiPackIndex=true required for Fix 2's `maintenance incremental-repack`.
21
+ export const BOUND_GC_CONFIG: ReadonlyArray<readonly [key: string, value: string]> = [
22
+ ['gc.auto', '0'],
23
+ ['gc.autoPackLimit', '0'],
24
+ ['gc.bigPackThreshold', '100m'],
25
+ ['pack.threads', '1'],
26
+ ['pack.windowMemory', '64m'],
27
+ ['pack.deltaCacheSize', '1'],
28
+ ['pack.window', '5'],
29
+ ['pack.depth', '10'],
30
+ ['core.bigFileThreshold', '10m'],
31
+ ['core.deltaBaseCacheLimit', '16m'],
32
+ ['core.multiPackIndex', 'true'],
33
+ ] as const
34
+
35
+ // Writes BOUND_GC_CONFIG into the agent repo's machine-local git config.
36
+ //
37
+ // Best-effort, exactly like untrackTrulyIgnoredFiles / commitSystemFile: no-ops
38
+ // when the folder is not a git repo or Bun is missing, and NEVER throws — start()
39
+ // hygiene must not block boot. These are `git config` (local scope) writes: they
40
+ // live in .git/config, are not tracked, not committed, and are idempotent —
41
+ // re-running just re-sets the same values.
42
+ //
43
+ // Returns the number of keys successfully written (0 when skipped) so callers /
44
+ // tests can assert the write happened without coupling to git internals.
45
+ export async function applyBoundGcConfig(cwd: string): Promise<{ applied: number }> {
46
+ const bun = getBun()
47
+ if (!bun) return { applied: 0 }
48
+ const repo = resolveAgentGit(cwd)
49
+ if (!repo) return { applied: 0 }
50
+
51
+ let applied = 0
52
+ for (const [key, value] of BOUND_GC_CONFIG) {
53
+ if (await setLocalConfig(bun, cwd, repo.gitArgs, key, value)) applied += 1
54
+ }
55
+ return { applied }
56
+ }
57
+
58
+ async function setLocalConfig(
59
+ bun: BunLike,
60
+ cwd: string,
61
+ gitArgs: readonly string[],
62
+ key: string,
63
+ value: string,
64
+ ): Promise<boolean> {
65
+ try {
66
+ const proc = bun.spawn({
67
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, 'config', '--local', key, value])],
68
+ cwd,
69
+ stdout: 'pipe',
70
+ stderr: 'pipe',
71
+ })
72
+ return (await proc.exited) === 0
73
+ } catch {
74
+ return false
75
+ }
76
+ }
77
+
78
+ type BunLike = { spawn: typeof Bun.spawn }
79
+
80
+ function getBun(): BunLike | undefined {
81
+ return (globalThis as { Bun?: BunLike }).Bun
82
+ }
@@ -0,0 +1,5 @@
1
+ const HOOKLESS_GIT_CONFIG = ['-c', 'core.hooksPath=/dev/null'] as const
2
+
3
+ export function hooklessGitArgs(args: readonly string[]): string[] {
4
+ return [...HOOKLESS_GIT_CONFIG, ...args]
5
+ }
@@ -4,6 +4,7 @@ import { join } from 'node:path'
4
4
 
5
5
  import { SYSTEM_MANAGED_ROOTS, TRULY_IGNORED_PATTERNS } from '@/init/gitignore'
6
6
 
7
+ import { hooklessGitArgs } from './hookless'
7
8
  import { type AgentGit, resolveAgentGit } from './resolve-agent-git'
8
9
 
9
10
  export type UntrackResult = { untracked: string[] }
@@ -170,7 +171,7 @@ async function listTrackedIgnored(
170
171
  excludeFile: string,
171
172
  ): Promise<string[]> {
172
173
  const proc = bun.spawn({
173
- cmd: ['git', ...gitArgs, 'ls-files', '-z', '-c', '-i', '--exclude-from', excludeFile],
174
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, 'ls-files', '-z', '-c', '-i', '--exclude-from', excludeFile])],
174
175
  cwd,
175
176
  stdout: 'pipe',
176
177
  stderr: 'pipe',
@@ -182,7 +183,7 @@ async function listTrackedIgnored(
182
183
 
183
184
  async function gitRmCached(bun: BunLike, cwd: string, gitArgs: readonly string[], files: string[]): Promise<string[]> {
184
185
  const proc = bun.spawn({
185
- cmd: ['git', ...gitArgs, 'rm', '--cached', '-q', '--', ...files],
186
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, 'rm', '--cached', '-q', '--', ...files])],
186
187
  cwd,
187
188
  stdout: 'pipe',
188
189
  stderr: 'pipe',
@@ -200,7 +201,13 @@ async function run(
200
201
  args: readonly string[],
201
202
  env?: GitEnv,
202
203
  ): Promise<boolean> {
203
- const proc = bun.spawn({ cmd: ['git', ...gitArgs, ...args], cwd, env, stdout: 'pipe', stderr: 'pipe' })
204
+ const proc = bun.spawn({
205
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, ...args])],
206
+ cwd,
207
+ env,
208
+ stdout: 'pipe',
209
+ stderr: 'pipe',
210
+ })
204
211
  return (await proc.exited) === 0
205
212
  }
206
213
 
@@ -211,7 +218,13 @@ async function capture(
211
218
  args: readonly string[],
212
219
  env?: GitEnv,
213
220
  ): Promise<string> {
214
- const proc = bun.spawn({ cmd: ['git', ...gitArgs, ...args], cwd, env, stdout: 'pipe', stderr: 'pipe' })
221
+ const proc = bun.spawn({
222
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, ...args])],
223
+ cwd,
224
+ env,
225
+ stdout: 'pipe',
226
+ stderr: 'pipe',
227
+ })
215
228
  if ((await proc.exited) !== 0) return ''
216
229
  return await new Response(proc.stdout).text()
217
230
  }
@@ -226,7 +239,7 @@ async function forceRemove(
226
239
  env: GitEnv,
227
240
  ): Promise<boolean> {
228
241
  const proc = bun.spawn({
229
- cmd: ['git', ...gitArgs, 'update-index', '-z', '--force-remove', '--stdin'],
242
+ cmd: ['git', ...hooklessGitArgs([...gitArgs, 'update-index', '-z', '--force-remove', '--stdin'])],
230
243
  cwd,
231
244
  env,
232
245
  stdin: new TextEncoder().encode(files.join('\0')),
@@ -1,3 +1,4 @@
1
+ import { hooklessGitArgs } from './hookless'
1
2
  import { resolveAgentGit } from './resolve-agent-git'
2
3
 
3
4
  // Commits TypeClaw-owned tracked files (.gitignore, package.json,
@@ -27,7 +28,7 @@ export async function commitSystemFile(cwd: string, file: string | readonly stri
27
28
  if (!repo) return
28
29
 
29
30
  const status = bun.spawn({
30
- cmd: ['git', ...repo.gitArgs, 'status', '--porcelain', '--', ...files],
31
+ cmd: ['git', ...hooklessGitArgs([...repo.gitArgs, 'status', '--porcelain', '--', ...files])],
31
32
  cwd,
32
33
  stdout: 'pipe',
33
34
  stderr: 'pipe',
@@ -36,11 +37,16 @@ export async function commitSystemFile(cwd: string, file: string | readonly stri
36
37
  const dirty = (await new Response(status.stdout).text()).trim().length > 0
37
38
  if (!dirty) return
38
39
 
39
- const add = bun.spawn({ cmd: ['git', ...repo.gitArgs, 'add', '--', ...files], cwd, stdout: 'pipe', stderr: 'pipe' })
40
+ const add = bun.spawn({
41
+ cmd: ['git', ...hooklessGitArgs([...repo.gitArgs, 'add', '--', ...files])],
42
+ cwd,
43
+ stdout: 'pipe',
44
+ stderr: 'pipe',
45
+ })
40
46
  if ((await add.exited) !== 0) return
41
47
 
42
48
  const commit = bun.spawn({
43
- cmd: ['git', ...repo.gitArgs, 'commit', '-m', message, '--only', '--', ...files],
49
+ cmd: ['git', ...hooklessGitArgs([...repo.gitArgs, 'commit', '-m', message, '--only', '--', ...files])],
44
50
  cwd,
45
51
  stdout: 'pipe',
46
52
  stderr: 'pipe',
@@ -73,7 +79,7 @@ export function commitSystemFileSync(cwd: string, file: string | readonly string
73
79
  if (!repo) return
74
80
 
75
81
  const status = bun.spawnSync({
76
- cmd: ['git', ...repo.gitArgs, 'status', '--porcelain', '--', ...files],
82
+ cmd: ['git', ...hooklessGitArgs([...repo.gitArgs, 'status', '--porcelain', '--', ...files])],
77
83
  cwd,
78
84
  stdout: 'pipe',
79
85
  stderr: 'pipe',
@@ -82,7 +88,7 @@ export function commitSystemFileSync(cwd: string, file: string | readonly string
82
88
  if (new TextDecoder().decode(status.stdout).trim().length === 0) return
83
89
 
84
90
  const add = bun.spawnSync({
85
- cmd: ['git', ...repo.gitArgs, 'add', '--', ...files],
91
+ cmd: ['git', ...hooklessGitArgs([...repo.gitArgs, 'add', '--', ...files])],
86
92
  cwd,
87
93
  stdout: 'pipe',
88
94
  stderr: 'pipe',
@@ -90,7 +96,7 @@ export function commitSystemFileSync(cwd: string, file: string | readonly string
90
96
  if (add.exitCode !== 0) return
91
97
 
92
98
  bun.spawnSync({
93
- cmd: ['git', ...repo.gitArgs, 'commit', '-m', message, '--only', '--', ...files],
99
+ cmd: ['git', ...hooklessGitArgs([...repo.gitArgs, 'commit', '-m', message, '--only', '--', ...files])],
94
100
  cwd,
95
101
  stdout: 'pipe',
96
102
  stderr: 'pipe',