@botdocs/cli 0.10.3 → 0.12.0

package/dist/lib/auto-detect.js

@@ -1,5 +1,36 @@
 import path from 'node:path';
 const NORMALIZE = (p) => p.replace(/\\/g, '/');
+/**
+ * Defense-in-depth path confinement.
+ *
+ * The server-side validator in `apps/web/src/lib/filename-validation.ts` is
+ * the authoritative gate against malicious manifest filenames — `..`
+ * segments, absolute paths, NUL bytes, etc. all get rejected before they
+ * ever reach the DB. This function adds a second layer on the CLI side so
+ * an already-running CLI installing from a (hypothetical) server that
+ * regressed the validator still can't write outside the install root.
+ *
+ * Asserts `path.resolve(dest)` is contained within `path.resolve(root)`
+ * before returning the dest. If the post-join resolution escapes the
+ * root, throws a clear error so the install fails loudly rather than
+ * silently writing to `~/.zshenv` or `~/.ssh/authorized_keys`.
+ *
+ * Even branches that already use `path.basename(src)` (which neutralizes
+ * `..` on its own) call this — defense in depth means we don't have to
+ * remember which branches are safe-by-construction.
+ */
+function assertWithinRoot(dest, root, srcRelative) {
+    const resolvedDest = path.resolve(dest);
+    const resolvedRoot = path.resolve(root);
+    // The dest must be either the root itself (unusual but technically fine)
+    // or a strict descendant. `resolvedRoot + path.sep` avoids the classic
+    // `/root` ⊂ `/rootBAD` prefix-match pitfall.
+    if (resolvedDest !== resolvedRoot &&
+        !resolvedDest.startsWith(resolvedRoot + path.sep)) {
+        throw new Error(`Manifest filename '${srcRelative}' resolved outside install root '${resolvedRoot}'`);
+    }
+    return dest;
+}
 export function detectDestination(srcRelative, ctx) {
     const src = NORMALIZE(srcRelative);
     if (src.startsWith('claude/')) {
@@ -12,10 +43,9 @@ export function detectDestination(srcRelative, ctx) {
             ? remainder.replace(/^[^/]+\//, '')
             : remainder;
         const skillPath = ctx.flatScope ? ctx.slug : path.join(ctx.scope, ctx.slug);
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.claude', 'skills', skillPath, finalName),
-        };
+        const root = path.join(ctx.homeDir, '.claude', 'skills', skillPath);
+        const dest = path.join(root, finalName);
+        return { kind: 'global', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('claude-code/agents/')) {
         // Layout mirrors claude skills:
@@ -29,22 +59,19 @@ export function detectDestination(srcRelative, ctx) {
         const finalName = remainder.includes('/')
             ? remainder.replace(/^[^/]+\//, '')
             : remainder;
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.claude', 'agents', ctx.slug, finalName),
-        };
+        const root = path.join(ctx.projectDir, '.claude', 'agents', ctx.slug);
+        const dest = path.join(root, finalName);
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('claude-code/commands/')) {
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.claude', 'commands', path.basename(src)),
-        };
+        const root = path.join(ctx.projectDir, '.claude', 'commands');
+        const dest = path.join(root, path.basename(src));
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('cursor/rules/')) {
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.cursor', 'rules', path.basename(src)),
-        };
+        const root = path.join(ctx.projectDir, '.cursor', 'rules');
+        const dest = path.join(root, path.basename(src));
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('codex/')) {
         // Codex skills are nested SKILL.md directories at
@@ -61,27 +88,29 @@ export function detectDestination(srcRelative, ctx) {
         if (!remainder.includes('/')) {
             // Flat legacy form `codex/<slug>.md` → nested SKILL.md.
             const slug = remainder.replace(/\.md$/, '');
-            return { kind: 'global', dest: path.join(codexBase, slug, 'SKILL.md') };
+            const root = path.join(codexBase, slug);
+            const dest = path.join(root, 'SKILL.md');
+            return { kind: 'global', dest: assertWithinRoot(dest, root, srcRelative) };
         }
         const finalName = remainder.replace(/^[^/]+\//, '');
-        return { kind: 'global', dest: path.join(codexBase, ctx.slug, finalName) };
+        const root = path.join(codexBase, ctx.slug);
+        const dest = path.join(root, finalName);
+        return { kind: 'global', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('copilot/instructions/')) {
         // GitHub Copilot custom instructions live in .github/instructions/
         // (https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot).
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.github', 'instructions', path.basename(src)),
-        };
+        const root = path.join(ctx.projectDir, '.github', 'instructions');
+        const dest = path.join(root, path.basename(src));
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('windsurf/rules/')) {
         // Windsurf reads project rules from <proj>/.windsurf/rules/<slug>.md
         // (docs.windsurf.com). Flat .md rule, project-scoped. The canonical form
         // is already flat, so basename() is the right leaf either way.
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.windsurf', 'rules', path.basename(src)),
-        };
+        const root = path.join(ctx.projectDir, '.windsurf', 'rules');
+        const dest = path.join(root, path.basename(src));
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('gemini/')) {
         // Gemini CLI has NO per-skill file directory — it uses hierarchical
@@ -89,6 +118,9 @@ export function detectDestination(srcRelative, ctx) {
         // project). There's no real path to write to, so route to `manual` (like
         // chatgpt): install surfaces the content for the user to paste into their
         // GEMINI.md or @import it, rather than fabricating ~/.gemini/instructions/.
+        //
+        // `manual` doesn't write to disk, so confinement doesn't apply — `dest`
+        // here is just an informational hint shown to the user.
         return { kind: 'manual', dest: src };
     }
     if (src.startsWith('antigravity/skills/')) {
@@ -108,10 +140,14 @@ export function detectDestination(srcRelative, ctx) {
         const agentBase = path.join(ctx.projectDir, '.agent', 'skills');
         if (!remainder.includes('/')) {
             const slug = remainder.replace(/\.md$/, '');
-            return { kind: 'project', dest: path.join(agentBase, slug, 'SKILL.md') };
+            const root = path.join(agentBase, slug);
+            const dest = path.join(root, 'SKILL.md');
+            return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
         }
         const finalName = remainder.replace(/^[^/]+\//, '');
-        return { kind: 'project', dest: path.join(agentBase, ctx.slug, finalName) };
+        const root = path.join(agentBase, ctx.slug);
+        const dest = path.join(root, finalName);
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('opencode/')) {
         // OpenCode skills are nested SKILL.md directories (opencode.ai/docs/skills).
@@ -128,13 +164,17 @@ export function detectDestination(srcRelative, ctx) {
         const opencodeBase = path.join(ctx.projectDir, '.opencode', 'skills');
         if (src.startsWith('opencode/instructions/')) {
             const slug = path.basename(src).replace(/\.md$/, '');
-            return { kind: 'project', dest: path.join(opencodeBase, slug, 'SKILL.md') };
+            const root = path.join(opencodeBase, slug);
+            const dest = path.join(root, 'SKILL.md');
+            return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
         }
         const remainder = src.slice('opencode/'.length);
         const finalName = remainder.includes('/')
             ? remainder.replace(/^[^/]+\//, '')
             : remainder;
-        return { kind: 'project', dest: path.join(opencodeBase, ctx.slug, finalName) };
+        const root = path.join(opencodeBase, ctx.slug);
+        const dest = path.join(root, finalName);
+        return { kind: 'project', dest: assertWithinRoot(dest, root, srcRelative) };
     }
     if (src.startsWith('chatgpt/')) {
         return { kind: 'manual', dest: src };

package/dist/lib/config.d.ts

@@ -14,4 +14,19 @@ interface AuthConfig {
 export declare function saveAuth(config: AuthConfig): void;
 export declare function loadAuth(): AuthConfig | null;
 export declare function clearAuth(): void;
+/** One-time startup migration check. If auth.json exists and was created by
+ * a pre-P1-G CLI (mode 0644 / world-readable), tighten it in place AND
+ * warn the user — the token may have been read by another local user, so
+ * they should consider rotating it via /settings/tokens.
+ *
+ * Best-effort: never throws, never blocks CLI startup. Skipped on Windows
+ * where POSIX modes don't apply. Returns a structured result so callers
+ * (and tests) can observe the action taken without scraping stderr.
+ */
+export interface AuthPermsCheck {
+    changed: boolean;
+    previousMode?: number;
+    warning?: string;
+}
+export declare function checkAuthFilePerms(): AuthPermsCheck;
 export {};

package/dist/lib/config.js

@@ -1,6 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+// POSIX modes used for the CLI's credential storage. The token lives in
+// auth.json and is the bearer for every authenticated API call — a default
+// umask of 022 leaves the file at 0644 (world-readable) on shared dev
+// boxes, which is a real exfiltration surface. We lock the dir to 0700 and
+// the file to 0600 so only the owning user can traverse/read.
+const CONFIG_DIR_MODE = 0o700; // rwx for user only
+const CONFIG_FILE_MODE = 0o600; // rw for user only
 // Resolved lazily so tests can swap os.homedir between cases without having
 // to monkey-patch a captured constant.
 function getConfigDir() {
@@ -12,12 +19,46 @@ function getAuthFile() {
 function ensureConfigDir() {
     const dir = getConfigDir();
     if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
+        fs.mkdirSync(dir, { recursive: true, mode: CONFIG_DIR_MODE });
+        return dir;
     }
+    // Existing dir — if it's too permissive, lock it down. Don't try this
+    // on Windows where chmod is largely a no-op; the per-user profile ACL
+    // is the real defense.
+    if (process.platform !== 'win32') {
+        try {
+            const stat = fs.statSync(dir);
+            const currentMode = stat.mode & 0o777;
+            if (currentMode !== CONFIG_DIR_MODE) {
+                fs.chmodSync(dir, CONFIG_DIR_MODE);
+            }
+        }
+        catch {
+            // Best-effort. A chmod failure shouldn't block login.
+        }
+    }
+    return dir;
 }
 export function saveAuth(config) {
     ensureConfigDir();
-    fs.writeFileSync(getAuthFile(), JSON.stringify(config, null, 2), 'utf-8');
+    const file = getAuthFile();
+    // The `mode` option on writeFileSync only takes effect when the file
+    // doesn't exist yet (it's passed to open(O_CREAT)). For existing files
+    // the underlying inode mode is preserved, which means an auth.json
+    // written before this hardening landed would stay 0644 forever. So we
+    // chmod separately below.
+    fs.writeFileSync(file, JSON.stringify(config, null, 2), {
+        encoding: 'utf-8',
+        mode: CONFIG_FILE_MODE,
+    });
+    if (process.platform !== 'win32') {
+        try {
+            fs.chmodSync(file, CONFIG_FILE_MODE);
+        }
+        catch {
+            // Best-effort — a chmod failure shouldn't fail login.
+        }
+    }
 }
 export function loadAuth() {
     const file = getAuthFile();
@@ -37,3 +78,43 @@ export function clearAuth() {
         fs.unlinkSync(file);
     }
 }
+export function checkAuthFilePerms() {
+    if (process.platform === 'win32')
+        return { changed: false };
+    const file = getAuthFile();
+    if (!fs.existsSync(file))
+        return { changed: false };
+    let previousMode;
+    try {
+        previousMode = fs.statSync(file).mode & 0o777;
+    }
+    catch {
+        return { changed: false };
+    }
+    if (previousMode === CONFIG_FILE_MODE)
+        return { changed: false };
+    // Mode is wrong — tighten in place and surface a warning. We intentionally
+    // do NOT clear the token; the user's session keeps working, but we tell
+    // them their bearer was historically readable so they can rotate.
+    try {
+        fs.chmodSync(file, CONFIG_FILE_MODE);
+    }
+    catch {
+        // chmod failed — still surface the warning so the user knows.
+    }
+    // Also tighten the directory in passing.
+    try {
+        const dir = getConfigDir();
+        const dirMode = fs.statSync(dir).mode & 0o777;
+        if (dirMode !== CONFIG_DIR_MODE) {
+            fs.chmodSync(dir, CONFIG_DIR_MODE);
+        }
+    }
+    catch {
+        // best-effort
+    }
+    const warning = `botdocs: ~/.botdocs/auth.json was mode ${previousMode.toString(8).padStart(4, '0')} ` +
+        `(world/group readable). Fixed to 0600. If this machine has other users, ` +
+        `consider rotating your token at https://botdocs.ai/settings/tokens.`;
+    return { changed: true, previousMode, warning };
+}

package/dist/lib/ingest-session-client.d.ts

@@ -0,0 +1,93 @@
+export interface ClaimResult {
+    sessionId: string;
+    expiresAt: string;
+}
+export declare class PairingClaimError extends Error {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number, options?: {
+        cause?: unknown;
+    });
+}
+/** Event types and per-type payload shapes — must stay aligned with the
+ * web schema in apps/web/src/lib/ingest-session.ts. Drift here means the
+ * server 400s and the CLI swallows it silently. Bump both in lockstep. */
+export type EventType = 'selection_committed' | 'upload_started' | 'upload_completed' | 'upload_failed' | 'cancelled';
+export interface EventPayloads {
+    selection_committed: {
+        totalSelected: number;
+        candidatesScanned: number;
+    };
+    upload_started: {
+        filename: string;
+        type: 'agent' | 'prompt' | 'context' | 'workflow';
+        experimental: boolean;
+    };
+    upload_completed: {
+        filename: string;
+        type: 'agent' | 'prompt' | 'context' | 'workflow';
+        experimental: boolean;
+        draftId: string;
+        slug: string;
+    };
+    upload_failed: {
+        filename: string;
+        reason: string;
+    };
+    cancelled: {
+        reason?: string;
+    };
+}
+export interface IngestSessionClientOptions {
+    /** Window in ms within which queued events are batched before sending.
+     * Defaults to 80 ms — short enough to feel real-time, long enough to
+     * batch ~10 file events into one round-trip on a fast scan. */
+    batchWindowMs?: number;
+    /** Override `console.error` for tests. */
+    logger?: (msg: string) => void;
+}
+/** Encapsulates the paired-session lifecycle. Created in two phases:
+ * `new IngestSessionClient(...)` then `await client.claim(code)`. Once
+ * `sessionId` is set, `emit` / `finalize` / `cancel` are usable. */
+export declare class IngestSessionClient {
+    private sessionId;
+    private readonly queue;
+    private flushTimer;
+    private flushing;
+    private closed;
+    private readonly batchWindowMs;
+    private readonly log;
+    constructor(options?: IngestSessionClientOptions);
+    /** True when a code has been claimed and events can flow. */
+    get isPaired(): boolean;
+    /** Exchange a BD-XXXXX code for a sessionId. Throws PairingClaimError on
+     * any non-2xx — the caller is expected to catch and offer the user a
+     * graceful "continue without pairing" path.
+     *
+     * Side effect: ON SUCCESS the server writes a `paired` event (seq 1)
+     * with the machineName + cwd. We don't queue that locally because the
+     * server already has it. */
+    claim(input: {
+        code: string;
+        machineName: string;
+        cwd: string;
+    }): Promise<ClaimResult>;
+    /** Queue an event for the next batched flush. No-op when not paired or
+     * after the session is closed. NEVER throws — the catch in `flush()`
+     * downgrades errors to a debug log. */
+    emit<T extends EventType>(type: T, payload: EventPayloads[T]): void;
+    /** Send the final `done` event + flip session state to `complete`.
+     * Flushes any pending events first so the consumer sees them before
+     * the end-of-stream marker. NEVER throws. */
+    finalize(totals: {
+        uploaded: number;
+        failed: number;
+    }): Promise<void>;
+    /** Cancel the session — used on Ctrl+C and on the unhappy-path early
+     * return. Writes a `cancelled` event server-side. NEVER throws. */
+    cancel(reason?: string): Promise<void>;
+    /** Manually flush any queued events synchronously. Public for tests +
+     * the finalize path; the normal flow goes through `scheduleFlush()`. */
+    flushNow(): Promise<void>;
+    private scheduleFlush;
+    private drainQueue;
+}

package/dist/lib/ingest-session-client.js

@@ -0,0 +1,217 @@
+/**
+ * CLI-side client for the live ingest pairing flow.
+ *
+ * Lifecycle:
+ *
+ *   1. User runs `botdocs ingest --pair`. The CLI prompts for the code
+ *      that the web's onboarding step shows them (BD-XXXXX).
+ *   2. CLI calls `claim()`. On success, the server has flipped the
+ *      session to `paired` and we hold a `sessionId` we use for events.
+ *   3. CLI calls `emit(type, payload)` as the ingest flow progresses.
+ *      Events are buffered briefly (default 80ms) and flushed in
+ *      batches to amortize round-trips during a fast scan.
+ *   4. On success, CLI calls `finalize({ uploaded, failed })`. On
+ *      failure or Ctrl+C, CLI calls `cancel()`.
+ *
+ * Resilience: every network call is **fire-and-forget from the user's
+ * perspective**. Pairing is a nice-to-have side channel — if the API is
+ * down or the user has flaky wifi, the ingest itself must continue. So:
+ *
+ *   - `claim()` rejects with `PairingClaimError` so the caller can decide
+ *     whether to fall back to unpaired mode (we do).
+ *   - All other calls (`emit`, `finalize`, `cancel`) NEVER throw. They
+ *     log to stderr in debug mode and drop the event quietly otherwise.
+ *
+ * Batching: events queued up while a flush is in flight stack up in
+ * `pendingFlush` so we don't fan-out concurrent POSTs. A trailing flush
+ * is scheduled at most once per debounce window.
+ */
+import { ApiError, apiFetch } from './api.js';
+const DEBUG = process.env.BOTDOCS_DEBUG === '1';
+const DEFAULT_BATCH_WINDOW_MS = 80;
+export class PairingClaimError extends Error {
+    status;
+    constructor(message, status, options) {
+        super(message, options);
+        this.name = 'PairingClaimError';
+        this.status = status;
+    }
+}
+/** Encapsulates the paired-session lifecycle. Created in two phases:
+ * `new IngestSessionClient(...)` then `await client.claim(code)`. Once
+ * `sessionId` is set, `emit` / `finalize` / `cancel` are usable. */
+export class IngestSessionClient {
+    sessionId = null;
+    queue = [];
+    flushTimer = null;
+    flushing = false;
+    closed = false;
+    batchWindowMs;
+    log;
+    constructor(options = {}) {
+        this.batchWindowMs = options.batchWindowMs ?? DEFAULT_BATCH_WINDOW_MS;
+        this.log = options.logger ?? ((msg) => process.stderr.write(`${msg}\n`));
+    }
+    /** True when a code has been claimed and events can flow. */
+    get isPaired() {
+        return this.sessionId !== null && !this.closed;
+    }
+    /** Exchange a BD-XXXXX code for a sessionId. Throws PairingClaimError on
+     * any non-2xx — the caller is expected to catch and offer the user a
+     * graceful "continue without pairing" path.
+     *
+     * Side effect: ON SUCCESS the server writes a `paired` event (seq 1)
+     * with the machineName + cwd. We don't queue that locally because the
+     * server already has it. */
+    async claim(input) {
+        try {
+            const res = await apiFetch('/api/cli/ingest-sessions/claim', {
+                method: 'POST',
+                auth: true,
+                body: {
+                    code: input.code,
+                    machineName: input.machineName,
+                    cwd: input.cwd,
+                },
+            });
+            this.sessionId = res.sessionId;
+            return res;
+        }
+        catch (err) {
+            if (err instanceof ApiError) {
+                // Translate the most common cases into actionable copy. Anything
+                // else falls through with the server's message.
+                if (err.status === 404) {
+                    throw new PairingClaimError("Pairing code not recognized. Check the onboarding page for a fresh code.", 404, { cause: err });
+                }
+                if (err.status === 410) {
+                    throw new PairingClaimError('Pairing code expired. Refresh the onboarding page for a fresh code.', 410, { cause: err });
+                }
+                if (err.status === 409) {
+                    throw new PairingClaimError('Pairing code was already used. Refresh the onboarding page for a fresh code.', 409, { cause: err });
+                }
+                throw new PairingClaimError(err.message, err.status, { cause: err });
+            }
+            throw new PairingClaimError(err instanceof Error ? err.message : 'Failed to pair with botdocs.ai', undefined, { cause: err });
+        }
+    }
+    /** Queue an event for the next batched flush. No-op when not paired or
+     * after the session is closed. NEVER throws — the catch in `flush()`
+     * downgrades errors to a debug log. */
+    emit(type, payload) {
+        if (!this.isPaired)
+            return;
+        this.queue.push({ type, payload });
+        this.scheduleFlush();
+    }
+    /** Send the final `done` event + flip session state to `complete`.
+     * Flushes any pending events first so the consumer sees them before
+     * the end-of-stream marker. NEVER throws. */
+    async finalize(totals) {
+        if (!this.sessionId || this.closed)
+            return;
+        await this.flushNow();
+        const sessionId = this.sessionId;
+        this.closed = true;
+        try {
+            await apiFetch(`/api/cli/ingest-sessions/${encodeURIComponent(sessionId)}/finalize`, {
+                method: 'POST',
+                auth: true,
+                body: totals,
+            });
+        }
+        catch (err) {
+            if (DEBUG)
+                this.log(`[pair] finalize failed: ${describe(err)}`);
+        }
+    }
+    /** Cancel the session — used on Ctrl+C and on the unhappy-path early
+     * return. Writes a `cancelled` event server-side. NEVER throws. */
+    async cancel(reason) {
+        if (!this.sessionId || this.closed)
+            return;
+        const sessionId = this.sessionId;
+        this.closed = true;
+        // Best-effort: do NOT flush the queue. Cancel is the "user hit Ctrl+C"
+        // path; getting the cancel signal in fast matters more than
+        // delivering trailing events.
+        try {
+            await apiFetch(`/api/ingest-sessions/${encodeURIComponent(sessionId)}`, {
+                method: 'DELETE',
+                auth: true,
+                body: reason ? { reason } : undefined,
+            });
+        }
+        catch (err) {
+            if (DEBUG)
+                this.log(`[pair] cancel failed: ${describe(err)}`);
+        }
+    }
+    /** Manually flush any queued events synchronously. Public for tests +
+     * the finalize path; the normal flow goes through `scheduleFlush()`. */
+    async flushNow() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.drainQueue();
+    }
+    scheduleFlush() {
+        if (this.flushTimer || this.flushing)
+            return;
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            void this.drainQueue();
+        }, this.batchWindowMs);
+        // Don't let a pending flush keep the Node process alive — the CLI
+        // exit path will call finalize() which awaits a final flush anyway.
+        if (typeof this.flushTimer.unref === 'function') {
+            this.flushTimer.unref();
+        }
+    }
+    async drainQueue() {
+        if (this.flushing)
+            return;
+        if (!this.sessionId || this.closed) {
+            this.queue.length = 0;
+            return;
+        }
+        if (this.queue.length === 0)
+            return;
+        this.flushing = true;
+        // Snapshot the current batch and clear the queue under the lock.
+        // Anything queued while we're posting will get sent on the next tick.
+        const batch = this.queue.splice(0, this.queue.length);
+        try {
+            await apiFetch(`/api/cli/ingest-sessions/${encodeURIComponent(this.sessionId)}/events`, {
+                method: 'POST',
+                auth: true,
+                body: { events: batch },
+            });
+        }
+        catch (err) {
+            if (DEBUG)
+                this.log(`[pair] events flush failed (dropped ${batch.length}): ${describe(err)}`);
+            // Don't requeue — a retry storm against a down endpoint helps no one.
+            // The web side will see a gap in the seq sequence and the design
+            // already handles partial event loss (it renders what it has).
+        }
+        finally {
+            this.flushing = false;
+        }
+        // If more events arrived during the in-flight POST, schedule another
+        // flush. Bounded recursion via the timer (not a tight loop).
+        if (this.queue.length > 0)
+            this.scheduleFlush();
+    }
+}
+function describe(err) {
+    if (err instanceof Error)
+        return err.message;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}

package/dist/lib/lockfile.d.ts

@@ -20,6 +20,19 @@ export interface InstalledRef {
         type: 'team';
         slug: string;
     };
+    /** True when the most recent sync bumped the lockfile to the current
+     * upstream version BUT couldn't apply every change — at least one file
+     * still reflects the user's local edits (preserved via a skip choice).
+     * Subsequent syncs use `skippedFiles` to know which files still need
+     * conflict resolution; the rest are treated as up-to-date.
+     *
+     * Absent/false on a clean install or a fully-applied sync. */
+    partial?: boolean;
+    /** The list of `src` paths the most recent sync skipped on this entry.
+     * Used in concert with `partial` so sync display can say "1 file
+     * skipped — conflict" and so the next sync can leave clean files alone
+     * while still surfacing the unresolved ones. */
+    skippedFiles?: string[];
 }
 export interface Lockfile {
     version: 1;

package/dist/lib/manifest.d.ts

@@ -2,6 +2,18 @@ export type BotDocType = 'SPEC' | 'SKILL' | 'BUNDLE';
 export declare class ManifestError extends Error {
     constructor(message: string);
 }
+/**
+ * The placeholder description `botdocs init` writes into a fresh manifest.
+ * Duplicated here (kept in sync with the constant in `commands/init.ts`) so
+ * the validator can reject the exact string without commands/init.ts and
+ * lib/manifest.ts having a circular dependency (init imports validate
+ * indirectly through the publish flow; manifest is upstream of both).
+ *
+ * If you change this, change `INIT_PLACEHOLDER_DESCRIPTION` in
+ * `commands/init.ts` to match — a string-literal diff in either file
+ * silently breaks the "you left the placeholder" detection.
+ */
+export declare const INIT_PLACEHOLDER_DESCRIPTION = "TODO: describe your skill in one sentence.";
 export interface SkillRef {
     username: string;
     slug: string;