@ramarivera/coding-buddy 0.7.0 → 0.7.2

package/hooks/suggest.sh

@@ -1,55 +1,11 @@
 #!/usr/bin/env bash
-# coding-buddy Stop hook — proactive suggestion detection
-# Detects coding patterns and offers suggestions when relevant.
-#
-# Combined with buddy-comment.sh to avoid running two separate Stop hooks.
-
-# shellcheck source=../scripts/paths.sh
-source "$(dirname "${BASH_SOURCE[0]}")/../scripts/paths.sh"
-
-STATE_DIR="$BUDDY_STATE_DIR"
-CONFIG_FILE="$STATE_DIR/config.json"
-LAST_SUGGESTION_FILE="$STATE_DIR/.last_suggestion"
-SUGGESTIONS_FILE="$STATE_DIR/suggestions.json"
-
-[ -f "$CONFIG_FILE" ] || exit 0
-
-# Check if suggestions are enabled (default: true)
-SUGGESTIONS_ENABLED="true"
-if [ -f "$CONFIG_FILE" ]; then
-    _enabled=$(jq -r '.suggestionsEnabled // true' "$CONFIG_FILE" 2>/dev/null)
-    [ "$_enabled" = "false" ] && exit 0
-fi
-
-# Check cooldown (default: 180s = 3 min)
-SUGGESTION_COOLDOWN=180
-if [ -f "$CONFIG_FILE" ]; then
-    _cd=$(jq -r '.suggestionCooldown // 180' "$CONFIG_FILE" 2>/dev/null || echo 180)
-    [[ "$_cd" =~ ^[0-9]+$ ]] && SUGGESTION_COOLDOWN=$_cd
-fi
-
-if [ -f "$LAST_SUGGESTION_FILE" ]; then
-    LAST=$(cat "$LAST_SUGGESTION_FILE" 2>/dev/null)
-    NOW=$(date +%s)
-    DIFF=$(( NOW - ${LAST:-0} ))
-    [ "$DIFF" -lt "$SUGGESTION_COOLDOWN" ] && exit 0
-fi
-
-INPUT=$(cat)
-
-# Extract messages
-ASSISTANT_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // ""' 2>/dev/null)
-[ -z "$ASSISTANT_MSG" ] && exit 0
-
-# Record turn and check patterns
-PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-
-# Check for patterns via the suggestions script
-if [ -x "$(command -v bun)" ]; then
-    # Run the suggestion check (async, non-blocking)
-    bun run "$PLUGIN_ROOT/server/check-suggestions.ts" \
-        "$(echo "$ASSISTANT_MSG" | jq -Rs .)" \
-        >/dev/null 2>&1 &
-fi
-
-exit 0
+set +e
+SCRIPT_DIR="${BASH_SOURCE[0]%/*}"
+ROOT="$(cd "$SCRIPT_DIR/.." 2>/dev/null && pwd)" || exit 0
+[ -n "$ROOT" ] || exit 0
+BUN="$(command -v bun 2>/dev/null || true)"
+[ -x "$BUN" ] || BUN="$HOME/.bun/bin/bun"
+[ -x "$BUN" ] || BUN="/opt/homebrew/bin/bun"
+[ -x "$BUN" ] || BUN="/usr/local/bin/bun"
+[ -x "$BUN" ] || exit 0
+exec "$BUN" run "$ROOT/server/hooks/suggest.ts" || exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ramarivera/coding-buddy",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Persistent coding companion for Claude Code, Pi, and Oh My Pi",
   "type": "module",
   "omp": {

package/server/hooks/buddy-comment.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  defaultSpawnDetached,
+  fileExists,
+  isOnCooldown,
+  nonNegativeInteger,
+  parseHookInput,
+  readJsonFile,
+  readStdin,
+  resolveHookSessionId,
+  resolveHookStateDir,
+  stringField,
+  type HookRuntime,
+} from "./common.ts";
+
+interface BuddyConfig {
+  commentCooldown?: unknown;
+}
+
+interface Events {
+  turns?: number;
+  [key: string]: unknown;
+}
+
+const BUDDY_COMMENT_PATTERN = /<!--\s*buddy:\s*([\s\S]*?)\s*-->/g;
+
+export interface BuddyCommentResult {
+  comment?: string;
+  updated: boolean;
+}
+
+export function extractBuddyComment(message: string): string {
+  let comment = "";
+  for (const match of message.matchAll(BUDDY_COMMENT_PATTERN)) {
+    const candidate = match[1]?.trim();
+    if (candidate) comment = candidate;
+  }
+  return comment;
+}
+
+export function handleBuddyComment(rawInput: string, runtime: HookRuntime = {}): BuddyCommentResult {
+  const stateDir = resolveHookStateDir(runtime);
+  if (!fileExists(join(stateDir, "status.json"))) return { updated: false };
+
+  const input = parseHookInput(rawInput);
+  if (!input) return { updated: false };
+
+  const assistantMessage = stringField(input, "last_assistant_message");
+  if (!assistantMessage) return { updated: false };
+
+  const comment = extractBuddyComment(assistantMessage);
+  if (!comment) return { updated: false };
+
+  const now = runtime.now?.() ?? Date.now();
+  const sid = resolveHookSessionId(runtime);
+  const config = readJsonFile<BuddyConfig>(join(stateDir, "config.json")) ?? {};
+  const cooldown = nonNegativeInteger(config.commentCooldown, 30);
+  const cooldownFile = join(stateDir, `.last_comment.${sid}`);
+  if (isOnCooldown(cooldownFile, cooldown, now)) return { updated: false };
+
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(cooldownFile, String(Math.floor(now / 1000)));
+  writeFileSync(
+    join(stateDir, `reaction.${sid}.json`),
+    JSON.stringify({ reaction: comment, timestamp: now, reason: "turn" }),
+  );
+
+  const eventsFile = join(stateDir, "events.json");
+  const events = readJsonFile<Events>(eventsFile) ?? {};
+  events.turns = (typeof events.turns === "number" ? events.turns : 0) + 1;
+  writeFileSync(eventsFile, JSON.stringify(events, null, 2));
+
+  const spawnDetached = runtime.spawnDetached ?? defaultSpawnDetached(runtime);
+  spawnDetached("server/award-xp.ts", ["turn"]);
+  spawnDetached("server/consolidate.ts", [
+    assistantMessage,
+    stringField(input, "last_user_message"),
+  ]);
+
+  return { comment, updated: true };
+}
+
+if (import.meta.main) {
+  try {
+    handleBuddyComment(await readStdin());
+  } catch {
+    // Claude Code hooks must never fail the turn.
+  }
+  process.exit(0);
+}

package/server/hooks/common.ts

@@ -0,0 +1,95 @@
+import { spawn } from "child_process";
+import { existsSync, readFileSync } from "fs";
+import { join, resolve } from "path";
+import { buddyStateDir } from "../path.ts";
+
+export type JsonObject = Record<string, unknown>;
+
+export interface HookRuntime {
+  now?: () => number;
+  packageRoot?: string;
+  sessionId?: string;
+  spawnDetached?: (script: string, args: string[]) => void;
+  stateDir?: string;
+}
+
+export function parseHookInput(raw: string): JsonObject | null {
+  try {
+    const value = JSON.parse(raw) as unknown;
+    return value && typeof value === "object" && !Array.isArray(value)
+      ? value as JsonObject
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export function stringField(input: JsonObject, field: string): string {
+  const value = input[field];
+  return typeof value === "string" ? value : "";
+}
+
+export function resolveHookStateDir(runtime: HookRuntime = {}): string {
+  return runtime.stateDir ?? buddyStateDir();
+}
+
+export function resolveHookSessionId(runtime: HookRuntime = {}): string {
+  if (runtime.sessionId) return runtime.sessionId;
+  const ccSid = process.env.CLAUDE_CODE_SESSION_ID;
+  if (ccSid) return ccSid.slice(0, 8);
+  const pane = process.env.TMUX_PANE;
+  if (pane) return pane.replace(/^%/, "");
+  return "default";
+}
+
+export function readJsonFile<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+export function nonNegativeInteger(value: unknown, fallback: number): number {
+  if (Number.isInteger(value) && Number(value) >= 0) return Number(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return Number(value);
+  return fallback;
+}
+
+export function isOnCooldown(path: string, cooldownSeconds: number, nowMs: number): boolean {
+  try {
+    const last = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+    if (!Number.isFinite(last)) return false;
+    return Math.floor(nowMs / 1000) - last < cooldownSeconds;
+  } catch {
+    return false;
+  }
+}
+
+export function packageRootFromHooks(): string {
+  return resolve(import.meta.dir, "..", "..");
+}
+
+export function defaultSpawnDetached(runtime: HookRuntime = {}): (script: string, args: string[]) => void {
+  return (script, args) => {
+    const root = runtime.packageRoot ?? packageRootFromHooks();
+    const child = spawn(process.execPath, ["run", join(root, script), ...args], {
+      cwd: root,
+      detached: true,
+      stdio: "ignore",
+    });
+    child.unref();
+  };
+}
+
+export function fileExists(path: string): boolean {
+  try {
+    return existsSync(path);
+  } catch {
+    return false;
+  }
+}
+
+export async function readStdin(): Promise<string> {
+  return await Bun.stdin.text();
+}

package/server/hooks/legacy-bash.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { join } from "path";
+import { packageRootFromHooks, readStdin } from "./common.ts";
+
+const ALLOWED = new Set([
+  "react.sh",
+  "file-type-react.sh",
+  "name-react.sh",
+  "mood-react.sh",
+]);
+
+if (import.meta.main) {
+  try {
+    const script = process.argv[2] ?? "";
+    if (ALLOWED.has(script)) {
+      const root = packageRootFromHooks();
+      const hook = join(root, "hooks", "legacy", script);
+      if (existsSync(hook)) {
+        spawnSync("bash", [hook], {
+          cwd: root,
+          input: await readStdin(),
+          stdio: ["pipe", "ignore", "ignore"],
+          timeout: 14_000,
+        });
+      }
+    }
+  } catch {
+    // Claude Code hooks must never fail the turn.
+  }
+  process.exit(0);
+}

package/server/hooks/suggest.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+
+import { join } from "path";
+import {
+  defaultSpawnDetached,
+  fileExists,
+  isOnCooldown,
+  nonNegativeInteger,
+  parseHookInput,
+  readJsonFile,
+  readStdin,
+  resolveHookStateDir,
+  stringField,
+  type HookRuntime,
+} from "./common.ts";
+
+interface SuggestConfig {
+  suggestionCooldown?: unknown;
+  suggestionsEnabled?: unknown;
+}
+
+export interface SuggestHookResult {
+  checked: boolean;
+}
+
+export function handleSuggest(rawInput: string, runtime: HookRuntime = {}): SuggestHookResult {
+  const stateDir = resolveHookStateDir(runtime);
+  const configFile = join(stateDir, "config.json");
+  if (!fileExists(configFile)) return { checked: false };
+
+  const config = readJsonFile<SuggestConfig>(configFile) ?? {};
+  if (config.suggestionsEnabled === false || config.suggestionsEnabled === "false") {
+    return { checked: false };
+  }
+
+  const now = runtime.now?.() ?? Date.now();
+  const cooldown = nonNegativeInteger(config.suggestionCooldown, 180);
+  if (isOnCooldown(join(stateDir, ".last_suggestion"), cooldown, now)) {
+    return { checked: false };
+  }
+
+  const input = parseHookInput(rawInput);
+  if (!input) return { checked: false };
+
+  const assistantMessage = stringField(input, "last_assistant_message");
+  if (!assistantMessage) return { checked: false };
+
+  const spawnDetached = runtime.spawnDetached ?? defaultSpawnDetached(runtime);
+  spawnDetached("server/check-suggestions.ts", [JSON.stringify(assistantMessage)]);
+  return { checked: true };
+}
+
+if (import.meta.main) {
+  try {
+    handleSuggest(await readStdin());
+  } catch {
+    // Claude Code hooks must never fail the turn.
+  }
+  process.exit(0);
+}

package/server/index.ts

@@ -9,6 +9,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { existsSync } from "fs";
 import { join, resolve, dirname } from "path";
 
 import { generateBones,
@@ -45,6 +46,7 @@ import {
 } from "./state";
 import {
   buddyStateDir,
+  buddyAppDir,
   claudeConfigDir,
   claudeSettingsPath,
 } from "./path";
@@ -622,7 +624,7 @@ server.tool("buddy_unmute", "Unmute buddy reactions", {}, async () => {
 
 server.tool(
   "buddy_statusline",
-  "Enable or disable the buddy status line, and toggle combined mode (shows rate-limit usage bars alongside the buddy). Returns current status if called without arguments.",
+  "Enable or disable the buddy status line, toggle combined mode (shows rate-limit usage bars alongside the buddy), or set a cached asynchronous sub-status command. Returns current status if called without arguments.",
   {
     enabled: z
       .boolean()
@@ -636,17 +638,24 @@ server.tool(
       .describe(
         "true to show rate-limit usage bars alongside buddy (requires python3), false for buddy-only mode.",
       ),
+    subStatusCommand: z
+      .string()
+      .optional()
+      .describe(
+        "Shell command whose cached output is appended below the buddy panel. Empty string clears it; the command always runs asynchronously.",
+      ),
   },
-  async ({ enabled, combined }) => {
-    if (enabled === undefined && combined === undefined) {
+  async ({ enabled, combined, subStatusCommand }) => {
+    if (enabled === undefined && combined === undefined && subStatusCommand === undefined) {
       const cfg = loadConfig();
       const state = cfg.statusLineEnabled ? "enabled" : "disabled";
       const mode = cfg.useCombinedStatus ? "combined (with rate-limit bars)" : "basic (buddy only)";
+      const subStatus = cfg.subStatusCommand ?? "unset";
       return {
         content: [
           {
             type: "text",
-            text: `Status line: ${state}\nMode: ${mode}\nUse /buddy statusline on|off to toggle, /buddy statusline combined to add rate-limit bars.\nRestart Claude Code after changes for them to take effect.`,
+            text: `Status line: ${state}\nMode: ${mode}\nSub-status command: ${subStatus}\nUse /buddy statusline on|off to toggle, /buddy statusline combined to add rate-limit bars, or set subStatusCommand to append cached command output.\nRestart Claude Code after changes for them to take effect.`,
           },
         ],
       };
@@ -656,6 +665,10 @@ server.tool(
       saveConfig({ useCombinedStatus: combined });
     }
 
+    if (subStatusCommand !== undefined) {
+      saveConfig({ subStatusCommand: subStatusCommand.trim() ? subStatusCommand : undefined });
+    }
+
     if (enabled !== undefined) {
       saveConfig({ statusLineEnabled: enabled });
     }
@@ -663,7 +676,10 @@ server.tool(
     const cfg = loadConfig();
 
     if (cfg.statusLineEnabled) {
-      const pluginRoot = resolve(dirname(import.meta.dir));
+      const installedRoot = buddyAppDir();
+      const pluginRoot = existsSync(join(installedRoot, "statusline", "buddy-status.sh"))
+        ? installedRoot
+        : resolve(dirname(import.meta.dir));
       const scriptName = cfg.useCombinedStatus ? "combined-status.sh" : "buddy-status.sh";
       const statusScript = join(pluginRoot, "statusline", scriptName);
       setBuddyStatusLine(statusScript);

package/server/path.ts

@@ -80,3 +80,8 @@ export function buddyStateDir(): string {
   if (cfgDir) return join(cfgDir, "buddy-state");
   return join(homedir(), ".claude-buddy");
 }
+
+/** Stable per-profile runtime copy used by installer registrations. */
+export function buddyAppDir(): string {
+  return join(buddyStateDir(), "app");
+}

package/server/state.ts

@@ -324,6 +324,7 @@ export interface BuddyConfig {
   bubbleWidth: number;
   bubbleMargin: number;
   useCombinedStatus: boolean;
+  subStatusCommand?: string;
   rainbowColors?: string[];
   theme: "dark" | "light" | "auto";
   moodEnabled: boolean;
@@ -349,12 +350,22 @@ const DEFAULT_CONFIG: BuddyConfig = {
   suggestionCooldown: 180,
 };
 
+export function normalizeConfig(data: unknown): BuddyConfig {
+  const values = data && typeof data === "object" && !Array.isArray(data)
+    ? data
+    : {};
+  const config = { ...DEFAULT_CONFIG, ...values } as BuddyConfig;
+  if (typeof config.subStatusCommand !== "string" || config.subStatusCommand.trim() === "") {
+    delete config.subStatusCommand;
+  }
+  return config;
+}
+
 export function loadConfig(): BuddyConfig {
   try {
-    const data = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
-    return { ...DEFAULT_CONFIG, ...data };
+    return normalizeConfig(JSON.parse(readFileSync(CONFIG_FILE, "utf8")));
   } catch {
-    return { ...DEFAULT_CONFIG };
+    return normalizeConfig({});
   }
 }
 
@@ -507,6 +518,7 @@ const TRANSIENT_PREFIXES = [
   "reaction.",
   ".last_reaction.",
   ".last_comment.",
+  ".substatus.",
 ];
 
 /**

package/statusline/buddy-status.sh

@@ -16,6 +16,7 @@
 
 # shellcheck source=../scripts/paths.sh
 source "$(dirname "${BASH_SOURCE[0]}")/../scripts/paths.sh"
+source "$(dirname "${BASH_SOURCE[0]}")/substatus.sh"
 
 STATE="$BUDDY_STATE_DIR/status.json"
 CONFIG_FILE="$BUDDY_STATE_DIR/config.json"
@@ -31,6 +32,7 @@ NAME=$(jq -r '.name // ""' "$STATE" 2>/dev/null)
 [ -z "$NAME" ] && exit 0
 
 RARITY=$(jq -r '.rarity // "common"' "$STATE" 2>/dev/null)
+STARS=$(jq -r '.stars // ""' "$STATE" 2>/dev/null)
 SHINY=$(jq -r '.shiny // false' "$STATE" 2>/dev/null)
 REACTION_FILE="$BUDDY_STATE_DIR/reaction.$SID.json"
 REACTION=$(jq -r '.reaction // ""' "$REACTION_FILE" 2>/dev/null)
@@ -38,7 +40,7 @@ ACHIEVEMENT=$(jq -r '.achievement // ""' "$STATE" 2>/dev/null)
 LEVEL=$(jq -r '.level // 1' "$STATE" 2>/dev/null)
 MOOD=$(jq -r '.mood // "focused"' "$STATE" 2>/dev/null)
 
-cat > /dev/null  # drain stdin
+BUDDY_STATUSLINE_INPUT=$(cat)
 
 # ─── Animation: pick current frame from server-rendered frames ──────────────
 NOW=${BUDDY_FAKE_NOW:-$(date +%s)}
@@ -67,6 +69,7 @@ if [ -f "$CONFIG_FILE" ]; then
 fi
 
 NC=$'\033[0m'
+NEUTRAL=$'\033[39m'
 case "$RARITY" in
   common)
     [ "$_THEME" = "light" ] && C=$'\033[38;2;90;90;90m' || C=$'\033[38;2;153;153;153m' ;;
@@ -188,6 +191,7 @@ fi
 # so the geometric center sits at col 6.
 NAME_WITH_LEVEL="$NAME"
 [ "$LEVEL" -gt 1 ] 2>/dev/null && NAME_WITH_LEVEL="${NAME} [L${LEVEL}]"
+[ -n "$STARS" ] && NAME_WITH_LEVEL="${NAME_WITH_LEVEL} ${STARS}"
 case "$MOOD" in
     happy)       MOOD_EMOJI="" ;;
     focused)     MOOD_EMOJI="" ;;
@@ -214,11 +218,11 @@ for line in "${ART_LINES[@]}"; do
     if [ "$SHINY" = "true" ]; then
         ALL_COLORS+=("${RAINBOW[$(( (_arc + RAINBOW_OFFSET) % RAINBOW_LEN ))]}")
     else
-        ALL_COLORS+=("$C")
+        ALL_COLORS+=("$NEUTRAL")
     fi
     _arc=$(( _arc + 1 ))
 done
-ALL_LINES+=("$NAME_LINE"); ALL_COLORS+=("$DIM")
+ALL_LINES+=("$NAME_LINE"); ALL_COLORS+=("$C")
 
 case "$SPECIES" in
   axolotl|capybara|rabbit|mushroom|chonk) ART_W=10 ;;
@@ -377,18 +381,18 @@ for (( i=0; i<MAX_LINES; i++ )); do
 
             # Connector: "-- " on the middle text line, spaces otherwise
             if [ $bi -eq $CONNECTOR_BI ]; then
-                gap="${C}--${NC} "
+                gap="${NEUTRAL}--${NC} "
             else
                 gap="   "
             fi
 
             if [ "$btype" = "border" ]; then
-                echo "${SPACER}${C}${bline}${NC}${gap}${art_part}"
+                echo "${SPACER}${NEUTRAL}${bline}${NC}${gap}${art_part}"
             else
                 pipe_l="${bline:0:1}"
                 pipe_r="${bline: -1}"
                 inner="${bline:1:$(( ${#bline} - 2 ))}"
-                echo "${SPACER}${C}${pipe_l}${NC}${DIM}${inner}${NC}${C}${pipe_r}${NC}${gap}${art_part}"
+                echo "${SPACER}${NEUTRAL}${pipe_l}${NC}${DIM}${inner}${NC}${NEUTRAL}${pipe_r}${NC}${gap}${art_part}"
             fi
         else
             empty=$(printf '%*s' "$BOX_W" '')
@@ -399,4 +403,8 @@ for (( i=0; i<MAX_LINES; i++ )); do
     fi
 done
 
+# Append the last cached sub-status result below the buddy panel and refresh
+# it asynchronously when stale. The statusline itself never waits on it.
+append_substatus
+
 exit 0

package/statusline/combined-status.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # statusline/combined-status.sh
 # Two-panel status line: rate-limit stats left, buddy art right.
-# buddy-status.sh is intentionally untouched (kept clean for upstream PR).
+# buddy-status.sh renders the buddy panel and shared cached sub-status below it.
 
 [ "$BUDDY_SHELL" = "1" ] && exit 0
 
@@ -54,7 +54,7 @@ except Exception:
 " 2>/dev/null)
 
 # ── Capture buddy art (buddy reads state files, not stdin) ───────────────────
-BUDDY_OUTPUT=$("$BUDDY_SCRIPT" </dev/null 2>/dev/null)
+BUDDY_OUTPUT=$(printf '%s' "$STDIN_DATA" | "$BUDDY_SCRIPT" 2>/dev/null)
 
 # No buddy output → exit silently (muted, no state, etc.)
 [ -z "$BUDDY_OUTPUT" ] && exit 0

package/statusline/substatus.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Shared cached sub-status renderer for the buddy statusline scripts.
+#
+# The command is intentionally launched from a detached process. Claude Code
+# kills a statusline process when the next one starts, so running the command
+# inline would make slow commands disappear before they can finish.
+
+_substatus_mtime() {
+    local path="$1"
+    local value
+    value=$(stat -f %m "$path" 2>/dev/null)
+    case "$value" in
+        ''|*[!0-9]*) value=$(stat -c %Y "$path" 2>/dev/null) ;;
+    esac
+    case "$value" in
+        ''|*[!0-9]*) echo 0 ;;
+        *) echo "$value" ;;
+    esac
+}
+
+append_substatus() {
+    local state_dir="$BUDDY_STATE_DIR"
+    local sid="${BUDDY_SID:-default}"
+    local config_file="$state_dir/config.json"
+    local cache_file="$state_dir/.substatus.$sid"
+    local lock_dir="$state_dir/.substatus.$sid.lock"
+    local command=""
+    local now cache_age lock_age
+
+    [ -f "$config_file" ] || return 0
+    command=$(jq -r '.subStatusCommand // ""' "$config_file" 2>/dev/null)
+    [ -n "$command" ] || return 0
+
+    # Always show the last complete result first. A missing or stale cache is
+    # allowed to be blank; the refresh below will populate the next tick.
+    [ -f "$cache_file" ] && cat "$cache_file"
+
+    now=$(date +%s)
+    cache_age=999999
+    if [ -f "$cache_file" ]; then
+        cache_age=$(( now - $(_substatus_mtime "$cache_file") ))
+        [ "$cache_age" -lt 0 ] && cache_age=0
+    fi
+    [ "$cache_age" -lt 5 ] && return 0
+
+    # mkdir is the portable atomic lock primitive. Only remove locks that are
+    # over a minute old, so a slow but healthy command is never duplicated.
+    if [ -d "$lock_dir" ]; then
+        lock_age=$(( now - $(_substatus_mtime "$lock_dir") ))
+        if [ "$lock_age" -gt 60 ]; then
+            rmdir "$lock_dir" 2>/dev/null || rm -rf "$lock_dir" 2>/dev/null
+        fi
+    fi
+
+    mkdir "$lock_dir" 2>/dev/null || return 0
+
+    # Keep the parent statusline fast even when the command takes minutes.
+    # The explicit /dev/null stdin makes this process independent of Claude's
+    # killed statusline process; the captured payload is piped to the command.
+    (
+        local tmp_file="$cache_file.$$"
+        printf '%s' "${BUDDY_STATUSLINE_INPUT:-}" | sh -c "$command" > "$tmp_file" 2>/dev/null
+        mv "$tmp_file" "$cache_file" 2>/dev/null || rm -f "$tmp_file" 2>/dev/null
+        rmdir "$lock_dir" 2>/dev/null || rm -rf "$lock_dir" 2>/dev/null
+    ) </dev/null > /dev/null 2>/dev/null &
+}