typeclaw 0.48.7 → 0.48.9

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 (108) hide show
  1. package/auth.schema.json +15 -1
  2. package/package.json +1 -1
  3. package/secrets.schema.json +15 -1
  4. package/src/agent/guard-types.ts +25 -0
  5. package/src/agent/guards.ts +102 -0
  6. package/src/agent/index.ts +33 -3
  7. package/src/agent/multimodal/read-redirect.ts +8 -9
  8. package/src/agent/plugin-tools.ts +283 -148
  9. package/src/agent/provider-error.ts +6 -1
  10. package/src/agent/reload-tool.ts +12 -5
  11. package/src/agent/retry-same-ref.ts +95 -36
  12. package/src/agent/session-origin.ts +13 -1
  13. package/src/agent/system-prompt.ts +14 -3
  14. package/src/agent/todo/continuation-policy.ts +3 -4
  15. package/src/agent/tool-file-safety.ts +36 -13
  16. package/src/agent/tools/channel-reply.ts +39 -2
  17. package/src/agent/tools/channel-send.ts +45 -2
  18. package/src/agent/tools/post-github-review.ts +31 -13
  19. package/src/agent/tools/spawn-subagent.ts +15 -0
  20. package/src/agent/tools/webfetch/inline-style-visibility.ts +2 -2
  21. package/src/agent/tools/webfetch/strategies/readability.ts +109 -10
  22. package/src/agent/turn-runner.ts +23 -19
  23. package/src/bundled-plugins/backup/git-auth.ts +7 -4
  24. package/src/bundled-plugins/backup/subagents.ts +1 -1
  25. package/src/bundled-plugins/bun-hygiene/README.md +23 -20
  26. package/src/bundled-plugins/bun-hygiene/index.ts +1 -7
  27. package/src/bundled-plugins/bun-hygiene/policy.ts +111 -35
  28. package/src/bundled-plugins/github-cli-auth/gh-review-detect.ts +44 -2
  29. package/src/bundled-plugins/github-cli-auth/gh-store.ts +733 -0
  30. package/src/bundled-plugins/github-cli-auth/git-askpass.ts +25 -0
  31. package/src/bundled-plugins/github-cli-auth/git-command.ts +209 -31
  32. package/src/bundled-plugins/github-cli-auth/git-credential-env.ts +151 -0
  33. package/src/bundled-plugins/github-cli-auth/index.ts +236 -38
  34. package/src/bundled-plugins/github-cli-auth/review-recorder.ts +5 -0
  35. package/src/bundled-plugins/guard/index.ts +2 -25
  36. package/src/bundled-plugins/guard/keys.ts +8 -0
  37. package/src/bundled-plugins/guard/policies/non-workspace-write.ts +7 -8
  38. package/src/bundled-plugins/guard/policy.ts +1 -7
  39. package/src/bundled-plugins/security/policies/git-exfil.ts +22 -30
  40. package/src/bundled-plugins/security/policies/outbound-secret-scan.ts +2 -4
  41. package/src/bundled-plugins/security/policies/private-surface-read.ts +8 -6
  42. package/src/bundled-plugins/security/policies/secret-exfil-bash.ts +2 -5
  43. package/src/bundled-plugins/security/policies/secret-exfil-read.ts +2 -4
  44. package/src/bundled-plugins/security/policies/session-search-secrets.ts +2 -4
  45. package/src/bundled-plugins/security/policies/system-prompt-leak.ts +2 -4
  46. package/src/bundled-plugins/security/policy.ts +0 -8
  47. package/src/channels/adapters/discord-bot-slash-commands.ts +22 -0
  48. package/src/channels/adapters/discord-bot.ts +2 -1
  49. package/src/channels/adapters/discord-classify.ts +16 -4
  50. package/src/channels/adapters/discord.ts +20 -8
  51. package/src/channels/adapters/github/dedup.ts +37 -8
  52. package/src/channels/adapters/github/inbound.ts +241 -46
  53. package/src/channels/adapters/github/review-state.ts +13 -9
  54. package/src/channels/adapters/github/review-thread-resolver.ts +52 -20
  55. package/src/channels/adapters/slack-bot.ts +13 -3
  56. package/src/channels/adapters/slack-classify.ts +40 -5
  57. package/src/channels/adapters/slack.ts +3 -9
  58. package/src/channels/adapters/teams.ts +8 -6
  59. package/src/channels/adapters/webex-bot-classify.ts +4 -33
  60. package/src/channels/adapters/webex-bot.ts +2 -4
  61. package/src/channels/adapters/webex-classify.ts +4 -33
  62. package/src/channels/adapters/webex-format.ts +36 -0
  63. package/src/channels/adapters/webex.ts +2 -4
  64. package/src/channels/continuation-willingness.ts +64 -39
  65. package/src/channels/github-rereview-guard.ts +20 -0
  66. package/src/channels/github-review-turn-ledger.ts +11 -1
  67. package/src/channels/github-review-verdict-coordinator.ts +475 -41
  68. package/src/channels/github-verdict-activity.ts +14 -5
  69. package/src/channels/manager.ts +17 -1
  70. package/src/channels/persistence.ts +89 -5
  71. package/src/channels/router.ts +1187 -254
  72. package/src/channels/types.ts +21 -5
  73. package/src/cli/compose-stats.ts +6 -7
  74. package/src/cli/compose-status.ts +6 -7
  75. package/src/cli/compose-usage.ts +6 -7
  76. package/src/cli/stats.ts +6 -7
  77. package/src/cli/status.ts +7 -8
  78. package/src/cli/ui.ts +4 -4
  79. package/src/container/start.ts +41 -1
  80. package/src/container/stop.ts +2 -1
  81. package/src/cron/consumer.ts +30 -9
  82. package/src/cron/scheduler.ts +24 -9
  83. package/src/doctor/channel-checks.ts +64 -0
  84. package/src/doctor/report.ts +8 -8
  85. package/src/dreams/render.ts +2 -2
  86. package/src/init/dockerfile.ts +8 -1
  87. package/src/inspect/render.ts +2 -2
  88. package/src/path-safety/real-intended-path.ts +14 -1
  89. package/src/permissions/permissions.ts +10 -2
  90. package/src/permissions/resolve.ts +8 -2
  91. package/src/plugin/core-tool-names.ts +15 -0
  92. package/src/plugin/hooks.ts +37 -3
  93. package/src/plugin/registry.ts +7 -3
  94. package/src/run/index.ts +33 -7
  95. package/src/sandbox/build.ts +39 -10
  96. package/src/sandbox/policy.ts +6 -2
  97. package/src/secrets/export-github-cli-store.ts +158 -0
  98. package/src/secrets/index.ts +19 -1
  99. package/src/secrets/provision-github-cli-store.ts +322 -0
  100. package/src/secrets/schema.ts +13 -7
  101. package/src/secrets/storage.ts +30 -0
  102. package/src/shared/index.ts +2 -0
  103. package/src/shared/style-text.ts +13 -0
  104. package/src/skills/typeclaw-channel-github/SKILL.md +24 -12
  105. package/src/skills/typeclaw-config/SKILL.md +3 -1
  106. package/src/skills/typeclaw-github-contributing/SKILL.md +6 -2
  107. package/src/skills/typeclaw-permissions/SKILL.md +11 -22
  108. package/src/usage/report.ts +3 -3
@@ -1,4 +1,7 @@
1
+ import { randomUUID } from 'node:crypto'
2
+
1
3
  import type { ReviewVerdict } from './github-review-turn-ledger'
4
+ import type { GithubReviewFollowupRound } from './types'
2
5
 
3
6
  // Raw latest-decisive state. DISMISSED is kept DISTINCT from NONE on purpose: a
4
7
  // genuine dismissal means a fresh same-verdict re-review is legitimate and must
@@ -25,21 +28,31 @@ export type HeadShaResolver = (target: { workspace: string; prNumber: number })
25
28
 
26
29
  export type ApproveBlock = {
27
30
  block: true
28
- kind: 'concurrent' | 'duplicate'
31
+ kind: 'concurrent' | 'duplicate' | 'round-ineligible'
29
32
  reason: string
30
33
  duplicateSource?: 'standing' | 'recent'
31
34
  leaseRetained?: boolean
32
35
  }
33
36
 
37
+ // What the reserved call actually published. `formal-landed` is a verified review
38
+ // on `/pulls/{n}/reviews`; `fallback-landed` is the PR-level comment a caller posts
39
+ // instead when a standing same verdict blocks the formal submit. Both are PR-level
40
+ // review publications and must arm the duplicate cooldown, but only the formal one
41
+ // may claim a verdict — hence an explicit outcome rather than a boolean `succeeded`,
42
+ // which could not tell the two landings apart.
43
+ export type ReviewOutputOutcome = 'failed' | 'formal-landed' | 'fallback-landed'
44
+
34
45
  export type ReviewVerdictGuard = {
35
46
  guard: (args: {
36
47
  callId: string
37
48
  workspace: string
38
49
  prNumber: number
39
50
  verdict: ReviewVerdict
51
+ round?: GithubReviewFollowupRound
52
+ thread?: string | null
40
53
  retainDuplicateLease?: boolean
41
54
  }) => Promise<ApproveBlock | null>
42
- release: (args: { callId: string; succeeded: boolean }) => Promise<void>
55
+ release: (args: { callId: string; outcome: ReviewOutputOutcome }) => Promise<void>
43
56
  // Arms the read-after-write lag shield for a verdict that landed WITHOUT a prior
44
57
  // guard() reservation. The pre-execution detector can miss a review-submission
45
58
  // command shape, so the verdict is only recovered post-hoc from the REST result
@@ -93,6 +106,10 @@ const CONCURRENT_REASON =
93
106
  'Another session in this agent is already submitting a formal review verdict for this pull request. ' +
94
107
  'Only one verdict may land per PR — do not submit a second review; the in-flight one will post.'
95
108
 
109
+ const ROUND_INELIGIBLE_REASON =
110
+ 'This review follow-up round assigned the formal verdict to another sibling thread session. ' +
111
+ 'Do not submit a formal verdict from this session; wait for the designated sibling verdict activity, then close out only this thread.'
112
+
96
113
  // The standing verdict a fresh attempt would duplicate. APPROVE duplicates a
97
114
  // standing APPROVED; REQUEST_CHANGES duplicates a standing CHANGES_REQUESTED.
98
115
  function duplicatesStanding(verdict: ReviewVerdict, effective: EffectiveVerdict): boolean {
@@ -114,6 +131,17 @@ function cooldownApplies(verdict: ReviewVerdict, effective: EffectiveVerdict): b
114
131
  // never strand a PR for long.
115
132
  const LEASE_TTL_MS = 5 * 60_000
116
133
 
134
+ // A review round spans human-paced sibling sessions and can legitimately take
135
+ // much longer than one command lease. Two hours leaves room for a careful PR
136
+ // re-review while still guaranteeing that an abandoned round cannot gate later
137
+ // verdicts indefinitely.
138
+ export const REVIEW_ROUND_TTL_MS = 2 * 60 * 60_000
139
+
140
+ // Reply fan-out only needs to cover one reviewer run, its prescribed retry,
141
+ // and carrier promotion; keeping it short prevents a later conversation about
142
+ // the same review from inheriting an abandoned gate.
143
+ export const REPLY_REVIEW_ROUND_TTL_MS = 30 * 60_000
144
+
117
145
  // How long a just-landed verdict suppresses a redundant same-verdict re-submit on
118
146
  // the same head — a duplicate-review cooldown. It started as a narrow lag shield
119
147
  // for GitHub's ~10-18s read-after-write lag (the original ~10-18s-apart duplicates
@@ -128,15 +156,17 @@ const LEASE_TTL_MS = 5 * 60_000
128
156
  // stays well under the lease TTL and short enough that a deliberate human-driven
129
157
  // re-approval of the identical commit is the only thing it can delay.
130
158
  const RECENT_LANDED_TTL_MS = 5 * 60_000
159
+ const COMPLETED_REPLY_REVIEW_ROUND_GRACE_MS = 5 * 60_000
131
160
 
132
161
  type Reservation = {
133
162
  key: string
134
163
  token: number
135
164
  createdAt: number
136
165
  headSha: string | null
137
- verdict: ReviewVerdict
166
+ verdict: ReviewVerdict | 'DISMISSED'
138
167
  workspace: string
139
168
  prNumber: number
169
+ roundKey?: string
140
170
  }
141
171
 
142
172
  // headSha === null is the UNCERTAINTY sentinel: the command succeeded but the head
@@ -156,8 +186,282 @@ type LandedVerdict = { verdict: ReviewVerdict; headSha: string | null; landedAt:
156
186
  const inFlightByPr = new Map<string, Reservation>()
157
187
  const reservationByCall = new Map<string, Reservation>()
158
188
  const recentLandedByPr = new Map<string, LandedVerdict>()
189
+ type ReviewRoundState = {
190
+ round: GithubReviewFollowupRound
191
+ status: 'pending' | 'completed'
192
+ createdAt: number
193
+ attemptedCarriers: Set<string | null>
194
+ dismissalAttempted: boolean
195
+ requestChangesAttempted: boolean
196
+ }
197
+ let reviewRounds = new Map<string, ReviewRoundState>()
198
+ let expiredReviewRoundKeys = new Set<string>()
199
+ type ReplyReviewRoundGeneration = { round: GithubReviewFollowupRound; createdAt: number }
200
+ let replyReviewRoundGenerations = new Map<string, ReplyReviewRoundGeneration>()
159
201
  let tokenSeq = 0
160
202
 
203
+ export function githubReviewRoundKey(round: GithubReviewFollowupRound): string {
204
+ return `${round.workspace}#${round.prNumber}#${round.headSha}#${round.roundId}`
205
+ }
206
+
207
+ export function registerOrJoinReplyReviewRound(input: {
208
+ workspace: string
209
+ prNumber: number
210
+ headSha: string
211
+ blockingReviewId: number
212
+ thread: string
213
+ now?: () => number
214
+ generateRoundId?: () => string
215
+ }): GithubReviewFollowupRound {
216
+ const now = input.now ?? Date.now
217
+ const currentTime = now()
218
+ const correlationKey = JSON.stringify([input.workspace, input.prNumber, input.headSha, input.blockingReviewId])
219
+ const existing = replyReviewRoundGenerations.get(correlationKey)
220
+ if (existing !== undefined) {
221
+ const state = activeReviewRoundState(githubReviewRoundKey(existing.round), now)
222
+ const completedGraceExpired =
223
+ state?.status === 'completed' && currentTime - existing.createdAt >= COMPLETED_REPLY_REVIEW_ROUND_GRACE_MS
224
+ if (state !== undefined && !completedGraceExpired) return existing.round
225
+ replyReviewRoundGenerations.delete(correlationKey)
226
+ }
227
+
228
+ const round: GithubReviewFollowupRound = {
229
+ kind: 'reply',
230
+ roundId: (input.generateRoundId ?? randomUUID)(),
231
+ workspace: input.workspace,
232
+ prNumber: input.prNumber,
233
+ headSha: input.headSha,
234
+ carrierThread: input.thread,
235
+ }
236
+ replyReviewRoundGenerations.set(correlationKey, { round, createdAt: currentTime })
237
+ registerGithubReviewRound(round, currentTime, now)
238
+ return round
239
+ }
240
+
241
+ export function registerGithubReviewRound(
242
+ round: GithubReviewFollowupRound,
243
+ createdAt = Date.now(),
244
+ now: () => number = Date.now,
245
+ ): GithubReviewFollowupRound | null {
246
+ const key = githubReviewRoundKey(round)
247
+ if (expiredReviewRoundKeys.has(key)) return null
248
+ for (const [candidateKey, state] of reviewRounds) {
249
+ if (activeReviewRoundState(candidateKey, now) === undefined) continue
250
+ if (candidateKey !== key && state.round.workspace === round.workspace && state.round.prNumber === round.prNumber) {
251
+ reviewRounds.delete(candidateKey)
252
+ }
253
+ }
254
+ const existing = activeReviewRoundState(key, now)
255
+ if (existing !== undefined) return existing.round
256
+ if (now() - createdAt >= reviewRoundTtlMs(round)) {
257
+ expiredReviewRoundKeys.add(key)
258
+ return null
259
+ }
260
+ reviewRounds.set(key, {
261
+ round,
262
+ status: 'pending',
263
+ createdAt,
264
+ attemptedCarriers: new Set([round.carrierThread]),
265
+ dismissalAttempted: false,
266
+ requestChangesAttempted: false,
267
+ })
268
+ return round
269
+ }
270
+
271
+ export function restoreGithubReviewRound(
272
+ round: GithubReviewFollowupRound,
273
+ status: ReviewRoundState['status'],
274
+ attemptedCarriers: readonly (string | null)[] = [round.carrierThread],
275
+ dismissalAttempted = false,
276
+ requestChangesAttempted = false,
277
+ createdAt = Date.now(),
278
+ ): GithubReviewFollowupRound | null {
279
+ const registered = registerGithubReviewRound(round, createdAt)
280
+ if (registered === null) return null
281
+ const key = githubReviewRoundKey(registered)
282
+ // Restoration is monotonic: a persisted `pending` record must never overwrite
283
+ // an unexpired round this process already completed. A sibling session that
284
+ // was idle-GC'd before completion still carries the stale status, and letting
285
+ // it regress would re-arm failover and permit a second blocking review.
286
+ // Expiry still wins — `activeReviewRoundState` drops the state first, so an
287
+ // expired round is never resurrected by a late restore.
288
+ const existing = activeReviewRoundState(key)
289
+ if (existing !== undefined && existing.status === 'completed' && status === 'pending') return registered
290
+ reviewRounds.set(key, {
291
+ round: registered,
292
+ status,
293
+ createdAt,
294
+ attemptedCarriers: new Set(attemptedCarriers),
295
+ dismissalAttempted,
296
+ requestChangesAttempted,
297
+ })
298
+ return registered
299
+ }
300
+
301
+ export function githubReviewRoundPersistence(round: GithubReviewFollowupRound): {
302
+ status: ReviewRoundState['status']
303
+ createdAt: number
304
+ attemptedCarriers: (string | null)[]
305
+ dismissalAttempted?: true
306
+ requestChangesAttempted?: true
307
+ } | null {
308
+ const state = activeReviewRoundState(githubReviewRoundKey(round))
309
+ if (state === undefined) return null
310
+ return {
311
+ status: state.status,
312
+ createdAt: state.createdAt,
313
+ attemptedCarriers: Array.from(state.attemptedCarriers),
314
+ ...(state.dismissalAttempted === true ? { dismissalAttempted: true as const } : {}),
315
+ ...(state.requestChangesAttempted === true ? { requestChangesAttempted: true as const } : {}),
316
+ }
317
+ }
318
+
319
+ export function forgetGithubReviewRound(round: GithubReviewFollowupRound): void {
320
+ reviewRounds.delete(githubReviewRoundKey(round))
321
+ }
322
+
323
+ export function completeGithubReviewRound(round: GithubReviewFollowupRound): void {
324
+ const key = githubReviewRoundKey(round)
325
+ let current = activeReviewRoundState(key)
326
+ if (current === undefined) {
327
+ const registered = registerGithubReviewRound(round)
328
+ if (registered === null) return
329
+ current = activeReviewRoundState(key)
330
+ if (current === undefined) return
331
+ }
332
+ reviewRounds.set(key, {
333
+ round: current.round,
334
+ status: 'completed',
335
+ createdAt: current.createdAt,
336
+ attemptedCarriers: current.attemptedCarriers,
337
+ dismissalAttempted: current.dismissalAttempted,
338
+ requestChangesAttempted: current.requestChangesAttempted,
339
+ })
340
+ }
341
+
342
+ export function isGithubReviewRoundComplete(round: GithubReviewFollowupRound): boolean {
343
+ return activeReviewRoundState(githubReviewRoundKey(round))?.status === 'completed'
344
+ }
345
+
346
+ export function promoteGithubReviewRound(
347
+ round: GithubReviewFollowupRound,
348
+ carrierThread: string | null,
349
+ ): GithubReviewFollowupRound | null {
350
+ const key = githubReviewRoundKey(round)
351
+ const current = activeReviewRoundState(key)
352
+ if (current === undefined || current.status === 'completed') return null
353
+ const active = current.round
354
+ if (active.carrierThread !== round.carrierThread) return null
355
+ if (current.attemptedCarriers.has(carrierThread)) return null
356
+ const promoted = { ...active, carrierThread }
357
+ const attemptedCarriers = new Set(current.attemptedCarriers)
358
+ attemptedCarriers.add(carrierThread)
359
+ reviewRounds.set(key, {
360
+ round: promoted,
361
+ status: 'pending',
362
+ createdAt: current.createdAt,
363
+ attemptedCarriers,
364
+ dismissalAttempted: current.dismissalAttempted,
365
+ requestChangesAttempted: current.requestChangesAttempted,
366
+ })
367
+ return promoted
368
+ }
369
+
370
+ export function canPromoteGithubReviewRoundTo(round: GithubReviewFollowupRound, thread: string | null): boolean {
371
+ const current = activeReviewRoundState(githubReviewRoundKey(round))
372
+ return current !== undefined && current.status !== 'completed' && !current.attemptedCarriers.has(thread)
373
+ }
374
+
375
+ export async function validateGithubReviewRound(
376
+ round: GithubReviewFollowupRound,
377
+ createdAt?: number,
378
+ ): Promise<boolean> {
379
+ if (createdAt !== undefined && Date.now() - createdAt >= reviewRoundTtlMs(round)) return false
380
+ if (expiredReviewRoundKeys.has(githubReviewRoundKey(round))) return false
381
+ const currentHead = await processHeadShaResolver({ workspace: round.workspace, prNumber: round.prNumber })
382
+ return currentHead !== null && currentHead === round.headSha
383
+ }
384
+
385
+ export async function guardGithubReviewRoundDismissal(args: {
386
+ callId: string
387
+ workspace: string
388
+ prNumber: number
389
+ round?: GithubReviewFollowupRound
390
+ thread?: string | null
391
+ }): Promise<ApproveBlock | null> {
392
+ const blocked = await evaluateRoundEligibility(args, processHeadShaResolver)
393
+ if (blocked !== null) return blocked
394
+ if (args.round === undefined) return null
395
+
396
+ const roundKey = githubReviewRoundKey(args.round)
397
+ const roundState = activeReviewRoundState(roundKey)
398
+ if (roundState === undefined) return null
399
+ if (roundState?.dismissalAttempted === true) {
400
+ return { block: true, kind: 'round-ineligible', reason: ROUND_INELIGIBLE_REASON }
401
+ }
402
+
403
+ const key = prKey(args.workspace, args.prNumber)
404
+ const held = inFlightByPr.get(key)
405
+ if (held !== undefined && Date.now() - held.createdAt < LEASE_TTL_MS) {
406
+ return { block: true, kind: 'concurrent', reason: CONCURRENT_REASON }
407
+ }
408
+ const reservation: Reservation = {
409
+ key,
410
+ token: ++tokenSeq,
411
+ createdAt: Date.now(),
412
+ headSha: args.round.headSha,
413
+ verdict: 'DISMISSED',
414
+ workspace: args.workspace,
415
+ prNumber: args.prNumber,
416
+ roundKey,
417
+ }
418
+ inFlightByPr.set(key, reservation)
419
+ reservationByCall.set(args.callId, reservation)
420
+ if (roundState !== undefined) roundState.dismissalAttempted = true
421
+ return null
422
+ }
423
+
424
+ export function releaseGithubReviewRoundDismissal(callId: string, attempted = true): void {
425
+ const reservation = reservationByCall.get(callId)
426
+ if (reservation?.verdict !== 'DISMISSED') return
427
+ if (!attempted && reservation.roundKey !== undefined) {
428
+ const state = activeReviewRoundState(reservation.roundKey)
429
+ if (state !== undefined) state.dismissalAttempted = false
430
+ }
431
+ releaseReservation(callId, reservation)
432
+ }
433
+
434
+ export function hasGithubReviewRoundDismissalAttempt(round: GithubReviewFollowupRound): boolean {
435
+ return activeReviewRoundState(githubReviewRoundKey(round))?.dismissalAttempted === true
436
+ }
437
+
438
+ export function resetGithubReviewRoundCompletion(round: GithubReviewFollowupRound): void {
439
+ const state = activeReviewRoundState(githubReviewRoundKey(round))
440
+ if (state === undefined || state.status === 'completed') return
441
+ // A verified mutation may outlive its publishing session or hit a transient
442
+ // head read before the observer can record completion. Release operation
443
+ // latches so the carrier can retry and failover remains available instead of
444
+ // leaving the pending round permanently stranded.
445
+ state.dismissalAttempted = false
446
+ state.requestChangesAttempted = false
447
+ }
448
+
449
+ export function resetGithubReviewRoundCompletionForPr(
450
+ workspace: string,
451
+ prNumber: number,
452
+ ): GithubReviewFollowupRound | null {
453
+ expireReviewRounds()
454
+ const state = Array.from(reviewRounds.values()).find(
455
+ (candidate) =>
456
+ candidate.status === 'pending' &&
457
+ candidate.round.workspace === workspace &&
458
+ candidate.round.prNumber === prNumber,
459
+ )
460
+ if (state === undefined) return null
461
+ resetGithubReviewRoundCompletion(state.round)
462
+ return state.round
463
+ }
464
+
161
465
  // Makes a formal `gh ... event=APPROVE|REQUEST_CHANGES` idempotent per PR across
162
466
  // turns, sessions, and (in-process) concurrent fan-out. Three layers, in order:
163
467
  //
@@ -180,8 +484,9 @@ let tokenSeq = 0
180
484
  // second engagement turn ~10s later starts after the first's lease released,
181
485
  // and GitHub's reviews list still lags the write (reports NONE). A short-lived
182
486
  // `recentLandedByPr` record — same verdict + (same OR uncertain head), written
183
- // on a succeeded release, RECENT_LANDED_TTL_MS — disambiguates "NONE because
184
- // lag" from "NONE because genuinely absent": only the former blocks. The head
487
+ // on any landed release (formal or fallback), RECENT_LANDED_TTL_MS —
488
+ // disambiguates "NONE because lag" from "NONE because genuinely absent": only
489
+ // the former blocks. The head
185
490
  // is re-resolved at release time; if the PR head advanced during the submit the
186
491
  // record stores a null head (uncertainty), which matches the current head so a
187
492
  // push-during-review cannot leak a duplicate. Because it fires after a raw
@@ -202,8 +507,17 @@ export function createApproveIdempotencyGuard(deps: {
202
507
  return {
203
508
  async guard(args): Promise<ApproveBlock | null> {
204
509
  if (args.verdict !== 'APPROVE' && args.verdict !== 'REQUEST_CHANGES') return null
510
+ expireRecentLanded(now)
511
+ const blocked = await evaluateRoundEligibility(args, deps.resolveHeadSha ?? processHeadShaResolver, now)
512
+ if (blocked !== null) return blocked
205
513
  const key = prKey(args.workspace, args.prNumber)
206
514
 
515
+ const roundState =
516
+ args.round === undefined ? undefined : activeReviewRoundState(githubReviewRoundKey(args.round), now)
517
+ if (args.verdict === 'REQUEST_CHANGES' && roundState?.requestChangesAttempted === true) {
518
+ return { block: true, kind: 'round-ineligible', reason: ROUND_INELIGIBLE_REASON }
519
+ }
520
+
207
521
  // Reserve BEFORE the await so two calls racing into guard() for the same PR
208
522
  // cannot both observe an empty map: the loser sees the winner's in-flight
209
523
  // lease and is blocked. An expired lease (tool.after never fired) is
@@ -220,9 +534,11 @@ export function createApproveIdempotencyGuard(deps: {
220
534
  verdict: args.verdict,
221
535
  workspace: args.workspace,
222
536
  prNumber: args.prNumber,
537
+ ...(roundState !== undefined ? { roundKey: githubReviewRoundKey(roundState.round) } : {}),
223
538
  }
224
539
  inFlightByPr.set(key, reservation)
225
540
  reservationByCall.set(args.callId, reservation)
541
+ if (args.verdict === 'REQUEST_CHANGES' && roundState !== undefined) roundState.requestChangesAttempted = true
226
542
 
227
543
  // Resolve the head SHA only AFTER the lease is held, so this await cannot
228
544
  // widen the reserve-before-await race the lease closes above.
@@ -230,42 +546,41 @@ export function createApproveIdempotencyGuard(deps: {
230
546
  reservation.headSha = headSha
231
547
 
232
548
  // Layer 2: GitHub is the authoritative, sole source of truth for a standing
233
- // verdict. A standing same verdict is a real duplicate; DISMISSED and the
234
- // opposite decisive verdict are genuine supersessions that must pass here
235
- // (the 35287f99 invariant). A read error fails OPEN.
549
+ // verdict. A standing same verdict is a real duplicate except for the one
550
+ // carrier REQUEST_CHANGES required to complete a new-head follow-up round;
551
+ // DISMISSED and the opposite decisive verdict are genuine supersessions
552
+ // that must pass here (the 35287f99 invariant). A read error fails OPEN.
236
553
  const remote = await deps.resolveEffectiveApproval({ workspace: args.workspace, prNumber: args.prNumber })
237
- if (remote.ok && duplicatesStanding(args.verdict, remote.effective)) {
238
- // Standing verdict upstream already matches. Block, and release the lease
239
- // now: a blocked command never reaches tool.after, so release() won't run
240
- // for this callId. Leaving the lease set would resurrect the strand bug —
241
- // the GitHub read is authoritative for the standing case.
242
- if (args.retainDuplicateLease !== true) releaseReservation(args.callId, reservation)
243
- return {
244
- block: true,
245
- kind: 'duplicate',
246
- reason: duplicateReason(args.verdict),
247
- duplicateSource: 'standing',
248
- ...(args.retainDuplicateLease === true ? { leaseRetained: true } : {}),
249
- }
250
- }
554
+ const allowedRoundSameStateRequest =
555
+ args.verdict === 'REQUEST_CHANGES' &&
556
+ roundState !== undefined &&
557
+ remote.ok &&
558
+ remote.effective === 'CHANGES_REQUESTED'
251
559
 
252
560
  // Layer 3 — duplicate-review cooldown. A recently-landed SAME verdict on the
253
- // SAME (or uncertain) head blocks a redundant re-submit for the window. It
561
+ // SAME (or uncertain) head blocks a redundant re-publication for the window. It
254
562
  // fires on a bare NONE (read-after-write lag, the original shield) AND on the
255
563
  // now-indexed SAME standing verdict (the PR #1042 fan-out, where siblings fired
256
- // minutes apart after indexing) — `duplicatesStanding` above already returned
257
- // here for that case, so reaching this line on a same-standing-verdict means
258
- // only that the lease-released duplicate is being re-tried; either way the
259
- // cooldown holds. It must NOT fire on a DISMISSED or the opposite decisive
260
- // verdict: those are genuine supersessions, so the cooldown is gated to the
261
- // ambiguous states (NONE, or the same standing verdict) and skipped for any
262
- // decisive state that contradicts a redundant re-submit. A read error skips it
263
- // (fails open) so a transient failure cannot strand a re-verdict.
564
+ // minutes apart, each after GitHub had already indexed the prior). It must NOT
565
+ // fire on a DISMISSED or the opposite decisive verdict: those are genuine
566
+ // supersessions, so the cooldown is gated to the ambiguous states (NONE, or the
567
+ // same standing verdict) and skipped for any decisive state that contradicts a
568
+ // redundant re-submit. A read error skips it (fails open) so a transient failure
569
+ // cannot strand a re-verdict.
570
+ //
571
+ // This is checked BEFORE the standing block below, and the order is load-bearing.
572
+ // `standing` is the one block a caller may answer by publishing a PR-level
573
+ // fallback comment instead, so a `standing` verdict on a PR that already got that
574
+ // comment would let every sibling thread session publish its own copy, which is
575
+ // how one PR collected two full reviews. Reporting `recent` here denies the whole publication
576
+ // instead, which is the accurate answer once a same-verdict output already landed.
264
577
  if (
578
+ !allowedRoundSameStateRequest &&
265
579
  remote.ok &&
266
580
  cooldownApplies(args.verdict, remote.effective) &&
267
581
  recentlyLandedSame(key, args.verdict, headSha, now)
268
582
  ) {
583
+ resetRoundRequestChangesAttempt(reservation)
269
584
  releaseReservation(args.callId, reservation)
270
585
  return {
271
586
  block: true,
@@ -275,6 +590,24 @@ export function createApproveIdempotencyGuard(deps: {
275
590
  }
276
591
  }
277
592
 
593
+ if (remote.ok && duplicatesStanding(args.verdict, remote.effective) && !allowedRoundSameStateRequest) {
594
+ // Standing verdict upstream already matches. Block, and release the lease
595
+ // now: a blocked command never reaches tool.after, so release() won't run
596
+ // for this callId. Leaving the lease set would resurrect the strand bug —
597
+ // the GitHub read is authoritative for the standing case.
598
+ if (args.retainDuplicateLease !== true) {
599
+ resetRoundRequestChangesAttempt(reservation)
600
+ releaseReservation(args.callId, reservation)
601
+ }
602
+ return {
603
+ block: true,
604
+ kind: 'duplicate',
605
+ reason: duplicateReason(args.verdict),
606
+ duplicateSource: 'standing',
607
+ ...(args.retainDuplicateLease === true ? { leaseRetained: true } : {}),
608
+ }
609
+ }
610
+
278
611
  return null
279
612
  },
280
613
 
@@ -282,17 +615,27 @@ export function createApproveIdempotencyGuard(deps: {
282
615
  const reservation = reservationByCall.get(args.callId)
283
616
  if (reservation === undefined) return
284
617
  try {
285
- // The pre-submit head can go stale: if the PR head advanced between the
286
- // guard() capture and the review landing, GitHub attaches the review to the
287
- // NEWER head while reservation.headSha holds the older one. Re-resolve the
288
- // head AFTER a successful submit and store what we can prove: the resolved
289
- // head only when pre==post, else the null uncertainty sentinel (matches any
290
- // current head for the lag window) so a push-during-review cannot let a
291
- // same-verdict duplicate slip past on the new head. The lease stays held
292
- // across this await (finally below), so the window is not reopened.
293
- if (args.succeeded && reservation.headSha !== null) {
618
+ // A FORMAL review's pre-submit head can go stale: if the PR head advanced
619
+ // between the guard() capture and the review landing, GitHub attaches the
620
+ // review to the NEWER head while reservation.headSha holds the older one.
621
+ // Re-resolve the head AFTER a successful submit and store what we can prove:
622
+ // the resolved head only when pre==post, else the null uncertainty sentinel
623
+ // (matches any current head for the lag window) so a push-during-review
624
+ // cannot let a same-verdict duplicate slip past on the new head. The lease
625
+ // stays held across this await (finally below), so the window is not reopened.
626
+ //
627
+ // A FALLBACK comment has no such ambiguity and must NOT take the sentinel.
628
+ // It is an issue comment, which GitHub associates with no head at all, and
629
+ // its body was written for reservation.headSha. Storing the sentinel for it
630
+ // would make a push landing mid-delivery shadow EVERY head, so the first
631
+ // genuine review of the new head would be denied as `recent` — an
632
+ // over-broad guard blocking real work. Pin it to the head it was written for.
633
+ if (args.outcome !== 'failed' && reservation.headSha !== null && reservation.verdict !== 'DISMISSED') {
294
634
  const postHeadSha =
295
- (await deps.resolveHeadSha?.({ workspace: reservation.workspace, prNumber: reservation.prNumber })) ?? null
635
+ args.outcome === 'fallback-landed'
636
+ ? reservation.headSha
637
+ : ((await deps.resolveHeadSha?.({ workspace: reservation.workspace, prNumber: reservation.prNumber })) ??
638
+ null)
296
639
  const landedHeadSha = postHeadSha !== null && postHeadSha === reservation.headSha ? postHeadSha : null
297
640
  recentLandedByPr.set(reservation.key, {
298
641
  verdict: reservation.verdict,
@@ -301,6 +644,7 @@ export function createApproveIdempotencyGuard(deps: {
301
644
  })
302
645
  }
303
646
  } finally {
647
+ if (args.outcome !== 'formal-landed') resetRoundRequestChangesAttempt(reservation)
304
648
  releaseReservation(args.callId, reservation)
305
649
  }
306
650
  },
@@ -321,6 +665,56 @@ export function createApproveIdempotencyGuard(deps: {
321
665
  }
322
666
  }
323
667
 
668
+ async function evaluateRoundEligibility(
669
+ args: {
670
+ workspace: string
671
+ prNumber: number
672
+ round?: GithubReviewFollowupRound
673
+ thread?: string | null
674
+ },
675
+ resolveHeadSha: HeadShaResolver,
676
+ now: () => number = Date.now,
677
+ ): Promise<ApproveBlock | null> {
678
+ expireReviewRounds(now)
679
+ const pendingRoundForPr = Array.from(reviewRounds.values()).find(
680
+ (state) =>
681
+ state.status === 'pending' &&
682
+ state.round.kind === 'push' &&
683
+ state.round.workspace === args.workspace &&
684
+ state.round.prNumber === args.prNumber,
685
+ )
686
+ // Pushes invalidate the whole PR's prior verdict, so their round legitimately
687
+ // owns every verdict attempt until one sibling carries it. Reply rounds only
688
+ // coordinate the stamped siblings answering one blocking review: their
689
+ // non-carriers are rejected below, while unrelated round-less sessions remain
690
+ // covered by the in-flight, standing, and recent-landing duplicate guards.
691
+ if (args.round === undefined) {
692
+ return pendingRoundForPr === undefined
693
+ ? null
694
+ : { block: true, kind: 'round-ineligible', reason: ROUND_INELIGIBLE_REASON }
695
+ }
696
+ if (args.round.workspace !== args.workspace || args.round.prNumber !== args.prNumber) {
697
+ if (expiredReviewRoundKeys.has(githubReviewRoundKey(args.round))) return null
698
+ return { block: true, kind: 'round-ineligible', reason: ROUND_INELIGIBLE_REASON }
699
+ }
700
+ const roundKey = githubReviewRoundKey(args.round)
701
+ if (expiredReviewRoundKeys.has(roundKey)) return null
702
+ const existing = activeReviewRoundState(roundKey, now)
703
+ const activeRound = existing?.round ?? args.round
704
+ if (existing?.status === 'completed' || activeRound.carrierThread !== (args.thread ?? null)) {
705
+ return { block: true, kind: 'round-ineligible', reason: ROUND_INELIGIBLE_REASON }
706
+ }
707
+ const currentRoundHead = await resolveHeadSha({
708
+ workspace: activeRound.workspace,
709
+ prNumber: activeRound.prNumber,
710
+ })
711
+ if (currentRoundHead === null || currentRoundHead !== activeRound.headSha) {
712
+ return { block: true, kind: 'round-ineligible', reason: ROUND_INELIGIBLE_REASON }
713
+ }
714
+ registerGithubReviewRound(activeRound, now())
715
+ return null
716
+ }
717
+
324
718
  // True only when a recently-landed record proves the GitHub NONE is read lag: same
325
719
  // verdict, within the window, AND the heads agree. Head agreement holds when the
326
720
  // stored head equals the current head, OR the stored head is the null uncertainty
@@ -347,15 +741,55 @@ function releaseReservation(callId: string, reservation: Reservation): void {
347
741
  }
348
742
  }
349
743
 
744
+ function resetRoundRequestChangesAttempt(reservation: Reservation): void {
745
+ if (reservation.verdict !== 'REQUEST_CHANGES' || reservation.roundKey === undefined) return
746
+ const state = activeReviewRoundState(reservation.roundKey)
747
+ if (state !== undefined && state.status === 'pending') state.requestChangesAttempted = false
748
+ }
749
+
350
750
  function prKey(workspace: string, prNumber: number): string {
351
751
  return `${workspace}#${prNumber}`
352
752
  }
353
753
 
754
+ function activeReviewRoundState(key: string, now: () => number = Date.now): ReviewRoundState | undefined {
755
+ const state = reviewRounds.get(key)
756
+ if (state === undefined) return undefined
757
+ if (now() - state.createdAt < reviewRoundTtlMs(state.round)) return state
758
+ reviewRounds.delete(key)
759
+ expiredReviewRoundKeys.add(key)
760
+ return undefined
761
+ }
762
+
763
+ function reviewRoundTtlMs(round: GithubReviewFollowupRound): number {
764
+ return round.kind === 'reply' ? REPLY_REVIEW_ROUND_TTL_MS : REVIEW_ROUND_TTL_MS
765
+ }
766
+
767
+ function expireReviewRounds(now: () => number = Date.now): void {
768
+ for (const key of reviewRounds.keys()) activeReviewRoundState(key, now)
769
+ }
770
+
771
+ // `recentlyLandedSame` only reports a miss on an expired record, so a PR that is
772
+ // reviewed once leaves an entry nothing ever reads or drops again — one dead record
773
+ // per PR for the life of the process. Sweeping on each guard bounds the map to PRs
774
+ // still inside the window, and only a process that keeps reviewing can grow it.
775
+ function expireRecentLanded(now: () => number): void {
776
+ for (const [key, landed] of recentLandedByPr) {
777
+ if (now() - landed.landedAt >= RECENT_LANDED_TTL_MS) recentLandedByPr.delete(key)
778
+ }
779
+ }
780
+
781
+ export function __recentLandedRecordCountForTest(): number {
782
+ return recentLandedByPr.size
783
+ }
784
+
354
785
  // Test-only: clear the process-wide lease state between cases.
355
786
  export function __resetReviewVerdictGuardForTest(): void {
356
787
  inFlightByPr.clear()
357
788
  reservationByCall.clear()
358
789
  recentLandedByPr.clear()
790
+ reviewRounds = new Map<string, ReviewRoundState>()
791
+ expiredReviewRoundKeys = new Set<string>()
792
+ replyReviewRoundGenerations = new Map<string, ReplyReviewRoundGeneration>()
359
793
  tokenSeq = 0
360
794
  processEffectiveResolver = async () => ({ ok: false })
361
795
  processHeadShaResolver = async () => null