@phuetz/code-buddy 1.3.1 → 1.4.0

package/dist/commands/cli/code-explorer-commands.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CodeExplorer CLI commands
+ *
+ * Exposes commands to consult CodeExplorer and push session summaries.
+ */
+import type { Command } from 'commander';
+export declare function registerCodeExplorerCommands(program: Command): void;

package/dist/commands/cli/code-explorer-commands.js

@@ -0,0 +1,40 @@
+/**
+ * CodeExplorer CLI commands
+ *
+ * Exposes commands to consult CodeExplorer and push session summaries.
+ */
+import { CodeExplorerTool } from '../../tools/code-explorer-tool.js';
+export function registerCodeExplorerCommands(program) {
+    const codeExplorerCmd = program
+        .command('code-explorer')
+        .description('Interact with CodeExplorer for code understanding and session syncing');
+    codeExplorerCmd.command('ask')
+        .description('Consult CodeExplorer for a query or code understanding request')
+        .argument('<query>', 'The query or task description to ask CodeExplorer about')
+        .action(async (query) => {
+        try {
+            const codeExplorer = new CodeExplorerTool();
+            const result = await codeExplorer.ask(query);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            console.error('Error querying CodeExplorer:', error);
+            process.exit(1);
+        }
+    });
+    codeExplorerCmd.command('push-session')
+        .description('Push the session summary to CodeExplorer as technical memory')
+        .argument('<summary>', 'The session summary to push')
+        .action(async (summary) => {
+        try {
+            const codeExplorer = new CodeExplorerTool();
+            const result = await codeExplorer.pushSession(summary);
+            console.log(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            console.error('Error pushing session to CodeExplorer:', error);
+            process.exit(1);
+        }
+    });
+}
+//# sourceMappingURL=code-explorer-commands.js.map

package/dist/commands/cli/native-engine-commands.js

@@ -939,6 +939,70 @@ export function registerFleetAutonomyCommands(program) {
         const goalNote = task.goalMode ? ` goal-mode(${task.goalMaxTurns ?? 5} turns)` : '';
         console.log(`Added task ${task.id} [${task.priority}]${goalNote}${task.dependsOn ? ` depends on ${task.dependsOn.join(', ')}` : ''}`);
     });
+    tasks
+        .command('board')
+        .description('Render the unified fleet board as Hermes-style columns (To Do / In Progress / Review / Done)')
+        .option('--dir <path>', 'colab dir')
+        .option('--json', 'output JSON')
+        .action(async (opts) => {
+        const { FleetColabStore } = await import('../../fleet/colab-store.js');
+        const store = new FleetColabStore({ ...(opts.dir ? { dir: opts.dir } : {}) });
+        const all = store.listTasks();
+        const columns = [
+            { key: 'open', label: 'To Do' },
+            { key: 'in_progress', label: 'In Progress' },
+            { key: 'blocked', label: 'Review' },
+            { key: 'completed', label: 'Done' },
+        ];
+        if (opts.json) {
+            const grouped = Object.fromEntries(columns.map((c) => [c.label, all.filter((t) => t.status === c.key)]));
+            console.log(JSON.stringify(grouped, null, 2));
+            return;
+        }
+        for (const col of columns) {
+            const items = all.filter((t) => t.status === col.key);
+            console.log(`\n${col.label} (${items.length})`);
+            if (items.length === 0) {
+                console.log('  —');
+                continue;
+            }
+            for (const t of items) {
+                const annotations = [];
+                if (t.claimedBy)
+                    annotations.push(`@${t.claimedBy}`);
+                if (t.attempts)
+                    annotations.push(`attempts:${t.attempts}`);
+                if (t.dependsOn?.length)
+                    annotations.push(`deps:${t.dependsOn.length}`);
+                if (t.goalMode)
+                    annotations.push('goal');
+                if (col.key === 'blocked' && t.blockedReason)
+                    annotations.push(`(${t.blockedReason})`);
+                const suffix = annotations.length ? ` — ${annotations.join(' ')}` : '';
+                console.log(`  ${t.id} [${t.priority}] ${t.title}${suffix}`);
+            }
+        }
+    });
+    tasks
+        .command('import-kanban')
+        .description('Migrate cards from a legacy kanban-board.json into the unified fleet board')
+        .option('--board <path>', 'source kanban-board.json (default <cwd>/.codebuddy/kanban-board.json)')
+        .option('--dir <path>', 'target colab dir')
+        .option('--json', 'output JSON')
+        .action(async (opts) => {
+        const { KanbanStore } = await import('../../kanban/kanban-store.js');
+        const { FleetColabStore } = await import('../../fleet/colab-store.js');
+        const { importKanbanCards } = await import('../../kanban/colab-kanban-adapter.js');
+        const source = new KanbanStore(opts.board ? { boardPath: opts.board } : {});
+        const cards = await source.listCards({ includeArchived: true, includeDone: true });
+        const store = new FleetColabStore({ ...(opts.dir ? { dir: opts.dir } : {}) });
+        const { imported, skipped } = importKanbanCards(cards, store);
+        if (opts.json) {
+            console.log(JSON.stringify({ imported, skipped }, null, 2));
+            return;
+        }
+        console.log(`Imported ${imported.length} card(s) into the unified board, skipped ${skipped.length} (archived or already present).`);
+    });
     fleet
         .command('swarm <goal>')
         .description('Create a workers → verifier → synthesizer task graph')

package/dist/commands/handlers/channel-handlers.js

@@ -327,13 +327,8 @@ export async function registerAIMessageHandler(manager) {
     aiHandlerRegistered = true;
     manager.onMessage(async (message, channel) => {
         try {
-            const apiKey = process.env.GROK_API_KEY || process.env.XAI_API_KEY || '';
-            if (!apiKey) {
-                logger.warn('No API key for channel AI responses');
-                return;
-            }
-            const { checkDMPairing, getDMPairing, getRouteAgentConfig } = await import('../../channels/core.js');
-            // 1. Check DM pairing first
+            // 1. DM pairing gate — unapproved senders get a code, then we stop.
+            const { checkDMPairing, getDMPairing } = await import('../../channels/core.js');
             const pairingStatus = await checkDMPairing(message);
             if (!pairingStatus.approved) {
                 if (pairingStatus.code) {
@@ -347,14 +342,35 @@ export async function registerAIMessageHandler(manager) {
                 }
                 return;
             }
-            // 2. Resolve route-backed agent config
-            const agentConfig = getRouteAgentConfig(message);
-            // 3. Instantiate Agent with routed config
+            // Nothing to answer (e.g. a non-text message with no transcription).
+            if (!message.content || !message.content.trim()) {
+                return;
+            }
+            // 2. Context-adaptive agent reply (« comme Claude »): the agent's own
+            //    query-classifier + buildForQuery scale the system prompt to the
+            //    request (a greeting → minimal ~800B prompt, NOT the 73KB legacy),
+            //    and tools load on demand — RAG selects only the relevant ~15 and the
+            //    `tool_search` meta-tool pulls more when actually needed. Bounded
+            //    rounds keep a simple chat fast while a real task can still act.
+            const { resolveProviderFromEnv } = await import('../../fleet/peer-chat-client-factory.js');
+            const knownProviders = ['ollama', 'chatgpt', 'gemini', 'grok', 'anthropic'];
+            const preferredProvider = process.env.CODEBUDDY_PROVIDER && knownProviders.includes(process.env.CODEBUDDY_PROVIDER)
+                ? process.env.CODEBUDDY_PROVIDER
+                : 'auto';
+            const resolved = resolveProviderFromEnv(preferredProvider);
+            if (!resolved) {
+                logger.warn('No LLM provider for channel chat — set CODEBUDDY_PROVIDER + a provider key/env');
+                return;
+            }
+            const { getRouteAgentConfig } = await import('../../channels/core.js');
             const { CodeBuddyAgent } = await import('../../agent/codebuddy-agent.js');
-            const model = agentConfig.model || process.env.GROK_MODEL || 'grok-3-latest';
-            const maxRounds = agentConfig.maxToolRounds;
-            const agent = new CodeBuddyAgent(apiKey, process.env.GROK_BASE_URL, model, maxRounds);
-            // 4. Resume/Initialize session history
+            const agentConfig = getRouteAgentConfig(message);
+            const model = agentConfig.model || resolved.model;
+            const agent = new CodeBuddyAgent(resolved.apiKey || 'local', resolved.baseUrl, model, agentConfig.maxToolRounds ?? 6, // bounded (vs the 50-round default)
+            true, // useRAGToolSelection — relevant tools on demand, not all ~194
+            process.env.CODEBUDDY_CHANNEL_PROMPT_ID || 'auto', // minimal/adaptive prompt, not the 73KB legacy
+            process.cwd());
+            // Multi-turn: restore prior session history into the agent.
             const sessionKey = message.sessionKey || 'default-global';
             const sessionStore = agent.getSessionStore();
             let session = await sessionStore.loadSession(sessionKey);
@@ -371,18 +387,16 @@ export async function registerAIMessageHandler(manager) {
                 await sessionStore.saveSession(session);
             }
             await sessionStore.resumeSession(sessionKey);
-            const activeSession = session;
-            if (activeSession.messages && activeSession.messages.length > 0) {
-                const chatHistory = sessionStore.convertMessagesToChatEntries(activeSession.messages);
-                const messages = activeSession.messages.map(m => ({
+            if (session.messages && session.messages.length > 0) {
+                const chatHistory = sessionStore.convertMessagesToChatEntries(session.messages);
+                const priorMessages = session.messages.map((m) => ({
                     role: m.type === 'user' ? 'user' : 'assistant',
-                    content: m.content
+                    content: m.content,
                 }));
                 const historyRestorer = agent;
                 historyRestorer.historyManager.setChatHistory(chatHistory);
-                historyRestorer.historyManager.setMessages(messages);
+                historyRestorer.historyManager.setMessages(priorMessages);
             }
-            // 5. Run agent turn
             const entries = await agent.processUserMessage(message.content);
             const lastEntry = entries[entries.length - 1];
             const response = lastEntry ? String(lastEntry.content) : '';
@@ -412,7 +426,10 @@ export async function instantiateChannel(config) {
     switch (config.type) {
         case 'telegram': {
             const { TelegramChannel } = await import('../../channels/telegram/index.js');
-            return new TelegramChannel({ botToken: config.token || '', ...opts });
+            // TelegramChannel reads `config.token` (client.ts) — pass `token`, not
+            // `botToken`, or it throws "Telegram bot token is required" and the
+            // channel never starts from channels.json / server intake.
+            return new TelegramChannel({ token: config.token || '', ...opts });
         }
         case 'discord': {
             const { DiscordChannel } = await import('../../channels/discord/index.js');

package/dist/commands/handlers/graph-handlers.d.ts

@@ -1,5 +1,5 @@
 /**
- * Graph Slash Command Handlers — GitNexus Knowledge Graph
+ * Graph Slash Command Handlers — CodeExplorer Knowledge Graph
  *
  * /impact <symbol>  — Analyze blast radius of changing a symbol
  * /processes         — Detect execution flows in the codebase

package/dist/commands/handlers/graph-handlers.js

@@ -1,5 +1,5 @@
 /**
- * Graph Slash Command Handlers — GitNexus Knowledge Graph
+ * Graph Slash Command Handlers — CodeExplorer Knowledge Graph
  *
  * /impact <symbol>  — Analyze blast radius of changing a symbol
  * /processes         — Detect execution flows in the codebase

package/dist/config/model-tools.js

@@ -147,7 +147,7 @@ const DEFAULT_MODEL_CONFIGS = [
     },
     // ChatGPT Codex backend (Phase d.23) — exposed via OAuth subscription
     // auth at chatgpt.com/backend-api/codex/responses. `gpt-5.5` matches the
-    // GitNexus helper default; `gpt-5.2` remains the known-good fallback.
+    // CodeExplorer helper default; `gpt-5.2` remains the known-good fallback.
     {
         model: 'gpt-5.5*',
         supportsReasoning: true,

package/dist/daemon/autonomous-loop.d.ts

@@ -82,13 +82,6 @@ export declare class FleetAutonomousLoop {
     private readonly executor;
     private readonly policy;
     private readonly enabled;
-    /**
-     * Per-task consecutive-failure counts (in-memory, this run). Fed to
-     * {@link chooseAutonomousModel} so a task that keeps failing on the cheap tier
-     * escalates to a stronger model (policy `escalateAfterFailures`). Cleared on
-     * success. Resets across process restarts — escalation is a within-run feature.
-     */
-    private readonly failures;
     private readonly goalJudge;
     private readonly selfImprove;
     private readonly selfImproveCooldownMs;

package/dist/daemon/autonomous-loop.js

@@ -76,13 +76,10 @@ export class FleetAutonomousLoop {
     executor;
     policy;
     enabled;
-    /**
-     * Per-task consecutive-failure counts (in-memory, this run). Fed to
-     * {@link chooseAutonomousModel} so a task that keeps failing on the cheap tier
-     * escalates to a stronger model (policy `escalateAfterFailures`). Cleared on
-     * success. Resets across process restarts — escalation is a within-run feature.
-     */
-    failures = new Map();
+    // Per-task failure counts now live on the task itself (`ColabTask.attempts`,
+    // persisted by FleetColabStore) so they survive daemon restarts and are visible
+    // cross-machine. They feed {@link chooseAutonomousModel} for model-ladder
+    // escalation AND the retry budget that dead-letters a hopeless task.
     goalJudge;
     selfImprove;
     selfImproveCooldownMs;
@@ -146,6 +143,10 @@ export class FleetAutonomousLoop {
             return { outcome: 'saturated', detail: 'at capacity — leaving the queue to idle peers' };
         }
         this.store.updatePresence({ status: 'active' });
+        // Zombie sweep (Hermes-kanban parity): reclaim crashed peers' expired claims
+        // before picking work. Each reclaim counts against the task's retry budget,
+        // dead-lettering a task that has been claimed-and-abandoned too many times.
+        this.store.reclaimExpired();
         const next = this.store.nextClaimable();
         if (!next) {
             // No real work — use the idle moment for one bounded self-improvement
@@ -163,7 +164,7 @@ export class FleetAutonomousLoop {
             return { outcome: 'idle', detail: err instanceof Error ? err.message : String(err) };
         }
         this.store.updatePresence({ status: 'active', currentTask: task.title });
-        const failures = this.failures.get(task.id) ?? 0;
+        const failures = task.attempts ?? 0;
         const model = chooseAutonomousModel(this.tierConfig, { priority: task.priority, ...(failures > 0 ? { failures } : {}) }, this.policy);
         let result;
         const doneLoad = beginFleetWork('autonomy.task');
@@ -185,7 +186,7 @@ export class FleetAutonomousLoop {
                     return goalOutcome;
                 // null → judge said done (or skipped): fall through to completion.
             }
-            this.failures.delete(task.id);
+            this.store.resetAttempts(task.id);
             this.store.completeTask(task.id, {
                 summary: result.summary,
                 filesModified: result.filesModified ?? [],
@@ -194,18 +195,27 @@ export class FleetAutonomousLoop {
             this.store.updatePresence({ status: 'idle', currentTask: null });
             return { outcome: 'completed', taskId: task.id, taskTitle: task.title, model };
         }
-        // Track the failure so the next attempt can escalate up the model ladder.
-        this.failures.set(task.id, failures + 1);
-        // Failure: log it and release the task so it can be retried (or escalated).
+        // Persist the failure (retry-budget counter — survives restarts, visible
+        // cross-machine). The next attempt can escalate up the model ladder; once the
+        // budget is exhausted the task is dead-lettered to `blocked` (the Review
+        // column) instead of being released to spin forever.
+        const { attempts, exhausted } = this.store.recordFailure(task.id);
         this.store.appendWorklog({
             agent: this.store.agentId,
             taskId: task.id,
             summary: `Autonomous attempt failed: ${result.summary}`,
             filesModified: [],
             issues: [result.error ?? 'unknown error'],
-            nextSteps: ['retry on a later tick or escalate to the strong model'],
+            nextSteps: exhausted
+                ? [`retry budget (${attempts} attempts) exhausted — dead-lettered for human review`]
+                : ['retry on a later tick or escalate to the strong model'],
         });
-        this.store.releaseTask(task.id);
+        if (exhausted) {
+            this.store.blockTask(task.id, `Failed ${attempts}× (retry budget exhausted) — needs review`);
+        }
+        else {
+            this.store.releaseTask(task.id);
+        }
         this.store.updatePresence({ status: 'idle', currentTask: null });
         return {
             outcome: 'failed',

package/dist/fleet/capability-registry.js

@@ -351,7 +351,15 @@ function buildGrokCatalog() {
     }));
 }
 function buildMistralCatalog() {
-    const ids = ['mistral-large-latest', 'mistral-medium-latest', 'mistral-small-latest'];
+    const ids = [
+        'mistral-large-latest',
+        'mistral-medium-latest',
+        'mistral-small-latest',
+        'codestral-latest',
+        'devstral-latest',
+        'magistral-medium-latest',
+        'ministral-8b-latest',
+    ];
     return ids.map((id) => ({
         id,
         contextWindow: 128_000,

package/dist/fleet/colab-store.d.ts

@@ -36,6 +36,21 @@ export interface ColabTask {
     assignedAgent?: string | null;
     claimedBy?: string | null;
     claimedAt?: string | null;
+    /**
+     * Last lease renewal (heartbeat). A live worker calls {@link FleetColabStore.heartbeat}
+     * to re-stamp `claimedAt`, so {@link FleetColabStore.isClaimExpired} (which measures
+     * `claimedAt` age) doubles as zombie detection: a silent claim ages out, a
+     * heartbeated one does not. Informational mirror of the last bump.
+     */
+    lastHeartbeatAt?: string | null;
+    /**
+     * Persisted failure/zombie-reclaim count (Hermes-kanban retry-budget parity).
+     * Survives daemon restarts and is visible cross-machine, unlike an in-memory
+     * counter. Reset on success; incremented on each failed attempt or zombie reclaim.
+     */
+    attempts?: number;
+    /** Per-task override of the dead-letter threshold (default {@link DEFAULT_RETRY_BUDGET}). */
+    retryBudget?: number;
     completedAt?: string | null;
     blockedReason?: string;
     filesToModify?: string[];
@@ -64,6 +79,34 @@ export interface ColabTask {
     goalLastReason?: string;
     createdBy?: string;
     createdAt?: string;
+    /** Free-text labels for filtering (`kanban_list --tag`). */
+    tags?: string[];
+    /** Human/agent the card is assigned to (distinct from `claimedBy`, which is the live worker). */
+    assignee?: string;
+    /** Discussion thread (block/unblock/complete also append here). */
+    comments?: ColabComment[];
+    /** Progress pings (each also renews the lease via {@link FleetColabStore.heartbeat}). */
+    heartbeats?: ColabHeartbeat[];
+    /** Free-form references (PRs, commits, files) — NOT DAG edges; dependency edges live in `dependsOn`. */
+    links?: ColabLink[];
+}
+export interface ColabComment {
+    id: string;
+    author?: string;
+    text: string;
+    createdAt: string;
+}
+export interface ColabHeartbeat {
+    id: string;
+    author?: string;
+    message?: string;
+    createdAt: string;
+}
+export interface ColabLink {
+    id: string;
+    target: string;
+    label?: string;
+    createdAt: string;
 }
 export interface ColabWorklogFileChange {
     file: string;
@@ -97,6 +140,12 @@ export interface FleetColabStoreConfig {
      * not stay stuck. Lazy-on-read (no timer); 0 disables. Default 15 min.
      */
     claimTtlMs?: number;
+    /**
+     * Default retry budget for tasks that don't set their own (default
+     * {@link DEFAULT_RETRY_BUDGET}). After this many failures/zombie-reclaims a task
+     * is dead-lettered to `blocked` for review instead of being retried forever.
+     */
+    retryBudget?: number;
     /** Injectable clock (epoch ms) for deterministic tests. */
     now?: () => number;
     /** Injectable id generator for deterministic tests. */
@@ -120,6 +169,11 @@ export interface AddTaskInput {
     dependsOn?: string[];
     goalMode?: boolean;
     goalMaxTurns?: number;
+    /** Per-task dead-letter threshold override (default {@link DEFAULT_RETRY_BUDGET}). */
+    retryBudget?: number;
+    tags?: string[];
+    assignee?: string;
+    status?: ColabTaskStatus;
     createdBy?: string;
     id?: string;
 }
@@ -131,6 +185,8 @@ export declare class FleetColabStore {
     private readonly now;
     private readonly generateId;
     private readonly claimTtlMs;
+    private readonly retryBudget;
+    private writeSeq;
     private readonly tasksPath;
     private readonly worklogPath;
     private readonly presencePath;
@@ -150,12 +206,39 @@ export declare class FleetColabStore {
      * reclaim of a crashed agent's work). Lazy: evaluated on read, no timer.
      */
     isClaimExpired(task: Pick<ColabTask, 'status' | 'claimedAt'>, nowMs?: number): boolean;
+    /** The dead-letter threshold for a task (its own `retryBudget`, else the store default). */
+    resolveRetryBudget(task: Pick<ColabTask, 'retryBudget'>): number;
     /**
-     * Sweep expired claims back to `open` (for a daemon to call proactively).
-     * Returns the reclaimed task ids. Lazy callers can rely on {@link nextClaimable},
-     * which already treats expired claims as available.
+     * Sweep expired claims (zombie detection) — a crashed agent's claim ages out
+     * because it stopped heartbeating. Each reclaim counts against the task's
+     * retry budget: under budget it returns to `open` for retry; at/over budget it
+     * is dead-lettered to `blocked` (the "Review" column) instead of spinning
+     * forever. Returns every reclaimed task id (re-opened or dead-lettered).
+     * Lazy callers can rely on {@link nextClaimable}, which treats an expired claim
+     * as available — but only the sweep enforces the retry budget, so a daemon
+     * should call this each tick.
      */
     reclaimExpired(): string[];
+    /**
+     * Renew a claim's lease (Hermes-kanban heartbeat). Re-stamps `claimedAt` and
+     * `lastHeartbeatAt` so a long-running but live worker is not reclaimed as a
+     * zombie. Only valid while the task is `in_progress`; when `agentId` is given it
+     * must match the current claimant.
+     */
+    heartbeat(taskId: string, agentId?: string): ColabTask;
+    /**
+     * Record a failed attempt (persisted retry-budget counter). Increments
+     * `attempts` and reports whether the budget is now exhausted, so the caller can
+     * dead-letter (`blockTask`) vs retry (`releaseTask`). Does not change status —
+     * the daemon owns the worklog/release flow.
+     */
+    recordFailure(taskId: string): {
+        task: ColabTask;
+        attempts: number;
+        exhausted: boolean;
+    };
+    /** Reset the retry-budget counter (call on a successful attempt). */
+    resetAttempts(taskId: string): ColabTask;
     /** Dependency ids that are not yet `completed` (unknown/missing ids count as unmet). */
     unmetDependencies(task: Pick<ColabTask, 'dependsOn'>, tasks: ColabTask[]): string[];
     /** True when every dependency of a task is `completed` (DAG readiness). */
@@ -192,6 +275,21 @@ export declare class FleetColabStore {
     link(childId: string, parentId: string): ColabTask;
     /** Remove a `child dependsOn parent` edge. Returns false if the edge was absent. */
     unlink(childId: string, parentId: string): boolean;
+    /** Append a comment to a task's discussion thread. */
+    addComment(taskId: string, text: string, author?: string): ColabTask;
+    /** Attach a free-form reference (PR/commit/file/url) — not a DAG edge (see {@link link}). */
+    addLink(taskId: string, target: string, label?: string): ColabTask;
+    /**
+     * Tool-facing heartbeat: records a progress ping AND renews the lease. Lenient
+     * (unlike {@link heartbeat}, which is the strict programmatic lease-renewal):
+     * an `open` task transitions to `in_progress` and is claimed by `agentId`, so
+     * an agent pinging a fresh card takes ownership the way Hermes's kanban does.
+     */
+    recordHeartbeat(taskId: string, message?: string, author?: string, agentId?: string): ColabTask;
+    /** Resume a blocked task (back to in_progress) and record why. Mirrors `kanban_unblock`. */
+    unblockTask(taskId: string, comment?: string, author?: string): ColabTask;
+    /** Shared read-modify-write helper for single-task surface mutations. */
+    private mutateTask;
     appendWorklog(entry: Omit<ColabWorklogEntry, 'id' | 'date'> & {
         id?: string;
         date?: string;
@@ -214,5 +312,13 @@ export declare class FleetColabStore {
     private readPresence;
     private writePresence;
     private readJson;
+    /**
+     * Atomic write (temp file + rename). `fs.renameSync` is atomic on POSIX, so a
+     * concurrent same-host reader/writer never sees a half-written file — important
+     * now that the daemon, the `kanban_*` tools, and `/colab` can all drive the
+     * same `colab-tasks.json`. (Cross-machine arbitration stays git-push-order by
+     * design; this guards only the local race.) Mirrors the idiom in
+     * `src/kanban/kanban-store.ts`.
+     */
     private writeJson;
 }