codiedev 0.9.18 → 0.9.20

package/dist/captureLog.d.ts

@@ -0,0 +1,20 @@
+import * as fs from "fs";
+export declare const CAPTURE_LOG_MAX_BYTES: number;
+export declare const CAPTURE_LOG_PATH: string;
+export interface CaptureLogEntry {
+    stage: "capture-finish" | "upload" | "upload-deferred" | "stderr";
+    sessionId: string | undefined;
+    outcome: string;
+    detail?: string;
+}
+interface LogDeps {
+    readFileSync: typeof fs.readFileSync;
+    writeFileSync: typeof fs.writeFileSync;
+    appendFileSync: typeof fs.appendFileSync;
+    existsSync: typeof fs.existsSync;
+    mkdirSync: typeof fs.mkdirSync;
+    statSync: typeof fs.statSync;
+}
+export declare function appendCaptureLog(entry: CaptureLogEntry, deps?: LogDeps, filePath?: string, now?: () => number): void;
+export declare function readCaptureLogTail(n: number, deps?: Pick<LogDeps, "readFileSync" | "existsSync">, filePath?: string): string[];
+export {};

package/dist/captureLog.js

@@ -0,0 +1,101 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CAPTURE_LOG_PATH = exports.CAPTURE_LOG_MAX_BYTES = void 0;
+exports.appendCaptureLog = appendCaptureLog;
+exports.readCaptureLogTail = readCaptureLogTail;
+// Rotating capture diagnostic log at ~/.codiedev/capture.log.
+//
+// Every stage of the capture pipeline (capture-finish child, upload child,
+// stderr from detached children) writes one line here so users — and
+// `codiedev doctor` — can see exactly why a capture succeeded or failed
+// without having to file a support ticket or grep /tmp. The log is
+// best-effort throughout: appendCaptureLog NEVER throws into the hook path.
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// Rotate the log when it exceeds this size (keeps the newest ~half). 256 KB
+// holds thousands of entries; a user would have to see hundreds of errors
+// before hitting this limit, so it's a generous safety valve.
+exports.CAPTURE_LOG_MAX_BYTES = 256 * 1024;
+exports.CAPTURE_LOG_PATH = path.join(os.homedir(), ".codiedev", "capture.log");
+// Append one structured line to the capture log. Rotates the file when it
+// grows past CAPTURE_LOG_MAX_BYTES by truncating it to the newest half (keeps
+// the most recent diagnostics). Best-effort: NEVER throws into the hook path —
+// a diagnostic log must not break the thing it's diagnosing.
+function appendCaptureLog(entry, deps = fs, filePath = exports.CAPTURE_LOG_PATH, now = Date.now) {
+    try {
+        const dir = path.dirname(filePath);
+        if (!deps.existsSync(dir))
+            deps.mkdirSync(dir, { recursive: true });
+        if (deps.existsSync(filePath) && deps.statSync(filePath).size >= exports.CAPTURE_LOG_MAX_BYTES) {
+            // Rotation: keep the newest half. Slice from the middle to a line
+            // boundary so we never persist a torn (partial) first line.
+            const content = deps.readFileSync(filePath, "utf8");
+            const half = content.slice(Math.floor(content.length / 2));
+            const firstNewline = half.indexOf("\n");
+            // If no newline is found in the second half, drop it all and start
+            // fresh — better than keeping a torn line.
+            const fromLine = firstNewline === -1 ? "" : half.slice(firstNewline + 1);
+            deps.writeFileSync(filePath, fromLine);
+        }
+        // Sanitize before composing: error messages can carry newlines (e.g. a
+        // proxy's HTML error body in err.message) which would tear the one-line
+        // format that doctor's parser depends on.
+        const outcome = entry.outcome.replace(/\s+/g, " ").trim();
+        const detail = entry.detail?.replace(/\s+/g, " ").trim();
+        const line = `${new Date(now()).toISOString()} ${entry.stage} session=${entry.sessionId ?? "-"} ${outcome}` +
+            (detail ? ` ${detail}` : "") +
+            "\n";
+        deps.appendFileSync(filePath, line);
+    }
+    catch {
+        // diagnostics must never break capture
+    }
+}
+// Read the last N lines from the capture log. Returns [] when the file is
+// missing or unreadable — callers (e.g. `codiedev doctor`) treat that as
+// "nothing captured yet" rather than an error.
+function readCaptureLogTail(n, deps = fs, filePath = exports.CAPTURE_LOG_PATH) {
+    try {
+        if (!deps.existsSync(filePath))
+            return [];
+        const lines = deps.readFileSync(filePath, "utf8").split("\n").filter(Boolean);
+        return lines.slice(-n);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/captureReadiness.d.ts

@@ -32,6 +32,11 @@ export interface LastCaptureSummary {
     detail: string;
 }
 export declare function summarizeLastCapture(record: LastCaptureRecord | null, nowMs: number): LastCaptureSummary;
+export interface CaptureActivitySummary {
+    status: "pass" | "warn" | "fail";
+    detail: string;
+}
+export declare function summarizeCaptureActivity(tailLines: string[], pendingJobCount: number): CaptureActivitySummary;
 export interface ServerCaptureResponse {
     found: boolean;
     latest: {

package/dist/captureReadiness.js

@@ -11,6 +11,7 @@ exports.assessCaptureReadiness = assessCaptureReadiness;
 exports.assessWorkspaceRepos = assessWorkspaceRepos;
 exports.formatRelativeAge = formatRelativeAge;
 exports.summarizeLastCapture = summarizeLastCapture;
+exports.summarizeCaptureActivity = summarizeCaptureActivity;
 exports.summarizeServerCapture = summarizeServerCapture;
 function assessCaptureReadiness(cwd, repos, deps) {
     let gitOnPath = false;
@@ -95,6 +96,115 @@ function summarizeLastCapture(record, nowMs) {
     }
     return { status: "pass", detail: `last session captured ${age} ago` };
 }
+// ─── Capture-activity summarizer ──────────────────────────────────────────────
+// Turns the tail of ~/.codiedev/capture.log + a count of pending upload jobs
+// into a single doctor CheckResult-compatible {status, detail} object.
+//
+// Pure (no fs/os imports) — all data is injected by the caller (doctor.ts).
+const LOG_PATH_SUFFIX = "— details: ~/.codiedev/capture.log";
+// Parse regex: a valid structured line has exactly this shape.
+// stage is one of the four known stages; outcome is a bare token.
+const STRUCTURED_LINE_RE = /^(\S+) (capture-finish|upload|upload-deferred|stderr) session=(\S+) (\S+)(?: (.*))?$/;
+/** Append the shared log-path suffix to any detail string. */
+function withSuffix(detail) {
+    return `${detail} ${LOG_PATH_SUFFIX}`;
+}
+/**
+ * Derive remediation text and status from the last failing upload-ish line.
+ * Inspects the `detail` field of the log line for http= and msg= tokens.
+ */
+function failDetail(rawLine, outcome, lineDetail) {
+    const d = lineDetail ?? "";
+    const truncated = rawLine.slice(0, 140);
+    let hint;
+    if (/http=40[13]/.test(d)) {
+        hint = `token invalid or expired — run \`codiedev connect\` with a fresh token`;
+    }
+    else if (/http=5/.test(d) || /fetch|network|ECONN|ETIMEDOUT/i.test(d)) {
+        hint = `backend unreachable — uploads are queued and retried automatically`;
+    }
+    else if (outcome === "gave-up") {
+        hint = `an upload exhausted its retries — check network/proxy, then run a new session`;
+    }
+    else {
+        hint = `see the log line for details`;
+    }
+    return withSuffix(`${hint} (${truncated})`);
+}
+function summarizeCaptureActivity(tailLines, pendingJobCount) {
+    const parsed = [];
+    for (const raw of tailLines) {
+        const m = STRUCTURED_LINE_RE.exec(raw);
+        if (!m)
+            continue;
+        parsed.push({ ts: m[1], stage: m[2], session: m[3], outcome: m[4], detail: m[5], raw });
+    }
+    // We care only about upload-ish lines (upload + upload-deferred).
+    // capture-finish and stderr lines are noise for this check.
+    const uploadLines = parsed.filter((p) => p.stage === "upload" || p.stage === "upload-deferred");
+    // Rule 1: last upload-ish outcome is ERROR or gave-up → fail.
+    if (uploadLines.length > 0) {
+        const last = uploadLines[uploadLines.length - 1];
+        if (last.outcome === "ERROR" || last.outcome === "gave-up") {
+            return {
+                status: "fail",
+                detail: failDetail(last.raw, last.outcome, last.detail),
+            };
+        }
+    }
+    // Rule 2: pending jobs queued (last upload wasn't a hard failure, but
+    // retries are still in-flight).
+    if (pendingJobCount > 0) {
+        const noun = pendingJobCount === 1 ? "job" : "jobs";
+        return {
+            status: "warn",
+            detail: withSuffix(`${pendingJobCount} pending upload ${noun} queued for retry`),
+        };
+    }
+    // Rule 3: no upload-ish lines at all — log is empty, garbage-only, or
+    // only capture-finish lines.
+    if (uploadLines.length === 0) {
+        return {
+            status: "warn",
+            detail: withSuffix("no capture uploads recorded yet on this machine — run a session and exit, then re-run `codiedev doctor`"),
+        };
+    }
+    // Rule 4a: last upload-ish outcome is ok → pass.
+    const last = uploadLines[uploadLines.length - 1];
+    const hasOk = uploadLines.some((p) => p.outcome === "ok");
+    if (last.outcome === "ok") {
+        return {
+            status: "pass",
+            detail: withSuffix(`last upload ok (${last.ts})`),
+        };
+    }
+    // Rule 4b: last is "deferred" — a throttled/scheduled defer was queued.
+    // If an ok exists somewhere in the tail → pass (next upload deferred is fine).
+    // If no ok exists → warn.
+    if (last.outcome === "deferred") {
+        if (hasOk) {
+            return {
+                status: "pass",
+                detail: withSuffix(`last upload ok; next upload deferred (throttle)`),
+            };
+        }
+        return {
+            status: "warn",
+            detail: withSuffix("deferred uploads were superseded but no completed upload found in the recent log"),
+        };
+    }
+    // Rule 4c: last is "superseded".
+    if (hasOk) {
+        return {
+            status: "pass",
+            detail: withSuffix(`last upload ok (a later upload superseded an earlier one)`),
+        };
+    }
+    return {
+        status: "warn",
+        detail: withSuffix("deferred uploads were superseded but no completed upload found in the recent log"),
+    };
+}
 // Server-confirmed "did my last session land?". Prefers portal truth over the
 // local 2xx breadcrumb; the highest-value branch is "uploaded locally but the
 // portal has no record" — the exact silent failure devs hit (2xx to nothing,

package/dist/commands/doctor.js

@@ -44,6 +44,7 @@ const detection_1 = require("../detection");
 const version_1 = require("../version");
 const upgradeNudge_1 = require("../upgradeNudge");
 const captureReadiness_1 = require("../captureReadiness");
+const captureLog_1 = require("../captureLog");
 const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), ".claude", "settings.json");
 const CLAUDE_INSTRUCTIONS_PATH = path.join(os.homedir(), ".claude", "CLAUDE.md");
 const CODEX_HOOKS_PATH = path.join(os.homedir(), ".codex", "hooks.json");
@@ -310,6 +311,23 @@ async function runDoctor(_args) {
         status: lastCapture.status,
         detail: lastCapture.detail,
     });
+    // 4d. Capture-log activity: did recent uploads succeed? Are there pending jobs?
+    const logTail = (0, captureLog_1.readCaptureLogTail)(40);
+    let pendingJobCount = 0;
+    try {
+        pendingJobCount = fs
+            .readdirSync(os.tmpdir())
+            .filter((f) => /^codiedev-capture-.*\.json(\.claim-\d+)?$/.test(f)).length;
+    }
+    catch {
+        pendingJobCount = 0;
+    }
+    const captureActivity = (0, captureReadiness_1.summarizeCaptureActivity)(logTail, pendingJobCount);
+    checks.push({
+        name: "Recent capture activity",
+        status: captureActivity.status,
+        detail: captureActivity.detail,
+    });
     // 5. Claude Code setup (if present)
     if ((0, utils_1.claudeCodeInstalled)()) {
         checks.push({

package/dist/connect.js

@@ -42,7 +42,10 @@ const connectFlow_1 = require("./connectFlow");
 const version_1 = require("./version");
 const upgradeNudge_1 = require("./upgradeNudge");
 const shared_1 = require("./commands/shared");
-const BACKEND_URL = process.env.CODIEDEV_URL || "https://judicious-falcon-861.convex.site";
+// cli.codiedev.com is a Convex custom domain on the prod deployment; the
+// underlying judicious-falcon-861.convex.site URL keeps serving, so configs
+// written by older CLI versions stay valid without a re-connect.
+const BACKEND_URL = process.env.CODIEDEV_URL || "https://cli.codiedev.com";
 /**
  * Reads a line from stdin without echoing the typed/pasted characters —
  * for tokens, passwords, anything that shouldn't end up in terminal

package/dist/hook.js

@@ -43,6 +43,7 @@ const child_process_1 = require("child_process");
 const utils_1 = require("./utils");
 const limitEvent_1 = require("./limitEvent");
 const version_1 = require("./version");
+const captureLog_1 = require("./captureLog");
 function getJson(url, bearerToken) {
     return new Promise((resolve, reject) => {
         const parsed = new URL(url);
@@ -220,22 +221,49 @@ function resolveMode(arg) {
     return "claude-code";
 }
 async function main() {
+    // Shared upload deps used by both "upload" and "upload-deferred" branches.
+    // Extracted to keep both branches in lockstep — any new dep added here
+    // automatically applies to the deferred path too.
+    function makeUploadDeps() {
+        return {
+            post: postJson,
+            readFileSync: fs.readFileSync,
+            unlinkSync: fs.unlinkSync,
+            // Persist a bumped attempt count on failure so a later sweep retries
+            // (instead of dropping a session on a transient network blip).
+            writeFileSync: fs.writeFileSync,
+            // On a successful upload, drop the "last session captured" breadcrumb
+            // that `codiedev doctor` reads to confirm the session landed.
+            recordSuccess: (job) => (0, utils_1.writeLastCapture)((0, utils_1.buildLastCaptureRecord)(job, Date.now())),
+            // Write structured outcome lines (ok / ERROR / gave-up) to the
+            // rotating capture log so users and doctor can see why captures fail.
+            log: (e) => (0, captureLog_1.appendCaptureLog)(e),
+            // Write per-session upload state so the throttle can defer later
+            // non-final uploads within the same window.
+            writeSessionState: utils_1.writeSessionUploadState,
+        };
+    }
     // Detached uploader child (spawned by the capture path below). The job —
     // including transcript and token — is on disk; no stdin is needed, so handle
     // this before readStdin() to avoid blocking on the ignored stdin pipe.
     if (process.argv[2] === "upload") {
         const jobFile = process.argv[3];
         if (jobFile) {
-            await (0, utils_1.runCaptureUpload)(jobFile, {
-                post: postJson,
-                readFileSync: fs.readFileSync,
-                unlinkSync: fs.unlinkSync,
-                // Persist a bumped attempt count on failure so a later sweep retries
-                // (instead of dropping a session on a transient network blip).
-                writeFileSync: fs.writeFileSync,
-                // On a successful upload, drop the "last session captured" breadcrumb
-                // that `codiedev doctor` reads to confirm the session landed.
-                recordSuccess: (job) => (0, utils_1.writeLastCapture)((0, utils_1.buildLastCaptureRecord)(job, Date.now())),
+            await (0, utils_1.runCaptureUpload)(jobFile, makeUploadDeps());
+        }
+        process.exit(0);
+    }
+    // Deferred uploader child (spawned by runCaptureFinish when the per-turn
+    // Stop capture is inside the throttle window). Sleeps for the remaining
+    // delay, then claims the job file (if it hasn't been superseded by a newer
+    // turn) and uploads. No stdin needed — handle before readStdin().
+    if (process.argv[2] === "upload-deferred") {
+        const jobFile = process.argv[3];
+        const delayMs = Math.max(0, Number(process.argv[4]) || 0);
+        if (jobFile) {
+            await (0, utils_1.runDeferredUpload)(jobFile, delayMs, {
+                ...makeUploadDeps(),
+                renameSync: fs.renameSync,
             });
         }
         process.exit(0);
@@ -316,7 +344,40 @@ async function main() {
     // Stop/sessionEnd backup path — separate from session capture and needs no
     // transcript. Lists changed artifact files in the workspace and dispatches a
     // detached child that backs them up privately. Best-effort, never blocks.
+    //
+    // Per-turn capture: Stop fires reliably in editor-embedded clients (VS Code
+    // extension) where SessionEnd may never come — the silent zero-capture bug.
+    // Same detached capture-finish child as SessionEnd, marked non-final so the
+    // server renews the session lease instead of summarizing immediately.
     if (process.argv[2] === "backup") {
+        if (transcript_path) {
+            try {
+                (0, utils_1.dispatchCaptureFinish)({
+                    // "capture" = the claude-code entrypoint literal, same as the
+                    // SessionEnd path below (resolveMode maps it to claude-code).
+                    mode: "capture",
+                    session_id,
+                    transcript_path,
+                    cwd,
+                    workspace_roots,
+                    // non-final: server should renew the lease, not close it yet.
+                    final: false,
+                }, process.argv[1], {
+                    spawn: child_process_1.spawn,
+                    writeFileSync: fs.writeFileSync,
+                    openSync: fs.openSync,
+                    closeSync: fs.closeSync,
+                    // UNIQUE per dispatch (sid+pid+ts): Stop and SessionEnd children
+                    // each own their input file exclusively — a shared per-session
+                    // name let one child's `finally` unlink eat the other's input
+                    // (lost final:true) or double-dispatch. See finishInputTmpFile.
+                    tmpFile: (0, utils_1.finishInputTmpFile)(session_id),
+                });
+            }
+            catch {
+                // capture is best-effort; never break backup
+            }
+        }
         const { runBackup } = await Promise.resolve().then(() => __importStar(require("./backup/run")));
         runBackup(workspaceRoot, process.argv[1]);
         process.exit(0);
@@ -338,14 +399,23 @@ async function main() {
         process.exit(0);
     }
     try {
-        const jobFile = path.join(os.tmpdir(), `codiedev-capture-job-${session_id ?? process.pid}.json`);
+        // "codiedev-finish-" prefix (NOT "codiedev-capture-") so the sweep regex
+        // /^codiedev-capture-.*\.json$/ never mistakes a finish-input file for an
+        // upload job. UNIQUE per dispatch (sid+pid+ts) so a concurrent Stop-hook
+        // child's `finally` unlink can never eat this input (lost final:true).
+        const jobFile = (0, utils_1.finishInputTmpFile)(session_id);
         (0, utils_1.dispatchCaptureFinish)({
             mode: process.argv[2] ?? "capture",
             session_id,
             transcript_path,
             cwd,
             workspace_roots,
-        }, process.argv[1], { spawn: child_process_1.spawn, writeFileSync: fs.writeFileSync, tmpFile: jobFile });
+            // final:true ONLY for claude-code's SessionEnd. Codex routes its
+            // per-turn Stop hook through "capture-codex" — final:true there would
+            // close the server lease every turn. Codex/Cursor keep legacy
+            // behaviour (final omitted).
+            final: (0, utils_1.resolveCaptureFinal)(process.argv[2]),
+        }, process.argv[1], { spawn: child_process_1.spawn, writeFileSync: fs.writeFileSync, tmpFile: jobFile, openSync: fs.openSync, closeSync: fs.closeSync });
     }
     catch (err) {
         process.stderr.write(`[codiedev-hook] Warning: Failed to dispatch session capture — ${err.message}\n`);
@@ -366,6 +436,22 @@ async function runCaptureFinish(input) {
     const { session_id, transcript_path, cwd, workspace_roots } = input;
     if (!transcript_path)
         return;
+    // Log that this child has started processing — the first diagnostic proof
+    // that the detached capture-finish child actually ran (visible in doctor).
+    (0, captureLog_1.appendCaptureLog)({ stage: "capture-finish", sessionId: session_id, outcome: "start" });
+    try {
+        await runCaptureFinishInner(input, config, session_id, transcript_path, cwd, workspace_roots);
+    }
+    catch (err) {
+        (0, captureLog_1.appendCaptureLog)({
+            stage: "capture-finish",
+            sessionId: session_id,
+            outcome: "ERROR",
+            detail: (err instanceof Error ? err.message : String(err)).slice(0, 200),
+        });
+    }
+}
+async function runCaptureFinishInner(input, config, session_id, transcript_path, cwd, workspace_roots) {
     const mode = resolveMode(input.mode);
     const workspaceRoot = workspace_roots && workspace_roots.length > 0
         ? workspace_roots[0]
@@ -458,23 +544,59 @@ async function runCaptureFinish(input) {
         sessionStartedAt,
         interruptCount: steering.interrupts,
         rejectionCount: steering.rejections,
+        // Carry the final flag into the HTTP body — the server uses it to decide
+        // whether to close the session lease (true) or renew it (false/absent).
+        final: input.final,
+    });
+    // Throttle decision: final captures go immediately; non-final (per-turn Stop)
+    // are deferred if we uploaded this session recently, to avoid per-turn churn.
+    const uploadState = (0, utils_1.readSessionUploadState)(session_id ?? "");
+    const decision = (0, utils_1.decideDispatch)({
+        final: input.final === true,
+        lastUploadAt: uploadState?.lastUploadAt ?? null,
+        now: Date.now(),
+    });
+    // Log capture-finish outcome with dispatch context so doctor can see whether
+    // the upload went immediately or was deferred (and by how much).
+    (0, captureLog_1.appendCaptureLog)({
+        stage: "capture-finish",
+        sessionId: session_id,
+        outcome: decision.mode === "deferred" ? "deferred" : "ok",
+        detail: decision.mode === "deferred"
+            ? `dispatch=deferred delayMs=${decision.delayMs} final=${input.final === true} repo=${remoteUrl ?? "-"} branch=${branch ?? "-"} msgs=${stats.messageCount}`
+            : `dispatch=immediate final=${input.final === true} repo=${remoteUrl ?? "-"} branch=${branch ?? "-"} msgs=${stats.messageCount}`,
     });
     // Fire the upload from a further-detached child. We're already off the
     // shutdown clock here, but reusing dispatchCaptureDetached keeps the upload
     // retry + last-capture breadcrumb logic (runCaptureUpload) intact verbatim.
+    // Per-session job file: one file per session; newer turns overwrite it,
+    // which is the "supersede" mechanism for the deferred path.
     try {
         const hookScriptPath = process.argv[1];
         const tmpFile = path.join(os.tmpdir(), `codiedev-capture-${session_id ?? process.pid}.json`);
-        (0, utils_1.dispatchCaptureDetached)({ url: `${config.backendUrl}/api/captureSession`, token: config.token, body: payload }, hookScriptPath, { spawn: child_process_1.spawn, writeFileSync: fs.writeFileSync, tmpFile });
-        // Retry any earlier capture jobs that failed to upload (transient network
-        // blips), excluding the one we just dispatched. Best-effort, detached.
-        (0, utils_1.sweepPendingCaptures)({
-            dir: os.tmpdir(),
-            readdirSync: fs.readdirSync,
-            spawn: child_process_1.spawn,
-            hookScriptPath,
-            exclude: tmpFile,
-        });
+        if (decision.mode === "immediate") {
+            (0, utils_1.dispatchCaptureDetached)({ url: `${config.backendUrl}/api/captureSession`, token: config.token, body: payload }, hookScriptPath, { spawn: child_process_1.spawn, writeFileSync: fs.writeFileSync, tmpFile, openSync: fs.openSync, closeSync: fs.closeSync });
+            // Retry any earlier capture jobs that failed to upload (transient network
+            // blips), excluding the one we just dispatched. Best-effort, detached.
+            // Skip the sweep on deferred path — the deferred child will handle uploading.
+            (0, utils_1.sweepPendingCaptures)({
+                dir: os.tmpdir(),
+                readdirSync: fs.readdirSync,
+                renameSync: fs.renameSync,
+                statSync: fs.statSync,
+                spawn: child_process_1.spawn,
+                hookScriptPath,
+                exclude: tmpFile,
+                openSync: fs.openSync,
+                closeSync: fs.closeSync,
+            });
+        }
+        else {
+            // Deferred: write the job file (newer turns overwrite = supersede), then
+            // spawn the deferred-upload child which will sleep, claim, and upload.
+            // Same stdio/fd-hygiene contract as dispatchCaptureDetached.
+            (0, utils_1.dispatchDeferredUpload)({ url: `${config.backendUrl}/api/captureSession`, token: config.token, body: payload }, hookScriptPath, { spawn: child_process_1.spawn, writeFileSync: fs.writeFileSync, tmpFile, openSync: fs.openSync, closeSync: fs.closeSync }, decision.delayMs);
+        }
     }
     catch (err) {
         process.stderr.write(`[codiedev-hook] Warning: Failed to dispatch session capture — ${err.message}\n`);

package/dist/utils.d.ts

@@ -1,5 +1,6 @@
 import * as fs from "fs";
 import { spawn as nodeSpawn } from "child_process";
+import type { CaptureLogEntry } from "./captureLog";
 export interface CodiedevConfig {
     token: string;
     companyId: string;
@@ -62,6 +63,7 @@ export interface CapturePayloadInput {
     sessionStartedAt?: number | null;
     interruptCount?: number;
     rejectionCount?: number;
+    final?: boolean;
 }
 export declare function buildCapturePayload(input: CapturePayloadInput): Record<string, unknown>;
 export declare function hashToken(token: string): string;
@@ -174,6 +176,8 @@ interface DispatchDeps {
     writeFileSync: typeof fs.writeFileSync;
     tmpFile: string;
     nodePath?: string;
+    openSync?: typeof fs.openSync;
+    closeSync?: typeof fs.closeSync;
 }
 export interface CaptureFinishInput {
     mode: string;
@@ -181,19 +185,65 @@ export interface CaptureFinishInput {
     transcript_path?: string;
     cwd?: string;
     workspace_roots?: string[];
+    final?: boolean;
 }
 export declare function dispatchCaptureFinish(input: CaptureFinishInput, hookScriptPath: string, deps: DispatchDeps): void;
 export declare function dispatchCaptureDetached(job: CaptureUploadJob, hookScriptPath: string, deps: DispatchDeps): void;
+export declare function dispatchDeferredUpload(job: CaptureUploadJob, hookScriptPath: string, deps: DispatchDeps, delayMs: number): void;
 interface SweepDeps {
     dir: string;
     readdirSync: (dir: string) => string[];
+    renameSync: (from: string, to: string) => void;
+    statSync: (p: string) => {
+        mtimeMs: number;
+    };
     spawn: typeof nodeSpawn;
     hookScriptPath: string;
     nodePath?: string;
     exclude?: string;
     max?: number;
+    now?: () => number;
+    openSync?: typeof fs.openSync;
+    closeSync?: typeof fs.closeSync;
+    pruneState?: () => void;
 }
+export declare const CLAIM_STALE_MS: number;
 export declare function sweepPendingCaptures(deps: SweepDeps): void;
+export declare const CAPTURE_THROTTLE_MS: number;
+export declare const SWEEP_MIN_AGE_MS: number;
+export declare function resolveCaptureFinal(argv2: string | undefined): boolean | undefined;
+export declare function finishInputTmpFile(sessionId: string | undefined): string;
+export declare function decideDispatch(args: {
+    final: boolean;
+    lastUploadAt: number | null;
+    now: number;
+}): {
+    mode: "immediate";
+} | {
+    mode: "deferred";
+    delayMs: number;
+};
+export interface SessionUploadState {
+    lastUploadAt: number;
+}
+interface SessionStateDeps {
+    readFileSync: typeof fs.readFileSync;
+    existsSync: typeof fs.existsSync;
+}
+interface SessionStateWriteDeps {
+    writeFileSync: typeof fs.writeFileSync;
+    existsSync: typeof fs.existsSync;
+    mkdirSync: typeof fs.mkdirSync;
+}
+export declare function readSessionUploadState(sessionId: string, deps?: SessionStateDeps): SessionUploadState | null;
+export declare function writeSessionUploadState(sessionId: string, state: SessionUploadState, deps?: SessionStateWriteDeps): void;
+export declare function pruneCaptureStateDir(deps?: {
+    readdirSync: (d: string) => string[];
+    statSync: (p: string) => {
+        mtimeMs: number;
+    };
+    unlinkSync: (p: string) => void;
+}, dir?: string, now?: number): void;
 interface UploadDeps {
     post: (url: string, body: Record<string, unknown>, token: string) => Promise<void>;
     readFileSync: typeof fs.readFileSync;
@@ -201,6 +251,8 @@ interface UploadDeps {
     writeFileSync?: typeof fs.writeFileSync;
     now?: () => number;
     recordSuccess?: (job: CaptureUploadJob) => void;
+    log?: (entry: CaptureLogEntry) => void;
+    writeSessionState?: (sessionId: string, state: SessionUploadState) => void;
 }
 export interface LastCaptureRecord {
     sessionId: string | undefined;
@@ -225,4 +277,9 @@ interface LastCaptureReadDeps {
 }
 export declare function readLastCapture(deps?: LastCaptureReadDeps, filePath?: string): LastCaptureRecord | null;
 export declare function runCaptureUpload(jobFile: string, deps: UploadDeps): Promise<void>;
+interface DeferredUploadDeps extends UploadDeps {
+    renameSync: typeof fs.renameSync;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function runDeferredUpload(jobFile: string, delayMs: number, deps: DeferredUploadDeps): Promise<void>;
 export {};

package/dist/utils.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UPLOAD_TTL_MS = exports.MAX_UPLOAD_ATTEMPTS = void 0;
+exports.SWEEP_MIN_AGE_MS = exports.CAPTURE_THROTTLE_MS = exports.CLAIM_STALE_MS = exports.UPLOAD_TTL_MS = exports.MAX_UPLOAD_ATTEMPTS = void 0;
 exports.readConfig = readConfig;
 exports.writeConfig = writeConfig;
 exports.parseGitRemoteFromConfig = parseGitRemoteFromConfig;
@@ -85,16 +85,25 @@ exports.parseCodexStats = parseCodexStats;
 exports.extractCodexRepoUrl = extractCodexRepoUrl;
 exports.dispatchCaptureFinish = dispatchCaptureFinish;
 exports.dispatchCaptureDetached = dispatchCaptureDetached;
+exports.dispatchDeferredUpload = dispatchDeferredUpload;
 exports.sweepPendingCaptures = sweepPendingCaptures;
+exports.resolveCaptureFinal = resolveCaptureFinal;
+exports.finishInputTmpFile = finishInputTmpFile;
+exports.decideDispatch = decideDispatch;
+exports.readSessionUploadState = readSessionUploadState;
+exports.writeSessionUploadState = writeSessionUploadState;
+exports.pruneCaptureStateDir = pruneCaptureStateDir;
 exports.buildLastCaptureRecord = buildLastCaptureRecord;
 exports.writeLastCapture = writeLastCapture;
 exports.readLastCapture = readLastCapture;
 exports.runCaptureUpload = runCaptureUpload;
+exports.runDeferredUpload = runDeferredUpload;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const detection_1 = require("./detection");
+const captureLog_1 = require("./captureLog");
 const CONFIG_DIR = path.join(os.homedir(), ".codiedev");
 const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
 function readConfig() {
@@ -676,6 +685,8 @@ function buildCapturePayload(input) {
         sessionStartedAt: input.sessionStartedAt ?? undefined,
         interruptCount: input.interruptCount,
         rejectionCount: input.rejectionCount,
+        // final is only emitted when explicitly set (not for Codex/Cursor).
+        final: input.final,
     };
 }
 function hashToken(token) {
@@ -1626,6 +1637,32 @@ function extractCodexRepoUrl(content) {
 // failing job never litters /tmp forever. Paired with UPLOAD_TTL_MS.
 exports.MAX_UPLOAD_ATTEMPTS = 5;
 exports.UPLOAD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// Open the capture log for appending so a detached child's stderr lands there
+// instead of vanishing into stdio:"ignore". Returns the stdio value to spawn
+// with plus the parent's fd (to close after spawn — the child gets its own
+// duplicate). Falls back to plain "ignore" when openSync is absent or throws,
+// so a missing/unwritable log dir never breaks a dispatch.
+function openCaptureLogStdio(openSync) {
+    if (!openSync)
+        return { stdio: "ignore" };
+    try {
+        const fd = openSync(captureLog_1.CAPTURE_LOG_PATH, "a");
+        return { stdio: ["ignore", "ignore", fd], fd };
+    }
+    catch {
+        return { stdio: "ignore" };
+    }
+}
+// Best-effort close of the parent's log-fd copy. No-op when there's no fd or
+// no closeSync dep — never throws into the capture path.
+function closeCaptureLogFd(fd, closeSync) {
+    if (fd === undefined || !closeSync)
+        return;
+    try {
+        closeSync(fd);
+    }
+    catch { /* best-effort */ }
+}
 // Hand the SessionEnd capture off to a detached child so the inline hook can
 // exit 0 immediately. Detaching only the network upload (dispatchCaptureDetached)
 // wasn't enough: the synchronous transcript read + parse and — the killer on
@@ -1637,8 +1674,21 @@ exports.UPLOAD_TTL_MS = 7 * 24 * 60 * 60 * 1000;
 // small file write plus a spawn.
 function dispatchCaptureFinish(input, hookScriptPath, deps) {
     deps.writeFileSync(deps.tmpFile, JSON.stringify(input), { mode: 0o600 });
-    const child = deps.spawn(deps.nodePath ?? process.execPath, [hookScriptPath, "capture-finish", deps.tmpFile], { detached: true, stdio: "ignore" });
-    child.unref();
+    // Route the child's stderr to the capture log so any crash output is
+    // visible to `codiedev doctor`. The caller must explicitly pass openSync
+    // (e.g. fs.openSync in hook.ts) to enable this; when omitted (tests,
+    // older call-sites) we fall back to "ignore" so existing behaviour is
+    // unchanged and no real fd is opened.
+    const { stdio, fd } = openCaptureLogStdio(deps.openSync);
+    try {
+        const child = deps.spawn(deps.nodePath ?? process.execPath, [hookScriptPath, "capture-finish", deps.tmpFile], { detached: true, stdio });
+        child.unref();
+    }
+    finally {
+        // Close the PARENT's fd copy even when spawn throws — the child (if
+        // spawned) holds its own duplicate, so this never cuts off its stderr.
+        closeCaptureLogFd(fd, deps.closeSync);
+    }
 }
 // Fire-and-forget the session-capture upload from a fully detached child so the
 // SessionEnd hook can exit 0 immediately. Awaiting the upload inline let Claude
@@ -1647,12 +1697,52 @@ function dispatchCaptureFinish(input, hookScriptPath, deps) {
 // passed via argv so it never shows up in the process list.
 function dispatchCaptureDetached(job, hookScriptPath, deps) {
     deps.writeFileSync(deps.tmpFile, JSON.stringify(job), { mode: 0o600 });
-    const child = deps.spawn(deps.nodePath ?? process.execPath, [hookScriptPath, "upload", deps.tmpFile], { detached: true, stdio: "ignore" });
-    child.unref();
+    // Route the child's stderr to the capture log (same pattern as
+    // dispatchCaptureFinish). The caller must explicitly pass openSync to
+    // enable this; when omitted we fall back to "ignore" so existing callers
+    // keep working unchanged.
+    const { stdio, fd } = openCaptureLogStdio(deps.openSync);
+    try {
+        const child = deps.spawn(deps.nodePath ?? process.execPath, [hookScriptPath, "upload", deps.tmpFile], { detached: true, stdio });
+        child.unref();
+    }
+    finally {
+        // Close the PARENT's fd copy even when spawn throws — the child (if
+        // spawned) holds its own duplicate, so this never cuts off its stderr.
+        closeCaptureLogFd(fd, deps.closeSync);
+    }
 }
+// Deferred twin of dispatchCaptureDetached: persist the job, then spawn the
+// `upload-deferred` child which sleeps for delayMs before claiming + uploading
+// (or finding itself superseded by a newer turn). Used when decideDispatch
+// says a non-final per-turn capture is inside the throttle window. Identical
+// stdio/fd-hygiene contract to the other dispatch fns.
+function dispatchDeferredUpload(job, hookScriptPath, deps, delayMs) {
+    deps.writeFileSync(deps.tmpFile, JSON.stringify(job), { mode: 0o600 });
+    const { stdio, fd } = openCaptureLogStdio(deps.openSync);
+    try {
+        const child = deps.spawn(deps.nodePath ?? process.execPath, [hookScriptPath, "upload-deferred", deps.tmpFile, String(delayMs)], { detached: true, stdio });
+        child.unref();
+    }
+    finally {
+        // Close the PARENT's fd copy even when spawn throws — the child (if
+        // spawned) holds its own duplicate, so this never cuts off its stderr.
+        closeCaptureLogFd(fd, deps.closeSync);
+    }
+}
+// A claimed job whose uploader hasn't finished after this long is presumed
+// crashed and gets renamed back to its canonical name for a later retry.
+exports.CLAIM_STALE_MS = 15 * 60 * 1000;
 // Retry kept-on-failure capture jobs: re-dispatch each pending
 // `codiedev-capture-*.json` to the detached uploader (which bumps attempts /
 // gives up at the cap). Best-effort — never throws into the hook.
+//
+// Each job is CLAIMED with an atomic rename before dispatch. Several
+// session-end hooks can run this sweep over the same tmpdir at once, and
+// without the claim each of them dispatched an uploader for the same job —
+// every duplicate upload triggered a full server-side re-summarize of the
+// session (real LLM spend per duplicate). Rename is atomic, so exactly one
+// sweeper wins each file; the losers' renames throw and they skip it.
 function sweepPendingCaptures(deps) {
     let files;
     try {
@@ -1661,20 +1751,190 @@ function sweepPendingCaptures(deps) {
     catch {
         return;
     }
+    const now = deps.now?.() ?? Date.now();
+    // Recover claims orphaned by a crashed/killed uploader: a stale claim is
+    // renamed back to its canonical name so a LATER sweep retries it. (Not this
+    // one — the uploader may legitimately still be running near the threshold,
+    // and dispatching reclaimed work immediately would race it.)
+    for (const f of files) {
+        const m = /^(codiedev-capture-.*\.json)\.claim-\d+$/.exec(f);
+        if (!m)
+            continue;
+        const claimedPath = path.join(deps.dir, f);
+        try {
+            if (now - deps.statSync(claimedPath).mtimeMs > exports.CLAIM_STALE_MS) {
+                deps.renameSync(claimedPath, path.join(deps.dir, m[1]));
+            }
+        }
+        catch {
+            // raced another sweeper or the uploader just finished — fine
+        }
+    }
     const jobs = files
         .filter((f) => /^codiedev-capture-.*\.json$/.test(f))
         .map((f) => path.join(deps.dir, f))
         .filter((p) => p !== deps.exclude)
+        // Min-age guard: a YOUNG job file may be a sleeping deferred upload whose
+        // own upload-deferred child will consume it within CAPTURE_THROTTLE_MS of
+        // its mtime. The sweep must not steal it — that would upload per-turn and
+        // defeat the throttle with 2+ concurrent sessions. Only genuinely stuck
+        // jobs (older than SWEEP_MIN_AGE_MS) are retried. A stat failure means the
+        // job was claimed/consumed mid-sweep — skip it.
+        .filter((p) => {
+        try {
+            return now - deps.statSync(p).mtimeMs >= exports.SWEEP_MIN_AGE_MS;
+        }
+        catch {
+            return false;
+        }
+    })
         .slice(0, deps.max ?? 10);
+    // One log fd shared by every re-dispatched uploader in this batch (each
+    // spawn duplicates it); the parent's copy is closed after the loop.
+    const { stdio, fd } = openCaptureLogStdio(deps.openSync);
     for (const jobFile of jobs) {
+        const claimed = `${jobFile}.claim-${process.pid}`;
         try {
-            const child = deps.spawn(deps.nodePath ?? process.execPath, [deps.hookScriptPath, "upload", jobFile], { detached: true, stdio: "ignore" });
+            deps.renameSync(jobFile, claimed);
+        }
+        catch {
+            continue; // another sweeper claimed it first
+        }
+        try {
+            const child = deps.spawn(deps.nodePath ?? process.execPath, [deps.hookScriptPath, "upload", claimed], { detached: true, stdio });
             child.unref();
         }
         catch {
-            // ignore — best-effort retry
+            // Couldn't fork the uploader — release the claim so a later sweep
+            // retries instead of the job dying invisible under the claimed name.
+            try {
+                deps.renameSync(claimed, jobFile);
+            }
+            catch {
+                // best-effort
+            }
         }
     }
+    closeCaptureLogFd(fd, deps.closeSync);
+    // Housekeeping: prune per-session upload-state files older than the upload
+    // TTL so capture-state doesn't grow forever. Best-effort, never throws.
+    try {
+        (deps.pruneState ?? pruneCaptureStateDir)();
+    }
+    catch {
+        // best-effort
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-session upload throttle — defers mid-session Stop-hook uploads so we
+// don't hammer the server (and re-summarize) after every single turn.
+// ─────────────────────────────────────────────────────────────────────────────
+// Minimum interval between non-final uploads for the same session. 10 minutes:
+// fine-grained enough to capture recent work while avoiding per-turn churn.
+exports.CAPTURE_THROTTLE_MS = 10 * 60 * 1000;
+// Minimum AGE of a job file before the retry sweep may claim it. An actively
+// deferred job is consumed by its own upload-deferred child within
+// CAPTURE_THROTTLE_MS of its mtime — a sweep stealing it early would upload
+// per-turn and defeat the throttle whenever 2+ sessions run concurrently.
+// The 2-min slack covers the child's wake-up + claim. Side effect: failed
+// uploads (whose retry bump refreshes mtime) now wait ~12 min between retry
+// attempts — fine for a 7-day-TTL retry queue, and a free rate-limit on
+// retry storms.
+exports.SWEEP_MIN_AGE_MS = exports.CAPTURE_THROTTLE_MS + 2 * 60 * 1000;
+// Map the hook's capture argv to the payload's `final` flag. EXPLICIT
+// ALLOWLIST: only claude-code's SessionEnd entrypoints ("capture", or the bare
+// hook with no subcommand) are a true final signal. Everything else —
+// capture-codex (Codex's Stop fires per-turn; final:true would close the
+// server-side session lease every turn), capture-cursor, and any FUTURE mode
+// (e.g. a capture-windsurf added to resolveMode but not audited here) — gets
+// undefined, i.e. legacy server behaviour. Defaulting unknowns to true would
+// silently re-introduce the per-turn lease-close bug for every new agent.
+function resolveCaptureFinal(argv2) {
+    return argv2 === "capture" || argv2 === undefined ? true : undefined;
+}
+// Build a UNIQUE finish-input tmpFile name per dispatch. Both the Stop hook and
+// SessionEnd dispatch capture-finish children, and the child unlinks its input
+// in `finally` — a SHARED per-session name let interleavings drop the final
+// dispatch (Stop's child unlinks the file SessionEnd just wrote) or
+// double-dispatch. Unique names mean each child owns its file exclusively; at
+// worst concurrent Stop+SessionEnd children both upload, which is harmless
+// (the server upserts by sessionId). Orphans (child dies before unlink) sit in
+// tmpdir OUTSIDE the sweep regex (codiedev-finish- ≠ codiedev-capture-);
+// negligible volume (one tiny JSON per crashed child), though note Windows
+// %TEMP% is not auto-cleaned — acceptable.
+function finishInputTmpFile(sessionId) {
+    return path.join(os.tmpdir(), `codiedev-finish-${sessionId ?? process.pid}-${process.pid}-${Date.now()}.json`);
+}
+// Decide whether to upload immediately or defer until the throttle window expires.
+//   final=true  → always immediate (SessionEnd: close the session now)
+//   null        → immediate (first upload for this session)
+//   outside window → immediate
+//   inside window  → deferred with exact remaining delay
+//   future clock skew → deferred clamped to CAPTURE_THROTTLE_MS
+function decideDispatch(args) {
+    if (args.final || args.lastUploadAt === null)
+        return { mode: "immediate" };
+    const elapsed = args.now - args.lastUploadAt;
+    // Clock-skew guard: elapsed < 0 means lastUploadAt is in the future. Clamping
+    // to 0 also bounds delayMs to at most CAPTURE_THROTTLE_MS (safeElapsed >= 0).
+    const safeElapsed = Math.max(0, elapsed);
+    if (safeElapsed >= exports.CAPTURE_THROTTLE_MS)
+        return { mode: "immediate" };
+    return { mode: "deferred", delayMs: exports.CAPTURE_THROTTLE_MS - safeElapsed };
+}
+// Per-session state dir: ~/.codiedev/capture-state/<sanitized-session-id>.json
+const CAPTURE_STATE_DIR = path.join(CONFIG_DIR, "capture-state");
+function captureStatePath(sessionId) {
+    const safe = sessionId.replace(/[^A-Za-z0-9_-]/g, "_");
+    return path.join(CAPTURE_STATE_DIR, `${safe}.json`);
+}
+// Read the per-session upload state from ~/.codiedev/capture-state/<id>.json.
+// Returns null when missing or unreadable. Never throws.
+function readSessionUploadState(sessionId, deps = fs) {
+    try {
+        const p = captureStatePath(sessionId);
+        if (!deps.existsSync(p))
+            return null;
+        return JSON.parse(deps.readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// Write the per-session upload state to ~/.codiedev/capture-state/<id>.json.
+// Best-effort: never throws into the capture path.
+function writeSessionUploadState(sessionId, state, deps = fs) {
+    try {
+        if (!deps.existsSync(CAPTURE_STATE_DIR)) {
+            deps.mkdirSync(CAPTURE_STATE_DIR, { recursive: true });
+        }
+        const p = captureStatePath(sessionId);
+        deps.writeFileSync(p, JSON.stringify(state), { mode: 0o600 });
+    }
+    catch {
+        // best-effort — never break the capture path
+    }
+}
+// Prune per-session upload-state files older than UPLOAD_TTL_MS (7 days — same
+// TTL as the upload retry queue) so ~/.codiedev/capture-state (one tiny file
+// per session) doesn't grow forever. Called from sweepPendingCaptures, i.e. on
+// the cadence captures already run housekeeping. Best-effort: never throws.
+function pruneCaptureStateDir(deps = fs, dir = CAPTURE_STATE_DIR, now = Date.now()) {
+    try {
+        for (const f of deps.readdirSync(dir)) {
+            const p = path.join(dir, f);
+            try {
+                if (now - deps.statSync(p).mtimeMs > exports.UPLOAD_TTL_MS)
+                    deps.unlinkSync(p);
+            }
+            catch {
+                // raced another pruner or unreadable — skip
+            }
+        }
+    }
+    catch {
+        // dir missing/unreadable — nothing to prune
+    }
 }
 // "Last session captured" breadcrumb. Written next to config.json on a
 // successful capture upload; read by `codiedev doctor` so a user can confirm
@@ -1732,6 +1992,7 @@ async function runCaptureUpload(jobFile, deps) {
         catch { /* gone */ }
         return;
     }
+    const sessionId = job.body?.sessionId;
     try {
         await deps.post(job.url, job.body, job.token);
         // success — drop a "last session captured" breadcrumb (before removing the
@@ -1742,28 +2003,82 @@ async function runCaptureUpload(jobFile, deps) {
             }
             catch { /* breadcrumb is best-effort */ }
         }
+        // Write the per-session upload state so the throttle can defer the next
+        // non-final (per-turn) upload until the window expires.
+        const uploadedSessionId = job.body?.sessionId;
+        if (uploadedSessionId && deps.writeSessionState) {
+            try {
+                deps.writeSessionState(uploadedSessionId, { lastUploadAt: deps.now ? deps.now() : Date.now() });
+            }
+            catch { /* best-effort */ }
+        }
+        const attempt = (job.attempts ?? 0) + 1;
+        if (deps.log) {
+            try {
+                deps.log({ stage: "upload", sessionId, outcome: "ok", detail: `attempt=${attempt}` });
+            }
+            catch { /* log is best-effort */ }
+        }
         try {
             deps.unlinkSync(jobFile);
         }
         catch { /* gone */ }
         return;
     }
-    catch {
+    catch (err) {
         // Failure: keep the job for a later sweep to retry, UNLESS we've hit the
         // attempt cap or TTL — then give up so /tmp doesn't accumulate forever.
         const now = deps.now ? deps.now() : Date.now();
         const attempts = (job.attempts ?? 0) + 1;
         const queuedAt = job.queuedAt ?? now;
         const expired = now - queuedAt > exports.UPLOAD_TTL_MS;
-        if (attempts >= exports.MAX_UPLOAD_ATTEMPTS || expired || !deps.writeFileSync) {
+        const giveUp = attempts >= exports.MAX_UPLOAD_ATTEMPTS || expired || !deps.writeFileSync;
+        if (giveUp) {
+            if (deps.log) {
+                try {
+                    const ageMs = now - queuedAt;
+                    deps.log({
+                        stage: "upload",
+                        sessionId,
+                        outcome: "gave-up",
+                        detail: `attempt=${attempts} age=${ageMs}ms`,
+                    });
+                }
+                catch { /* log is best-effort */ }
+            }
             try {
                 deps.unlinkSync(jobFile);
             }
             catch { /* gone */ }
             return;
         }
+        // Log the error before persisting the retry bump.
+        if (deps.log) {
+            try {
+                const msg = err.message ?? String(err);
+                // Extract http=<status> when the error message carries one (format used
+                // by postJson: "HTTP <status>: <body>"). Truncate to 200 chars.
+                const httpMatch = msg.match(/\bhttp[= ](\d{3})\b/i);
+                const httpPart = httpMatch ? `http=${httpMatch[1]} ` : "";
+                const detail = `${httpPart}${msg.slice(0, 200)} attempt=${attempts}`;
+                deps.log({ stage: "upload", sessionId, outcome: "ERROR", detail });
+            }
+            catch { /* log is best-effort */ }
+        }
+        // The sweep hands us a CLAIMED path (`<job>.claim-<pid>`). Persist the
+        // retry bump under the canonical name — the sweep only matches
+        // `codiedev-capture-*.json`, so a bump left on the claimed path would
+        // never be retried (a silently dropped capture).
+        const canonical = jobFile.replace(/\.claim-\d+$/, "");
+        const writeFn = deps.writeFileSync; // always set here: giveUp branch checked !deps.writeFileSync
         try {
-            deps.writeFileSync(jobFile, JSON.stringify({ ...job, attempts, queuedAt }), { mode: 0o600 });
+            writeFn(canonical, JSON.stringify({ ...job, attempts, queuedAt }), { mode: 0o600 });
+            if (canonical !== jobFile) {
+                try {
+                    deps.unlinkSync(jobFile);
+                }
+                catch { /* gone */ }
+            }
         }
         catch {
             // couldn't persist the bump — drop it rather than risk a stuck file.
@@ -1774,3 +2089,27 @@ async function runCaptureUpload(jobFile, deps) {
         }
     }
 }
+async function runDeferredUpload(jobFile, delayMs, deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    await sleep(delayMs);
+    // Claim via rename. If the file is gone or already claimed, a newer turn's
+    // upload superseded this one: log and exit silently.
+    const claimed = `${jobFile}.claim-${process.pid}`;
+    try {
+        deps.renameSync(jobFile, claimed);
+    }
+    catch {
+        if (deps.log) {
+            try {
+                // The job file is gone, so its body (and sessionId) is unreadable —
+                // recover the session id from the per-session filename so doctor can
+                // still tie this line to a session.
+                const sid = /^codiedev-capture-(.+)\.json/.exec(path.basename(jobFile))?.[1];
+                deps.log({ stage: "upload-deferred", sessionId: sid, outcome: "superseded" });
+            }
+            catch { /* log is best-effort */ }
+        }
+        return;
+    }
+    await runCaptureUpload(claimed, deps);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codiedev",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "description": "Connect Claude Code, Codex, Cursor, or VS Code Copilot to Codiedev for org-wide session capture and artifact collaboration",
   "bin": {
     "codiedev": "dist/cli.js",