typeclaw 0.45.1 → 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 (142) hide show
  1. package/README.md +1 -1
  2. package/package.json +2 -1
  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 +151 -39
  9. package/src/agent/network/response-body.ts +26 -0
  10. package/src/agent/network/safe-http.ts +198 -0
  11. package/src/agent/plugin-tools.ts +379 -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 +1050 -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 +143 -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 +27 -0
  30. package/src/agent/turn-runner.ts +86 -6
  31. package/src/bundled-plugins/backup/index.ts +2 -1
  32. package/src/bundled-plugins/backup/runner.ts +2 -1
  33. package/src/bundled-plugins/doc-render/render.ts +93 -12
  34. package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md +13 -13
  35. package/src/bundled-plugins/github-cli-auth/effective-approval.ts +16 -6
  36. package/src/bundled-plugins/github-cli-auth/gh-command.ts +555 -15
  37. package/src/bundled-plugins/github-cli-auth/index.ts +131 -135
  38. package/src/bundled-plugins/github-cli-auth/review-checkout.ts +138 -0
  39. package/src/bundled-plugins/guard/policies/uncommitted-changes.ts +2 -1
  40. package/src/bundled-plugins/memory/README.md +23 -11
  41. package/src/bundled-plugins/memory/append-tool.ts +15 -8
  42. package/src/bundled-plugins/memory/citations.ts +22 -9
  43. package/src/bundled-plugins/memory/dreaming.ts +13 -8
  44. package/src/bundled-plugins/memory/find-entry-tool.ts +4 -0
  45. package/src/bundled-plugins/memory/index.ts +0 -4
  46. package/src/bundled-plugins/memory/load-memory.ts +8 -3
  47. package/src/bundled-plugins/memory/provenance-index.ts +717 -0
  48. package/src/bundled-plugins/memory/provenance-sanitize.ts +40 -0
  49. package/src/bundled-plugins/memory/references/store-reference-tool.ts +4 -0
  50. package/src/bundled-plugins/memory/search-tool.ts +163 -60
  51. package/src/bundled-plugins/memory/stream-events.ts +2 -0
  52. package/src/bundled-plugins/memory/vector/hybrid.ts +126 -13
  53. package/src/bundled-plugins/researcher/write-report.ts +6 -3
  54. package/src/bundled-plugins/reviewer/index.ts +2 -2
  55. package/src/bundled-plugins/reviewer/reviewer.ts +10 -3
  56. package/src/bundled-plugins/reviewer/skills/code-review.ts +19 -9
  57. package/src/bundled-plugins/scout/scout.ts +8 -0
  58. package/src/bundled-plugins/security/index.ts +4 -4
  59. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +1 -0
  60. package/src/bundled-plugins/security/policies/private-surface-read.ts +220 -29
  61. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +1 -0
  62. package/src/bundled-plugins/security/policies/ssrf.ts +29 -9
  63. package/src/channels/adapters/discord-bot-channel-resolver.ts +26 -14
  64. package/src/channels/adapters/discord-bot-thread-room.ts +44 -12
  65. package/src/channels/adapters/discord-bot.ts +66 -6
  66. package/src/channels/adapters/discord-channel-resolver.ts +91 -23
  67. package/src/channels/adapters/discord-id.ts +4 -0
  68. package/src/channels/adapters/discord-resolver-cache.ts +41 -0
  69. package/src/channels/adapters/discord.ts +57 -7
  70. package/src/channels/adapters/github/auth-app.ts +41 -12
  71. package/src/channels/adapters/github/index.ts +23 -11
  72. package/src/channels/adapters/github/review-submitter.ts +302 -0
  73. package/src/channels/adapters/kakaotalk-channel-resolver.ts +5 -3
  74. package/src/channels/adapters/kakaotalk-fetch-attachment.ts +8 -4
  75. package/src/channels/adapters/kakaotalk-typing.ts +17 -15
  76. package/src/channels/adapters/slack-attachment-download.ts +71 -0
  77. package/src/channels/adapters/slack-bot.ts +19 -8
  78. package/src/channels/adapters/slack-classify.ts +21 -2
  79. package/src/channels/adapters/slack.ts +59 -7
  80. package/src/channels/adapters/telegram-bot.ts +18 -5
  81. package/src/channels/adapters/webex-bot.ts +8 -3
  82. package/src/channels/adapters/webex.ts +8 -3
  83. package/src/channels/fetch-attachment.ts +43 -0
  84. package/src/{bundled-plugins/github-cli-auth/approve-idempotency.ts → channels/github-review-verdict-coordinator.ts} +25 -1
  85. package/src/channels/github-token-bridge.ts +10 -3
  86. package/src/channels/manager.ts +9 -0
  87. package/src/channels/router.ts +248 -6
  88. package/src/channels/types.ts +28 -1
  89. package/src/cli/channel.ts +1 -1
  90. package/src/cli/init.ts +1 -1
  91. package/src/cli/model.ts +57 -7
  92. package/src/compose/stop.ts +17 -5
  93. package/src/config/config.ts +6 -6
  94. package/src/config/models-mutation.ts +13 -1
  95. package/src/config/providers.ts +176 -0
  96. package/src/container/start.ts +49 -10
  97. package/src/doctor/checks.ts +3 -1
  98. package/src/doctor/commit.ts +2 -1
  99. package/src/doctor/file-ownership.ts +52 -0
  100. package/src/dreams/git.ts +2 -1
  101. package/src/git/hookless.ts +5 -0
  102. package/src/git/reconcile-ignored.ts +18 -5
  103. package/src/git/secret-history.ts +371 -0
  104. package/src/git/system-commit.ts +12 -6
  105. package/src/init/dockerfile.ts +86 -5
  106. package/src/init/index.ts +17 -5
  107. package/src/init/models-dev.ts +4 -0
  108. package/src/init/validate-api-key.ts +2 -0
  109. package/src/mcp/tools.ts +16 -3
  110. package/src/permissions/builtins.ts +3 -1
  111. package/src/plugin/context.ts +2 -0
  112. package/src/plugin/index.ts +1 -0
  113. package/src/plugin/manager.ts +4 -0
  114. package/src/plugin/types.ts +21 -0
  115. package/src/run/index.ts +40 -0
  116. package/src/run/llm-fetch-observer.ts +41 -4
  117. package/src/sandbox/build.ts +37 -15
  118. package/src/sandbox/canonical-secrets.ts +18 -0
  119. package/src/sandbox/env-exposure.ts +80 -0
  120. package/src/sandbox/errors.ts +13 -6
  121. package/src/sandbox/hidden-paths.ts +102 -44
  122. package/src/sandbox/index.ts +22 -4
  123. package/src/sandbox/package-install.ts +3 -27
  124. package/src/sandbox/policy.ts +11 -25
  125. package/src/sandbox/privileged-runtime.ts +255 -0
  126. package/src/sandbox/session-tmp.ts +8 -2
  127. package/src/sandbox/writable-zones.ts +204 -140
  128. package/src/secrets/index.ts +8 -0
  129. package/src/secrets/refresh-provider-oauth.ts +128 -0
  130. package/src/server/command-runner.ts +48 -4
  131. package/src/server/index.ts +4 -0
  132. package/src/skills/typeclaw-channel-github/SKILL.md +49 -56
  133. package/src/skills/typeclaw-claude-code/SKILL.md +24 -60
  134. package/src/skills/typeclaw-claude-code/references/auth-flow.md +17 -158
  135. package/src/skills/typeclaw-codex-cli/SKILL.md +19 -49
  136. package/src/skills/typeclaw-codex-cli/references/auth-flow.md +17 -154
  137. package/src/skills/typeclaw-config/SKILL.md +5 -5
  138. package/src/skills/typeclaw-config/references/recommended-mounts.md +24 -24
  139. package/src/skills/typeclaw-github-contributing/SKILL.md +23 -26
  140. package/src/skills/typeclaw-memory/SKILL.md +9 -3
  141. package/src/skills/typeclaw-permissions/SKILL.md +19 -15
  142. 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
@@ -54,6 +55,36 @@ const TRANSPORT_FAILURE =
54
55
  const AUTH_FAULT =
55
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
56
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
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
59
90
  // specific: a miss falls through to GENERIC_SAFE_NOTICE rather than echoing raw
@@ -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,7 +163,7 @@ 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
 
@@ -130,6 +177,10 @@ export function isThrottleOrOverload(raw: string): boolean {
130
177
  return THROTTLE_OR_OVERLOAD.test(raw)
131
178
  }
132
179
 
180
+ export function isObserverTtfbTimeout(raw: string): boolean {
181
+ return OBSERVER_TIMEOUT.test(raw) && OBSERVER_TTFB_TIMEOUT.test(raw)
182
+ }
183
+
133
184
  // Failover predicate for turn-drivers' `shouldFailover`: rotate to the next model
134
185
  // ref on a transient capacity signal (throttle/overload), an observer stall
135
186
  // timeout, or a transport/session failure. A stall or a dropped session is as
@@ -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>
@@ -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[]
@@ -22,6 +22,16 @@ export type RunSubagentDrainOptions = {
22
22
  // Cooperative cancellation: when this returns true the loop stops re-prompting
23
23
  // and returns, letting the caller's timeout/abort path dispose the session.
24
24
  cancelled?: () => boolean
25
+ // Wall-clock ceiling on how long a single background child may stay `running`
26
+ // before the drain gives up on it. A child without its own `timeoutMs` can
27
+ // wedge forever (a hung `session.prompt`), and the drain would otherwise wait
28
+ // on it indefinitely — stranding the parent's whole report. When a child
29
+ // exceeds this, we abort it and record a timeout completion so its reminder is
30
+ // delivered and the loop can reach its fixed point with partial results.
31
+ // Undefined keeps the legacy unbounded behavior.
32
+ maxChildWaitMs?: number
33
+ // Injectable clock + abort-await seam for tests; production uses real time.
34
+ now?: () => number
25
35
  }
26
36
 
27
37
  // Re-prompts a subagent with its children's completion reminders until a fixed
@@ -35,16 +45,22 @@ export type RunSubagentDrainOptions = {
35
45
  // "spawned nothing" flag is needed. The watch MUST have been started before the
36
46
  // initial prompt (see `beginSubagentDrainWatch`) to close the lost-wakeup race.
37
47
  export async function runSubagentDrain(watch: SubagentDrainWatch, options: RunSubagentDrainOptions): Promise<void> {
38
- const { drain, prompt, cancelled } = options
48
+ const { drain, prompt, cancelled, maxChildWaitMs, now = Date.now } = options
39
49
  const delivered = new Set<string>()
40
50
  try {
41
51
  while (cancelled === undefined || !cancelled()) {
52
+ expireOverdueChildren(drain, maxChildWaitMs, now)
42
53
  const pending = collectPendingReminders(drain, delivered)
43
54
  if (pending.length === 0) {
44
55
  if (!hasRunningChildren(drain)) return
45
56
  // Children still running but none newly completed: wait for the next
46
- // wakeup, then re-derive from the registry.
47
- const woke = await watch.waitForWakeup()
57
+ // wakeup, then re-derive. A `maxChildWaitMs` bounds this wait (via a
58
+ // timer) so a child that never broadcasts still gets expired next
59
+ // iteration. `waitForWakeup` returns true on a completion OR a timer
60
+ // expiry, and false ONLY when the watch is stopped — which must always
61
+ // terminate the loop, else a stopped watch with a still-running child
62
+ // spins synchronously forever.
63
+ const woke = await watch.waitForWakeup(nextExpiryDelayMs(drain, maxChildWaitMs, now))
48
64
  if (!woke) return
49
65
  continue
50
66
  }
@@ -59,6 +75,64 @@ export async function runSubagentDrain(watch: SubagentDrainWatch, options: RunSu
59
75
  }
60
76
  }
61
77
 
78
+ // Records a timeout completion (then fires abort) for any background child that
79
+ // has been `running` past the ceiling. Recording a (failed) completion is what
80
+ // lets the child surface as a delivered reminder and drop out of
81
+ // `hasRunningChildren`, so the loop reaches its fixed point with partial results
82
+ // rather than hanging on a wedged child. Synchronous by design — see the
83
+ // record-before-abort note inside.
84
+ function expireOverdueChildren(
85
+ drain: SubagentBackgroundDrain,
86
+ maxChildWaitMs: number | undefined,
87
+ now: () => number,
88
+ ): void {
89
+ if (maxChildWaitMs === undefined) return
90
+ const deadline = now() - maxChildWaitMs
91
+ for (const child of drain.liveRegistry.list({ parentSessionId: drain.sessionId })) {
92
+ if (child.background !== true || child.status !== 'running') continue
93
+ if (child.startedAt > deadline) continue
94
+ const durationMs = now() - child.startedAt
95
+ const error = `subagent ${child.subagentName} exceeded the ${maxChildWaitMs}ms drain wait and was abandoned`
96
+ // Claim the settlement BEFORE aborting. If the child's real completion
97
+ // already won, skip — no double-settle, no broadcast. Awaiting abort here
98
+ // would be the bug the ceiling exists to prevent: a wedged `session.abort()`
99
+ // that never reaches idle would hang the drain, so fire-and-forget instead.
100
+ // Logical settlement can precede physical teardown; startSubagent still
101
+ // disposes the session when its own work settles.
102
+ if (!drain.liveRegistry.recordCompletionIfRunning(child.taskId, { ok: false, durationMs, error })) continue
103
+ drain.stream.publish({
104
+ target: { kind: 'broadcast' },
105
+ payload: {
106
+ kind: 'subagent.completed',
107
+ taskId: child.taskId,
108
+ subagent: child.subagentName,
109
+ parentSessionId: drain.sessionId,
110
+ ok: false,
111
+ durationMs,
112
+ error,
113
+ },
114
+ })
115
+ void child.abort().catch(() => {})
116
+ }
117
+ }
118
+
119
+ // The soonest a still-running child will cross the ceiling, so waitForWakeup can
120
+ // wake the loop to expire it even if no completion broadcast ever arrives.
121
+ // Undefined when there is no ceiling or no running child (wait indefinitely).
122
+ function nextExpiryDelayMs(
123
+ drain: SubagentBackgroundDrain,
124
+ maxChildWaitMs: number | undefined,
125
+ now: () => number,
126
+ ): number | undefined {
127
+ if (maxChildWaitMs === undefined) return undefined
128
+ const running = drain.liveRegistry
129
+ .list({ parentSessionId: drain.sessionId })
130
+ .filter((c) => c.background === true && c.status === 'running')
131
+ if (running.length === 0) return undefined
132
+ const oldestStart = Math.min(...running.map((c) => c.startedAt))
133
+ return Math.max(0, oldestStart + maxChildWaitMs - now())
134
+ }
135
+
62
136
  type PendingReminder = { taskId: string; text: string }
63
137
 
64
138
  function collectPendingReminders(drain: SubagentBackgroundDrain, delivered: Set<string>): PendingReminder[] {
@@ -97,20 +171,47 @@ function hasRunningChildren(drain: SubagentBackgroundDrain): boolean {
97
171
  export type SubagentDrainWatch = {
98
172
  // Resolves true on a child-completion wakeup, false once stopped. A wakeup
99
173
  // that arrives before anyone waits is latched (pendingWake), so a completion
100
- // during the subagent's prompt is not lost.
101
- waitForWakeup: () => Promise<boolean>
174
+ // during the subagent's prompt is not lost. An optional `timeoutMs` resolves
175
+ // true when it elapses (a spurious wake) so the loop re-derives and can expire
176
+ // a child that never broadcast a completion.
177
+ waitForWakeup: (timeoutMs?: number) => Promise<boolean>
102
178
  stop: () => void
103
179
  }
104
180
 
105
- export function beginSubagentDrainWatch(drain: SubagentBackgroundDrain): SubagentDrainWatch {
181
+ // Injectable timer seam so tests can assert timer cancellation deterministically
182
+ // (a real setTimeout cancellation is invisible without racing the clock). `set`
183
+ // returns an opaque handle; `clear` cancels it. Production uses node timers.
184
+ export type TimerScheduler = {
185
+ set: (fn: () => void, ms: number) => unknown
186
+ clear: (handle: unknown) => void
187
+ }
188
+
189
+ const realTimerScheduler: TimerScheduler = {
190
+ set: (fn, ms) => setTimeout(fn, ms),
191
+ clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
192
+ }
193
+
194
+ export function beginSubagentDrainWatch(
195
+ drain: SubagentBackgroundDrain,
196
+ scheduler: TimerScheduler = realTimerScheduler,
197
+ ): SubagentDrainWatch {
106
198
  let stopped = false
107
199
  let pendingWake = false
108
200
  let resolveWaiter: ((woke: boolean) => void) | null = null
201
+ let waiterTimer: unknown = null
202
+
203
+ const clearWaiterTimer = (): void => {
204
+ if (waiterTimer !== null) {
205
+ scheduler.clear(waiterTimer)
206
+ waiterTimer = null
207
+ }
208
+ }
109
209
 
110
210
  const wake = (): void => {
111
211
  if (resolveWaiter !== null) {
112
212
  const r = resolveWaiter
113
213
  resolveWaiter = null
214
+ clearWaiterTimer()
114
215
  r(true)
115
216
  return
116
217
  }
@@ -125,7 +226,7 @@ export function beginSubagentDrainWatch(drain: SubagentBackgroundDrain): Subagen
125
226
  })
126
227
 
127
228
  return {
128
- waitForWakeup: () =>
229
+ waitForWakeup: (timeoutMs?: number) =>
129
230
  new Promise<boolean>((resolve) => {
130
231
  if (stopped) {
131
232
  resolve(false)
@@ -137,11 +238,20 @@ export function beginSubagentDrainWatch(drain: SubagentBackgroundDrain): Subagen
137
238
  return
138
239
  }
139
240
  resolveWaiter = resolve
241
+ if (timeoutMs !== undefined) {
242
+ waiterTimer = scheduler.set(() => {
243
+ if (resolveWaiter === null) return
244
+ resolveWaiter = null
245
+ waiterTimer = null
246
+ resolve(true)
247
+ }, timeoutMs)
248
+ }
140
249
  }),
141
250
  stop: () => {
142
251
  if (stopped) return
143
252
  stopped = true
144
253
  unsubscribe()
254
+ clearWaiterTimer()
145
255
  if (resolveWaiter !== null) {
146
256
  const r = resolveWaiter
147
257
  resolveWaiter = null