Skip to content

fix(cli): explain an engine that runs without the agentmemory worker - #1758

Merged
rohitg00 merged 8 commits into
mainfrom
fix/status-engine-only
Nov 12, 2026
Merged

rohitg00 merged 8 commits into
mainfrom
fix/status-engine-only

Conversation

@rohitg00

@rohitg00 rohitg00 commented Nov 11, 2026 •

Copy link
Copy Markdown
Owner

When only the iii engine runs (for example an old Docker image), the agentmemory routes return 404 and status showed v? and Health: unknown with no cause.

  • Status detects this case and says the worker is not connected, how to start agentmemory, and that old Docker images ran only the engine.
  • Doctor has a new manual-only worker-not-connected check with the same fix.
  • Every failing doctor check prints its message and a fix hint.
  • iii-on-path-not-local-bin now says which iii is used and what to run.

Includes docs:sync output in the same commit.

Found through docs-assistant questions from users.

Test notes: targeted tests pass. Full-suite failures seen locally (fs-watcher, observation-source, graph timeouts) also fail on a clean origin/main checkout under load.

Summary by CodeRabbit

  • New Features
    • The status command now identifies engine-only and unrecognized services, and reports when a managed worker is unavailable.
    • Doctor checks include worker connectivity and provide clearer problem descriptions and recovery guidance.
    • PATH checks show the detected CLI version and provide guidance when it differs from the pinned version.
  • Documentation
    • Updated the reported passing-test count to 4,800+ across the README and its translations.

When only the iii engine runs on the REST port, the agentmemory routes
return 404. Status printed version v? and Health unknown, and the viewer
returned 404, with no hint about the cause. Old Docker images from the
legacy CLI Docker mode ran only the engine and showed this state.

Status now probes /agentmemory/livez and /agentmemory/health. When both
return 404, it says that the engine runs without the worker, how to start
agentmemory, and where the Docker migration guide is.

Doctor has a new worker-not-connected check with the same fix text.
Every failing doctor check now prints its message and a fix hint, not
only its id. The iii-on-path-not-local-bin check now says which iii is
used, its version, and the command to run.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
@vercel

vercel Bot commented Nov 11, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
agentmemory Ready Ready Preview Nov 12, 2026 11:39am UTC

Request Review

@coderabbitai

coderabbitai Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review
Walkthrough

The CLI adds worker connectivity checks to status and doctor, including saved Compose failure handling and recovery guidance. Doctor output and PATH-binary diagnostics are revised. Testing instructions, README files, and sync metadata update reported counts.

Changes: Test-count documentation

Layer / File(s) Summary
Update documented test counts
AGENTS.md, README.md, READMEs/README.*, scripts/docs-sync.state.json
Testing instructions and localized README badges and command comments now report 4,800+ tests. The sync state records 260 source files instead of 259; the function count remains 323.

CLI worker and doctor diagnostics

Layer / File(s) Summary
Probe worker endpoint connectivity
src/cli/worker-connection.ts, test/cli-worker-connection.test.ts
The probe requests the worker live and health routes concurrently and classifies the result as connected, engine-only, unrecognized, or unreachable. The module also adds TCP port checks, shell-argument quoting, and guidance for engine-only and unrecognized services. Tests cover probe results, headers, port checks, quoting, and guidance.
Wire worker checks into status and doctor
src/cli.ts, src/cli/doctor-diagnostics.ts, test/cli-doctor-fixes.test.ts
status checks worker connectivity and saved Compose failures. Doctor recognizes worker connection states and managed Compose targets. Recovery guidance retains the selected instance, port, and data directory.
Report doctor failures and PATH binary details
src/cli.ts, src/cli/doctor-diagnostics.ts, test/cli-doctor-fixes.test.ts
Doctor output uses diagnostic-specific problem and fix text. The PATH-binary diagnostic reports the discovered binary path and version and provides manual guidance.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant CLI as CLI status command
  participant Probe as probeWorkerConnection
  participant Routes as Worker routes
  participant Doctor as Doctor diagnostics
  CLI->>Probe: Probe target with configured headers
  Probe->>Routes: Request live and health routes
  Routes-->>Probe: Return route statuses or failures
  Probe-->>CLI: Return worker connection classification
  CLI->>Doctor: Supply worker state and target context
  Doctor-->>CLI: Return diagnostic problem and fix guidance
Loading

Possibly related issues

  • rohitg00/agentmemory#1740 — This issue concerns the same status and doctor command areas. This PR changes their diagnostics but does not split the commands.

Possibly related PRs

Merge Risk: Low · previous review 6359e

The new status and doctor guidance for an engine-only setup is useful. In a few edge cases, status can still print a connected report without a failing exit code, and Windows recovery hints can mishandle drive roots or Command Prompt quoting. These are minor and not merge-blocking, but owners should be aware of them.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main CLI change: explaining when the engine runs without the agentmemory worker.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 15 functions across 5 files.

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

devin-ai-integration[bot]

This comment was marked as resolved.

When a supervised worker in the managed Compose project exhausts its
restarts, the agentmemory routes can return 404. The engine-only probe
then exited before status printed the Compose failure. Skip the probe
for managed Compose state in status and doctor; it is meant for engines
agentmemory does not manage.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
coderabbitai[bot]

This comment was marked as resolved.

devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

Two 404 responses from the agentmemory routes no longer prove an iii
engine. The probe now also checks the engine port. If that port does
not answer, status and doctor report an unrecognized service and do not
tell the user to stop it.

Status and doctor now probe the selected target also when managed
Compose state exists. Status prints the Compose failure report first
when there is one. Doctor reports a managed Compose engine without its
worker and no longer passes for a remote URL or another port.

The recovery command keeps --instance, --port and --data-dir. The
iii-on-path-not-local-bin message no longer says that startup uses the
PATH iii.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
@rohitg00

Copy link
Copy Markdown
Owner Author

Review-body findings, handled in c02a4e4:

  • Compose failure summary before exit (src/cli.ts, status): fixed. The Compose inspection is now one helper. Status uses it when REST is down and also when the engine answers but the agentmemory routes return 404, and prints container states and last errors before it exits with code 1.
  • Port in the recovery command (src/cli/worker-connection.ts): fixed. See the inline thread.
  • Compose state must match the doctor target (src/cli.ts): fixed. See the inline thread.
  • Docstring Coverage: not applied. The repo rule is no code comments.

devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

When a managed Compose worker exhausted its restarts, the agentmemory
routes answer 404 and status exited with the engine-only message. Status
now continues to the normal report, which lists the Compose failure,
as it did before.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
Status and doctor recovery commands now keep --instance, --port and a
shell-quoted --data-dir for status, stop and start. A route that fails
next to a 404 no longer counts as a connected worker. Status exits 1
when the worker routes do not respond. The engine bus probe honors
III_URL when III_ENGINE_URL is unset. The doctor message no longer
claims an engine is running, and the unrecognized-service hint points
old Docker images at the migration guide.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

On Windows the recovery hint now puts --data-dir in PowerShell single
quotes, so dollar signs and apostrophes stay literal. Trailing path
separators are dropped, so no backslash comes before a closing quote.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

A drive root such as C:/ keeps its separator in recovery hints. Windows
paths that need quoting use double quotes, which Command Prompt and
PowerShell both read literally. Paths with a dollar sign keep PowerShell
single quotes.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
@reevesc88

Copy link
Copy Markdown
Contributor

@codex review

2 similar comments
@reevesc88

Copy link
Copy Markdown
Contributor

@codex review

@reevesc88

Copy link
Copy Markdown
Contributor

@codex review

Resolve the src/cli.ts import conflict by keeping the worker-connection
import from this branch and the hook-capture status imports from #1756.

Signed-off-by: Rohit Ghumare <ghumare64@gmail.com>
@rohitg00
rohitg00 merged commit 1ee2820 into main Nov 12, 2026
17 of 18 checks passed
@rohitg00
rohitg00 deleted the fix/status-engine-only branch November 12, 2026 11:39

This branch was successfully deployed

1 active deployment
Preview — 1005485b Deployed Nov 12, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants