@dtlabs/ai-toolkit 0.17.2 → 0.17.4

package/CHANGELOG.md

@@ -1,4 +1,21 @@
 ## 0.1.4 (2026-07-21)
+## [0.17.4](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.3...v0.17.4) (2026-10-13)
+
+
+### Bug Fixes
+
+* **workflow-control:** repair unescaped control chars in recovered JSON ([ebeddb5](https://github.com/dtlab-tech/ai-toolkit/commit/ebeddb5465ac988f94bd28d20b7f9dfdd967c2c9))
+* **workflow-control:** repair unescaped control chars in recovered JSON ([0ce2466](https://github.com/dtlab-tech/ai-toolkit/commit/0ce24666b6d4d09b25ca71b1ed3b9f0ba7c06d7a))
+
+## [0.17.3](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.2...v0.17.3) (2026-10-12)
+
+
+### Bug Fixes
+
+* **execution-ledger:** close PID-reuse gap in lock-staleness liveness check ([4a9a365](https://github.com/dtlab-tech/ai-toolkit/commit/4a9a3652bf8e7844accff46851b2e1286e24c0d7))
+* **task-executor:** session-list clutter and PID-reuse lock-liveness gap ([e000a6f](https://github.com/dtlab-tech/ai-toolkit/commit/e000a6faa2e75eac5bb65069eb9b37b102a14cf8))
+* **task-executor:** stop every dispatch from cluttering the Claude Code session list ([8676d66](https://github.com/dtlab-tech/ai-toolkit/commit/8676d66157bceeafb7fa225cabeb8a666dbac955))
+
 ## [0.17.2](https://github.com/dtlab-tech/ai-toolkit/compare/v0.17.1...v0.17.2) (2026-10-12)
 
 

package/lib/execution-ledger.js

@@ -4,6 +4,10 @@ const fs     = require('fs');
 const path   = require('path');
 const os     = require('os');
 const crypto = require('crypto');
+// Namespaced (not destructured) so tests can jest.spyOn(ownership, '_queryProcessStartTimeSync')
+// — a destructured reference would capture the original function at require
+// time and bypass any later spy on the module's own export.
+const ownership = require('./task-executor/ownership');
 
 // ── Internal I/O helpers (stubs — implemented by INFRA-TASK-BE-03) ──────────
 
@@ -131,6 +135,78 @@ function _sleepSync(ms) {
   while (Date.now() < end) { /* busy-wait for synchronous cross-process backoff */ }
 }
 
+// This process's own OS-level start time, probed via ownership.js's
+// host:pid:startTime technique exactly ONCE per process lifetime (not once
+// per lock acquisition) and cached forever after — a process's own start
+// time never changes. Recording this in every lock token we write is what
+// later lets a CONTENDED acquisition attempt tell "the recorded owner is
+// still running" apart from "a recycled pid now belongs to someone else"
+// (see _confirmSameOwnerProcess). `undefined` means not yet probed;
+// `null` means the probe was inconclusive (non-Windows, or it failed) —
+// callers must treat that the same as "no evidence either way", never as
+// proof of death.
+let _selfProcessStartTime;
+function _getSelfProcessStartTime() {
+  if (_selfProcessStartTime === undefined) {
+    const probe = ownership._queryProcessStartTimeSync(process.pid);
+    _selfProcessStartTime = (probe && probe.found) ? probe.startTime : null;
+  }
+  return _selfProcessStartTime;
+}
+
+// Per-nonce verdict cache for the PID-reuse check below. A lock's nonce is
+// unique per acquisition (crypto.randomBytes at write time), so a verdict
+// for a given nonce never goes stale: either the recorded owner is
+// confirmed still the same OS process (forever, until it exits), or it was
+// already confirmed to be a different process that reused the pid
+// (forever — that fact doesn't change either). Caching here is what keeps
+// the expensive OS probe to once per contended lock episode instead of once
+// per ~100ms poll in _acquireLock's retry loop. Bounded defensively; a
+// single process is not expected to ever accumulate more than a handful of
+// distinct contended nonces in practice.
+const _ownerProcessVerdictCache = new Map();
+
+// Resolves whether `token.pid` is still the SAME OS process that wrote this
+// lock, using the host:pid:startTime identity technique (same one
+// ownership.js already uses for task leases) — `process.kill(pid, 0)` alone
+// cannot tell a still-alive original owner apart from an unrelated process
+// that reused a recycled pid after the owner crashed.
+//
+// Returns:
+//   true  — confirmed same process (startTime probes match)
+//   false — confirmed a DIFFERENT process now holds this pid (mismatch)
+//   null  — inconclusive (non-Windows, probe failed, or token predates this
+//           field) — caller must fall back to trusting process.kill() alone,
+//           exactly like before this check existed; never treated as death.
+function _confirmSameOwnerProcess(token) {
+  if (typeof token.processStartTime !== 'string' || !token.nonce) return null;
+
+  const cached = _ownerProcessVerdictCache.get(token.nonce);
+  if (cached !== undefined) return cached;
+
+  const probe = ownership._queryProcessStartTimeSync(token.pid);
+  // Inconclusive probe (non-Windows, or the query failed) or the OS
+  // confirms no such pid despite process.kill() saying alive (a narrow
+  // race): do not cache — there is nothing stable to remember, and a
+  // later retry might get a conclusive answer.
+  if (!probe) return null;
+  if (!probe.found) return null;
+
+  const verdict = probe.startTime === token.processStartTime;
+  if (_ownerProcessVerdictCache.size > 500) _ownerProcessVerdictCache.clear();
+  _ownerProcessVerdictCache.set(token.nonce, verdict);
+  return verdict;
+}
+
+// Test-only reset: both caches are intentionally process-lifetime-scoped in
+// production (see their own comments for why), which would otherwise leak
+// a mocked _queryProcessStartTimeSync's behavior across unrelated test cases
+// sharing the same Jest worker process.
+function _resetOwnerProcessCaches() {
+  _selfProcessStartTime = undefined;
+  _ownerProcessVerdictCache.clear();
+}
+
 function _acquireLock(lockPath, opts) {
   const deadlineMs = (opts && opts.deadlineMs != null) ? opts.deadlineMs : 5000;
   const retryIntervalMs = (opts && opts.retryIntervalMs != null) ? opts.retryIntervalMs : 100;
@@ -142,7 +218,12 @@ function _acquireLock(lockPath, opts) {
       fd = fs.openSync(lockPath, 'wx');
       const nonce = crypto.randomBytes(16).toString('hex');
       const startedAt = new Date().toISOString();
-      const ownerToken = { pid: process.pid, startedAt, nonce };
+      // processStartTime: this process's own OS start time (cached once per
+      // process lifetime, see _getSelfProcessStartTime) — null on non-Windows
+      // or when the probe is unavailable, matching ownership.js's own
+      // null-means-inconclusive convention. Lets a later contended acquirer
+      // tell "still us" apart from "a recycled pid, now someone else".
+      const ownerToken = { pid: process.pid, startedAt, nonce, processStartTime: _getSelfProcessStartTime() };
       fs.writeSync(fd, JSON.stringify(ownerToken));
       fs.fsyncSync(fd);
       fs.closeSync(fd);
@@ -270,7 +351,15 @@ function _isLockStale(content, stat) {
       }
     }
 
-    if (ownerAlive) {
+    // process.kill(pid, 0) alone cannot tell a still-alive original owner
+    // apart from an unrelated process that reused a recycled pid after the
+    // owner crashed. _confirmSameOwnerProcess returns false only when it has
+    // positive OS evidence that today's occupant of this pid started at a
+    // different time than the token recorded — a confirmed PID reuse, not a
+    // guess. true or null (inconclusive) both fall through to the original
+    // "trust process.kill()" behavior, so nothing regresses on non-Windows
+    // or for locks written before this field existed.
+    if (ownerAlive && _confirmSameOwnerProcess(token) !== false) {
       return 'live';
     }
 
@@ -827,6 +916,9 @@ module.exports = {
   _acquireLock,
   _releaseLock,
   _isLockStale,
+  _confirmSameOwnerProcess,
+  _getSelfProcessStartTime,
+  _resetOwnerProcessCaches,
   _validateMetadata,
   _extractStoredMetadata,
   _metadataEqual,

package/lib/task-executor/index.js

@@ -600,9 +600,16 @@ async function dispatchTaskAttempt(args) {
 
   // 4. Only now: dispatch the verified agent.
   const prompt = typeof args.prompt === 'string' ? args.prompt : _buildTaskPrompt(task);
+  // --no-session-persistence: this dispatch is a one-shot --print invocation
+  // that is never resumed (no code path in this codebase passes --resume /
+  // --continue / --session-id for a task-executor spawn; replan/resume
+  // re-dispatch with a fresh prompt, never reattach to a prior Claude
+  // conversation), so a saved, resumable session transcript has no purpose
+  // here — only cost: every dispatch would otherwise accumulate as its own
+  // entry in the user's Claude Code session list.
   const baseSpawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
-    : ['--print', '--output-format', 'json', '--agent', identity.nativeName].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
+    : ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
   // Append the same processIdentity tag already persisted above as one extra
   // trailing argv element, so it appears verbatim in the spawned process's
   // own command line — this is what makes _findLiveTaggedProcess's later OS
@@ -905,7 +912,7 @@ async function runReview(args) {
   const prompt = _buildReviewPrompt(task, diff);
   const spawnArgs = Array.isArray(args.spawnArgs)
     ? args.spawnArgs
-    : ['--print', '--output-format', 'json', '--agent', identity.nativeName].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
+    : ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'].concat(EXECUTOR_PERMISSION_BYPASS_ARGS);
   const spawnResult = await claudeProcess.spawnClaudeAgent({
     claudePath: args.claudePath,
     args: spawnArgs,

package/lib/task-executor/ownership.js

@@ -587,4 +587,10 @@ module.exports = {
   reclaimLease,
   checkOwnerLiveness,
   createOwnershipGuard,
+  // Exported for execution-ledger.js's lock-staleness check (US-xx liveness
+  // parity): the same host:pid:startTime identity technique proven here is
+  // the only reliable defense against a recycled PID being misread as the
+  // original lock owner. See execution-ledger.js's own comment at its call
+  // site for why this is only invoked lazily/cached there, never per-poll.
+  _queryProcessStartTimeSync,
 };

package/lib/workflow-control.js

@@ -139,7 +139,12 @@ function createControl(options) {
     const identity = await resolve(id);
     const definition = definitionFields(read(identity.path));
     return activity(opts.label || id, async () => {
-      const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName];
+      // --no-session-persistence: this worker call is a one-shot --print
+      // invocation that is never resumed, so a saved session transcript has
+      // no purpose — only cost, accumulating as a stray entry in the user's
+      // Claude Code session list (see lib/task-executor/index.js's dispatch
+      // call sites for the same reasoning).
+      const cliArgs = ['--print', '--output-format', 'json', '--agent', identity.nativeName, '--no-session-persistence'];
       if (opts.schema) cliArgs.push('--json-schema', JSON.stringify(opts.schema));
       if (options.workerMaxBudgetUsd != null) cliArgs.push('--max-budget-usd', String(options.workerMaxBudgetUsd));
       const outputs = opts.outputs || [];
@@ -300,6 +305,41 @@ function createControl(options) {
   return api;
 }
 
+// A model asked to emit a JSON blob as part of a chat reply (rather than through a real
+// serializer, i.e. whenever structured_output didn't get populated and extraction has to
+// recover the payload from free text) is prone to one specific, well-understood defect: a
+// long free-text field (a "report") gets its literal line breaks typed as real newlines
+// instead of the required `\n` escape. The JSON otherwise reads as entirely correct to a
+// human, but JSON.parse rejects it outright ("Bad control character in string literal") —
+// confirmed against a real run where the model's JSON was discarded for exactly this reason
+// despite carrying the correct ```json fence tag and schema-correct structure. This is a
+// narrow, mechanical repair for that one defect, not a lenient parser: it tracks whether
+// each character lies inside a double-quoted JSON string literal (honoring \" and \\
+// escapes) and re-escapes a raw newline/CR/tab ONLY there, leaving structural whitespace
+// between tokens untouched. Applied as a fallback after a plain JSON.parse fails, never in
+// place of one, so already-valid JSON is never second-guessed.
+function _repairUnescapedControlCharsInStrings(text) {
+  let result = '';
+  let inString = false;
+  let escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escaped) { result += ch; escaped = false; }
+      else if (ch === '\\') { result += ch; escaped = true; }
+      else if (ch === '"') { result += ch; inString = false; }
+      else if (ch === '\n') { result += '\\n'; }
+      else if (ch === '\r') { result += '\\r'; }
+      else if (ch === '\t') { result += '\\t'; }
+      else { result += ch; }
+    } else {
+      if (ch === '"') inString = true;
+      result += ch;
+    }
+  }
+  return result;
+}
+
 // The model is not consistent about which delimiter it uses to mark its final structured
 // answer inside otherwise-free text — observed empirically, same agent and schema, run to
 // run: an <structured_output> tag, a ```json fence, and an unprompted <json> tag. Growing
@@ -327,8 +367,15 @@ function extractDelimitedStructuredOutput(text, schema) {
   const last = text.lastIndexOf('}');
   if (first !== -1 && last > first) candidates.push(text.slice(first, last + 1));
   for (const raw of candidates) {
+    const trimmed = raw.trim();
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (e) {
+      try { parsed = JSON.parse(_repairUnescapedControlCharsInStrings(trimmed)); }
+      catch (e2) { continue; }
+    }
     try {
-      const parsed = JSON.parse(raw.trim());
       validateSchema(parsed, schema);
       return parsed;
     } catch (e) { /* try the next candidate, or fall through to null */ }
@@ -349,7 +396,18 @@ function extractDelimitedStructuredOutput(text, schema) {
 // remains the one thing that fails closed on it; this function only undoes wrapping, it is not
 // itself a validation gate.
 function extractJsonDocument(text) {
-  const tryParse = candidate => { try { JSON.parse(candidate); return candidate; } catch (e) { return null; } };
+  // Same "try the candidate as-is, then try it with raw control characters inside
+  // string literals re-escaped" fallback as extractDelimitedStructuredOutput, and
+  // for the identical reason: a long free-text field (e.g. a task description)
+  // typed with literal line breaks instead of `\n` is otherwise indistinguishable
+  // from genuinely malformed JSON, even though it's one mechanical fix away from
+  // valid. Returns the (possibly repaired) STRING to write to disk, never the
+  // parsed object — this function's contract is text recovery, not parsing.
+  const tryParse = candidate => {
+    try { JSON.parse(candidate); return candidate; } catch (e) {}
+    const repaired = _repairUnescapedControlCharsInStrings(candidate);
+    try { JSON.parse(repaired); return repaired; } catch (e) { return null; }
+  };
   const whole = tryParse(text.trim());
   if (whole != null) return whole;
   const fenceMatches = [...text.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dtlabs/ai-toolkit",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "AI Toolkit — reusable agents and procedures for developers to build AI-powered applications.",
   "files": [
     "docs/",