fix(cli): os dev --no-watch turns watch off, and a PACKAGE matching nothing fails loudly

[objectstack-fleet]

Fixes #20681

Clause-②: no

What

os dev had an off branch for its watch-recompile loop (watchActive, and the loop comment's "Skipped when" list), but no argv reached it. Three changes, all in packages/cli/src/commands/dev.ts:

1. watch gets allowNo: true, the declaration the sibling compile, restart and seed-admin flags already carry. os dev --no-watch now boots with the loop off, and bare os dev keeps it on. The decision that the loop and the stale-artifact remedy line read is now one exported function, devWatchActive, so the pin can drive it with what oclif parsed. The loop comment's --watch=false is now --no-watch.
2. A PACKAGE argument that selects no workspace project exits 1 instead of 0. The orchestration command now passes --fail-if-no-match to pnpm. pnpm owns the filter grammar (names, globs, ./dir, ...pkg), so pnpm decides whether the filter matched, and the CLI does not read the workspace a second time. This is the change that closes os dev --watch=false: oclif has no =value form for a boolean flag, so that argv parses as --watch plus the PACKAGE false.
3. --no-watch in monorepo orchestration mode is refused (exit 1, naming the flag). Change 1 also makes --no-watch reachable there. In that mode each package's own dev script decides whether it watches, and the CLI would have printed Watch: enabled right under the flag. Before this PR that argv was refused as a nonexistent flag (exit 2), so nothing that used to work is refused now.

The loud check on the PACKAGE argument fit inside dev.ts (one token plus the refusal block), so this PR delivers the whole card. Nothing is left over.

Measured

Before, at BASE 73155fedc, through the source entry (tsx packages/cli/bin/run-dev.js), in a temp dir holding only objectstack.config.ts:

• os dev --no-watch printed Nonexistent flag: --no-watch and exited 2.
• os dev --watch=false printed Package: false, Watch: enabled, $ pnpm --filter false dev, then No projects found in ..., and exited 0.

After, at 4804d8a7a:

• Same dir, os dev --watch=false ran pnpm --filter false --fail-if-no-match dev, which printed No projects found in .... The CLI then printed ✗ Development mode failed: Command failed: pnpm --filter false --fail-if-no-match dev and exited 1.
• At the repo root, os dev nonexistent-pkg-xyz printed No projects matched the filters and exited 1.
• At a temp workspace root (pnpm-workspace.yaml, no config), os dev --no-watch was refused, naming --no-watch, and exited 1.
• Positive control, repo root: os dev @objectstack/verify ran that package's tsc -w dev script, which was still running when the 60 s timeout stopped it (exit 124). So the added flag does not break a filter that matches.
• examples/app-todo, os dev --no-watch --fresh -p RANDOM: Server is ready, and no watching ... line. Control without --no-watch: watching objectstack.config.ts, src — rebuild + restart on change.

pnpm added --fail-if-no-match in 8.13.1, according to pnpm's own CHANGELOG at v10.31.0. It was measured here on 10.31.0 only. The changeset says monorepo mode now needs pnpm 8.13.1 or later.

Tests

New pin packages/cli/test/dev-no-watch.pin.test.ts. It spawns the source entry, so it is in the integration tier (vitest-tiers.ts fires childProcess, entryBasename, tsxBin).

• Parse and decide, through oclif's own Parser.parse over Dev.flags / Dev.args: --no-watch gives watch: false, and devWatchActive answers false. Bare gives true and true. --watch=false gives watch: true and package: 'false'.
• Spawned: --watch=false in a project dir exits 1, and the ✗ line names false. The workspace fixture's dev script prints a marker. Bare os dev there exits 0 and prints it (the control). --no-watch there exits 1, its ✗ line names --no-watch, and the marker is absent.

Runs:

• Pin: pnpm --filter @objectstack/cli exec vitest run --project integration --maxWorkers=2 test/dev-no-watch.pin.test.ts: 1 file, 8/8 passed.
• Ablation, three legs through scripts/ablation-replace.mjs in wrap mode. Each restore was proven: blob == HEAD 02c1c4bb1d8e, and git diff HEAD empty. All three turned red, as predicted:
  • A, --fail-if-no-match dropped: 2 failed / 6 passed (expected +0 to be 1, and no ✗ line). The first attempt at this leg was a no-op. The tool refused it because the replacement was a substring of the anchor, so its count could not rise. It was re-run with a replacement that does not overlap the anchor.
  • B, orchestration refusal disabled: 2 failed / 6 passed (expected +0 to be 1, and the marker present).
  • C, watch loses allowNo: 2 failed / 6 passed (the parse throws, and the spawned run exits 2).
• Unit tier, pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2: 235 of 237 files passed (3341 tests passed, 29 skipped). The other two, published-subpath-console.pin and published-subpath-hook-body.pin, refused because packages/cli/dist was not built (a prerequisite, not a result). After pnpm --filter @objectstack/cli build: 2/2 files, 29/29 tests passed.
• pnpm --filter @objectstack/cli typecheck: exit 0. check:test-typecheck: OK ... 3 file(s) / 28 error(s) is the ledger's existing figure; the new test adds no error.
• Gates: node scripts/pm/dispatch-gates.mjs --commands, run without paths, derived 63 commands at c36db5507. All 63 exit 0. check:dual-build-cjs-loads and check:i18n-coverage first exited 3 (PREREQUISITE NOT MET) and then 0 once the packages were built. --ran reconciliation: 63 derived, 63 run, 0 NOT-MEASURED, 0 UNRUN.
• pnpm lint: exit 0 at c36db5507.

The gate, lint, unit and typecheck results are on the final head c36db5507. The pin and ablation runs were on fcf4f78e3, and the only later commit adds the changeset file.

Acceptance notes

• The os dev options table in content/docs/deployment/cli.mdx lists neither -w, --[no-]watch nor --[no-]restart, --log-level, --preset, --admin-email or --admin-password. That gap predates this PR, no pin enumerates that table, and the file is outside this card's file surface. Carrier: none.
• Monorepo orchestration mode forwards none of dev's other flags (--port, --fresh, --ui, --artifact together with a PACKAGE, and so on) and says nothing about dropping them. Not measured here. This PR refuses only the flag it made reachable.
• The orchestration branch still prints Watch: enabled whenever watch is on. That line describes the child packages' own dev scripts, which the CLI does not control.
• The Clause-② line is copied from the claim. For the at-tier review: the no-match refusal turns an exit-0 run that started nothing into exit 1, and monorepo mode now needs pnpm 8.13.1 or later, where before any pnpm worked.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: os dev (command, 30 pages)
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 25 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json b28054654d12e6faf92509a69fa416d9f5b56c82 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from c47a0af007f0097dd0a7508be81b527c2a00052c — the merge of head c36db55077d3f439811ec609f19bbbc9f7dae30c into base b28054654d12e6faf92509a69fa416d9f5b56c82, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin c47a0af007f0097dd0a7508be81b527c2a00052c && git checkout c47a0af007f0097dd0a7508be81b527c2a00052c
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin b28054654d12e6faf92509a69fa416d9f5b56c82 c36db55077d3f439811ec609f19bbbc9f7dae30c && git checkout -B drift-repro b28054654d12e6faf92509a69fa416d9f5b56c82 && git merge --no-ff c36db55077d3f439811ec609f19bbbc9f7dae30c

node scripts/docs-audit/affected-docs.mjs --json b28054654d12e6faf92509a69fa416d9f5b56c82

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: c36db55077d3f439811ec609f19bbbc9f7dae30c
Local-runs: none

Inputs read: card #20681 body and its three comments (triage 5895852973, claim 5908367350, os-dev-report 5909733295); PR #20839 body, file list (3 files, +257/-4, 261 changed lines, head repo is the base repo, no governed path) and the net diff from merge-base 73155fedcacc215565c4eef6d9899977e0707010 to the head; the 34 check-runs on the head, collapsed to 34 names with no duplicates: 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke opt-in), 0 failure — all seven required contexts success. At the merge-base: root package.json (packageManager pnpm@10.31.0, engines node 22 or later), packages/cli/package.json (17.5.0; exports closed to ., ./console, ./hook-body, ./package.json; engines node 22 or later, no pnpm range), content/docs/deployment/cli.mdx os dev section, and packages/cli/src/index.ts for question (d). The diffed dev.ts was read at the head for the context its hunks sit in.

① Derived judgments

(a) watch gains allowNo: true — right.

• Accept set: gains exactly one token, --no-watch, which at BASE was a parse-time "Nonexistent flag" exit 2 (card measurement, reproduced by the dev). -w, bare --watch, every other flag and the positional are untouched by the diff. --watch=false parses exactly as before — oclif has no =value form for a boolean, so it is --watch plus the PACKAGE false (pinned: watch: true, package: 'false'). No argv that parsed before parses differently now.
• Declared default default: true is unchanged and accurate: bare os dev gives watch: true and devWatchActive true (pinned). Help text "Watch objectstack.config.ts and src/, rebuilding on change (default: on). Disable with --no-watch." matches the watcher (watchPaths = [configPath] plus src/ when present; rebuild then restart) and the new spelling; oclif also renders --[no-]watch, so the "Disable with" clause is redundant, not wrong.
• flags.watch !== false && !flags.artifact && configExists to devWatchActive({ watch, artifact, configExists }) is equivalent for a boolean watch. The loop comment's --watch=false becoming --no-watch corrects a spelling the CLI never read.

(b) --fail-if-no-match — right, and it is the only newly refused run on a supported pnpm.

• The token is appended only on the packageName !== 'all' branch; os dev and os dev all at a workspace root still run bare pnpm dev, unchanged. With a PACKAGE, pnpm exits non-zero when the filter selects zero projects; the branch's existing catch prints ✗ Development mode failed: Command failed: pnpm --filter VALUE --fail-if-no-match dev and exits 1, so the value is named (through the echoed command, after pnpm's own "No projects matched the filters" line). At BASE that run exited 0 having started nothing — the card's second measurement.
• A filter that matches keeps working (dev's positive control os dev @objectstack/verify ran that package's tsc -w). A matching filter whose packages lack a dev script is pnpm's business either way; the token does not touch it. So on pnpm 8.13.1 or later the no-match PACKAGE is the only newly non-zero run.
• Letting pnpm judge its own filter grammar instead of re-reading the workspace in the CLI is the one-owner rule (PD Add comprehensive test suite for Zod schema validation #12, route and surface ownership Add metamodel interfaces for ObjectQL/ObjectUI contract #1). Right.
• The floor: on a pnpm before 8.13.1 the token is an unknown option, so every PACKAGE-filtered run fails there — loudly (exit 1, command echoed) but without naming the floor. The repo declares pnpm 10.31.0, @objectstack/cli declares node 22 or later and no pnpm range, and the changeset states the floor. Accepted; graded in ② and flagged in ③.

(c) --no-watch refused in monorepo orchestration mode — right, minimal, inside the surface.

• Reachability: (a) makes os dev PKG --no-watch, and os dev --no-watch at a workspace root without objectstack.config.ts, parse; both route to the orchestration branch (the single-environment gate is packageName === 'all' && (configExists || flags.artifact)). Without the block the CLI would print 🔄 Watch: enabled directly under the operator's --no-watch and run each package's own dev script — the declared-not-delivered shape PD chore: version packages #10 forbids and the card exists to close. Accepting and silently ignoring the flag would recreate the exit-0 no-op.
• Newly refused set: nothing that ever worked — every argv it refuses was exit 2 at BASE.
• Minimal: five lines, printError plus one remedy line naming both single-environment routes (config in cwd, or --artifact), process.exit(1) matching the branch's sibling refusal ("Config file not found"), no new flag, no tracker number in the prose. Ordered after the "Config file not found" check, so a directory with neither config nor workspace still gets the more useful error.
• Surface: packages/cli/src/commands/dev.ts, the file the claim names; declared as deviation 1 with a must-fix rationale I accept.

(d) Exported devWatchActive — does not widen @objectstack/cli's published surface.

• The exports map is closed to ., ./console, ./hook-body and ./package.json; there is no ./commands/* subpath and node 22 or later honours the map, so dist/commands/dev.js is not importable by a consumer. The . barrel (src/index.ts, untouched by the diff) re-exports only default as DevCommand from ./commands/dev.js, so the named export never reaches dist/index.d.ts. forwardSeedSettledToParent is already a named export of the same file with the same reachability — prior art. oclif's pattern loader reads the module's default export only. The pin reaches it by the relative ../src/commands/dev.js import, inside the package.

(e) Changeset .changeset/20681-dev-no-watch.md — accurate, with one wording note.

• '@objectstack/cli': patch, Clause-②: no; the 20681- filename prefix is the repo's convention (every sibling at the merge-base is named that way); the body carries no tracker number.
• Every sentence checked against the diff and the measurements: exit 2 before; --watch=false parsed as the PACKAGE false and exited 0 before; --no-watch off and bare on; no-match PACKAGE exits 1 naming the value through --fail-if-no-match; --no-watch in monorepo mode (PACKAGE given, or workspace root without config) exits 1 naming the flag; the remedy "project directory, or --artifact" matches the routing condition. Nothing claimed that the diff does not deliver.
• The floor is stated ("Monorepo mode now needs pnpm 8.13.1 or later"). Wording note: the token is passed only with a PACKAGE argument, so os dev and os dev all at a workspace root carry no floor; the sentence is over-broad by that case, in the conservative direction. The seat may tighten it to "Monorepo mode with a PACKAGE argument" before landing; not verdict-bearing.

Gates and pin. All seven required contexts success on the head (Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance, Governed Surface Queue Guard); Check Changeset success; the three skipped runs are path-filtered opt-ins. The pin drives the parse-and-decide half through oclif's own Parser.parse over Dev.flags and Dev.args, and the shell half through three spawned runs with a control proving the fixture starts when asked; the three ablation legs each went red on exactly the asserted cases. Its only escape from the package is to node_modules/.bin/tsx, which the cross-package gate deliberately does not flag. That the pin executed in CI rests on its integration-tier declaration plus Test Core's green; it was not separately verified here.

② Semver level

Decision: keep @objectstack/cli patch with bare Clause-②: no — the dev's option A. No ADR-0087 disposition is owed.

By AGENTS.md's changeset section the (narrowing) arm is BREAKING and is about a published contract, so the question is what the published door declared:

1. The no-match PACKAGE. cli.mdx declares os dev [package] as "Start development mode with hot reload", shape 3 as "Monorepo root … orchestrates pnpm -r dev across packages", the example as os dev my-package # Workspace package (monorepo orchestration mode), and the positional's own help is "Package name or filter pattern". The declared value set is a workspace package or filter; the promise is to start development mode. A PACKAGE that selects nothing was never inside that set and never received the promise — the exit-0 nothing-started run is the card's defect, not an effect any caller was getting. Refusing it pulls the door back to the contract the docs already state. That is PR fix(runtime,metadata-protocol): the /automation write doors keep the packaged-base lock the /meta door keeps (#20679) #20817's pattern, the negative boundary of clause ② with no arm. PR fix(rest): /import reads a time cell by core's one time rule, so an exported 10:00:00.250 re-imports (#20722) #20829's pattern would apply if the refused value had sat inside the door's declared set with an effect callers relied on; here it did not.
2. --no-watch. The flag's help said "(default)" and the code documented its off branch ("Skipped when: … user opted out"); the diff makes a declared opt-out reachable. A fix of declared-not-delivered, not a new capability — so not yes; and no (widening) is malformed under AGENTS.md anyway.
3. The orchestration-mode refusal refuses only argv that was exit 2 before. No arm.
4. The pnpm floor. The docs name pnpm with no version; the repo's only declared pnpm is 10.31.0; @objectstack/cli declares node 22 or later and no pnpm range. 8.13.1 (December 2023) predates node 22 and every pnpm the repo has ever declared, so no published contract admitted a lower pnpm. A newly stated requirement below every declared floor is not the narrowing of a declared range, and the changeset states it — the text an upgrading agent greps. Had the repo declared a pnpm range that 8.13.1 cuts into, this would be (narrowing), minor, with a disposition; it does not.

③ Boundary flags

Open question (bare no vs no (narrowing)): answered in ② — A, bare no, patch.

Deviations

1. Orchestration-mode --no-watch refusal — accepted, judged in ①(c).
2. devWatchActive extraction and export — accepted, ①(a) and ①(d): behaviour-preserving, no surface widening.
3. Ablation leg A's first try was a no-op, re-run with a disjoint replacement — accepted; declared, and the re-run went red on the two asserted cases.
4. Gate chunk 43-63 backgrounded and waited on a recorded PID — accepted; multi-agent discipline §8 permits waiting on a PID you recorded.
5. Attribution: all three commits carry the model-free Claude-Session / Co-authored-by: Claude pair (verified on the branch) and the PR body carries the session-URL footer — AGENTS.md's form, to which the harness reminder is subordinate. Accepted.
6. One SendMessage reply to the PM probe — procedural, accepted.
7. Cleanup (servers ended by their own timeouts, worktree removed) — accepted.

Out-of-scope findings

1. The cli.mdx os dev options table omits -w, --[no-]watch, --[no-]restart, --log-level and --preset (confirmed at the merge-base; --admin-email and --admin-password appear inline in the seed-admin row, not as rows). Pre-existing, the docs promise less rather than more, and the file is outside the claim's surface, so the acceptance note is the right carrier under PD chore: version packages #10. Escalated to the seat as a docs card to file: the CHANGELOG this PR ships now names --no-watch and the docs page's table does not.
2. Monorepo orchestration mode forwards none of dev's other flags (--port, --fresh, --ui, --artifact with a PACKAGE) and says nothing — unmeasured. If it reproduces it is a declared-not-delivered shape (PD chore: version packages #10). Escalated to the seat: measure one (os dev PKG -p N at the repo root) and file a card naming the repro if it holds. Not this PR's scope.

Reviewer's own flags
3. Changeset wording: "Monorepo mode now needs pnpm 8.13.1 or later" is over-broad by the no-PACKAGE case (①(e)); tighten before landing if the seat wishes. Not verdict-bearing.
4. Floor enforcement: on a pnpm below 8.13.1 the failure is pnpm's "Unknown option" surfaced through the CLI's existing ✗ Development mode failed line — loud, but it does not name the floor. Whether shell-out dependency floors should be declared mechanically (engines.pnpm, or a version probe before the spawn) is a repo-wide decision, not this card's; noted for the seat, no card required now.

Implemented-by: claude/issue-20681-dev-no-watch
Reviewed-by: session_01VvcEokUG1tvVxkceYfR5XB

VERDICT: PASS

---

Generated by Claude Code