@phuetz/code-buddy 1.3.0 → 1.3.2

package/dist/codebuddy/tools.js

@@ -15,7 +15,7 @@ import { applyToolFilter } from "../utils/tool-filter.js";
 import { TOOL_METADATA } from "../tools/metadata.js";
 import { getPluginMarketplace } from "../plugins/marketplace.js";
 // Import modular tool definitions
-import { CORE_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, SEARCH_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, AGENT_TOOLS, FIRECRAWL_TOOLS, LSP_TOOLS, SECRETS_TOOLS, ADVISOR_TOOLS, ASK_USER_QUESTION_TOOLS, EXIT_PLAN_MODE_TOOLS, CODEBASE_REPLACE_TOOLS, SESSION_TOOLS, GITNEXUS_TOOLS, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
+import { CORE_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, SEARCH_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, AGENT_TOOLS, FIRECRAWL_TOOLS, LSP_TOOLS, SECRETS_TOOLS, ADVISOR_TOOLS, ASK_USER_QUESTION_TOOLS, EXIT_PLAN_MODE_TOOLS, CODEBASE_REPLACE_TOOLS, SESSION_TOOLS, CODE_EXPLORER_TOOLS, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
 import { FLEET_TOOLS } from "./fleet-tool-defs.js";
 // Explicit re-exports from tool-definitions (no blanket export *)
 export { CORE_TOOLS, MORPH_EDIT_TOOL, isMorphEnabled, SEARCH_TOOLS, TODO_TOOLS, KANBAN_TOOLS, MESSAGING_TOOLS, YUANBAO_TOOLS, HOMEASSISTANT_TOOLS, MOA_TOOLS, SPOTIFY_TOOLS, X_SEARCH_TOOLS, FEISHU_TOOLS, CRON_TOOLS, WEB_TOOLS, ADVANCED_TOOLS, MULTIMODAL_TOOLS, COMPUTER_CONTROL_TOOLS, BROWSER_TOOLS, CANVAS_TOOLS, REASON_TOOL, EXECUTE_CODE_TOOL, WINDOWS_TOOLS, } from "./tool-definitions/index.js";
@@ -50,7 +50,7 @@ export function getBuiltinToolNames() {
         CODEBASE_REPLACE_TOOLS,
         SESSION_TOOLS,
         FLEET_TOOLS,
-        GITNEXUS_TOOLS,
+        CODE_EXPLORER_TOOLS,
         WINDOWS_TOOLS,
     ];
     return Array.from(new Set(groups.flatMap((tools) => tools.map((tool) => tool.function.name))));
@@ -145,8 +145,8 @@ export function initializeToolRegistry() {
     // Fleet tools — peer_delegate, list_peers (Phase (d).17). Always available;
     // peer_delegate returns a clear error when no peers are connected.
     registerGroup(FLEET_TOOLS);
-    // GitNexus tools
-    registerGroup(GITNEXUS_TOOLS);
+    // CodeExplorer tools
+    registerGroup(CODE_EXPLORER_TOOLS);
     isRegistryInitialized = true;
     logger.debug('Tool registry initialized with built-in tools');
 }
@@ -162,14 +162,14 @@ export function getMCPManager() {
     return mcpManager;
 }
 /**
- * True when the Code Explorer (gitnexus) MCP tools are connected — i.e. at least
- * one `mcp__gitnexus__*` tool is registered. Used to conditionally steer the
+ * True when the Code Explorer (code-explorer) MCP tools are connected — i.e. at least
+ * one `mcp__code-explorer__*` tool is registered. Used to conditionally steer the
  * agent toward Code Explorer for relationship/impact questions. Returns false
  * (no behavior change) whenever Code Explorer is not installed.
  */
 export function isCodeExplorerAvailable() {
     try {
-        return getMCPManager().getTools().some((t) => t.name.startsWith('mcp__gitnexus__'));
+        return getMCPManager().getTools().some((t) => t.name.startsWith('mcp__code-explorer__'));
     }
     catch {
         return false;
@@ -387,14 +387,14 @@ export async function getAllCodeBuddyTools() {
     }
     // Apply CLI tool filter (--enabled-tools, --disabled-tools, --allowed-tools)
     allTools = applyToolFilter(allTools);
-    // When Code Explorer (gitnexus) is connected, make the built-in graph tools
+    // When Code Explorer (code-explorer) is connected, make the built-in graph tools
     // defer to it at the decision point — its graph is broader / more complete.
     // Conditional & non-mutating: returns fresh objects only for code_graph /
-    // codebase_map, and only when a gitnexus tool is present (no change otherwise).
-    if (allTools.some((t) => t.function.name.startsWith('mcp__gitnexus__'))) {
-        const DEFER = ' NOTE: Code Explorer (gitnexus) is available — for code-relationship, blast-radius/impact, ' +
-            'dead-code and cycle questions PREFER its MCP tools (`mcp__gitnexus__impact` / `context` / ' +
-            '`query` / `find_cycles`); use this built-in only as a fallback if a gitnexus tool errors.';
+    // codebase_map, and only when a code-explorer tool is present (no change otherwise).
+    if (allTools.some((t) => t.function.name.startsWith('mcp__code-explorer__'))) {
+        const DEFER = ' NOTE: Code Explorer (code-explorer) is available — for code-relationship, blast-radius/impact, ' +
+            'dead-code and cycle questions PREFER its MCP tools (`mcp__code-explorer__impact` / `context` / ' +
+            '`query` / `find_cycles`); use this built-in only as a fallback if a code-explorer tool errors.';
         allTools = allTools.map((t) => t.function.name === 'code_graph' || t.function.name === 'codebase_map'
             ? { ...t, function: { ...t.function, description: (t.function.description ?? '') + DEFER } }
             : t);

package/dist/collaboration/ai-colab-manager.js

@@ -16,8 +16,13 @@ export class AIColabManager {
     workLog = [];
     constructor(workingDirectory = process.cwd()) {
         this.colabFilePath = path.join(workingDirectory, 'COLAB.md');
-        this.tasksFilePath = path.join(workingDirectory, '.codebuddy', 'colab-tasks.json');
-        this.workLogFilePath = path.join(workingDirectory, '.codebuddy', 'colab-worklog.json');
+        // The shared fleet board `.codebuddy/colab-tasks.json` is now owned solely by
+        // FleetColabStore (the kanban_* tools + the autonomous daemon). This legacy
+        // `/colab` manager uses an incompatible schema (`not_started` status, no
+        // version/comment preservation, non-atomic full-file rewrite), so it writes
+        // its OWN files to avoid clobbering the unified board. See ColabKanbanAdapter.
+        this.tasksFilePath = path.join(workingDirectory, '.codebuddy', 'ai-colab-tasks.json');
+        this.workLogFilePath = path.join(workingDirectory, '.codebuddy', 'ai-colab-worklog.json');
         this.config = {
             project: 'Code Buddy',
             version: '1.0.0',
@@ -317,8 +322,8 @@ Couverture de tests actuelle: ${this.config.currentCoverage}% (objectif: ${this.
 
 - \`COLAB.md\` - Document de coordination principal
 - \`CLAUDE.md\` - Instructions de build et développement
-- \`.codebuddy/colab-tasks.json\` - Tâches en cours
-- \`.codebuddy/colab-worklog.json\` - Journal de travail
+- \`.codebuddy/ai-colab-tasks.json\` - Tâches en cours
+- \`.codebuddy/ai-colab-worklog.json\` - Journal de travail
 
 ### Règles de Collaboration
 

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/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;
 }