shadok-ai 0.9.0 → 0.9.2

package/README.md

@@ -354,7 +354,7 @@ machine, which silently shifts every daily prompt on a server running in UTC.
 | `SHADOK_PERMISSION_MODE` | mode new agents start in (default `acceptEdits`) |
 | `SHADOK_AUTOUPDATE` | fallback only — the GUI setting wins once used |
 | `SHADOK_PILOT_PROMPT=0` | don't inject the cockpit system prompt |
-| `SHADOK_LEDGER=1` | opt into the shared-ledger reflex (OFF by default; the GUI/config setting wins once used) |
+| `SHADOK_LEDGER=1` | opt into the shared-ledger reflex — a per-instance state table siblings read/write so they stop re-surfacing resolved work, plus a `⟦ledger⟧` delta pushed ahead of each message (OFF by default; the GUI/config setting wins once used) |
 | `SHADOK_RESUME_SUMMARY=1` | don't auto-answer the resume-from-summary prompt |
 | `SHADOK_SSH_IDENTITY=0` · `SHADOK_FORCE_SSH_IDENTITY=1` | disable / force the Docker SSH identity |
 | `TELEGRAM_BOT_TOKEN` · `TELEGRAM_ALLOWED_CHATS` | override the stored config |

package/context/ledger-reflex.md

@@ -16,9 +16,18 @@ Then let it steer you:
   ("de mémoire, à faire — dis-moi si c'est déjà réglé"), don't assert;
 - a **stale** record (days old) → confirm before acting.
 
+**You are also pushed the changes.** Before each user message you may receive a
+`⟦ledger · N updates since your last message⟧` block listing what sibling agents
+resolved or decided since you last heard — each line `• [id] entity — status`.
+Treat it as current status (don't re-raise what it shows resolved). It is the
+push half; `check` is still there for older or specific items the block didn't
+carry.
+
 When you **resolve, decide, or change** something notable, record it so the next
 agent doesn't redo it:
 `node ~/.claude/skills/shadok-ledger/ledger.mjs record --entity "<name>" --status <resolved|open|in-progress|decided> --note "<line>" --source "<PR#/who>"`.
+To update an item you saw in the block, quote its handle instead of retyping the
+name: `… record --id <id> --status resolved --note "<line>"`.
 
 This gates **status** claims only. A durable lesson or constraint (not a status)
 is used freely.

package/context/ledger-skill/SKILL.md

@@ -46,6 +46,15 @@ node ~/.claude/skills/shadok-ledger/ledger.mjs record \
 Re-recording the same entity **supersedes** its row (no duplicates). Log facts —
 resolutions, decisions, state changes, launched actions — never chatter.
 
+Every row has a short **id** (shown as `[id]` in `check`/`list` and in the ledger
+block pushed ahead of your messages). To update a row you already saw, quote its
+id instead of retyping the name — no risk of a typo forking a second row:
+
+```
+node ~/.claude/skills/shadok-ledger/ledger.mjs record \
+  --id <id> --status resolved --note "<one line>"
+```
+
 ## To consult the whole table
 
 ```

package/context/ledger-skill/ledger-core.mjs

@@ -12,13 +12,52 @@ export function normEntity(s) {
 }
 
 /**
- * Upsert by normalised entity — SUPERSEDE the existing row, never append a twin.
- * `now` (epoch ms) is injected so the core stays pure/testable.
+ * Resolve a short id — exact match, else a UNIQUE prefix — to its row, or null.
+ * Empty and ambiguous both resolve to null (never guess), the same rule the cron
+ * ids follow (invariant 17). The id is a durable HANDLE an agent can quote from
+ * the pushed ledger block to update a row without retyping its (long) entity.
  */
-export function upsertEntry(entries, patch, now) {
+export function resolveId(entries, idOrPrefix) {
+  const q = String(idOrPrefix ?? "").trim().toLowerCase();
+  if (!q) return null;
+  const exact = entries.find((e) => e.id === q);
+  if (exact) return exact;
+  const pre = entries.filter((e) => typeof e.id === "string" && e.id.startsWith(q));
+  return pre.length === 1 ? pre[0] : null;
+}
+
+/**
+ * Upsert a row, two ways:
+ *  - `patch.id` present → UPDATE that exact row in place (resolved via resolveId),
+ *    keeping its id AND its entity (a rename only if `patch.entity` is given).
+ *    An unknown id THROWS — an update must never silently spawn a new row.
+ *  - else → upsert by normalised entity: supersede the existing twin, PRESERVING
+ *    its id (the handle is durable across every write), or create a new row with
+ *    `newId`.
+ * `now` (epoch ms) and `newId` are injected so the core stays pure/testable.
+ */
+export function upsertEntry(entries, patch, now, newId) {
+  if (patch.id != null && String(patch.id).trim()) {
+    const cur = resolveId(entries, patch.id);
+    if (!cur) throw new Error(`no ledger entry with id "${patch.id}"`);
+    const row = {
+      id: cur.id,
+      entity:
+        patch.entity != null && String(patch.entity).trim() ? String(patch.entity).trim() : cur.entity,
+      status:
+        patch.status != null && String(patch.status).trim() ? String(patch.status).trim() : cur.status,
+      ...((patch.note ?? cur.note) ? { note: String(patch.note ?? cur.note).trim() } : {}),
+      ...((patch.source ?? cur.source) ? { source: String(patch.source ?? cur.source).trim() } : {}),
+      updatedAt: now,
+    };
+    return [...entries.filter((e) => e.id !== cur.id), row];
+  }
+
   const key = normEntity(patch.entity);
   if (!key) throw new Error("entity is required");
+  const existing = entries.find((e) => normEntity(e.entity) === key);
   const row = {
+    id: existing?.id ?? newId,
     entity: String(patch.entity).trim(),
     status: String(patch.status ?? "").trim(),
     ...(patch.note ? { note: String(patch.note).trim() } : {}),
@@ -29,14 +68,17 @@ export function upsertEntry(entries, patch, now) {
 }
 
 /**
- * Rows whose entity OR note contains the query (case-insensitive), most-recent
- * first. An empty query returns the whole table (for `list`).
+ * Rows whose id, entity OR note contains the query (case-insensitive), most-
+ * recent first. An empty query returns the whole table (for `list`).
  */
 export function findEntries(entries, query) {
   const q = normEntity(query);
   const rows = q
     ? entries.filter(
-        (e) => normEntity(e.entity).includes(q) || normEntity(e.note ?? "").includes(q),
+        (e) =>
+          String(e.id ?? "").toLowerCase().includes(q) ||
+          normEntity(e.entity).includes(q) ||
+          normEntity(e.note ?? "").includes(q),
       )
     : entries.slice();
   return rows.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0));

package/context/ledger-skill/ledger.mjs

@@ -1,13 +1,20 @@
 #!/usr/bin/env node
 // shadok-ledger CLI — a tiny state table so agents verify a status before they
-// assert or act on it. Store: ~/.shadok-ai/ledger.json (per instance, NOT the
-// repo). See SKILL.md and the design spec. No server involved.
+// assert or act on it, and record what they resolve/decide.
+//
+// Store: the PER-INSTANCE ledger. The server hands each agent the exact path in
+// SHADOK_LEDGER_FILE at spawn (an agent's own cwd is a worktree, not the launch
+// dir, so it cannot derive it); a hand-run CLI with no env falls back to the
+// legacy global file. See SKILL.md and the design spec. No server involved.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { upsertEntry, findEntries, ageDays } from "./ledger-core.mjs";
+import crypto from "node:crypto";
+import { upsertEntry, findEntries, ageDays, resolveId, normEntity } from "./ledger-core.mjs";
 
-const FILE = path.join(os.homedir(), ".shadok-ai", "ledger.json");
+const FILE =
+  (process.env.SHADOK_LEDGER_FILE || "").trim() ||
+  path.join(os.homedir(), ".shadok-ai", "ledger.json");
 
 function load() {
   try {
@@ -25,6 +32,16 @@ function save(rows) {
   fs.renameSync(tmp, FILE); // atomic: a concurrent reader never sees half a file
 }
 
+/** A short, unique handle (4 hex): quotable from the pushed ledger block. */
+function mintId(rows) {
+  const taken = new Set(rows.map((r) => r.id).filter(Boolean));
+  for (let i = 0; i < 1000; i++) {
+    const id = crypto.randomBytes(2).toString("hex");
+    if (!taken.has(id)) return id;
+  }
+  return crypto.randomBytes(4).toString("hex");
+}
+
 /** `--key value` pairs → object. Values may be quoted by the shell already. */
 function parseFlags(args) {
   const out = {};
@@ -37,7 +54,8 @@ function parseFlags(args) {
 function fmt(e, now) {
   const age = ageDays(e, now);
   const when = age <= 0 ? "today" : age === 1 ? "1d ago" : `${age}d ago`;
-  const head = `• ${e.entity} — ${e.status} (${when}${e.source ? ` · ${e.source}` : ""})`;
+  const handle = e.id ? `[${e.id}] ` : "";
+  const head = `• ${handle}${e.entity} — ${e.status} (${when}${e.source ? ` · ${e.source}` : ""})`;
   return e.note ? `${head}\n    ${e.note}` : head;
 }
 
@@ -59,13 +77,33 @@ if (cmd === "check") {
   }
 } else if (cmd === "record") {
   const f = parseFlags(rest);
-  if (!f.entity || !f.status) {
-    console.error('usage: ledger record --entity "<name>" --status <resolved|open|in-progress|decided> [--note "<line>"] [--source "<ref>"]');
+  // Two shapes: create/supersede by --entity (+ --status), or update an existing
+  // row by its --id handle (change any of status/note/source; entity optional).
+  const byId = f.id != null && String(f.id).trim();
+  const idHasNoFields = f.status == null && f.note == null && f.source == null && f.entity == null;
+  if (byId ? idHasNoFields : !f.entity || !f.status) {
+    console.error(
+      'usage: ledger record --entity "<name>" --status <resolved|open|in-progress|decided> [--note "<line>"] [--source "<ref>"]\n' +
+        '   or: ledger record --id <handle> [--status <…>] [--note "<line>"] [--source "<ref>"]',
+    );
+    process.exit(2);
+  }
+  const rows0 = load();
+  let rows;
+  try {
+    rows = upsertEntry(
+      rows0,
+      { id: f.id, entity: f.entity, status: f.status, note: f.note, source: f.source },
+      now,
+      mintId(rows0),
+    );
+  } catch (e) {
+    console.error(String(e?.message ?? e));
     process.exit(2);
   }
-  const rows = upsertEntry(load(), { entity: f.entity, status: f.status, note: f.note, source: f.source }, now);
   save(rows);
-  console.log(`recorded: ${f.entity} — ${f.status}`);
+  const row = byId ? resolveId(rows, f.id) : rows.find((r) => normEntity(r.entity) === normEntity(f.entity));
+  console.log(`recorded: ${row.entity} — ${row.status} [${row.id}]`);
 } else if (cmd === "list") {
   const rows = findEntries(load(), "");
   console.log(rows.length ? rows.map((e) => fmt(e, now)).join("\n") : "(ledger empty)");

package/dist/claude-auth.js

@@ -1,4 +1,5 @@
 import { execFile, spawn } from "node:child_process";
+import { claudeCommand } from "./claude-bin.js";
 /** Pure: `claude auth status --json`. Unreadable output is `unknown`, NOT signed out. */
 export function parseAuthStatus(stdout) {
     try {
@@ -59,7 +60,7 @@ export function invalidateAuthStatus() {
     cached = null;
 }
 const probe = () => new Promise((resolve) => {
-    execFile("claude", ["auth", "status", "--json"], { timeout: 15_000 }, (_err, stdout) => resolve(parseAuthStatus(stdout ?? "")));
+    execFile(claudeCommand(), ["auth", "status", "--json"], { timeout: 15_000 }, (_err, stdout) => resolve(parseAuthStatus(stdout ?? "")));
 });
 export async function authStatus(force = false) {
     if (!force && cached && Date.now() - cached.at < STATUS_TTL_MS)
@@ -106,7 +107,7 @@ export async function startLogin() {
     if ((await authStatus(true)).state === "signed-in")
         return { alreadySignedIn: true };
     cancelLogin();
-    const child = spawn("claude", ["auth", "login", "--claudeai"], {
+    const child = spawn(claudeCommand(), ["auth", "login", "--claudeai"], {
         // BROWSER is neutralised: on a desktop host the CLI would otherwise open a
         // tab on the SERVER's machine, which is not where the user is.
         env: { ...process.env, BROWSER: "/usr/bin/true" },

package/dist/claude-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-auth.js","sourceRoot":"","sources":["../src/claude-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude-auth.js","sourceRoot":"","sources":["../src/claude-auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAuC,MAAM,oBAAoB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAqChD,yFAAyF;AACzF,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YACjD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC/C,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI;YAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QACzE,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,WAAW;YAClB,GAAG,CAAC,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzE,GAAG,CAAC,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,GAAG,CAAC,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5F,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC;QACN,kEAAkE;SACjE,OAAO,CAAC,uCAAuC,EAAE,EAAE,CAAC;QACrD,wCAAwC;SACvC,OAAO,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAChE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACzB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,OAAO,eAAe,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3E,CAAC;AAED,gFAAgF;AAChF,MAAM,aAAa,GAAG,MAAM,CAAC;AAC7B,iFAAiF;AACjF,MAAM,YAAY,GAAG,EAAE,GAAG,MAAM,CAAC;AAEjC,IAAI,MAAM,GAA8C,IAAI,CAAC;AAE7D,MAAM,UAAU,oBAAoB;IAClC,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED,MAAM,KAAK,GAAG,GAAwB,EAAE,CACtC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAC5F,OAAO,CAAC,eAAe,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CACvC,CAAC;AACJ,CAAC,CAAC,CAAC;AAEL,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAK,GAAG,KAAK;IAC5C,IAAI,CAAC,KAAK,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,EAAE,GAAG,aAAa;QAAE,OAAO,MAAM,CAAC,MAAM,CAAC;IACrF,IAAI,MAAM,GAAG,MAAM,KAAK,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,2EAA2E;IAC3E,0CAA0C;IAC1C,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,GAAG,MAAM,KAAK,EAAE,CAAC;IACvD,6EAA6E;IAC7E,4DAA4D;IAC5D,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,MAAM,GAAG,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,CAAC;IACpE,OAAO,MAAM,CAAC;AAChB,CAAC;AAiBD;;;;;GAKG;AACH,IAAI,IAAI,GAAgB,IAAI,CAAC;AAE7B,MAAM,UAAU,YAAY;IAC1B,OAAO,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzB,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAClB,IAAI,GAAG,IAAI,CAAC;AACd,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU;IAG9B,0EAA0E;IAC1E,6EAA6E;IAC7E,wEAAwE;IACxE,kCAAkC;IAClC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IAC9D,8EAA8E;IAC9E,8EAA8E;IAC9E,oDAAoD;IACpD,IAAI,CAAC,MAAM,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,WAAW;QAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;IACrF,WAAW,EAAE,CAAC;IACd,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE;QACpE,2EAA2E;QAC3E,+DAA+D;QAC/D,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE;QACjD,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAChC,CAAC,CAAC;IACH,MAAM,CAAC,GAAS;QACd,KAAK;QACL,GAAG,EAAE,IAAI;QACT,GAAG,EAAE,EAAE;QACP,OAAO,EAAE,IAAI;QACb,KAAK,EAAE,KAAK;QACZ,KAAK,EAAE,UAAU,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC;KACrD,CAAC;IACF,IAAI,GAAG,CAAC,CAAC;IAET,MAAM,MAAM,GAAG,CAAC,CAAU,EAAE,EAAE;QAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC;QACvB,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;QACjB,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IACZ,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,CAAS,EAAE,EAAE;QAC3B,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QACtB,IAAI,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,cAAc;YAAE,MAAM,CAAC,cAAc,CAAC,CAAC;IAC1E,CAAC,CAAC;IACF,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,6EAA6E;IAC7E,4EAA4E;IAC5E,6EAA6E;IAC7E,qDAAqD;IACrD,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACxB,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;QACf,MAAM,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IACH,6EAA6E;IAC7E,oCAAoC;IACpC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACrB,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC;QACf,MAAM,CAAC,OAAO,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,EAAE;YAC/B,WAAW,EAAE,CAAC;YACd,OAAO,CAAC,EAAE,KAAK,EAAE,6CAA6C,EAAE,CAAC,CAAC;QACpE,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,MAAM,GAAG,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACjC,IAAI,GAAG,EAAE,CAAC;gBACR,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC;gBACZ,aAAa,CAAC,IAAI,CAAC,CAAC;gBACpB,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACvB,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;YACnB,CAAC;iBAAM,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;gBACjC,aAAa,CAAC,IAAI,CAAC,CAAC;gBACpB,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACvB,OAAO,CAAC,EAAE,KAAK,EAAE,+CAA+C,EAAE,CAAC,CAAC;YACtE,CAAC;QACH,CAAC,EAAE,GAAG,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY;IAEZ,MAAM,CAAC,GAAG,IAAI,CAAC;IACf,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,6CAA6C,EAAE,CAAC;IAC9F,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAExD,+DAA+D;IAC/D,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC,CAAC;IACxD,6EAA6E;IAC7E,iDAAiD;IACjD,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC;IAEX,MAAM,OAAO,GAAG,MAAM,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;QACrD,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE;YACxB,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;YACjB,OAAO,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC,EAAE,MAAM,CAAC,CAAC;QACX,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,EAAE;YAChB,YAAY,CAAC,CAAC,CAAC,CAAC;YAChB,OAAO,CAAC,CAAC,CAAC,CAAC;QACb,CAAC,CAAC;QACF,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,WAAW,EAAE,CAAC;QACd,oBAAoB,EAAE,CAAC;QACvB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IACD,IAAI,OAAO,KAAK,cAAc;QAC5B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,0DAA0D,EAAE,CAAC;IAC1F,IAAI,OAAO,KAAK,OAAO;QACrB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yDAAyD,EAAE,CAAC;IACzF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAC;AACnE,CAAC"}

package/dist/claude-bin.d.ts

@@ -4,11 +4,121 @@
  * (name, env, exists) — inject `exists` in tests.
  */
 export declare function resolveBin(name: string, env?: NodeJS.ProcessEnv, exists?: (p: string) => boolean): string | null;
+/** Bytes read to classify a launcher. The whole placeholder is 500 B. */
+export declare const BIN_HEAD_BYTES = 512;
+export type BinKind = "usable" | "stub" | "missing";
+/** What a cheap look at a launcher file yields: its size and its first bytes. */
+export interface BinSample {
+    size: number;
+    head: string;
+}
+/**
+ * Tell the npm placeholder from something we can actually run. Pure.
+ *
+ * Deliberately CONSERVATIVE: it condemns only what it positively recognises as
+ * the placeholder, and calls everything else usable. The tempting rule — "a
+ * real claude is an ELF/Mach-O of hundreds of MB, so anything else is broken" —
+ * would also condemn every legitimate small launcher: pnpm's shell shim,
+ * volta/asdf/mise shims, npm's `.cmd` shim on Windows, a user's own wrapper.
+ * Those work fine, and refusing to spawn them would be a worse bug than the one
+ * this fixes. Same rule as invariant 27: assert only what you observed.
+ *
+ * No execution probe. Running `claude --version` before each spawn would cost a
+ * process launch per session start, and it would not even be sound: the answer
+ * is stale the moment it returns, and the window this guards against is
+ * milliseconds wide. A stat plus a 512-byte read costs microseconds and is
+ * exactly as (un)raceable, so it buys the safety at none of the price.
+ */
+export declare function classifyBin(sample: BinSample | null): BinKind;
+/** Read the first {@link BIN_HEAD_BYTES} of a file, or null if it isn't there. */
+export declare function sampleBin(p: string): BinSample | null;
+/**
+ * The optional dependency holding the native binary for a platform, mirroring
+ * the PLATFORMS map of `install.cjs`. Returns null for a platform the package
+ * does not publish — the caller then has no fallback, which is the truth.
+ */
+export declare function platformPkg(platform: string, arch: string, musl?: boolean): {
+    pkg: string;
+    bin: string;
+} | null;
+/**
+ * Where the native binary may sit, given the REAL path of the launcher
+ * (`.../@anthropic-ai/claude-code/bin/claude.exe`). Pure: it only builds
+ * candidates, the caller decides which one exists.
+ *
+ * The `node_modules` walk is not decoration. npm hoists an optional dependency
+ * to the top level as readily as it nests it, and the layout differs between a
+ * global install, `npx`, and the managed `~/.shadok-ai/app`. Assuming the nested
+ * layout is precisely the mistake that made `node-pty-fix.ts`'s chmod silently
+ * miss on every non-dev install (see CLAUDE.md) — so we reproduce node's own
+ * resolution instead: every ancestor directory, each with `node_modules/<pkg>`.
+ */
+export declare function nativeBinCandidates(launcherRealPath: string, pkg: string, bin: string): string[];
+export type ClaudeBin = {
+    ok: true;
+    path: string;
+    via: "launcher" | "native";
+} | {
+    ok: false;
+    reason: "missing" | "stub";
+};
+export interface FindClaudeDeps {
+    /** Find the launcher now (typically resolveBin("claude")). */
+    resolve: () => string | null;
+    /** Follow symlinks (typically fs.realpathSync); may throw, caller guards. */
+    realpath: (p: string) => string;
+    /** Cheap look at a file (typically sampleBin). */
+    sample: (p: string) => BinSample | null;
+    platform: string;
+    arch: string;
+    musl: boolean;
+}
+/**
+ * Resolve a claude we can actually run: the launcher when it is real, else the
+ * native binary the launcher is only a placeholder for. Pure over injected
+ * deps, so the whole decision is unit-tested without touching the real FS.
+ */
+export declare function findClaudeBin(deps: FindClaudeDeps): ClaudeBin;
+export interface RetryOptions {
+    /** Total attempts, including the first. */
+    tries?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * {@link findClaudeBin}, retried briefly. The failure this guards is a
+ * TRANSIENT window in someone else's postinstall (unlink → relink), so a hard
+ * refusal on the first look would report a healthy install as broken. Bounded
+ * on purpose — a couple of seconds at worst, and only on the spawn path, never
+ * at boot (same rule as `ensureTmux` / `ensureSshIdentity`: nothing here may
+ * hold the server back from serving).
+ */
+export declare function findClaudeBinWithRetry(deps: FindClaudeDeps, opts?: RetryOptions): Promise<ClaudeBin>;
+/** Live deps for {@link findClaudeBin}, reading the real filesystem. */
+export declare function liveClaudeDeps(): FindClaudeDeps;
+/**
+ * The claude to spawn. The resolved binary when we have one — which is NOT
+ * always the launcher, see {@link findClaudeBin} — else the bare name, so a
+ * layout we failed to understand behaves exactly as it did before.
+ *
+ * Re-validated on each call: a cached path rots the moment claude-code
+ * upgrades, and one stat is a rounding error next to the process spawn every
+ * caller is about to pay for.
+ */
+export declare function claudeCommand(): string;
+/** Record a path already resolved (by `ensureClaude`), so we don't look twice. */
+export declare function rememberClaudeBin(p: string | null): void;
 /** The manual-install fallback message, shown when the auto-install can't help. */
 export declare function claudeMissingMessage(detail: string): string;
+/**
+ * Why a spawn was refused when `claude` IS on PATH. The point is to say what is
+ * wrong instead of letting a bare `posix_spawnp failed` — or the placeholder's
+ * own exit 1 — reach the user, in the spirit of `describeStuckScreen`.
+ */
+export declare function claudeStubMessage(): string;
 export interface EnsureClaudeDeps {
-    /** Find claude now (typically resolveBin("claude")). Called again after install. */
-    resolve: () => string | null;
+    /** Locate a RUNNABLE claude now. Called again after an install. */
+    find: () => Promise<ClaudeBin>;
     /** Perform the global install (typically `npm i -g @anthropic-ai/claude-code`). */
     install: () => Promise<void>;
     /** Surface progress (server log / a line to the client). */
@@ -22,10 +132,14 @@ export type EnsureClaudeResult = {
     error: string;
 };
 /**
- * Make the claude CLI available, installing it ONCE if it is missing. Returns
- * the resolved path, or a clear, actionable error when it still isn't there
- * (install failed on permissions, or the global bin dir isn't on PATH) — never
- * the raw `posix_spawnp failed` a bare spawn would throw. Pure orchestration
- * over injected deps, so it is tested without touching npm.
+ * Make a runnable claude CLI available, installing it ONCE if it is missing.
+ * Returns the path to spawn — which is NOT always the launcher: when the
+ * launcher is the placeholder we hand back the native binary behind it.
+ * Otherwise a clear, actionable error, never the raw `posix_spawnp failed` a
+ * bare spawn would throw, and never the placeholder's opaque exit 1.
+ *
+ * A placeholder is NOT a reason to reinstall: the package is plainly installed,
+ * so `npm i -g` would neither be the missing-CLI case nor a safe move while
+ * someone else's postinstall is mid-rewrite. We say what is wrong instead.
  */
 export declare function ensureClaude(deps: EnsureClaudeDeps): Promise<EnsureClaudeResult>;