#235 Agentic CLI improvements: --json stdout isolation, array inputs, and --repo-dir consistency

Summary

After extensive agentic use of swamp (model method runs, workflow execution, data queries, extension management), several friction points emerge that reduce reliability and increase complexity for AI agent integrations. These are grouped by priority.

1. Mixed stdout/stderr in --json mode (CRITICAL)

Several commands output log lines (INF, WRN) interleaved with JSON to the same stream, making it impossible to reliably JSON.parse() the output.

Example from model method run ... --json:

23:49:47.342 INF model·method·run ... 
{ "intent": "...", "action": "ok" }
23:49:48.286 INF model·method·run ...

Recommendation: When --json is specified, ALL non-JSON output should go to stderr. JSON should be the only thing on stdout.

2. Array/object inputs not passable via --input (HIGH)

Extension model methods (e.g. @bixu/wheelshop search) accept array-typed arguments like keywords: string[]. Passing --input 'keywords=["typescript"]' fails with expected array, received string. There is no documented way to pass array or object values.

Recommendation: Support JSON-typed inputs via --input 'keywords:json=["typescript","retry"]' or auto-detect JSON when value starts with [ or {. Alternatively, add --input-json '{"run":"echo hello","keywords":["a","b"]}' for single-shot structured input.

3. Some commands lack --repo-dir (MEDIUM)

doctor, model type search, and audit do not accept --repo-dir, requiring agents to cd first. This breaks stateless agent patterns where each command invocation is independent.

Recommendation: Add --repo-dir to all repo-scoped commands for consistency.

4. data gc requires interactive confirmation even with --json (MEDIUM)

data gc prompts Proceed with garbage collection? [y/N] even in --json mode, stalling non-interactive pipelines. --force works but should not be required when --json implies non-interactive.

Recommendation: --json should imply non-interactive mode (default to dry-run, or require --force but dont prompt).

5. Global lock contention on read-only operations (MEDIUM)

Nearly every data operation (list, get, search, query) shows Waiting for per-model lock(s) to be released with 2-5 second delays. When an agent runs frequent read operations alongside a workflow, lock contention dominates latency.

Recommendation: Consider read-only operations acquiring shared/reader locks instead of exclusive locks. Or expose a lock-free read path for queries that don't mutate state.

6. No CLI-level timeout for method/workflow execution (LOW)

Workflow runs and model method executions have no CLI-level timeout. A hung external command blocks the agent indefinitely.

Recommendation: Add --timeout 30s flag for model method run and workflow run.

7. Error output format inconsistency (LOW)

Fatal errors use FTL error Error: "..." with nested quoting. With --json, errors should return structured JSON on stdout: {"error": "...", "code": "..."} instead of the log-formatted FTL line.

Environment

• CLI: 20260504.233645.0-sha.430c1535
• OS: Linux x86_64
• Use case: AI agent (Claude Code) driving swamp via CLI for automated workflow execution, extension model methods, and data management