@dtlabs/ai-toolkit 0.17.2 → 0.17.3

package/CHANGELOG.md

@@ -1,4 +1,13 @@
 ## 0.1.4 (2026-07-21)
+## [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 || [];

package/package.json

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