@lincoln504/pi-research 1.6.2 → 1.6.3

package/README.md

@@ -63,11 +63,10 @@ Three depth levels (normal, deep, ultra) set the team size and number of rounds.
 - Keeping a persistent and searchable knowledge store of findings, scoped globally or per project.
 - Building agent systems that find and read web content, or populating a dataset of web sources.
 
-### Why pi-research
+### Why
 
 - **No quota and no monthly fee.** Most AI search providers cap free searches and then charge, with results served from their index on their servers. pi-research searches and scrapes locally through DuckDuckGo in a stealth browser.
 - **The index is local.** Every finding can be saved to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
-- **Cited reports rather than raw dumps.** Each run returns one sourced Markdown report instead of raw web content pasted into the conversation. Context efficient and easy to verify.
 - **Read-only by design.** The research agent cannot run shell commands or write, edit, or delete anything — the right shape for an agent whose whole job is reading untrusted web pages. Prompt injection picked up mid-run has nothing to act on.
 - **Search a little or a lot.** Depth levels range from a quick pass to a large-scale investigation.
 

package/agent-skill/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.6.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.6.3", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 

package/dist/cli.mjs

@@ -6831,7 +6831,7 @@ var init_file_lock_service = __esm({
                 const errnoError = error;
                 if (errnoError.code === "EEXIST") {
                   contentionCount++;
-                  let reclaimEligibleAt = null;
+                  let awaitingReclaim = false;
                   try {
                     const rawContent = await fs7.readFile(this.lockFilePath, "utf-8");
                     const parsed = this._parseLockContent(rawContent);
@@ -6843,7 +6843,7 @@ var init_file_lock_service = __esm({
                     }
                     lastSeenUuid = lockUuid;
                     lastSeenMtime = stats.mtimeMs;
-                    reclaimEligibleAt = (parsed?.pid ?? null) === null ? stats.mtimeMs + this._unidentifiedStaleThreshold() : null;
+                    awaitingReclaim = this.lockTimeout > 0 && (parsed?.pid ?? null) === null && lockAge <= this._unidentifiedStaleThreshold();
                     if (lockUuid === this.lockUuid) {
                       try {
                         await fs7.unlink(this.lockFilePath);
@@ -6880,7 +6880,6 @@ var init_file_lock_service = __esm({
                   }
                   const stalledFor = Date.now() - lastProgressAt;
                   const waitedFor = Date.now() - startTime;
-                  const awaitingReclaim = this.lockTimeout > 0 && reclaimEligibleAt !== null && Date.now() < reclaimEligibleAt;
                   if (stalledFor >= this.lockTimeout && !awaitingReclaim || waitedFor >= this.acquireCeilingMs) {
                     metrics.observe("state_lock_acquire_duration_ms", waitedFor, { status: "timeout" });
                     metrics.increment("state_lock_acquire_total", 1, { status: "timeout" });

package/docs/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.3] - 2026-08-25
+
+A unit test that had already been granted CI-jitter headroom twice went red a third
+time — and this time the timing signature (rejection 10008ms into a 10000ms window)
+identified a real race in the lock acquire loop rather than a slow runner.
+
+### Fixed
+
+- **A waiter gave up on a torn lock at the exact moment its reclaim window opened.** The acquire loop's reclaim decision measures the lock's age at `fs.stat` time, but the stall-check exemption that keeps a waiter alive until that reclaim ("never give up on a lock we are about to be allowed to take") compared a fresh `Date.now()` against the window. For the few milliseconds between the stat and the stall check the two clocks could disagree, and a retry tick landing astride the window boundary satisfied neither: not yet reclaimable by its stat, no longer awaited by the clock. Since a torn, pid-less lock never shows progress, the long-expired stall bound then fired, and a wait that had correctly outlasted it was abandoned right as the recovery became permitted — in production, a knowledge-store init failing at the moment it could have recovered. Both judgments now derive from the same observation, so every tick that can read the lock either reclaims it or keeps waiting; the try-take exclusion and the absolute ceiling are unchanged (`src/infrastructure/file-lock-service.ts`).
+- **The test's forensic comment blamed scheduler jitter for all three CI failures.** True for the first two (which failed at the stall bound); wrong for this one (which failed at the window boundary). The record now distinguishes the two mechanisms (`test/unit/infrastructure/file-lock-progress-aware-wait.test.ts`).
+- **A browser-config test deleted the whole suite's shared log directory as its own cleanup.** `unit-env.ts` routes every unit worker's log into `<tmpdir>/pi-research-test/`; the profile-containment test nested its scratch path inside that directory and removed the shared parent recursively — destroying the live log out from under every parallel worker, and racing the lazy logger re-creating the file mid-removal, which is an `ENOTEMPTY` crash of the cleanup itself (seen on macos-latest CI on this release's first tag). The test now creates its own `mkdtemp` directory and removes only that (`test/unit/infrastructure/browser-config.test.ts`).
+
+### Verified
+
+- 2938 unit tests over 233 files, lint, type-check, and the full CI matrix green on the fix commit — including the ubuntu-latest job that caught the failure.
+
 ## [1.6.2] - 2026-08-24
 
 An agent-skill run reported that every search had failed and concluded it had hit an

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "Web research for your agents with smart and safe tooling + knowledge store",
   "type": "module",
   "private": false,

package/src/infrastructure/file-lock-service.ts

@@ -694,12 +694,13 @@ export class FileLockService implements IService {
             const errnoError = error as NodeJS.ErrnoException;
             if (errnoError.code === 'EEXIST') {
               contentionCount++;
-              // When the contended lock becomes eligible for reclaim, if this tick can
-              // know it. Scoped per observation: a tick that could not read the lock
+              // Whether THIS tick judged the contended lock not-yet-eligible for the
+              // pid-less reclaim — i.e. we are waiting for a recovery we will be allowed
+              // to perform. Scoped per observation: a tick that could not read the lock
               // learned nothing, and an eligibility carried over from an earlier one is
               // no longer evidence of anything. See the stall check below for why the
               // stall bound must not fire before this moment.
-              let reclaimEligibleAt: number | null = null;
+              let awaitingReclaim = false;
               // Read lock content to verify ownership and liveness before considering stale
               try {
                 const rawContent = await fs.readFile(this.lockFilePath, 'utf-8');
@@ -720,17 +721,26 @@ export class FileLockService implements IService {
                 // A lock with no readable pid is judged purely on age (see
                 // _shouldReclaim), and its mtime never moves again — so it can never
                 // show progress and the stall bound is guaranteed to expire first.
-                // Record when it becomes reclaimable so the wait below can outlast the
-                // stall bound rather than abandoning the recovery at 20s.
+                // Mark this tick as awaiting that reclaim so the wait below can outlast
+                // the stall bound rather than abandoning the recovery at 20s.
+                //
+                // Judged from the SAME lockAge observation _shouldReclaim will use, not
+                // from a fresh Date.now() at the stall check: the two clocks disagreed
+                // for the few ms between the stat and that check, and a tick landing
+                // astride the window boundary judged the lock not-yet-reclaimable here
+                // yet no-longer-awaited there — giving up at the exact moment the
+                // window opened (ubuntu CI, 2026-08-24: rejected 10008ms into a
+                // 10000ms window). The complement of _shouldReclaim's strict > means
+                // one of the two branches now holds on every readable tick.
                 //
                 // Deliberately NOT extended to a live owner: there the heartbeat is the
                 // designed progress signal, its absence past lockTimeout is real evidence
                 // of a wedge, and reporting that to the caller promptly beats waiting out
                 // a two-to-four-minute live-owner threshold on a lock we may well never
                 // be handed.
-                reclaimEligibleAt = (parsed?.pid ?? null) === null
-                  ? stats.mtimeMs + this._unidentifiedStaleThreshold()
-                  : null;
+                awaitingReclaim = this.lockTimeout > 0
+                  && (parsed?.pid ?? null) === null
+                  && lockAge <= this._unidentifiedStaleThreshold();
 
                 if (lockUuid === this.lockUuid) {
                   // This is our own lock — a previous attempt was interrupted. Reclaim.
@@ -802,8 +812,6 @@ export class FileLockService implements IService {
               // on the spot rather than wait for anything, and the run semaphore's slot
               // files carry a TEN-MINUTE unidentified window, so honouring eligibility
               // there would turn "is this slot free right now" into a ten-minute block.
-              const awaitingReclaim =
-                this.lockTimeout > 0 && reclaimEligibleAt !== null && Date.now() < reclaimEligibleAt;
               if ((stalledFor >= this.lockTimeout && !awaitingReclaim) || waitedFor >= this.acquireCeilingMs) {
                 metrics.observe('state_lock_acquire_duration_ms', waitedFor, { status: 'timeout' });
                 metrics.increment('state_lock_acquire_total', 1, { status: 'timeout' });