opencode-overclock 0.1.0 → 0.2.0

package/README.md

@@ -41,18 +41,41 @@ Local dev: copy or symlink into `.opencode/plugins/` — see [Dev](#dev). Note t
 
 `true`/`false` toggle. Object = on + options. Defaults: all on except sandbox; guard inert without `hooks`.
 
+Unknown keys, unknown feature names, and wrong option types are reported at startup with a
+"did you mean" — a typo like `killOnExist` would otherwise read as "not set" and silently
+run the default. Bad config never takes the plugin down; it falls back to defaults.
+
+| Feature                | Options                                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| `tasks`                | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num |
+| `sched`                | `skipIfBusy` bool                                                                               |
+| `sandbox`              | `net` bool                                                                                      |
+| `guard`                | `hooks` array                                                                                   |
+| `usage`, `checkpoints` | —                                                                                               |
+| `buddy`                | — (TUI surface; `features.buddy: false` hides it)                                               |
+
+Each `guard` hook takes `name` · `tools` (array) · `run` — plus optional `pathFilter` (glob),
+`mode` (`inject` default, or `append`), `debounceMs` (2000), `timeoutMs` (60000), `onSuccess`
+(`silent`/`notify`), and `maxDeferMs` (300000 — how long `inject` waits for an idle session
+before reporting anyway).
+
+On a project's first run, overclock reports what it added. Worth knowing that installing it
+grants the agent **background shell execution** (`task_run`) and **recurring scheduling**
+(`schedule_create`). The tool definitions themselves cost ~800 tokens of context in total.
+
 ## Features
 
-| Module        | Tools                                                      | Does                                                                                                         |
-| ------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `tasks`       | `task_run` `task_status` `task_output` `task_kill`         | background shell cmds; exit -> result posted back into session; stall watchdog nudges on interactive prompts |
-| `sched`       | `schedule_create` `schedule_list` `schedule_delete`        | cron exprs or intervals ("5m"); interval + current session = loop; restart-safe                              |
-| `sandbox`     | `bash_unsandboxed` (escape hatch)                          | bwrap-wrap every bash call: `/` ro, project + `/tmp` rw, net configurable. Opt-in                            |
-| `guard`       | —                                                          | user hooks: after matching tool calls, run configured cmds (debounced), failures fed back to model           |
-| `usage`       | `usage_report`                                             | per-day + per-session cost/token telemetry off `message.updated` events                                      |
-| `checkpoints` | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` | session revert/unrevert over opencode's shadow-git snapshots; revert gated by permission ask                 |
+| Module        | Tools                                                      | Does                                                                                                                      |
+| ------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `tasks`       | `task_run` `task_status` `task_output` `task_kill`         | background shell cmds; exit -> result posted back into session; stall watchdog nudges on interactive prompts              |
+| `sched`       | `schedule_create` `schedule_list` `schedule_delete`        | cron exprs or intervals ("5m"); interval + current session = loop; restart-safe                                           |
+| `sandbox`     | `bash_unsandboxed` (escape hatch)                          | bwrap-wrap every bash call: `/` ro, project + `/tmp` rw, net configurable. Opt-in                                         |
+| `guard`       | —                                                          | user hooks: after matching tool calls, run configured cmds (debounced), failures fed back to model once the session idles |
+| `usage`       | `usage_report`                                             | per-day + per-session cost/token telemetry off `message.updated` events                                                   |
+| `checkpoints` | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` | session revert/unrevert over opencode's shadow-git snapshots; revert gated by permission ask                              |
+| `buddy`       | —                                                          | ASCII pet beside the prompt (TUI): hatches once per install, idles/blinks, reacts to session events; `/oc-buddy` pets it  |
 
-TUI plugin (`src/tui.ts`, separate surface): OS notifications on idle/permission/question/error via `attention.notify`, slash commands for tasks/usage/schedules off the `.opencode/overclock/` state mirrors.
+TUI plugin (`src/tui.ts`, separate surface): OS notifications on idle/permission/question/error via `attention.notify`, slash commands for tasks/usage/schedules off the `.opencode/overclock/` state mirrors, and the buddy (`src/buddy/`) in the prompt-right slots. The buddy rolls species/rarity/name/stats once (persisted in TUI kv), hides below 100 columns, and needs `@opentui/solid` resolvable at runtime -- if it isn't, the buddy silently sits this one out while the rest of the TUI plugin loads.
 
 ## Layout
 
@@ -107,6 +130,11 @@ proves an installed-from-npm session actually gets the tools; run it after every
 2. Edit `src/`. No hot reload -> restart opencode.
 3. State inspect: `.opencode/overclock/` (gitignored).
 
+Gotcha: if `~/.config/opencode/tui.json` also loads `opencode-overclock` from npm, that copy
+wins the `overclock-tui` id and the local dev TUI plugin (and any unpublished feature, e.g.
+the buddy) silently never loads. Remove the global entry while developing, or run with
+`XDG_CONFIG_HOME` pointed elsewhere.
+
 ### Headless e2e
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-overclock",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Power-ups for opencode: background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Modular, toggleable.",
   "type": "module",
   "repository": {
@@ -41,7 +41,16 @@
     "@opencode-ai/plugin": "1.18.9",
     "croner": "^10.0.1"
   },
+  "peerDependencies": {
+    "@opentui/solid": ">=0.4.5"
+  },
+  "peerDependenciesMeta": {
+    "@opentui/solid": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@opentui/solid": "0.4.5",
     "@types/bun": "latest",
     "prettier": "^3.9.6",
     "typescript": "^5.7.0"

package/src/buddy/companion.ts

@@ -0,0 +1,78 @@
+import { SPECIES, type Companion, type CompanionStats, type Rarity } from "./types.ts"
+
+const RARITY_WEIGHTS: { rarity: Rarity; weight: number }[] = [
+  { rarity: "common", weight: 60 },
+  { rarity: "uncommon", weight: 25 },
+  { rarity: "rare", weight: 10 },
+  { rarity: "legendary", weight: 5 },
+]
+
+const NAME_POOL = [
+  "Biscuit",
+  "Ember",
+  "Noodle",
+  "Pixel",
+  "Rune",
+  "Static",
+  "Widget",
+  "Zephyr",
+  "Marble",
+  "Gizmo",
+  "Puddle",
+  "Cinder",
+  "Quokka",
+  "Kernel",
+  "Sprocket",
+]
+
+/** Deterministic PRNG for tests -- production uses Math.random via the default param. */
+export function mulberry32(seed: number): () => number {
+  let a = seed | 0
+  return () => {
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+function pick<T>(rng: () => number, pool: readonly T[]): T {
+  return pool[Math.floor(rng() * pool.length)]!
+}
+
+function rollRarity(rng: () => number): Rarity {
+  const total = RARITY_WEIGHTS.reduce((sum, e) => sum + e.weight, 0)
+  let r = rng() * total
+  for (const entry of RARITY_WEIGHTS) {
+    if (r < entry.weight) return entry.rarity
+    r -= entry.weight
+  }
+  return RARITY_WEIGHTS[RARITY_WEIGHTS.length - 1]!.rarity
+}
+
+function rollStat(rng: () => number): number {
+  return 1 + Math.floor(rng() * 10)
+}
+
+/** One-line card for the /oc-buddy toast. */
+export function describeCompanion(c: Companion): string {
+  const s = c.stats
+  return `${c.name} the ${c.rarity} ${c.species} · patience ${s.patience} chaos ${s.chaos} wisdom ${s.wisdom} snark ${s.snark}`
+}
+
+/** Pure: roll a fresh companion. Called once at hatch, then persisted -- never re-rolled. */
+export function rollCompanion(rng: () => number = Math.random, now: number = Date.now()): Companion {
+  const stats: CompanionStats = {
+    patience: rollStat(rng),
+    chaos: rollStat(rng),
+    wisdom: rollStat(rng),
+    snark: rollStat(rng),
+  }
+  return {
+    species: pick(rng, SPECIES),
+    rarity: rollRarity(rng),
+    name: pick(rng, NAME_POOL),
+    stats,
+    hatchedAt: now,
+  }
+}

package/src/buddy/reactions.ts

@@ -0,0 +1,41 @@
+import type { SpriteState } from "./sprites.ts"
+
+export type ReactionKind = "done" | "error" | "permission" | "question" | "pet"
+
+/** Speech-bubble line + which face the sprite pulls while it shows. */
+export interface Reaction {
+  text: string
+  state: SpriteState
+}
+
+// Lines render into the sprite's 12-col effect row -- keep every line <= 12 chars.
+const POOLS: Record<ReactionKind, { lines: string[]; state: SpriteState }> = {
+  done: { lines: ["done!", "all set.", "ship it.", "*stretch*"], state: "idle" },
+  error: { lines: ["uh oh.", "*winces*", "yikes."], state: "alarmed" },
+  permission: { lines: ["can we?", "*peeks*", "please?"], state: "curious" },
+  question: { lines: ["your call.", "hmm?", "*head tilt*"], state: "curious" },
+  pet: { lines: ["<3", "*purrs*", "hi!!", "missed you."], state: "pet" },
+}
+
+/** Pure: pick a random line for a reaction kind. */
+export function pickReaction(kind: ReactionKind, rng: () => number = Math.random): Reaction {
+  const pool = POOLS[kind]
+  return { text: pool.lines[Math.floor(rng() * pool.lines.length)]!, state: pool.state }
+}
+
+export interface ReactionGate {
+  /** True + arms the cooldown if enough time has passed since the last fire. */
+  tryFire(now?: number): boolean
+}
+
+/** Debounce for event-driven reactions -- keeps a busy session from spamming the bubble. */
+export function createReactionGate(cooldownMs = 8000): ReactionGate {
+  let last = -Infinity
+  return {
+    tryFire(now: number = Date.now()): boolean {
+      if (now - last < cooldownMs) return false
+      last = now
+      return true
+    },
+  }
+}

package/src/buddy/sprites.ts

@@ -0,0 +1,115 @@
+import type { Species } from "./types.ts"
+
+/**
+ * Every frame is padded to exactly SPRITE_WIDTH columns so animation never
+ * causes layout reflow. Height is per-species (see spriteHeight) and is *not*
+ * padded: the buddy is mounted as a bottom-anchored absolute overlay, so a
+ * trailing blank row would lift the creature off the agent/model line.
+ */
+export const SPRITE_WIDTH = 12
+/**
+ * Tallest a frame can get: 1 effect row + a 3-row body. The prompt box is 4 rows
+ * tall with an empty input, so staying within this keeps the buddy -- bubble row
+ * included -- from drawing above the box and onto the transcript.
+ */
+export const SPRITE_MAX_HEIGHT = 4
+
+export type SpriteState = "idle" | "pet" | "alarmed" | "curious" | "sleep"
+
+/**
+ * Frames are body templates, not full art per state: `{E}` is replaced by a
+ * 3-char eye string, and a top "effect" line floats <3 / ! / ? / z above the
+ * head. One drawing per species (plus a fidget frame) covers every state.
+ */
+const EYES = {
+  open: "o.o",
+  blink: "-.-",
+  pet: "^.^",
+  alarmed: "O.O",
+  sleep: "-.-",
+} as const
+
+interface SpeciesArt {
+  /** Two body frames, alternated while idle: tail flick, ear twitch, wing flap... */
+  idle: [string[], string[]]
+}
+
+const ART: Record<Species, SpeciesArt> = {
+  cat: {
+    idle: [
+      [" /\\_/\\", "( {E} )", " > ^ <"],
+      [" /\\_/\\", "( {E} )", " > ^ <~"],
+    ],
+  },
+  dog: {
+    idle: [
+      [" /^-^\\", "( {E} )", "/  ~  \\"],
+      [" /^-^/", "( {E} )", "/  ~  \\"],
+    ],
+  },
+  dragon: {
+    idle: [
+      ["  /\\~/\\", " ( {E} )", "<(  v  )>"],
+      ["  /\\~/\\", " ( {E} )", "^(  v  )^"],
+    ],
+  },
+  ghost: {
+    idle: [
+      ["  .-.", " ({E})", " '\"'\"'"],
+      ["  .-.", " ({E})", ' ~"~"~'],
+    ],
+  },
+  slime: {
+    idle: [
+      ["   ___", "  ({E})", " (_____)"],
+      ["  ___", " (({E}))", "(_______)"],
+    ],
+  },
+}
+
+const BLINK_EVERY = 7
+
+/** Effect row on top, body below it, every row padded to SPRITE_WIDTH. */
+function compose(effect: string, body: readonly string[], eyes: string): string {
+  const lines = [effect, ...body.map((l) => l.replace("{E}", eyes))]
+  return lines.map((l) => l.slice(0, SPRITE_WIDTH).padEnd(SPRITE_WIDTH)).join("\n")
+}
+
+/**
+ * Rows a species' frames occupy: constant across states and ticks, so the host
+ * node can be sized once at mount and never resized mid-animation.
+ */
+export function spriteHeight(species: Species): number {
+  return 1 + ART[species].idle[0].length
+}
+
+/** Pure: overlay a speech line onto the frame's effect row (line 0), truncated to width. */
+export function withBubble(frame: string, bubble: string | undefined): string {
+  if (!bubble) return frame
+  const lines = frame.split("\n")
+  lines[0] = bubble.slice(0, SPRITE_WIDTH).padEnd(SPRITE_WIDTH)
+  return lines.join("\n")
+}
+
+/** Pure: render one frame. `tick` drives idle fidget + blink; other states are static. */
+export function spriteFrame(species: Species, state: SpriteState, tick: number): string {
+  const art = ART[species]
+  const t = ((tick % 1000) + 1000) % 1000
+  const body = art.idle[t % 2]!
+  const rest = art.idle[0]!
+
+  switch (state) {
+    case "idle": {
+      const eyes = t % BLINK_EVERY === BLINK_EVERY - 1 ? EYES.blink : EYES.open
+      return compose("", body, eyes)
+    }
+    case "pet":
+      return compose("     <3", rest, EYES.pet)
+    case "alarmed":
+      return compose("     !", rest, EYES.alarmed)
+    case "curious":
+      return compose("     ?", rest, EYES.open)
+    case "sleep":
+      return compose("     z Z", rest, EYES.sleep)
+  }
+}

package/src/buddy/tui.ts

@@ -0,0 +1,171 @@
+import type { TuiPluginApi, TuiThemeCurrent } from "@opencode-ai/plugin/tui"
+import { rollCompanion, describeCompanion } from "./companion.ts"
+import type { Companion, Rarity } from "./types.ts"
+import { spriteFrame, withBubble, spriteHeight, SPRITE_WIDTH, type SpriteState } from "./sprites.ts"
+import { pickReaction, createReactionGate, type ReactionKind } from "./reactions.ts"
+
+const KV_KEY = "buddy.companion"
+/** Below this terminal width the buddy hides rather than crowd the prompt. */
+const MIN_COLS = 100
+const TICK_MS = 500
+const BUBBLE_MS = 6000
+const SLEEP_AFTER_MS = 120_000
+
+/**
+ * Structural view of the opentui TextRenderable we mutate. The buddy is updated
+ * imperatively through refs instead of solid signals on purpose: reactivity would
+ * silently break if the plugin's solid-js instance ever differs from the host's,
+ * while direct property sets on host-created nodes always work.
+ */
+interface SpriteNode {
+  content: string
+  visible: boolean
+  destroyed?: boolean
+}
+
+function rarityColor(rarity: Rarity, theme: TuiThemeCurrent): unknown {
+  switch (rarity) {
+    case "legendary":
+      return theme.accent
+    case "rare":
+      return theme.info
+    case "uncommon":
+      return theme.success
+    default:
+      return theme.textMuted
+  }
+}
+
+/**
+ * Hatch (or load) the companion and mount it in the prompt-right slots.
+ * Dynamic import of @opentui/solid: if the host doesn't map the specifier to its
+ * own instance, this throws and the caller degrades to "no buddy" -- it must
+ * never take the rest of the TUI plugin down.
+ */
+export async function registerBuddy(api: TuiPluginApi): Promise<void> {
+  const { jsx } = (await import("@opentui/solid/jsx-runtime")) as unknown as {
+    jsx: (type: string, props?: Record<string, unknown> | null) => unknown
+  }
+
+  let companion = api.kv.get<Companion | undefined>(KV_KEY, undefined)
+  if (!companion) {
+    companion = rollCompanion()
+    api.kv.set(KV_KEY, companion)
+    api.ui.toast({ message: `a buddy hatched: ${describeCompanion(companion)}` })
+  }
+  const hatched: Companion = companion
+
+  // One ticker drives every mounted node (home + session slots).
+  const nodes = new Set<SpriteNode>()
+  let tick = 0
+  let bubble: string | undefined
+  let bubbleUntil = 0
+  let faceOverride: SpriteState | undefined
+  let lastActivity = Date.now()
+
+  function currentState(now: number): SpriteState {
+    if (faceOverride && now < bubbleUntil) return faceOverride
+    if (now - lastActivity > SLEEP_AFTER_MS) return "sleep"
+    return "idle"
+  }
+
+  function paint(): void {
+    const now = Date.now()
+    const frame = spriteFrame(hatched.species, currentState(now), tick)
+    const text = withBubble(frame, now < bubbleUntil ? bubble : undefined)
+    const wide = api.renderer.width >= MIN_COLS
+    for (const node of [...nodes]) {
+      try {
+        if (node.destroyed) {
+          nodes.delete(node)
+          continue
+        }
+        node.visible = wide
+        if (wide) node.content = text
+      } catch {
+        nodes.delete(node)
+      }
+    }
+  }
+
+  function react(kind: ReactionKind): void {
+    const reaction = pickReaction(kind)
+    bubble = reaction.text
+    bubbleUntil = Date.now() + BUBBLE_MS
+    faceOverride = reaction.state
+    lastActivity = Date.now()
+    paint()
+  }
+
+  const timer = setInterval(() => {
+    tick++
+    paint()
+  }, TICK_MS)
+  api.lifecycle.onDispose(async () => clearInterval(timer))
+
+  const gate = createReactionGate()
+  const unsubs = [
+    api.event.on("session.status", (event) => {
+      lastActivity = Date.now()
+      if (event.properties.status.type === "idle" && gate.tryFire()) react("done")
+    }),
+    api.event.on("session.error", () => {
+      if (gate.tryFire()) react("error")
+    }),
+    api.event.on("permission.asked", () => {
+      if (gate.tryFire()) react("permission")
+    }),
+    api.event.on("question.asked", () => {
+      if (gate.tryFire()) react("question")
+    }),
+  ]
+  for (const unsub of unsubs) api.lifecycle.onDispose(async () => unsub())
+
+  // The host renders the slot inside a one-line flex row next to the agent/model
+  // text (prompt/index.tsx: justifyContent="space-between"). An in-flow sprite
+  // would stretch that row -- and the whole prompt box -- by its full height, so
+  // it goes out of flow instead: yoga places absolute children against their
+  // parent's edges, and bottom/right pin the creature's last row onto the
+  // agent/model line while it grows upward over the (usually empty) input area.
+  const renderSprite = (theme: TuiThemeCurrent) =>
+    jsx("text", {
+      position: "absolute",
+      bottom: 0,
+      right: 0,
+      width: SPRITE_WIDTH,
+      height: spriteHeight(hatched.species),
+      content: spriteFrame(hatched.species, "idle", tick),
+      fg: rarityColor(hatched.rarity, theme),
+      selectable: false,
+      visible: api.renderer.width >= MIN_COLS,
+      ref: (node: SpriteNode | undefined) => {
+        if (node) nodes.add(node)
+      },
+    })
+
+  // register returns the assigned plugin id, not a disposer -- the host owns
+  // slot cleanup when the TUI plugin deactivates.
+  api.slots.register({
+    slots: {
+      home_prompt_right: (ctx) => renderSprite(ctx.theme.current),
+      session_prompt_right: (ctx) => renderSprite(ctx.theme.current),
+    },
+  })
+
+  try {
+    const uncommand = api.command?.register(() => [
+      {
+        title: "Overclock: Pet buddy",
+        value: "overclock.buddy",
+        slash: { name: "oc-buddy" },
+        onSelect: async () => {
+          react("pet")
+          api.ui.toast({ message: describeCompanion(hatched) })
+        },
+      },
+    ])
+    if (uncommand) api.lifecycle.onDispose(async () => uncommand())
+  } catch (e) {
+    console.warn(`[overclock-tui] /oc-buddy command registration failed: ${e}`)
+  }
+}

package/src/buddy/types.ts

@@ -0,0 +1,20 @@
+export const SPECIES = ["cat", "dog", "dragon", "ghost", "slime"] as const
+export type Species = (typeof SPECIES)[number]
+
+export type Rarity = "common" | "uncommon" | "rare" | "legendary"
+
+export interface CompanionStats {
+  patience: number
+  chaos: number
+  wisdom: number
+  snark: number
+}
+
+/** Persisted in TUI kv. Rolled once at hatch, then stable for the life of the install. */
+export interface Companion {
+  species: Species
+  rarity: Rarity
+  name: string
+  stats: CompanionStats
+  hatchedAt: number
+}

package/src/features/buddy.ts

@@ -0,0 +1,15 @@
+import type { FeatureModule } from "../types.ts"
+
+/**
+ * Buddy is a TUI-surface feature (src/buddy/, wired in src/tui.ts): an ASCII pet
+ * beside the prompt. This server module registers no hooks or tools -- it exists
+ * so `features.buddy` validates in overclock.json (one config file toggles both
+ * surfaces) and the first-run summary mentions it.
+ */
+export const buddy: FeatureModule = {
+  name: "buddy",
+  defaultEnabled: true,
+  async init() {
+    return {}
+  },
+}

package/src/features/checkpoints.ts

@@ -81,6 +81,7 @@ export function createCheckpoints(client: Client): Checkpoints {
  */
 export const checkpoints: FeatureModule = {
   name: "checkpoints",
+  tools: ["checkpoint_list", "checkpoint_revert", "checkpoint_restore"],
   defaultEnabled: true,
   requires: ["session.revert", "session.unrevert", "session.messages"],
   async init(ctx) {

package/src/features/guard.ts

@@ -10,6 +10,8 @@ export interface GuardHook {
   debounceMs: number
   timeoutMs: number
   onSuccess: "silent" | "notify"
+  /** inject mode: give up deferring past a busy session after this long, and report anyway. */
+  maxDeferMs: number
 }
 
 /** options.hooks -> validated GuardHook[]. Invalid entries -> console.warn, skipped, never throw. */
@@ -33,6 +35,7 @@ export function parseHooks(raw: unknown): GuardHook[] {
       debounceMs: typeof e.debounceMs === "number" ? e.debounceMs : 2000,
       timeoutMs: typeof e.timeoutMs === "number" ? e.timeoutMs : 60000,
       onSuccess: e.onSuccess === "notify" ? "notify" : "silent",
+      maxDeferMs: typeof e.maxDeferMs === "number" ? e.maxDeferMs : 300000,
     })
   }
   return hooks
@@ -85,12 +88,18 @@ interface HookState {
   lastToolName: string
   lastFilePath?: string
   procs: Set<Bun.Subprocess>
+  /** when the current run of deferrals started, for the maxDeferMs cap */
+  deferredSince?: number
+  /** last payload actually injected, to avoid re-reporting a standing failure */
+  lastInjectedPayload?: string
 }
 
 export interface GuardRunnerDeps {
   cwd: string
   onInject: (sessionID: string, payload: string) => Promise<void>
   onNotify: (hookName: string) => Promise<void>
+  /** omitted -> never busy, i.e. the old always-inject behaviour */
+  isBusy?: (sessionID: string) => boolean
 }
 
 export interface GuardRunner {
@@ -134,8 +143,20 @@ export function createGuardRunner(deps: GuardRunnerDeps): GuardRunner {
       s.timer = setTimeout(() => void fire(hook), hook.debounceMs)
       return
     }
-    s.running = true
     const sessionID = s.lastSessionID
+    // Agent still mid-turn: the tree is in flux, so any verdict we reach now may already be
+    // stale by the time it's read. Re-arm instead. The recheck doubles as dedup -- if the
+    // agent fixed the fault itself, the later run exits 0 and we stay silent.
+    if (sessionID && deps.isBusy?.(sessionID)) {
+      s.deferredSince ??= Date.now()
+      if (Date.now() - s.deferredSince < hook.maxDeferMs) {
+        s.timer = setTimeout(() => void fire(hook), hook.debounceMs)
+        return
+      }
+      // deferred too long -- session may be wedged. Report anyway rather than never.
+    }
+    s.deferredSince = undefined
+    s.running = true
     const toolName = s.lastToolName
     const filePath = s.lastFilePath
     try {
@@ -143,10 +164,18 @@ export function createGuardRunner(deps: GuardRunnerDeps): GuardRunner {
         s.procs.add(p),
       )
       if (result.code !== 0) {
-        if (sessionID)
-          await deps.onInject(sessionID, failurePayload(hook.name, result.code, result.combined))
-      } else if (hook.onSuccess === "notify") {
-        await deps.onNotify(hook.name)
+        const payload = failurePayload(hook.name, result.code, result.combined)
+        // Backstop to the idle gate above: a fault the agent can't fix would otherwise
+        // re-inject on every idle cycle forever. Report transitions, not standing state.
+        // Exact-match is deliberately conservative -- it only ever suppresses a report
+        // that is byte-identical to the one the agent has already seen and failed to clear.
+        if (sessionID && payload !== s.lastInjectedPayload) {
+          await deps.onInject(sessionID, payload)
+          s.lastInjectedPayload = payload
+        }
+      } else {
+        s.lastInjectedPayload = undefined
+        if (hook.onSuccess === "notify") await deps.onNotify(hook.name)
       }
     } finally {
       s.running = false
@@ -181,13 +210,18 @@ export function createGuardRunner(deps: GuardRunnerDeps): GuardRunner {
 /**
  * User-configurable post-tool hooks. Run commands after matching tool calls. No config -> inert.
  * "append": run synchronously, failure appended to tool output in place.
- * "inject" (default): debounced per hook name, failure injected as a user turn.
+ * "inject" (default): debounced per hook name, failure injected as a user turn once the
+ * session goes idle. Firing mid-turn doesn't interrupt (promptAsync queues), but each
+ * fire queues its own turn, so a burst of edits stacks several reports of a fault the
+ * agent was already fixing -- and reports it from a tree that was still being edited.
  */
 export const guard: FeatureModule = {
   name: "guard",
+  tools: [],
+  options: { hooks: "array" },
   defaultEnabled: true,
   requires: ["session.promptAsync", "session.messages"],
-  async init(ctx, options) {
+  async init(ctx, options, shared) {
     if (options.hooks !== undefined && !Array.isArray(options.hooks)) {
       console.warn(`[overclock] guard: options.hooks must be an array, got ${typeof options.hooks}`)
     }
@@ -202,6 +236,7 @@ export const guard: FeatureModule = {
       onNotify: async (hookName) => {
         await toast(ctx.client, `guard "${hookName}" passed`, "success")
       },
+      isBusy: (sessionID) => shared.busy.isBusy(sessionID),
     })
 
     return {

package/src/features/index.ts

@@ -5,6 +5,7 @@ import { sandbox } from "./sandbox.ts"
 import { guard } from "./guard.ts"
 import { usage } from "./usage.ts"
 import { checkpoints } from "./checkpoints.ts"
+import { buddy } from "./buddy.ts"
 
 /** Registry, ordered. Order = hook composition order. */
-export const features: FeatureModule[] = [tasks, sched, sandbox, guard, usage, checkpoints]
+export const features: FeatureModule[] = [tasks, sched, sandbox, guard, usage, checkpoints, buddy]

package/src/features/sandbox.ts

@@ -51,6 +51,8 @@ export function probeBwrap(): boolean {
  */
 export const sandbox: FeatureModule = {
   name: "sandbox",
+  tools: ["bash_unsandboxed"],
+  options: { net: "boolean" },
   defaultEnabled: false,
   async init(ctx, options) {
     const policy: SandboxPolicy = {

package/src/features/sched.ts

@@ -3,7 +3,6 @@ import { Cron } from "croner"
 import type { FeatureModule } from "../types.ts"
 import { ensureStateDir, readJson, writeJson } from "../lib/state.ts"
 import { inject, toast } from "../lib/inject.ts"
-import { createBusyTracker } from "../lib/busy.ts"
 
 const z = tool.schema
 
@@ -34,15 +33,16 @@ interface Schedule {
  */
 export const sched: FeatureModule = {
   name: "sched",
+  tools: ["schedule_create", "schedule_list", "schedule_delete"],
+  options: { skipIfBusy: "boolean" },
   defaultEnabled: true,
   requires: ["session.promptAsync", "session.messages", "session.create"],
-  async init(ctx, options) {
+  async init(ctx, options, shared) {
     const dir = await ensureStateDir(ctx.directory)
     const storePath = `${dir}/schedules.json`
     const schedules = new Map<string, Schedule>()
     const timers = new Map<string, Cron | ReturnType<typeof setInterval>>()
     const skipIfBusy = options.skipIfBusy !== false
-    const busy = createBusyTracker()
 
     const persist = () => writeJson(storePath, [...schedules.values()])
 
@@ -50,7 +50,7 @@ export const sched: FeatureModule = {
       try {
         if (s.target === "current") {
           // target still chewing on previous turn -> skip this fire, no pileup
-          if (skipIfBusy && busy.isBusy(s.sessionID)) {
+          if (skipIfBusy && shared.busy.isBusy(s.sessionID)) {
             await toast(ctx.client, `schedule ${s.id} skipped (session busy)`, "info")
             return
           }
@@ -103,7 +103,6 @@ export const sched: FeatureModule = {
     }
 
     return {
-      event: async ({ event }) => busy.onEvent(event),
       dispose: async () => {
         for (const id of [...timers.keys()]) disarm(id)
       },

package/src/features/tasks.ts

@@ -236,6 +236,13 @@ const fmt = (t: TaskRecord) =>
  */
 export const tasks: FeatureModule = {
   name: "tasks",
+  tools: ["task_run", "task_status", "task_output", "task_kill"],
+  options: {
+    killOnExit: "boolean",
+    stallDetection: "boolean",
+    stallThresholdMs: "number",
+    stallCheckIntervalMs: "number",
+  },
   defaultEnabled: true,
   requires: ["session.promptAsync", "session.messages"],
   async init(ctx, options) {

package/src/features/usage.ts

@@ -236,6 +236,7 @@ export function createUsageTracker(opts: UsageTrackerOpts): UsageTracker {
  */
 export const usage: FeatureModule = {
   name: "usage",
+  tools: ["usage_report"],
   defaultEnabled: true,
   async init(ctx) {
     const dir = await ensureStateDir(ctx.directory)

package/src/index.ts

@@ -1,9 +1,13 @@
-import type { Plugin } from "@opencode-ai/plugin"
+import type { Hooks, Plugin } from "@opencode-ai/plugin"
 import { features } from "./features/index.ts"
 import { loadConfig } from "./config.ts"
 import { mergeHooks } from "./merge.ts"
 import { missingSurfaces } from "./lib/probe.ts"
 import { toast } from "./lib/inject.ts"
+import { firstRun } from "./lib/state.ts"
+import { validateConfig, summarise } from "./validate.ts"
+import { createBusyTracker } from "./lib/busy.ts"
+import type { FeatureModule, SharedDeps } from "./types.ts"
 
 /**
  * Entry. Load config -> probe surfaces -> init enabled modules -> merge hooks.
@@ -11,8 +15,27 @@ import { toast } from "./lib/inject.ts"
  */
 export const Overclock: Plugin = async (ctx) => {
   const config = await loadConfig(ctx.directory)
-  const parts = []
+
+  // A mistyped key is otherwise a silent no-op -- the feature runs with defaults and the
+  // user believes their setting took effect. Warn, never throw: bad config degrades to
+  // defaults rather than taking the plugin down.
+  const issues = validateConfig(config, features)
+  for (const issue of issues) {
+    console.warn(`[overclock] config: ${issue.path ? `${issue.path}: ` : ""}${issue.message}`)
+  }
+  if (issues.length) {
+    void toast(
+      ctx.client,
+      `overclock: ${issues.length} config issue${issues.length > 1 ? "s" : ""} (see logs) -- using defaults for those`,
+      "warning",
+    )
+  }
+
+  const shared: SharedDeps = { busy: createBusyTracker() }
+  // First part, so the tracker is current before any module's own event hook reads it.
+  const parts: Partial<Hooks>[] = [{ event: async ({ event }) => shared.busy.onEvent(event) }]
   const skipped: string[] = []
+  const enabled: FeatureModule[] = []
 
   for (const feature of features) {
     const setting = config.features?.[feature.name] ?? feature.defaultEnabled
@@ -27,12 +50,21 @@ export const Overclock: Plugin = async (ctx) => {
     }
     const options = typeof setting === "object" ? setting : {}
     try {
-      parts.push(await feature.init(ctx, options))
+      parts.push(await feature.init(ctx, options, shared))
+      enabled.push(feature)
     } catch (e) {
       console.warn(`[overclock] feature ${feature.name} failed init: ${e}`)
     }
   }
 
+  // Say what was added. This plugin grants the agent background shell execution and
+  // recurring scheduling; that should not be discovered by accident. Log every start
+  // (stderr, invisible unless you look), toast only on a project's first run.
+  console.warn(`[overclock] ${summarise(enabled, skipped)}`)
+  if (await firstRun(ctx.directory)) {
+    void toast(ctx.client, `overclock active: ${summarise(enabled, skipped)}`, "info")
+  }
+
   if (skipped.length)
     void toast(ctx.client, `overclock: ${skipped.join(", ")} disabled (SDK drift)`, "warning")
   return mergeHooks(parts)

package/src/lib/state.ts

@@ -7,6 +7,18 @@ export async function ensureStateDir(directory: string, sub?: string): Promise<s
   return dir
 }
 
+/**
+ * True once per project, then never again. Marker lives beside the other state, so
+ * deleting .opencode/overclock/ re-arms the first-run notice.
+ */
+export async function firstRun(directory: string): Promise<boolean> {
+  const dir = await ensureStateDir(directory)
+  const marker = Bun.file(`${dir}/.installed`)
+  if (await marker.exists()) return false
+  await Bun.write(marker, new Date().toISOString())
+  return true
+}
+
 export async function readJson<T>(path: string, fallback: T): Promise<T> {
   const file = Bun.file(path)
   if (!(await file.exists())) return fallback

package/src/tui.ts

@@ -1,4 +1,5 @@
 import type { TuiPlugin, TuiPluginModule } from "@opencode-ai/plugin/tui"
+import { registerBuddy } from "./buddy/tui.ts"
 
 const STATE_SUBDIR = ".opencode/overclock"
 
@@ -7,6 +8,23 @@ export interface TuiOptions {
   notifyPermission?: boolean
   notifyQuestion?: boolean
   notifyError?: boolean
+  buddy?: boolean
+}
+
+/**
+ * The buddy toggles from the same overclock.json as the server features, so one
+ * config file governs both surfaces. `features.buddy: false` disables; missing
+ * file or unreadable config = default on.
+ */
+export async function buddyEnabledInConfig(directory: string): Promise<boolean> {
+  try {
+    const file = Bun.file(`${directory}/.opencode/overclock.json`)
+    if (!(await file.exists())) return true
+    const config = (await file.json()) as { features?: Record<string, unknown> }
+    return config.features?.["buddy"] !== false
+  } catch {
+    return true
+  }
 }
 
 export interface TaskMirrorEntry {
@@ -222,6 +240,16 @@ const tui: TuiPlugin = async (api, options) => {
   } catch (e) {
     console.warn(`[overclock-tui] /oc-schedules command registration failed: ${e}`)
   }
+
+  // ASCII pet beside the prompt. Anything here failing (missing @opentui/solid,
+  // slot API drift) must degrade to "no buddy", never take the notifications down.
+  try {
+    if (opts.buddy !== false && (await buddyEnabledInConfig(api.state.path.directory))) {
+      await registerBuddy(api)
+    }
+  } catch (e) {
+    console.warn(`[overclock-tui] buddy disabled: ${e}`)
+  }
 }
 
 export default { id: "overclock-tui", tui } satisfies TuiPluginModule

package/src/types.ts

@@ -1,8 +1,22 @@
 import type { Hooks, PluginInput } from "@opencode-ai/plugin"
+import type { BusyTracker } from "./lib/busy.ts"
+
+/**
+ * Singletons built once by the entry and handed to every module.
+ * Derived from the event bus, so they must have exactly one subscription -- a per-module
+ * copy would be N subscriptions maintaining N identical copies of the same state.
+ */
+export interface SharedDeps {
+  /** live per-session busy/idle state; the entry owns the subscription that feeds it */
+  busy: BusyTracker
+}
 
 /** Per-feature config from .opencode/overclock.json. `false` = off, object = options. */
 export type FeatureConfig = boolean | Record<string, unknown>
 
+/** Option value kinds a module declares, so a typo in overclock.json can be caught. */
+export type OptionType = "boolean" | "number" | "string" | "array" | "object"
+
 export interface OverclockConfig {
   features?: Record<string, FeatureConfig>
 }
@@ -17,5 +31,9 @@ export interface FeatureModule {
   defaultEnabled: boolean
   /** SDK client surfaces (dot-paths) the module needs. Missing -> module skipped + warn. */
   requires?: string[]
-  init(ctx: PluginInput, options: Record<string, unknown>): Promise<Partial<Hooks>>
+  /** Tool names registered. Declared, not derived -- feeds the first-run summary. */
+  tools?: string[]
+  /** Accepted option keys -> expected type. Anything else in config is a typo. */
+  options?: Record<string, OptionType>
+  init(ctx: PluginInput, options: Record<string, unknown>, shared: SharedDeps): Promise<Partial<Hooks>>
 }

package/src/validate.ts

@@ -0,0 +1,143 @@
+import type { FeatureModule, OptionType } from "./types.ts"
+
+export interface ConfigIssue {
+  /** dotted location in overclock.json, e.g. "features.tasks.killOnExit" */
+  path: string
+  message: string
+}
+
+/** Levenshtein, capped -- only used to turn a typo into a "did you mean". */
+function distance(a: string, b: string): number {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  const cur = new Array<number>(b.length + 1)
+  for (let i = 1; i <= a.length; i++) {
+    cur[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev.splice(0, prev.length, ...cur)
+  }
+  return prev[b.length]
+}
+
+/** Closest known name within edit distance 2, else undefined. */
+function nearest(input: string, known: readonly string[]): string | undefined {
+  let best: string | undefined
+  let bestD = 3
+  for (const k of known) {
+    const d = distance(input.toLowerCase(), k.toLowerCase())
+    if (d < bestD) {
+      bestD = d
+      best = k
+    }
+  }
+  return best
+}
+
+function unknownKey(input: string, known: readonly string[], what: string): string {
+  const guess = nearest(input, known)
+  if (guess) return `unknown ${what} "${input}" -- did you mean "${guess}"?`
+  return `unknown ${what} "${input}". Known: ${known.join(", ")}`
+}
+
+function typeOf(v: unknown): OptionType | "null" {
+  if (v === null) return "null"
+  if (Array.isArray(v)) return "array"
+  const t = typeof v
+  if (t === "boolean" || t === "number" || t === "string" || t === "object") return t
+  return "object"
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+/**
+ * Check overclock.json against the feature registry.
+ *
+ * Exists because an unrecognised key is otherwise a silent no-op: `killOnExist: true`
+ * reads as "option not set", the feature runs with defaults, and nothing complains.
+ * Returns every issue found -- callers warn, never throw. A bad config degrades to
+ * defaults rather than taking the plugin down.
+ */
+export function validateConfig(config: unknown, features: readonly FeatureModule[]): ConfigIssue[] {
+  const issues: ConfigIssue[] = []
+  if (!isPlainObject(config)) {
+    return [{ path: "", message: `config must be an object, got ${typeOf(config)}` }]
+  }
+
+  const TOP = ["features"]
+  for (const key of Object.keys(config)) {
+    if (!TOP.includes(key)) issues.push({ path: key, message: unknownKey(key, TOP, "top-level key") })
+  }
+
+  const { features: featuresCfg } = config
+  if (featuresCfg === undefined) return issues
+  if (!isPlainObject(featuresCfg)) {
+    issues.push({
+      path: "features",
+      message: `"features" must be an object, got ${typeOf(featuresCfg)}`,
+    })
+    return issues
+  }
+
+  const names = features.map((f) => f.name)
+  for (const [name, setting] of Object.entries(featuresCfg)) {
+    const feature = features.find((f) => f.name === name)
+    if (!feature) {
+      issues.push({ path: `features.${name}`, message: unknownKey(name, names, "feature") })
+      continue
+    }
+    if (typeof setting === "boolean") continue
+    if (!isPlainObject(setting)) {
+      issues.push({
+        path: `features.${name}`,
+        message: `must be true, false, or an options object -- got ${typeOf(setting)}`,
+      })
+      continue
+    }
+
+    const schema = feature.options ?? {}
+    const optionNames = Object.keys(schema)
+    for (const [key, value] of Object.entries(setting)) {
+      const expected = schema[key]
+      if (!expected) {
+        issues.push({
+          path: `features.${name}.${key}`,
+          message: optionNames.length
+            ? unknownKey(key, optionNames, "option")
+            : `"${name}" takes no options, got "${key}"`,
+        })
+        continue
+      }
+      const actual = typeOf(value)
+      if (actual !== expected) {
+        issues.push({
+          path: `features.${name}.${key}`,
+          message: `expected ${expected}, got ${actual}`,
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+/**
+ * One-line inventory of what this plugin just added to the session.
+ *
+ * Not about context cost -- the full tool surface is only ~800 tokens. It is about
+ * capability: installing overclock hands the agent background shell execution and
+ * recurring scheduling, and that should not be something a user discovers by accident.
+ */
+export function summarise(enabled: readonly FeatureModule[], skipped: readonly string[]): string {
+  const toolCount = enabled.reduce((n, f) => n + (f.tools?.length ?? 0), 0)
+  const parts = enabled.map((f) => {
+    const tools = f.tools?.length ? ` (${f.tools.join(", ")})` : ""
+    return `${f.name}${tools}`
+  })
+  const plural = (n: number, word: string) => `${n} ${word}${n === 1 ? "" : "s"}`
+  let line = `${plural(enabled.length, "module")}, ${plural(toolCount, "tool")}: ${parts.join(" · ")}`
+  if (skipped.length) line += ` | skipped: ${skipped.join(", ")}`
+  return line
+}