skalpel 3.4.17 → 3.4.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skalpel",
-  "version": "3.4.17",
+  "version": "3.4.18",
   "description": "Skalpel — local proxy and TUI for coding agents (skalpel + skalpeld bundle).",
   "license": "Apache-2.0",
   "homepage": "https://skalpel.ai",
@@ -59,10 +59,10 @@
     "x64"
   ],
   "optionalDependencies": {
-    "@skalpelai/skalpel-darwin-arm64": "3.4.17",
-    "@skalpelai/skalpel-darwin-x64": "3.4.17",
-    "@skalpelai/skalpel-linux-arm64": "3.4.17",
-    "@skalpelai/skalpel-linux-x64": "3.4.17",
-    "@skalpelai/skalpel-win32-x64": "3.4.17"
+    "@skalpelai/skalpel-darwin-arm64": "3.4.18",
+    "@skalpelai/skalpel-darwin-x64": "3.4.18",
+    "@skalpelai/skalpel-linux-arm64": "3.4.18",
+    "@skalpelai/skalpel-linux-x64": "3.4.18",
+    "@skalpelai/skalpel-win32-x64": "3.4.18"
   }
 }

package/postinstall/lib/prosumer-hooks.js

@@ -8,11 +8,13 @@ const { spawnSync } = require('child_process');
 const RUNTIME_FILES = [
   'auth.mjs',
   'bootstrap.mjs',
+  'incremental-ingest.mjs',
   'insights.mjs',
   'metrics.mjs',
   'stats.mjs',
   'skalpel-hook.mjs',
   'skalpel-hook-session.mjs',
+  'skalpel-hook-session-end.mjs',
   'skalpel-statusline.mjs',
   'install.mjs',
 ];

package/postinstall/lib/prosumer-hooks.test.js

@@ -13,6 +13,13 @@ const { spawnSync } = require('child_process');
 const hooksLib = path.join(__dirname, 'prosumer-hooks.js');
 const statusline = path.resolve(__dirname, '..', '..', 'prosumer-hooks', 'skalpel-statusline.mjs');
 const bootstrap = path.resolve(__dirname, '..', '..', 'prosumer-hooks', 'bootstrap.mjs');
+const sessionEnd = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  'prosumer-hooks',
+  'skalpel-hook-session-end.mjs'
+);
 const packageJson = path.resolve(__dirname, '..', '..', 'package.json');
 
 let pass = 0;
@@ -104,6 +111,7 @@ function run() {
       'npm package files must include the CLI-owned hook/status-line runtime',
     );
     assert.ok(fs.existsSync(statusline), 'status-line source is missing from the packaged directory');
+    assert.ok(fs.existsSync(sessionEnd), 'SessionEnd ingest hook is missing from the package');
   });
 
   test('graph bootstrap never owns or mutates behavior hooks', () => {
@@ -206,8 +214,42 @@ function run() {
       const cfg = settings(home);
       assert.ok(cfg.hooks.UserPromptSubmit.length > 0);
       assert.ok(cfg.hooks.SessionStart.length > 0);
+      assert.strictEqual(cfg.hooks.SessionEnd.length, 1);
+      const endHandler = cfg.hooks.SessionEnd[0].hooks[0];
+      assert.match(endHandler.command, /skalpel-hook-session-end\.mjs$/);
+      assert.strictEqual(endHandler.async, true, 'SessionEnd ingest must not block session exit');
+      assert.strictEqual(endHandler.timeout, 55);
       assert.match(cfg.statusLine.command, /skalpel-statusline\.mjs$/);
       assert.strictEqual(fs.existsSync(path.join(home, '.claude', 'CLAUDE.md')), true);
+      assert.strictEqual(
+        fs.existsSync(path.join(home, '.skalpel', 'hooks', 'incremental-ingest.mjs')),
+        true,
+        'durable outbox module must be staged with the entrypoint',
+      );
+    } finally {
+      fs.rmSync(home, { recursive: true, force: true });
+    }
+  });
+
+  test('Codex keeps next-launch fallback instead of installing unsupported SessionEnd', () => {
+    const home = tempHome({ claude: true });
+    try {
+      fs.mkdirSync(path.join(home, '.codex'), { recursive: true });
+      fs.writeFileSync(
+        path.join(home, '.claude', 'settings.json'),
+        JSON.stringify({
+          hooks: {
+            UserPromptSubmit: [
+              { hooks: [{ type: 'command', command: 'node /old/skalpel-hook.mjs' }] },
+            ],
+          },
+        }),
+      );
+      const result = stage(home);
+      assert.strictEqual(result.status, 0, result.stderr);
+      const codex = fs.readFileSync(path.join(home, '.codex', 'config.toml'), 'utf8');
+      assert.doesNotMatch(codex, /SessionEnd/);
+      assert.ok(settings(home).hooks.SessionEnd.length > 0, 'Claude should still receive SessionEnd');
     } finally {
       fs.rmSync(home, { recursive: true, force: true });
     }

package/prosumer-hooks/bootstrap.mjs

@@ -19,6 +19,7 @@ import {
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
 import { gzipSync } from "node:zlib";
 import { identity } from "./auth.mjs";
 import { recordInsight } from "./insights.mjs";
@@ -222,6 +223,75 @@ async function postIngest(payload, token, compressed) {
   });
 }
 
+function count(value) {
+  return Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0;
+}
+
+function serverHeartbeat(status) {
+  for (const key of ["heartbeat_at", "updated_at", "last_heartbeat_at"]) {
+    if (typeof status?.[key] === "string" && status[key]) return status[key];
+  }
+  return null;
+}
+
+function activeMessage(state, errors, heartbeat) {
+  let message;
+  switch (state) {
+    case "queued":
+      message = "Graph build queued";
+      break;
+    case "waiting_quota":
+      message = "Waiting for graph capacity";
+      break;
+    case "running":
+    case "judging":
+      message = "Learning from your sessions";
+      break;
+    default:
+      message = "Building your intent graph";
+      break;
+  }
+  if (errors > 0) message += ` · ${errors} session${errors === 1 ? "" : "s"} failed`;
+  if (heartbeat) message += " · server active";
+  return message;
+}
+
+// Normalize the server's evolving job-status contract into the stable NDJSON row consumed by
+// the Go TUI. Production historically returned `running`; the hook used to recognize only
+// `judging`, leaving a real 2/16 build painted forever as 0/16. Unknown nonterminal states remain
+// visible instead of being silently discarded, so adding a server phase is backward-compatible.
+export function normalizeJobStatus(status = {}) {
+  const state = typeof status.state === "string" && status.state ? status.state : "running";
+  const done = count(status.done);
+  const total = count(status.total);
+  const errors = count(status.errors);
+  const heartbeat = serverHeartbeat(status);
+  const terminal = status.terminal === true;
+  const requiresReplay = status.requires_replay === true;
+  const failed = state === "error" || state === "failed" || (terminal && requiresReplay);
+  const complete = state === "done";
+  return {
+    state,
+    done,
+    total,
+    errors,
+    heartbeat,
+    terminal,
+    requiresReplay,
+    complete,
+    failed,
+    sessions: count(status.n_sessions ?? done),
+    message: failed
+      ? String(
+          status.error ||
+            (requiresReplay
+              ? "graph capacity was exhausted; retry the build"
+              : "server graph build failed"),
+        )
+      : activeMessage(state, errors, heartbeat),
+  };
+}
+
 async function pollJob(jobId, uid, token) {
   const statusUrl = `${API}/ingest/status?job_id=${encodeURIComponent(jobId)}`;
   let lastProgress = "";
@@ -236,18 +306,49 @@ async function pollJob(jobId, uid, token) {
     if (response.status === 401) throw new Error("session expired; run `skalpel login` and retry");
     if (!response.ok) continue;
     const status = await response.json().catch(() => ({}));
-    if (status.state === "done") return status.n_sessions ?? 0;
-    if (status.state === "error") {
-      writeState({ state: "failed", user_id: uid, error: "server graph build failed" });
-      throw new Error("server graph build failed");
+    const progress = normalizeJobStatus(status);
+    if (progress.complete) {
+      return { sessions: progress.sessions, errors: progress.errors };
     }
-    const progress = `${status.done ?? 0}/${status.total ?? 0}`;
-    if (status.state === "judging" && progress !== lastProgress) {
-      lastProgress = progress;
-      writeState({ state: "judging", user_id: uid, job_id: jobId, ...status });
-      emit("judging", `Judging your sessions… ${progress}`, {
-        done: status.done ?? 0,
-        total: status.total ?? 0,
+    if (progress.failed) {
+      writeState({
+        state: "failed",
+        server_state: progress.state,
+        user_id: uid,
+        job_id: jobId,
+        done: progress.done,
+        total: progress.total,
+        errors: progress.errors,
+        heartbeat: progress.heartbeat,
+        error: progress.message,
+      });
+      throw new Error(progress.message);
+    }
+    const signature = JSON.stringify([
+      progress.state,
+      progress.done,
+      progress.total,
+      progress.errors,
+      progress.heartbeat,
+    ]);
+    // Persist every successful poll as a local liveness heartbeat. Emit only when the server's
+    // observable state changes; Bubble Tea advances its own spinner between status rows.
+    writeState({
+      state: progress.state,
+      user_id: uid,
+      job_id: jobId,
+      done: progress.done,
+      total: progress.total,
+      errors: progress.errors,
+      heartbeat: progress.heartbeat,
+    });
+    if (signature !== lastProgress) {
+      lastProgress = signature;
+      emit(progress.state, progress.message, {
+        done: progress.done,
+        total: progress.total,
+        errors: progress.errors,
+        heartbeat: progress.heartbeat,
       });
     }
   }
@@ -308,6 +409,7 @@ async function ingestAndFinish(files, auth, runStartMs) {
 
   const accepted = await response.json().catch(() => ({}));
   let sessions;
+  let errors = 0;
   if (typeof accepted.n_sessions === "number") {
     sessions = accepted.n_sessions;
   } else if (accepted.job_id) {
@@ -321,14 +423,18 @@ async function ingestAndFinish(files, auth, runStartMs) {
       done: 0,
       total: payload.sessions,
     });
-    sessions = await pollJob(accepted.job_id, auth.uid, auth.token);
+    const result = await pollJob(accepted.job_id, auth.uid, auth.token);
+    sessions = result.sessions;
+    errors = result.errors;
   } else {
     throw new Error("ingest response did not include a graph job");
   }
 
-  emit("building", `Building your graph from ${sessions} session${sessions === 1 ? "" : "s"}…`, {
-    sessions,
-  });
+  emit(
+    "building",
+    `Building your graph from ${sessions} session${sessions === 1 ? "" : "s"}${errors > 0 ? ` · ${errors} failed` : ""}…`,
+    { sessions, errors },
+  );
   const profile = await fetchProfile(auth.uid, auth.token);
   recordProfile(profile, sessions);
   writeState({
@@ -364,11 +470,15 @@ async function main() {
     return;
   }
 
-  if (prior.user_id === auth.uid && prior.job_id && prior.state !== "done") {
+  // --force is the explicit replay path for a terminal job. Re-polling its old job_id can only
+  // return the same idempotent terminal result; a fresh scan/POST is required.
+  if (!FORCE && prior.user_id === auth.uid && prior.job_id && prior.state !== "done") {
     emit("resuming", "Resuming the existing graph build");
-    const sessions = await pollJob(prior.job_id, auth.uid, auth.token);
+    const result = await pollJob(prior.job_id, auth.uid, auth.token);
+    const { sessions, errors } = result;
     emit("building", `Building your graph from ${sessions} session${sessions === 1 ? "" : "s"}…`, {
       sessions,
+      errors,
     });
     const profile = await fetchProfile(auth.uid, auth.token);
     recordProfile(profile, sessions);
@@ -402,18 +512,31 @@ async function main() {
   await ingestAndFinish(files, auth, runStartMs);
 }
 
-if (!acquireLock()) {
-  emit("skipped", "Coding history is already being learned in another skalpel window", {
-    terminal: true,
-  });
-} else {
-  main()
+async function run() {
+  if (!acquireLock()) {
+    emit("skipped", "Coding history is already being learned in another skalpel window", {
+      terminal: true,
+    });
+    return;
+  }
+  await main()
     .catch((error) => {
       const prior = readState();
       const message = String(error?.message || error).replace(/[\r\n\t]+/g, " ").slice(0, 240);
       writeState({ ...prior, state: "failed", error: message });
-      emit("failed", message, { terminal: true, retryable: true });
+      emit("failed", message, {
+        terminal: true,
+        retryable: true,
+        done: prior.done ?? 0,
+        total: prior.total ?? 0,
+        errors: prior.errors ?? 0,
+        heartbeat: prior.heartbeat ?? null,
+      });
       process.exitCode = 1;
     })
     .finally(releaseLock);
 }
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await run();
+}

package/prosumer-hooks/bootstrap.test.mjs

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { normalizeJobStatus } from "./bootstrap.mjs";
+
+test("running jobs expose real counters instead of staying at zero", () => {
+  assert.deepEqual(
+    normalizeJobStatus({ state: "running", done: 2, total: 16, errors: 0 }),
+    {
+      state: "running",
+      done: 2,
+      total: 16,
+      errors: 0,
+      heartbeat: null,
+      terminal: false,
+      requiresReplay: false,
+      complete: false,
+      failed: false,
+      sessions: 2,
+      message: "Learning from your sessions",
+    },
+  );
+});
+
+test("waiting_quota remains nonterminal and carries failures plus heartbeat", () => {
+  const progress = normalizeJobStatus({
+    state: "waiting_quota",
+    done: 5,
+    total: 16,
+    errors: 1,
+    heartbeat_at: "2026-07-12T04:00:00Z",
+  });
+
+  assert.equal(progress.failed, false);
+  assert.equal(progress.complete, false);
+  assert.equal(progress.done, 5);
+  assert.equal(progress.total, 16);
+  assert.equal(progress.errors, 1);
+  assert.equal(progress.heartbeat, "2026-07-12T04:00:00Z");
+  assert.equal(progress.message, "Waiting for graph capacity · 1 session failed · server active");
+});
+
+test("terminal waiting_quota tells the caller to create a fresh replay", () => {
+  const progress = normalizeJobStatus({
+    state: "waiting_quota",
+    done: 2,
+    total: 16,
+    errors: 0,
+    terminal: true,
+    requires_replay: true,
+  });
+
+  assert.equal(progress.failed, true);
+  assert.equal(progress.terminal, true);
+  assert.equal(progress.requiresReplay, true);
+  assert.equal(progress.message, "graph capacity was exhausted; retry the build");
+});
+
+test("unknown future phases stay visible as active work", () => {
+  const progress = normalizeJobStatus({ state: "embedding", done: 9, total: 16 });
+  assert.equal(progress.state, "embedding");
+  assert.equal(progress.failed, false);
+  assert.equal(progress.complete, false);
+  assert.equal(progress.message, "Building your intent graph");
+});
+
+test("done and error states retain authoritative terminal detail", () => {
+  const complete = normalizeJobStatus({
+    state: "done",
+    done: 14,
+    total: 16,
+    errors: 2,
+    n_sessions: 14,
+  });
+  assert.equal(complete.complete, true);
+  assert.equal(complete.sessions, 14);
+  assert.equal(complete.errors, 2);
+
+  const failed = normalizeJobStatus({
+    state: "error",
+    done: 2,
+    total: 16,
+    errors: 14,
+    error: "provider quota exhausted",
+    updated_at: "2026-07-12T04:01:00Z",
+  });
+  assert.equal(failed.failed, true);
+  assert.equal(failed.message, "provider quota exhausted");
+  assert.equal(failed.done, 2);
+  assert.equal(failed.total, 16);
+  assert.equal(failed.errors, 14);
+  assert.equal(failed.heartbeat, "2026-07-12T04:01:00Z");
+});