codeep 2.20.0 → 2.22.0

package/dist/utils/agent.js

@@ -14,6 +14,7 @@ const debug = (...args) => {
 import { agentChat, getAgentSystemPrompt, getFallbackSystemPrompt, loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent, summarizeEarlierHistory, } from './agentChat.js';
 import { ApiError } from '../api/index.js';
 import { loadUserProfilePrompt } from './userProfile.js';
+import { beginAuditRun, endAuditRun, recordAuditEvent, describeAuditTarget } from './auditLog.js';
 import { getActivePersonality, getPersonalityToolAllowlist, isPersonalityToolCallAllowed, resolvePersonalityRuntimeModel, } from './personalities.js';
 export { loadProjectRules, loadProgressLog, writeProgressLog, formatChatHistoryForAgent };
 /**
@@ -172,6 +173,30 @@ const DEFAULT_OPTIONS = {
     maxDuration: 20 * 60 * 1000, // 20 minutes
     usePlanning: false, // Disable task planning - causes more problems than it solves
 };
+/**
+ * Sleep that gives up when the run is stopped.
+ *
+ * A plain `setTimeout` promise ignores the abort signal, so pressing Stop
+ * during "retrying in 10s" did nothing until the wait expired — and then the
+ * loop went on to retry anyway. Ctrl-C behaved the same way, because both
+ * routes set the same signal that nothing was reading.
+ *
+ * Resolves early on abort. Callers must still check `aborted` afterwards; this
+ * only stops the waiting, it does not decide what to do next.
+ */
+function abortableSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise(resolve => {
+        const timer = setTimeout(finish, ms);
+        function finish() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        }
+        signal?.addEventListener('abort', finish, { once: true });
+    });
+}
 /**
  * Run the agent loop
  */
@@ -190,7 +215,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
     const messages = [];
     // A structured custom bot is resolved once per run. This keeps a cloud sync
     // or file edit from changing policy halfway through an in-flight request.
-    const activePersonality = getActivePersonality(projectContext.root);
+    const activePersonality = opts.personalityOverride ?? getActivePersonality(projectContext.root);
     const currentRuntime = {
         providerId: String(config.get('provider')),
         model: String(config.get('model')),
@@ -205,7 +230,21 @@ export async function runAgent(prompt, projectContext, options = {}) {
     // Start history session for undo support. Skipped for nested (delegated)
     // runs so we don't reset the parent's currentSession singleton — the
     // sub-agent's actions still record into the parent's open session.
-    const sessionId = opts.nested ? '' : startSession(prompt, projectContext.root || process.cwd());
+    // The return value is unused — startSession's point here is the side
+    // effect of opening the history session. Binding it hid that from
+    // noUnusedLocals, so the dead binding is gone and the call stays.
+    const auditRoot = projectContext.root || process.cwd();
+    if (!opts.nested)
+        startSession(prompt, auditRoot);
+    // A delegated sub-agent records into the parent's run for the same reason it
+    // shares the parent's history session: its actions are part of what the run
+    // did, not a separate story. Only the top-level call opens a run.
+    let auditFailure;
+    const auditRun = opts.nested ? '' : beginAuditRun(auditRoot, {
+        prompt,
+        agent: activePersonality?.displayName,
+        capabilities: activePersonality?.declaredTools,
+    });
     // Task planning phase (if enabled)
     // Use planning for complex keywords or multi-word prompts
     let taskPlan = null;
@@ -427,6 +466,9 @@ export async function runAgent(prompt, projectContext, options = {}) {
     messages.push({ role: 'user', content: initialPrompt });
     let iteration = 0;
     let finalResponse = '';
+    // Initialised rather than merely declared: the `finally` reads it to decide
+    // the audit outcome, and TypeScript is right that a throw before assignment
+    // would leave it unset.
     let result;
     let consecutiveTimeouts = 0;
     let incompleteWorkRetries = 0;
@@ -571,7 +613,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 const totalTokensEstimate = messages.reduce((sum, m) => sum + Math.ceil(m.content.length / 4), 0);
                 const throttleMs = Math.min(Math.floor(totalTokensEstimate / 10000) * 1000, 5000);
                 if (throttleMs > 0)
-                    await new Promise(resolve => setTimeout(resolve, throttleMs));
+                    await abortableSleep(throttleMs, opts.abortSignal);
             }
             // Compress messages if context window is getting full (silent)
             const compressed = compressMessages(messages, actions);
@@ -664,7 +706,11 @@ export async function runAgent(prompt, projectContext, options = {}) {
                             break;
                         }
                         // Wait before retry (exponential backoff)
-                        await new Promise(resolve => setTimeout(resolve, 1000 * retryCount));
+                        await abortableSleep(1000 * retryCount, opts.abortSignal);
+                        // Stopping during a backoff must actually stop. Without this the
+                        // wait ended and the loop retried the request the user cancelled.
+                        if (opts.abortSignal?.aborted)
+                            break;
                         continue;
                     }
                     // Don't retry on 4xx client errors except 429 (rate limit)
@@ -728,7 +774,12 @@ export async function runAgent(prompt, projectContext, options = {}) {
                         });
                         break; // Break retry loop, continue main loop
                     }
-                    await new Promise(resolve => setTimeout(resolve, waitSec * 1000));
+                    await abortableSleep(waitSec * 1000, opts.abortSignal);
+                    // Stopping during a rate-limit wait must actually stop. Without
+                    // this the wait ran to completion and the loop retried the request
+                    // the user had already cancelled.
+                    if (opts.abortSignal?.aborted)
+                        break;
                     continue;
                 }
             }
@@ -833,6 +884,13 @@ export async function runAgent(prompt, projectContext, options = {}) {
                     };
                     opts.onToolResult?.(denied, toolCall);
                     actions.push(createActionLog(toolCall, denied));
+                    // The one event nothing recorded before. A boundary you cannot audit
+                    // is a boundary you have to take on faith.
+                    recordAuditEvent(auditRoot, {
+                        ts: Date.now(), run: auditRun, tool: toolCall.tool, action: 'refused',
+                        target: describeAuditTarget(toolCall), outcome: 'refused',
+                        detail: `blocked by custom bot "${activePersonality.displayName}"; allowed: ${allowed}`,
+                    });
                     toolResults.push(`Tool ${toolCall.tool} is blocked by the active custom bot. Allowed capabilities: ${allowed}.`);
                     continue;
                 }
@@ -940,6 +998,14 @@ export async function runAgent(prompt, projectContext, options = {}) {
                 // Log action
                 const actionLog = createActionLog(toolCall, toolResult);
                 actions.push(actionLog);
+                // createActionLog already classified this; reuse its verdict rather than
+                // re-deriving the action type in a second place that could drift.
+                recordAuditEvent(auditRoot, {
+                    ts: Date.now(), run: auditRun, tool: toolCall.tool, action: actionLog.type,
+                    target: describeAuditTarget(toolCall),
+                    outcome: toolResult.success ? 'ok' : 'error',
+                    detail: toolResult.success ? undefined : toolResult.error,
+                });
                 // ── Infinite loop detection for write/edit ──────────────────────────
                 if (toolCall.tool === 'write_file' || toolCall.tool === 'edit_file') {
                     const filePath = toolCall.parameters.path || '';
@@ -1121,6 +1187,13 @@ export async function runAgent(prompt, projectContext, options = {}) {
                                 };
                                 opts.onToolResult?.(denied, toolCall);
                                 actions.push(createActionLog(toolCall, denied));
+                                // The one event nothing recorded before. A boundary you cannot audit
+                                // is a boundary you have to take on faith.
+                                recordAuditEvent(auditRoot, {
+                                    ts: Date.now(), run: auditRun, tool: toolCall.tool, action: 'refused',
+                                    target: describeAuditTarget(toolCall), outcome: 'refused',
+                                    detail: `blocked by custom bot "${activePersonality.displayName}"`,
+                                });
                                 fixResults.push(`Tool ${toolCall.tool} blocked by the active custom bot.`);
                                 continue;
                             }
@@ -1141,6 +1214,14 @@ export async function runAgent(prompt, projectContext, options = {}) {
                             opts.onToolResult?.(toolResult, toolCall);
                             const actionLog = createActionLog(toolCall, toolResult);
                             actions.push(actionLog);
+                            // createActionLog already classified this; reuse its verdict rather than
+                            // re-deriving the action type in a second place that could drift.
+                            recordAuditEvent(auditRoot, {
+                                ts: Date.now(), run: auditRun, tool: toolCall.tool, action: actionLog.type,
+                                target: describeAuditTarget(toolCall),
+                                outcome: toolResult.success ? 'ok' : 'error',
+                                detail: toolResult.success ? undefined : toolResult.error,
+                            });
                             if (toolResult.success) {
                                 const truncated = truncateToolResult(toolResult.output, toolCall.tool);
                                 fixResults.push(`Tool ${toolCall.tool} succeeded:\n${truncated}`);
@@ -1199,6 +1280,7 @@ export async function runAgent(prompt, projectContext, options = {}) {
     }
     catch (error) {
         const err = error;
+        auditFailure = err.message;
         result = {
             success: false,
             iterations: iteration,
@@ -1211,8 +1293,22 @@ export async function runAgent(prompt, projectContext, options = {}) {
     finally {
         // End session and save history. Skipped for nested runs so we don't write
         // a separate session file or null out the parent's open session.
-        if (!opts.nested)
+        if (!opts.nested) {
             endSession();
+            // In `finally`, so a run that throws still closes its record. An audit
+            // trail that only survives success is worth very little — the runs you
+            // most want to read are the ones that went wrong.
+            //
+            // The outcome comes from the result, not from whether an exception
+            // escaped. Several failure paths — a user abort, a 4xx from the provider
+            // — return `success: false` with a plain `return`, and reading only the
+            // catch recorded those as successful runs. An audit record that says a
+            // failed run passed is worse than having no record at all.
+            const failed = auditFailure ?? (result === undefined || result.success
+                ? undefined
+                : (result.aborted ? 'stopped by the user' : (result.error ?? 'run did not succeed')));
+            endAuditRun(auditRoot, auditRun, failed ? 'error' : 'ok', failed);
+        }
     }
 }
 /**

package/dist/utils/auditLog.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Audit record — what an agent actually touched.
+ *
+ * Distinct from `history.ts`, which exists to undo things: that journal keeps
+ * file contents so a write can be reversed, records only mutations, and lives
+ * in `~/.codeep/history/`. This one answers a different question — *what did
+ * this agent do to this project* — so it records reads and refusals too, keeps
+ * no file contents at all, and lives with the project it describes.
+ *
+ * The most valuable entry is the one nothing recorded before: a tool call the
+ * capability boundary refused. A boundary you cannot audit is a boundary you
+ * have to take on faith.
+ *
+ * Format is JSON Lines. Appending one line per event survives a crash mid-run,
+ * needs no read-modify-write, and stays greppable without a parser.
+ *
+ * PRIVACY: entries carry command lines and file paths, not file contents. A
+ * command can still contain a secret someone typed into it, exactly as shell
+ * history can — treat the directory like shell history, not like source.
+ *
+ * It sits under `.codeep/`, which most projects already ignore, but Codeep does
+ * not edit anyone's `.gitignore` and this module must not claim otherwise. If a
+ * project tracks `.codeep/`, the audit log will be committed with it.
+ */
+/** One thing an agent did, or was stopped from doing. */
+export interface AuditEvent {
+    /** Epoch millis. */
+    ts: number;
+    /** Groups every event from one agent run. */
+    run: string;
+    /** Provider-facing tool name, e.g. `read_file`. Absent on run markers. */
+    tool?: string;
+    /** What kind of thing happened. `refused` is a boundary denial. */
+    action: 'run-start' | 'run-end' | 'read' | 'write' | 'edit' | 'delete' | 'command' | 'search' | 'list' | 'mkdir' | 'fetch' | 'refused';
+    /** File path, command line, or URL — truncated, never file contents. */
+    target?: string;
+    outcome?: 'ok' | 'error' | 'refused';
+    /** Short reason or note. Never a file body. */
+    detail?: string;
+    /** Run markers only: the active custom bot and what it was granted. */
+    agent?: string;
+    capabilities?: string[];
+    prompt?: string;
+}
+/** A one-line, content-free description of what a tool call was aimed at.
+ *  Paths, commands and URLs are the point of the record; file bodies are not,
+ *  and `content`/`old_string` style arguments are never read here. */
+export declare function describeAuditTarget(call: {
+    tool: string;
+    parameters: Record<string, unknown>;
+}): string;
+/** Audit is on unless explicitly disabled. A record you have to remember to
+ *  switch on is not a record you can rely on having. */
+export declare function isAuditEnabled(): boolean;
+/**
+ * Append one event. Never throws: an unwritable project (read-only checkout,
+ * full disk, a directory we lack permission for) must not take the agent down
+ * with it. A missing audit line is a gap in the record; a crashed run is worse.
+ */
+export declare function recordAuditEvent(projectRoot: string, event: AuditEvent): void;
+/** Open a run and return its id. Records the agent and the capabilities it was
+ *  granted, so a later reader can tell what the boundary *was* at the time —
+ *  a bot edited afterwards must not rewrite the history of what it could do. */
+export declare function beginAuditRun(projectRoot: string, opts: {
+    prompt: string;
+    agent?: string;
+    capabilities?: string[];
+}): string;
+export declare function endAuditRun(projectRoot: string, run: string, outcome: 'ok' | 'error', detail?: string): void;
+/** One run, reassembled from its lines. */
+export interface AuditRun {
+    run: string;
+    startedAt: number;
+    endedAt?: number;
+    prompt?: string;
+    agent?: string;
+    capabilities?: string[];
+    outcome?: 'ok' | 'error';
+    events: AuditEvent[];
+    refusals: number;
+}
+/**
+ * Read back the most recent runs, newest first.
+ *
+ * Malformed lines are skipped rather than throwing: an append-only log written
+ * by a process that may be killed mid-write will occasionally end in a partial
+ * line, and one torn line must not make the whole record unreadable.
+ */
+export declare function readAuditRuns(projectRoot: string, limit?: number): AuditRun[];
+/** Render recent runs for `/audit`. Deliberately compact: the question this
+ *  answers is "what has been happening here", and a wall of every event
+ *  answers it worse than a summary with the refusals called out. */
+export declare function formatAuditLog(projectRoot: string, limit?: number): string;

package/dist/utils/auditLog.js

@@ -0,0 +1,217 @@
+/**
+ * Audit record — what an agent actually touched.
+ *
+ * Distinct from `history.ts`, which exists to undo things: that journal keeps
+ * file contents so a write can be reversed, records only mutations, and lives
+ * in `~/.codeep/history/`. This one answers a different question — *what did
+ * this agent do to this project* — so it records reads and refusals too, keeps
+ * no file contents at all, and lives with the project it describes.
+ *
+ * The most valuable entry is the one nothing recorded before: a tool call the
+ * capability boundary refused. A boundary you cannot audit is a boundary you
+ * have to take on faith.
+ *
+ * Format is JSON Lines. Appending one line per event survives a crash mid-run,
+ * needs no read-modify-write, and stays greppable without a parser.
+ *
+ * PRIVACY: entries carry command lines and file paths, not file contents. A
+ * command can still contain a secret someone typed into it, exactly as shell
+ * history can — treat the directory like shell history, not like source.
+ *
+ * It sits under `.codeep/`, which most projects already ignore, but Codeep does
+ * not edit anyone's `.gitignore` and this module must not claim otherwise. If a
+ * project tracks `.codeep/`, the audit log will be committed with it.
+ */
+import { existsSync, mkdirSync, appendFileSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+import { config } from '../config/index.js';
+/** A one-line, content-free description of what a tool call was aimed at.
+ *  Paths, commands and URLs are the point of the record; file bodies are not,
+ *  and `content`/`old_string` style arguments are never read here. */
+export function describeAuditTarget(call) {
+    const p = call.parameters ?? {};
+    const str = (k) => (typeof p[k] === 'string' ? p[k] : undefined);
+    const command = str('command');
+    if (command) {
+        const args = Array.isArray(p.args) ? p.args.map(String) : [];
+        return [command, ...args].join(' ');
+    }
+    return str('path') ?? str('url') ?? str('pattern') ?? str('query') ?? str('directory') ?? call.tool;
+}
+const MAX_TARGET = 300;
+const MAX_DETAIL = 200;
+const MAX_PROMPT = 400;
+function auditDir(projectRoot) {
+    return join(projectRoot, '.codeep', 'audit');
+}
+/** One file per day keeps a long-lived project from growing a single huge log
+ *  while staying trivial to find — no index, no rotation logic. */
+function auditFile(projectRoot) {
+    const day = new Date().toISOString().slice(0, 10);
+    return join(auditDir(projectRoot), `${day}.jsonl`);
+}
+function clip(value, max) {
+    if (value === undefined)
+        return undefined;
+    const flat = value.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
+}
+/** Audit is on unless explicitly disabled. A record you have to remember to
+ *  switch on is not a record you can rely on having. */
+export function isAuditEnabled() {
+    return config.get('auditLog') !== false;
+}
+/**
+ * Append one event. Never throws: an unwritable project (read-only checkout,
+ * full disk, a directory we lack permission for) must not take the agent down
+ * with it. A missing audit line is a gap in the record; a crashed run is worse.
+ */
+export function recordAuditEvent(projectRoot, event) {
+    if (!isAuditEnabled())
+        return;
+    try {
+        const dir = auditDir(projectRoot);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const line = {
+            ...event,
+            target: clip(event.target, MAX_TARGET),
+            detail: clip(event.detail, MAX_DETAIL),
+            prompt: clip(event.prompt, MAX_PROMPT),
+        };
+        // Drop undefined keys so a line stays small and diffs stay readable.
+        const compact = Object.fromEntries(Object.entries(line).filter(([, v]) => v !== undefined));
+        appendFileSync(auditFile(projectRoot), JSON.stringify(compact) + '\n');
+    }
+    catch {
+        /* an unwritable audit log must never fail the run */
+    }
+}
+/** Open a run and return its id. Records the agent and the capabilities it was
+ *  granted, so a later reader can tell what the boundary *was* at the time —
+ *  a bot edited afterwards must not rewrite the history of what it could do. */
+export function beginAuditRun(projectRoot, opts) {
+    const run = randomBytes(6).toString('hex');
+    recordAuditEvent(projectRoot, {
+        ts: Date.now(),
+        run,
+        action: 'run-start',
+        prompt: opts.prompt,
+        agent: opts.agent,
+        capabilities: opts.capabilities,
+    });
+    return run;
+}
+export function endAuditRun(projectRoot, run, outcome, detail) {
+    recordAuditEvent(projectRoot, { ts: Date.now(), run, action: 'run-end', outcome, detail });
+}
+/**
+ * Read back the most recent runs, newest first.
+ *
+ * Malformed lines are skipped rather than throwing: an append-only log written
+ * by a process that may be killed mid-write will occasionally end in a partial
+ * line, and one torn line must not make the whole record unreadable.
+ */
+export function readAuditRuns(projectRoot, limit = 20) {
+    const dir = auditDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    let files;
+    try {
+        files = readdirSync(dir)
+            .filter(f => f.endsWith('.jsonl'))
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+    const runs = new Map();
+    for (const file of files) {
+        let raw;
+        try {
+            const path = join(dir, file);
+            if (statSync(path).size > 8 * 1024 * 1024)
+                continue; // skip an absurd file
+            raw = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (!event || typeof event.run !== 'string' || typeof event.ts !== 'number')
+                continue;
+            let entry = runs.get(event.run);
+            if (!entry) {
+                entry = { run: event.run, startedAt: event.ts, events: [], refusals: 0 };
+                runs.set(event.run, entry);
+            }
+            if (event.action === 'run-start') {
+                entry.startedAt = event.ts;
+                entry.prompt = event.prompt;
+                entry.agent = event.agent;
+                entry.capabilities = event.capabilities;
+            }
+            else if (event.action === 'run-end') {
+                entry.endedAt = event.ts;
+                entry.outcome = event.outcome === 'error' ? 'error' : 'ok';
+            }
+            else {
+                entry.events.push(event);
+                if (event.action === 'refused')
+                    entry.refusals++;
+            }
+        }
+        if (runs.size >= limit * 2)
+            break; // enough files read to satisfy `limit`
+    }
+    return [...runs.values()]
+        .sort((a, b) => b.startedAt - a.startedAt)
+        .slice(0, limit);
+}
+/** Render recent runs for `/audit`. Deliberately compact: the question this
+ *  answers is "what has been happening here", and a wall of every event
+ *  answers it worse than a summary with the refusals called out. */
+export function formatAuditLog(projectRoot, limit = 10) {
+    const runs = readAuditRuns(projectRoot, limit);
+    if (runs.length === 0) {
+        return isAuditEnabled()
+            ? 'No agent runs recorded in this project yet.\n\nThe record starts at the next run and lives in `.codeep/audit/`.'
+            : 'Audit recording is off for this project. Turn it on with `/audit on`.';
+    }
+    const lines = ['**Recent agent runs** — `.codeep/audit/`', ''];
+    for (const run of runs) {
+        const when = new Date(run.startedAt).toLocaleString();
+        const took = run.endedAt ? `${Math.max(1, Math.round((run.endedAt - run.startedAt) / 1000))}s` : 'unfinished';
+        const who = run.agent ? `**${run.agent}**` : 'default agent';
+        const grant = run.capabilities?.length ? ` (${run.capabilities.join(', ')})` : '';
+        const mark = run.outcome === 'error' ? '✗' : '✓';
+        lines.push(`${mark} ${when} · ${who}${grant} · ${took}`);
+        if (run.prompt)
+            lines.push(`   ${run.prompt}`);
+        // Summarise by action so a hundred reads collapse to "read ×100".
+        const tally = new Map();
+        for (const e of run.events)
+            tally.set(e.action, (tally.get(e.action) ?? 0) + 1);
+        const summary = [...tally.entries()].map(([a, n]) => (n > 1 ? `${a} ×${n}` : a)).join(', ');
+        if (summary)
+            lines.push(`   ${summary}`);
+        // Refusals are the reason this record exists, so they are never collapsed.
+        for (const e of run.events.filter(e => e.action === 'refused')) {
+            lines.push(`   ⨯ refused: ${e.tool}${e.target ? ` → ${e.target}` : ''}`);
+        }
+        lines.push('');
+    }
+    lines.push('_Paths and commands only — file contents are never recorded._');
+    return lines.join('\n');
+}

package/dist/utils/codeepCloud.d.ts

@@ -84,12 +84,37 @@ declare function readFileBundle(kind: 'personalities' | 'commands'): Record<stri
  *  files. Only writes files that don't already exist (additive merge —
  *  never clobber local edits). Returns the count of newly written files. */
 declare function writeFileBundle(kind: 'personalities' | 'commands', items: Record<string, string>): number;
+/** Apply the server's explicit deletion list.
+ *
+ *  Only names the server named. Absence from `items` is deliberately NOT a
+ *  deletion signal: an expired session, the wrong account, or a truncated
+ *  response all yield an empty `items`, and deleting on absence would wipe
+ *  every local agent. Project-scoped agents in `.codeep/personalities/` are
+ *  not cloud-owned and are never touched — only the global directory is.
+ *  Every removal is backed up first, and a failed backup cancels the delete. */
+declare function applyPersonalityTombstones(deleted: readonly string[]): number;
 declare function writePulledPersonalityBundle(items: Record<string, string>): number;
-export declare const pullPersonalities: () => Promise<number | null>;
+/** Why a sync attempt produced nothing. Reported so a silent failure cannot
+ *  look like a successful no-op — the two were indistinguishable when every
+ *  path returned `null`, and a user watching `codeep account sync` print
+ *  nothing had no way to tell which had happened. */
+export type SyncFailure = 'not-linked' | 'unreachable' | 'rejected' | 'malformed';
+/** Success carries a count (which may legitimately be 0 — nothing new), plus
+ *  how many local agents the server's tombstone list removed. */
+export type SyncResult = {
+    ok: true;
+    count: number;
+    removed: number;
+} | {
+    ok: false;
+    reason: SyncFailure;
+};
+export declare function describeSyncFailure(reason: SyncFailure): string;
+export declare const pullPersonalities: () => Promise<SyncResult>;
 export declare const getLastPersonalityPullBackupCount: () => number;
-export declare const pushPersonalities: () => Promise<number | null>;
-export declare const pullCommands: () => Promise<number | null>;
-export declare const pushCommands: () => Promise<number | null>;
+export declare const pushPersonalities: () => Promise<SyncResult>;
+export declare const pullCommands: () => Promise<SyncResult>;
+export declare const pushCommands: () => Promise<SyncResult>;
 /**
  * Sync session conversation history to codeep.dev.
  * Only user/assistant messages are sent — system messages are filtered out.
@@ -184,4 +209,5 @@ export declare const _globalDirForTest: typeof globalDir;
 export declare const _readFileBundleForTest: typeof readFileBundle;
 export declare const _writeFileBundleForTest: typeof writeFileBundle;
 export declare const _writePulledPersonalityBundleForTest: typeof writePulledPersonalityBundle;
+export declare const _applyPersonalityTombstonesForTest: typeof applyPersonalityTombstones;
 export {};