Skip to content

fix: make the flags and flow features the docs promised actually work (v2.16.0) - #243

Merged
paulkr merged 1 commit into
mainfrom
fix/docs-audit-bugs
Nov 20, 2026
Merged

paulkr merged 1 commit into
mainfrom
fix/docs-audit-bugs

Conversation

@paulkr

@paulkr paulkr commented Nov 20, 2026

Copy link
Copy Markdown
Member

Why

The docs audit in #242 found commands that ignored their own flags, or quietly did something risky. #242 made the docs describe that behaviour; this PR fixes the code and puts the docs back.

Each bug below was reproduced with the real CLI built from main, then confirmed fixed with the CLI built from this branch. Both ran offline in an isolated HOME, with the One API and OpenAI faked at fetch, so no real config or memory store was touched.

What changed

Bug On main On this branch
sync run ignored the profile's memory.embed (and defaults.embedOnSync) Profile with embed: true: 2 records synced, 0 embedding calls 2 embedding calls; --no-embed still gives 0; defaults.embedOnSync: true alone gives 2
mem search --no-track did nothing access_count 3 → 4 stays at 2; a plain search still counts
mem add --no-embed did nothing (same root cause) 1 embedding call 0
mem search --deep did nothing key set, no pgvector: fts_only, exit 0 exit 1, searchMode: "unavailable", how lists every missing piece
flow execute --mock ran file writes for real out/report.json created nothing written; output is { path, bytesWritten, _mock: true }
Ctrl+C didn't pause printed "Pausing...", then ran to the end (status completed); in a terminal the signal killed the code sandbox and the run was saved as failed stops before the next step, status paused, exit 130, prints the resume command; resume runs only the remaining steps; a second Ctrl+C quits at once
onError: fallback never ran the fallback the fallback step ran only because of its position, even when the primary succeeded runs only when the primary fails, wherever it's listed; skipped otherwise
sync init overwrote an existing profile exit 0; connection.tag, onInsert and memory gone exit 1, status: "exists", profile untouched; --config merges, --force re-seeds
one --agent logout deleted both configs without asking project and global config both deleted confirmation_required without --force; with --force only the config in effect; --scope global|both to choose

Details:

  • sync embed: --embed was registered with a default of false, so commander always passed embed: false, which overrode the profile. A missing memory.embed was also coerced to false, so defaults.embedOnSync was never read. The enrich phase now receives --embed / --no-embed too (it ignored both).
  • --deep: --deep now means "hybrid or nothing". The error names every missing piece at once (pgvector, OpenAI key) rather than one per attempt.
  • Pause: FlowPauseSignal (like FlowStopSignal) unwinds the run at the next step boundary. A step that fails while a pause is pending is treated as interrupted: no retry and no onError, and it re-runs on resume. Without that, a terminal Ctrl+C, which also signals bash and code child processes, would mark the run failed. flow resume gets the same Ctrl+C handling. Agent mode returns {"status": "paused", "pausedBefore", "resume"}.
  • Fallback: the fallback step must be a sibling in the same steps list (parallel blocks included) and is skipped in normal order. The failed step is recorded with fallback: "<id>". If the fallback fails too, the flow fails. The validator now requires fallbackStepId, checks it's a sibling and not the step itself, and rejects fallback in defaultOnError.
  • sync init: the new --force also makes two existing hints valid: the runtime hint already suggested --force, and the drift warning suggested a bare sync init, which would wipe the profile. The drift warning now says --force and warns that it replaces the profile.
  • Docs: README, the skill, the flows reference, one guide and --help are updated to match.
  • Version: 2.15.2 → 2.16.0 (new flags and features). Both lockfile version fields were hand-edited, per CLAUDE.md.

Behaviour changes to note

  • Scripts that ran one --agent logout now need --force.
  • A bare sync init on an existing profile now exits 1 instead of replacing it.
  • mem search --deep now exits 1 when semantic search can't run.
  • Flows that relied on a fallback step running in its normal position now see it skipped unless the primary fails.

Not in this PR

  • --mock still runs code.module steps for real (they have full Node access).
  • The other items from the audit list (e.g. mem flush, the mem sql guard, mem doctor without pgvector) are untouched.
  • The website CLI page (withoneai/landing) still describes the old behaviour for these flags and needs a follow-up once this ships.

Testing

  • 7 new test files, 39 tests, covering each fix (each failed on main before its fix).
  • Full suite: 918 tests, 910 pass. The 6 failures are resolveConfig in src/lib/config.test.ts, which fails the same way on main and isn't touched here.
  • npm run typecheck passes.
  • Real-CLI reproduction and confirmation for all 8 items (table above), run offline against faked One/OpenAI endpoints.
  • Not verified: the --deep success path (key plus pgvector giving hybrid results), because this machine's bundled Postgres has no pgvector.

🤖 Generated with Claude Code

… (v2.16.0)

The docs audit in #242 found commands that ignored their own flags or
silently did something risky. Each was reproduced with the real CLI on
main and confirmed fixed on this branch.

- sync run: honour the profile's memory.embed, then defaults.embedOnSync.
  --embed was registered with a default of false, so "no flag" always
  meant "don't embed". The enrich phase now gets --embed/--no-embed too.
- mem search --no-track and mem add --no-embed: read the property
  commander actually sets (track/embed), so both flags work.
- mem search --deep: require hybrid search. When it can't run, fail and
  list what's missing (OpenAI key, pgvector) instead of quietly
  returning full-text results.
- flow execute --mock: mock file-write steps too (report path and
  bytesWritten, write nothing).
- Ctrl+C in flow execute/resume: really pause. The run stops before the
  next step, is saved as paused, and prints the resume command; a bash or
  code step the Ctrl+C interrupts re-runs on resume. A second Ctrl+C
  quits at once and still saves the run as paused.
- onError fallback: run the fallbackStepId step when the step fails. The
  fallback must be a sibling and is skipped in normal order. The
  validator now checks fallbackStepId and rejects fallback in
  defaultOnError.
- sync init: refuse to overwrite an existing profile unless --force
  (re-seed) or --config (merge). The drift hint now says --force and
  warns that it replaces the profile.
- one --agent logout: needs --force, and clears only the config in
  effect unless --scope global|both.

Docs (README, skill, flows reference, guide, help text) updated to match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paulkr
paulkr merged commit ff0e5e3 into main Nov 20, 2026
8 checks passed
@paulkr
paulkr deleted the fix/docs-audit-bugs branch November 20, 2026 02:03
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.

1 participant