typeclaw 0.1.0 → 0.1.2

package/README.md

@@ -68,18 +68,18 @@ That's it. The agent is now alive, listening on a websocket, ready to receive pr
 
 ## CLI
 
-| Command            | Purpose                                         |
-| ------------------ | ----------------------------------------------- |
-| `typeclaw init`    | Scaffold a new agent folder                     |
-| `typeclaw start`   | Build and run the container                     |
-| `typeclaw stop`    | Stop the container                              |
-| `typeclaw restart` | `stop` then `start`                             |
-| `typeclaw status`  | Show container + daemon registration state      |
-| `typeclaw logs`    | `docker logs` passthrough, `-f` to follow       |
-| `typeclaw tui`     | Attach a terminal UI over the agent's websocket |
-| `typeclaw shell`   | Open a shell inside the running container       |
-| `typeclaw reload`  | Push a live config reload to the running agent  |
-| `typeclaw compose` | Orchestrate multiple agents                     |
+| Command            | Purpose                                                              |
+| ------------------ | -------------------------------------------------------------------- |
+| `typeclaw init`    | Scaffold a new agent folder                                          |
+| `typeclaw start`   | Build and run the container                                          |
+| `typeclaw stop`    | Stop the container                                                   |
+| `typeclaw restart` | `stop` then `start`                                                  |
+| `typeclaw status`  | Show container + daemon registration state                           |
+| `typeclaw logs`    | Stream container stdout/stderr with local timestamps; `-f` to follow |
+| `typeclaw tui`     | Attach a terminal UI over the agent's websocket                      |
+| `typeclaw shell`   | Open a shell inside the running container                            |
+| `typeclaw reload`  | Push a live config reload to the running agent                       |
+| `typeclaw compose` | Orchestrate multiple agents                                          |
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -16,6 +16,7 @@
   "files": [
     "src",
     "scripts",
+    "tsconfig.json",
     "typeclaw.schema.json",
     "cron.schema.json",
     "secrets.schema.json",
@@ -44,7 +45,7 @@
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",
     "@mozilla/readability": "^0.6.0",
-    "agent-messenger": "2.14.1",
+    "agent-messenger": "2.15.0",
     "cheerio": "^1.2.0",
     "citty": "^0.2.2",
     "cron-parser": "^5.5.0",

package/src/agent/auth.ts

@@ -10,7 +10,7 @@ import {
   supportsOAuth,
   type KnownProviderId,
 } from '@/config/providers'
-import { createSecretsStoreForAgent } from '@/secrets'
+import { createSecretsStoreForAgent, stripEnvKey } from '@/secrets'
 
 type Auth = {
   authStorage: AuthStorage
@@ -70,9 +70,15 @@ export function getAuth(): Auth {
     const envKey = process.env[provider.apiKeyEnv]
     if (envKey) {
       const existing = authStorage.get(provider.id)
-      const needsWrite = existing === undefined || (existing.type === 'api_key' && existing.key !== envKey)
-      if (needsWrite) {
-        authStorage.set(provider.id, { type: 'api_key', key: envKey })
+      const apiKeyOwned = existing === undefined || existing.type === 'api_key'
+      if (apiKeyOwned) {
+        if (existing === undefined || existing.key !== envKey) {
+          authStorage.set(provider.id, { type: 'api_key', key: envKey })
+        }
+        // secrets.json is now authoritative for this provider's api-key credential.
+        // Strip the value from `.env` so the next boot does not silently revive a
+        // stale or rotated-away key, and so users have a single place to edit.
+        stripEnvKey(join(process.cwd(), '.env'), provider.apiKeyEnv)
       }
     }
   }

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/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).

package/src/bundled-plugins/backup/index.ts

@@ -0,0 +1,209 @@
+import { z } from 'zod'
+
+import { definePlugin, type Subagent } from '@/plugin'
+
+import { COMMIT_TIMEOUT_MS, makeDefaultGitSpawn, NETWORK_TIMEOUT_MS, runBackup, type BackupResult } from './runner'
+import {
+  cleanupMessageFile,
+  type CommitMessagePayload,
+  createCommitMessageSubagent,
+  createDiagnoseFailureSubagent,
+  type DiagnoseFailurePayload,
+  ensureMessageDir,
+  messageFilePath,
+  readMessageFile,
+} from './subagents'
+
+const DEFAULT_IDLE_MS = 30_000
+const MIN_IDLE_MS = 1_000
+
+const SUBAGENT_BACKUP_RUNNER = 'backup'
+const SUBAGENT_COMMIT_MESSAGE = 'backup-message'
+const SUBAGENT_DIAGNOSE = 'backup-diagnose'
+
+const SELF_INDUCED_SUBAGENT_NAMES = new Set<string>([
+  SUBAGENT_BACKUP_RUNNER,
+  SUBAGENT_COMMIT_MESSAGE,
+  SUBAGENT_DIAGNOSE,
+])
+
+const backupConfigSchema = z
+  .object({
+    enabled: z.boolean().default(true),
+    idleMs: z.number().int().min(MIN_IDLE_MS).default(DEFAULT_IDLE_MS),
+    pushToOrigin: z.boolean().default(true),
+    commitTimeoutMs: z.number().int().min(1).default(COMMIT_TIMEOUT_MS),
+    networkTimeoutMs: z.number().int().min(1).default(NETWORK_TIMEOUT_MS),
+  })
+  .default({
+    enabled: true,
+    idleMs: DEFAULT_IDLE_MS,
+    pushToOrigin: true,
+    commitTimeoutMs: COMMIT_TIMEOUT_MS,
+    networkTimeoutMs: NETWORK_TIMEOUT_MS,
+  })
+
+const runnerPayloadSchema = z.object({
+  agentDir: z.string(),
+  pushToOrigin: z.boolean(),
+})
+
+type RunnerPayload = z.infer<typeof runnerPayloadSchema>
+
+export default definePlugin({
+  configSchema: backupConfigSchema,
+  plugin: async (ctx) => {
+    const enabled = ctx.config.enabled
+    const idleMs = ctx.config.idleMs
+    const pushToOrigin = ctx.config.pushToOrigin
+
+    const activeTurns = new Set<string>()
+    let idleTimer: ReturnType<typeof setTimeout> | null = null
+    let pendingFire = false
+    let inFlight = false
+
+    const cancelTimer = (): void => {
+      if (idleTimer !== null) {
+        clearTimeout(idleTimer)
+        idleTimer = null
+      }
+    }
+
+    const fireIfQuiet = async (): Promise<void> => {
+      if (!enabled) return
+      if (inFlight) {
+        pendingFire = true
+        return
+      }
+      if (activeTurns.size > 0) return
+      inFlight = true
+      try {
+        await ctx.spawnSubagent(SUBAGENT_BACKUP_RUNNER, {
+          agentDir: ctx.agentDir,
+          pushToOrigin,
+        } satisfies RunnerPayload)
+      } catch (err) {
+        ctx.logger.error(`backup runner spawn failed: ${err instanceof Error ? err.message : String(err)}`)
+      } finally {
+        inFlight = false
+        if (pendingFire) {
+          pendingFire = false
+          if (activeTurns.size === 0) {
+            queueMicrotask(() => {
+              void fireIfQuiet()
+            })
+          }
+        }
+      }
+    }
+
+    const isSelfInducedTurn = (origin: { kind: string; subagent?: string } | undefined): boolean => {
+      if (origin?.kind !== 'subagent') return false
+      const sub = origin.subagent
+      return sub !== undefined && SELF_INDUCED_SUBAGENT_NAMES.has(sub)
+    }
+
+    const runnerSubagent: Subagent<RunnerPayload> = {
+      systemPrompt: '(backup runner — no LLM)',
+      payloadSchema: runnerPayloadSchema,
+      inFlightKey: (payload) => payload.agentDir,
+      handler: async (sctx) => {
+        const result = await runBackupOnce(sctx.payload, ctx)
+        const summary = describeResult(result)
+        ctx.logger.info(`[backup] ${summary}`)
+      },
+    }
+
+    return {
+      subagents: {
+        [SUBAGENT_BACKUP_RUNNER]: runnerSubagent,
+        [SUBAGENT_COMMIT_MESSAGE]: createCommitMessageSubagent(),
+        [SUBAGENT_DIAGNOSE]: createDiagnoseFailureSubagent(),
+      },
+      hooks: {
+        'session.turn.start': (event) => {
+          if (isSelfInducedTurn(event.origin)) return
+          activeTurns.add(event.sessionId)
+          cancelTimer()
+        },
+        'session.turn.end': (event) => {
+          if (isSelfInducedTurn(event.origin)) return
+          activeTurns.delete(event.sessionId)
+        },
+        'session.end': (event) => {
+          activeTurns.delete(event.sessionId)
+        },
+        'session.idle': () => {
+          if (!enabled) return
+          if (activeTurns.size > 0) return
+          cancelTimer()
+          idleTimer = setTimeout(() => {
+            idleTimer = null
+            void fireIfQuiet()
+          }, idleMs)
+        },
+      },
+    }
+  },
+})
+
+async function runBackupOnce(
+  payload: RunnerPayload,
+  ctx: {
+    agentDir: string
+    logger: { info: (m: string) => void; warn: (m: string) => void }
+    spawnSubagent: (name: string, payload?: unknown) => Promise<void>
+  },
+): Promise<BackupResult> {
+  const messagePath = messageFilePath(payload.agentDir)
+  await ensureMessageDir(messagePath)
+  await cleanupMessageFile(messagePath)
+
+  const result = await runBackup(
+    { cwd: payload.agentDir, pushToOrigin: payload.pushToOrigin },
+    {
+      gitSpawn: makeDefaultGitSpawn(),
+      pickCommitMessage: async ({ status, diffstat }) => {
+        await cleanupMessageFile(messagePath)
+        const messagePayload: CommitMessagePayload = {
+          agentDir: payload.agentDir,
+          status,
+          diffstat,
+          outputPath: messagePath,
+        }
+        try {
+          await ctx.spawnSubagent(SUBAGENT_COMMIT_MESSAGE, messagePayload)
+        } catch (err) {
+          ctx.logger.warn(
+            `${SUBAGENT_COMMIT_MESSAGE} subagent failed, using fallback: ${err instanceof Error ? err.message : String(err)}`,
+          )
+        }
+        const written = await readMessageFile(messagePath)
+        await cleanupMessageFile(messagePath)
+        return written ?? 'chore: backup'
+      },
+      diagnoseFailure: async (input) => {
+        const diagPayload: DiagnoseFailurePayload = {
+          agentDir: input.cwd,
+          stage: input.stage,
+          exitCode: input.exitCode,
+          stderr: input.stderr,
+          stdout: input.stdout,
+        }
+        try {
+          await ctx.spawnSubagent(SUBAGENT_DIAGNOSE, diagPayload)
+        } catch (err) {
+          ctx.logger.warn(`${SUBAGENT_DIAGNOSE} subagent failed: ${err instanceof Error ? err.message : String(err)}`)
+        }
+      },
+    },
+  )
+
+  await cleanupMessageFile(messagePath)
+  return result
+}
+
+function describeResult(r: BackupResult): string {
+  if (r.ok) return r.kind
+  return `failed (${r.kind}): ${r.reason}`
+}