typeclaw 0.23.0 → 0.25.0

package/src/channels/schema.ts

@@ -131,11 +131,27 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
   'pull_request_review.submitted',
 ] as const
 
+// Which pull_request webhook action triggers an agent code review. The two
+// event values are GitHub's bare PR action names (the `pull_request.` event
+// prefix is implied by this field living under the review config); `off` is the
+// disable sentinel, matching the `engagement.stickiness: 'off'` convention:
+//   - 'review_requested' — review only when the bot is requested (default)
+//   - 'opened'           — review every non-draft PR as soon as it opens; draft
+//                          PRs are skipped until an explicit review_requested
+//   - 'off'              — disable code review entirely
+export const GITHUB_REVIEW_ON_VALUES = ['review_requested', 'opened', 'off'] as const
+
+export type GithubReviewOn = (typeof GITHUB_REVIEW_ON_VALUES)[number]
+
+export const DEFAULT_GITHUB_REVIEW_ON: GithubReviewOn = 'review_requested'
+
 // PR-review policy knobs. Grouped under `review` so future toggles
-// (`requestChanges`, auto-review-on-request, severity thresholds) cluster
-// here instead of flattening onto the channel root.
+// (`requestChanges`, severity thresholds) cluster here instead of flattening
+// onto the channel root.
+//
+// `on` gates which pull_request action triggers a code review (see values above).
 //
-// `approve` gates whether the agent may submit a formal review with
+// `approve` gates *whether* the agent may submit a formal review with
 // `event: APPROVE`. When `false`, the adapter appends an operator-policy note
 // to inbounds and the `typeclaw-channel-github` skill downgrades an `approve`
 // verdict to a `COMMENT` review (findings still posted, no formal approval).
@@ -144,9 +160,10 @@ export const DEFAULT_GITHUB_EVENT_ALLOWLIST = [
 // temp file the command interceptor never sees.
 const githubReviewSchema = z
   .object({
+    on: z.enum(GITHUB_REVIEW_ON_VALUES).default(DEFAULT_GITHUB_REVIEW_ON),
     approve: z.boolean().default(true),
   })
-  .default({ approve: true })
+  .default({ on: DEFAULT_GITHUB_REVIEW_ON, approve: true })
 
 const githubChannelSchema = adapterSchema.extend({
   // Optional now (PR 2): when omitted and a `tunnels[]` entry with

package/src/channels/subagent-completion-bridge.ts

@@ -47,27 +47,23 @@ const consoleLogger: SubagentCompletionBridgeLogger = {
 // `LiveSession`, so the lookup is O(N) over live sessions with N small
 // (one per active conversation).
 //
-// On `no-live-session`, we silently drop. Three observable paths reach
-// this branch in production:
+// On `no-live-session`, we drop the reminder. When the parent was a
+// channel session, the broadcast now carries the channel-key coordinate
+// `{ adapter, workspace, chat, thread }`, and the router first tries to
+// reroute to the live successor session for that key — covering the two
+// common drop paths where the exact sessionId is gone but the
+// conversation lives on:
 //
 //   - The parent session was GC'd by the idle-eviction tick
 //     (SESSION_IDLE_MS) while the subagent was running.
 //   - The parent session rolled over (SESSION_FRESHNESS_TTL_MS) when a
-//     new inbound arrived during a long-running subagent — the channel
-//     conversation continues on the new sessionId, but the broadcast
-//     still carries the old one.
-//   - The parent was a TUI session (the TUI bridge in
-//     src/server/index.ts handles it).
+//     new inbound arrived during a long-running subagent.
 //
-// The right fix for the first two paths is for the broadcast to carry
-// the channel-key coordinate `{ adapter, workspace, chat, thread }` so
-// the bridge can fall back to "any live session for the same channel
-// key" when the exact sessionId no longer matches. That requires
-// extending the broadcast payload (consumed by TUI and channel paths)
-// and gating spawn_subagent to capture the origin coordinates — both
-// non-trivial. Deferred until we see this drop pattern in production
-// logs; the info log line below makes the case diagnosable from logs
-// alone.
+// A reminder still reaching this branch means there is no live session
+// for the key at all (the whole conversation went idle), or the parent
+// was a TUI session (handled by the TUI bridge in src/server/index.ts).
+// Logged at warn with the channel key so an undelivered completion is
+// diagnosable from logs alone.
 export function createSubagentCompletionBridge(options: SubagentCompletionBridgeOptions): SubagentCompletionBridge {
   const logger = options.logger ?? consoleLogger
   const unsubscribe = options.stream.subscribe({ target: { kind: 'broadcast' } }, (msg) => {
@@ -75,8 +71,12 @@ export function createSubagentCompletionBridge(options: SubagentCompletionBridge
     if (parsed === null) return
     const result = options.router.injectSubagentCompletionReminder(parsed)
     if (result.kind === 'no-live-session') {
-      logger.info(
-        `[channels] subagent-completion reminder dropped: no live session for parentSessionId=${parsed.parentSessionId} task=${parsed.taskId}`,
+      const keyInfo =
+        parsed.channelKey !== undefined
+          ? ` channelKey=${parsed.channelKey.adapter}:${parsed.channelKey.workspace}:${parsed.channelKey.chat}:${parsed.channelKey.thread ?? ''}`
+          : ''
+      logger.warn(
+        `[channels] subagent-completion reminder dropped: no live session for parentSessionId=${parsed.parentSessionId} task=${parsed.taskId}${keyInfo}`,
       )
     }
   })

package/src/channels/types.ts

@@ -52,6 +52,9 @@ export type InboundMessage = {
   chat: string
   thread: string | null
   text: string
+  // Prompt-only context for replied-to / quoted / linked messages. Kept out
+  // of `text` so the engagement gate sees only the human-authored body.
+  referenceContext?: InboundReferenceContext
   // Non-text attachments the user sent on this inbound. Empty / omitted
   // when the message is text-only. The router carries these through to
   // the live session's promptQueue/contextBuffer so channel tools can
@@ -94,6 +97,15 @@ export type InboundMessage = {
   // means "unknown" — the formatter renders such lines without a
   // timestamp prefix instead of stamping them with the wrong clock.
   ts: number
+  // Platform-native anchor for showing a typing/status indicator, kept
+  // SEPARATE from `thread` on purpose: `thread` drives reply threading,
+  // this drives ONLY the typing surface. Slack's `assistant.threads.
+  // setStatus` (the bot's only typing signal) requires a real message ts
+  // even in a flat DM, where `thread` is null because replies stay top-
+  // level. The classifier sets this to the inbound message ts for DMs so
+  // the status can render without forcing the reply into a thread. Omitted
+  // for non-DM inbounds, where the typing path falls back to `thread`.
+  typingThread?: string
   // Opaque, adapter-owned handle for the entity an emoji reaction would
   // attach to. The classifier stamps it because only there is the platform-
   // side target type still known (GitHub: issue body vs issue-comment vs
@@ -183,6 +195,10 @@ export type OutboundMessage = {
   // `uploadFile` does not accept a content body or a thread id, see the
   // adapter for the workaround details.
   attachments?: OutboundAttachment[]
+  // Typing-only anchor (see InboundMessage.typingThread), stamped by the
+  // router from the live session so the adapter can CLEAR the status after a
+  // flat DM send — where `thread` is null and would otherwise no-op the clear.
+  typingThread?: string
   // Set by the router (native render mode + anchor fired) so an adapter can
   // reply to the inbound it answers. Telegram/Discord consume `externalMessageId`;
   // `quote`-mode adapters never see this (the router prepends the blockquote into
@@ -207,6 +223,11 @@ export type QuoteAnchorSource = {
   text: string
 }
 
+export type InboundReferenceContext = {
+  kind: 'reply' | 'quote' | 'link'
+  sources: readonly QuoteAnchorSource[]
+}
+
 export type SendErrorCode =
   | 'duplicate'
   | 'turn-cap'
@@ -224,6 +245,10 @@ export type TypingTarget = {
   workspace: string
   chat: string
   thread?: string | null
+  // Typing-only anchor (see InboundMessage.typingThread). An adapter whose
+  // typing surface needs a message ts even when `thread` is null (Slack DMs)
+  // reads this first and falls back to `thread`. Never used for reply routing.
+  typingThread?: string
   // 'tick' is the heartbeat fired during debouncing/generation; adapters
   // should set the indicator visible. 'stop' is fired exactly once when the
   // router decides the turn is over (drain finally, /stop command, or
@@ -280,6 +305,7 @@ export type ChannelHistoryMessage = {
   authorId: string
   authorName: string
   text: string
+  referenceContext?: InboundReferenceContext
   attachments?: readonly InboundAttachment[]
   ts: number
   isBot: boolean
@@ -314,6 +340,48 @@ export type FetchAttachmentResult =
 
 export type FetchAttachmentCallback = (args: FetchAttachmentArgs) => Promise<FetchAttachmentResult>
 
-export function channelKeyId(key: ChannelKey): string {
+// A request to resolve (close out) a review-comment thread the bot itself
+// opened, after the author addressed it. Adapter-specific: only the github
+// adapter registers a resolver today. The router carries the request through
+// to that resolver, which is responsible for the platform-side authorship
+// check — `resolveReviewThread` MUST only close a thread whose root comment
+// the bot authored, never a human reviewer's thread. The address fields below
+// are the same ones a `channel_reply` origin carries: `workspace` is the repo
+// slug `owner/name`, `chat` is `pr:<N>`, and `rootCommentId` is the numeric id
+// of the thread's root comment (the `thread` value the inbound carried).
+export type ReviewThreadResolveRequest = {
+  adapter: AdapterId
+  workspace: string
+  chat: string
+  rootCommentId: string
+}
+
+// `already-resolved` is a success-shaped no-op: the thread was closed before we
+// got here (a duplicate turn, a manual resolve), so the desired end state holds
+// and the caller should treat it like `ok: true`. `not-author` is a hard
+// refusal: the root comment is not the bot's, so resolving would erase a
+// human's open question — the caller must NOT proceed as if it closed the loop.
+//
+// `no-match` is the ONLY non-blocking failure: the PR's threads listed cleanly
+// but none is rooted at this comment (already deleted, or the wrong target),
+// so there is genuinely nothing to close and an acknowledgement may still post.
+// Every other code is a hard failure — `not-found` here means an HTTP 404 from
+// the API (a real problem, e.g. wrong repo/PR), NOT "no such thread"; a caller
+// must treat it as blocking so it never claims a thread is settled on a failed
+// or misdirected lookup.
+export type ReviewThreadResolveResult =
+  | { ok: true; alreadyResolved?: boolean }
+  | {
+      ok: false
+      error: string
+      code?: 'not-author' | 'no-match' | 'not-found' | 'unsupported' | 'permission-denied' | 'transient'
+    }
+
+// Registered per-adapter on the ChannelRouter, last-write-wins like the
+// self-identity resolver (one bot account per adapter). Adapters that do not
+// support review threads never register one; the router answers `unsupported`.
+export type ReviewThreadResolver = (req: ReviewThreadResolveRequest) => Promise<ReviewThreadResolveResult>
+
+export function channelKeyId(key: { adapter: string; workspace: string; chat: string; thread: string | null }): string {
   return `${key.adapter}:${key.workspace}:${key.chat}:${key.thread ?? ''}`
 }

package/src/cli/inspect-controller.ts

@@ -1,11 +1,17 @@
-// Pure controller for the inspect CLI's esc/ctrl-c key dispatch.
-// Owns the AbortController lifecycle and the bare-ESC debounce timer,
-// independent of process.stdin / TTY raw mode (which is wired in src/cli/inspect.ts).
-// Extracted for testability: the lifecycle bug we want to pin is "armForStream's
-// signal must remain valid across pause()/resume() cycles" — verifying that without
-// a real TTY requires this seam.
+// Pure controller for the inspect CLI's esc/ctrl-c/quit key dispatch.
+// Owns the AbortController lifecycle and a VT-input parser, independent of
+// process.stdin / TTY raw mode (which is wired in src/cli/inspect.ts).
+//
+// Input is parsed byte-by-byte through a small escape-sequence state machine so
+// that arrow keys and other CSI/SS3 sequences can never be mistaken for a bare
+// ESC — regardless of how the bytes are split across 'data' events. The old
+// implementation used a 50ms wall-clock debounce to tell "ESC" from "ESC ["; on
+// a laggy SSH link the inter-byte gap of a single arrow key routinely exceeds
+// 50ms, so the leading ESC fired 'back' mid-keystroke and bounced the user out
+// of the viewer. The parser below makes CSI/SS3 always win, with a much longer
+// idle fallback used ONLY to resolve a genuinely-trailing bare ESC.
 
-export type EscChunkResult = { sigint: boolean }
+export type EscChunkResult = { sigint: boolean; quit: boolean }
 
 export type EscController = {
   armForStream: () => AbortSignal
@@ -14,15 +20,58 @@ export type EscController = {
   dispose: () => void
 }
 
+const ESC = 0x1b
+const CSI_INTRODUCER = 0x5b
+const SS3_INTRODUCER = 0x4f
+const CTRL_C = 0x03
+const QUIT_KEY = 0x71
+
+type ParseState = 'idle' | 'sawEsc' | 'csi' | 'ss3'
+
+// A CSI sequence ends at a final byte in 0x40..0x7e (e.g. arrow keys 'A'..'D',
+// '~' for nav keys, 'M'/'m' for mouse). Parameter/intermediate bytes (0x20..0x3f)
+// are consumed without ending it.
+function isCsiFinal(byte: number): boolean {
+  return byte >= 0x40 && byte <= 0x7e
+}
+
+// C0 controls (0x00..0x1f plus DEL 0x7f) are not legal sequence-body bytes.
+function isC0Control(byte: number): boolean {
+  return byte <= 0x1f || byte === 0x7f
+}
+
 export function createEscController({ debounceMs }: { debounceMs: number }): EscController {
   let currentCtrl: AbortController | null = null
+  let state: ParseState = 'idle'
   let pendingEsc: ReturnType<typeof setTimeout> | null = null
+  // A trailing ESC with no following byte cannot be proven "bare" without
+  // waiting. Use a generous idle window (>= debounceMs) so SSH-fragmented
+  // sequences whose continuation is still in flight are never misread.
+  const bareEscIdleMs = Math.max(debounceMs, 500)
 
   const clearPending = (): void => {
     if (pendingEsc !== null) {
       clearTimeout(pendingEsc)
       pendingEsc = null
     }
+    state = 'idle'
+  }
+
+  const scheduleBareEsc = (): void => {
+    if (pendingEsc !== null) clearTimeout(pendingEsc)
+    const ctrl = currentCtrl
+    pendingEsc = setTimeout(() => {
+      pendingEsc = null
+      state = 'idle'
+      ctrl?.abort()
+    }, bareEscIdleMs)
+  }
+
+  const cancelPendingTimer = (): void => {
+    if (pendingEsc !== null) {
+      clearTimeout(pendingEsc)
+      pendingEsc = null
+    }
   }
 
   return {
@@ -32,34 +81,81 @@ export function createEscController({ debounceMs }: { debounceMs: number }): Esc
       return currentCtrl.signal
     },
     onChunk: (chunk) => {
-      if (chunk.length === 0) return { sigint: false }
-      if (chunk[0] === 0x03) {
-        // Ctrl-C in raw mode arrives as a byte (terminal driver does not generate
-        // SIGINT). Surface to the caller so it can re-issue SIGINT via the OS;
-        // we deliberately keep the AbortController lifecycle separate from SIGINT.
-        return { sigint: true }
-      }
-      if (chunk.length === 1 && chunk[0] === 0x1b) {
-        // Bare ESC: schedule the abort. A follow-up byte within debounceMs (CSI
-        // sequences from arrow keys, mouse, paste) cancels the pending fire.
-        // Snapshot currentCtrl so a late-firing timer can't abort a controller
-        // created by a subsequent armForStream() call.
-        clearPending()
-        const ctrl = currentCtrl
-        pendingEsc = setTimeout(() => {
-          pendingEsc = null
-          ctrl?.abort()
-        }, debounceMs)
-        return { sigint: false }
+      let sigint = false
+      let quit = false
+      for (const byte of chunk) {
+        switch (state) {
+          case 'idle':
+            if (byte === ESC) {
+              state = 'sawEsc'
+              scheduleBareEsc()
+            } else if (byte === CTRL_C) {
+              sigint = true
+            } else if (byte === QUIT_KEY) {
+              quit = true
+            }
+            break
+          case 'sawEsc':
+            if (byte === CSI_INTRODUCER) {
+              cancelPendingTimer()
+              state = 'csi'
+            } else if (byte === SS3_INTRODUCER) {
+              cancelPendingTimer()
+              state = 'ss3'
+            } else if (byte === CTRL_C || byte === QUIT_KEY) {
+              // ESC then an exit key: exit must win over the pending bare-ESC
+              // 'back'. Drop the pending ESC WITHOUT aborting (abort would settle
+              // 'back' synchronously and pre-empt the exit), and surface the key.
+              cancelPendingTimer()
+              state = 'idle'
+              if (byte === CTRL_C) sigint = true
+              else quit = true
+            } else if (byte === ESC) {
+              // The first ESC was bare; abort now and keep this ESC pending.
+              cancelPendingTimer()
+              currentCtrl?.abort()
+              state = 'sawEsc'
+              scheduleBareEsc()
+            } else {
+              // ESC + an ordinary byte: the ESC was bare. Abort to 'back' and
+              // drop the trailing byte (e.g. Alt+key is treated as a bare ESC).
+              cancelPendingTimer()
+              currentCtrl?.abort()
+              state = 'idle'
+            }
+            break
+          case 'csi':
+          case 'ss3':
+            // A C0 control byte is never a legal part of a CSI/SS3 body. A
+            // truncated or malformed sequence (e.g. dropped final byte over a
+            // lossy SSH link) must not strand the parser swallowing the user's
+            // exit keys. ESC resynchronizes to a new sequence; Ctrl-C surfaces
+            // immediately; any other C0 control just abandons the sequence.
+            if (byte === ESC) {
+              state = 'sawEsc'
+              scheduleBareEsc()
+            } else if (byte === CTRL_C) {
+              cancelPendingTimer()
+              state = 'idle'
+              sigint = true
+            } else if (isC0Control(byte)) {
+              cancelPendingTimer()
+              state = 'idle'
+            } else if (state === 'csi') {
+              if (isCsiFinal(byte)) state = 'idle'
+            } else {
+              // SS3 carries exactly one final byte (e.g. application-mode arrows).
+              state = 'idle'
+            }
+            break
+        }
       }
-      // Any other byte arriving within the ESC window is the second byte of a CSI
-      // sequence; cancel the pending abort.
-      clearPending()
-      return { sigint: false }
+      return { sigint, quit }
     },
     clearPending,
     dispose: () => {
-      clearPending()
+      cancelPendingTimer()
+      state = 'idle'
       currentCtrl = null
     },
   }
@@ -111,8 +207,11 @@ export function createTailScope(opts: { debounceMs: number; input?: RawInput; pr
 
   const onData = (chunk: Buffer): void => {
     if (esc === null) return
-    const { sigint } = esc.onChunk(chunk)
-    if (sigint) settle('exit')
+    // Route every byte through the parser so arrow keys (CSI/SS3) are consumed
+    // as no-ops and q/ctrl-c are detected even when batched with other bytes.
+    // q mirrors dreams' quit key and is symmetric with Ctrl-C in live tail.
+    const { sigint, quit } = esc.onChunk(chunk)
+    if (sigint || quit) settle('exit')
   }
 
   const dispose = (): void => {

package/src/cli/inspect.ts

@@ -58,6 +58,7 @@ export const inspectCommand = defineCommand({
       selectSession: (sessions, selectOpts) => clackSelect(sessions, selectOpts?.initialSessionId),
       ...(liveSource !== undefined ? { liveSource } : {}),
       createTailScope: () => createTailScope({ debounceMs: ESC_DEBOUNCE_MS }),
+      ...(interactive ? { interactive: true } : {}),
       ...(liveHint !== undefined ? { liveHint } : {}),
       stdout: (line) => process.stdout.write(`${line}\n`),
       stderr: (line) => process.stderr.write(`${line}\n`),
@@ -93,7 +94,7 @@ async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefin
 }
 
 function escHintLine(color: boolean): string {
-  const text = '(press esc to return to session list)'
+  const text = '(esc to return to session list · q to quit)'
   return color ? `\u001b[2m${text}\u001b[0m` : text
 }
 

package/src/commands/index.ts

@@ -25,6 +25,13 @@ export type Command<Context> = {
   description: string
   permission?: CommandPermission
   requiresLiveSession?: boolean
+  // Resolve an existing live session into the handler context WITHOUT failing
+  // when none exists (distinct from `requiresLiveSession`, which aborts the
+  // command if no session is live). Used by /restart: it must bounce the
+  // container even from a cold channel, but when a session IS live it needs
+  // that session's identity to write a resume handoff. Ignored when
+  // `requiresLiveSession` is true (that path already resolves the session).
+  wantsLiveSession?: boolean
   handler: CommandHandler<Context>
 }
 
@@ -42,6 +49,7 @@ export type CommandInfo = {
   description: string
   permission: CommandPermission
   requiresLiveSession: boolean
+  wantsLiveSession: boolean
 }
 
 export type CommandResult =
@@ -74,6 +82,7 @@ export function createCommandRegistry<Context>(commands: readonly Command<Contex
     description: command.description,
     permission: command.permission ?? 'session.control',
     requiresLiveSession: command.requiresLiveSession ?? true,
+    wantsLiveSession: command.wantsLiveSession ?? false,
   })
 
   return {

package/src/container/start.ts

@@ -4,6 +4,7 @@ import { readFile, writeFile } from 'node:fs/promises'
 import { isAbsolute, join, resolve } from 'node:path'
 
 import { expandMountPath, loadConfigSync, type Config } from '@/config'
+import { commitGitignoreWithUntracks, untrackTrulyIgnoredFiles } from '@/git/reconcile-ignored'
 import { commitSystemFile as commitSystemFileShared } from '@/git/system-commit'
 import { send as sendToDaemon } from '@/hostd/client'
 import type { HttpInfoResult } from '@/hostd/protocol'
@@ -188,7 +189,12 @@ export async function start({
     // trigger the migration commit if the file was legacy.
     await refreshGitignore(cwd)
     const pkgRefresh = await refreshPackageJson(cwd)
-    await commitSystemFile(cwd, GITIGNORE_FILE, 'Update .gitignore')
+    const { untracked } = await untrackTrulyIgnoredFiles(cwd, (await loadTypeclawConfig(cwd)).git.ignore.append)
+    if (untracked.length > 0) {
+      await commitGitignoreWithUntracks(cwd, GITIGNORE_FILE, untracked, 'Untrack newly-ignored files')
+    } else {
+      await commitSystemFile(cwd, GITIGNORE_FILE, 'Update .gitignore')
+    }
     if (pkgRefresh.changed) {
       await commitSystemFile(cwd, pkgRefresh.files, 'Enable bun workspaces (packages/*)')
     }

package/src/git/mutex.ts

@@ -0,0 +1,22 @@
+const chains = new Map<string, Promise<void>>()
+
+export async function withGitLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const previous = chains.get(key) ?? Promise.resolve()
+  let release!: () => void
+  const current = new Promise<void>((resolve) => {
+    release = resolve
+  })
+  const next = previous.then(
+    () => current,
+    () => current,
+  )
+  chains.set(key, next)
+
+  await previous.catch(() => undefined)
+  try {
+    return await fn()
+  } finally {
+    release()
+    if (chains.get(key) === next) chains.delete(key)
+  }
+}