typeclaw 0.45.0 → 0.46.0

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 (147) 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 +67 -25
  5. package/src/agent/live-subagents.ts +18 -0
  6. package/src/agent/loop-guard.ts +208 -10
  7. package/src/agent/multimodal/index.ts +1 -1
  8. package/src/agent/multimodal/look-at.ts +78 -44
  9. package/src/agent/multimodal/looker.ts +151 -39
  10. package/src/agent/network/response-body.ts +26 -0
  11. package/src/agent/network/safe-http.ts +198 -0
  12. package/src/agent/plugin-tools.ts +438 -162
  13. package/src/agent/provider-error.ts +62 -4
  14. package/src/agent/restart/index.ts +61 -40
  15. package/src/agent/restart-handoff/index.ts +73 -4
  16. package/src/agent/retry-same-ref.ts +66 -0
  17. package/src/agent/reviewer-bash-policy.ts +42 -1
  18. package/src/agent/session-origin.ts +2 -0
  19. package/src/agent/subagent-drain.ts +117 -7
  20. package/src/agent/subagents.ts +77 -18
  21. package/src/agent/throttle-circuit.ts +25 -5
  22. package/src/agent/tool-error-remediation.ts +72 -0
  23. package/src/agent/tool-file-safety.ts +1050 -0
  24. package/src/agent/tools/channel-fetch-attachment.ts +10 -3
  25. package/src/agent/tools/channel-reply.ts +15 -1
  26. package/src/agent/tools/channel-send.ts +17 -1
  27. package/src/agent/tools/ddg.ts +16 -2
  28. package/src/agent/tools/post-github-review.ts +199 -0
  29. package/src/agent/tools/spawn-subagent.ts +21 -18
  30. package/src/agent/tools/webfetch/fetch.ts +143 -183
  31. package/src/agent/tools/webfetch/tool.ts +2 -3
  32. package/src/agent/tools/websearch.ts +23 -2
  33. package/src/agent/tools-without-local-file-operands.ts +27 -0
  34. package/src/agent/turn-runner.ts +109 -15
  35. package/src/bundled-plugins/backup/index.ts +2 -1
  36. package/src/bundled-plugins/backup/runner.ts +2 -1
  37. package/src/bundled-plugins/doc-render/render.ts +93 -12
  38. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  39. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  40. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  41. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  42. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  43. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  44. package/src/bundled-plugins/memory/README.md +23 -11
  45. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  46. package/src/bundled-plugins/memory/citations.ts +22 -9
  47. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  48. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  49. package/src/bundled-plugins/memory/index.ts +0 -4
  50. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  51. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  52. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  53. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  54. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  55. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  56. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  57. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  58. package/src/bundled-plugins/reviewer/index.ts +2 -2
  59. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  60. package/src/bundled-plugins/reviewer/skills/code-review.ts +24 -9
  61. package/src/bundled-plugins/scout/scout.ts +8 -0
  62. package/src/bundled-plugins/security/index.ts +4 -4
  63. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  64. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  65. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  66. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  67. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  68. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  69. package/src/channels/adapters/discord-bot.ts +91 -10
  70. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  71. package/src/channels/adapters/discord-id.ts +4 -0
  72. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  73. package/src/channels/adapters/discord.ts +57 -7
  74. package/src/channels/adapters/github/auth-app.ts +41 -12
  75. package/src/channels/adapters/github/index.ts +23 -11
  76. package/src/channels/adapters/github/review-submitter.ts +302 -0
  77. package/src/channels/adapters/kakaotalk-channel-resolver.ts +12 -1
  78. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  79. package/src/channels/adapters/kakaotalk-typing.ts +127 -0
  80. package/src/channels/adapters/kakaotalk.ts +19 -0
  81. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  82. package/src/channels/adapters/slack-bot.ts +19 -8
  83. package/src/channels/adapters/slack-classify.ts +21 -2
  84. package/src/channels/adapters/slack.ts +59 -7
  85. package/src/channels/adapters/telegram-bot.ts +18 -5
  86. package/src/channels/adapters/webex-bot.ts +8 -3
  87. package/src/channels/adapters/webex.ts +8 -3
  88. package/src/channels/fetch-attachment.ts +43 -0
  89. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  90. package/src/channels/github-token-bridge.ts +10 -3
  91. package/src/channels/manager.ts +9 -0
  92. package/src/channels/router.ts +568 -12
  93. package/src/channels/types.ts +28 -1
  94. package/src/cli/channel.ts +1 -1
  95. package/src/cli/init.ts +1 -1
  96. package/src/cli/model.ts +57 -7
  97. package/src/compose/stop.ts +17 -5
  98. package/src/config/config.ts +6 -6
  99. package/src/config/models-mutation.ts +13 -1
  100. package/src/config/providers.ts +176 -0
  101. package/src/container/start.ts +49 -10
  102. package/src/doctor/checks.ts +3 -1
  103. package/src/doctor/commit.ts +2 -1
  104. package/src/doctor/file-ownership.ts +52 -0
  105. package/src/dreams/git.ts +2 -1
  106. package/src/git/hookless.ts +5 -0
  107. package/src/git/reconcile-ignored.ts +18 -5
  108. package/src/git/secret-history.ts +371 -0
  109. package/src/git/system-commit.ts +12 -6
  110. package/src/init/dockerfile.ts +86 -5
  111. package/src/init/index.ts +17 -5
  112. package/src/init/models-dev.ts +4 -0
  113. package/src/init/validate-api-key.ts +2 -0
  114. package/src/mcp/tools.ts +16 -3
  115. package/src/permissions/builtins.ts +3 -1
  116. package/src/plugin/context.ts +2 -0
  117. package/src/plugin/index.ts +1 -0
  118. package/src/plugin/manager.ts +4 -0
  119. package/src/plugin/types.ts +21 -0
  120. package/src/run/index.ts +40 -0
  121. package/src/run/llm-fetch-observer.ts +188 -13
  122. package/src/sandbox/build.ts +37 -15
  123. package/src/sandbox/canonical-secrets.ts +18 -0
  124. package/src/sandbox/env-exposure.ts +80 -0
  125. package/src/sandbox/errors.ts +13 -6
  126. package/src/sandbox/hidden-paths.ts +102 -44
  127. package/src/sandbox/index.ts +22 -4
  128. package/src/sandbox/package-install.ts +3 -27
  129. package/src/sandbox/policy.ts +11 -25
  130. package/src/sandbox/privileged-runtime.ts +255 -0
  131. package/src/sandbox/session-tmp.ts +8 -2
  132. package/src/sandbox/writable-zones.ts +204 -140
  133. package/src/secrets/index.ts +8 -0
  134. package/src/secrets/refresh-provider-oauth.ts +128 -0
  135. package/src/server/command-runner.ts +48 -4
  136. package/src/server/index.ts +4 -0
  137. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  138. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  139. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  140. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  141. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  142. package/src/skills/typeclaw-config/SKILL.md +5 -5
  143. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  144. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  145. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  146. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  147. package/typeclaw.schema.json +20 -0
@@ -32,6 +32,7 @@ const GENERIC_SAFE_NOTICE = 'The upstream LLM provider failed. Operators can che
32
32
  // reaches `detectProviderError`; the marker lets the hard-throw path recognize
33
33
  // and surface it. The literal is the system's own token — English by design.
34
34
  const OBSERVER_TIMEOUT = /\(typeclaw observer timeout\)/i
35
+ const OBSERVER_TTFB_TIMEOUT = /timed out before response headers/i
35
36
 
36
37
  // Transport-layer failure: the request died at the connection/session before a
37
38
  // usable response — an expired live session, a WebSocket upgrade that never
@@ -42,17 +43,47 @@ const OBSERVER_TIMEOUT = /\(typeclaw observer timeout\)/i
42
43
  // `wss://…/codex/responses` non-101 upgrade). Provider protocol tokens — English
43
44
  // by design (the system-token exception to the multi-language rule).
44
45
  const TRANSPORT_FAILURE =
45
- /provider[_ -]?transport[_ -]?failure|(?:websocket|ws) connection.*failed|expected 101|session expired/i
46
+ /provider[_ -]?transport[_ -]?failure|(?:websocket|ws)(?: connection)?(?:(?: was| is)? closed|.*failed)|expected 101|session expired/i
46
47
 
47
48
  // Auth failure: the provider rejected our credentials (bad/expired/missing API
48
- // key, 401, failed authentication). Account-wide — a different ref shares the
49
+ // key or token, 401/403, failed authentication). Account-wide — a different ref shares the
49
50
  // same credential problem — so this is BOTH a redacted safe-message class (a
50
51
  // 401 body can carry a Bearer token) AND a NON_FAILOVER_FAULT reason. Shared as
51
52
  // one constant so the two uses can never drift: previously the safe-message copy
52
53
  // matched `api key ... expired` but the failover copy didn't, letting
53
54
  // `session expired: api key expired` wrongly fail over past the auth guard.
54
55
  const AUTH_FAULT =
55
- /\b(401|unauthori[sz]ed|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|authentication failed|invalid bearer)\b/i
56
+ /\b(401|403|unauthori[sz]ed|forbidden|access denied|invalid[_ -]?api[_ -]?key|api key.*(?:invalid|expired|missing)|(?:access|session)[_ -]?token(?:(?:[_ -]+)(?:has|is))?[_ -]+expired|authentication(?: failed|[_ -]?error)|invalid bearer)\b/i
57
+
58
+ // Unsupported-or-misspelled MODEL id specifically. Codex returns
59
+ // `{"type":"invalid_request_error","message":"The 'gpt-5.6' model is not
60
+ // supported when using Codex with a ChatGPT account."}` for a model that isn't
61
+ // in the account's catalog. This is account/config-wide: retrying or failing
62
+ // over to another ref can't fix a bad `models` entry, so it is BOTH a redacted
63
+ // safe-message class (an actionable "check your model config" notice, not the
64
+ // generic one) AND a NON_FAILOVER_FAULT reason. Shared as one constant so the
65
+ // two uses can't drift (mirrors AUTH_FAULT). Matched against the raw JSON body:
66
+ // pi-ai's Codex adapter can't lift the nested `error.message` and stringifies
67
+ // the whole event, so the text is the raw payload.
68
+ //
69
+ // This is deliberately NARROWER than "any invalid_request_error": OpenAI's
70
+ // `BadRequestError`/`invalid_request_error` also covers missing parameters,
71
+ // out-of-range values, and encoding/format/size problems — none of which are a
72
+ // model-config issue. Requiring model-specific evidence (`model_not_found`, or
73
+ // a `… model … not supported` / `model = …` phrasing) keeps the model notice
74
+ // from misdiagnosing those. Bare invalid requests are handled by
75
+ // `INVALID_REQUEST` below.
76
+ const INVALID_MODEL =
77
+ /\bmodel_not_found\b|\bmodel\b[^"]*\bnot supported\b|\bnot supported\b[^"]*\bmodel\b|\bunsupported\b[^"]*\bmodel\b|\bunknown model\b|\binvalid model\b/i
78
+
79
+ // Any OTHER provider-side invalid request: a malformed body, a missing/invalid
80
+ // parameter, a bad value, or an encoding/format/size problem. Still not fixable
81
+ // by retrying or failing over the SAME payload to another ref, so it stays a
82
+ // NON_FAILOVER_FAULT reason — but it gets a GENERIC invalid-request message, not
83
+ // the model-config notice, so a non-model 400 is never misattributed to the
84
+ // `models` setting. Anchored on the provider's own `invalid_request_error`
85
+ // token so it doesn't match natural-language prose.
86
+ const INVALID_REQUEST = /\binvalid_request_error\b/i
56
87
 
57
88
  // Each entry pairs a narrow matcher against the raw provider text with the
58
89
  // canonical, leak-free sentence shown in channels. Matchers are intentionally
@@ -76,6 +107,22 @@ const SAFE_CLASSES: ReadonlyArray<{ match: RegExp; safe: string }> = [
76
107
  match: /\bcyber_policy\b/i,
77
108
  safe: 'The upstream LLM provider (OpenAI Codex) refused the request under its cybersecurity content policy. Operators must enroll the account in OpenAI Trusted Access for Cyber at https://chatgpt.com/cyber, or switch the configured model.',
78
109
  },
110
+ {
111
+ // Model-specific invalid request — an unsupported or misspelled model id.
112
+ // Placed AFTER cyber_policy so a policy refusal keeps its more specific
113
+ // notice, and BEFORE the generic INVALID_REQUEST below so a model error gets
114
+ // the actionable `models`-setting hint rather than the generic invalid-request
115
+ // sentence. Requires model evidence, so a non-model 400 falls through here.
116
+ match: INVALID_MODEL,
117
+ safe: 'The upstream LLM provider rejected the request as invalid — the configured model is likely unsupported or misspelled. Operators should check the `models` setting in typeclaw.json and `typeclaw logs`.',
118
+ },
119
+ {
120
+ // Any other provider-side invalid request (malformed body, missing/invalid
121
+ // parameter, size/format problem). Distinct GENERIC wording — it is NOT
122
+ // attributed to the model config, since the evidence above didn't match.
123
+ match: INVALID_REQUEST,
124
+ safe: 'The upstream LLM provider rejected the request as invalid. Operators can check `typeclaw logs` for details.',
125
+ },
79
126
  {
80
127
  match: /\b(usage limit|rate limit|rate.?limited|too many requests|429)\b/i,
81
128
  safe: 'The upstream LLM provider is rate-limited (usage limit reached). Try again shortly.',
@@ -116,15 +163,24 @@ const THROTTLE_OR_OVERLOAD =
116
163
  // status code alone must not force a pointless failover. The auth arm reuses the
117
164
  // shared `AUTH_FAULT` source so it stays in lockstep with the safe-message class.
118
165
  const NON_FAILOVER_FAULT = new RegExp(
119
- `\\bcyber_policy\\b|insufficient.*(?:quota|credit|fund|balance)|\\bquota\\b|billing|payment|account is not active|${AUTH_FAULT.source}`,
166
+ `${INVALID_MODEL.source}|${INVALID_REQUEST.source}|\\bcyber_policy\\b|insufficient.*(?:quota|credit|fund|balance)|\\bquota\\b|billing|payment|account is not active|${AUTH_FAULT.source}`,
120
167
  'i',
121
168
  )
122
169
 
170
+ // Context-window exhaustion belongs to the SDK compaction/error path, never
171
+ // transport recovery. Keep this to provider protocol forms rather than matching
172
+ // natural-language user text.
173
+ const CONTEXT_OVERFLOW = /\bcontext[_ -]?length[_ -]?exceeded\b/i
174
+
123
175
  export function isThrottleOrOverload(raw: string): boolean {
124
176
  if (NON_FAILOVER_FAULT.test(raw)) return false
125
177
  return THROTTLE_OR_OVERLOAD.test(raw)
126
178
  }
127
179
 
180
+ export function isObserverTtfbTimeout(raw: string): boolean {
181
+ return OBSERVER_TIMEOUT.test(raw) && OBSERVER_TTFB_TIMEOUT.test(raw)
182
+ }
183
+
128
184
  // Failover predicate for turn-drivers' `shouldFailover`: rotate to the next model
129
185
  // ref on a transient capacity signal (throttle/overload), an observer stall
130
186
  // timeout, or a transport/session failure. A stall or a dropped session is as
@@ -133,6 +189,7 @@ export function isThrottleOrOverload(raw: string): boolean {
133
189
  // Account-wide faults (billing/quota/auth) are excluded up front — a different
134
190
  // ref shares the same account problem, so switching can't help.
135
191
  export function isFailoverWorthy(raw: string): boolean {
192
+ if (CONTEXT_OVERFLOW.test(raw)) return false
136
193
  if (NON_FAILOVER_FAULT.test(raw)) return false
137
194
  return isThrottleOrOverload(raw) || OBSERVER_TIMEOUT.test(raw) || TRANSPORT_FAILURE.test(raw)
138
195
  }
@@ -157,6 +214,7 @@ const NETWORK_OR_5XX =
157
214
  // does NOT match context-overflow: that stays on the SDK compaction path and must
158
215
  // never be treated as a retryable provider failure.
159
216
  export function isRetryableSameRef(raw: string): boolean {
217
+ if (CONTEXT_OVERFLOW.test(raw)) return false
160
218
  if (NON_FAILOVER_FAULT.test(raw)) return false
161
219
  if (isThrottleOrOverload(raw)) return false
162
220
  return TRANSPORT_FAILURE.test(raw) || OBSERVER_TIMEOUT.test(raw) || NETWORK_OR_5XX.test(raw)
@@ -1,6 +1,6 @@
1
1
  import { basename } from 'node:path'
2
2
 
3
- import { type RestartHandoffOrigin, writeRestartHandoff } from '@/agent/restart-handoff'
3
+ import { acquireRestartHandoffLock, type RestartHandoffOrigin, writeRestartHandoff } from '@/agent/restart-handoff'
4
4
  import { sendHttp } from '@/hostd/client'
5
5
  import type { Stream } from '@/stream'
6
6
 
@@ -77,52 +77,73 @@ export async function requestContainerRestart({
77
77
  'host daemon control endpoint unavailable (TYPECLAW_HOSTD_URL/TYPECLAW_HOSTD_TOKEN not set); cannot request restart',
78
78
  }
79
79
  }
80
- const reply = await sendHttp(request, { timeoutMs: ackBudget, url: httpUrl, token: httpToken })
80
+ const url = httpUrl
81
+ const token = httpToken
81
82
 
82
- if (!reply.ok) return { ok: false, containerName, reason: reply.reason }
83
-
84
- const restartTimestamp = restartedAt ?? new Date().toISOString()
85
-
86
- // Fan out the restart notice to every live session BEFORE writing the handoff.
87
- // The originating session's subscribeRestartNotice appends the
88
- // typeclaw.restart-self entry synchronously (broker delivery + the JSONL
89
- // append are both synchronous), so the handoff below points at a JSONL that
90
- // already carries the "I'm back" instruction the rebooted container hydrates.
91
- // Only after an accepted ACK, never on a failed/timed-out restart.
92
- if (stream !== undefined && originatingSessionId !== undefined) {
93
- const broadcast: ContainerRestartingBroadcast = {
94
- kind: 'container-restarting',
95
- restartedAt: restartTimestamp,
96
- originatingSessionId,
97
- }
98
- stream.publish({ target: { kind: 'broadcast' }, payload: broadcast })
99
- }
100
-
101
- // Post-ACK: hostd has committed the restart, so a handoff-write failure must
102
- // never demote it to a failure — that would render a false error in the TUI
103
- // and swallow the accepted response. The handoff is a best-effort resume hint
104
- // only; a missing one just cold-starts the rebooted container without the
105
- // "I'm back" greeting. writeRestartHandoff swallows its own errors today, but
106
- // guard here too so this contract survives the writer being changed later.
107
- if (
83
+ const handoffTarget =
108
84
  agentDir !== undefined &&
109
85
  originatingSessionId !== undefined &&
110
86
  originatingSessionFile !== undefined &&
111
87
  handoffOrigin !== undefined
112
- ) {
113
- try {
114
- await writeRestartHandoff(agentDir, {
115
- schemaVersion: 2,
88
+ ? { agentDir, originatingSessionId, originatingSessionFile, handoffOrigin }
89
+ : undefined
90
+
91
+ // Hold the handoff lock from BEFORE the ACK through our post-ACK write. hostd
92
+ // fires `docker stop` → SIGTERM the instant it accepts, so the container's
93
+ // SIGTERM writer can run while we are still mid-flight; the lock makes it wait
94
+ // and then augment the exact handoff we commit here, instead of synthesizing
95
+ // one for another session in the gap before our write lands.
96
+ const releaseHandoffLock =
97
+ handoffTarget !== undefined ? await acquireRestartHandoffLock(handoffTarget.agentDir) : undefined
98
+ try {
99
+ return await performRestart()
100
+ } finally {
101
+ releaseHandoffLock?.()
102
+ }
103
+
104
+ async function performRestart(): Promise<RequestContainerRestartResult> {
105
+ const reply = await sendHttp(request, { timeoutMs: ackBudget, url, token })
106
+
107
+ if (!reply.ok) return { ok: false, containerName, reason: reply.reason }
108
+
109
+ const restartTimestamp = restartedAt ?? new Date().toISOString()
110
+
111
+ // Fan out the restart notice to every live session BEFORE writing the handoff.
112
+ // The originating session's subscribeRestartNotice appends the
113
+ // typeclaw.restart-self entry synchronously (broker delivery + the JSONL
114
+ // append are both synchronous), so the handoff below points at a JSONL that
115
+ // already carries the "I'm back" instruction the rebooted container hydrates.
116
+ // Only after an accepted ACK, never on a failed/timed-out restart.
117
+ if (stream !== undefined && originatingSessionId !== undefined) {
118
+ const broadcast: ContainerRestartingBroadcast = {
119
+ kind: 'container-restarting',
116
120
  restartedAt: restartTimestamp,
117
121
  originatingSessionId,
118
- originatingSessionFile: basename(originatingSessionFile),
119
- origin: handoffOrigin,
120
- ...(triggeringAuthorId !== undefined ? { triggeringAuthorId } : {}),
121
- })
122
- } catch {
123
- // intentional swallow — see the post-ACK rationale above
122
+ }
123
+ stream.publish({ target: { kind: 'broadcast' }, payload: broadcast })
124
124
  }
125
- }
126
125
 
127
- return { ok: true, containerName, restartedAt: restartTimestamp }
126
+ // Post-ACK: hostd has committed the restart, so a handoff-write failure must
127
+ // never demote it to a failure — that would render a false error in the TUI
128
+ // and swallow the accepted response. The handoff is a best-effort resume hint
129
+ // only; a missing one just cold-starts the rebooted container without the
130
+ // "I'm back" greeting. writeRestartHandoff swallows its own errors today, but
131
+ // guard here too so this contract survives the writer being changed later.
132
+ if (handoffTarget !== undefined) {
133
+ try {
134
+ await writeRestartHandoff(handoffTarget.agentDir, {
135
+ schemaVersion: 2,
136
+ restartedAt: restartTimestamp,
137
+ originatingSessionId: handoffTarget.originatingSessionId,
138
+ originatingSessionFile: basename(handoffTarget.originatingSessionFile),
139
+ origin: handoffTarget.handoffOrigin,
140
+ ...(triggeringAuthorId !== undefined ? { triggeringAuthorId } : {}),
141
+ })
142
+ } catch {
143
+ // intentional swallow — see the post-ACK rationale above
144
+ }
145
+ }
146
+
147
+ return { ok: true, containerName, restartedAt: restartTimestamp }
148
+ }
128
149
  }
@@ -1,3 +1,4 @@
1
+ import { randomUUID } from 'node:crypto'
1
2
  import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
2
3
  import { dirname } from 'node:path'
3
4
 
@@ -9,6 +10,39 @@ export { restartHandoffPath } from './paths'
9
10
 
10
11
  export const RESTART_HANDOFF_TTL_MS = 60_000
11
12
 
13
+ // Process-local serialization of the two same-process handoff producers that
14
+ // race during a restart: the in-session `/restart` tool (which writes the
15
+ // originating handoff post-ACK) and the SIGTERM writer (which peek-augments it).
16
+ // hostd fires `docker stop` → SIGTERM before its ACK reaches the container, so
17
+ // without this the SIGTERM read-modify-write can interleave with `/restart`'s
18
+ // write and drop the originating session's origin/author or its interrupted
19
+ // children. This is NOT a cross-process lock — both producers live in this one
20
+ // container process; the event loop yields at every await, so a promise-chain
21
+ // mutex is all that's needed. Keyed by handoff path so distinct agent dirs
22
+ // (tests) never contend.
23
+ const handoffLocks = new Map<string, Promise<void>>()
24
+
25
+ export async function acquireRestartHandoffLock(agentDir: string): Promise<() => void> {
26
+ const key = restartHandoffPath(agentDir)
27
+ const prior = handoffLocks.get(key) ?? Promise.resolve()
28
+ let release!: () => void
29
+ const held = new Promise<void>((resolve) => {
30
+ release = resolve
31
+ })
32
+ const chained = prior.then(() => held)
33
+ handoffLocks.set(key, chained)
34
+ await prior
35
+ let released = false
36
+ return () => {
37
+ if (released) return
38
+ released = true
39
+ // Drop the map entry only if we are still the tail, so a later waiter that
40
+ // already chained onto `chained` is not orphaned.
41
+ if (handoffLocks.get(key) === chained) handoffLocks.delete(key)
42
+ release()
43
+ }
44
+ }
45
+
12
46
  // The channel coordinates needed to reopen and wake the originating session
13
47
  // on the channel side after a restart. Mirrors ChannelKey (src/channels/types)
14
48
  // but is duplicated here so the handoff module does not depend on the channel
@@ -42,6 +76,12 @@ export type RestartHandoff = {
42
76
  // whatever bare-channel rule matches on every "I'm back" turn. Optional and
43
77
  // additive: pre-field v2 handoffs and tui handoffs omit it.
44
78
  triggeringAuthorId?: string
79
+ // Names of background subagents still running when the restart fired, so the
80
+ // resumed session can tell the thread its promised result was lost. Absent
81
+ // (never an empty array) when nothing was in flight. Rides the handoff's 60s
82
+ // TTL, so a stop→idle-for-hours→start drops it instead of replaying a stale
83
+ // notice into a moved-on conversation.
84
+ interruptedSubagents?: string[]
45
85
  }
46
86
 
47
87
  // Atomic write via `.tmp` + rename so a crash mid-write never leaves the
@@ -50,16 +90,36 @@ export type RestartHandoff = {
50
90
  // half-written one. Errors are swallowed: handoff is best-effort. A failed
51
91
  // write means the next boot cold-starts (no greeting), which is the same
52
92
  // graceful degradation as the dying container being SIGKILL'd before the
53
- // write could run.
54
- export async function writeRestartHandoff(agentDir: string, handoff: RestartHandoff): Promise<void> {
93
+ // write could run. Returns whether the file was actually written, so a caller
94
+ // whose contract depends on the write landing can react to the swallowed
95
+ // failure instead of assuming success.
96
+ export async function writeRestartHandoff(agentDir: string, handoff: RestartHandoff): Promise<boolean> {
55
97
  const path = restartHandoffPath(agentDir)
98
+ // Per-write unique tmp name so two producers staging concurrently never share
99
+ // a staging file or race a rename against a tmp the other already renamed
100
+ // away. The final rename stays atomic; last rename wins, ordered by the lock.
101
+ const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`
56
102
  try {
57
103
  await mkdir(dirname(path), { recursive: true })
58
- const tmp = `${path}.tmp`
59
104
  await writeFile(tmp, JSON.stringify(handoff), 'utf8')
60
105
  await rename(tmp, path)
106
+ return true
107
+ } catch {
108
+ await rm(tmp, { force: true }).catch(() => undefined)
109
+ return false
110
+ }
111
+ }
112
+
113
+ // Non-consuming read of the pending handoff, for a caller that must decide
114
+ // whether one already exists before writing its own (so an accepted in-session
115
+ // restart's handoff is preserved rather than clobbered). Unlike consumeRestartHandoff
116
+ // this never deletes, never applies the TTL, and never restores — it is a pure
117
+ // peek. Returns null when absent or malformed.
118
+ export async function peekRestartHandoff(agentDir: string): Promise<RestartHandoff | null> {
119
+ try {
120
+ return parseHandoff(await readFile(restartHandoffPath(agentDir), 'utf8'))
61
121
  } catch {
62
- return
122
+ return null
63
123
  }
64
124
  }
65
125
 
@@ -168,9 +228,18 @@ function parseHandoff(raw: string): RestartHandoff | null {
168
228
  ...(typeof obj.triggeringAuthorId === 'string' && obj.triggeringAuthorId !== ''
169
229
  ? { triggeringAuthorId: obj.triggeringAuthorId }
170
230
  : {}),
231
+ ...(() => {
232
+ const names = parseInterruptedSubagents(obj.interruptedSubagents)
233
+ return names.length > 0 ? { interruptedSubagents: names } : {}
234
+ })(),
171
235
  }
172
236
  }
173
237
 
238
+ function parseInterruptedSubagents(raw: unknown): string[] {
239
+ if (!Array.isArray(raw)) return []
240
+ return raw.filter((entry): entry is string => typeof entry === 'string' && entry !== '')
241
+ }
242
+
174
243
  function parseOrigin(raw: unknown): RestartHandoffOrigin | null {
175
244
  if (raw === null || typeof raw !== 'object') return null
176
245
  const obj = raw as Record<string, unknown>
@@ -79,6 +79,72 @@ export async function retryTurnOnPersistentSession(
79
79
  return true
80
80
  }
81
81
 
82
+ // Resume only the post-tool provider-failure shape. Unlike the generic helper,
83
+ // this deliberately refuses a trailing user leaf or an assistant error whose
84
+ // predecessor is anything other than the completed tool result. Callers use it
85
+ // after externally visible tool activity, where replaying the original turn
86
+ // could duplicate side effects.
87
+ export async function retryTurnAfterCompletedToolResult(
88
+ session: AgentSession,
89
+ opts: {
90
+ attempt: number
91
+ signal?: AbortSignal
92
+ random?: () => number
93
+ authorize: () => boolean
94
+ onBackoffStart?: () => void
95
+ },
96
+ ): Promise<boolean> {
97
+ const agent = (session as { agent?: ContinuableAgent }).agent
98
+ if (!agent || typeof agent.continue !== 'function') return false
99
+ if (!hasCompletedToolResultErrorTail(agent.state?.messages)) return false
100
+
101
+ opts.onBackoffStart?.()
102
+ await sleep(retryBackoffMs(opts.attempt, opts.random), opts.signal)
103
+ if (opts.signal?.aborted) return false
104
+
105
+ // Re-read after the backoff: another actor may have advanced the transcript
106
+ // while we slept. Mutation is safe only while the exact tail still holds.
107
+ const messages = agent.state?.messages
108
+ if (!hasCompletedToolResultErrorTail(messages)) return false
109
+ if (opts.authorize() !== true) return false
110
+
111
+ const originalMessages = messages
112
+ const prefix = messages.slice(0, -1)
113
+ ;(agent.state as { messages: unknown }).messages = prefix
114
+ try {
115
+ await agent.continue()
116
+ } catch (err) {
117
+ if (hasSameEntries(agent.state?.messages, prefix)) {
118
+ ;(agent.state as { messages: unknown }).messages = originalMessages
119
+ }
120
+ throw err
121
+ }
122
+ return true
123
+ }
124
+
125
+ function hasCompletedToolResultErrorTail(messages: unknown): messages is unknown[] {
126
+ if (!Array.isArray(messages) || messages.length < 2) return false
127
+ const predecessor = messages[messages.length - 2]
128
+ const leaf = messages[messages.length - 1]
129
+ return (
130
+ typeof predecessor === 'object' &&
131
+ predecessor !== null &&
132
+ (predecessor as { role?: unknown }).role === 'toolResult' &&
133
+ typeof leaf === 'object' &&
134
+ leaf !== null &&
135
+ (leaf as { role?: unknown }).role === 'assistant' &&
136
+ (leaf as { stopReason?: unknown }).stopReason === 'error'
137
+ )
138
+ }
139
+
140
+ function hasSameEntries(messages: unknown, expected: unknown[]): boolean {
141
+ return (
142
+ Array.isArray(messages) &&
143
+ messages.length === expected.length &&
144
+ messages.every((entry, i) => entry === expected[i])
145
+ )
146
+ }
147
+
82
148
  // Same-ref retry for DIRECT `session.prompt()` call sites that bypass the model
83
149
  // fallback helpers (non-stream TUI, slash commands, subagent drain/required-block
84
150
  // nudges, multimodal look-at). These lost the SDK's built-in retry when it was
@@ -92,6 +92,8 @@ const READONLY_VERBS = new Set([
92
92
  'true',
93
93
  'false',
94
94
  'test',
95
+ 'which', // read-only tool-availability probe; does not execute the queried command
96
+ 'type', // shell builtin lookup; read-only. `type -a foo` reports, never runs
95
97
  'dirname',
96
98
  'basename',
97
99
  'realpath',
@@ -166,7 +168,7 @@ const GIT_MUTATING_ALWAYS_DENIED = new Set([
166
168
  ])
167
169
 
168
170
  // git subcommands permitted only when the effective working dir is /tmp.
169
- const GIT_TMP_SCOPED = new Set(['clone', 'fetch', 'checkout', 'init', 'sparse-checkout', 'worktree'])
171
+ const GIT_TMP_SCOPED = new Set(['init', 'sparse-checkout', 'worktree'])
170
172
 
171
173
  // `gh` subcommands/objects that mutate remote state. The reviewer reads PRs and
172
174
  // repos; it never merges, reviews, comments, edits, or creates. We allow the
@@ -515,6 +517,44 @@ function assertGhApiReadOnly(rest: string[]): void {
515
517
  }
516
518
  }
517
519
 
520
+ // `command` normally re-enters execution (`command git push` runs `git push`),
521
+ // so it is a forbidden wrapper by default. The sole read-only exception is the
522
+ // lookup form `command -v NAME` / `command -V NAME`, which only *reports* whether
523
+ // NAME resolves and never executes it — the reviewer's legitimate "is this tool
524
+ // available?" probe.
525
+ //
526
+ // The parse must respect POSIX `command [-pVv] name [arg...]` operand semantics:
527
+ // only options BEFORE the first operand are `command`'s own; the first non-option
528
+ // token is the command NAME, and everything after it is that command's arguments.
529
+ // So `command git push -v` is NOT a lookup — `git` is the operand and the trailing
530
+ // `-v` belongs to `git push` (a real verbose push). Scanning every position for a
531
+ // `-v` (the earlier bug) would misread that as a lookup and authorize a mutation.
532
+ // We therefore require a `-v`/`-V` among the LEADING options, reject `-p` (forces a
533
+ // PATH exec) and `--` (ends option parsing → execution), and — since a lookup takes
534
+ // exactly one NAME and never runs it — reject any operand beyond that single name.
535
+ function classifyCommandBuiltin(tokens: string[]): void {
536
+ const args = tokens.slice(1)
537
+ const leadingOptions: string[] = []
538
+ let i = 0
539
+ while (i < args.length && args[i]!.startsWith('-') && args[i] !== '--') {
540
+ leadingOptions.push(args[i]!)
541
+ i++
542
+ }
543
+ const operands = args.slice(i).filter((t) => t !== '--')
544
+ const endsOptionParsing = i < args.length && args[i] === '--'
545
+
546
+ const isLookup = leadingOptions.some((f) => f === '-v' || f === '-V' || f === '-vV' || f === '-Vv')
547
+ const forcesExecution = leadingOptions.some((f) => f === '-p' || f.includes('p')) || endsOptionParsing
548
+ // A lookup resolves exactly one NAME and never executes it; a second operand
549
+ // means the extra tokens are arguments to an executed command, not a lookup.
550
+ const isSingleNameLookup = isLookup && !forcesExecution && operands.length <= 1
551
+
552
+ if (isSingleNameLookup) return
553
+ throw new SubagentBashPolicyError(
554
+ '`command` re-enters execution (only the read-only lookup form `command -v NAME` is allowed); it is not permitted.',
555
+ )
556
+ }
557
+
518
558
  function classifyFsWriter(verb: string, tokens: string[], redirectTargets: string[]): void {
519
559
  const operands = tokens.slice(1).filter((t) => !t.startsWith('-'))
520
560
  const allUnderTmp = operands.length > 0 && operands.every(isTmpPath) && redirectTargets.every(isTmpPath)
@@ -538,6 +578,7 @@ function classifySegment(segment: Segment): void {
538
578
  if (tokens.length === 0) return
539
579
  const verb = stripQuotes(tokens[0]!)
540
580
 
581
+ if (verb === 'command') return classifyCommandBuiltin(tokens)
541
582
  if (FORBIDDEN_WRAPPER_VERBS.has(verb)) {
542
583
  throw new SubagentBashPolicyError(`\`${verb}\` can re-enter a shell or hand off execution; it is not permitted.`)
543
584
  }
@@ -39,6 +39,8 @@ export type SessionOrigin =
39
39
  chat: string
40
40
  chatName?: string
41
41
  thread: string | null
42
+ parentChat?: string
43
+ parentChatName?: string
42
44
  lastInboundAuthorId?: string
43
45
  reactionRef?: ReactionRef
44
46
  participants?: readonly ChannelParticipant[]