typeclaw 0.1.1 → 0.1.3

package/src/agent/doctor.ts

@@ -0,0 +1,173 @@
+import { isAbsolute, normalize } from 'node:path'
+
+import type {
+  PluginCheckResult,
+  PluginCheckStatus,
+  PluginDoctorContext,
+  PluginFixResult,
+  PluginRegistry,
+  RegisteredDoctorCheck,
+} from '@/plugin'
+
+export type PluginCheckRecord = {
+  id: string
+  pluginName: string
+  checkName: string
+  description: string
+  category: string
+  status: PluginCheckStatus
+  message: string
+  details?: string[]
+  fix?: { description: string; hasApply: boolean }
+}
+
+export type PluginFixOutcome = { ok: true; summary: string; changedPaths: string[] } | { ok: false; error: string }
+
+export type RunPluginDoctorOptions = {
+  registry: PluginRegistry
+  agentDir: string
+  checkTimeoutMs?: number
+}
+
+export type RunPluginDoctorFixOptions = RunPluginDoctorOptions & {
+  checkId: string
+  fixTimeoutMs?: number
+}
+
+const DEFAULT_CHECK_TIMEOUT_MS = 5_000
+const DEFAULT_FIX_TIMEOUT_MS = 30_000
+
+export function checkId(pluginName: string, checkName: string): string {
+  return `${pluginName}.${checkName}`
+}
+
+export async function runPluginDoctorChecks(opts: RunPluginDoctorOptions): Promise<PluginCheckRecord[]> {
+  const timeoutMs = opts.checkTimeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS
+  const records: PluginCheckRecord[] = []
+  for (const entry of opts.registry.doctorChecks) {
+    records.push(await runOneCheck(entry, opts.agentDir, timeoutMs))
+  }
+  return records
+}
+
+export async function runPluginDoctorFix(opts: RunPluginDoctorFixOptions): Promise<PluginFixOutcome> {
+  const entry = opts.registry.doctorChecks.find((c) => checkId(c.pluginName, c.checkName) === opts.checkId)
+  if (!entry) return { ok: false, error: `doctor check ${opts.checkId} is not registered` }
+
+  const ctx = buildPluginCtx(entry, opts.agentDir)
+  let result: PluginCheckResult
+  try {
+    result = await raceWithTimeout(entry.check.run(ctx), opts.checkTimeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS, 'check')
+  } catch (err) {
+    return { ok: false, error: messageOf(err) }
+  }
+  const apply = result.fix?.apply
+  if (!apply) return { ok: false, error: `${opts.checkId}: no auto-fix available` }
+
+  let fix: PluginFixResult
+  try {
+    fix = await raceWithTimeout(apply(ctx), opts.fixTimeoutMs ?? DEFAULT_FIX_TIMEOUT_MS, 'fix')
+  } catch (err) {
+    return { ok: false, error: messageOf(err) }
+  }
+
+  const sanitized = sanitizeChangedPaths(fix.changedPaths)
+  if (sanitized.rejected.length > 0) {
+    entry.logger.warn(
+      `${opts.checkId}: dropped ${sanitized.rejected.length} invalid changedPaths (${sanitized.rejected.join(', ')})`,
+    )
+  }
+  return { ok: true, summary: fix.summary, changedPaths: sanitized.accepted }
+}
+
+async function runOneCheck(
+  entry: RegisteredDoctorCheck,
+  agentDir: string,
+  timeoutMs: number,
+): Promise<PluginCheckRecord> {
+  const id = checkId(entry.pluginName, entry.checkName)
+  const ctx = buildPluginCtx(entry, agentDir)
+  try {
+    const result = await raceWithTimeout(entry.check.run(ctx), timeoutMs, 'check')
+    return buildRecord(entry, id, result)
+  } catch (err) {
+    return {
+      id,
+      pluginName: entry.pluginName,
+      checkName: entry.checkName,
+      description: entry.check.description,
+      category: entry.check.category ?? `plugin:${entry.pluginName}`,
+      status: 'error',
+      message: messageOf(err),
+    }
+  }
+}
+
+function buildRecord(entry: RegisteredDoctorCheck, id: string, result: PluginCheckResult): PluginCheckRecord {
+  const record: PluginCheckRecord = {
+    id,
+    pluginName: entry.pluginName,
+    checkName: entry.checkName,
+    description: entry.check.description,
+    category: entry.check.category ?? `plugin:${entry.pluginName}`,
+    status: result.status,
+    message: result.message,
+  }
+  if (result.details !== undefined && result.details.length > 0) record.details = result.details
+  if (result.fix !== undefined) {
+    record.fix = { description: result.fix.description, hasApply: result.fix.apply !== undefined }
+  }
+  return record
+}
+
+function buildPluginCtx(entry: RegisteredDoctorCheck, agentDir: string): PluginDoctorContext {
+  return Object.freeze({
+    pluginName: entry.pluginName,
+    agentDir,
+    config: entry.pluginConfig,
+    logger: entry.logger,
+  })
+}
+
+async function raceWithTimeout<T>(work: Promise<T>, ms: number, label: 'check' | 'fix'): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | null = null
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`plugin doctor ${label} timed out after ${ms}ms`)), ms)
+  })
+  try {
+    return await Promise.race([work, timeout])
+  } finally {
+    if (timer !== null) clearTimeout(timer)
+  }
+}
+
+function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+export type PathSanitization = { accepted: string[]; rejected: string[] }
+
+// Plugin fixes declare paths relative to agentDir; the host re-validates on
+// receipt for defense in depth, but rejecting here first keeps the wire
+// payload small and the failure attribution accurate.
+export function sanitizeChangedPaths(paths: readonly string[]): PathSanitization {
+  const accepted: string[] = []
+  const rejected: string[] = []
+  for (const raw of paths) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+      rejected.push(String(raw))
+      continue
+    }
+    if (isAbsolute(raw) || raw.includes('\\')) {
+      rejected.push(raw)
+      continue
+    }
+    const normalized = normalize(raw)
+    if (normalized.startsWith('..') || normalized.split('/').includes('..')) {
+      rejected.push(raw)
+      continue
+    }
+    accepted.push(normalized)
+  }
+  return { accepted, rejected }
+}

package/src/agent/subagents.ts

@@ -5,6 +5,7 @@ import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
 
 import { type AgentSession, createSession } from './index'
+import type { SessionOrigin } from './session-origin'
 
 type AgentSessionTools = NonNullable<Parameters<typeof createSession>[0]>['tools']
 
@@ -54,6 +55,8 @@ export type CreateSessionForSubagentResult = {
   dispose?: () => Promise<void>
   hooks?: HookBus
   sessionId?: string
+  agentDir?: string
+  origin?: SessionOrigin
   getTranscriptPath?: () => string | undefined
 }
 export type CreateSessionForSubagentOptions = {
@@ -82,6 +85,8 @@ type NormalizedSubagentSession = {
   dispose: () => Promise<void>
   hooks: HookBus | undefined
   sessionId: string | undefined
+  agentDir: string | undefined
+  origin: SessionOrigin | undefined
   getTranscriptPath: (() => string | undefined) | undefined
 }
 
@@ -92,6 +97,8 @@ function normalizeSubagentSession(result: AgentSession | CreateSessionForSubagen
       dispose: result.dispose ?? (async () => {}),
       hooks: result.hooks,
       sessionId: result.sessionId,
+      agentDir: result.agentDir,
+      origin: result.origin,
       getTranscriptPath: result.getTranscriptPath,
     }
   }
@@ -100,6 +107,8 @@ function normalizeSubagentSession(result: AgentSession | CreateSessionForSubagen
     dispose: async () => {},
     hooks: undefined,
     sessionId: undefined,
+    agentDir: undefined,
+    origin: undefined,
     getTranscriptPath: undefined,
   }
 }
@@ -125,11 +134,24 @@ export async function invokeSubagent(name: string, options: InvokeSubagentOption
   }
 
   const runSession: RunSession = async (override) => {
-    const { session, dispose, hooks, sessionId, getTranscriptPath } = normalizeSubagentSession(
+    const { session, dispose, hooks, sessionId, agentDir, origin, getTranscriptPath } = normalizeSubagentSession(
       await createSessionForSubagent(subagent, sessionOptions),
     )
+    const turnEvent =
+      hooks && sessionId !== undefined && agentDir !== undefined
+        ? { sessionId, agentDir, ...(origin !== undefined ? { origin } : {}) }
+        : undefined
     try {
-      await session.prompt(override?.userPrompt ?? options.userPrompt)
+      if (hooks && turnEvent !== undefined) {
+        await hooks.runSessionTurnStart(turnEvent)
+      }
+      try {
+        await session.prompt(override?.userPrompt ?? options.userPrompt)
+      } finally {
+        if (hooks && turnEvent !== undefined) {
+          await hooks.runSessionTurnEnd(turnEvent)
+        }
+      }
       if (hooks && sessionId !== undefined) {
         await hooks.runSessionIdle({
           sessionId,

package/src/agent/tools/channel-fetch-attachment.ts

@@ -7,6 +7,8 @@ import { defineTool } from '@mariozechner/pi-coding-agent'
 import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
 export type ChannelFetchAttachmentOrigin = {
   adapter: AdapterId
 }
@@ -15,6 +17,7 @@ export type CreateChannelFetchAttachmentToolOptions = {
   router: ChannelRouter
   origin: ChannelFetchAttachmentOrigin
   inboxDir?: string
+  logger?: ChannelToolLogger
 }
 
 export const DEFAULT_INBOX_DIR = '/agent/workspace/inbox'
@@ -23,6 +26,7 @@ export function createChannelFetchAttachmentTool({
   router,
   origin,
   inboxDir,
+  logger = consoleChannelLogger,
 }: CreateChannelFetchAttachmentToolOptions) {
   const baseDir = inboxDir ?? DEFAULT_INBOX_DIR
   const adapter = origin.adapter
@@ -60,6 +64,7 @@ export function createChannelFetchAttachmentTool({
         ...(params.filename !== undefined ? { filename: params.filename } : {}),
       })
       if (!result.ok) {
+        logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: ${result.error}`))
         const text = `channel_fetch_attachment error: ${result.error}`
         const details: Details = { ok: false, error: result.error }
         return { content: [{ type: 'text' as const, text }], details }
@@ -74,6 +79,7 @@ export function createChannelFetchAttachmentTool({
         await writeFile(targetPath, result.buffer)
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
+        logger.warn(formatChannelToolFailure('channel_fetch_attachment', `${adapter}: write failed: ${message}`))
         const text = `channel_fetch_attachment error: write failed: ${message}`
         const details: Details = { ok: false, error: `write failed: ${message}` }
         return { content: [{ type: 'text' as const, text }], details }

package/src/agent/tools/channel-history.ts

@@ -5,6 +5,8 @@ import type { ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 import type { ChannelHistoryMessage } from '@/channels/types'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
 export type ChannelHistoryOrigin = {
   adapter: AdapterId
   workspace: string
@@ -15,6 +17,7 @@ export type ChannelHistoryOrigin = {
 export type CreateChannelHistoryToolOptions = {
   router: ChannelRouter
   origin: ChannelHistoryOrigin
+  logger?: ChannelToolLogger
 }
 
 // channel_history is a lazy "look back" capability for channel-routed
@@ -27,7 +30,11 @@ export type CreateChannelHistoryToolOptions = {
 // `scope` defaults to thread when the origin has one, channel otherwise.
 // Thread scope on a channel-root session is rejected rather than silently
 // downgraded so the agent doesn't conflate the two views.
-export function createChannelHistoryTool({ router, origin }: CreateChannelHistoryToolOptions) {
+export function createChannelHistoryTool({
+  router,
+  origin,
+  logger = consoleChannelLogger,
+}: CreateChannelHistoryToolOptions) {
   return defineTool({
     name: 'channel_history',
     label: 'Channel History',
@@ -64,6 +71,7 @@ export function createChannelHistoryTool({ router, origin }: CreateChannelHistor
       type Details = { ok: boolean; error?: string; count?: number; nextCursor?: string }
 
       if (scope === 'thread' && origin.thread === null) {
+        logger.warn(formatChannelToolFailure('channel_history', 'thread-scope-requires-thread-session'))
         const text =
           'channel_history error: thread-scope-requires-thread-session — this session is not in a thread; pass `scope: "channel"` instead.'
         const details: Details = { ok: false, error: 'thread-scope-requires-thread-session' }
@@ -78,6 +86,7 @@ export function createChannelHistoryTool({ router, origin }: CreateChannelHistor
       })
 
       if (!result.ok) {
+        logger.warn(formatChannelToolFailure('channel_history', `${origin.adapter}:${origin.chat}: ${result.error}`))
         const details: Details = { ok: false, error: result.error }
         return {
           content: [{ type: 'text' as const, text: `channel_history error: ${result.error}` }],

package/src/agent/tools/channel-log.ts

@@ -0,0 +1,32 @@
+// Shared logger surface for the channel_* agent tools.
+//
+// Until now, channel_send / channel_reply / channel_history /
+// channel_fetch_attachment swallowed every failure into the model-visible
+// tool result and emitted nothing to the container's stdout/stderr. That
+// made operator-side debugging blind: a Slack send that 403'd, a
+// `thread-scope-requires-thread-session` denial, or a Discord attachment
+// fetch that timed out left no trace in `typeclaw logs`. The router layer
+// logs some of these (e.g. `fetchHistory` warns on caught exceptions) but
+// does NOT log `router.send` rejections, and pre-router validation errors
+// inside the tools (missing text, NO_REPLY misuse, thread-scope mismatch,
+// local write failures) never reached the router in the first place.
+//
+// One injectable logger per tool keeps the existing fake-router test
+// pattern intact: tests pass an array-collecting logger to assert the log
+// line, production code defaults to `consoleChannelLogger` which routes to
+// `console.warn` so it lands in `typeclaw logs` alongside the existing
+// `[channels]` lines from manager.ts / router.ts.
+export type ChannelToolLogger = {
+  warn: (msg: string) => void
+}
+
+export const consoleChannelLogger: ChannelToolLogger = {
+  warn: (m) => console.warn(m),
+}
+
+// Format a failure log line. Keeps the `[channels]` prefix used by
+// manager.ts and router.ts so operators can `grep '\[channels\]'` and see
+// the full stack of channel-related warnings in one pass.
+export function formatChannelToolFailure(tool: string, error: string): string {
+  return `[channels] ${tool} failed: ${error}`
+}

package/src/agent/tools/channel-reply.ts

@@ -4,6 +4,8 @@ import { defineTool } from '@mariozechner/pi-coding-agent'
 import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
 import type { AdapterId } from '@/channels/schema'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
+
 export type ChannelReplyOrigin = {
   adapter: AdapterId
   workspace: string
@@ -14,6 +16,7 @@ export type ChannelReplyOrigin = {
 export type CreateChannelReplyToolOptions = {
   router: ChannelRouter
   origin: ChannelReplyOrigin
+  logger?: ChannelToolLogger
 }
 
 // channel_reply is the happy-path companion to channel_send for channel-routed
@@ -25,7 +28,11 @@ export type CreateChannelReplyToolOptions = {
 // channel_reply takes only `text` and addresses the message from the origin.
 // channel_send remains for posting somewhere else (different chat, breaking
 // out of a thread, sending DMs from a channel session, etc.).
-export function createChannelReplyTool({ router, origin }: CreateChannelReplyToolOptions) {
+export function createChannelReplyTool({
+  router,
+  origin,
+  logger = consoleChannelLogger,
+}: CreateChannelReplyToolOptions) {
   return defineTool({
     name: 'channel_reply',
     label: 'Channel Reply',
@@ -64,6 +71,7 @@ export function createChannelReplyTool({ router, origin }: CreateChannelReplyToo
       const text = params.text
       const attachments = params.attachments
       if ((text === undefined || text === '') && (attachments === undefined || attachments.length === 0)) {
+        logger.warn(formatChannelToolFailure('channel_reply', 'missing text and attachments'))
         return {
           content: [
             { type: 'text' as const, text: 'channel_reply denied: must provide `text`, `attachments`, or both.' },
@@ -74,6 +82,7 @@ export function createChannelReplyTool({ router, origin }: CreateChannelReplyToo
 
       const noReplyError = noReplyMisuseError(text)
       if (noReplyError) {
+        logger.warn(formatChannelToolFailure('channel_reply', noReplyError))
         return {
           content: [{ type: 'text' as const, text: `channel_reply denied: ${noReplyError}` }],
           details: { ok: false, error: noReplyError },
@@ -89,6 +98,14 @@ export function createChannelReplyTool({ router, origin }: CreateChannelReplyToo
         ...(attachments !== undefined ? { attachments } : {}),
       })
 
+      if (!result.ok) {
+        logger.warn(
+          formatChannelToolFailure(
+            'channel_reply',
+            `${origin.adapter}:${origin.workspace}/${origin.chat}: ${result.error}`,
+          ),
+        )
+      }
       const details: { ok: boolean; error?: string } = result.ok ? { ok: true } : { ok: false, error: result.error }
       // Echo the delivered text back to the model. The adapter classifier
       // drops self-authored messages on the inbound path (`self_author`),

package/src/agent/tools/channel-send.ts

@@ -4,6 +4,7 @@ import { defineTool } from '@mariozechner/pi-coding-agent'
 import { isNoReplySignal, type ChannelRouter } from '@/channels/router'
 import { ADAPTER_IDS, type AdapterId } from '@/channels/schema'
 
+import { type ChannelToolLogger, consoleChannelLogger, formatChannelToolFailure } from './channel-log'
 import { renderOutboundEcho } from './channel-reply'
 
 export type ChannelSendOrigin = {
@@ -21,9 +22,10 @@ export type CreateChannelSendToolOptions = {
   // the model can self-correct on its next turn. Absent for sessions whose
   // origin isn't a channel (e.g. cron prompts that send to channels).
   origin?: ChannelSendOrigin
+  logger?: ChannelToolLogger
 }
 
-export function createChannelSendTool({ router, origin }: CreateChannelSendToolOptions) {
+export function createChannelSendTool({ router, origin, logger = consoleChannelLogger }: CreateChannelSendToolOptions) {
   return defineTool({
     name: 'channel_send',
     label: 'Channel Send',
@@ -93,6 +95,7 @@ export function createChannelSendTool({ router, origin }: CreateChannelSendToolO
       const bodyText = params.text
       const attachments = params.attachments
       if ((bodyText === undefined || bodyText === '') && (attachments === undefined || attachments.length === 0)) {
+        logger.warn(formatChannelToolFailure('channel_send', 'missing text and attachments'))
         return {
           content: [
             { type: 'text' as const, text: 'channel_send denied: must provide `text`, `attachments`, or both.' },
@@ -103,6 +106,7 @@ export function createChannelSendTool({ router, origin }: CreateChannelSendToolO
 
       const noReplyError = noReplyMisuseError(bodyText)
       if (noReplyError) {
+        logger.warn(formatChannelToolFailure('channel_send', noReplyError))
         return {
           content: [{ type: 'text' as const, text: `channel_send denied: ${noReplyError}` }],
           details: { ok: false, error: noReplyError },
@@ -118,6 +122,14 @@ export function createChannelSendTool({ router, origin }: CreateChannelSendToolO
         ...(attachments !== undefined ? { attachments } : {}),
       })
 
+      if (!result.ok) {
+        logger.warn(
+          formatChannelToolFailure(
+            'channel_send',
+            `${params.adapter}:${params.workspace}/${params.chat}: ${result.error}`,
+          ),
+        )
+      }
       const details: { ok: boolean; error?: string } = result.ok ? { ok: true } : { ok: false, error: result.error }
       const echo = renderOutboundEcho(bodyText, attachments)
       const baseText = result.ok

package/src/bundled-plugins/backup/README.md

@@ -0,0 +1,81 @@
+# typeclaw-plugin-backup
+
+The bundled backup plugin. Watches the agent folder for uncommitted work and commits + pushes it during quiet moments, with the LLM picking commit messages and diagnosing push/rebase failures. Replaces the previously documented-but-unimplemented "sessions/ via auto-backup" promise.
+
+This plugin is **auto-loaded** by every TypeClaw agent. There is no `plugins[]` entry to add and no opt-out short of `backup.enabled: false`. To configure it, add a `backup` block to `typeclaw.json`.
+
+## Config
+
+```json
+{
+  "backup": {
+    "enabled": true,
+    "idleMs": 30000,
+    "pushToOrigin": true
+  }
+}
+```
+
+| Field                     | Default | Effect                                                                                                                                                                                                                                                                                                                          |
+| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `backup.enabled`          | `true`  | Master switch. When `false`, all hooks no-op and the runner subagent is never spawned.                                                                                                                                                                                                                                          |
+| `backup.idleMs`           | `30000` | Debounce window after the agent goes idle (no in-flight prompt turns) before the backup runner fires. Resets on every new prompt. Minimum `1000`.                                                                                                                                                                               |
+| `backup.pushToOrigin`     | `true`  | When `true`, after committing, the runner attempts `git push`. On non-fast-forward, it `git fetch && git rebase` then re-pushes. On rebase conflict, it aborts the rebase and asks the diagnose subagent to write a human-readable report. Set `false` to commit-only (useful for offline workflows or repos without a remote). |
+| `backup.commitTimeoutMs`  | `30000` | Per-command wall clock for local git operations (status/add/commit/diff). Mostly an escape hatch — defaults are generous.                                                                                                                                                                                                       |
+| `backup.networkTimeoutMs` | `60000` | Per-command wall clock for network git operations (push/fetch/rebase). Bounds the failure mode where a stuck remote would otherwise hang the runner indefinitely. `GIT_TERMINAL_PROMPT=0` is also set so auth failures fail fast instead of prompting.                                                                          |
+
+All fields are **restart-required** — the plugin reads them once at boot.
+
+## How it triggers
+
+The backup plugin uses **`session.idle` with debounce** as its trigger, not a fixed cron schedule. This means backups fire only after meaningful agent activity has settled — sporadic agents that never go idle (e.g. long polling loops in tools) will not be backed up by this plugin alone.
+
+The fire path is gated by an **active-turn counter**: the plugin tracks `session.turn.start` / `session.turn.end` events from every prompt source (TUI, channel router, cron consumer, subagent invocations) and only fires when the count is zero. The plugin's own three subagents (`backup`, `backup-message`, `backup-diagnose`) are excluded from the count via `origin.kind === 'subagent' && origin.subagent` matching, so the backup never self-gates.
+
+If a new prompt arrives while the runner is in flight, the runner finishes its current commit-and-push cycle; the plugin then re-evaluates the gate. There is no preemption mid-commit — the unit of atomicity is one full backup pass.
+
+## What it commits
+
+The runner stages two categories of dirty paths:
+
+- **Tracked or untracked agent paths** (anything `git status --porcelain=v1 --untracked-files=all` reports), **except** paths under `memory/` — those are owned by the memory plugin's dreaming subagent.
+- **Force-added `sessions/`** — gitignored, but force-added so transcripts survive across restarts.
+
+Commit message comes from the `backup-message` subagent, which sees a truncated `git status` and `git diff --cached --stat` and writes a single conventional-ish commit message to a tmp file. On any failure the runner falls back to `chore: backup`.
+
+## What it pushes
+
+When `pushToOrigin: true` and the current branch has an upstream (`git rev-parse --abbrev-ref --symbolic-full-name @{upstream}` succeeds), the runner runs `git push`. On non-fast-forward rejection, it runs `git fetch` then `git rebase <upstream>` then `git push` again.
+
+If any network step fails (rebase conflict, auth failure, network timeout), the runner aborts cleanly and spawns the `backup-diagnose` subagent. That subagent has `bash`, `read`, and `write` tools and writes a short human-readable report to `<agentDir>/sessions/backup-diagnostics.log`. The diagnose subagent is explicitly forbidden from force-pushing or resolving merge conflicts itself.
+
+## What it contributes
+
+| Kind     | Name                          | Notes                                                                                                                                                       |
+| -------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Subagent | `backup`                      | Runner orchestrator. No LLM call — `handler` directly invokes the deterministic `runBackup`. Coalesced per `agentDir`.                                      |
+| Subagent | `backup-message`              | Picks commit message from the diff. Has only the `write` tool. Coalesced per `agentDir`.                                                                    |
+| Subagent | `backup-diagnose`             | Diagnoses push/rebase failures. Has `bash`, `read`, `write`. Coalesced per `agentDir`.                                                                      |
+| Hook     | `session.turn.start` / `.end` | Maintains the active-turn counter. Excludes self-induced turns (the three subagents above) so the backup never gates against itself.                        |
+| Hook     | `session.idle`                | Debouncer (idleMs). Resets the timer on every event. On fire, checks the active-turn counter and spawns `backup` if zero.                                   |
+| Hook     | `session.end`                 | Removes the session from the active-turn set on session close. Defensive: if a session ends mid-turn (network drop), `session.turn.end` may not have fired. |
+
+## Files on disk
+
+- **`<agentDir>/.typeclaw/backup-message.tmp`** — ephemeral. Written by `backup-message` subagent, read and then deleted by the runner. The directory is created on demand. Not gitignored because it always cleans itself up before commit.
+- **`<agentDir>/sessions/backup-diagnostics.log`** — append-only log written by `backup-diagnose` when push/rebase fails. Lives under `sessions/` so it gets force-added by the next successful backup. Read this file when investigating why the backup plugin stopped working.
+
+## Why this design
+
+This feature came up as: "periodically check for dirty files and commit; LLM picks the message and handles failures." A pre-implementation Oracle review pushed back hard on two assumptions:
+
+1. **Don't make the core flow LLM-driven.** A subagent with `bash` orchestrating push/rebase/conflict recovery can hang on auth prompts, freestyle-mishandle conflicts, or burn an LLM call on every backup even when nothing went wrong. Instead, the deterministic runner owns the flow and only delegates two narrow tasks to LLMs: commit message synthesis (one short call, naturally bounded) and failure diagnosis (only fires on actual failures).
+
+2. **`session.start` / `session.end` is the wrong gate.** Long-lived TUI and channel sessions stay open for hours; counting open sessions would mean the backup never fires. The new `session.turn.start` / `session.turn.end` hooks bracket each `session.prompt(...)` call across all four call sites (TUI server, cron consumer, subagent runner, channel router), so the counter reflects "active work in progress" rather than "any session connected".
+
+`session.idle` (with debounce) was chosen over cron because it ties backup frequency to actual activity. There is no fixed `*/15 * * * *` schedule to misconfigure or re-explain. The tradeoff is the sporadic-agent case noted above.
+
+## Tests
+
+- `runner.test.ts` — deterministic runner unit tests (status parsing, force-add of `sessions/`, push-only-with-upstream, rebase-on-non-fast-forward, diagnose-on-rebase-conflict, advisory-throw isolation, sanitize-commit-message).
+- `index.test.ts` — plugin composition tests (subagent/hook surface, config schema defaults and validation, debounce, active-turn gating, self-induced-turn exclusion, coalescing).