Skip to content

fix(cli): reject an unknown or empty lobster run --mode value - #220

Open
KrasimirKralev wants to merge 1 commit into
openclaw:mainfrom
KrasimirKralev:fix/run-mode-reject-unknown
Open

KrasimirKralev wants to merge 1 commit into
openclaw:mainfrom
KrasimirKralev:fix/run-mode-reject-unknown

Conversation

@KrasimirKralev

@KrasimirKralev KrasimirKralev commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

What Problem This Solves

lobster run --mode tools '<pipeline>' (a one-letter typo of tool) runs the pipeline in human mode and exits 0, so a caller that asked for the JSON tool envelope gets plain human output and no error. The same happens for --mode=TOOL, --mode= and a trailing --mode with no value; a bare --mode placed before the pipeline swallows the pipeline as its value and then fails with an unrelated Parse error: Empty pipeline.

  • normalizeMode in src/cli.ts mapped every value other than tool to human, and parseRunArgs turned an empty --mode= into human and ignored a trailing --mode with no value.
  • Scope: only the value check for lobster run --mode. human (still the default when --mode is absent) and tool behave exactly as before; resume, graph, the core tool API and every pipeline command are untouched.

User Impact

A tool integration or script with a mistyped or empty --mode now gets Parse error: --mode must be "human" or "tool", got "<value>" on stderr with exit code 2, before anything runs, instead of a silent fallback to human output that its JSON parser then chokes on. This narrows the accepted values to the two documented ones; any script that relied on an arbitrary --mode value meaning "human" now has to drop the flag or pass human.

Why This Change Was Made

  • What changed: normalizeMode returns "human" | "tool" | null, and handleRun reports null as a parse error (exit 2, human stderr form because the requested mode is unknown). parseRunArgs keeps an empty --mode= and a trailing value-less --mode as "", the same way it already handles --args-json, so both are rejected too.
  • Root cause: the mode was normalized with a === "tool" ? "tool" : "human" fallback, so every unrecognised value silently became human mode.
  • Missing detection: nothing covered an invalid --mode. New cases in test/cli_run_errors.test.ts run bin/lobster.js run with --mode tools, --mode=TOOL, --mode= and a trailing --mode, and check exit 2, empty stdout and the exact stderr line; one more pins that --mode human still prints the human output.
  • Regression check: with the src/cli.ts change reverted, the full suite fails exactly the 4 rejection cases (753/757); with it, 757/757 pass. pnpm lint and pnpm typecheck are clean.
  • README notes the accepted values next to the existing input-error paragraph, plus a CHANGELOG line under ## Unreleased.

Evidence

  • Behavior or issue addressed: lobster run --mode <unknown or empty> no longer falls back to human output with exit 0.
  • Real environment tested: Linux, Node v24.22.2, lobster built from this branch (pnpm run build) at upstream 473b1f7 + this commit.
  • Exact steps or command run after this patch: node bin/lobster.js run 'exec --json "echo [1]"' --mode <value> with the same six --mode forms below, on main and on this branch (each followed by echo "exit=$?").
  • Evidence after fix:
# main (473b1f7)
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode tools; echo "exit=$?"
[
  1
]
exit=0
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode=TOOL; echo "exit=$?"
[
  1
]
exit=0
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode=; echo "exit=$?"
[
  1
]
exit=0
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode; echo "exit=$?"
[
  1
]
exit=0
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode human; echo "exit=$?"
[
  1
]
exit=0
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode tool; echo "exit=$?"
{
  "protocolVersion": 1,
  "ok": true,
  "status": "ok",
  "output": [
    1
  ],
  "requiresApproval": null,
  "requiresInput": null
}
exit=0

# this branch
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode tools; echo "exit=$?"
Parse error: --mode must be "human" or "tool", got "tools"
exit=2
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode=TOOL; echo "exit=$?"
Parse error: --mode must be "human" or "tool", got "TOOL"
exit=2
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode=; echo "exit=$?"
Parse error: --mode must be "human" or "tool", got ""
exit=2
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode; echo "exit=$?"
Parse error: --mode must be "human" or "tool", got ""
exit=2
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode human; echo "exit=$?"
[
  1
]
exit=0
$ node bin/lobster.js run 'exec --json "echo [1]"' --mode tool; echo "exit=$?"
{
  "protocolVersion": 1,
  "ok": true,
  "status": "ok",
  "output": [
    1
  ],
  "requiresApproval": null,
  "requiresInput": null
}
exit=0
  • Observed result after fix: running node bin/lobster.js run with tools, TOOL, an empty value or no value now stops with the parse error and exit 2 before the pipeline runs; human and tool produce the same output as on main.
  • What was not tested: a workflow-file run (--file) with a bad --mode; it goes through the same check at the top of handleRun, before the target is resolved.
  • Proof limitations or environment constraints: none.

@clawsweeper

clawsweeper Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T07:50:56.016114Z 38f5687 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@clawsweeper clawsweeper Bot added clawsweeper:intake:bug Preliminary submission classification; full source review pending. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on maintainer Only explicit maintainer approvals or decisions remain; merge is still blocked. and removed clawsweeper:intake:bug Preliminary submission classification; full source review pending. labels Nov 14, 2026
@clawsweeper

clawsweeper Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codex review: ready, awaiting a maintainer decision.

What this changes

Reject unknown, empty, or missing run-mode values with exit code 2 before executing a pipeline or workflow.

Example: Run lobster run 'exec --json "echo [1]"' --mode tools.

  • Before: Prints [1] as human output and exits 0.
  • After: Reports that --mode must be "human" or "tool" and exits 2.

Review scores

Measure Result What it means
Overall readiness 🦐 gold shrimp (3/6) Focused implementation with sufficient shipped-CLI evidence and no identified defects; product readiness awaits the compatibility decision.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): The supplied Linux and Node 24 transcript exercises the built bin/lobster.js entry point for tools, TOOL, empty equals, and trailing valueless modes, showing exit 2 after the fix and unchanged human/tool output; workflow targets share the same validation before resolution.
Patch quality 🦞 diamond lobster (5/6) No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Needs a maintainer decision · Fix scope: Complete
User problem: A script mistyping tool mode executes with human output instead of receiving an actionable input error.
Reason: The diagnostic has clear value, but removing the established fallback requires an owner decision.

Merge readiness

⏳ Ready, awaiting maintainer decision

This PR addresses behavior still present on main with a focused, correct patch; accepting the removal of the longstanding human-mode fallback remains an owner decision.

Priority: P2
Reviewed head: 38f568794538676d67acfcb217fd9a67072cce03
Owner decision: Required. See Decision needed.

Decision needed

  • Question: Should unknown or empty --mode values stop with exit code 2 instead of continuing in human mode?
  • Recommendation: Accept strict validation: Accept rejection because human and tool are the documented modes and the diagnostic names the valid replacements.
  • Why: This removes established accepted CLI behavior, and no owner approval of that direction is recorded.

Before merge

None.

Findings

None.

Agent review details

How this fits together

The CLI parses run arguments, resolves a pipeline or workflow file, executes it, and renders human output or a tool JSON envelope.

flowchart TD
A[CLI arguments] --> B[Parse run arguments]
B --> C[Validate mode]
C --> D[Input error and exit 2]
C --> E[Resolve pipeline or workflow]
E --> F[Execute and render output]
Loading

Technical review

Best possible solution:

Land the focused validation through the existing CLI error reporter once the CLI owner accepts the compatibility change.

Do we have a high-confidence way to reproduce the issue?

Current-main parsing and normalization establish the silent fallback, corroborated by the contributor's base-versus-branch CLI transcript; no target code was executed during this read-only review.

Is this the best way to solve the issue?

Preserving the supplied value, validating before execution, and reusing reportRunError is the smallest complete fix shown.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 3d168c79cdd8.

Provenance checked

  • Run-mode parsing and normalization changes intended behavior with a stated reason (14479b6: Workflow-file support introduced normalizeMode while carrying forward permissive parsing from the original tool-mode implementation at 93e62d8; neither stated purpose promises arbitrary mode values.)
  • Run-error reporting keeps the original intent (fix: route CLI target errors and graph help correctly #178: Centralize mode-aware diagnostics and controlled exit codes for invalid run inputs.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

  • Main retains the permissive fallback: Main substitutes human for an empty equals value and normalizes every non-tool value to human. (src/cli.ts:531, 3d168c79cdd8)
  • Validation uses the existing error owner: The introduced diff preserves empty values and rejects invalid modes through reportRunError before target resolution; valid-mode execution paths remain intact. (src/cli.ts:202, 38f568794538)
  • Contributor supplied shipped-CLI proof: The complete PR body records Linux and Node 24 built-CLI output for four rejected forms and both valid modes, plus a reported base-versus-fix regression check. (bin/lobster.js:3, 38f568794538)
  • Fallback provenance: The original JavaScript tool-mode implementation accepted arbitrary mode strings; workflow-file support subsequently introduced normalizeMode with its explicit human fallback. Neither commit explains arbitrary values as a supported contract. (src/cli.ts:536, 14479b62c666)
  • Existing error-reporting intent preserved: fix: route CLI target errors and graph help correctly #178 centralized mode-aware parsing errors; this PR reuses that implementation. (src/cli.ts:365, f9da0f10eada)
  • Discussion and current checks: Discussion contains no owner acceptance of strict validation; all four checks on the reviewed head succeeded. The prior review listed no findings or published rank-up moves. (38f568794538)

Likely related people:

  • Peter Steinberger: Raw commit f9da0f1 adds src/cli.ts:198 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: f9da0f10eada; files: src/cli.ts)
  • Krasimir Kralev: Raw commit d296ac2 adds test/cli_run_errors.test.ts:143 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: d296ac290d1d; files: test/cli_run_errors.test.ts)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Labels

Label changes:

No label changes.

Label justifications:

  • P2: A mistyped mode silently produces the wrong output format for CLI integrations, with a limited trigger.
  • merge-risk: 🚨 compatibility: Previously successful invocations using arbitrary or empty modes will exit 2 before running their pipeline.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • status: ⏳ waiting on maintainer: Only explicit maintainer approvals or decisions remain; merge is still blocked.
  • proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

History

Review history (1 earlier review cycle)
  • reviewed 2026-11-14T16:11:31.975Z sha 8f41577 :: ready, awaiting a maintainer decision. :: none

Reviewed November 16, 2026, 3:01 AM ET / 08:01 UTC (Revision 2).

@KrasimirKralev
KrasimirKralev force-pushed the fix/run-mode-reject-unknown branch from 8f41577 to 38f5687 Compare November 16, 2026 07:47
@KrasimirKralev

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

🦞👀
Exact review queued.

Re-review progress:

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on maintainer Only explicit maintainer approvals or decisions remain; merge is still blocked.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant