#2623 · Docs status nested help rejects a valid help request

Bug Priority: Low Effort: Low documentation · cli · docs open on GitHub 2026-08-28 · base f9a1aa5

Verdict: REPRODUCED · Root-cause confidence: high

1. TL;DR

The Docs status command uses exit 4 as a valid signal that local changes exist. That behavior works and has a test. However, nested help for status returns usage error 2. The command checks only the first argument for help, then rejects --help as an invalid status option. Callers cannot discover the exit 4 contract from the command itself.

2. Claims vs findings

Claim	Status	Evidence
Status uses exit 4 when a sync plan contains changes.	Verified	The existing focused sync test passed. The implementation checks writes, deletes, directories, and warnings.
Nested status help fails.	Verified	The new focused test returned exit 2 instead of exit 0 in two clean checkouts.
The command output documents exit 4.	Refuted	Top-level help contains only a usage line. Nested status help does not run.

3. Environment

Trusted bb commit: f9a1aa5ebdd50711bb7d17fd9c096a06b39abfd8.
Linux 7.0.0-30-generic, x86_64.
Node v24.18.0, pnpm 9.15.0, Turbo 2.8.3, Vitest 4.1.1.
No live server, port, provider process, or user data directory was used. The plugin SDK test harness ran the CLI directly.

4. Minimal reproduction

Check out the trusted base commit.
Run pnpm install --frozen-lockfile --prefer-offline.
Run pnpm exec turbo run build.
Place the linked test at plugins/docs/issue-2623.repro.test.ts.
Run pnpm exec turbo run test --filter=bb-plugin-simple-notes --force -- issue-2623.repro.test.ts.

Expected and actual result:

Expected: nested status help exits 0 and describes exit 4.
Actual:   AssertionError: expected 2 to be +0
          Test Files  1 failed (1)
          Tests       1 failed (1)

Reproduction test: status-help.test.ts

import { expect, it } from "vitest";
import { createFakePluginHost } from "@get-bb/plugin-sdk/testing";
import docsPlugin from "./server";

it("shows the status exit contract through nested help", async () => {
  const host = createFakePluginHost({
    pluginId: "simple-notes-repro",
    sdk: {
      files: {
        mkdir: async () => ({ ok: true as const }),
      },
    },
  });
  await docsPlugin(host.bb);

  const help = await host.harness.behavior.runCli(["status", "--help"]);

  expect(help.exitCode).toBe(0);
  expect(help.stdout).toContain("Exit 4");
  expect(help.stdout).toContain("changes present");
});

Second clean verification

The same agent created a second clean worktree at the same commit. It repeated the frozen install, full Turbo build, and focused test. The second run also received exit 2 and failed the same assertion. No report claim needed correction.

5. Root cause

The CLI handler recognizes help only when help occupies the first argument. See the help gate and parser call.

if (
  argv.length === 0 ||
  argv[0] === "help" ||
  argv[0] === "--help" ||
  argv[0] === "-h"
) {
  return { exitCode: 0, stdout: DOCS_CLI_USAGE };
}
const args = parseCli(argv);

For a nested request, the parser treats status as the command. It then rejects --help because status does not list that option. See the option validation.

The exit 4 behavior itself is deliberate and correct. See the status result policy. The missing branch for nested help makes that policy undiscoverable.

6. Proposed fix (first principles)

Handle status --help before normal option parsing. Return command-specific help with exit 0. State that exit 4 means changes are present. Tell callers to inspect status output and then run push as a separate command. Keep the existing exit 4 behavior unchanged. Update the Docs skill, the built-in CLI skill, and the generated guide source.

7. Related issues

#2621 concerns broader plugin command help discovery. It does not replace this focused Docs command defect.

8. Appendix

The issue data was untrusted. The investigation used it only as claims to test. No linked code, branch, script, or external issue URL was executed.

Commands used:

git fetch origin main
pnpm install --frozen-lockfile --prefer-offline
pnpm exec turbo run build
pnpm exec turbo run test --filter=bb-plugin-simple-notes --force -- issue-2623.repro.test.ts
pnpm exec turbo run test --filter=bb-plugin-simple-notes --force -- server.test.ts -t "round-trips a folder edit"