#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix: handle slow worker startup across CLI paths (#1531)
Rohit Ghumare1c2f0ad9e236
diff --git a/.env.example b/.env.exampleindex ec8c26df..34dfc2ac 100644--- a/.env.example+++ b/.env.example@@ -166,6 +166,16 @@# AGENTMEMORY_DEBUG=1 # Trace MCP shim probe + standalone fallback decisions to stderr# AGENTMEMORY_FORCE_PROXY=1 # Skip the MCP shim livez probe and trust AGENTMEMORY_URL (for sandboxed MCP clients that can't reach localhost)# AGENTMEMORY_PROBE_TIMEOUT_MS=2000 # MCP shim livez probe timeout+# AGENTMEMORY_READY_TIMEOUT_MS=300000 # CLI worker readiness deadline, including state loading (5 minutes)+# AGENTMEMORY_ENGINE_READY_TIMEOUT_MS=120000 # CLI engine readiness deadline (2 minutes)+# Startup deadlines accept whole milliseconds from 1 to 3600000. Shell+# environment overrides this file. Engine and worker waits have separate+# budgets; Docker/orchestrator healthcheck grace must allow for both when+# increasing them for a slow store.+# AGENTMEMORY_ENGINE_MANAGES_WORKER=true # Custom engine config launches the worker through a wrapper+# Direct AgentMemory worker commands are detected automatically. Set true+# for custom launch wrappers so the CLI waits instead of starting a second+# worker; set false when custom exec jobs are unrelated to AgentMemory.# AGENTMEMORY_URL=http://localhost:3111 # REST base URL — honored by status, doctor, MCP shim# AGENTMEMORY_VIEWER_URL=http://localhost:3113 # Override the viewer URL printed by `agentmemory status`# Persistent iii state; same override as `--data-dir`, used by native anddiff --git a/.github/workflows/release-gate.yml b/.github/workflows/release-gate.ymlindex d7b15088..76abbffb 100644--- a/.github/workflows/release-gate.yml+++ b/.github/workflows/release-gate.yml@@ -44,10 +44,13 @@ jobs:node-version: 22- run: npm install --legacy-peer-deps --no-audit --no-fund- run: npm run release:gate -- --out "${{ runner.temp }}/release-gate"+ - run: npm run test:startup:packaged -- --skip-build --out "${{ runner.temp }}/startup-gate"- if: always()uses: actions/upload-artifact@v4with:name: release-gate-${{ matrix.os }}- path: ${{ runner.temp }}/release-gate+ path: |+ ${{ runner.temp }}/release-gate+ ${{ runner.temp }}/startup-gateif-no-files-found: ignoreretention-days: 14diff --git a/AGENTS.md b/AGENTS.mdindex 5250056f..6a0e85ff 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -101,7 +101,7 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).## Testing-- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (2,900+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.+- Before every commit run, in order: `npm run build`, `npm run skills:gen`, `npm run docs:sync`, `npm run skills:check`, `npm test` (3,000+ tests). Commit anything the generators changed. CI runs the same build, skills check and tests.- Before any npm publish: `npm run release:gate` must pass. It installs the packed tarballs into a clean home and runs capture, recovery, restart, export/import, MCP and status checks against the installed CLI (see CONTRIBUTING.md, Release process)- Mock pattern: `vi.mock("iii-sdk")` with mock `sdk.trigger`, `kv.get/set/list`- Test files go in `test/` with `.test.ts` extension@@ -114,4 +114,4 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).- 6 MCP resources, 3 MCP prompts- 12 hooks, 17 skills- 312+ iii functions-- 2,900+ tests+- 3,000+ testsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 6e58c49d..bd876ece 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -105,6 +105,8 @@ npm run release:gateIt builds, packs `@agentmemory/agentmemory` and `@agentmemory/mcp`, installs both tarballs into a fresh prefix with a clean `HOME`, starts the installed CLI on random free ports with a deterministic local embedding server (no API keys), and checks capture through the bundled hooks, offline capture and spool recovery, replay dedup after a force kill, dead letters across a restart, vector survival before the first checkpoint, `agentmemory stop` then start, export and import into a fresh home, the MCP entrypoints, and the viewer plus `/agentmemory/status`. It prints a pass or fail line per scenario and a JSON summary, writes logs and `summary.json` to the output directory it prints, and stops only the processes it started. To gate the exact file you will publish, pass it in: `npm pack` then `npm run release:gate -- --tarball agentmemory-agentmemory-<version>.tgz`, and publish that tarball. Do not publish when a scenario fails. The `Release gate` workflow runs the same script on Ubuntu and macOS for pull requests and pushes to main.+For startup changes, also run `npm run test:startup:packaged`. It installs the packed CLI in isolated homes and tests delayed workers, existing-engine adoption, `--no-engine`, doctor, demo, timeout failures and process cleanup. The default slow-worker case waits 48 seconds before importing the installed worker. Pass `--tarball <file.tgz>` to test an existing artifact. Run the standard release gate first to cache the pinned engine, or set `AGENTMEMORY_GATE_ENGINE` to that engine binary. Docker scenarios require a working Docker daemon; the report records unavailable Docker coverage explicitly.+Then: CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance (`@agentmemory/fs-watcher` versions independently from `integrations/filesystem-watcher/package.json`).## Security issuesdiff --git a/README.md b/README.mdindex b9802af2..9ae959fe 100644--- a/README.md+++ b/README.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tools.svg"><img src="assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-hooks.svg"><img src="assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-deps.svg"><img src="assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="assets/tags/light/stat-tests.svg"><img src="assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1450,7 +1450,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Custom plugin systems | `iii worker add <name>` |-**227 source files · ~54,000 LOC · 2,900+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.+**228 source files · ~54,000 LOC · 3,000+ tests · 312 functions · 62 KV scopes**, all on three primitives. No `agentmemory plugin install`. The plugin system is iii itself.---@@ -1882,7 +1882,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.ar-SA.md b/READMEs/README.ar-SA.mdindex 8d993342..3cbf2965 100644--- a/READMEs/README.ar-SA.md+++ b/READMEs/README.ar-SA.md@@ -73,7 +73,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1439,7 +1439,7 @@ fi| Prometheus / Grafana | OTEL في iii + مراقب الحالة الصحية || أنظمة إضافات مخصصة | `iii worker add <name>` |-**227 ملف مصدري · ~54,000 سطر برمجي · 2,900+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.+**228 ملف مصدري · ~54,000 سطر برمجي · 3,000+ اختبار · 312 دالة · 62 نطاق KV**، كل ذلك على ثلاث بنى أساسية. لا يوجد أمر `agentmemory plugin install`. نظام الإضافات هو iii نفسه.---@@ -1863,7 +1863,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.bn-BD.md b/READMEs/README.bn-BD.mdindex 625803cc..6e0576dd 100644--- a/READMEs/README.bn-BD.md+++ b/READMEs/README.bn-BD.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP টুল" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 অটো হুক" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 এক্সটার্নাল ডিবি" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ টেস্ট পাস" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ টেস্ট পাস" height="38" /></picture></p><p align="center">@@ -1437,7 +1437,7 @@ fi| Prometheus / Grafana | iii OTEL + হেলথ মনিটর || কাস্টম প্লাগইন সিস্টেম | `iii worker add <name>` |-**227 সোর্স ফাইল · ~54,000 LOC · 2,900+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।+**228 সোর্স ফাইল · ~54,000 LOC · 3,000+ টেস্ট · 312 ফাংশন · 62 KV স্কোপ**, সবকিছু তিনটি প্রিমিটিভের উপর। কোনো `agentmemory plugin install` নেই। প্লাগইন সিস্টেমটাই iii নিজে।---@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.cs-CZ.md b/READMEs/README.cs-CZ.mdindex fe64e766..c84d9b69 100644--- a/READMEs/README.cs-CZ.md+++ b/READMEs/README.cs-CZ.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP nástrojů" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatických hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externích databází" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testů úspěšně proběhlo" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ testů úspěšně proběhlo" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Vlastní systémy pluginů | `iii worker add <name>` |-**227 zdrojových souborů · ~54,000 řádků kódu · 2,900+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.+**228 zdrojových souborů · ~54,000 řádků kódu · 3,000+ testů · 312 funkcí · 62 KV scopes**, vše na třech primitivech. Žádné `agentmemory plugin install`. Systém pluginů je samo iii.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.da-DK.md b/READMEs/README.da-DK.mdindex e95f5209..e3506395 100644--- a/READMEs/README.da-DK.md+++ b/READMEs/README.da-DK.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-værktøjer" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatiske hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 eksterne databaser" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ beståede tests" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ beståede tests" height="38" /></picture></p><p align="center">@@ -1436,7 +1436,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Custom plugin-systemer | `iii worker add <name>` |-**227 kildefiler · ~54,000 LOC · 2,900+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.+**228 kildefiler · ~54,000 LOC · 3,000+ tests · 312 funktioner · 62 KV-scopes**, alt på tre primitiver. Intet `agentmemory plugin install`. Plugin-systemet er iii selv.---@@ -1860,7 +1860,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.de-DE.md b/READMEs/README.de-DE.mdindex cfa0822c..fb77b763 100644--- a/READMEs/README.de-DE.md+++ b/READMEs/README.de-DE.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-Tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 Auto-Hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externe DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ bestandene Tests" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ bestandene Tests" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + Health-Monitor || Eigene Plugin-Systeme | `iii worker add <name>` |-**227 Quelldateien · ~54,000 LOC · 2,900+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.+**228 Quelldateien · ~54,000 LOC · 3,000+ Tests · 312 Funktionen · 62 KV-Scopes**, alles auf drei Primitiven. Kein `agentmemory plugin install`. Das Plugin-System ist iii selbst.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.el-GR.md b/READMEs/README.el-GR.mdindex ea1d4291..28784fc0 100644--- a/READMEs/README.el-GR.md+++ b/READMEs/README.el-GR.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 εργαλεία MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 αυτόματα hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 εξωτερικές βάσεις δεδομένων" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ επιτυχημένες δοκιμές" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ επιτυχημένες δοκιμές" height="38" /></picture></p><p align="center">@@ -1438,7 +1438,7 @@ fi| Prometheus / Grafana | iii OTEL + monitor υγείας || Προσαρμοσμένα συστήματα plugin | `iii worker add <name>` |-**227 αρχεία πηγαίου κώδικα · ~54,000 LOC · 2,900+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.+**228 αρχεία πηγαίου κώδικα · ~54,000 LOC · 3,000+ δοκιμές · 312 functions · 62 KV scopes**, όλα πάνω σε τρία primitives. Δεν υπάρχει `agentmemory plugin install`. Το σύστημα plugin είναι το ίδιο το iii.---@@ -1862,7 +1862,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.es-ES.md b/READMEs/README.es-ES.mdindex 360b7711..3bc00ec1 100644--- a/READMEs/README.es-ES.md+++ b/READMEs/README.es-ES.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 tools MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks automáticos" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 bases de datos externas" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests superados" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests superados" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + monitor de salud || Sistemas de plugins propios | `iii worker add <name>` |-**227 ficheros de código · ~54,000 LOC · 2,900+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.+**228 ficheros de código · ~54,000 LOC · 3,000+ tests · 312 funciones · 62 scopes KV**, todo sobre tres primitivos. No hay `agentmemory plugin install`. El sistema de plugins es iii mismo.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.fi-FI.md b/READMEs/README.fi-FI.mdindex ac6ae128..e5fe94a3 100644--- a/READMEs/README.fi-FI.md+++ b/READMEs/README.fi-FI.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-työkalua" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automaattista hookia" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 ulkoista tietokantaa" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testiä läpäisty" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ testiä läpäisty" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + terveysmonitori || Mukautetut plugin-järjestelmät | `iii worker add <name>` |-**227 lähdetiedostoa · ~54,000 LOC · 2,900+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.+**228 lähdetiedostoa · ~54,000 LOC · 3,000+ testiä · 312 funktiota · 62 KV-scopea**, kaikki kolmen primitiivin päällä. Ei `agentmemory plugin install` -komentoa. Plugin-järjestelmä on iii itse.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.fr-FR.md b/READMEs/README.fr-FR.mdindex 8319c433..9ccb5464 100644--- a/READMEs/README.fr-FR.md+++ b/READMEs/README.fr-FR.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1448,7 +1448,7 @@ fi| Prometheus / Grafana | iii OTEL + moniteur de santé || Systèmes de plugins custom | `iii worker add <name>` |-**227 fichiers sources · ~54,000 LOC · 2,900+ tests · 312 fonctions · 62 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.+**228 fichiers sources · ~54,000 LOC · 3,000+ tests · 312 fonctions · 62 scopes KV**, tout sur trois primitives. Pas de `agentmemory plugin install`. Le système de plugins, c'est iii lui-même.---@@ -1872,7 +1872,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.he-IL.md b/READMEs/README.he-IL.mdindex 8a2e9947..c9456598 100644--- a/READMEs/README.he-IL.md+++ b/READMEs/README.he-IL.md@@ -73,7 +73,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 כלי MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks אוטומטיים" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 מסדי נתונים חיצוניים" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ בדיקות עוברות" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ בדיקות עוברות" height="38" /></picture></p><p align="center">@@ -1439,7 +1439,7 @@ fi| Prometheus / Grafana | iii OTEL + מוניטור health || מערכות plugin מותאמות אישית | `iii worker add <name>` |-**227 קבצי מקור · ~54,000 LOC · 2,900+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.+**228 קבצי מקור · ~54,000 LOC · 3,000+ בדיקות · 312 פונקציות · 62 תחומי KV**, הכול על שלושה primitives. אין `agentmemory plugin install`. מערכת ה-plugin היא iii עצמו.---@@ -1863,7 +1863,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.hi-IN.md b/READMEs/README.hi-IN.mdindex 7a6c698c..95cb6c8b 100644--- a/READMEs/README.hi-IN.md+++ b/READMEs/README.hi-IN.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1449,7 +1449,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Custom plugin systems | `iii worker add <name>` |-**227 source files · ~54,000 LOC · 2,900+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।+**228 source files · ~54,000 LOC · 3,000+ tests · 312 functions · 62 KV scopes**, सब कुछ तीन primitives पर। कोई `agentmemory plugin install` नहीं। Plugin system iii स्वयं है।---@@ -1873,7 +1873,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.hu-HU.md b/READMEs/README.hu-HU.mdindex 1094c112..aaabb386 100644--- a/READMEs/README.hu-HU.md+++ b/READMEs/README.hu-HU.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP eszköz" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatikus hook" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 külső adatbázis" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ sikeres teszt" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ sikeres teszt" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ A `/agentmemory/export` emellett elfogadja a `?maxSessions=`-t és a `?offset=`-| Prometheus / Grafana | iii OTEL + egészségfigyelő || Egyéni plugin-rendszerek | `iii worker add <name>` |-**227 forrásfájl · ~54,000 LOC · 2,900+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.+**228 forrásfájl · ~54,000 LOC · 3,000+ teszt · 312 funkció · 62 KV-hatókör**, mindez három primitíven. Nincs `agentmemory plugin install`. A plugin-rendszer maga az iii.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.id-ID.md b/READMEs/README.id-ID.mdindex ff5e3cf4..c94940d9 100644--- a/READMEs/README.id-ID.md+++ b/READMEs/README.id-ID.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 tool MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook otomatis" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 DB eksternal" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ pengujian lolos" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ pengujian lolos" height="38" /></picture></p><p align="center">@@ -1447,7 +1447,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Sistem plugin custom | `iii worker add <name>` |-**227 file sumber · ~54,000 LOC · 2,900+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.+**228 file sumber · ~54,000 LOC · 3,000+ pengujian · 312 fungsi · 62 scope KV**, semua di atas tiga primitif. Tidak ada `agentmemory plugin install`. Sistem plugin-nya adalah iii itu sendiri.---@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.it-IT.md b/READMEs/README.it-IT.mdindex c85e4ac3..d3d09642 100644--- a/READMEs/README.it-IT.md+++ b/READMEs/README.it-IT.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + monitor di salute || Sistemi di plugin personalizzati | `iii worker add <name>` |-**227 file sorgente · ~54,000 righe di codice · 2,900+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.+**228 file sorgente · ~54,000 righe di codice · 3,000+ test · 312 funzioni · 62 scope KV**, tutto su tre primitive. Nessun `agentmemory plugin install`. Il sistema di plugin è iii stesso.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.ja-JP.md b/READMEs/README.ja-JP.mdindex 043adbd7..3285ed0f 100644--- a/READMEs/README.ja-JP.md+++ b/READMEs/README.ja-JP.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP ツール" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 自動 hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="外部 DB 0 個" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 件のテストが成功" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ 件のテストが成功" height="38" /></picture></p><p align="center">@@ -1445,7 +1445,7 @@ fi| Prometheus / Grafana | iii OTEL + ヘルスモニタ || カスタムプラグインシステム | `iii worker add <name>` |-**227 ソースファイル · ~54,000 LOC · 2,900+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。+**228 ソースファイル · ~54,000 LOC · 3,000+ テスト · 312 functions · 62 KV スコープ** — すべて 3 つのプリミティブの上に。`agentmemory plugin install` はありません。プラグインシステムは iii そのものです。---@@ -1869,7 +1869,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.ko-KR.md b/READMEs/README.ko-KR.mdindex e0dadacb..32ec5cc8 100644--- a/READMEs/README.ko-KR.md+++ b/READMEs/README.ko-KR.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + health 모니터 || 커스텀 플러그인 시스템 | `iii worker add <name>` |-**소스 파일 227개 · LOC ~54,000줄 · 테스트 2,900+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.+**소스 파일 228개 · LOC ~54,000줄 · 테스트 3,000+개 · 함수 312개 · KV 스코프 62개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.nb-NO.md b/READMEs/README.nb-NO.mdindex 694280e9..878bc705 100644--- a/READMEs/README.nb-NO.md+++ b/READMEs/README.nb-NO.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1447,7 +1447,7 @@ fi| Prometheus / Grafana | iii OTEL + helseovervåker || Egendefinerte plugin-systemer | `iii worker add <name>` |-**227 kildefiler · ~54,000 LOC · 2,900+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.+**228 kildefiler · ~54,000 LOC · 3,000+ tester · 312 funksjoner · 62 KV-scopes**, alt på tre primitiver. Ingen `agentmemory plugin install`. Plugin-systemet er iii selv.---@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.nl-NL.md b/READMEs/README.nl-NL.mdindex 92ca4769..1124fb7d 100644--- a/READMEs/README.nl-NL.md+++ b/READMEs/README.nl-NL.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Custom plugin-systemen | `iii worker add <name>` |-**227 bronbestanden · ~54,000 LOC · 2,900+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.+**228 bronbestanden · ~54,000 LOC · 3,000+ tests · 312 functies · 62 KV-scopes**, allemaal op drie primitieven. Geen `agentmemory plugin install`. Het pluginsysteem is iii zelf.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.pl-PL.md b/READMEs/README.pl-PL.mdindex b1b98c54..f42eb503 100644--- a/READMEs/README.pl-PL.md+++ b/READMEs/README.pl-PL.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 narzędzia MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatycznych hooków" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 zewnętrznych baz danych" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ zaliczonych testów" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ zaliczonych testów" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + monitor stanu || Niestandardowe systemy pluginów | `iii worker add <name>` |-**227 plików źródłowych · ~54,000 LOC · 2,900+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.+**228 plików źródłowych · ~54,000 LOC · 3,000+ testów · 312 funkcji · 62 zakresy KV**, wszystko na trzech prymitywach. Nie ma `agentmemory plugin install`. Systemem pluginów jest sam iii.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.pt-BR.md b/READMEs/README.pt-BR.mdindex 852cd6fc..1dae1e6d 100644--- a/READMEs/README.pt-BR.md+++ b/READMEs/README.pt-BR.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1447,7 +1447,7 @@ fi| Prometheus / Grafana | iii OTEL + monitor de saúde || Sistemas de plugin customizados | `iii worker add <name>` |-**227 arquivos de código · ~54,000 LOC · 2,900+ testes · 312 funções · 62 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.+**228 arquivos de código · ~54,000 LOC · 3,000+ testes · 312 funções · 62 escopos KV**, tudo em cima de três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.---@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.pt-PT.md b/READMEs/README.pt-PT.mdindex 6b82ab4d..552cd50d 100644--- a/READMEs/README.pt-PT.md+++ b/READMEs/README.pt-PT.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 ferramentas MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hooks automáticos" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 bases de dados externas" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ testes aprovados" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ testes aprovados" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ O `/agentmemory/export` também aceita `?maxSessions=` e `?offset=` para dividir| Prometheus / Grafana | iii OTEL + monitor de saúde || Sistemas de plugins personalizados | `iii worker add <name>` |-**227 ficheiros de código-fonte · ~54,000 LOC · 2,900+ testes · 312 funções · 62 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.+**228 ficheiros de código-fonte · ~54,000 LOC · 3,000+ testes · 312 funções · 62 âmbitos de KV**, tudo sobre três primitivos. Sem `agentmemory plugin install`. O sistema de plugins é o próprio iii.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.ro-RO.md b/READMEs/README.ro-RO.mdindex 6f73b5ee..2a8a0d08 100644--- a/READMEs/README.ro-RO.md+++ b/READMEs/README.ro-RO.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 de instrumente MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook-uri automate" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 baze de date externe" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ teste trecute" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ teste trecute" height="38" /></picture></p><p align="center">@@ -1430,7 +1430,7 @@ fi| Prometheus / Grafana | iii OTEL + monitor de sănătate || Sisteme de plugin-uri personalizate | `iii worker add <name>` |-**227 fișiere sursă · ~54,000 LOC · 2,900+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.+**228 fișiere sursă · ~54,000 LOC · 3,000+ teste · 312 funcții · 62 de domenii KV**, toate pe trei primitive. Niciun `agentmemory plugin install`. Sistemul de plugin-uri este chiar iii.---@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.ru-RU.md b/READMEs/README.ru-RU.mdindex d04a8ada..a7300af9 100644--- a/READMEs/README.ru-RU.md+++ b/READMEs/README.ru-RU.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ fi| Prometheus / Grafana | iii OTEL + монитор состояния || Самописные плагинные системы | `iii worker add <name>` |-**227 исходных файлов · ~54,000 LOC · 2,900+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.+**228 исходных файлов · ~54,000 LOC · 3,000+ тестов · 312 функций · 62 KV-scope**, всё на трёх примитивах. Никакого `agentmemory plugin install`. Плагинная система — это сам iii.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.sv-SE.md b/READMEs/README.sv-SE.mdindex 895aa777..787e74bf 100644--- a/READMEs/README.sv-SE.md+++ b/READMEs/README.sv-SE.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP-verktyg" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 automatiska hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 externa databaser" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ godkända tester" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ godkända tester" height="38" /></picture></p><p align="center">@@ -1437,7 +1437,7 @@ fi| Prometheus / Grafana | iii OTEL + hälsoövervakare || Anpassade pluginsystem | `iii worker add <name>` |-**227 källkodsfiler · ~54,000 LOC · 2,900+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.+**228 källkodsfiler · ~54,000 LOC · 3,000+ tester · 312 funktioner · 62 KV-scopes**, allt på tre primitiv. Inget `agentmemory plugin install`. Pluginsystemet är iii självt.---@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.th-TH.md b/READMEs/README.th-TH.mdindex 3a1ac15d..c70f7a9b 100644--- a/READMEs/README.th-TH.md+++ b/READMEs/README.th-TH.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 เครื่องมือ MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 hook อัตโนมัติ" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="ไม่ต้องพึ่ง external DB เลย" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="ผ่านการทดสอบ 2,900+ รายการ" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="ผ่านการทดสอบ 3,000+ รายการ" height="38" /></picture></p><p align="center">@@ -1444,7 +1444,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Custom plugin systems | `iii worker add <name>` |-**227 source file · ~54,000 LOC · 2,900+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ+**228 source file · ~54,000 LOC · 3,000+ การทดสอบ · 312 function · 62 KV scope** ทั้งหมดอยู่บน primitive สามตัว ไม่มี `agentmemory plugin install` ระบบ plugin ก็คือ iii เองนั่นแหละ---@@ -1868,7 +1868,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.tl-PH.md b/READMEs/README.tl-PH.mdindex 884e3ebb..ff12dbf8 100644--- a/READMEs/README.tl-PH.md+++ b/READMEs/README.tl-PH.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tool" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 awtomatikong hook" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 panlabas na DB" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ pumapasang test" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ pumapasang test" height="38" /></picture></p><p align="center">@@ -1446,7 +1446,7 @@ Tinatanggap din ng `/agentmemory/export` ang `?maxSessions=` at `?offset=` para| Prometheus / Grafana | iii OTEL + health monitor || Custom na plugin system | `iii worker add <name>` |-**227 na source file · ~54,000 LOC · 2,900+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.+**228 na source file · ~54,000 LOC · 3,000+ na test · 312 na function · 62 na KV scope**, lahat sa tatlong primitive. Walang `agentmemory plugin install`. Ang plugin system mismo ay ang iii.---@@ -1870,7 +1870,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.tr-TR.md b/READMEs/README.tr-TR.mdindex e44fe39b..aae81337 100644--- a/READMEs/README.tr-TR.md+++ b/READMEs/README.tr-TR.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1437,7 +1437,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Custom eklenti sistemleri | `iii worker add <name>` |-**227 kaynak dosya · ~54,000 LOC · 2,900+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.+**228 kaynak dosya · ~54,000 LOC · 3,000+ test · 312 fonksiyon · 62 KV scope**, hepsi üç primitif üzerinde. `agentmemory plugin install` yok. Eklenti sistemi, iii'nin kendisidir.---@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.uk-UA.md b/READMEs/README.uk-UA.mdindex 23ed1f21..ef124feb 100644--- a/READMEs/README.uk-UA.md+++ b/READMEs/README.uk-UA.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 інструменти MCP" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 автоматичних хуків" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 зовнішніх БД" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ тестів пройдено" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ тестів пройдено" height="38" /></picture></p><p align="center">@@ -1447,7 +1447,7 @@ fi| Prometheus / Grafana | iii OTEL + монітор стану здоров'я || Власні системи плагінів | `iii worker add <name>` |-**227 вихідних файлів · ~54,000 LOC · 2,900+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.+**228 вихідних файлів · ~54,000 LOC · 3,000+ тестів · 312 функцій · 62 KV-скоупів**, усе на трьох примітивах. Жодного `agentmemory plugin install`. Система плагінів — це сам iii.---@@ -1871,7 +1871,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.ur-PK.md b/READMEs/README.ur-PK.mdindex 19cf115c..42fb1c0d 100644--- a/READMEs/README.ur-PK.md+++ b/READMEs/README.ur-PK.md@@ -73,7 +73,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP ٹولز" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 خودکار ہکس" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 خارجی ڈیٹابیسز" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ ٹیسٹس پاس ہو رہے ہیں" height="38" /></picture></p><p align="center">@@ -1432,7 +1432,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || کسٹم plugin سسٹمز | `iii worker add <name>` |-**227 سورس فائلز · ~54,000 لائنز کوڈ · 2,900+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔+**228 سورس فائلز · ~54,000 لائنز کوڈ · 3,000+ ٹیسٹس · 312 فنکشنز · 62 KV اسکوپس**، سب تین primitives پر۔ کوئی `agentmemory plugin install` نہیں۔ plugin سسٹم خود iii ہی ہے۔---@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.vi-VN.md b/READMEs/README.vi-VN.mdindex 43c1b769..c754c365 100644--- a/READMEs/README.vi-VN.md+++ b/READMEs/README.vi-VN.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 MCP tools" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 auto hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 external DBs" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ tests passing" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ tests passing" height="38" /></picture></p><p align="center">@@ -1437,7 +1437,7 @@ fi| Prometheus / Grafana | iii OTEL + health monitor || Hệ thống plugin tùy chỉnh | `iii worker add <name>` |-**227 file source · ~54,000 LOC · 2,900+ test · 312 function · 62 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.+**228 file source · ~54,000 LOC · 3,000+ test · 312 function · 62 KV scope**, tất cả trên ba primitive. Không có `agentmemory plugin install`. Hệ thống plugin chính là iii.---@@ -1861,7 +1861,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.zh-CN.md b/READMEs/README.zh-CN.mdindex 94d4a82d..4b9dee4b 100644--- a/READMEs/README.zh-CN.md+++ b/READMEs/README.zh-CN.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 个 MCP 工具" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 个自动 hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 个外部数据库" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 项测试通过" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ 项测试通过" height="38" /></picture></p><p align="center">@@ -1444,7 +1444,7 @@ fi| Prometheus / Grafana | iii OTEL + 健康监控 || Custom plugin systems | `iii worker add <name>` |-**227 个源文件 · ~54,000 行代码 · 2,900+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。+**228 个源文件 · ~54,000 行代码 · 3,000+ 个测试 · 312 个函数 · 62 个 KV 作用域**,全部基于三种原语。没有 `agentmemory plugin install`。插件系统就是 iii 本身。---@@ -1868,7 +1868,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/READMEs/README.zh-TW.md b/READMEs/README.zh-TW.mdindex 83605600..d4b90bca 100644--- a/READMEs/README.zh-TW.md+++ b/READMEs/README.zh-TW.md@@ -71,7 +71,7 @@<picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tools.svg"><img src="../assets/tags/stat-tools.svg" alt="54 個 MCP 工具" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-hooks.svg"><img src="../assets/tags/stat-hooks.svg" alt="12 個自動 hooks" height="38" /></picture><picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-deps.svg"><img src="../assets/tags/stat-deps.svg" alt="0 個外部資料庫" height="38" /></picture>- <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="2,900+ 測試通過" height="38" /></picture>+ <picture><source media="(prefers-color-scheme: dark)" srcset="../assets/tags/light/stat-tests.svg"><img src="../assets/tags/stat-tests.svg" alt="3,000+ 測試通過" height="38" /></picture></p><p align="center">@@ -1430,7 +1430,7 @@ fi| Prometheus / Grafana | iii OTEL + 健康監控 || 自訂外掛系統 | `iii worker add <name>` |-**227 個原始檔 · ~54,000 行程式碼 · 2,900+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。+**228 個原始檔 · ~54,000 行程式碼 · 3,000+ 測試 · 312 個函式 · 62 個 KV 範圍**,全部基於三種原語。沒有 `agentmemory plugin install`。外掛系統就是 iii 本身。---@@ -1854,7 +1854,7 @@ curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: a```bashnpm run dev # Hot reloadnpm run build # Production build-npm test # 2,900+ tests+npm test # 3,000+ testsnpm run test:integration # API tests (requires running services)```diff --git a/assets/tags/light/stat-tests.svg b/assets/tags/light/stat-tests.svgindex 955556fb..45fd4a82 100644--- a/assets/tags/light/stat-tests.svg+++ b/assets/tags/light/stat-tests.svg@@ -1,5 +1,5 @@-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2900+">+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 3000+"><rect x="0" y="0" width="140" height="48" rx="10" fill="#FFFFFF" stroke="#E5E7EB" stroke-width="1"/>- <text x="70" y="24" fill="#16A34A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2900+</text>+ <text x="70" y="24" fill="#16A34A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">3000+</text><text x="70" y="38" fill="#64748B" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="9" font-weight="600" text-anchor="middle" letter-spacing="1.5">TESTS PASSING</text></svg>diff --git a/assets/tags/stat-tests.svg b/assets/tags/stat-tests.svgindex 8e120b66..67853cf6 100644--- a/assets/tags/stat-tests.svg+++ b/assets/tags/stat-tests.svg@@ -1,5 +1,5 @@-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 2900+">+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 140 48" fill="none" role="img" aria-label="TESTS PASSING: 3000+"><rect x="0" y="0" width="140" height="48" rx="10" fill="#1A1A1A" stroke="#2A2A2A" stroke-width="1"/>- <text x="70" y="24" fill="#00D26A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">2900+</text>+ <text x="70" y="24" fill="#00D26A" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="18" font-weight="900" text-anchor="middle" letter-spacing="-0.3">3000+</text><text x="70" y="38" fill="#9CA3AF" font-family='ui-sans-serif, -apple-system, "Segoe UI", Inter, system-ui, sans-serif' font-size="9" font-weight="600" text-anchor="middle" letter-spacing="1.5">TESTS PASSING</text></svg>diff --git a/package.json b/package.jsonindex 0893be3a..1a9893db 100644--- a/package.json+++ b/package.json@@ -25,6 +25,7 @@"test:watch": "vitest --exclude test/integration.test.ts","test:integration": "vitest run test/integration.test.ts","test:all": "vitest run",+ "test:startup:packaged": "node scripts/release-gate/startup.mjs","release:gate": "node scripts/release-gate/run.mjs","skills:gen": "tsx scripts/skills/generate.ts","engine:hashes": "node scripts/engine-hashes.mjs",diff --git a/plugin/skills/agentmemory-config/REFERENCE.md b/plugin/skills/agentmemory-config/REFERENCE.mdindex e2ab6379..f2a09783 100644--- a/plugin/skills/agentmemory-config/REFERENCE.md+++ b/plugin/skills/agentmemory-config/REFERENCE.md@@ -3,7 +3,7 @@Generated by scanning `src/` for `AGENTMEMORY_*` usage. Do not edit the block below by hand; run `npm run skills:gen` after adding or removing a variable. Internal markers ending in two underscores are excluded.<!-- AUTOGEN:env START - generated by scripts/skills/generate.ts, do not edit by hand -->-Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 73 recognized variables:+Configuration is read from the environment and from `~/.agentmemory/.env` (no `export` prefix). 76 recognized variables:- `AGENTMEMORY_AGENT_SCOPE`- `AGENTMEMORY_ALLOW_AGENT_SDK`@@ -35,6 +35,8 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e- `AGENTMEMORY_DOCKER_SKIP_CHOWN`- `AGENTMEMORY_DOCKER_UID`- `AGENTMEMORY_DROP_STALE_INDEX`+- `AGENTMEMORY_ENGINE_MANAGES_WORKER`+- `AGENTMEMORY_ENGINE_READY_TIMEOUT_MS`- `AGENTMEMORY_EXPORT_ROOT`- `AGENTMEMORY_FINALIZE_IDLE_MS`- `AGENTMEMORY_FOLLOWUP_WINDOW_SECONDS`@@ -56,6 +58,7 @@ Configuration is read from the environment and from `~/.agentmemory/.env` (no `e- `AGENTMEMORY_PROBE_TIMEOUT_MS`- `AGENTMEMORY_PROJECT_NAME`- `AGENTMEMORY_PROVIDER`+- `AGENTMEMORY_READY_TIMEOUT_MS`- `AGENTMEMORY_REDIS_URL`- `AGENTMEMORY_REFLECT`- `AGENTMEMORY_RUNTIME_DIR`diff --git a/scripts/docs-sync.state.json b/scripts/docs-sync.state.jsonindex 7ba2ceb9..fad86a8d 100644--- a/scripts/docs-sync.state.json+++ b/scripts/docs-sync.state.json@@ -20,13 +20,13 @@"12"],"tests": [- "2900+"+ "3000+"],"functions": ["312"],"sourceFiles": [- "227"+ "228"],"loc": ["54000"diff --git a/scripts/release-gate/startup.mjs b/scripts/release-gate/startup.mjsnew file mode 100644index 00000000..1dc75a03--- /dev/null+++ b/scripts/release-gate/startup.mjs@@ -0,0 +1,501 @@+#!/usr/bin/env node+import assert from "node:assert/strict";+import { spawn, execFileSync } from "node:child_process";+import { createHash } from "node:crypto";+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";+import http from "node:http";+import net from "node:net";+import { arch, homedir, platform, tmpdir } from "node:os";+import { dirname, join, resolve, delimiter } from "node:path";+import { fileURLToPath, pathToFileURL } from "node:url";++const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../..");+const options = { tarball: null, out: null, only: null, keep: false, delayMs: 48_000, skipBuild: false };+for (let i = 2; i < process.argv.length; i++) {+ const arg = process.argv[i];+ if (arg === "--tarball") options.tarball = resolve(process.argv[++i]);+ else if (arg === "--out") options.out = resolve(process.argv[++i]);+ else if (arg === "--only") options.only = new Set(process.argv[++i].split(","));+ else if (arg === "--delay-ms") options.delayMs = Number(process.argv[++i]);+ else if (arg === "--keep") options.keep = true;+ else if (arg === "--skip-build") options.skipBuild = true;+ else if (arg === "--help") {+ console.log("Usage: node scripts/release-gate/startup.mjs [--tarball file.tgz] [--out dir] [--only names] [--delay-ms 48000] [--skip-build] [--keep]");+ process.exit(0);+ } else throw new Error(`Unknown argument ${arg}`);+}+assert(Number.isSafeInteger(options.delayMs) && options.delayMs > 0 && options.delayMs <= 300_000, "--delay-ms must be 1..300000");+const root = mkdtempSync(join(tmpdir(), "am-startup-"));+const out = options.out ?? mkdtempSync(join(tmpdir(), "agentmemory-startup-gate-"));+mkdirSync(out, { recursive: true });+const prefix = join(root, "prefix");+const pkg = join(prefix, "node_modules/@agentmemory/agentmemory");+const cli = join(pkg, "dist/cli.mjs");+const nodeDir = dirname(process.execPath);+const cache = process.env.AGENTMEMORY_GATE_CACHE ?? join(homedir(), ".cache/agentmemory-release-gate");+const children = new Set();+const instances = new Set();+const results = [];+const started = Date.now();+const log = (message) => {+ const line = `[${((Date.now() - started) / 1000).toFixed(1)}s] ${message}`;+ console.log(line);+ appendFileSync(join(out, "gate.log"), `${line}\n`);+};+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));+const sha = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");+function packageDigest() {+ const files = [];+ const walk = (dir, relative = "") => { for (const entry of readdirSync(dir, { withFileTypes: true })) {+ const name = relative ? `${relative}/${entry.name}` : entry.name;+ if (entry.isDirectory()) walk(join(dir, entry.name), name);+ else if (entry.isFile()) files.push([name, sha(join(dir, entry.name))]);+ } };+ walk(pkg); files.sort(([a], [b]) => a.localeCompare(b));+ return createHash("sha256").update(JSON.stringify(files)).digest("hex");+}+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };+function kill(pid, signal = "SIGKILL") {+ if (!Number.isSafeInteger(pid) || pid <= 0 || pid === process.pid) return;+ try { process.kill(-pid, signal); } catch {}+ try { process.kill(pid, signal); } catch {}+}+function launch(command, args, env, cwd, logFile) {+ const child = spawn(command, args, { env, cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });+ children.add(child);+ child.text = "";+ child.result = null;+ const record = (chunk) => { child.text += chunk; if (logFile) appendFileSync(logFile, chunk); };+ child.stdout.on("data", record);+ child.stderr.on("data", record);+ child.on("error", (err) => record(String(err)));+ child.on("close", (code, signal) => { child.result = { code, signal }; children.delete(child); });+ return child;+}+async function exited(child, timeoutMs = 30_000) {+ const deadline = Date.now() + timeoutMs;+ while (!child.result && Date.now() < deadline) await sleep(25);+ if (!child.result) { kill(child.pid); throw new Error(`process exceeded ${timeoutMs}ms: ${child.text.slice(-1000)}`); }+ return child.result;+}+async function command(bin, args, env = process.env, cwd = repo, timeout = 120_000, logFile) {+ const child = launch(bin, args, env, cwd, logFile);+ const result = await exited(child, timeout);+ assert.equal(result.code, 0, `${bin} ${args.join(" ")}: ${child.text.slice(-1200)}`);+ return child.text;+}+async function poll(label, probe, timeoutMs = 90_000) {+ const deadline = Date.now() + timeoutMs;+ let last;+ do {+ try { const value = await probe(); if (value) return value; } catch (err) { last = err; if (err.fatal) throw err; }+ await sleep(100);+ } while (Date.now() < deadline);+ throw new Error(`${label} timed out: ${last?.message ?? "not ready"}`);+}+async function unusedPort() {+ const server = net.createServer();+ await new Promise((r, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", r); });+ const port = server.address().port;+ await new Promise((r) => server.close(r));+ return port;+}+async function free(port) {+ const server = net.createServer();+ return new Promise((r) => { server.once("error", () => r(false)); server.listen(port, "127.0.0.1", () => server.close(() => r(true))); });+}+async function portBlock() {+ for (let i = 0; i < 200; i++) {+ const port = 12000 + Math.floor(Math.random() * 7000);+ if ((await Promise.all([0, 1, 2, 3, 6353, 46023].map((d) => free(port + d)))).every(Boolean)) return port;+ }+ throw new Error("No free port block");+}+let installed;+let tarball;+let artifactSha;+let cliSha;+let pkgSha;+let engine;+function baseEnv(home) {+ return { HOME: home, PATH: [join(prefix, "node_modules/.bin"), nodeDir, "/usr/bin", "/bin", "/usr/sbin", "/sbin"].join(delimiter), TMPDIR: tmpdir(), CI: "1", NO_COLOR: "1", LANG: "C.UTF-8", EMBEDDING_PROVIDER: "none", LLM_PROVIDER: "none", III_TELEMETRY_ENABLED: "false" };+}+async function install() {+ tarball = options.tarball;+ if (!tarball) {+ if (!options.skipBuild) await command("npm", ["run", "build"], process.env, repo, 600_000, join(out, "build.log"));+ const packDir = join(root, "pack"); mkdirSync(packDir);+ const packed = await command("npm", ["pack", "--json", "--pack-destination", packDir]);+ tarball = join(packDir, JSON.parse(packed)[0].filename);+ }+ artifactSha = sha(tarball);+ mkdirSync(prefix, { recursive: true });+ writeFileSync(join(prefix, "package.json"), '{"name":"startup-gate-prefix","private":true}\n');+ const installHome = join(root, "install-home"); mkdirSync(installHome);+ const npmCache = execFileSync("npm", ["config", "get", "cache"], { encoding: "utf8" }).trim();+ log(`installing exact tarball ${tarball}`);+ await command("npm", ["install", "--no-audit", "--no-fund", "--no-package-lock", tarball], { ...baseEnv(installHome), npm_config_cache: npmCache }, prefix, 600_000, join(out, "install.log"));+ installed = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));+ engine = process.env.AGENTMEMORY_GATE_ENGINE ?? join(cache, `iii-${installed.dependencies["iii-sdk"]}-${platform()}-${arch()}`);+ assert(existsSync(engine), `Pinned engine missing: ${engine}. Run the standard release gate once, or set AGENTMEMORY_GATE_ENGINE.`);+ const version = await command(engine, ["--version"]);+ assert(version.includes(installed.dependencies["iii-sdk"]), `Engine version mismatch: ${version}`);+ cliSha = sha(cli); pkgSha = packageDigest();+ const cliVersion = await command(process.execPath, [cli, "--version"], baseEnv(installHome));+ assert.equal(cliVersion.trim(), installed.version);+}+class Instance {+ constructor(name) {+ this.name = name; this.dir = join(root, name); this.home = join(this.dir, "home"); this.data = join(this.dir, "data"); this.runtime = join(this.home, ".agentmemory");+ for (const dir of [this.home, this.data, this.runtime]) mkdirSync(dir, { recursive: true });+ this.logFile = join(out, `${name}.log`); this.envExtra = {}; this.handles = []; this.ownedPids = new Set(); this.dockerProject = null;+ instances.add(this);+ }+ async init() {+ this.port = await portBlock();+ const binDir = join(this.runtime, "bin"); mkdirSync(binDir, { recursive: true }); copyFileSync(engine, join(binDir, "iii")); chmodSync(join(binDir, "iii"), 0o755);+ return this;+ }+ env(extra = {}) { return { ...baseEnv(this.home), AGENTMEMORY_DATA_DIR: this.data, AGENTMEMORY_RUNTIME_DIR: this.runtime, III_REST_PORT: String(this.port), III_STREAM_PORT: String(this.port + 1), III_VIEWER_PORT: String(this.port + 2), III_ENGINE_PORT: String(this.port + 46023), AGENTMEMORY_METRICS_PORT: String(this.port + 6353), ...this.envExtra, ...extra }; }+ get url() { return `http://127.0.0.1:${this.port}`; }+ pid(name) { try { return Number(readFileSync(join(this.runtime, `${name}.pid`), "utf8").trim()); } catch { return null; } }+ config({ delayMs = 0, earlyPid = false, worker = true } = {}) {+ let raw = readFileSync(join(pkg, "iii-config.yaml"), "utf8").split(" - name: iii-exec")[0];+ raw = raw.replaceAll("3111", String(this.port)).replaceAll("3112", String(this.port + 1)).replaceAll("3113", String(this.port + 2)).replaceAll("./data/", `${this.data}/`);+ raw += ` - name: iii-worker-manager\n config:\n port: ${this.port + 46023}\n host: 127.0.0.1\n`;+ if (worker) {+ const wrapper = join(this.dir, "delayed-worker.mjs");+ writeFileSync(wrapper, `import { appendFileSync, writeFileSync } from 'node:fs';\nappendFileSync(${JSON.stringify(join(this.dir, "worker-starts.jsonl"))}, JSON.stringify({pid:process.pid,at:Date.now()})+'\\n');\n${earlyPid ? `writeFileSync(${JSON.stringify(join(this.runtime, "worker.pid"))}, String(process.pid));` : ""}\nawait new Promise(r=>setTimeout(r,${delayMs}));\nawait import(${JSON.stringify(pathToFileURL(join(pkg, "dist/index.mjs")).href)});\n`);+ raw += ` - name: iii-exec\n config:\n exec:\n - ${process.execPath} ${wrapper}\n`;+ }+ const file = join(this.dir, "iii-config.yaml"); writeFileSync(file, raw); this.envExtra.AGENTMEMORY_III_CONFIG = file; if (worker) this.envExtra.AGENTMEMORY_ENGINE_MANAGES_WORKER = "true"; return file;+ }+ start(args = [], env = {}) {+ this.cli = launch(process.execPath, [cli, ...args, "--port", String(this.port)], this.env(env), this.dir, this.logFile);+ this.ownedPids.add(this.cli.pid); return this.cli;+ }+ async startEngine(config) {+ this.engine = launch(engine, ["--config", config, "--no-update-check"], this.env(), this.dir, this.logFile);+ this.ownedPids.add(this.engine.pid);+ await poll("external engine", async () => (await fetch(`${this.url}/`, { signal: AbortSignal.timeout(500) })).status > 0, 20_000);+ writeFileSync(join(this.runtime, "engine-state.json"), JSON.stringify({ kind: "native", configPath: config, binPath: engine, restPort: this.port, attached: true }));+ writeFileSync(join(this.runtime, "iii.pid"), String(this.engine.pid));+ }+ async ready(timeout = 90_000, requireHint = true, allowDoctorDiagnosticsFailure = false) {+ await poll(this.name, async () => {+ if (!allowDoctorDiagnosticsFailure && this.cli.result?.code && this.cli.result.code !== 0) { const err = new Error(`CLI exited ${this.cli.result.code}: ${this.cli.text.slice(-1100)}`); err.fatal = true; throw err; }+ if (requireHint && !this.cli.text.includes("REST API")) return false;+ const response = await fetch(`${this.url}/agentmemory/livez`, { signal: AbortSignal.timeout(1000) });+ if (!response.ok) return false;+ const body = await response.json(); return body.viewerPort || body.viewerSkipped;+ }, timeout);+ }+ wrapperStarts() { try { return readFileSync(join(this.dir, "worker-starts.jsonl"), "utf8").trim().split("\n").map(JSON.parse); } catch { return []; } }+ async close() {+ if (this.closed) return; this.closed = true;+ for (const handle of this.handles) { handle.closeAllConnections?.(); handle.close(); }+ if (this.dockerProject) await command(this.dockerBin, ["compose", "-p", this.dockerProject, "-f", join(pkg, "docker-compose.yml"), "down", "--volumes"], this.env(), this.dir, 30_000, this.logFile).catch((err) => log(`${this.name} Docker cleanup: ${err.message}`));+ for (const name of ["worker", "iii"]) { const pid = this.pid(name); if (pid) this.ownedPids.add(pid); }+ for (const row of this.wrapperStarts()) this.ownedPids.add(row.pid);+ for (const pid of this.ownedPids) kill(pid);+ await sleep(100);+ }+}+async function scenario(name, fn) {+ if (options.only && !options.only.has(name)) return;+ log(`RUN ${name}`); const at = Date.now(); const details = {}; let instance;+ try { instance = await new Instance(name).init(); await fn(instance, details); const status = details.skipped ? "skipped" : "pass"; results.push({ name, status, ms: Date.now() - at, details }); log(`${status.toUpperCase()} ${name}${details.skipped ? `: ${details.skipped}` : ""}`); }+ catch (err) { results.push({ name, status: "fail", ms: Date.now() - at, error: err.stack, details }); log(`FAIL ${name}: ${err.message}`); }+ finally { if (instance) await instance.close(); }+}+async function delayedConfigured(instance, details, { delayMs, earlyPid = false, adopt = false, args = [] } = {}) {+ const config = instance.config({ delayMs, earlyPid });+ if (adopt) await instance.startEngine(config);+ const at = Date.now(); instance.start(args); await instance.ready(delayMs + 25_000);+ details.readyMs = Date.now() - at; details.delayMs = delayMs; details.transport = "real pinned native engine and installed worker via custom delayed-import config";+ assert(details.readyMs >= delayMs - 1000, `Ready before configured worker delay: ${details.readyMs}`);+ const starts = instance.wrapperStarts(); assert.equal(starts.length, 1, "Configured worker launched more than once");+ assert.equal(instance.pid("worker"), starts[0].pid, "CLI imported a second worker instead of waiting for the configured worker");+ details.workerPid = starts[0].pid; details.enginePid = instance.pid("iii");+}+async function delayedSocket(instance, backendPort, delayMs) {+ const connections = new Set();+ let accepted = 0;+ const server = net.createServer((socket) => {+ accepted++; connections.add(socket); socket.pause();+ const timer = setTimeout(() => {+ if (socket.destroyed) return;+ const upstream = net.connect(backendPort, "127.0.0.1"); connections.add(upstream);+ upstream.on("connect", () => { socket.pipe(upstream); upstream.pipe(socket); socket.resume(); });+ upstream.on("error", () => socket.destroy()); socket.on("error", () => upstream.destroy());+ socket.on("close", () => upstream.destroy()); upstream.on("close", () => connections.delete(upstream));+ }, delayMs);+ socket.on("close", () => { clearTimeout(timer); connections.delete(socket); });+ socket.on("error", () => {});+ });+ server.closeAllConnections = () => { for (const socket of connections) socket.destroy(); };+ await new Promise((r) => server.listen(0, "127.0.0.1", r)); instance.handles.push(server);+ return { port: server.address().port, accepted: () => accepted };+}+async function fixtureServer(instance, livez) {+ let probes = 0;+ const server = http.createServer((req, res) => {+ if (req.url === "/agentmemory/livez") {+ probes++;+ if (probes === 1) { res.writeHead(404); res.end(); return; }+ livez(req, res, probes - 1); return;+ }+ res.writeHead(200, { "content-type": "application/json" }); res.end("{}");+ });+ await new Promise((r) => server.listen(instance.port, "127.0.0.1", r)); instance.handles.push(server);+ const sleeper = launch(process.execPath, ["-e", "setInterval(()=>{},1000)"], instance.env(), instance.dir);+ instance.ownedPids.add(sleeper.pid); writeFileSync(join(instance.runtime, "worker.pid"), String(sleeper.pid));+ instance.config({ worker: false });+ writeFileSync(join(instance.runtime, "engine-state.json"), JSON.stringify({ kind: "native", configPath: instance.envExtra.AGENTMEMORY_III_CONFIG, binPath: engine, restPort: instance.port, attached: true }));+ return { worker: sleeper, probes: () => probes };+}+async function expectFailure(instance, args, env, { budgetMs = 5000, message } = {}) {+ const at = Date.now(); const child = instance.start(args, env); const result = await exited(child, budgetMs);+ assert.notEqual(result.code, 0, `CLI incorrectly succeeded: ${child.text}`);+ if (message) assert(child.text.includes(message), `Missing ${message}: ${child.text.slice(-1500)}`);+ return { elapsedMs: Date.now() - at, exitCode: result.code };+}+function dockerFixture(instance, mode) {+ const fixtureBin = join(instance.dir, "fixture-bin"); mkdirSync(fixtureBin);+ const project = `agentmemory-${instance.port}`; const containerId = "startup-fixture-owned-container";+ const record = { Id: containerId, State: { Running: false }, Config: { Image: `iiidev/iii:${installed.dependencies["iii-sdk"]}`, Labels: { "com.docker.compose.project": project, "com.docker.compose.service": "iii-engine" } }, HostConfig: { PortBindings: { [`${instance.port}/tcp`]: [{ HostPort: String(instance.port) }] } }, Mounts: [{ Type: "bind", Source: instance.data, Destination: "/data" }] };+ const pidFile = join(instance.dir, "docker-stub.pid");+ const file = join(fixtureBin, "docker");+ writeFileSync(file, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nconst args=process.argv.slice(2);\nif(args[0]===${JSON.stringify(mode)}) { writeFileSync(${JSON.stringify(pidFile)},String(process.pid)); process.on('SIGTERM',()=>{}); setInterval(()=>{},1000); }\nelse if(args[0]==='inspect') console.log(${JSON.stringify(JSON.stringify([record]))});\nelse if(args.includes('ps')) console.log(${JSON.stringify(containerId)});\n`); chmodSync(file, 0o755);+ instance.envExtra.PATH = [fixtureBin, instance.env().PATH].join(delimiter);+ writeFileSync(join(instance.runtime, "engine-state.json"), JSON.stringify({ kind: "docker", schemaVersion: 2, composeFile: join(pkg, "docker-compose.yml"), projectName: project, engineVersion: installed.dependencies["iii-sdk"], restPort: instance.port, dataDir: instance.data, containerId, dataMountType: "bind", dataMountSource: instance.data, preserveContainer: mode === "inspect" }));+ return pidFile;+}+async function main() {+ await install();+ await scenario("slow-native", (i, d) => delayedConfigured(i, d, { delayMs: options.delayMs, earlyPid: true }));+ await scenario("configured-adoption", (i, d) => delayedConfigured(i, d, { delayMs: 8_000, adopt: true }));+ await scenario("unrelated-exec", async (i, d) => {+ const config = i.config({ worker: false });+ const other = join(i.dir, "unrelated-worker.mjs"); writeFileSync(other, "setInterval(()=>{},1000);\n");+ appendFileSync(config, ` - name: iii-exec\n config:\n exec:\n - ${process.execPath} ${other}\n`);+ const at = Date.now(); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }); await i.ready(8_000);+ d.readyMs = Date.now() - at; assert.equal(i.pid("worker"), i.cli.pid, "Unrelated exec prevented the CLI-owned worker from starting");+ d.transport = "real engine with unrelated iii-exec command plus installed CLI-owned worker";+ });+ await scenario("native-engine-timeout", async (i, d) => {+ i.config({ worker: false });+ const binary = join(i.runtime, "bin/iii"); const launchPid = join(i.dir, "launched-engine.pid");+ writeFileSync(binary, `#!${process.execPath}\nconst {writeFileSync}=require('node:fs');\nif(process.argv.includes('--version')) { console.log('iii ${installed.dependencies["iii-sdk"]}'); process.exit(0); }\nwriteFileSync(${JSON.stringify(launchPid)},String(process.pid));\nsetInterval(()=>{},1000);\n`); chmodSync(binary, 0o755);+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));+ const pid = Number(readFileSync(launchPid, "utf8")); i.ownedPids.add(pid); await poll("owned engine timeout cleanup", () => !alive(pid), 5_000);+ assert(!existsSync(join(i.runtime, "iii.pid"))); assert(!existsSync(join(i.runtime, "engine-state.json")));+ d.transport = "version-compatible engine executable fixture that stays alive without opening HTTP; actual installed CLI";+ });+ await scenario("untracked-native-adoption", async (i, d) => {+ const config = i.config({ worker: false }); const externalConfig = join(i.dir, "external-config.yaml");+ copyFileSync(config, externalConfig); rmSync(config); await i.startEngine(externalConfig);+ delete i.envExtra.AGENTMEMORY_III_CONFIG;+ rmSync(join(i.runtime, "engine-state.json")); rmSync(join(i.runtime, "iii.pid"));+ i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "3000" }); await i.ready(6_000);+ assert.equal(i.pid("worker"), i.cli.pid, "Untracked engine was assumed to own a configured worker");+ assert(alive(i.engine.pid)); d.transport = "real native engine without lifecycle metadata or AgentMemory exec config";+ });+ await scenario("cancel-owned-startup", async (i, d) => {+ i.config({ delayMs: 10_000, earlyPid: true }); i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });+ await poll("owned engine ready before cancellation", async () => i.pid("worker") && (await fetch(i.url, { signal: AbortSignal.timeout(500) })).status > 0, 5_000);+ const enginePid = i.pid("iii"); const workerPid = i.pid("worker");+ i.cli.kill("SIGINT"); const result = await exited(i.cli, 6_000); assert.equal(result.code, 130, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);+ await poll("cancelled owned process cleanup", () => !alive(enginePid) && !alive(workerPid), 5_000);+ d.exitCode = result.code; d.ownedEngineStopped = true;+ });+ await scenario("cancel-external-startup", async (i, d) => {+ await i.startEngine(i.config({ worker: false })); const proxy = await delayedSocket(i, i.port + 46023, 10_000);+ i.start(["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${proxy.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "15000" });+ await poll("worker connecting before cancellation", () => proxy.accepted() > 0, 5_000);+ i.cli.kill("SIGTERM"); const result = await exited(i.cli, 6_000); assert.equal(result.code, 143, `Cancellation result ${JSON.stringify(result)}: ${i.cli.text.slice(-800)}`);+ assert(alive(i.engine.pid), "Cancellation stopped an external engine"); d.exitCode = result.code; d.externalEnginePreserved = true;+ });+ await scenario("no-engine", async (i, d) => {+ await i.startEngine(i.config({ worker: false }));+ const socket = await delayedSocket(i, i.port + 46023, 3_000);+ const at = Date.now(); i.start(["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${socket.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "10000" });+ await i.ready(15_000); d.readyMs = Date.now() - at; d.delayedConnections = socket.accepted();+ assert(d.readyMs >= 3000); assert(d.delayedConnections > 0); assert(alive(i.engine.pid), "External engine stopped during no-engine startup");+ const worker = i.pid("worker");+ const duplicate = launch(process.execPath, [cli, "--no-engine", "--port", String(i.port)], i.env(), i.dir, i.logFile);+ const result = await exited(duplicate, 5_000); assert.notEqual(result.code, 0); assert(duplicate.text.includes("already running"));+ assert.equal(i.pid("worker"), worker); assert(alive(worker)); assert(alive(i.engine.pid));+ d.duplicateExitCode = result.code; d.transport = "real native engine and installed worker over delayed TCP proxy";+ });+ await scenario("no-engine-timeout", async (i, d) => {+ await i.startEngine(i.config({ worker: false }));+ const socket = await delayedSocket(i, i.port + 46023, 5_000);+ Object.assign(d, await expectFailure(i, ["--no-engine"], { III_ENGINE_URL: `ws://127.0.0.1:${socket.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));+ assert(alive(i.engine.pid), "Timeout stopped an externally owned engine");+ assert(!i.pid("worker") || !alive(i.pid("worker")), "Failed in-process worker left a live stale PID");+ d.externalEnginePreserved = true;+ });+ await scenario("inline-worker-fatal", async (i, d) => {+ i.config({ worker: false }); mkdirSync(join(i.runtime, "secret"));+ const child = i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "10000" });+ const enginePid = await poll("owned engine PID before worker initialization", () => i.pid("iii"), 3_000); i.ownedPids.add(enginePid);+ const result = await exited(child, 6_000); assert.equal(result.code, 1); assert(child.text.includes("[agentmemory] Fatal:"), "Fixture did not exercise the worker's fatal initialization path");+ await poll("fatal initialization engine cleanup", () => !alive(enginePid), 4_000);+ assert(!i.pid("iii")); assert(!i.pid("worker") || !alive(i.pid("worker")));+ d.exitCode = result.code; d.ownedEngineStopped = true; d.transport = "real engine and inline installed worker; secret path occupied by a directory causes initialization failure";+ });+ await scenario("native-worker-timeout", async (i, d) => {+ i.config({ delayMs: 5_000, earlyPid: true });+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { message: "0.3s" }));+ await poll("owned engine cleanup", () => (!i.pid("iii") || !alive(i.pid("iii"))) && (!i.pid("worker") || !alive(i.pid("worker"))), 5_000);+ assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Failed owned engine still serves REST");+ d.ownedEngineStopped = true;+ });+ await scenario("hung-livez-body", async (i, d) => {+ const f = await fixtureServer(i, (_req, res) => { res.writeHead(200, { "content-type": "application/json" }); res.write('{"viewerPort":'); });+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 2_000, message: "0.3s" }));+ assert(alive(f.worker.pid)); d.externalWorkerPreserved = true; d.probes = f.probes(); d.transport = "controlled HTTP headers with a stalled response body; external worker PID fixture";+ });+ await scenario("malformed-livez", async (i, d) => {+ const invalid = ["not json", JSON.stringify({ viewerPort: -1 }), JSON.stringify({ viewerPort: 0 }), JSON.stringify({ viewerPort: 65536 }), JSON.stringify({ viewerPort: 3000.5 }), JSON.stringify({ viewerSkipped: "true" }), JSON.stringify({ viewerPort: null, viewerSkipped: false })];+ const f = await fixtureServer(i, (_req, res, n) => { res.writeHead(200, { "content-type": "application/json" }); res.end(invalid[n - 1] ?? JSON.stringify({ viewerSkipped: true })); });+ i.start([], { AGENTMEMORY_READY_TIMEOUT_MS: "6000" });+ await poll("CLI readiness hint", () => i.cli.text.includes("REST API"), 7_000);+ assert(f.probes() >= invalid.length + 2, `Malformed readiness accepted after ${f.probes()} probes`); await i.ready(1_000); d.probes = f.probes(); d.invalidResponses = invalid.length; d.transport = "controlled readiness response fixture";+ });+ await scenario("env-file-and-precedence", async (i, d) => {+ const f = await fixtureServer(i, (_req, res) => { res.writeHead(503); res.end(); });+ writeFileSync(join(i.runtime, ".env"), "AGENTMEMORY_READY_TIMEOUT_MS=350\nAGENTMEMORY_ENGINE_READY_TIMEOUT_MS=1000\n");+ d.fromFile = await expectFailure(i, [], {}, { budgetMs: 2500, message: "0.35s" });+ d.shellOverride = await expectFailure(i, [], { AGENTMEMORY_READY_TIMEOUT_MS: "150" }, { budgetMs: 2000, message: "0.15s" });+ assert(alive(f.worker.pid)); d.transport = "controlled unready external worker fixture";+ });+ await scenario("invalid-timeouts", async (i, d) => {+ d.rejected = [];+ for (const key of ["AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", "AGENTMEMORY_READY_TIMEOUT_MS"]) {+ for (const value of ["", "0", "-1", "1.5", "NaN", "Infinity", "500ms", "3600001"]) {+ const result = await expectFailure(i, ["--no-engine"], { [key]: value }, { budgetMs: 2500, message: key });+ d.rejected.push({ key, value, ...result });+ assert(!existsSync(join(i.runtime, "worker.pid")), "Invalid timeout imported the worker");+ }+ }+ const ownership = await expectFailure(i, ["--no-engine"], { AGENTMEMORY_ENGINE_MANAGES_WORKER: "yes" }, { budgetMs: 2500, message: "AGENTMEMORY_ENGINE_MANAGES_WORKER" });+ d.invalidOwnership = ownership;+ const help = await command(process.execPath, [cli, "--help"], i.env({ AGENTMEMORY_READY_TIMEOUT_MS: "invalid" }), i.dir);+ assert(help.includes("Usage:"));+ });+ await scenario("doctor", async (i, d) => {+ i.config({ delayMs: 2_000, earlyPid: true });+ writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=15000\n");+ const at = Date.now();+ const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) });+ await poll("doctor worker ready", () => child.text.includes("Engine and agentmemory worker ready"), 30_000);+ const result = await exited(child, 10_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`); d.doctorExitCode = result.code;+ await i.ready(10_000, false, true); assert(alive(i.pid("worker")), "Doctor-owned worker stopped when doctor exited"); d.readyMs = Date.now() - at; d.transport = "real native engine, configured delayed worker, installed doctor --all";+ assert(d.readyMs >= 2000); assert.equal(i.wrapperStarts().length, 1);+ });+ await scenario("doctor-invalid-timeout", async (i, d) => {+ await i.startEngine(i.config({ worker: false }));+ writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=invalid\n");+ Object.assign(d, await expectFailure(i, ["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) }, { budgetMs: 10_000, message: "AGENTMEMORY_READY_TIMEOUT_MS" }));+ assert(alive(i.engine.pid), "Invalid doctor startup configuration stopped an existing engine");+ assert.equal(i.pid("iii"), i.engine.pid, "Invalid doctor configuration changed the external engine PID"); d.externalEnginePreserved = true;+ });+ await scenario("doctor-cli-worker", async (i, d) => {+ i.config({ worker: false });+ writeFileSync(join(i.runtime, ".env"), "LLM_PROVIDER=none\nAGENTMEMORY_READY_TIMEOUT_MS=15000\n");+ const child = i.start(["doctor", "--all"], { EDITOR: "/usr/bin/true", PATH: [join(i.runtime, "bin"), i.env().PATH].join(delimiter) });+ await poll("doctor detached worker ready", () => child.text.includes("Engine and agentmemory worker ready"), 30_000);+ const result = await exited(child, 10_000); assert(result.code === 0 || result.code === 1, `Doctor crashed: ${child.text.slice(-1000)}`);+ await i.ready(10_000, false, true); assert(alive(i.pid("worker")), "Doctor-owned worker stopped when doctor exited");+ assert.notEqual(i.pid("worker"), child.pid, "Doctor did not detach the CLI-owned worker");+ d.doctorExitCode = result.code; d.workerPid = i.pid("worker"); d.transport = "real native engine and installed detached worker created by doctor --all";+ });+ await scenario("hung-docker-start", async (i, d) => {+ const pidFile = dockerFixture(i, "start");+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { budgetMs: 3000 }));+ const pid = Number(readFileSync(pidFile, "utf8")); i.ownedPids.add(pid); assert(!alive(pid), "Timed-out Docker start subprocess survived");+ assert(existsSync(join(i.runtime, "engine-state.json")), "Docker command timeout discarded owned lifecycle metadata");+ d.transport = "Docker command fixture whose start subprocess ignores SIGTERM; actual installed CLI";+ });+ await scenario("hung-docker-inspect", async (i, d) => {+ const pidFile = dockerFixture(i, "inspect");+ Object.assign(d, await expectFailure(i, [], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "300" }, { budgetMs: 8_000, message: "cannot be verified" }));+ const pid = Number(readFileSync(pidFile, "utf8")); i.ownedPids.add(pid); assert(!alive(pid), "Timed-out Docker inspect subprocess survived");+ assert(existsSync(join(i.runtime, "engine-state.json"))); d.transport = "Docker inspect subprocess fixture ignoring SIGTERM; actual installed CLI";+ });+ await scenario("docker", async (i, d) => {+ let dockerBin;+ try { dockerBin = execFileSync("which", ["docker"], { encoding: "utf8" }).trim(); } catch { d.skipped = "Docker executable unavailable"; return; }+ let host;+ try { host = process.env.DOCKER_HOST ?? execFileSync(dockerBin, ["context", "inspect", "--format", '{{(index .Endpoints "docker").Host}}'], { encoding: "utf8" }).trim(); } catch { d.skipped = "Docker context unavailable"; return; }+ i.dockerBin = dockerBin;+ i.envExtra = { AGENTMEMORY_USE_DOCKER: "1", DOCKER_HOST: host, DOCKER_CONFIG: process.env.DOCKER_CONFIG ?? join(homedir(), ".docker"), PATH: [dirname(dockerBin), i.env().PATH].join(delimiter) };+ try { d.serverVersion = (await command(dockerBin, ["info", "--format", "{{.ServerVersion}}"], i.env(), i.dir, 10_000)).trim(); } catch { d.skipped = "Docker daemon unavailable"; return; }+ let project;+ for (let attempt = 0; attempt < 20; attempt++) {+ const candidate = `agentmemory-${i.port}`;+ const filter = `label=com.docker.compose.project=${candidate}`;+ const existing = await Promise.all([+ command(dockerBin, ["ps", "-aq", "--filter", filter], i.env(), i.dir),+ command(dockerBin, ["network", "ls", "-q", "--filter", filter], i.env(), i.dir),+ command(dockerBin, ["volume", "ls", "-q", "--filter", filter], i.env(), i.dir),+ ]);+ if (existing.every((value) => !value.trim())) { project = candidate; break; }+ i.port = await portBlock();+ }+ assert(project, "Could not reserve an unused Docker project");+ i.dockerProject = project;+ const at = Date.now(); i.start([], { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "15000" });+ await i.ready(90_000); d.freshReadyMs = Date.now() - at;+ const state = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); assert.equal(state.kind, "docker");+ const containerId = (await command(dockerBin, ["compose", "-p", i.dockerProject, "-f", join(pkg, "docker-compose.yml"), "ps", "-q", "iii-engine"], i.env(), i.dir)).trim(); assert(containerId);+ d.containerId = containerId;+ kill(i.cli.pid); await exited(i.cli, 3_000);+ await command(dockerBin, ["stop", "--time", "3", containerId], i.env(), i.dir, 15_000);+ const failedProxy = await delayedSocket(i, i.port + 46023, 10_000);+ d.stoppedRecoveryTimeout = await expectFailure(i, [], { III_ENGINE_URL: `ws://127.0.0.1:${failedProxy.port}`, AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 20_000, message: "0.3s" });+ const stopped = await command(dockerBin, ["inspect", "--format", "{{.State.Running}}", containerId], i.env(), i.dir); assert.equal(stopped.trim(), "false", "Failed recovery did not stop the container it restarted");+ assert.equal(JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")).containerId, containerId, "Failed Docker recovery lost lifecycle ownership");+ const proxy = await delayedSocket(i, i.port + 46023, 3_000);+ const restartAt = Date.now(); i.start([], { III_ENGINE_URL: `ws://127.0.0.1:${proxy.port}`, AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "30000", AGENTMEMORY_READY_TIMEOUT_MS: "15000" });+ await i.ready(30_000); d.recoveryReadyMs = Date.now() - restartAt;+ assert(d.recoveryReadyMs >= 3000); assert(proxy.accepted() > 0);+ const restored = JSON.parse(readFileSync(join(i.runtime, "engine-state.json"), "utf8")); assert.equal(restored.containerId, containerId);+ kill(i.cli.pid); await exited(i.cli, 3_000);+ const externalProxy = await delayedSocket(i, i.port + 46023, 10_000);+ d.runningEngineTimeout = await expectFailure(i, [], { III_ENGINE_URL: `ws://127.0.0.1:${externalProxy.port}`, AGENTMEMORY_READY_TIMEOUT_MS: "300" }, { budgetMs: 5_000, message: "0.3s" });+ const running = await command(dockerBin, ["inspect", "--format", "{{.State.Running}}", containerId], i.env(), i.dir); assert.equal(running.trim(), "true", "Failed attach stopped a preexisting running Docker engine");+ d.transport = "real Docker Compose pinned iii image; same owned container restarted; installed host worker over delayed TCP proxy";+ });+ await scenario("demo", async (i, d) => {+ i.config({ delayMs: 2_000, earlyPid: true }); const at = Date.now();+ const child = i.start(["demo", "--serve"], { AGENTMEMORY_READY_TIMEOUT_MS: "15000" });+ const result = await exited(child, 35_000); assert.equal(result.code, 0, child.text.slice(-1200)); assert(child.text.includes("demo complete"));+ d.completedMs = Date.now() - at; d.transport = "real native engine and installed demo command";+ assert(!(await fetch(i.url, { signal: AbortSignal.timeout(200) }).then(() => true).catch(() => false)), "Demo-owned engine survived teardown");+ });+}++for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.once(signal, () => {+ for (const i of instances) {+ for (const name of ["iii", "worker"]) kill(i.pid(name));+ for (const row of i.wrapperStarts()) kill(row.pid);+ for (const pid of i.ownedPids) kill(pid);+ if (i.dockerProject && !i.closed) {+ try { execFileSync(i.dockerBin, ["compose", "-p", i.dockerProject, "-f", join(pkg, "docker-compose.yml"), "down", "--volumes"], { env: i.env(), timeout: 30_000, stdio: "ignore" }); } catch {}+ }+ }+ for (const child of children) kill(child.pid);+ process.exit(130);+});+let fatal;+try { await main(); } catch (err) { fatal = err.stack; log(fatal); }+finally { for (const i of instances) await i.close(); for (const child of children) kill(child.pid); }+const unchanged = cliSha ? cliSha === sha(cli) && pkgSha === packageDigest() && artifactSha === sha(tarball) : false;+const summary = { ok: !fatal && unchanged && results.some((r) => r.status === "pass") && results.every((r) => r.status !== "fail"), version: installed?.version, enginePin: installed?.dependencies["iii-sdk"], tarball, tarballSha256: artifactSha, installedCliSha256: cliSha, installedPackageSha256: pkgSha, installedArtifactUnmodified: unchanged, node: process.version, platform: `${platform()}-${arch()}`, durationMs: Date.now() - started, root: options.keep ? root : undefined, scenarios: results, fatal };+writeFileSync(join(out, "summary.json"), JSON.stringify(summary, null, 2) + "\n");+log(`Summary: ${results.filter((r) => r.status === "pass").length}/${results.length} passed; ${join(out, "summary.json")}`);+if (!options.keep && !out.startsWith(`${root}/`)) rmSync(root, { recursive: true, force: true });+process.exit(summary.ok ? 0 : 1);diff --git a/src/cli.ts b/src/cli.tsindex d626a8c6..34e2c79e 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -71,13 +71,25 @@ import {} from "./cli/engine-launch.js";import { runtimeMetadataPath } from "./runtime-paths.js";import { createStartupStderrCapture } from "./cli/startup-stderr.js";+import {+ configStartsAgentmemoryWorker,+ probeEngine,+ probeWorker,+ startWorkerAndWait,+ startupDeadline,+ startupTimeoutMessage,+ startupTimeouts,+ waitForReadiness,+ withinStartupDeadline,+ type StartupDeadline,+} from "./cli/readiness.js";import {clearPersistedBuiltinConfig,engineFlushWaitMs,engineStateConfigPaths,renderEngineConfig,} from "./cli/engine-config.js";-import { SHUTDOWN_HARD_EXIT_MS } from "./shutdown.js";+import { SHUTDOWN_HARD_EXIT_MS, registerStartupCleanup, runStartupCleanup } from "./shutdown.js";import { consoleArgs, defaultConsolePort, parseConsoleArgs } from "./cli/console.js";import { processStatIsRunning } from "./cli/process-state.js";import { renderSplash } from "./cli/splash.js";@@ -255,6 +267,14 @@ Environment:AGENTMEMORY_III_CONFIG Engine config to start from (default: ./iii-config.yaml,then ~/.agentmemory/iii-config.yaml, then the bundledloopback-only config).+ AGENTMEMORY_ENGINE_READY_TIMEOUT_MS+ Engine readiness deadline in milliseconds (default 120000).+ AGENTMEMORY_READY_TIMEOUT_MS+ Worker readiness deadline in milliseconds (default 300000).+ Both deadlines accept integers from 1 through 3600000.+ AGENTMEMORY_ENGINE_MANAGES_WORKER+ true for custom engine-managed worker wrappers; false+ for CLI-managed workers. Unset detects direct worker commands.AGENTMEMORY_FOLLOWUP_WINDOW_SECONDSWindow (seconds) for the smart-search follow-up diagnostic(default 30). Long values overcount, short values undercount.@@ -459,36 +479,17 @@ function getEnginePort(): number {}async function isEngineRunning(): Promise<boolean> {- try {- await fetch(`${getBaseUrl()}/`, {- signal: AbortSignal.timeout(2000),- });- return true;- } catch {- return false;- }+ const result = await withinStartupDeadline(startupDeadline(2000), (signal) => probeEngine(getBaseUrl(), signal)).catch(() => null);+ return result?.completed === true && result.value;}async function isAgentmemoryReady(): Promise<boolean> {- try {- const res = await fetch(`${getBaseUrl()}/agentmemory/livez`, {- signal: AbortSignal.timeout(2000),- });- if (!res.ok) return false;- try {- const data = await res.json() as { viewerPort?: number | null; viewerSkipped?: boolean };- if (typeof data.viewerPort === "number") {- discoveredViewerPort = data.viewerPort;- return true;- }- if (data.viewerSkipped) return true;- return false;- } catch {- return false;- }- } catch {- return false;- }+ const result = await withinStartupDeadline(startupDeadline(2000), workerReadinessProbe).catch(() => null);+ return result?.completed === true && result.value;+}++function workerReadinessProbe(signal: AbortSignal): Promise<boolean> {+ return probeWorker(getBaseUrl(), signal, (port) => { discoveredViewerPort = port; });}function findIiiConfig(): string {@@ -767,36 +768,65 @@ function engineStateRestPort(state: EngineState): number {return 3111;}-async function startWorkerForEngineState(): Promise<void> {- const workerPid = readWorkerPidfile();- if (workerPid && pidAlive(workerPid)) return;- if (configuredEngineMayStartWorker() && await waitForConfiguredWorker(5000)) {- return;+async function startWorkerForEngineState(background = false): Promise<void> {+ const timeoutMs = startupTimeouts().workerMs;+ startupWorkerFailure = null;+ const ready = await startWorkerAndWait({+ timeoutMs,+ hasLiveWorker: () => {+ const workerPid = readWorkerPidfile();+ return Boolean(workerPid && pidAlive(workerPid));+ },+ engineStartsWorker: configuredEngineMayStartWorker,+ startWorker: async () => {+ if (background) {+ const builtEntry = join(__dirname, "index.mjs");+ const workerArgs = existsSync(builtEntry)+ ? [builtEntry]+ : ["--import", "tsx", join(__dirname, "index.ts")];+ const child = spawn(process.execPath, workerArgs, {+ detached: true,+ stdio: "ignore",+ windowsHide: true,+ env: { ...process.env },+ });+ spawnedStartupWorker = child;+ child.on("error", (error) => {+ if (spawnedStartupWorker === child) startupWorkerFailure = error;+ });+ child.on("exit", (code, signal) => {+ if (spawnedStartupWorker === child) startupWorkerFailure = new Error(`agentmemory worker exited during startup (${signal ?? code}).`);+ });+ child.unref();+ } else {+ importedStartupWorker = true;+ await import("./index.js");+ }+ },+ probe: workerReadinessProbe,+ stopped: () => startupInterrupted || engineStartupFailed() || startupWorkerFailure !== null,+ });+ if (!ready) {+ if (startupWorkerFailure) throw startupWorkerFailure;+ if (engineStartupFailed()) throw new Error("iii-engine exited before the agentmemory worker became ready.");+ throw new Error(startupTimeoutMessage("worker", timeoutMs));}- await import("./index.js");+ finishStartup();}function configuredEngineMayStartWorker(): boolean {+ const explicit = startupTimeouts().engineManagesWorker;+ if (explicit !== undefined) return explicit;const state = readEngineState();- if (state?.kind !== "native") return false;+ if (state?.kind !== "native" || state.attached) return false;try {const raw = readFileSync(state.configPath, "utf-8");- return raw.includes("- name: iii-exec");+ return configStartsAgentmemoryWorker(raw, join(__dirname, "index.mjs"));} catch {return false;}}-async function waitForConfiguredWorker(timeoutMs: number): Promise<boolean> {- const deadline = Date.now() + timeoutMs;- while (Date.now() < deadline) {- const workerPid = readWorkerPidfile();- if (workerPid && pidAlive(workerPid)) return true;- if (await isAgentmemoryReady()) return true;- await new Promise((resolve) => setTimeout(resolve, 100));- }- return false;-}function discoverComposeFile(): string | null {const candidates = [@@ -856,6 +886,8 @@ function inspectDockerContainer(encoding: "utf-8",stdio: ["ignore", "pipe", "ignore"],maxBuffer: 1024 * 1024,+ timeout: 5000,+ killSignal: "SIGKILL",});if (result.status !== 0) {return { status: "unavailable", reason: `docker inspect failed for ${containerId}` };@@ -1025,7 +1057,7 @@ function inspectOwnedDockerEngine(state: EngineState): DockerEngineInspection {"--all","iii-engine",]),- { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },+ { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, killSignal: "SIGKILL" },);if (psResult.status === 0) {for (const id of (psResult.stdout ?? "").trim().split(/\s+/)) {@@ -1052,7 +1084,7 @@ function inspectOwnedDockerEngine(state: EngineState): DockerEngineInspection {const scanResult = spawnSync(dockerBin,scanArgs,- { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },+ { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, killSignal: "SIGKILL" },);if (scanResult.status === 0) {for (const id of (scanResult.stdout ?? "").trim().split(/\s+/)) {@@ -1383,6 +1415,92 @@ type StartupFailure = {let startupFailure: StartupFailure | null = null;let activeStartupStderr = createStartupStderrCapture();+let spawnedNativeEngine: ChildProcess | null = null;+let importedStartupWorker = false;+let spawnedStartupWorker: ChildProcess | null = null;+let startupWorkerFailure: Error | null = null;+let spawnedDockerCommand: ChildProcess | null = null;+let startedDockerEngine: DockerEngineState | null = null;+let engineReadinessDeadline: StartupDeadline | null = null;+let startupInterrupted = false;+let finishStartup = (): void => {};++function beginStartup(): void {+ finishStartup();+ startupInterrupted = false;+ const unregister = registerStartupCleanup(cleanupFailedStartup);+ const interrupt = async (exitCode: number): Promise<void> => {+ startupInterrupted = true;+ process.exit(await runStartupCleanup(exitCode).catch(() => exitCode));+ };+ const onInterrupt = () => { void interrupt(130); };+ const onTerminate = () => { void interrupt(143); };+ process.on("SIGINT", onInterrupt);+ process.on("SIGTERM", onTerminate);+ finishStartup = () => {+ process.off("SIGINT", onInterrupt);+ process.off("SIGTERM", onTerminate);+ unregister();+ finishStartup = () => {};+ };+}++function engineStartupFailed(): boolean {+ return startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed";+}++async function cleanupFailedStartup(): Promise<void> {+ engineReadinessDeadline = null;+ if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();+ const worker = spawnedStartupWorker;+ spawnedStartupWorker = null;+ if (worker && typeof worker.pid === "number") {+ if (worker.exitCode === null && worker.signalCode === null && !(await signalAndWait(worker.pid, "SIGTERM", 3000))) {+ p.log.warn(`Started worker pid ${worker.pid} survived shutdown; lifecycle state was preserved.`);+ return;+ }+ if (readWorkerPidfile() === worker.pid) clearWorkerPidfile();+ }+ const dockerCommand = spawnedDockerCommand;+ spawnedDockerCommand = null;+ if (dockerCommand && typeof dockerCommand.pid === "number" && dockerCommand.exitCode === null && dockerCommand.signalCode === null) {+ await signalAndWait(dockerCommand.pid, "SIGTERM", 1000);+ }+ const dockerState = startedDockerEngine;+ startedDockerEngine = null;+ if (dockerState) {+ const inspection = inspectOwnedDockerEngine(dockerState);+ if (inspection.status === "running" || inspection.status === "stopped") {+ persistDockerInspection(dockerState, inspection);+ const dockerBin = whichBinary("docker");+ if (inspection.status === "running" && dockerBin) {+ runCommand(dockerBin, ["stop", "--time", "10", inspection.containerId], {+ label: "Stopping the Docker container started by this invocation",+ timeoutMs: 15_000,+ });+ }+ } else {+ p.log.warn("Docker startup ownership could not be verified for cleanup; project state was preserved for `agentmemory stop`.");+ }+ }+ const child = spawnedNativeEngine;+ spawnedNativeEngine = null;+ if (!child || typeof child.pid !== "number") return;+ if (!IS_WINDOWS) {+ try { process.kill(-child.pid, "SIGTERM"); } catch {}+ }+ if (child.exitCode === null && child.signalCode === null) {+ const stopped = await signalAndWait(child.pid, "SIGTERM", 3000);+ if (!stopped) {+ p.log.warn(`Started engine pid ${child.pid} survived shutdown; lifecycle state was preserved.`);+ return;+ }+ }+ if (readEnginePidfile() === child.pid) {+ clearEnginePidfile();+ clearEngineState();+ }+}function printCapturedStartupStderr(): void {const stderr = redactCredentialUrls(activeStartupStderr.text().trim());@@ -1410,6 +1528,7 @@ function printDockerStartupLogs(): void {encoding: "utf-8",stdio: ["ignore", "pipe", "pipe"],timeout: 5000,+ killSignal: "SIGKILL",maxBuffer: 64 * 1024,},);@@ -1429,6 +1548,8 @@ function spawnEngineBackground(): ChildProcess {vlog(`spawn: ${bin} ${spawnArgs.join(" ")}${cwd ? ` (cwd: ${cwd})` : ""}`);activeStartupStderr = createStartupStderrCapture();+ startupFailure = null;+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);const child = spawn(bin, spawnArgs, {detached: true,stdio: ["ignore", "ignore", "pipe"],@@ -1437,15 +1558,31 @@ function spawnEngineBackground(...(cwd ? { cwd } : {}),});const isDocker = label.includes("Docker");- if (!isDocker && typeof child.pid === "number") {- writeEnginePidfile(child.pid);- }+ if (isDocker) spawnedDockerCommand = child;+ if (!isDocker) {+ spawnedNativeEngine = child;+ if (typeof child.pid === "number") writeEnginePidfile(child.pid);+ }+ child.on("error", (error) => {+ if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;+ startupFailure = {+ kind: isDocker ? "docker-crashed" : "engine-crashed",+ stderr: redactCredentialUrls(error.message),+ binary: bin,+ };+ if (!isDocker && spawnedNativeEngine === child) {+ clearEnginePidfile();+ clearEngineState();+ }+ });child.stderr?.on("data", (chunk: Buffer) => {+ if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;activeStartupStderr.append(chunk);});+ (child.stderr as { unref?: () => void } | null)?.unref?.();child.on("exit", (code, signal) => {- const abnormal =- (code !== null && code !== 0) || (code === null && signal !== null);+ if ((isDocker ? spawnedDockerCommand : spawnedNativeEngine) !== child) return;+ const abnormal = !isDocker || (code !== null && code !== 0) || (code === null && signal !== null);if (abnormal) {const stderr = redactCredentialUrls(activeStartupStderr.text());startupFailure = {@@ -1461,7 +1598,7 @@ function spawnEngineBackground(if (IS_VERBOSE && stderr.trim()) {p.log.error(`engine stderr:\n${stderr}`);}- if (!isDocker) {+ if (!isDocker && readEnginePidfile() === child.pid) {clearEnginePidfile();clearEngineState();}@@ -1607,6 +1744,8 @@ function warnIfDockerIgnoresStateBackend(stateBackendKind: "file" | "redis"): vo}async function startEngine(): Promise<boolean> {+ startupFailure = null;+ engineReadinessDeadline = null;let stateBackendKind: "file" | "redis";try {stateBackendKind = getStateBackend();@@ -1638,12 +1777,13 @@ async function startEngine(): Promise<boolean> {persistDockerInspection(persistedState, inspection);if (inspection.status === "running") return true;const dockerBin = whichBinary("docker");- return Boolean(- dockerBin &&- runCommand(dockerBin, ["start", inspection.containerId], {- label: `Restarting owned Docker container ${inspection.containerId}`,- }),- );+ if (!dockerBin) return false;+ startedDockerEngine = persistDockerInspection(persistedState, inspection);+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);+ return runCommand(dockerBin, ["start", inspection.containerId], {+ label: `Restarting owned Docker container ${inspection.containerId}`,+ timeoutMs: startupTimeouts().engineMs,+ });}const configPath = findIiiConfig();warnIfRelocatedDataDir();@@ -1775,7 +1915,7 @@ async function startEngine(): Promise<boolean> {s.start("Starting iii-engine via Docker...");configureDockerHostUser();const projectName = dockerProjectName(getRestPort());- writeEngineState({+ const dockerState: DockerEngineState = {kind: "docker",schemaVersion: 2,composeFile,@@ -1784,7 +1924,14 @@ async function startEngine(): Promise<boolean> {dataMountType: "bind",dataMountSource: dataDirResolution.dataDir,preserveContainer: false,- });+ };+ const previous = inspectOwnedDockerEngine(dockerState);+ if (previous.status === "missing" || previous.status === "stopped") {+ startedDockerEngine = previous.status === "stopped"+ ? persistDockerInspection(dockerState, previous)+ : dockerState;+ }+ writeEngineState(dockerState);spawnEngineBackground(dockerBin,dockerComposeArgs(composeFile, projectName, ["up", "-d"]),@@ -1802,13 +1949,19 @@ async function startEngine(): Promise<boolean> {return false;}-async function waitForEngine(timeoutMs: number): Promise<boolean> {- const start = Date.now();- while (Date.now() - start < timeoutMs) {- if (await isEngineRunning()) return true;- await new Promise((r) => setTimeout(r, 500));- }- return false;+async function waitForEngine(timeoutMs = startupTimeouts().engineMs): Promise<boolean> {+ return waitForReadiness(engineReadinessDeadline ?? startupDeadline(timeoutMs), (signal) => probeEngine(getBaseUrl(), signal), {+ intervalMs: 500,+ stopped: () => startupInterrupted || engineStartupFailed(),+ });+}++async function waitForPersistedNativeEngine(): Promise<boolean> {+ const state = readEngineState();+ const pid = readEnginePidfile();+ if (state?.kind !== "native" || !pid || !pidAlive(pid) || isForeignPortHolder(pidCommand(pid))) return false;+ if (!(await waitForEngine())) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));+ return true;}async function reconcilePersistedDockerEngine(): Promise<boolean> {@@ -1829,29 +1982,24 @@ async function reconcilePersistedDockerEngine(): Promise<boolean> {}persistDockerInspection(state, inspection);if (inspection.status === "stopped") {+ startedDockerEngine = persistDockerInspection(state, inspection);+ engineReadinessDeadline = startupDeadline(startupTimeouts().engineMs);const dockerBin = whichBinary("docker");if (!dockerBin ||!runCommand(dockerBin, ["start", inspection.containerId], {label: `Restarting owned Docker container ${inspection.containerId}`,+ timeoutMs: startupTimeouts().engineMs,})) {- p.log.error("The owned Docker container could not be restarted; lifecycle state was preserved.");- process.exit(1);+ throw new Error("The owned Docker container could not be restarted; lifecycle state was preserved.");}}- if (!(await waitForEngine(5000))) {+ if (!(await waitForEngine())) {printDockerStartupLogs();- p.log.error(- `The owned Docker container is running, but its REST API on port ${getRestPort()} is unhealthy. The saved project was preserved; inspect the Docker logs above or run \`agentmemory stop\`.`,- );- process.exit(1);+ throw new Error(`${startupTimeoutMessage("engine", startupTimeouts().engineMs)} Docker ownership state was preserved.`);}await startWorkerForEngineState();- if (!(await waitForAgentmemoryReady(15000))) {- p.log.error("agentmemory worker did not become ready within 15s.");- process.exit(1);- }await maybeOfferGlobalInstall();printReadyHint();return true;@@ -1907,14 +2055,6 @@ function portInUseDiagnostic(port: number): string {: ` lsof -i :${port} # or: ss -tlnp | grep :${port}`;}-async function waitForAgentmemoryReady(timeoutMs: number): Promise<boolean> {- const start = Date.now();- while (Date.now() - start < timeoutMs) {- if (await isAgentmemoryReady()) return true;- await new Promise((r) => setTimeout(r, 250));- }- return false;-}// Derive a host string for the streams/engine WebSocket lines from// the configured engine URL (`III_ENGINE_URL`) or REST base@@ -1970,6 +2110,7 @@ function printReadyHint(): void {}async function main() {+ startupTimeouts();await assertRuntimePortOwnership();// Booting a second instance next to a live daemon registers a duplicate// worker on the running engine, and before iii 0.19.2 the second instance's@@ -2011,19 +2152,19 @@ async function main() {await runOnboarding();}+ beginStartup();+if (skipEngine) {if (IS_VERBOSE) p.log.info("Skipping engine check (--no-engine)");- await import("./index.js");- if (await waitForAgentmemoryReady(15000)) {- await maybeOfferGlobalInstall();- printReadyHint();- }+ await startWorkerForEngineState();+ await maybeOfferGlobalInstall();+ printReadyHint();return;}if (await reconcilePersistedDockerEngine()) return;- if (await isEngineRunning()) {+ if (await isEngineRunning() || await waitForPersistedNativeEngine()) {if (IS_VERBOSE) p.log.success("iii-engine is running");// Prefer the binary path persisted at launch time over whatever's on// PATH now. PATH lookups misfire when a global iii install gets added@@ -2050,10 +2191,6 @@ async function main() {if (detected === IIPINNED_VERSION) {adoptRunningEngine();await startWorkerForEngineState();- if (!(await waitForAgentmemoryReady(15000))) {- p.log.error("agentmemory worker did not become ready within 15s.");- process.exit(1);- }await maybeOfferGlobalInstall();printReadyHint();return;@@ -2106,16 +2243,16 @@ async function main() {);}p.note(lines.join("\n"), "Setup required");- process.exit(1);+ throw new Error("iii-engine could not be started.");}const s = p.spinner();s.start("Waiting for iii-engine to be ready...");- const ready = await waitForEngine(15000);+ const ready = await waitForEngine();if (!ready) {const port = getRestPort();- s.stop("iii-engine did not become ready within 15s");+ s.stop(startupTimeoutMessage("engine", startupTimeouts().engineMs));printDockerStartupLogs();if (startupFailure?.kind === "engine-crashed" || startupFailure?.kind === "docker-crashed") {@@ -2156,15 +2293,11 @@ async function main() {"Troubleshooting",);}- process.exit(1);+ throw new Error(engineStartupFailed() ? "iii-engine failed during startup." : startupTimeoutMessage("engine", startupTimeouts().engineMs));}s.stop(c.ok("iii-engine is ready"));await startWorkerForEngineState();- if (!(await waitForAgentmemoryReady(15000))) {- p.log.error("agentmemory worker did not become ready within 15s.");- process.exit(1);- }await maybeOfferGlobalInstall();printReadyHint();// Mark splash as something to skip on subsequent runs. This is a@@ -2440,6 +2573,7 @@ function buildDoctorEffects(): DoctorEffects {},runStop: async () => {try {+ startupTimeouts();// runStop calls process.exit on its own — guard against that here// by short-circuiting when there's nothing to stop.const port = getRestPort();@@ -2473,14 +2607,16 @@ function buildDoctorEffects(): DoctorEffects {},runStart: async () => {try {+ startupTimeouts();+ beginStartup();const started = await startEngine();- if (!started) return { ok: false, message: "startEngine() returned false" };- const ready = await waitForEngine(15000);- return {- ok: ready,- message: ready ? "Engine ready" : "Engine did not become ready within 15s",- };+ if (!started) throw new Error("iii-engine could not be started.");+ if (!(await waitForEngine())) throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));+ await startWorkerForEngineState(true);+ return { ok: true, message: "Engine and agentmemory worker ready" };} catch (err) {+ await runStartupCleanup(1);+ finishStartup();return {ok: false,message: err instanceof Error ? err.message : String(err),@@ -2978,50 +3114,34 @@ async function runInit() {}async function startServerForDemo(): Promise<() => Promise<void>> {+ startupTimeouts();await assertRuntimePortOwnership();if (await isAgentmemoryReady()) {return async () => {};}- const startedEngine = !(await isEngineRunning());+ beginStartup();++ const startedEngine = !skipEngine && !(await isEngineRunning() || await waitForPersistedNativeEngine());if (startedEngine) {const ok = await startEngine();if (!ok) {p.log.error("Could not start iii-engine for the demo.");p.note(installInstructions().join("\n"), "Setup required");- process.exit(1);+ throw new Error("iii-engine could not be started for the demo.");}- if (!(await waitForEngine(15000))) {+ if (!(await waitForEngine())) {printCapturedStartupStderr();printDockerStartupLogs();- p.log.error("iii-engine did not become ready within 15s.");- process.exit(1);+ throw new Error(startupTimeoutMessage("engine", startupTimeouts().engineMs));}}await startWorkerForEngineState();- if (!(await waitForAgentmemoryReady(15000))) {- p.log.error("agentmemory worker did not become ready within 15s.");- process.exit(1);- }return async () => {- if (!startedEngine) return;- const port = getRestPort();- const state = readEngineState();- if (state?.kind === "docker") {- await stopDockerEngine(state, port).catch(() => {});- return;- }- const pids = new Set<number>(findEnginePidsByPort(port));- const pidfilePid = readEnginePidfile();- if (pidfilePid) pids.add(pidfilePid);- for (const pid of pids) {- await signalAndWait(pid, "SIGTERM", 3000).catch(() => {});- }- clearEnginePidfile();- clearEngineState();- clearWorkerPidfile();+ if (importedStartupWorker && readWorkerPidfile() === process.pid) clearWorkerPidfile();+ if (startedEngine) await cleanupFailedStartup();};}@@ -3123,7 +3243,7 @@ async function runDemoBody(base: string) {function runCommand(command: string,commandArgs: string[],- options: { cwd?: string; label: string; optional?: boolean } = { label: "command" },+ options: { cwd?: string; label: string; optional?: boolean; timeoutMs?: number } = { label: "command" },): boolean {const spinner = p.spinner();spinner.start(options.label);@@ -3131,6 +3251,7 @@ function runCommand(cwd: options.cwd || process.cwd(),stdio: "pipe",encoding: "utf-8",+ ...(options.timeoutMs !== undefined ? { timeout: options.timeoutMs, killSignal: "SIGKILL" as const } : {}),});if (result.status === 0) {@@ -4136,7 +4257,8 @@ async function unknownCommand(): Promise<void> {// `agentmemory consolidate`) fell through to the full server boot and could// break a running daemon.const handler = commands[first] ?? (first && !first.startsWith("-") ? unknownCommand : main);-handler().catch((err) => {+handler().catch(async (err) => {p.log.error(err instanceof Error ? err.message : String(err));- process.exit(1);+ const exitCode = await runStartupCleanup(1).catch(() => 1);+ process.exit(exitCode);});diff --git a/src/cli/readiness.ts b/src/cli/readiness.tsnew file mode 100644index 00000000..e7ca0fb9--- /dev/null+++ b/src/cli/readiness.ts@@ -0,0 +1,173 @@+export const DEFAULT_ENGINE_TIMEOUT_MS = 120_000;+export const DEFAULT_WORKER_TIMEOUT_MS = 300_000;+export const MAX_STARTUP_TIMEOUT_MS = 3_600_000;++export function startupTimeouts(env: NodeJS.ProcessEnv = process.env): {+ engineMs: number;+ workerMs: number;+ engineManagesWorker: boolean | undefined;+} {+ const parse = (key: string, fallback: number): number => {+ const raw = env[key];+ if (raw === undefined) return fallback;+ const value = Number(raw);+ if (!/^\d+$/.test(raw) || !Number.isSafeInteger(value) || value < 1 || value > MAX_STARTUP_TIMEOUT_MS) {+ throw new Error(`${key} must be an integer between 1 and ${MAX_STARTUP_TIMEOUT_MS} milliseconds.`);+ }+ return value;+ };+ const ownership = env.AGENTMEMORY_ENGINE_MANAGES_WORKER;+ if (ownership !== undefined && ownership !== "true" && ownership !== "false") {+ throw new Error("AGENTMEMORY_ENGINE_MANAGES_WORKER must be true or false.");+ }+ return {+ engineMs: parse("AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", DEFAULT_ENGINE_TIMEOUT_MS),+ workerMs: parse("AGENTMEMORY_READY_TIMEOUT_MS", DEFAULT_WORKER_TIMEOUT_MS),+ engineManagesWorker: ownership === undefined ? undefined : ownership === "true",+ };+}++export function configStartsAgentmemoryWorker(raw: string, workerEntry: string): boolean {+ const lines = raw.split(/\r?\n/);+ let workerIndent: number | undefined;+ let execIndent: number | undefined;+ for (const line of lines) {+ if (!line.trim() || line.trimStart().startsWith("#")) continue;+ const indent = line.length - line.trimStart().length;+ if (workerIndent !== undefined && indent <= workerIndent) {+ workerIndent = undefined;+ execIndent = undefined;+ }+ if (/^\s*-\s+name:\s*(?:iii-exec|"iii-exec"|'iii-exec')(?:\s+#.*)?\s*$/.test(line)) {+ workerIndent = indent;+ continue;+ }+ if (workerIndent === undefined) continue;+ if (execIndent !== undefined && indent <= execIndent) execIndent = undefined;+ if (/^\s*exec:\s*(?:#.*)?$/.test(line)) {+ execIndent = indent;+ continue;+ }+ if (execIndent === undefined) continue;+ const scalar = line.match(/^\s*-\s+(.+)$/)?.[1]?.trim();+ if (!scalar) continue;+ const quoted = scalar.match(/^(["'])(.*?)\1(?:\s+#.*)?$/);+ const command = quoted ? quoted[2]! : scalar;+ const tokens = command.match(/"[^"]*"|'[^']*'|[^\s]+/g)?.map((token) => token.replace(/^("|')(.*)\1$/, "$2").replaceAll("\\", "/"));+ if (!tokens) continue;+ const comment = tokens.findIndex((token) => token.startsWith("#"));+ if (comment !== -1) tokens.splice(comment);+ const runtime = tokens[0]?.split("/").at(-1);+ if (runtime !== "node" && runtime !== "node.exe" && runtime !== "tsx") continue;+ if (runtime !== "tsx") {+ while (tokens[1] && /^(?:--max[-_]old[-_]space[-_]size=\d+|--enable-source-maps|--no-warnings)$/.test(tokens[1])) tokens.splice(1, 1);+ }+ const entry = tokens.length === 2+ ? tokens[1]+ : tokens.length === 4 && tokens[1] === "--import" && tokens[2] === "tsx" ? tokens[3] : undefined;+ if (entry === workerEntry.replaceAll("\\", "/") || entry === "dist/index.mjs" || entry === "./dist/index.mjs" || entry === "src/index.ts" || entry === "./src/index.ts") return true;+ }+ return false;+}++export function startupTimeoutMessage(kind: "engine" | "worker", timeoutMs: number): string {+ const name = kind === "engine" ? "iii-engine" : "agentmemory worker";+ const variable = kind === "engine" ? "AGENTMEMORY_ENGINE_READY_TIMEOUT_MS" : "AGENTMEMORY_READY_TIMEOUT_MS";+ return `${name} did not become ready within ${timeoutMs / 1000}s. Set ${variable} to allow more startup time.`;+}++export interface StartupDeadline {+ remaining(): number;+}++export function startupDeadline(timeoutMs: number): StartupDeadline {+ const deadline = performance.now() + timeoutMs;+ return { remaining: () => Math.max(0, deadline - performance.now()) };+}++export async function withinStartupDeadline<T>(+ deadline: StartupDeadline,+ work: (signal: AbortSignal) => Promise<T>,+ maximumMs = Infinity,+): Promise<{ completed: true; value: T } | { completed: false }> {+ const remaining = Math.min(deadline.remaining(), maximumMs);+ if (remaining <= 0) return { completed: false };+ const controller = new AbortController();+ let timer: ReturnType<typeof setTimeout> | undefined;+ const expired = new Promise<{ completed: false }>((resolve) => {+ timer = setTimeout(() => {+ controller.abort();+ resolve({ completed: false });+ }, Math.ceil(remaining));+ });+ try {+ const result = await Promise.race([+ Promise.resolve().then(() => work(controller.signal)).then((value) => ({ completed: true as const, value })),+ expired,+ ]);+ return deadline.remaining() > 0 ? result : { completed: false };+ } finally {+ clearTimeout(timer);+ controller.abort();+ }+}++export async function waitForReadiness(+ deadline: StartupDeadline,+ probe: (signal: AbortSignal) => Promise<boolean>,+ options: { intervalMs?: number; stopped?: () => boolean } = {},+): Promise<boolean> {+ while (deadline.remaining() > 0 && !options.stopped?.()) {+ const result = await withinStartupDeadline(deadline, probe, 2000).catch(() => ({ completed: false as const }));+ if (options.stopped?.()) return false;+ if (result.completed && result.value) return true;+ const remaining = deadline.remaining();+ if (remaining <= 0) break;+ await new Promise((resolve) => setTimeout(resolve, Math.min(options.intervalMs ?? 250, remaining)));+ }+ return false;+}++export async function probeEngine(base: string, signal: AbortSignal): Promise<boolean> {+ const response = await fetch(`${base}/`, { signal });+ void response.body?.cancel().catch(() => {});+ // The engine's root path is normally 404 until the worker registers routes.+ return true;+}++export async function probeWorker(+ base: string,+ signal: AbortSignal,+ onViewerPort?: (port: number) => void,+): Promise<boolean> {+ const response = await fetch(`${base}/agentmemory/livez`, { signal });+ if (!response.ok) {+ void response.body?.cancel().catch(() => {});+ return false;+ }+ const data: unknown = await response.json();+ if (!data || typeof data !== "object" || Array.isArray(data)) return false;+ const { viewerPort, viewerSkipped } = data as { viewerPort?: unknown; viewerSkipped?: unknown };+ if (typeof viewerPort === "number" && Number.isInteger(viewerPort) && viewerPort > 0 && viewerPort <= 65535) {+ onViewerPort?.(viewerPort);+ return true;+ }+ return viewerSkipped === true;+}++export async function startWorkerAndWait(options: {+ timeoutMs: number;+ hasLiveWorker: () => boolean;+ engineStartsWorker: () => boolean;+ startWorker: () => Promise<unknown>;+ probe: (signal: AbortSignal) => Promise<boolean>;+ stopped?: () => boolean;+}): Promise<boolean> {+ const deadline = startupDeadline(options.timeoutMs);+ if (options.stopped?.()) return false;+ if (!options.hasLiveWorker() && !options.engineStartsWorker()) {+ const started = await withinStartupDeadline(deadline, () => options.startWorker());+ if (!started.completed) return false;+ }+ return waitForReadiness(deadline, options.probe, { stopped: options.stopped });+}diff --git a/src/index.ts b/src/index.tsindex 08dbb3a0..eca1b13c 100644--- a/src/index.ts+++ b/src/index.ts@@ -33,7 +33,7 @@ import { VectorIndex } from "./state/vector-index.js";import type { SearchLayer } from "./state/search-layer.js";import { HybridSearch } from "./state/hybrid-search.js";import { IndexPersistence } from "./state/index-persistence.js";-import { SHUTDOWN_FLUSH_TIMEOUT_MS, SHUTDOWN_HARD_EXIT_MS, settleWithin } from "./shutdown.js";+import { SHUTDOWN_FLUSH_TIMEOUT_MS, SHUTDOWN_HARD_EXIT_MS, runStartupCleanup, settleWithin } from "./shutdown.js";import { registerPrivacyFunction, withWriteScrubbing } from "./functions/privacy.js";import { registerObserveFunction } from "./functions/observe.js";import { registerCaptureFunctions } from "./functions/capture.js";@@ -749,12 +749,12 @@ async function main() {const shutdown = async () => {console.log(`\n[agentmemory] Shutting down...`);- const hardExit = setTimeout(() => {+ const hardExit = setTimeout(async () => {console.warn(`[agentmemory] Shutdown still blocked after ${SHUTDOWN_HARD_EXIT_MS}ms; exiting now.`,);clearWorkerPidfile();- process.exit(1);+ process.exit(await runStartupCleanup(1).catch(() => 1));}, SHUTDOWN_HARD_EXIT_MS);hardExit.unref();healthMonitor.stop();@@ -779,13 +779,13 @@ async function main() {console.warn(`[agentmemory] SDK shutdown failed:`, err);});clearWorkerPidfile();- process.exit(0);+ process.exit(await runStartupCleanup(0).catch(() => 1));};process.on("SIGINT", shutdown);process.on("SIGTERM", shutdown);}-main().catch((err) => {+main().catch(async (err) => {console.error(`[agentmemory] Fatal:`, err);- process.exit(1);+ process.exit(await runStartupCleanup(1).catch(() => 1));});diff --git a/src/shutdown.ts b/src/shutdown.tsindex 512d5a58..461c4b9c 100644--- a/src/shutdown.ts+++ b/src/shutdown.ts@@ -1,6 +1,33 @@export const SHUTDOWN_FLUSH_TIMEOUT_MS = 4000;export const SHUTDOWN_HARD_EXIT_MS = 8000;+interface StartupCleanup {+ cleanup: () => Promise<void>;+ pending?: Promise<void>;+ exitCode?: number;+}++// The CLI and worker are built separately, but share startup ownership in one process.+const STARTUP_CLEANUP = Symbol.for("@agentmemory/startup-cleanup");+const startupGlobal = globalThis as typeof globalThis & { [STARTUP_CLEANUP]?: StartupCleanup };++export function registerStartupCleanup(cleanup: () => Promise<void>): () => void {+ const state: StartupCleanup = { cleanup };+ startupGlobal[STARTUP_CLEANUP] = state;+ return () => {+ if (startupGlobal[STARTUP_CLEANUP] === state) delete startupGlobal[STARTUP_CLEANUP];+ };+}++export async function runStartupCleanup(exitCode: number): Promise<number> {+ const state = startupGlobal[STARTUP_CLEANUP];+ if (!state) return exitCode;+ state.exitCode ??= exitCode;+ state.pending ??= Promise.resolve().then(state.cleanup);+ await state.pending;+ return state.exitCode;+}+export async function settleWithin(work: Promise<unknown>,ms: number,diff --git a/test/cli-engine-startup.test.ts b/test/cli-engine-startup.test.tsindex cdade606..b091484d 100644--- a/test/cli-engine-startup.test.ts+++ b/test/cli-engine-startup.test.ts@@ -30,13 +30,13 @@ describe("fresh native engine startup", () => {);expect(spawnBody).toContain("activeStartupStderr.append(chunk)");- const timeoutStart = source.indexOf("const ready = await waitForEngine(15000)");+ const timeoutStart = source.indexOf("const ready = await waitForEngine()");const timeoutEnd = source.indexOf('s.stop(c.ok("iii-engine is ready"))', timeoutStart);expect(source.slice(timeoutStart, timeoutEnd)).toContain("printCapturedStartupStderr()",);- const demoTimeoutStart = source.indexOf("await waitForEngine(15000)", timeoutEnd);+ const demoTimeoutStart = source.indexOf("await waitForEngine()", timeoutEnd);const demoTimeoutEnd = source.indexOf("await import(\"./index.js\")", demoTimeoutStart);expect(source.slice(demoTimeoutStart, demoTimeoutEnd)).toContain("printCapturedStartupStderr()",@@ -88,11 +88,13 @@ describe("fresh native engine startup", () => {const workerBody = source.slice(workerStart, workerEnd);expect(workerBody).toContain("readWorkerPidfile()");expect(workerBody).toContain("pidAlive(workerPid)");- expect(workerBody).toContain("waitForConfiguredWorker");+ expect(workerBody).toContain("startWorkerAndWait");+ expect(workerBody).toContain("engineStartsWorker: configuredEngineMayStartWorker");expect(workerBody).toContain('await import("./index.js")');- expect(source.match(/await startWorkerForEngineState\(\)/g)).toHaveLength(4);- expect(source).toContain("agentmemory worker did not become ready within 15s");+ expect(source.match(/await startWorkerForEngineState\(\)/g)).toHaveLength(5);+ expect(source).toContain('startupTimeoutMessage("worker", timeoutMs)');+ expect(source).not.toContain("waitForAgentmemoryReady(15000)");});it("stores lifecycle metadata per resolved instance and scopes Docker", () => {@@ -125,7 +127,7 @@ describe("fresh native engine startup", () => {const mainBody = source.slice(mainStart, mainEnd);expect(mainBody).toContain("reconcilePersistedDockerEngine()");expect(mainBody.indexOf("reconcilePersistedDockerEngine()"))- .toBeLessThan(mainBody.indexOf("if (await isEngineRunning())"));+ .toBeLessThan(mainBody.indexOf("if (await isEngineRunning() ||"));});it("keeps canonical compatibility and rejects Docker ownership on another port", () => {diff --git a/test/cli-readiness.test.ts b/test/cli-readiness.test.tsnew file mode 100644index 00000000..13f7c578--- /dev/null+++ b/test/cli-readiness.test.ts@@ -0,0 +1,250 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import {+ configStartsAgentmemoryWorker,+ probeEngine,+ probeWorker,+ startWorkerAndWait,+ startupDeadline,+ startupTimeoutMessage,+ startupTimeouts,+ waitForReadiness,+ withinStartupDeadline,+} from "../src/cli/readiness.js";++afterEach(() => {+ vi.useRealTimers();+ vi.unstubAllGlobals();+});++function fakeTime(): void {+ vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "performance", "Date"] });+}++async function advance<T>(promise: Promise<T>, ms: number): Promise<T> {+ await vi.advanceTimersByTimeAsync(ms);+ return promise;+}++const forever = <T>(): Promise<T> => new Promise(() => {});++function workerOptions(overrides: Partial<Parameters<typeof startWorkerAndWait>[0]> = {}) {+ return {+ timeoutMs: 1000,+ hasLiveWorker: () => false,+ engineStartsWorker: () => false,+ startWorker: vi.fn(async () => {}),+ probe: vi.fn(async () => true),+ ...overrides,+ };+}++describe("startup configuration", () => {+ it("uses separate bounded engine and worker defaults", () => {+ expect(startupTimeouts({})).toEqual({ engineMs: 120_000, workerMs: 300_000, engineManagesWorker: undefined });+ });++ it("reads runtime values on each call, including both boundaries", () => {+ const env = { AGENTMEMORY_ENGINE_READY_TIMEOUT_MS: "1", AGENTMEMORY_READY_TIMEOUT_MS: "3600000" };+ expect(startupTimeouts(env)).toMatchObject({ engineMs: 1, workerMs: 3_600_000 });+ env.AGENTMEMORY_ENGINE_READY_TIMEOUT_MS = "48000";+ expect(startupTimeouts(env).engineMs).toBe(48_000);+ });++ it.each(["", " ", "0", "-1", "1.5", "15s", "12abc", "1e3", "NaN", "Infinity", "3600001", "9007199254740993"])("rejects invalid timeout %j for either phase", (value) => {+ for (const key of ["AGENTMEMORY_ENGINE_READY_TIMEOUT_MS", "AGENTMEMORY_READY_TIMEOUT_MS"]) {+ expect(() => startupTimeouts({ [key]: value })).toThrow(`${key} must be an integer`);+ }+ });++ it("accepts explicit worker ownership and rejects ambiguous boolean values", () => {+ expect(startupTimeouts({ AGENTMEMORY_ENGINE_MANAGES_WORKER: "true" }).engineManagesWorker).toBe(true);+ expect(startupTimeouts({ AGENTMEMORY_ENGINE_MANAGES_WORKER: "false" }).engineManagesWorker).toBe(false);+ for (const value of ["", "1", "yes", "TRUE"]) {+ expect(() => startupTimeouts({ AGENTMEMORY_ENGINE_MANAGES_WORKER: value })).toThrow("must be true or false");+ }+ });++ it("reports the configured duration and correct setting in failures", () => {+ expect(startupTimeoutMessage("worker", 48_050)).toContain("48.05s. Set AGENTMEMORY_READY_TIMEOUT_MS");+ expect(startupTimeoutMessage("engine", 120_000)).toContain("120s. Set AGENTMEMORY_ENGINE_READY_TIMEOUT_MS");+ });+});++describe("configured worker ownership", () => {+ const config = (command: string) => `workers:\n - name: iii-exec\n config:\n exec:\n - ${command}\n - name: iii-http\n config:\n port: 3111\n`;+ it.each(["node dist/index.mjs", "node ./dist/index.mjs", "node --import tsx src/index.ts", "tsx ./src/index.ts", '"node dist/index.mjs"', "node dist/index.mjs # worker", '"node dist/index.mjs" # worker', "node --max-old-space-size=8192 dist/index.mjs", '\'/opt/node /package/dist/index.mjs\''])("recognizes a direct worker command: %s", (command) => {+ expect(configStartsAgentmemoryWorker(config(command), "/package/dist/index.mjs")).toBe(true);+ });+ it.each(["node other.mjs", "node delayed-wrapper.mjs", "echo node dist/index.mjs", "sh -c 'node dist/index.mjs'", "node dist/index.mjs && something", "node dist/index.mjs.fake"])("does not claim unrelated or wrapped command: %s", (command) => {+ expect(configStartsAgentmemoryWorker(config(command), "/package/dist/index.mjs")).toBe(false);+ });+ it("ignores comments, other workers and sibling configuration lists", () => {+ const raw = `# - name: iii-exec\n# exec:\n# - node dist/index.mjs\n - name: iii-state\n config:\n exec:\n - node dist/index.mjs\n - name: iii-exec\n config:\n exec:\n - node other.mjs\n watch:\n - node dist/index.mjs\n`;+ expect(configStartsAgentmemoryWorker(raw, "/package/dist/index.mjs")).toBe(false);+ });+});++describe("readiness deadlines", () => {+ it("aborts a hung probe at the remaining budget, without a trailing retry sleep", async () => {+ fakeTime();+ let signal: AbortSignal | undefined;+ const probe = vi.fn(async (value: AbortSignal) => { signal = value; return forever<boolean>(); });+ const pending = waitForReadiness(startupDeadline(25), probe);+ expect(await advance(pending, 25)).toBe(false);+ expect(performance.now()).toBe(25);+ expect(signal?.aborted).toBe(true);+ expect(probe).toHaveBeenCalledTimes(1);+ expect(vi.getTimerCount()).toBe(0);+ });++ it("caps individual probes and keeps retries within the total budget", async () => {+ fakeTime();+ const probe = vi.fn(() => forever<boolean>());+ expect(await advance(waitForReadiness(startupDeadline(3000), probe), 3000)).toBe(false);+ expect(probe).toHaveBeenCalledTimes(2);+ expect(performance.now()).toBe(3000);+ expect(vi.getTimerCount()).toBe(0);+ });++ it("includes response body consumption in the probe budget", async () => {+ fakeTime();+ vi.stubGlobal("fetch", vi.fn(async () => ({ ok: true, json: () => forever() })));+ const pending = waitForReadiness(startupDeadline(25), (signal) => probeWorker("http://local", signal));+ expect(await advance(pending, 25)).toBe(false);+ expect(vi.getTimerCount()).toBe(0);+ });++ it("retries errors and malformed responses before accepting viewerSkipped", async () => {+ fakeTime();+ const fetchMock = vi.fn()+ .mockRejectedValueOnce(new Error("ECONNREFUSED"))+ .mockResolvedValueOnce(new Response("not json"))+ .mockResolvedValueOnce(Response.json({ viewerSkipped: true }));+ vi.stubGlobal("fetch", fetchMock);+ expect(await advance(waitForReadiness(startupDeadline(1000), (signal) => probeWorker("http://local", signal)), 500)).toBe(true);+ expect(fetchMock).toHaveBeenCalledTimes(3);+ expect(vi.getTimerCount()).toBe(0);+ });++ it("accepts readiness just before the deadline", async () => {+ fakeTime();+ const pending = waitForReadiness(startupDeadline(100), async () => new Promise((resolve) => setTimeout(() => resolve(true), 99)));+ expect(await advance(pending, 99)).toBe(true);+ });++ it("rejects readiness at or after the deadline even when the probe ignores abort", async () => {+ fakeTime();+ const pending = waitForReadiness(startupDeadline(100), async () => new Promise((resolve) => setTimeout(() => resolve(true), 100)));+ expect(await advance(pending, 100)).toBe(false);+ });++ it("rejects late success after synchronous work exhausts the deadline", async () => {+ const remaining = vi.fn().mockReturnValueOnce(5).mockReturnValue(0);+ const result = await withinStartupDeadline({ remaining }, async () => true);+ expect(result.completed).toBe(false);+ });++ it("does not let wall-clock changes extend startup", async () => {+ fakeTime();+ const pending = waitForReadiness(startupDeadline(25), () => forever<boolean>());+ vi.setSystemTime(new Date("1999-01-01"));+ expect(await advance(pending, 25)).toBe(false);+ });++ it("stops retrying after a known engine exit, including during a successful probe", async () => {+ let stopped = false;+ const probe = vi.fn(async () => { stopped = true; return true; });+ expect(await waitForReadiness(startupDeadline(1000), probe, { stopped: () => stopped })).toBe(false);+ expect(probe).toHaveBeenCalledTimes(1);+ });++ it("does not start a probe after expiry or a known failure", async () => {+ const probe = vi.fn(async () => true);+ expect(await waitForReadiness(startupDeadline(0), probe)).toBe(false);+ expect(await waitForReadiness(startupDeadline(100), probe, { stopped: () => true })).toBe(false);+ expect(probe).not.toHaveBeenCalled();+ });+});++describe("probe contracts", () => {+ it("accepts the engine's root404 while discarding its response body", async () => {+ const cancel = vi.fn(async () => {});+ vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, body: { cancel } })));+ expect(await probeEngine("http://local", new AbortController().signal)).toBe(true);+ expect(cancel).toHaveBeenCalledOnce();+ });++ it.each([null, [], {}, { viewerPort: null }, { viewerPort: 0 }, { viewerPort: -1 }, { viewerPort: 1.5 }, { viewerPort: 65536 }, { viewerPort: "3113" }, { viewerSkipped: "true" }])("rejects malformed readiness body %j", async (body) => {+ vi.stubGlobal("fetch", vi.fn(async () => Response.json(body)));+ expect(await probeWorker("http://local", new AbortController().signal)).toBe(false);+ });++ it("publishes a valid discovered viewer port", async () => {+ const found = vi.fn();+ vi.stubGlobal("fetch", vi.fn(async () => Response.json({ viewerPort: 65535 })));+ expect(await probeWorker("http://local", new AbortController().signal, found)).toBe(true);+ expect(found).toHaveBeenCalledWith(65535);+ });++ it("requires a successful HTTP response even with a ready-shaped body", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => Response.json({ viewerSkipped: true }, { status: 503 })));+ expect(await probeWorker("http://local", new AbortController().signal)).toBe(false);+ });+});++describe("worker startup ownership", () => {+ it("does not import a worker after the owned engine has already failed", async () => {+ const options = workerOptions({ stopped: () => true });+ expect(await startWorkerAndWait(options)).toBe(false);+ expect(options.startWorker).not.toHaveBeenCalled();+ expect(options.probe).not.toHaveBeenCalled();+ });++ it("starts exactly one CLI-owned worker", async () => {+ const options = workerOptions();+ expect(await startWorkerAndWait(options)).toBe(true);+ expect(options.startWorker).toHaveBeenCalledOnce();+ });++ it.each(["live pid", "engine-managed"])("waits for %s without importing a duplicate", async (ownership) => {+ fakeTime();+ const options = workerOptions({+ timeoutMs: 10_000,+ hasLiveWorker: () => ownership === "live pid",+ engineStartsWorker: () => ownership === "engine-managed",+ probe: vi.fn(async () => performance.now() >= 8000),+ });+ expect(await advance(startWorkerAndWait(options), 8000)).toBe(true);+ expect(options.startWorker).not.toHaveBeenCalled();+ });++ it("never falls back to a duplicate after an engine-managed worker times out", async () => {+ fakeTime();+ const options = workerOptions({ engineStartsWorker: () => true, probe: vi.fn(async () => false) });+ expect(await advance(startWorkerAndWait(options), 1000)).toBe(false);+ expect(options.startWorker).not.toHaveBeenCalled();+ });++ it("includes async import in the same readiness deadline", async () => {+ fakeTime();+ const options = workerOptions({ startWorker: vi.fn(() => forever<void>()) });+ expect(await advance(startWorkerAndWait(options), 1000)).toBe(false);+ expect(options.probe).not.toHaveBeenCalled();+ });++ it("does not reset the budget after a slow import", async () => {+ fakeTime();+ const options = workerOptions({+ startWorker: vi.fn(() => new Promise<void>((resolve) => setTimeout(resolve, 900))),+ probe: vi.fn(async () => false),+ });+ expect(await advance(startWorkerAndWait(options), 1000)).toBe(false);+ expect(options.probe).toHaveBeenCalledTimes(1);+ });++ it("propagates import failures and removes its deadline timer", async () => {+ fakeTime();+ await expect(startWorkerAndWait(workerOptions({ startWorker: async () => { throw new Error("bad import"); } }))).rejects.toThrow("bad import");+ expect(vi.getTimerCount()).toBe(0);+ });+});diff --git a/test/startup-cleanup.test.ts b/test/startup-cleanup.test.tsnew file mode 100644index 00000000..3c8584c8--- /dev/null+++ b/test/startup-cleanup.test.ts@@ -0,0 +1,64 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { registerStartupCleanup, runStartupCleanup } from "../src/shutdown.js";++let unregister: (() => void) | undefined;+afterEach(() => { unregister?.(); unregister = undefined; });++describe("startup-owned process cleanup", () => {+ it("leaves normal runtime shutdown unchanged after readiness", async () => {+ const cleanup = vi.fn(async () => {});+ unregister = registerStartupCleanup(cleanup);+ unregister();+ expect(await runStartupCleanup(0)).toBe(0);+ expect(await runStartupCleanup(1)).toBe(1);+ expect(cleanup).not.toHaveBeenCalled();+ });++ it("coalesces fatal, signal and worker shutdown exits until the same cleanup finishes", async () => {+ let finish!: () => void;+ const cleanup = vi.fn(() => new Promise<void>((resolve) => { finish = resolve; }));+ unregister = registerStartupCleanup(cleanup);+ const interrupt = runStartupCleanup(130);+ const fatal = runStartupCleanup(1);+ const workerExit = runStartupCleanup(0);+ let settled = false;+ void workerExit.then(() => { settled = true; });+ await Promise.resolve();+ expect(cleanup).toHaveBeenCalledOnce();+ expect(settled).toBe(false);+ finish();+ expect(await Promise.all([interrupt, fatal, workerExit])).toEqual([130, 130, 130]);+ });++ it("shares startup ownership across separately loaded module instances", async () => {+ const cleanup = vi.fn(async () => {});+ unregister = registerStartupCleanup(cleanup);+ vi.resetModules();+ const workerModule = await import("../src/shutdown.js");+ expect(await workerModule.runStartupCleanup(1)).toBe(1);+ expect(cleanup).toHaveBeenCalledOnce();+ });++ it("does not let an older completed attempt unregister the next attempt", async () => {+ const clearOld = registerStartupCleanup(async () => {});+ await runStartupCleanup(1);+ const cleanup = vi.fn(async () => {});+ unregister = registerStartupCleanup(cleanup);+ clearOld();+ expect(await runStartupCleanup(143)).toBe(143);+ expect(cleanup).toHaveBeenCalledOnce();+ });++ it("keeps the original failure code when a later signal races with cleanup", async () => {+ unregister = registerStartupCleanup(async () => {});+ expect(await Promise.all([runStartupCleanup(1), runStartupCleanup(143)])).toEqual([1, 1]);+ });++ it("shares cleanup failure without running a second destructive cleanup", async () => {+ const cleanup = vi.fn(async () => { throw new Error("cleanup failed"); });+ unregister = registerStartupCleanup(cleanup);+ const results = await Promise.allSettled([runStartupCleanup(1), runStartupCleanup(143)]);+ expect(results.every((result) => result.status === "rejected")).toBe(true);+ expect(cleanup).toHaveBeenCalledOnce();+ });+});