@hncode/hncode 0.4.2 → 0.5.1

package/src/schedule.js

@@ -0,0 +1,294 @@
+// Scheduled prompts (/schedule) — a cron-like entry that queues a prompt on a
+// running session. Mirrors cline's `schedule` command: a recurring prompt for work
+// that happens on a clock rather than because the user asked.
+//
+// The cron parser is written here rather than pulled in as a dependency, because the
+// whole point of the feature is one line of config and a timer — five fields of
+// numbers and ranges do not justify a package. It supports exactly the cron subset
+// that is useful for a coding session and REJECTS anything it does not understand
+// instead of guessing: a schedule that silently never fires is worse than one that
+// fails loudly at parse time.
+//
+// Supported syntax, per field:
+//   *      any value
+//   5       that value
+//   1,3,5   a list
+//   1-5     a range
+//   */15    a step over the field's range
+//   1-30/10 a step over a range
+//
+// Field order and ranges are the standard five-field form:
+//   minute 0-59, hour 0-23, day-of-month 1-31, month 1-12, day-of-week 0-6 (0 = Sun)
+//
+// Day-of-month and day-of-week are combined with OR when BOTH are restricted, which
+// is what cron does (and is the standard source of confusion — a `0 9 1 * 1` entry
+// fires on the 1st OR on Mondays, not only on Mondays that are the 1st). That
+// behaviour is implemented, and stated in the help text rather than left as folklore.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FIELDS = [
+  { name: 'minute', min: 0, max: 59 },
+  { name: 'hour', min: 0, max: 23 },
+  { name: 'dom', min: 1, max: 31 },
+  { name: 'month', min: 1, max: 12 },
+  { name: 'dow', min: 0, max: 6 },
+];
+
+/** Compile one field into a Set of allowed numbers. Throws on anything invalid. */
+function parseField(spec, field) {
+  const out = new Set();
+  for (const part of String(spec).split(',')) {
+    const piece = part.trim();
+    if (!piece) throw new Error(`empty ${field.name} entry`);
+    // `base/step` — the base may be `*`, a single value or a range.
+    const [base, stepRaw] = piece.split('/');
+    let step = 1;
+    if (stepRaw !== undefined) {
+      step = Number(stepRaw);
+      if (!Number.isInteger(step) || step < 1) throw new Error(`bad step "${stepRaw}" in ${field.name}`);
+    }
+    let lo;
+    let hi;
+    if (base === '*') { lo = field.min; hi = field.max; }
+    else if (base.includes('-')) {
+      const [a, b] = base.split('-');
+      lo = Number(a);
+      hi = Number(b);
+      if (!Number.isInteger(lo) || !Number.isInteger(hi)) throw new Error(`bad range "${base}" in ${field.name}`);
+    } else {
+      lo = Number(base);
+      hi = lo;
+      if (!Number.isInteger(lo)) throw new Error(`bad value "${base}" in ${field.name}`);
+    }
+    // A DOW of 7 means Sunday in several cron implementations. Folding it to 0 must
+    // happen BEFORE the range tests: folding `hi` first made the single value `7`
+    // satisfy `hi < lo` (0 < 7) and be rejected as a backwards range.
+    const isDow = field.name === 'dow';
+    const foldDow = (v) => (isDow && v === 7 ? 0 : v);
+    if (isDow) {
+      // Validate against the ALLOWED range (0-7) before folding, so `8` is still
+      // rejected while `7` is accepted.
+      if (lo < field.min || lo > field.max + 1 || hi > field.max + 1) {
+        throw new Error(`${field.name} "${piece}" is out of range ${field.min}-${field.max}`);
+      }
+    } else if (lo < field.min || hi > field.max) {
+      throw new Error(`${field.name} "${piece}" is out of range ${field.min}-${field.max}`);
+    }
+    if (hi < lo) throw new Error(`${field.name} range "${base}" runs backwards`);
+    // A range ENDING at 7 covers Sunday, so the fold cannot just remap both ends to
+    // 0 — `0-7` would become `0-0` and lose six days. Iterate the original range and
+    // fold each VALUE instead.
+    for (let v = lo; v <= hi; v += step) out.add(foldDow(v));
+  }
+  return out;
+}
+
+/**
+ * Compile a cron expression. Returns a matcher with
+ * `{ fields, matches(date), describe(), restricted }`, or throws with a message
+ * naming the field that is wrong.
+ */
+export function parseCron(expr) {
+  const parts = String(expr == null ? '' : expr).trim().split(/\s+/).filter(Boolean);
+  if (parts.length !== 5) {
+    throw new Error(`expected 5 fields (minute hour day-of-month month day-of-week), got ${parts.length}`);
+  }
+  const fields = {};
+  for (let i = 0; i < FIELDS.length; i++) {
+    fields[FIELDS[i].name] = parseField(parts[i], FIELDS[i]);
+  }
+  // Which fields were written as `*`: the OR rule for dom/dow only applies when BOTH
+  // are restricted, so the distinction has to survive parsing.
+  const restricted = {
+    dom: parts[2].trim() !== '*',
+    dow: parts[4].trim() !== '*',
+  };
+  return {
+    fields,
+    restricted,
+    expr: parts.join(' '),
+    matches(date) {
+      const d = date || new Date();
+      if (!fields.minute.has(d.getMinutes())) return false;
+      if (!fields.hour.has(d.getHours())) return false;
+      if (!fields.month.has(d.getMonth() + 1)) return false;
+      const domHit = fields.dom.has(d.getDate());
+      const dowHit = fields.dow.has(d.getDay());
+      // Standard cron: when both day fields are restricted, either may match.
+      if (restricted.dom && restricted.dow) return domHit || dowHit;
+      if (restricted.dom) return domHit;
+      if (restricted.dow) return dowHit;
+      return true;
+    },
+  };
+}
+
+/** `0 9 * * 1-5` -> `weekdays at 09:00`. A readable gloss when the shape is known. */
+export function describeCron(expr) {
+  const text = String(expr || '').trim();
+  const named = {
+    '0 9 * * 1-5': 'weekdays at 09:00',
+    '0 18 * * 1-5': 'weekdays at 18:00',
+    '*/30 * * * *': 'every 30 minutes',
+    '0 * * * *': 'every hour, on the hour',
+    '0 0 * * *': 'daily at midnight',
+  };
+  return named[text] || text;
+}
+
+/** Validate a schedule entry's fields. Returns { ok, error }. */
+export function validateEntry(entry) {
+  if (!entry || typeof entry !== 'object') return { ok: false, error: 'not a table' };
+  if (!String(entry.prompt || '').trim()) return { ok: false, error: 'prompt is required' };
+  try {
+    parseCron(entry.cron || entry.at);
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+  return { ok: true, error: '' };
+}
+
+/** Normalise the config table into a list with stable ids. */
+export function listSchedules(schedule) {
+  const table = schedule && typeof schedule === 'object' ? schedule : {};
+  return Object.entries(table).map(([id, e]) => ({
+    id,
+    cron: String((e && (e.cron || e.at)) || '').trim(),
+    prompt: String((e && e.prompt) || ''),
+    enabled: !(e && e.enabled === false),
+    cwd: (e && e.cwd) || '',
+    lastRun: (e && e.last_run) || null,
+    valid: validateEntry(e).ok,
+    error: validateEntry(e).error,
+  }));
+}
+
+/**
+ * Which entries are DUE now.
+ *
+ * The rule is "the schedule matches this minute and it has not already run in this
+ * minute". Both halves matter: a timer that ticks twice within one minute (which
+ * happens when the process was busy, or when the tick lands on a minute boundary)
+ * must not fire the same entry twice, and a session that was closed over the due
+ * minute must not fire a burst of catch-up prompts on the next launch — a schedule
+ * is not a queue of missed work.
+ */
+export function dueSchedules(schedule, now) {
+  const d = now || new Date();
+  const minuteKey = `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}T${d.getHours()}:${d.getMinutes()}`;
+  const out = [];
+  for (const e of listSchedules(schedule)) {
+    if (!e.enabled || !e.valid) continue;
+    let matcher;
+    try { matcher = parseCron(e.cron); } catch { continue; }
+    if (!matcher.matches(d)) continue;
+    if (e.lastRun === minuteKey) continue;
+    out.push({ ...e, minuteKey });
+  }
+  return out;
+}
+
+/**
+ * The schedule table with the given entries marked as run in this minute.
+ *
+ * Kept for callers that keep their history IN the config (the panel shows it either
+ * way); the TUI uses the side file (see writeHistory) because rewriting the user's
+ * whole config.toml once a minute is not acceptable.
+ */
+export function markRun(schedule, ids, minuteKey) {
+  const out = { ...(schedule && typeof schedule === 'object' ? schedule : {}) };
+  for (const id of ids) {
+    if (!out[id]) continue;
+    out[id] = { ...out[id], last_run: minuteKey };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Run history
+// ---------------------------------------------------------------------------
+// `last_run` cannot live in config.toml: the schedules are HAND-WRITTEN tables, and
+// rewriting that file on every fire is both risky (it holds the user's whole
+// configuration) and wrong in kind (a run record is state, not configuration). So the
+// history is a separate small JSON file beside the config, keyed by entry id.
+//
+// It is also what makes "once per due minute" survive a RESTART: without a record on
+// disk, a session closed and reopened within the same minute would fire the entry a
+// second time.
+
+/** Where the run history lives — beside the config, so a test HOME gets its own. */
+export function historyFile(configFile) {
+  return path.join(path.dirname(String(configFile)), 'schedule-state.json');
+}
+
+/** Read the run history. A missing or corrupt file reads as empty; never throws. */
+export function readHistory(configFile) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(historyFile(configFile), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch { return {}; }
+}
+
+/** Write the run history. Best-effort: a failed write must not drop the work. */
+export function writeHistory(configFile, history) {
+  try {
+    fs.mkdirSync(path.dirname(historyFile(configFile)), { recursive: true });
+    fs.writeFileSync(historyFile(configFile), JSON.stringify(history, null, 2) + '\n', 'utf8');
+    return true;
+  } catch { return false; }
+}
+
+/** `2026-9-30T9:5` — LOCAL time, since a cron expression is local by definition. */
+export function minuteKeyOf(d) {
+  return `${d.getFullYear()}-${d.getMonth() + 1}-${d.getDate()}T${d.getHours()}:${d.getMinutes()}`;
+}
+
+/**
+ * Which entries are due, consulting BOTH the config and the persisted history.
+ *
+ * Kept beside `dueSchedules` rather than replacing it, so the pure matching rule stays
+ * testable without a filesystem.
+ */
+export function dueWithHistory(schedule, history, now) {
+  const d = now || new Date();
+  const minuteKey = minuteKeyOf(d);
+  const out = [];
+  for (const e of listSchedules(schedule)) {
+    if (!e.enabled || !e.valid) continue;
+    let matcher;
+    try { matcher = parseCron(e.cron); } catch { continue; }
+    if (!matcher.matches(d)) continue;
+    const last = (history && history[e.id]) || e.lastRun || '';
+    if (last === minuteKey) continue;
+    out.push({ ...e, minuteKey });
+  }
+  return out;
+}
+
+/** Panel lines for /schedule — history included when it is available. */
+export function describeSchedules(schedule, history) {
+  const rows = listSchedules(schedule);
+  if (!rows.length) {
+    return [
+      'No schedules. Add one to config.toml:',
+      '',
+      '  [schedule.morning]',
+      '  cron = "0 9 * * 1-5"           # weekdays at 09:00',
+      '  prompt = "Check the open PRs and post a summary"',
+      '  enabled = true                  # optional, default true',
+    ].join('\n');
+  }
+  return rows.map((e) => {
+    const state = !e.enabled ? 'off' : e.valid ? 'on ' : 'BAD';
+    const when = e.valid ? describeCron(e.cron) : `INVALID: ${e.error}`;
+    const last = (history && history[e.id]) || e.lastRun || '';
+    return `${state} ${e.id.padEnd(16)} ${when.padEnd(26)} ${e.prompt.slice(0, 44)}${last ? `  last ${last}` : ''}`;
+  }).join('\n');
+}
+
+export default {
+  parseCron, describeCron, validateEntry, listSchedules, dueSchedules, markRun,
+  describeSchedules, dueWithHistory, readHistory, writeHistory, historyFile, minuteKeyOf,
+};

package/src/session-approvals.js

@@ -0,0 +1,86 @@
+// Session approval memory — "always allow this, for now".
+//
+// The permission RULES in config.toml are the durable answer ("allow npm test
+// forever"). This module is the transient one: the user is mid-task, a prompt
+// appears for something they already decided about five minutes ago, and they want
+// it gone without editing a file. kimi has exactly this as one of its permission
+// policies (`session-approval-history`), evaluated AFTER the configured rules so a
+// rule always wins.
+//
+// Scope rules, all of which exist to keep the memory from being a surprise:
+//   * The entry lives on the SESSION object, not on config — it dies with the
+//     session. A persisted grant would silently apply to next week's work.
+//   * It is keyed by the SHAPE of the call, not the call: for a command, the
+//     PROGRAM plus its first argument (`npm test`), so `npm test --watch` is
+//     covered but `npm publish` is not.
+//   * It never covers a destructive command, whatever the user approved. Ctrl+A on
+//     `rm -rf /build` must not pre-approve the next `rm -rf /`. This is the one
+//     place the module refuses to be literal about what was approved.
+//   * It cannot override a `deny` rule: the rule check runs first (see the caller).
+
+/**
+ * The key an approval is remembered under.
+ *
+ * For a shell command: the program and its first non-flag argument. That is the
+ * narrowest unit that is still useful — `npm test` covers `npm test --watch` and
+ * `npm test src/a.test.ts`, while `npm run` stays separate from `npm test`.
+ *
+ * For anything else: the tool name alone. A file tool's approval is about the TOOL
+ * (the path guard still applies per call), and keying by path would produce a new
+ * entry per file with no benefit.
+ */
+export function approvalKey(toolName, args) {
+  const tool = String(toolName || '');
+  if (tool !== 'Bash') return tool;
+  const cmd = String((args && (args.command || args.cmd)) || '').trim();
+  if (!cmd) return tool;
+  const words = cmd.split(/\s+/).filter(Boolean);
+  // Skip a leading assignment (`FOO=1 npm test`) — it is not the program.
+  const prog = words.find((w) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) || '';
+  if (!prog) return tool;
+  const sub = words.slice(words.indexOf(prog) + 1).find((w) => !w.startsWith('-')) || '';
+  return sub ? `${tool}:${prog} ${sub}` : `${tool}:${prog}`;
+}
+
+/** A label for the transcript, e.g. `Bash: npm test` or `Write`. */
+export function sessionApprovalLabel(toolName, args) {
+  return approvalKey(toolName, args);
+}
+
+/**
+ * Was this call approved for the session? `destructive` is the caller's verdict on
+ * the command; a true value always returns false, so the memory cannot pre-approve
+ * something that was judged too dangerous to run unattended.
+ */
+export function isApprovedForSession(list, toolName, args, destructive = false) {
+  if (destructive) return false;
+  const key = approvalKey(toolName, args);
+  if (!key) return false;
+  return Array.isArray(list) && list.includes(key);
+}
+
+/** Add a key to the list (returning a new array; no duplicates). */
+export function rememberApproval(list, toolName, args) {
+  const key = approvalKey(toolName, args);
+  const cur = Array.isArray(list) ? list : [];
+  if (!key || cur.includes(key)) return cur.slice();
+  return [...cur, key];
+}
+
+/** Drop one key. */
+export function forgetApproval(list, key) {
+  return (Array.isArray(list) ? list : []).filter((k) => k !== key);
+}
+
+/** Panel lines for /permissions, so the grants are visible and revocable. */
+export function describeSessionApprovals(list) {
+  const arr = Array.isArray(list) ? list : [];
+  if (!arr.length) return 'No session approvals. Ctrl+A on a prompt remembers one.';
+  return ['Approved for this session (cleared when the session ends):']
+    .concat(arr.map((k) => '  ' + k)).join('\n');
+}
+
+export default {
+  approvalKey, sessionApprovalLabel, isApprovedForSession,
+  rememberApproval, forgetApproval, describeSessionApprovals,
+};

package/src/session-hub.js

@@ -168,6 +168,7 @@ export class SessionHub {
       dispatch: null,      // async (cmd, arg) => void      — slash commands
       interrupt: null,     // async () => void
       approve: null,       // async (id, ok) => void        — answer an approval
+      answerPlan: null,    // async (id, outcome) => void   — answer a Plan-mode review
       answerQuestion: null,// async (id, answers) => void   — AskUserQuestion
       stopTask: null,      // async (taskId) => void
       setMode: null,       // async (mode) => void

package/src/session.js

@@ -92,6 +92,13 @@ export function convRowFor(m) {
 // `"messages"` key, so a session whose updatedAt sits after the transcript
 // would report updatedAt = 0 and the session list / --continue would sort
 // wrongly (or pick the wrong session). Key order here is authoritative.
+//
+// `transcript` goes LAST — after `messages`, not merely after the metadata block.
+// It is the one value here with no size limit: every persisted reasoning block is
+// stored whole, and the head reader gives up after META_MAX_BYTES. Written ahead of
+// `messages` a multi-megabyte `transcript` pushed the key out of reach and the session
+// became unlistable, which is what made intact conversations vanish from /sessions.
+// Behind `messages` the reader never has to cross it.
 function serializableSession(session) {
   const out = {};
   out.id = session.id;
@@ -100,15 +107,16 @@ function serializableSession(session) {
   out.model = session.model || '';
   out.createdAt = session.createdAt || Date.now();
   out.updatedAt = Date.now();
-  // Everything else (messages, rounds, steps, plan, focus, swarm, effort, …)
-  // is copied AFTER updatedAt. `messages` in particular must come after the
-  // metadata block.
+  // Everything else (rounds, steps, plan, focus, swarm, effort, …) is copied AFTER
+  // updatedAt. `messages` and `transcript` in particular must come after the metadata
+  // block, and they are appended below in that order.
   for (const k of Object.keys(session)) {
     if (k in out) continue;
-    if (k === 'messages') continue;   // handled below, last
+    if (k === 'messages' || k === 'transcript') continue;
     out[k] = session[k];
   }
   out.messages = Array.isArray(session.messages) ? session.messages : [];
+  if (Array.isArray(session.transcript)) out.transcript = session.transcript;
   return out;
 }
 
@@ -122,23 +130,43 @@ export function saveSession(session, storeDir) {
     // FIX: unique temp name so two concurrent saves of the same session cannot
     // clobber each other's temp file mid-write.
     const tmp = `${target}.${process.pid}.${crypto.randomBytes(3).toString('hex')}.tmp`;
-    const json = JSON.stringify(serializableSession(session), null, 2);
+    // Compact JSON, no indentation. `null, 2` made the file ~30% larger for a
+    // human who never reads it (the reader is JSON.parse), and the pretty-printer
+    // itself costs real time on a large transcript — measured ~22ms for 5.7MB, all
+    // of it spent inserting whitespace. Saving is on the per-turn path.
+    const json = JSON.stringify(serializableSession(session));
     fs.writeFileSync(tmp, json, 'utf8');
     // Atomic replace. If this throws (EXDEV etc.) the temp is cleaned up below.
     fs.renameSync(tmp, target);
-    // The saved transcript changed, so its cached metadata head is stale. Drop
-    // just this entry; the next scan re-reads the file (cheap, one file).
     cacheFor(storeDir, false)?.delete(sessionFile(session.id, storeDir));
+    // A save that worked clears any earlier failure, so /save-report speaks about the
+    // CURRENT state rather than a problem the user already resolved by being told.
+    saveFailure = null;
   } catch (e) {
     // FIX: never fail silently. Previously an empty catch {} in the TUI meant a
     // serialization error (circular ref, disk full, permissions) lost the turn
     // with no signal at all.
-    logSessionError('save', `${session.id}: ${e && e.message ? e.message : String(e)}`);
+    const detail = e && e.message ? e.message : String(e);
+    logSessionError('save', `${session.id}: ${detail}`);
+    // The log alone was not enough. A session whose transcript had grown past the V8
+    // string limit failed EVERY save for an hour and a half — the turn was lost each
+    // time and all the file recorded was `Invalid string length`, in a log nobody opens.
+    // The flag is what lets the TUI say so out loud; this module never reaches into the UI.
+    if (!saveFailure) saveFailure = { at: Date.now(), id: session.id, detail };
     return session;
   }
   return session;
 }
 
+// The most recent save failure, or null. Set once per failure so a caller can report it
+// (the TUI shows a warning) without this module reaching into the UI.
+let saveFailure = null;
+
+/** The last save failure `{ at, id, detail }`, or null when saving has been clean. */
+export function lastSaveFailure() { return saveFailure; }
+/** Clear the recorded failure, after a save has succeeded. */
+export function clearSaveFailure() { saveFailure = null; }
+
 export function loadSession(id, storeDir) {
   const file = sessionFile(id, storeDir);
   let text;
@@ -288,6 +316,21 @@ function _readMetaOnce(file) {
         delete m.messages;
         return { meta: m, hasMessages: nonEmpty };
       } catch {
+        // Neither parse can work here, and the reason is structural rather than
+        // corrupt: the cap was hit before the `"messages"` key, so `text` stops
+        // inside some earlier value. That is what a session carrying a large
+        // `transcript` looked like while `serializableSession` wrote it ahead of
+        // `messages` — and returning null for it made the file UNLISTABLE, so a
+        // perfectly intact session silently disappeared from /sessions and from
+        // `--continue`. The metadata is all at the front and every field a listing
+        // needs is a top-level scalar, so read those directly instead of giving up.
+        const meta = scanMetaHead(text);
+        // `hasMessages` is taken as true here on purpose. Reaching the cap without
+        // seeing the `"messages"` key means some earlier value was megabytes long, and
+        // the only value that grows like that is a transcript — which a session only
+        // accumulates by having had a conversation. Reading it as empty instead would
+        // make `--continue --skipEmpty` pass over a session full of real work.
+        if (meta) return { meta, hasMessages: true };
         return null;
       }
     }
@@ -311,6 +354,133 @@ function findMessagesValueStart(text) {
   return i;   // may point at `[` (or be end-of-text; caller handles both)
 }
 
+// The metadata a LISTING needs, read out of a head that stopped mid-value.
+//
+// Only top-level keys are taken, and only while the scanner is at depth 1: a `"title"`
+// nested inside a todo or a transcript row must never be mistaken for the session's own.
+// The values pulled out are strings and numbers, so the scan can step over an oversized
+// value with `skipJsonValue` instead of trying to read it.
+const HEAD_SCALAR_KEYS = new Set([
+  'id', 'title', 'workspace', 'model', 'createdAt', 'updatedAt',
+  'rounds', 'steps', 'lastTurnMs', 'forkedFrom',
+]);
+
+function scanMetaHead(text) {
+  const out = {};
+  let depth = 0;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '{' || c === '[') { depth++; i++; continue; }
+    if (c === '}' || c === ']') { depth--; i++; continue; }
+    if (c !== '"') { i++; continue; }
+    const key = readJsonString(text, i);
+    if (!key) return Object.keys(out).length ? out : null;
+    i = key.end;
+    // Only a KEY of the root object counts, and only when a colon follows.
+    if (depth !== 1) {
+      const skip = skipJsonValue(text, i);
+      if (skip < 0) return Object.keys(out).length ? out : null;
+      i = skip;
+      continue;
+    }
+    let j = i;
+    while (j < text.length && /\s/.test(text[j])) j++;
+    if (text[j] !== ':') {
+      const skip = skipJsonValue(text, i);
+      if (skip < 0) return Object.keys(out).length ? out : null;
+      i = skip;
+      continue;
+    }
+    j++;
+    while (j < text.length && /\s/.test(text[j])) j++;
+    if (HEAD_SCALAR_KEYS.has(key.value)) {
+      if (text[j] === '"') {
+        const s = readJsonString(text, j);
+        if (!s) return Object.keys(out).length ? out : null;
+        out[key.value] = s.value;
+        i = s.end;
+      } else {
+        let k = j;
+        while (k < text.length && !',}]\n'.includes(text[k])) k++;
+        const n = Number(text.slice(j, k).trim());
+        if (Number.isFinite(n)) out[key.value] = n;
+        i = k;
+      }
+      continue;
+    }
+    const skip = skipJsonValue(text, j);
+    if (skip < 0) return Object.keys(out).length ? out : null;
+    i = skip;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+// A JSON string literal starting at `at` (which must be the opening quote), decoded.
+// Returns { value, end } with `end` past the closing quote, or null when the literal
+// runs off the end of `text` — the normal case for a value the head cap cut in half.
+function readJsonString(text, at) {
+  let i = at + 1;
+  let raw = '';
+  while (i < text.length) {
+    const c = text[i];
+    if (c === '\\') {
+      const n = text[i + 1];
+      if (n === undefined) return null;
+      if (n === 'u') {
+        const hex = text.slice(i + 2, i + 6);
+        if (hex.length < 4 || !/^[0-9a-fA-F]{4}$/.test(hex)) return null;
+        raw += String.fromCharCode(parseInt(hex, 16));
+        i += 6;
+        continue;
+      }
+      raw += n === 'n' ? '\n' : n === 't' ? '\t' : n === 'r' ? '\r' : n;
+      i += 2;
+      continue;
+    }
+    if (c === '"') return { value: raw, end: i + 1 };
+    raw += c;
+    i++;
+  }
+  return null;
+}
+
+// Step over one JSON value starting at `at`, returning the index just past it, or -1
+// when the value is not complete in `text`. Strings and containers are both handled, so
+// an oversized array is crossed without building it.
+function skipJsonValue(text, at) {
+  let i = at;
+  while (i < text.length && /\s/.test(text[i])) i++;
+  if (i >= text.length) return -1;
+  const c = text[i];
+  if (c === '"') {
+    const s = readJsonString(text, i);
+    return s ? s.end : -1;
+  }
+  if (c === '{' || c === '[') {
+    let depth = 0;
+    for (; i < text.length; i++) {
+      const ch = text[i];
+      if (ch === '"') {
+        const s = readJsonString(text, i);
+        if (!s) return -1;
+        i = s.end - 1;
+        continue;
+      }
+      if (ch === '{' || ch === '[') depth++;
+      else if (ch === '}' || ch === ']') {
+        depth--;
+        if (depth === 0) return i + 1;
+      }
+    }
+    return -1;
+  }
+  // A literal (number, true/false/null): up to the next delimiter.
+  let k = i;
+  while (k < text.length && !',}]'.includes(text[k])) k++;
+  return k > i ? k : -1;
+}
+
 // Non-empty detection now lives in _readMetaOnce (it reads the file head once
 // for both the metadata and the emptiness rule), so the old separate
 // hasMessages() scan is gone — latestSession no longer reopens each candidate.