diff --git a/docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md b/docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md
new file mode 100644
index 00000000..777eb55c
--- /dev/null
+++ b/docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md
@@ -0,0 +1,403 @@
+---
+title: "Agent CLI Ergonomics: Bulk Ops, Output Contract, and Sync Clarity"
+description: Reduce agent bash contortions (for-loops over issues, output truncation, sync rituals) by adding bulk/multi-target verbs, a trustworthy output contract, and a clear sync model
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+# Feature: Agent CLI Ergonomics (Bulk Ops, Output Contract, Sync Clarity)
+
+**Date:** 2026-06-13 (last updated 2026-06-13)
+
+**Author:** Joshua Levy
+
+**Status:** Draft
+
+> **Revised 2026-06-13 after a senior engineering review on
+> [PR #176](https://github.com/jlevy/tbd/pull/176).** Phase 1 was tightened: `--sync`
+> gets a tri-state intent and an explicit lock boundary, the unsynced hint must be
+> visible (via `output.notice()`, not the verbose-only `output.info()`), single-ID
+> `close`/`reopen` behavior is preserved (skips are bulk-only), bulk `show` is split out
+> as a separate read-only design, and `update --status closed` is excluded from bulk
+> closure. Sync doc fixes extend to `tbd-design.md`.
+
+## Overview
+
+Agents drive tbd through bash, and when a task touches more than one issue they fall
+back to error-prone shell contortions: `for` loops over issue IDs, `2>&1 | tail -1` on
+every command to tame output, `echo "=== ... ==="` headers to hand-roll a progress
+display, and a `--no-sync ... ; tbd sync` ritual to manage syncing.
+These patterns are brittle, hide what happened from the user, and make multi-issue work
+the most failure-prone thing an agent does with tbd.
+
+This spec catalogs the common problems, then proposes a **layered** fix that front-loads
+backward-compatible **quick wins** suitable for the current release (multi-target verbs,
+a trustworthy output contract, and an honest sync model) and maps out **broader ideas**
+(query-driven mutation, a transaction-file `apply` command) as follow-on work.
+
+It is a product/runtime change to tbd’s own CLI. It is distinct from
+[plan-2026-06-03-tbd-agent-cli-guideline-improvements.md](plan-2026-06-03-tbd-agent-cli-guideline-improvements.md),
+which improves the *guideline* about writing agent skills; this spec changes how tbd’s
+issue commands actually behave.
+
+### Motivating example
+
+A real agent command observed in the field (tbd-relevant slice; git/gh plumbing elided):
+
+```bash
+for b in fin-iri4 fin-kq1k fin-c02g; do
+  tbd close $b --reason "Delivered via PR #78 ..." --no-sync --quiet 2>&1 | tail -1
+done
+tbd close fin-xgo2 --reason "Keystone delivered via PR #78 ..." --no-sync --quiet 2>&1 | tail -1
+tbd create "KNOWN_DESCRIPTORS completeness gate ..." -t task -p 3 --parent fin-g1gv \
+  --no-sync --quiet -d '...long multi-paragraph body with $vars and `backticks`...' 2>&1 | tail -1
+tbd create "Reconcile fintool-server SEC mock shape ..." -t task -p 3 --parent fin-g1gv \
+  --no-sync --quiet -d '...' 2>&1 | tail -1
+tbd sync --quiet 2>&1 | tail -1
+```
+
+Every awkward thing here maps to a missing tbd primitive (see Problem Catalog).
+After Phase 1 the close loop collapses to a single call:
+
+```bash
+# one call, one lock, one summary line, one push:
+tbd close fin-iri4 fin-kq1k fin-c02g fin-xgo2 \
+  --reason "Delivered via PR #78 (merged to integration/launch 2026-06-13)" --sync
+```
+
+## Goals
+
+- **Eliminate the bash `for` loop** over issue IDs for the common verbs by accepting
+  multiple targets natively, under one lock, with one summary.
+- **Make output trustworthy** so agents stop wrapping commands in `2>&1 | tail -1`: a
+  documented single-line success contract, a stable `--json` shape, and incidental
+  notices that `--quiet` reliably silences.
+- **Make the sync model honest and self-revealing** so the `--no-sync ... ; tbd sync`
+  ritual is unnecessary: tell the agent when changes are unsynced, and let a bulk write
+  publish once on request.
+- **Remove the shell-quoting hazard** for large text fields (reasons, descriptions,
+  notes) by supporting file and stdin bodies consistently across verbs.
+- **Prioritize backward-compatible quick wins** that can ship in the current release,
+  and map the larger ideas without committing to them yet.
+- **Establish a consistent verb spine** (`verb [ids...] --flags`) future commands
+  inherit.
+
+## Non-Goals
+
+- Owning git/gh plumbing (PR merge, worktree/branch cleanup).
+  tbd will not wrap these; only the issue-tracking half of the motivating example is in
+  scope.
+- A general query/expression language beyond what `list` already understands.
+  Phase 2 reuses the existing filter grammar; it does not invent a new one.
+- Changing the on-disk issue format or the sync-worktree storage model.
+- Interactive TUI work.
+  The output contract targets piped/non-TTY agent use first.
+
+## Background
+
+Findings from the current code (cited so the plan is grounded, not speculative):
+
+- The core mutators each take exactly one ID:
+  [`close.ts:88`](../../../../packages/tbd/src/cli/commands/close.ts),
+  [`update.ts:431`](../../../../packages/tbd/src/cli/commands/update.ts),
+  [`reopen.ts:91`](../../../../packages/tbd/src/cli/commands/reopen.ts), and
+  `show.ts:194` all declare `.argument('<id>')`.
+- The repo already uses variadic args idiomatically elsewhere: `label.ts:201`
+  (`<labels...>`) and `docs-fork.ts:762` (`[names...]`). The mutators are inconsistent,
+  not idiomatically blocked.
+- Argument conventions are uneven: `label add <id> <labels...>` is variadic on the
+  *label* axis (one issue, many labels), `dep add <issue> <depends-on>` is pairwise,
+  `docs fork [names...]` is variadic, and the issue mutators are single.
+  There is no shared `verb [ids...] --flags` spine.
+- `success()` already prints exactly one line
+  ([`output.ts:382`](../../../../packages/tbd/src/cli/lib/output.ts)), but two stderr
+  notices can interleave with it: worktree auto-heal
+  ([`data-context.ts:183`](../../../../packages/tbd/src/cli/lib/data-context.ts)) and
+  config migration (`data-context.ts:164`).
+- **`--no-sync` is effectively a no-op for issue writes.** The `sync` boolean is set in
+  [`context.ts:46`](../../../../packages/tbd/src/cli/lib/context.ts) but read by no
+  mutator; `auto_sync` has no issue-level consumer in `src/` (only the docs cache honors
+  `doc_auto_sync_hours`). Writes stage into the hidden sync worktree and are published
+  only by `tbd sync`.
+- The right shape already exists in one place: `import` ingests many issues under a
+  single lock, prints one summary line, and nudges *“Run `tbd sync` to commit and push
+  imported issues”*
+  ([`import.ts:293`](../../../../packages/tbd/src/cli/commands/import.ts)). The mutators
+  should adopt the same shape.
+
+## Problem Catalog
+
+The common problems agents hit, each with the bash symptom it produces:
+
+1. **P1: Single-target mutators force shell loops.** `close`/`reopen`/`update`/`show`
+   take one `<id>`, so N issues become `for b in ...; do tbd close $b ...; done`. Each
+   iteration re-acquires the repo lock and re-resolves the worktree (N times the work),
+   and a mid-loop failure leaves a partially-applied change with no transaction
+   boundary.
+
+2. **P2: No query-driven mutation (no select-and-act).** There is no way to express
+   “close all open children of X” or “label everything matching Y” without first
+   listing, parsing IDs out of text/JSON, and looping.
+   The read side has filters (`list`, `ready`, `blocked`, `stale`, `search`); the write
+   side cannot consume them.
+
+3. **P3: Output is not trusted, so agents truncate it.** Despite the single-line
+   `success()`, agents defensively pipe `2>&1 | tail -1` because they cannot be sure how
+   many lines a command emits, stderr notices interleave with stdout, and in a loop they
+   only want the final line.
+   `tail -1` then swallows real errors, hiding failures.
+
+4. **P4: No structured, user-visible record of a multi-step session.** The agent
+   hand-rolls a UI with `echo "=== ... ==="` because tbd surfaces nothing to the user.
+   A multi-issue tbd session is invisible unless the agent narrates it, and there is no
+   machine- and human-readable “here is the batch I just applied” summary.
+
+5. **P5: The sync model is murky and partly vestigial.** `--no-sync` is consumed by no
+   mutator and `auto_sync` is not wired for issues, yet both *imply* a per-command sync.
+   Agents cargo-cult `--no-sync` on each write and append a final `tbd sync`, getting
+   the right outcome by accident.
+   Nothing tells the agent “you have N unsynced changes.”
+
+6. **P6: Large text fields inline in the shell are a quoting and correctness hazard.**
+   Multi-paragraph `--reason "..."` / `-d '...'` strings containing `$`, backticks,
+   quotes, or `#` are pasted straight into bash, risking interpolation, truncation, or
+   command injection, and are not reviewable.
+   `create` already supports `--file`/`-f` and `update` supports `--notes-file`, but
+   `close --reason` has no file form and there is no batch equivalent or shared stdin
+   (`-`) convention.
+
+7. **P7: Inconsistent argument conventions.** Without a `verb [ids...] --flags` spine,
+   agents cannot generalize muscle memory across verbs and reach for bash instead (see
+   Background for the specific inconsistencies).
+
+8. **P8: No preview/confirm discipline for set-based writes.** `--dry-run` exists
+   globally but there is no “show the N items this would touch, then apply” affordance,
+   which is exactly what makes query-driven mutation (P2) safe to offer.
+
+9. **P9 (adjacent, broader): “delivered by PR #N” has no first-class expression.** The
+   recurring intent “close these as delivered via PR #78” always degrades into bespoke
+   bash and an unstructured reason string, so the provenance is not queryable later.
+   Out of tbd’s direct control for the git half, but the bead half could be first-class.
+
+## Design
+
+### Approach
+
+Layer the work so value lands early and risk stays low:
+
+- **Phase 1 (quick wins, current release):** purely additive, backward-compatible
+  changes to existing verbs.
+  Multi-target IDs, a bulk summary + accurate sync hint, file/stdin bodies for reasons,
+  and an honest sync contract.
+  No new top-level commands.
+- **Phase 2 (broader, follow-on):** query-driven mutation and a transaction-file `apply`
+  command. These are larger surfaces with real blast radius and get their own design
+  pass; this spec scopes them enough to file beads, not to build blind.
+
+### Components
+
+CLI command modules under `packages/tbd/src/cli/commands/` (`close.ts`, `reopen.ts`,
+`update.ts`, `show.ts`), the shared output layer (`cli/lib/output.ts`), the command
+context (`cli/lib/context.ts`), and the data context that owns the lock
+(`cli/lib/data-context.ts`). Phase 2 adds a new `apply.ts` that generalizes the existing
+`import.ts` ingestion path.
+
+### API Changes (Phase 1, backward-compatible)
+
+- **Variadic IDs (mutators).** Change `close`/`reopen`/`update` from `<id>` to
+  `<ids...>` (mutators only; **not** `show`, see below).
+  A single ID behaves exactly as today.
+  Multiple IDs are processed under one `withDataSyncContext({ lock: true })` pass.
+  - `tbd close A B C --reason "..."` applies the shared reason to all.
+  - `tbd update A B C --add-label delivered --priority 3` applies shared **field**
+    updates to all. Per-ID-only flags (e.g. `--title`) are rejected when more than one ID
+    is given. Closing is done via `close`, **not** `update --status closed`: `update`
+    assigns `status` only and does not set `closed_at`/`close_reason`, so using it as a
+    bulk close would write semantically incomplete issues (PR #176 review).
+    Bulk `update` is limited to fields with no lifecycle side effects.
+  - **Validation/atomicity (default, fail-closed):** resolve all IDs first; if any is
+    unknown, abort before writing anything and list the bad IDs.
+    `--ignore-missing` downgrades unknown IDs to skips.
+  - **Single-ID behavior is preserved exactly (PR #176 review).** Single-target `close`
+    of an already-closed issue stays idempotent (silent success); single-target `reopen`
+    of an already-open issue keeps **erroring with exit 1** (locked by
+    `cli-crud.tryscript.md`). The “`already-X` is a reported *skip*” rule applies **only
+    to bulk paths** (2+ IDs), where the intent is batch completion.
+    Every existing single-ID golden stays green.
+- **Bulk `show` is a separate, read-only design (PR #176 review), not part of this
+  mutator slice.** `show` takes no write lock, emits multi-line YAML/Markdown plus
+  optional parent context, and shares none of the summary/hint/`--sync` contract.
+  A safe version is `tbd show A B C` rendering each issue with a delimiter and `--json`
+  returning an array; it is tracked separately and may land later.
+- **Bulk summary + visible sync hint.** A multi-target write prints one deterministic
+  summary line (text mode), e.g.
+  `Closed 3, skipped 1 (already closed): tbd-a tbd-b tbd-c`. When changes are unsynced
+  it prints a **visible** hint.
+  Caveat (PR #176 review): the `import` nudge is emitted via `output.info()`, which only
+  shows under `--verbose`/`--debug`, so it must not be copied verbatim.
+  Route the hint through `output.notice()` (shown at the default level, suppressed by
+  `--quiet` and `--json`). `--json` carries it as structured state instead:
+  `{ results: [{ id, action, ok, skippedReason? }], summary: {...}, sync: { pending: true, hint: "..." } }`.
+- **File/stdin bodies.** Add `--reason-file <path>` to `close`/`reopen`, and a shared
+  `-` convention so `--reason -`, `-d -`, and `--notes -` read the body from stdin.
+  This removes the P6 quoting hazard for big text without per-verb special cases.
+- **Honest sync (decided: stage-then-publish; `--no-sync` removed).** Keep the
+  stage-then-publish model: writes land in the sync worktree and are published by
+  `tbd sync`. There is **no** per-command auto-sync, and tbd will **not** move to an
+  always-auto-sync model.
+  - **`--no-sync` is removed outright (revised 2026-06-14).** It set a `ctx.sync` flag
+    that no mutator ever read, so it was a pure no-op that only fed the
+    `--no-sync … ; tbd sync` cargo-cult.
+    Dropping it (and the dead `ctx.sync` field) means `tbd <verb> --no-sync` now errors
+    as an unknown option — the honest signal.
+  - **A later opt-in `--sync` is possible but non-essential.** If ever added it would
+    publish once at the end of a (bulk) write, never on by default.
+    Implementation note for that day: apply all writes under one
+    `withDataSyncContext({ lock: true })` pass, *release that lock*, and only then run
+    the sync path (which re-takes the same non-reentrant lock and performs network I/O),
+    so a bulk write is a single call with no nested lock.
+
+### API Changes (Phase 2, sketch only)
+
+- **Query-driven mutation.** `tbd close --where "<filter>"` (and `update`, `reopen`)
+  reusing the `list` filter vocabulary.
+  **Prerequisite (PR #176 review):** that vocabulary is currently an
+  implementation-local `ListOptions` shape inside `list.ts`, not a reusable selector.
+  Phase 2 must first extract a shared selector module used by both `list` and the
+  mutators, with tests proving read and write selection match.
+  Always prints the matched set and count first; requires `--yes` above a small
+  threshold, or `--dry-run` to preview only.
+  Resolves P2 and P8.
+
+- **Transaction file.** `tbd apply <file>` (or `... | tbd apply -`) applies a YAML/JSON
+  document of mixed `create`/`close`/`update` operations under one lock, syncs once, and
+  prints a structured summary.
+  The clean answer to **creating many distinct issues** (which variadic cannot express,
+  since each needs its own title/body) and to P6 at batch scale.
+  It generalizes `import`. **Caveat (PR #176 review):** a real atomicity promise needs a
+  transaction/rollback story spanning issue writes, ID-mapping updates, parent
+  `child_order_hints`, and sync; a failure after mapping or hint writes could otherwise
+  leave partial state.
+  Phase 2 must specify that boundary.
+
+  ```yaml
+  # delivery.yml
+  close:
+    - ids: [fin-iri4, fin-kq1k, fin-c02g, fin-xgo2]
+      reason: "Delivered via PR #78 (merged to integration/launch 2026-06-13)"
+  create:
+    - { title: "KNOWN_DESCRIPTORS completeness gate", type: task, priority: 3,
+        parent: fin-g1gv, description_file: followup-1.md }
+    - { title: "Reconcile fintool-server SEC mock shape", type: task, priority: 3,
+        parent: fin-g1gv, description_file: followup-2.md }
+  sync: true
+  ```
+
+## Implementation Plan
+
+### Phase 1: Quick wins (current release)
+
+- [x] Make `close`, `reopen`, `update` accept `<ids...>` (mutators only; **not**
+  `show`); single-ID behavior unchanged.
+  Process all IDs under one locked data-sync context.
+- [x] Implement the validation/atomicity policy (validate-all-then-apply; `already-X` as
+  a **bulk-only** skip while single-ID `close`/`reopen` keep current behavior;
+  `--ignore-missing`); reject per-ID-only flags when multiple IDs are passed.
+- [x] Add the bulk summary line and the structured `--json` results array; emit the
+  unsynced-changes hint via `output.notice()` (visible by default), **not**
+  `output.info()` (which is `import`’s verbose-only nudge).
+- [x] Output contract (PR #176 review): keep `--quiet` **silent on success** (preserves
+  the `cli-advanced.tryscript.md` quiet-create golden); default **text** mode prints the
+  one-line summary; `--json` is the machine contract.
+  Suppress worktree-heal and config-migration stderr notices under `--quiet` too, so
+  `2>&1 | tail -1` is unnecessary.
+- [x] Add `--reason-file` to `close`/`reopen` and the shared `-`/stdin convention for
+  `--reason`, `-d/--description`, and `--notes` (one shared body reader).
+- [x] Sync: **remove `--no-sync`** (and the dead `ctx.sync` field) — it was a no-op that
+  only fed the `--no-sync … ; tbd sync` cargo-cult; default stays stage-only with no
+  per-command auto-sync.
+  A later opt-in `--sync` (publish once at end, under the lock, released before syncing
+  — no nested lock) remains possible but non-essential.
+  Land the sync doc fixes in the manual, `tbd prime`, **and `tbd-design.md`** (see
+  Rollout).
+- [x] Document the output contract (one-line summary; `--json` shape; what `--quiet`
+  guarantees) in `tbd-docs.md` and the `cli-agent-skill-patterns` guideline examples.
+- [ ] (Separate, read-only, optional this release) bulk `tbd show A B C` → delimited
+  text / `--json` array; no write lock, no summary/sync contract.
+  Tracked apart from the mutators.
+
+### Phase 2: Broader (follow-on, separate design pass)
+
+- [ ] Query-driven mutation (`--where` reusing the `list` grammar) with mandatory
+  preview + `--yes` threshold.
+- [ ] `tbd apply` transaction file generalizing `import`, with a structured summary and
+  single sync.
+- [ ] (Smaller follow-ons) First-class delivery provenance (P9), e.g.
+  `close --by-pr <n>` recording structured provenance; a documented `verb [ids...]`
+  spine future verbs inherit.
+
+## Testing Strategy
+
+- **tryscript e2e goldens** (the repo’s `.tryscript.md` harness): bulk
+  close/reopen/update with mixed already-X and unknown IDs; `--ignore-missing`;
+  single-ID backward compatibility; `--reason-file` and stdin bodies; the `--json`
+  results array shape.
+  Per the PR #176 review, also lock down:
+  - `--no-sync` is **removed**: `tbd <verb> --no-sync` errors as an unknown option, and
+    no mutator auto-syncs (writes stage; `tbd sync` publishes).
+  - the lock boundary around bulk-write-then-sync (no nested lock acquisition).
+  - `reopen` already-open: single-ID errors (exit 1) vs bulk reports a skip.
+  - `update --status closed` is rejected in bulk (or sets lifecycle metadata if ever
+    added); bulk `update` otherwise touches only side-effect-free fields.
+  - default text vs `--quiet` (silent on success) vs `--json` output contracts.
+  - stdin bodies for `--reason -`, `--description -`, `--notes -` with shell-sensitive
+    text (`$`, backticks, quotes).
+- **vitest unit tests** for the validate-all-then-apply policy and the summary/exit-code
+  logic (non-zero exit when any target failed under the default policy).
+- Phase 2 gets its own test plan at design time.
+
+## Rollout Plan
+
+- Phase 1 is additive and backward-compatible, so it ships in the current release cycle.
+  Update `packages/tbd/CHANGELOG.md`, the `tbd-docs.md` manual, `tbd prime`, the
+  agent-CLI guideline examples, **and `tbd-design.md`** in the same change.
+  Specifically fix the stale `--no-sync`/`auto_sync` “real issue-write behavior” claims
+  in `tbd-docs.md` (~L805-827, L1094-1098, L1263-1267) and `tbd-design.md` (~L1608-1646,
+  L2936-2961) so the repo stops carrying contradictory sync semantics (PR #176 review).
+- Phase 2 ships in a later release after its own design pass; nothing in Phase 1 blocks
+  on it, and Phase 1 establishes the conventions Phase 2 builds on.
+
+## Open Questions
+
+- **Sync model fork.** ~~Three options for the `--no-sync`/`auto_sync` vestige.~~
+  **Resolved 2026-06-13 as (a), then revised 2026-06-14 to (c): remove `--no-sync`
+  outright.** Keep stage-then-publish; default stage-only; no per-command auto-sync and
+  no always-auto-sync.
+  `--no-sync` set a `ctx.sync` flag no mutator read, so it is deleted rather than kept
+  as a no-op; a later opt-in `--sync` (one push per batch) stays possible but
+  non-essential. (Rejected: (b) per-command auto-sync behind `auto_sync`.)
+- **Default atomicity for bulk writes.** ~~Fail-closed vs best-effort?~~ **Resolved (PR
+  #176 review): fail-closed by default** (abort the batch on any unknown ID), with
+  `--ignore-missing` as the explicit best-effort escape hatch.
+- **`--where` grammar reuse.** ~~Reuse `list`’s vocabulary?~~ **Resolved (PR #176
+  review): yes, but Phase 2 must first extract a shared selector module** from
+  `list.ts`’s implementation-local `ListOptions`, with tests proving read and write
+  selection match.
+- **Target release.** Confirm Phase 1 is intended for the current (v0.3.x) cycle.
+- **Self-tracking.** Do we want this filed as a tbd epic + child beads linked to this
+  spec via `--spec` (dogfooding the very ergonomics under discussion)?
+
+## References
+
+- Senior engineering review that tightened Phase 1:
+  [PR #176](https://github.com/jlevy/tbd/pull/176) (jlevy, 2026-06-13).
+- Motivating analysis and code findings: this repo’s command sources cited inline above
+  (`close.ts`, `update.ts`, `reopen.ts`, `import.ts`, `output.ts`, `context.ts`,
+  `data-context.ts`).
+- Related (distinct) guideline plan:
+  [plan-2026-06-03-tbd-agent-cli-guideline-improvements.md](plan-2026-06-03-tbd-agent-cli-guideline-improvements.md)
+- Agent-CLI guideline: `tbd guidelines cli-agent-skill-patterns`
+  ([packages/tbd/docs/guidelines/cli-agent-skill-patterns.md](../../../../packages/tbd/docs/guidelines/cli-agent-skill-patterns.md))
+- Design doc (sync model): [tbd-design.md](../../../../packages/tbd/docs/tbd-design.md)
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->
diff --git a/packages/tbd/CHANGELOG.md b/packages/tbd/CHANGELOG.md
index de43f592..78765350 100644
--- a/packages/tbd/CHANGELOG.md
+++ b/packages/tbd/CHANGELOG.md
@@ -13,6 +13,18 @@ upgrading is safe and revertible.
 
 ### Features
 
+- **Agent CLI ergonomics (Phase 1)**: `close`, `reopen`, and `update` now accept
+  multiple IDs and process them under one lock, printing a single summary line (or a
+  structured `--json` `{ results, summary, sync }` object) plus a visible
+  unsynced-changes hint.
+  Validation is fail-closed, with `--ignore-missing` to downgrade unknown IDs to skips;
+  single-ID behavior is unchanged.
+  Free-text bodies (`--reason`/`--reason-file`, `-d`/`-f`, `--notes`/`--notes-file`)
+  accept `-` to read stdin, so shell-sensitive text no longer needs careful quoting.
+  `--quiet` is now fully silent on success (it also suppresses incidental worktree-heal
+  and config-migration notices).
+  The legacy no-op global `--no-sync` flag has been removed — writes always stage
+  locally and `tbd sync` publishes.
 - **Forkable docs** (`tbd docs fork` / `unfork` / `update` / `diff` / `status`): fork
   any managed doc into a visible fork dir (`docs/tbd/`, laid out by kind with a
   generated `README.md` index, tracked in git).
diff --git a/packages/tbd/docs/tbd-design.md b/packages/tbd/docs/tbd-design.md
index 954633d7..6a620322 100644
--- a/packages/tbd/docs/tbd-design.md
+++ b/packages/tbd/docs/tbd-design.md
@@ -1621,7 +1621,7 @@ display:
 
 # Runtime settings
 settings:
-  auto_sync: false # Auto-sync after write operations
+  auto_sync: false # Reserved; not applied to issue writes (they stage locally; run `tbd sync`)
   index_enabled: true # Enable search indexing
 ```
 
@@ -1640,7 +1640,7 @@ const ConfigSchema = z.object({
     }),
   settings: z
     .object({
-      auto_sync: z.boolean().default(false),
+      auto_sync: z.boolean().default(false), // reserved; issue writes stage locally
       index_enabled: z.boolean().default(true),
     })
     .default({}),
@@ -2598,14 +2598,13 @@ Options:
   --from-file <path>        Create from YAML+Markdown file (all fields)
   --type <type>             Issue type: bug, feature, task, epic, chore (default: task)
   --priority <0-4>          Priority (0=critical, 4=lowest, default: 2)
-  --description <text>      Description
-  --file <path>             Read description from file
+  --description <text>      Description ("-" reads stdin)
+  --file <path>             Read description from file ("-" reads stdin)
   --assignee <name>         Assignee
   --due <date>              Due date (ISO8601)
   --defer <date>            Defer until date (ISO8601)
   --parent=<id>             Parent issue ID
   --label <label>           Add label (repeatable)
-  --no-sync                 Don't sync after create
 ```
 
 > **Note on `--type` flag:** The CLI flag `--type` sets the issue’s `kind` field, NOT
@@ -2882,27 +2881,31 @@ tbd update proj-a1b2 --from-file issue.md
 #### Update
 
 ```bash
-tbd update <id> [options]
+tbd update <ids...> [options]
 
 Options:
-  --from-file <path>        Update all fields from YAML+Markdown file
-  --title <text>            Set title
-  --status <status>         Set status
+  --from-file <path>        Update all fields from YAML+Markdown file (single ID)
+  --title <text>            Set title (single ID)
+  --status <status>         Set status (single ID)
   --type <type>             Set type
   --priority <0-4>          Set priority
   --assignee <name>         Set assignee
-  --description <text>      Set description
-  --notes <text>            Set working notes
-  --notes-file <path>       Set notes from file
+  --description <text>      Set description ("-" reads stdin; single ID)
+  --notes <text>            Set working notes ("-" reads stdin; single ID)
+  --notes-file <path>       Set notes from file ("-" reads stdin; single ID)
   --due <date>              Set due date
   --defer <date>            Set deferred until date
   --add-label <label>       Add label
   --remove-label <label>    Remove label
-  --parent=<id>             Set parent
-  --child-order <ids>    Set child ordering hints (comma-separated)
-  --no-sync                 Don't sync after update
+  --parent=<id>             Set parent (single ID)
+  --child-order <ids>       Set child ordering hints (comma-separated; single ID)
+  --ignore-missing          Skip unknown IDs instead of failing (bulk)
 ```
 
+With two or more IDs, only shared fields apply (`--type`, `--priority`, `--assignee`,
+`--add-label`, `--remove-label`, `--due`, `--defer`); per-ID and lifecycle flags are
+rejected. Use `tbd close`/`tbd reopen` for lifecycle changes.
+
 **Examples:**
 
 ```bash
@@ -2936,11 +2939,12 @@ tbd update proj-a1b2 --from-file issue.md
 #### Close
 
 ```bash
-tbd close <id> [options]
+tbd close <ids...> [options]
 
 Options:
-  --reason <text>           Close reason
-  --no-sync                 Don't sync after close
+  --reason <text>           Close reason ("-" reads stdin)
+  --reason-file <path>      Read close reason from a file ("-" reads stdin)
+  --ignore-missing          Skip unknown IDs instead of failing (bulk)
 ```
 
 **Examples:**
@@ -2953,11 +2957,12 @@ tbd close proj-a1b2 --reason "Fixed in commit abc123"
 #### Reopen
 
 ```bash
-tbd reopen <id> [options]
+tbd reopen <ids...> [options]
 
 Options:
-  --reason <text>           Reopen reason
-  --no-sync                 Don't sync after reopen
+  --reason <text>           Reopen reason ("-" reads stdin)
+  --reason-file <path>      Read reopen reason from a file ("-" reads stdin)
+  --ignore-missing          Skip unknown IDs instead of failing (bulk)
 ```
 
 #### Ready
@@ -3571,7 +3576,6 @@ Available on all commands:
 --version                   Show version
 --db <path>                 Custom .tbd directory path (Beads compat alias)
 --dir <path>                Custom .tbd directory path (preferred)
---no-sync                   Disable auto-sync (per command)
 --json                      JSON output
 --color <when>              Colorize output: auto, always, never (default: auto)
 --actor <name>              Override actor name (not yet implemented)
@@ -3727,7 +3731,6 @@ tbd attic restore <id> <timestamp> [options]
 
 Options:
   --dry-run                 Show what would be restored
-  --no-sync                 Don't sync after restore
 ```
 
 **Example:**
@@ -3830,7 +3833,6 @@ Options:
   --from-beads [path]     Auto-detect from .beads/ directory (default: current dir)
   --branch <name>         Specific branch to import from (default: both main + sync)
   --dry-run               Show what would be imported without making changes
-  --no-sync               Don't sync after import
   --verbose               Show detailed import progress
 ```
 
@@ -4145,7 +4147,7 @@ IMPORT_BEADS(jsonl_file):
 
   4. Report: N new, M updated, K unchanged, J skipped (tbd newer)
 
-  5. Sync (unless --no-sync)
+  5. Stage locally (publish later with `tbd sync`)
 
 extract_short_id(beads_id):
   # "tbd-100" → "100"
@@ -4511,7 +4513,7 @@ These flags/behaviors are maintained for Beads script compatibility:
 2. **No daemon**: Background sync must be manual or cron-based
 
 3. **No auto-flush**: Beads auto-syncs on write
-   - tbd syncs on `tbd sync` or with `settings.auto_sync: true` in config
+   - tbd publishes issues on `tbd sync` (per-command auto-sync is not currently enabled)
 
 4. **Tombstone issues**: Decide import behavior (skip/convert/attic)
 
@@ -5476,7 +5478,7 @@ This is sufficient for the `ready` command algorithm.
 | `--help` | `--help` | ✅ Full | Help text |
 | `--version` | `--version` | ✅ Full | Version info |
 | `--db <path>` | `--db <path>` | ✅ Full | Custom .tbd path |
-| `--no-sync` | `--no-sync` | ✅ Full | Skip auto-sync |
+| `--no-sync` | *(n/a)* | ❌ Dropped | Removed; issue writes always stage locally (run `tbd sync` to publish) |
 | `--actor <name>` | `--actor <name>` | 🔄 Future | Override actor |
 | *(n/a)* | `--dry-run` | ✅ tbd | Preview changes |
 | *(n/a)* | `--verbose` | ✅ tbd | Debug output |
diff --git a/packages/tbd/docs/tbd-docs.md b/packages/tbd/docs/tbd-docs.md
index ff41597c..d7ee7550 100644
--- a/packages/tbd/docs/tbd-docs.md
+++ b/packages/tbd/docs/tbd-docs.md
@@ -343,10 +343,19 @@ Options:
 - `--spec <path>` - Set or clear spec path (empty string clears; validated and
   normalized). When updating a parent issue’s spec, the new value propagates to children
   whose `spec_path` was null or matched the old value.
+- `--ignore-missing` - Skip unknown IDs instead of failing the batch
+
+**Multiple IDs:** `tbd update A B C --priority 1 --add-label done` applies the same
+field updates to every issue under one lock.
+Per-ID-only flags (`--title`, `--description`, `--notes`/`--notes-file`) are rejected
+with two or more IDs, and `--status closed` is rejected in bulk — use `tbd close`.
+`--description` and `--notes` also accept `-` to read stdin.
 
 ### close
 
-Close a completed issue.
+Close one or more completed issues.
+A single ID keeps the classic one-line output; two or more run as a bulk operation — see
+**Bulk operations and the output contract** below.
 
 ```bash
 tbd close proj-a7k2                           # Close issue
@@ -354,11 +363,14 @@ tbd close proj-a7k2 --reason="Fixed in PR #42"
 ```
 
 Options:
-- `--reason <text>` - Reason for closing
+- `--reason <text>` - Reason for closing (`-` reads stdin)
+- `--reason-file <path>` - Read the close reason from a file (`-` reads stdin)
+- `--ignore-missing` - Skip unknown IDs instead of failing the batch
 
 ### reopen
 
-Reopen a closed issue.
+Reopen one or more closed issues — see **Bulk operations and the output contract**
+below.
 
 ```bash
 tbd reopen proj-a7k2                          # Reopen issue
@@ -366,7 +378,48 @@ tbd reopen proj-a7k2 --reason="Bug reappeared"
 ```
 
 Options:
-- `--reason <text>` - Reason for reopening
+- `--reason <text>` - Reason for reopening (`-` reads stdin)
+- `--reason-file <path>` - Read the reopen reason from a file (`-` reads stdin)
+- `--ignore-missing` - Skip unknown IDs instead of failing the batch
+
+### Bulk operations and the output contract
+
+`close`, `reopen`, and `update` accept multiple IDs and process them together under a
+single lock. The output is designed so agents never need `2>&1 | tail -1`:
+
+- **One summary line** on success, e.g. `✓ Closed 3, skipped 1 (already closed): …`,
+  followed by a visible `• Unsynced changes — run tbd sync to publish.` hint.
+
+- **Fail-closed validation**: if any ID is unknown the whole batch aborts before writing
+  anything and lists the bad IDs.
+  Add `--ignore-missing` to downgrade unknown IDs to skips instead.
+
+- **Single-ID behavior is unchanged**: one ID behaves exactly as before (idempotent
+  close; reopening an already-open issue still errors).
+  The “already-done is a skip” rule applies only to multi-ID batches.
+
+- **`--quiet`** is silent on success and also suppresses incidental notices (worktree
+  auto-heal, config migration), so output stays clean.
+
+- **`--json`** replaces the summary line with a machine contract:
+
+  ```json
+  {
+    "results": [{ "id": "proj-a7k2", "action": "closed", "ok": true }],
+    "summary": { "changed": 1, "skipped": 0, "missing": 0, "total": 1 },
+    "sync": { "pending": true, "hint": "Run `tbd sync` to publish." }
+  }
+  ```
+
+**Free-text bodies without quoting hazards.** Reasons, descriptions, and notes accept
+the text inline, from a file (`--reason-file`, `-f`/`--file`, `--notes-file`), or from
+stdin with the `-` convention (`--reason=-`, `-d -`, `--notes=-`), so shell-sensitive
+text (`$`, backticks, quotes) round-trips verbatim instead of being mangled by the
+shell.
+
+**Sync is stage-then-publish.** Every write lands in the local `tbd-sync` worktree
+immediately; nothing reaches the remote until you run `tbd sync`. There is no
+per-command auto-sync, and the legacy no-op `--no-sync` flag has been removed.
 
 ### ready
 
@@ -811,7 +864,6 @@ tbd list --json                             # JSON output
 tbd list --quiet                            # Suppress non-essential output
 tbd list --verbose                          # Enable verbose output
 tbd create "Test" --dry-run                 # Show what would happen
-tbd close proj-a7k2 --no-sync                 # Skip automatic sync
 tbd list --debug                            # Show internal IDs
 tbd list --color=never                      # Disable colors
 ```
@@ -823,7 +875,6 @@ Options:
 - `--quiet` - Suppress non-essential output
 - `--json` - Output as JSON
 - `--color <when>` - Colorize output: auto, always, never
-- `--no-sync` - Skip automatic sync after write operations
 - `--debug` - Show internal IDs alongside display IDs
 
 ## For AI Agents
@@ -1094,7 +1145,7 @@ display:
 sync:
   branch: tbd-sync           # Sync branch name
   remote: origin             # Remote name
-  auto_sync: true            # Auto-sync after writes
+  auto_sync: false           # Reserved; issue writes stage locally — run `tbd sync` to publish
 
 docs_cache:
   files:                     # Docs synced into the cache: destination -> docref
@@ -1262,10 +1313,9 @@ Notes:
   A bigger hammer also exists: deleting the entire `$GIT_COMMON_DIR/tbd/` directory is
   recoverable (layout and the data-sync worktree re-materialize from the config and the
   `tbd-sync` branch on the next command, or via `tbd doctor --fix`); **but only for
-  synced data**. Issue changes made with `--no-sync` since the last `tbd sync` live as
-  uncommitted files inside that worktree and would be lost, so run `tbd sync` first if
-  you must delete it. This is why the recipe deletes only `layout.yml`, never the whole
-  directory.
+  synced data**. Issue changes since the last `tbd sync` live as uncommitted files
+  inside that worktree and would be lost, so run `tbd sync` first if you must delete it.
+  This is why the recipe deletes only `layout.yml`, never the whole directory.
 - **Interrupted upgrades self-heal.** If the process dies between the two stamp writes
   (layout updated but not config, or config but not layout), the next command with the
   new version completes the migration; the abort recipe above also works from either
diff --git a/packages/tbd/src/cli/cli.ts b/packages/tbd/src/cli/cli.ts
index 41e0b4cd..a49d7b90 100644
--- a/packages/tbd/src/cli/cli.ts
+++ b/packages/tbd/src/cli/cli.ts
@@ -69,7 +69,6 @@ function createProgram(): Command {
     .option('--quiet', 'Suppress non-essential output')
     .option('--json', 'Output as JSON')
     .option('--color <when>', 'Colorize output: auto, always, never', 'auto')
-    .option('--no-sync', 'Skip automatic sync after write operations')
     .option('--debug', 'Show internal IDs alongside public IDs for debugging');
 
   // Add commands in logical groups
diff --git a/packages/tbd/src/cli/commands/close.ts b/packages/tbd/src/cli/commands/close.ts
index 0d127d4c..67c221f9 100644
--- a/packages/tbd/src/cli/commands/close.ts
+++ b/packages/tbd/src/cli/commands/close.ts
@@ -1,7 +1,12 @@
 /**
- * `tbd close` - Close an issue.
+ * `tbd close` - Close one or more issues.
  *
- * See: tbd-design.md §4.4 Close
+ * A single ID preserves the legacy output exactly. Two or more IDs are a bulk
+ * operation: processed under one lock, with a one-line summary, a structured
+ * `--json` results array, and a visible unsynced-changes hint.
+ *
+ * See: tbd-design.md §4.4 Close and
+ * docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md
  */
 
 import { Command } from 'commander';
@@ -11,83 +16,115 @@ import { requireInit, NotFoundError } from '../lib/errors.js';
 import { readIssue, writeIssue } from '../../file/storage.js';
 import { formatDisplayId, formatDebugId } from '../../lib/ids.js';
 import { now } from '../../utils/time-utils.js';
-import { resolveToInternalId } from '../../file/id-mapping.js';
 import { withDataSyncContext } from '../lib/data-context.js';
+import { resolveAllIds, emitBulkSummary, type BulkItemResult } from '../lib/bulk.js';
+import { resolveBodyInput } from '../lib/body-input.js';
 
 interface CloseOptions {
   reason?: string;
+  reasonFile?: string;
+  ignoreMissing?: boolean;
 }
 
 class CloseHandler extends BaseCommand {
-  async run(id: string, options: CloseOptions): Promise<void> {
+  async run(ids: string[], options: CloseOptions): Promise<void> {
     const tbdRoot = await requireInit();
-
-    let displayId = id;
-    let alreadyClosed = false;
-    let didClose = false;
+    const results: BulkItemResult[] = [];
 
     await this.execute(async () => {
+      const reason = await resolveBodyInput({
+        name: '--reason',
+        value: options.reason,
+        fileName: '--reason-file',
+        file: options.reasonFile,
+      });
       await withDataSyncContext(
         tbdRoot,
         { lock: true },
         async ({ dataSyncDir, mapping, config }) => {
-          // Resolve input ID to internal ID
-          let internalId: string;
-          try {
-            internalId = resolveToInternalId(id, mapping);
-          } catch {
-            throw new NotFoundError('Issue', id);
-          }
+          const { resolved, missing } = resolveAllIds(ids, mapping);
 
-          // Load existing issue
-          let issue;
-          try {
-            issue = await readIssue(dataSyncDir, internalId);
-          } catch {
-            throw new NotFoundError('Issue', id);
+          // Fail closed: any unknown ID aborts before writing anything, unless
+          // the caller opted into best-effort with --ignore-missing.
+          if (missing.length > 0 && !options.ignoreMissing) {
+            throw new NotFoundError('Issue', missing.join(', '));
           }
 
-          displayId = this.ctx.debug
-            ? formatDebugId(issue.id, mapping, config.display.id_prefix)
-            : formatDisplayId(issue.id, mapping, config.display.id_prefix);
-
-          // Idempotent: if already closed, succeed silently without modification
-          if (issue.status === 'closed') {
-            alreadyClosed = true;
-            didClose = true;
+          const dryRunMessage =
+            ids.length === 1 ? 'Would close issue' : `Would close ${resolved.length} issues`;
+          if (this.checkDryRun(dryRunMessage, { ids: resolved.map((r) => r.internalId) })) {
             return;
           }
 
-          if (this.checkDryRun('Would close issue', { id: internalId, reason: options.reason })) {
-            return;
-          }
+          for (const { input, internalId } of resolved) {
+            let issue;
+            try {
+              issue = await readIssue(dataSyncDir, internalId);
+            } catch {
+              // Single ID preserves the legacy hard error; bulk reports it.
+              if (ids.length === 1 && !options.ignoreMissing) {
+                throw new NotFoundError('Issue', input);
+              }
+              results.push({ id: input, action: 'missing', ok: false, skippedReason: 'not found' });
+              continue;
+            }
 
-          // Update issue
-          issue.status = 'closed';
-          issue.closed_at = now();
-          issue.close_reason = options.reason ?? null;
-          issue.version += 1;
-          issue.updated_at = now();
+            const displayId = this.ctx.debug
+              ? formatDebugId(issue.id, mapping, config.display.id_prefix)
+              : formatDisplayId(issue.id, mapping, config.display.id_prefix);
 
-          await writeIssue(dataSyncDir, issue);
-          didClose = true;
+            // Idempotent: already-closed is a reported skip, not a failure.
+            if (issue.status === 'closed') {
+              results.push({
+                id: displayId,
+                action: 'skipped',
+                ok: true,
+                skippedReason: 'already closed',
+              });
+              continue;
+            }
+
+            issue.status = 'closed';
+            issue.closed_at = now();
+            issue.close_reason = reason ?? null;
+            issue.version += 1;
+            issue.updated_at = now();
+            await writeIssue(dataSyncDir, issue);
+            results.push({ id: displayId, action: 'closed', ok: true });
+          }
+
+          // Report (but do not fail on) IDs skipped via --ignore-missing.
+          for (const m of missing) {
+            results.push({ id: m, action: 'missing', ok: false, skippedReason: 'not found' });
+          }
         },
       );
     }, 'Failed to close issue');
 
-    if (!didClose) return;
+    if (results.length === 0) return; // dry-run or nothing to do
+
+    // Single ID: preserve the exact legacy output (text + JSON).
+    if (ids.length === 1) {
+      const r = results[0]!;
+      if (r.action === 'missing') return; // --ignore-missing on a lone unknown ID
+      const alreadyClosed = r.action === 'skipped';
+      this.output.data({ id: r.id, closed: true, alreadyClosed }, () => {
+        this.output.success(`Closed ${r.id}`);
+      });
+      return;
+    }
 
-    this.output.data({ id: displayId, closed: true, alreadyClosed }, () => {
-      this.output.success(`Closed ${displayId}`);
-    });
+    emitBulkSummary(this.output, results, { verb: 'Closed', skippedNote: 'already closed' });
   }
 }
 
 export const closeCommand = new Command('close')
-  .description('Close an issue')
-  .argument('<id>', 'Issue ID')
-  .option('--reason <text>', 'Close reason')
-  .action(async (id, options, command) => {
+  .description('Close one or more issues')
+  .argument('<ids...>', 'Issue ID(s)')
+  .option('--reason <text>', 'Close reason ("-" reads stdin)')
+  .option('--reason-file <path>', 'Read close reason from a file ("-" reads stdin)')
+  .option('--ignore-missing', 'Skip unknown IDs instead of failing')
+  .action(async (ids, options, command) => {
     const handler = new CloseHandler(command);
-    await handler.run(id, options);
+    await handler.run(ids, options);
   });
diff --git a/packages/tbd/src/cli/commands/create.ts b/packages/tbd/src/cli/commands/create.ts
index da391c25..a073d374 100644
--- a/packages/tbd/src/cli/commands/create.ts
+++ b/packages/tbd/src/cli/commands/create.ts
@@ -5,10 +5,9 @@
  */
 
 import { Command } from 'commander';
-import { readFile } from 'node:fs/promises';
 
 import { BaseCommand } from '../lib/base-command.js';
-import { requireInit, ValidationError, CLIError } from '../lib/errors.js';
+import { requireInit, ValidationError } from '../lib/errors.js';
 import type { Issue, IssueKindType, PriorityType } from '../../lib/types.js';
 import { generateInternalId, extractUlidFromInternalId } from '../../lib/ids.js';
 import { readIssue, writeIssue } from '../../file/storage.js';
@@ -24,6 +23,7 @@ import { now } from '../../utils/time-utils.js';
 import { resolveAndValidatePath, getPathErrorMessage } from '../../lib/project-paths.js';
 import { validateIssueTitle } from '../lib/issue-input-validation.js';
 import { withDataSyncContext, notifyWorktreeRepaired } from '../lib/data-context.js';
+import { resolveBodyInput } from '../lib/body-input.js';
 
 interface CreateOptions {
   fromFile?: string;
@@ -59,16 +59,13 @@ class CreateHandler extends BaseCommand {
     const kind = this.parseKind(options.type ?? 'task');
     const priority = this.validatePriority(options.priority ?? '2');
 
-    // Read description from file if specified
-    let description = options.description;
-    if (options.file) {
-      try {
-        description = await readFile(options.file, 'utf-8');
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new CLIError(`Failed to read description from file '${options.file}': ${message}`);
-      }
-    }
+    // Resolve description from inline text, a file, or stdin ('-').
+    const description = await resolveBodyInput({
+      name: '--description',
+      value: options.description,
+      fileName: '--file',
+      file: options.file,
+    });
 
     // Validate and normalize spec path if provided
     let specPath: string | undefined;
@@ -207,8 +204,8 @@ export const createCommand = new Command('create')
   .option('--from-file <path>', 'Create from YAML+Markdown file')
   .option('-t, --type <type>', 'Issue type: bug, feature, task, epic, chore', 'task')
   .option('-p, --priority <0-4>', 'Priority (0=critical, 4=lowest)', '2')
-  .option('-d, --description <text>', 'Description')
-  .option('-f, --file <path>', 'Read description from file')
+  .option('-d, --description <text>', 'Description ("-" reads stdin)')
+  .option('-f, --file <path>', 'Read description from file ("-" reads stdin)')
   .option('--assignee <name>', 'Assignee')
   .option('--due <date>', 'Due date (ISO8601)')
   .option('--defer <date>', 'Defer until date (ISO8601)')
diff --git a/packages/tbd/src/cli/commands/reopen.ts b/packages/tbd/src/cli/commands/reopen.ts
index 3af3cca4..10a0891b 100644
--- a/packages/tbd/src/cli/commands/reopen.ts
+++ b/packages/tbd/src/cli/commands/reopen.ts
@@ -1,7 +1,14 @@
 /**
- * `tbd reopen` - Reopen a closed issue.
+ * `tbd reopen` - Reopen one or more closed issues.
  *
- * See: tbd-design.md §4.4 Reopen
+ * A single ID preserves the legacy output exactly, including the hard error when
+ * the issue is not closed. Two or more IDs are a bulk operation: processed under
+ * one lock, with a one-line summary, a structured `--json` results array, and a
+ * visible unsynced-changes hint. Already-open issues are a reported skip in the
+ * bulk path only (single-ID keeps erroring for backward compatibility).
+ *
+ * See: tbd-design.md §4.4 Reopen and
+ * docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md
  */
 
 import { Command } from 'commander';
@@ -11,86 +18,127 @@ import { requireInit, NotFoundError, CLIError } from '../lib/errors.js';
 import { readIssue, writeIssue } from '../../file/storage.js';
 import { formatDisplayId, formatDebugId } from '../../lib/ids.js';
 import { now } from '../../utils/time-utils.js';
-import { resolveToInternalId } from '../../file/id-mapping.js';
 import { withDataSyncContext } from '../lib/data-context.js';
+import { resolveAllIds, emitBulkSummary, type BulkItemResult } from '../lib/bulk.js';
+import { resolveBodyInput } from '../lib/body-input.js';
 
 interface ReopenOptions {
   reason?: string;
+  reasonFile?: string;
+  ignoreMissing?: boolean;
 }
 
 class ReopenHandler extends BaseCommand {
-  async run(id: string, options: ReopenOptions): Promise<void> {
+  async run(ids: string[], options: ReopenOptions): Promise<void> {
     const tbdRoot = await requireInit();
-
-    let displayId = id;
-    let didReopen = false;
+    const isBulk = ids.length > 1;
+    const results: BulkItemResult[] = [];
 
     await this.execute(async () => {
+      const reason = await resolveBodyInput({
+        name: '--reason',
+        value: options.reason,
+        fileName: '--reason-file',
+        file: options.reasonFile,
+      });
       await withDataSyncContext(
         tbdRoot,
         { lock: true },
         async ({ dataSyncDir, mapping, config }) => {
-          // Resolve input ID to internal ID
-          let internalId: string;
-          try {
-            internalId = resolveToInternalId(id, mapping);
-          } catch {
-            throw new NotFoundError('Issue', id);
-          }
-
-          // Load existing issue
-          let issue;
-          try {
-            issue = await readIssue(dataSyncDir, internalId);
-          } catch {
-            throw new NotFoundError('Issue', id);
-          }
+          const { resolved, missing } = resolveAllIds(ids, mapping);
 
-          // Check if not closed
-          if (issue.status !== 'closed') {
-            throw new CLIError(`Issue ${id} is not closed (status: ${issue.status})`);
+          // Fail closed: any unknown ID aborts before writing anything, unless
+          // the caller opted into best-effort with --ignore-missing.
+          if (missing.length > 0 && !options.ignoreMissing) {
+            throw new NotFoundError('Issue', missing.join(', '));
           }
 
-          if (this.checkDryRun('Would reopen issue', { id: internalId, reason: options.reason })) {
+          const dryRunMessage =
+            ids.length === 1 ? 'Would reopen issue' : `Would reopen ${resolved.length} issues`;
+          if (this.checkDryRun(dryRunMessage, { ids: resolved.map((r) => r.internalId) })) {
             return;
           }
 
-          // Update issue
-          issue.status = 'open';
-          issue.closed_at = null;
-          issue.close_reason = null;
-          issue.version += 1;
-          issue.updated_at = now();
-
-          // Optionally store reopen reason in notes if provided
-          if (options.reason) {
-            const reopenNote = `Reopened: ${options.reason}`;
-            issue.notes = issue.notes ? `${issue.notes}\n\n${reopenNote}` : reopenNote;
+          for (const { input, internalId } of resolved) {
+            let issue;
+            try {
+              issue = await readIssue(dataSyncDir, internalId);
+            } catch {
+              // Single ID preserves the legacy hard error; bulk reports it.
+              if (!isBulk && !options.ignoreMissing) {
+                throw new NotFoundError('Issue', input);
+              }
+              results.push({ id: input, action: 'missing', ok: false, skippedReason: 'not found' });
+              continue;
+            }
+
+            const displayId = this.ctx.debug
+              ? formatDebugId(issue.id, mapping, config.display.id_prefix)
+              : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+
+            // Only closed issues can be reopened. Single ID keeps the legacy
+            // hard error; bulk reports a skip so a batch reopen is idempotent.
+            if (issue.status !== 'closed') {
+              if (!isBulk) {
+                throw new CLIError(`Issue ${input} is not closed (status: ${issue.status})`);
+              }
+              results.push({
+                id: displayId,
+                action: 'skipped',
+                ok: true,
+                skippedReason:
+                  issue.status === 'open' ? 'already open' : `not closed (${issue.status})`,
+              });
+              continue;
+            }
+
+            issue.status = 'open';
+            issue.closed_at = null;
+            issue.close_reason = null;
+            issue.version += 1;
+            issue.updated_at = now();
+
+            // Optionally record the reopen reason in notes.
+            if (reason) {
+              const reopenNote = `Reopened: ${reason}`;
+              issue.notes = issue.notes ? `${issue.notes}\n\n${reopenNote}` : reopenNote;
+            }
+
+            await writeIssue(dataSyncDir, issue);
+            results.push({ id: displayId, action: 'reopened', ok: true });
           }
 
-          await writeIssue(dataSyncDir, issue);
-
-          displayId = this.ctx.debug
-            ? formatDebugId(issue.id, mapping, config.display.id_prefix)
-            : formatDisplayId(issue.id, mapping, config.display.id_prefix);
-          didReopen = true;
+          // Report (but do not fail on) IDs skipped via --ignore-missing.
+          for (const m of missing) {
+            results.push({ id: m, action: 'missing', ok: false, skippedReason: 'not found' });
+          }
         },
       );
     }, 'Failed to reopen issue');
 
-    if (!didReopen) return;
+    if (results.length === 0) return; // dry-run or nothing to do
+
+    // Single ID: preserve the exact legacy output (text + JSON).
+    if (ids.length === 1) {
+      const r = results[0]!;
+      if (r.action === 'missing') return; // --ignore-missing on a lone unknown ID
+      this.output.data({ id: r.id, reopened: true }, () => {
+        this.output.success(`Reopened ${r.id}`);
+      });
+      return;
+    }
 
-    this.output.data({ id: displayId, reopened: true }, () => {
-      this.output.success(`Reopened ${displayId}`);
-    });
+    emitBulkSummary(this.output, results, { verb: 'Reopened', skippedNote: 'already open' });
   }
 }
 
 export const reopenCommand = new Command('reopen')
-  .description('Reopen a closed issue')
-  .argument('<id>', 'Issue ID')
-  .option('--reason <text>', 'Reopen reason')
-  .action(async (id, options, command) => {
+  .description('Reopen one or more closed issues')
+  .argument('<ids...>', 'Issue ID(s)')
+  .option('--reason <text>', 'Reopen reason ("-" reads stdin)')
+  .option('--reason-file <path>', 'Read reopen reason from a file ("-" reads stdin)')
+  .option('--ignore-missing', 'Skip unknown IDs instead of failing')
+  .action(async (ids, options, command) => {
     const handler = new ReopenHandler(command);
-    await handler.run(id, options);
+    await handler.run(ids, options);
   });
diff --git a/packages/tbd/src/cli/commands/update.ts b/packages/tbd/src/cli/commands/update.ts
index fcce6674..ce19980c 100644
--- a/packages/tbd/src/cli/commands/update.ts
+++ b/packages/tbd/src/cli/commands/update.ts
@@ -20,6 +20,8 @@ import { resolveToInternalId, type IdMapping } from '../../file/id-mapping.js';
 import { resolveAndValidatePath, getPathErrorMessage } from '../../lib/project-paths.js';
 import { validateIssueTitle } from '../lib/issue-input-validation.js';
 import { withDataSyncContext } from '../lib/data-context.js';
+import { resolveAllIds, emitBulkSummary, type BulkItemResult } from '../lib/bulk.js';
+import { resolveBodyInput, type BodyInputState } from '../lib/body-input.js';
 
 interface UpdateOptions {
   fromFile?: string;
@@ -38,16 +40,33 @@ interface UpdateOptions {
   parent?: string;
   spec?: string;
   childOrder?: string;
+  ignoreMissing?: boolean;
 }
 
 class UpdateHandler extends BaseCommand {
-  async run(id: string, options: UpdateOptions): Promise<void> {
+  async run(ids: string[], options: UpdateOptions): Promise<void> {
+    if (ids.length === 1) {
+      await this.runSingle(ids[0]!, options);
+      return;
+    }
+    await this.runBulk(ids, options);
+  }
+
+  /**
+   * Single-ID update preserves the full legacy behavior, including structural
+   * side effects (re-parenting, spec propagation, child ordering hints).
+   */
+  async runSingle(id: string, options: UpdateOptions): Promise<void> {
     const tbdRoot = await requireInit();
 
     let displayId = id;
     let didUpdate = false;
 
     await this.execute(async () => {
+      // Resolve free-text bodies (description/notes) before the data context:
+      // the context changes cwd, so relative file paths and stdin must be read
+      // up front from the caller's working directory.
+      const resolvedOptions = await this.resolveBodyOptions(options);
       await withDataSyncContext(
         tbdRoot,
         { lock: true },
@@ -69,7 +88,7 @@ class UpdateHandler extends BaseCommand {
           }
 
           // Parse and validate options
-          const updates = await this.parseUpdates(options, mapping, tbdRoot);
+          const updates = await this.parseUpdates(resolvedOptions, mapping, tbdRoot);
           if (updates === null) return;
 
           if (this.checkDryRun('Would update issue', { id: internalId, ...updates })) {
@@ -182,6 +201,137 @@ class UpdateHandler extends BaseCommand {
     });
   }
 
+  /**
+   * Bulk update (2+ IDs): apply only shared fields that have no lifecycle or
+   * structural side effects. Per-ID-only flags are rejected up front, and
+   * lifecycle changes stay on `close`/`reopen` so `closed_at`/`close_reason`
+   * are never left inconsistent.
+   */
+  async runBulk(ids: string[], options: UpdateOptions): Promise<void> {
+    const perIdOnly: string[] = [];
+    if (options.fromFile) perIdOnly.push('--from-file');
+    if (options.title !== undefined) perIdOnly.push('--title');
+    if (options.description !== undefined) perIdOnly.push('--description');
+    if (options.notes !== undefined) perIdOnly.push('--notes');
+    if (options.notesFile) perIdOnly.push('--notes-file');
+    if (options.status !== undefined) perIdOnly.push('--status');
+    if (options.parent !== undefined) perIdOnly.push('--parent');
+    if (options.spec !== undefined) perIdOnly.push('--spec');
+    if (options.childOrder !== undefined) perIdOnly.push('--child-order');
+    if (perIdOnly.length > 0) {
+      throw new CLIError(
+        `Cannot use ${perIdOnly.join(', ')} when updating multiple issues. ` +
+          `These apply to a single issue; use \`tbd close\`/\`tbd reopen\` for status changes. ` +
+          `Bulk update supports shared fields: --priority, --assignee, --type, ` +
+          `--add-label, --remove-label, --due, --defer.`,
+      );
+    }
+
+    const tbdRoot = await requireInit();
+    const results: BulkItemResult[] = [];
+
+    await this.execute(async () => {
+      await withDataSyncContext(
+        tbdRoot,
+        { lock: true },
+        async ({ dataSyncDir, mapping, config }) => {
+          const updates = await this.parseUpdates(options, mapping, tbdRoot);
+          if (updates === null || Object.keys(updates).length === 0) {
+            throw new ValidationError(
+              'No fields to update. Specify at least one shared field, e.g. --priority or --add-label.',
+            );
+          }
+
+          const { resolved, missing } = resolveAllIds(ids, mapping);
+          if (missing.length > 0 && !options.ignoreMissing) {
+            throw new NotFoundError('Issue', missing.join(', '));
+          }
+
+          if (
+            this.checkDryRun(`Would update ${resolved.length} issues`, {
+              ids: resolved.map((r) => r.internalId),
+              ...updates,
+            })
+          ) {
+            return;
+          }
+
+          for (const { input, internalId } of resolved) {
+            let issue;
+            try {
+              issue = await readIssue(dataSyncDir, internalId);
+            } catch {
+              results.push({ id: input, action: 'missing', ok: false, skippedReason: 'not found' });
+              continue;
+            }
+
+            if (updates.kind !== undefined) issue.kind = updates.kind;
+            if (updates.priority !== undefined) issue.priority = updates.priority;
+            if (updates.assignee !== undefined) issue.assignee = updates.assignee;
+            if (updates.due_date !== undefined) issue.due_date = updates.due_date;
+            if (updates.deferred_until !== undefined) issue.deferred_until = updates.deferred_until;
+            if (updates.addLabels && updates.addLabels.length > 0) {
+              const labelsSet = new Set(issue.labels);
+              for (const label of updates.addLabels) labelsSet.add(label);
+              issue.labels = [...labelsSet];
+            }
+            if (updates.removeLabels && updates.removeLabels.length > 0) {
+              const removeSet = new Set(updates.removeLabels);
+              issue.labels = issue.labels.filter((l) => !removeSet.has(l));
+            }
+
+            issue.version += 1;
+            issue.updated_at = now();
+            await writeIssue(dataSyncDir, issue);
+
+            const displayId = this.ctx.debug
+              ? formatDebugId(issue.id, mapping, config.display.id_prefix)
+              : formatDisplayId(issue.id, mapping, config.display.id_prefix);
+            results.push({ id: displayId, action: 'updated', ok: true });
+          }
+
+          for (const m of missing) {
+            results.push({ id: m, action: 'missing', ok: false, skippedReason: 'not found' });
+          }
+        },
+      );
+    }, 'Failed to update issues');
+
+    if (results.length === 0) return; // dry-run or nothing to do
+    emitBulkSummary(this.output, results, { verb: 'Updated', skippedNote: 'unchanged' });
+  }
+
+  /**
+   * Resolve free-text body flags (--description, --notes, --notes-file) to plain
+   * strings before entering the data context, so relative file paths resolve
+   * against the caller's cwd and stdin ('-') is consumed exactly once.
+   * `--from-file` carries its own body and is left untouched.
+   */
+  private async resolveBodyOptions(options: UpdateOptions): Promise<UpdateOptions> {
+    if (options.fromFile) return options;
+    const bodyState: BodyInputState = {};
+    const resolved: UpdateOptions = { ...options };
+    if (options.description !== undefined) {
+      resolved.description = await resolveBodyInput(
+        { name: '--description', value: options.description },
+        bodyState,
+      );
+    }
+    if (options.notes !== undefined || options.notesFile) {
+      resolved.notes = await resolveBodyInput(
+        {
+          name: '--notes',
+          value: options.notes,
+          fileName: '--notes-file',
+          file: options.notesFile,
+        },
+        bodyState,
+      );
+      resolved.notesFile = undefined;
+    }
+    return resolved;
+  }
+
   private async parseUpdates(
     options: UpdateOptions,
     mapping: IdMapping,
@@ -341,6 +491,8 @@ class UpdateHandler extends BaseCommand {
       updates.assignee = options.assignee || null;
     }
 
+    // Body fields are pre-resolved (inline/file/stdin) by resolveBodyOptions
+    // before the data context, so here they are already plain strings.
     if (options.description !== undefined) {
       updates.description = options.description || null;
     }
@@ -349,14 +501,6 @@ class UpdateHandler extends BaseCommand {
       updates.notes = options.notes || null;
     }
 
-    if (options.notesFile) {
-      try {
-        updates.notes = await readFile(options.notesFile, 'utf-8');
-      } catch {
-        throw new CLIError(`Failed to read notes from file: ${options.notesFile}`);
-      }
-    }
-
     if (options.due !== undefined) {
       updates.due_date = options.due || null;
     }
@@ -427,8 +571,8 @@ class UpdateHandler extends BaseCommand {
 }
 
 export const updateCommand = new Command('update')
-  .description('Update an issue')
-  .argument('<id>', 'Issue ID')
+  .description('Update one or more issues')
+  .argument('<ids...>', 'Issue ID(s)')
   .option('--from-file <path>', 'Update all fields from YAML+Markdown file')
   .option('--title <text>', 'Set title')
   .option('--status <status>', 'Set status')
@@ -445,7 +589,8 @@ export const updateCommand = new Command('update')
   .option('--parent <id>', 'Set parent')
   .option('--spec <path>', 'Set or clear spec path (empty string clears)')
   .option('--child-order <ids>', 'Set child ordering hints (comma-separated IDs)')
-  .action(async (id, options, command) => {
+  .option('--ignore-missing', 'Skip unknown IDs instead of failing (bulk)')
+  .action(async (ids, options, command) => {
     const handler = new UpdateHandler(command);
-    await handler.run(id, options);
+    await handler.run(ids, options);
   });
diff --git a/packages/tbd/src/cli/lib/body-input.ts b/packages/tbd/src/cli/lib/body-input.ts
new file mode 100644
index 00000000..91d43fea
--- /dev/null
+++ b/packages/tbd/src/cli/lib/body-input.ts
@@ -0,0 +1,80 @@
+/**
+ * Shared resolver for free-text body inputs (reasons, descriptions, notes).
+ *
+ * Agents frequently need to pass shell-sensitive text (containing `$`,
+ * backticks, or quotes). Rather than fight shell escaping, every body flag
+ * accepts the text inline, from a file via a companion `*-file` flag, or from
+ * stdin using the `-` convention on either flag. Phase 1 agent CLI ergonomics;
+ * see docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+import { CLIError } from './errors.js';
+
+/** Tracks single-use of stdin across multiple body inputs in one command. */
+export interface BodyInputState {
+  stdinUsedBy?: string;
+}
+
+export interface BodyInputSpec {
+  /** Inline flag name for messages, e.g. `--reason`. */
+  name: string;
+  /** Value from the inline flag; the `-` sentinel means stdin. */
+  value?: string;
+  /** Companion `*-file` flag name for messages, e.g. `--reason-file`. */
+  fileName?: string;
+  /** Path from the `*-file` flag; the `-` sentinel means stdin. */
+  file?: string;
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+/**
+ * Resolve one body input to its final string, or `undefined` when unset.
+ *
+ * - inline text is returned as-is
+ * - a `*-file <path>` flag reads the file
+ * - `-` on either flag reads stdin (at most one stdin reader per command)
+ * - supplying both inline text and a file is an error
+ */
+export async function resolveBodyInput(
+  spec: BodyInputSpec,
+  state: BodyInputState = {},
+): Promise<string | undefined> {
+  const hasValue = spec.value !== undefined;
+  const hasFile = spec.file !== undefined;
+
+  if (hasValue && hasFile) {
+    throw new CLIError(
+      `Use either ${spec.name} or ${spec.fileName ?? `${spec.name}-file`}, not both.`,
+    );
+  }
+
+  if (spec.value === '-' || spec.file === '-') {
+    if (state.stdinUsedBy && state.stdinUsedBy !== spec.name) {
+      throw new CLIError(
+        `Cannot read both ${state.stdinUsedBy} and ${spec.name} from stdin ('-').`,
+      );
+    }
+    state.stdinUsedBy = spec.name;
+    return readStdin();
+  }
+
+  if (hasFile) {
+    try {
+      return await readFile(spec.file!, 'utf-8');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CLIError(`Failed to read ${spec.fileName ?? spec.name}: ${spec.file}: ${message}`);
+    }
+  }
+
+  return spec.value;
+}
diff --git a/packages/tbd/src/cli/lib/bulk.ts b/packages/tbd/src/cli/lib/bulk.ts
new file mode 100644
index 00000000..aa7c4d4f
--- /dev/null
+++ b/packages/tbd/src/cli/lib/bulk.ts
@@ -0,0 +1,125 @@
+/**
+ * Shared helpers for bulk (multi-target) mutators: `close`, `reopen`, `update`.
+ *
+ * Phase 1 of the agent CLI ergonomics work. A single ID keeps each command's
+ * legacy behavior byte-for-byte; two or more IDs are processed under one lock
+ * with a one-line summary and a structured `--json` results array. See
+ * docs/project/specs/active/plan-2026-06-13-agent-cli-ergonomics.md.
+ */
+
+import type { IdMapping } from '../../file/id-mapping.js';
+import { resolveToInternalId } from '../../file/id-mapping.js';
+import type { OutputManager } from './output.js';
+
+export interface ResolvedId {
+  /** The ID exactly as the user typed it. */
+  input: string;
+  /** The resolved internal ULID-based ID. */
+  internalId: string;
+}
+
+export interface IdResolution {
+  resolved: ResolvedId[];
+  /** Inputs that did not resolve, in input order. */
+  missing: string[];
+}
+
+/**
+ * Resolve every input ID up front (validate-all-then-apply). Unknown inputs are
+ * collected in `missing` so the caller can fail closed before any write.
+ */
+export function resolveAllIds(inputIds: string[], mapping: IdMapping): IdResolution {
+  const resolved: ResolvedId[] = [];
+  const missing: string[] = [];
+  for (const input of inputIds) {
+    try {
+      resolved.push({ input, internalId: resolveToInternalId(input, mapping) });
+    } catch {
+      missing.push(input);
+    }
+  }
+  return { resolved, missing };
+}
+
+export type BulkAction = 'closed' | 'reopened' | 'updated' | 'skipped' | 'missing';
+
+export interface BulkItemResult {
+  /** Display ID, or the raw input when the issue could not be resolved/read. */
+  id: string;
+  action: BulkAction;
+  ok: boolean;
+  /** Human reason when `action` is `skipped` or `missing`. */
+  skippedReason?: string;
+}
+
+export interface BulkSummary {
+  /** Items actually mutated (action equals the verb, e.g. `closed`). */
+  changed: number;
+  /** Items left unchanged on purpose (e.g. already closed). */
+  skipped: number;
+  /** Inputs that could not be resolved (only present with `--ignore-missing`). */
+  missing: number;
+  total: number;
+}
+
+/** Tally a results array into a summary. */
+export function summarizeBulk(results: BulkItemResult[]): BulkSummary {
+  let changed = 0;
+  let skipped = 0;
+  let missing = 0;
+  for (const r of results) {
+    if (r.action === 'skipped') skipped++;
+    else if (r.action === 'missing') missing++;
+    else changed++;
+  }
+  return { changed, skipped, missing, total: results.length };
+}
+
+/** The machine-readable result item shape emitted under `--json`. */
+export function toJsonResult(r: BulkItemResult): {
+  id: string;
+  action: BulkAction;
+  ok: boolean;
+  skippedReason?: string;
+} {
+  return r.skippedReason
+    ? { id: r.id, action: r.action, ok: r.ok, skippedReason: r.skippedReason }
+    : { id: r.id, action: r.action, ok: r.ok };
+}
+
+/**
+ * Emit the shared bulk result: one deterministic summary line in text mode, the
+ * structured `results`/`summary`/`sync` object under `--json`, and a visible
+ * unsynced-changes hint via `output.notice()`. Shared by `close`, `reopen`, and
+ * `update` so the multi-target output contract stays identical across verbs.
+ *
+ * `verb` is the past-tense word for changed items (e.g. `Closed`); `skippedNote`
+ * is the parenthetical reason for skipped items (e.g. `already closed`). A verb
+ * that never skips (e.g. `update`) simply never renders the skipped clause.
+ */
+export function emitBulkSummary(
+  output: OutputManager,
+  results: BulkItemResult[],
+  opts: { verb: string; skippedNote: string },
+): void {
+  const summary = summarizeBulk(results);
+  const syncPending = summary.changed > 0;
+  const json: Record<string, unknown> = {
+    results: results.map(toJsonResult),
+    summary,
+  };
+  if (syncPending) {
+    json.sync = { pending: true, hint: 'Run `tbd sync` to publish.' };
+  }
+
+  output.data(json, () => {
+    const parts = [`${opts.verb} ${summary.changed}`];
+    if (summary.skipped > 0) parts.push(`skipped ${summary.skipped} (${opts.skippedNote})`);
+    if (summary.missing > 0) parts.push(`not found ${summary.missing}`);
+    const idList = results.map((r) => r.id).join(' ');
+    output.success(`${parts.join(', ')}: ${idList}`);
+    if (syncPending) {
+      output.notice('Unsynced changes — run `tbd sync` to publish.');
+    }
+  });
+}
diff --git a/packages/tbd/src/cli/lib/context.ts b/packages/tbd/src/cli/lib/context.ts
index 4bc00128..c8c2b9b0 100644
--- a/packages/tbd/src/cli/lib/context.ts
+++ b/packages/tbd/src/cli/lib/context.ts
@@ -25,11 +25,32 @@ export interface CommandContext {
   quiet: boolean;
   json: boolean;
   color: ColorOption;
-  sync: boolean;
   /** Debug mode: shows internal IDs alongside public IDs */
   debug: boolean;
 }
 
+/**
+ * Process-wide mirror of the active command's `--quiet`.
+ *
+ * The low-level data layer (worktree auto-heal and config-migration stderr
+ * notices in data-context.ts) has no access to the per-command CommandContext,
+ * and threading a flag through `withDataSyncContext` and its ~18 call sites would
+ * be far noisier than the fix deserves. `--quiet` is a process-global concern set
+ * once per invocation, so getCommandContext records it here for those emitters to
+ * honor. See tbd-29k3 / plan-2026-06-13-agent-cli-ergonomics.md.
+ */
+let quietNotices = false;
+
+/** True when the active command was invoked with `--quiet`. */
+export function quietNoticesActive(): boolean {
+  return quietNotices;
+}
+
+/** Record the active command's `--quiet` for the low-level data layer. */
+export function setQuietNotices(quiet: boolean): void {
+  quietNotices = quiet;
+}
+
 /**
  * Extract command context from a Commander command.
  * Handles inheritance of global options through the command hierarchy.
@@ -37,15 +58,16 @@ export interface CommandContext {
 export function getCommandContext(command: Command): CommandContext {
   const opts = command.optsWithGlobals();
 
-  return {
+  const context: CommandContext = {
     dryRun: opts.dryRun ?? false,
     verbose: opts.verbose ?? false,
     quiet: opts.quiet ?? false,
     json: opts.json ?? false,
     color: (opts.color as ColorOption) ?? 'auto',
-    sync: opts.sync !== false, // --no-sync sets this to false
     debug: opts.debug ?? false,
   };
+  setQuietNotices(context.quiet);
+  return context;
 }
 
 /**
diff --git a/packages/tbd/src/cli/lib/data-context.ts b/packages/tbd/src/cli/lib/data-context.ts
index 5bc0002e..5523efb7 100644
--- a/packages/tbd/src/cli/lib/data-context.ts
+++ b/packages/tbd/src/cli/lib/data-context.ts
@@ -22,7 +22,7 @@ import type { Config, CommonDirLayout } from '../../lib/types.js';
 import { resolveDataSyncDir, resolveSharedTbdPaths, type SharedTbdPaths } from '../../lib/paths.js';
 import { formatDisplayId, formatDebugId } from '../../lib/ids.js';
 import type { CommandContext } from './context.js';
-import { getCommandContext } from './context.js';
+import { getCommandContext, quietNoticesActive } from './context.js';
 import { requireInit, NotFoundError } from './errors.js';
 import { checkWorktreeHealth, repairWorktree } from '../../file/git.js';
 import type { WorktreeHealth, WorktreeStatus } from '../../file/git.js';
@@ -162,6 +162,7 @@ async function ensureSharedDataSyncLayout(
  * plan-2026-05-17-shared-common-dir-sync-worktree.md.
  */
 function notifyConfigMigrated(fromFormat: string | undefined, toFormat: string): void {
+  if (quietNoticesActive()) return; // --quiet suppresses incidental notices
   if (fromFormat === toFormat) return;
   const arrow = fromFormat ? `${fromFormat} → ${toFormat}` : `→ ${toFormat}`;
   process.stderr.write(
@@ -181,6 +182,7 @@ function notifyConfigMigrated(fromFormat: string | undefined, toFormat: string):
  * stderr note keeps stdout (and JSON) clean while making the heal visible.
  */
 export function notifyWorktreeRepaired(status: WorktreeStatus | undefined): void {
+  if (quietNoticesActive()) return; // --quiet suppresses incidental notices
   if (status !== 'missing' && status !== 'prunable') return;
   process.stderr.write(
     `• tbd-sync worktree was ${status}; auto-materialized it ` +
diff --git a/packages/tbd/src/utils/lockfile.ts b/packages/tbd/src/utils/lockfile.ts
index 6a5b4224..e01658ee 100644
--- a/packages/tbd/src/utils/lockfile.ts
+++ b/packages/tbd/src/utils/lockfile.ts
@@ -107,6 +107,16 @@ export class LockAcquisitionError extends Error {
 /** Filesystem error codes that are transient on Windows and worth retrying. */
 const TRANSIENT_RMDIR_CODES = new Set(['EBUSY', 'EPERM', 'EACCES', 'ENOTEMPTY']);
 
+/**
+ * Codes that `mkdir` can transiently raise on Windows when acquisition races a
+ * concurrent `rmdir` of the same lock directory (AV scanners, lingering handles)
+ * — the acquire-side analogue of TRANSIENT_RMDIR_CODES. Retried a small, bounded
+ * number of times; a *persistent* failure (e.g. a genuinely unwritable parent
+ * directory, which `tbd doctor` surfaces) still propagates once the budget is spent.
+ */
+const TRANSIENT_MKDIR_CODES = new Set(['EBUSY', 'EPERM', 'EACCES']);
+const MAX_TRANSIENT_ACQUIRE_RETRIES = 5;
+
 /**
  * Remove a lock directory, tolerating transient Windows failures.
  *
@@ -191,6 +201,7 @@ export async function withLockfile<T>(
 
   const deadline = Date.now() + timeoutMs;
   let acquired = false;
+  let transientAcquireRetries = 0;
 
   while (Date.now() < deadline) {
     try {
@@ -199,12 +210,34 @@ export async function withLockfile<T>(
       acquired = true;
       break;
     } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== 'EEXIST') {
+        // Windows can transiently surface EBUSY/EPERM/EACCES from mkdir when it
+        // races a concurrent rmdir of the same lock directory — the acquire-side
+        // mirror of the transient failures removeLockDir tolerates on release. A
+        // genuinely unwritable parent (the sandbox case `tbd doctor` detects)
+        // fails identically on every attempt, so retry a small, bounded number of
+        // times and only then surface the original error. Any other code (ENOENT,
+        // ENOSPC, …) is non-transient and thrown immediately.
+        if (
+          code &&
+          TRANSIENT_MKDIR_CODES.has(code) &&
+          transientAcquireRetries < MAX_TRANSIENT_ACQUIRE_RETRIES
+        ) {
+          transientAcquireRetries++;
+          await new Promise((resolve) => setTimeout(resolve, 20 * transientAcquireRetries));
+          continue;
+        }
         // Unexpected error (permissions, disk full, missing parent, etc.):
         // preserve the original failure instead of misreporting lock contention.
         throw error;
       }
 
+      // A real EEXIST means the lock is genuinely held — reset the transient
+      // acquisition budget so a long, legitimate wait punctuated by the occasional
+      // Windows race never spuriously surfaces as a permission failure.
+      transientAcquireRetries = 0;
+
       // Lock exists; inspect it.
       let lockStat;
       try {
diff --git a/packages/tbd/tests/body-input.test.ts b/packages/tbd/tests/body-input.test.ts
new file mode 100644
index 00000000..6ef884a0
--- /dev/null
+++ b/packages/tbd/tests/body-input.test.ts
@@ -0,0 +1,56 @@
+import { describe, it, expect } from 'vitest';
+import { writeFile, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { resolveBodyInput } from '../src/cli/lib/body-input.js';
+
+describe('resolveBodyInput', () => {
+  it('returns inline text unchanged', async () => {
+    expect(await resolveBodyInput({ name: '--reason', value: 'done' })).toBe('done');
+  });
+
+  it('returns undefined when nothing is set', async () => {
+    expect(await resolveBodyInput({ name: '--reason' })).toBeUndefined();
+  });
+
+  it('preserves shell-sensitive characters in inline text', async () => {
+    const raw = 'cost is $5 `whoami` "ok" \'q\'';
+    expect(await resolveBodyInput({ name: '--reason', value: raw })).toBe(raw);
+  });
+
+  it('reads the body from a file verbatim', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'body-input-'));
+    try {
+      const path = join(dir, 'reason.txt');
+      const body = 'multi\nline $VAR `tick` "quote"';
+      await writeFile(path, body, 'utf-8');
+      expect(
+        await resolveBodyInput({ name: '--reason', fileName: '--reason-file', file: path }),
+      ).toBe(body);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('errors when both inline text and a file are given', async () => {
+    await expect(
+      resolveBodyInput({ name: '--reason', value: 'x', fileName: '--reason-file', file: 'y' }),
+    ).rejects.toThrow(/either --reason or --reason-file/);
+  });
+
+  it('errors when the file cannot be read', async () => {
+    await expect(
+      resolveBodyInput({ name: '--reason', fileName: '--reason-file', file: '/no/such/file-xyz' }),
+    ).rejects.toThrow(/Failed to read --reason-file/);
+  });
+
+  it('errors when two fields both request stdin', async () => {
+    // Pre-seed state as if --description already claimed stdin; this throws
+    // before any read, so no real stdin is touched.
+    const state = { stdinUsedBy: '--description' };
+    await expect(resolveBodyInput({ name: '--notes', value: '-' }, state)).rejects.toThrow(
+      /Cannot read both --description and --notes from stdin/,
+    );
+  });
+});
diff --git a/packages/tbd/tests/bulk.test.ts b/packages/tbd/tests/bulk.test.ts
new file mode 100644
index 00000000..195c84d5
--- /dev/null
+++ b/packages/tbd/tests/bulk.test.ts
@@ -0,0 +1,169 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  emitBulkSummary,
+  resolveAllIds,
+  summarizeBulk,
+  toJsonResult,
+  type BulkItemResult,
+} from '../src/cli/lib/bulk.js';
+import type { CommandContext } from '../src/cli/lib/context.js';
+import { OutputManager } from '../src/cli/lib/output.js';
+import { addIdMapping, type IdMapping } from '../src/file/id-mapping.js';
+
+function makeCtx(over: Partial<CommandContext> = {}): CommandContext {
+  return {
+    dryRun: false,
+    verbose: false,
+    quiet: false,
+    json: false,
+    color: 'never',
+    debug: false,
+    ...over,
+  };
+}
+
+const ULID_A = 'a'.repeat(26);
+const ULID_B = 'b'.repeat(26);
+
+function makeMapping(shorts: Record<string, string>): IdMapping {
+  const mapping: IdMapping = { shortToUlid: new Map(), ulidToShort: new Map() };
+  for (const [short, ulid] of Object.entries(shorts)) {
+    addIdMapping(mapping, ulid, short);
+  }
+  return mapping;
+}
+
+describe('resolveAllIds', () => {
+  it('resolves known IDs and collects unknown ones, preserving order', () => {
+    const mapping = makeMapping({ aaaa: ULID_A, bbbb: ULID_B });
+    const { resolved, missing } = resolveAllIds(['aaaa', 'zzzz', 'bbbb'], mapping);
+    expect(resolved.map((r) => r.input)).toEqual(['aaaa', 'bbbb']);
+    expect(missing).toEqual(['zzzz']);
+  });
+
+  it('reports every input as missing when nothing resolves', () => {
+    const { resolved, missing } = resolveAllIds(['zzzz', 'yyyy'], makeMapping({}));
+    expect(resolved).toHaveLength(0);
+    expect(missing).toEqual(['zzzz', 'yyyy']);
+  });
+
+  it('handles an empty input list', () => {
+    const { resolved, missing } = resolveAllIds([], makeMapping({}));
+    expect(resolved).toHaveLength(0);
+    expect(missing).toHaveLength(0);
+  });
+});
+
+describe('summarizeBulk', () => {
+  it('tallies changed, skipped, and missing', () => {
+    const results: BulkItemResult[] = [
+      { id: 'a', action: 'closed', ok: true },
+      { id: 'b', action: 'closed', ok: true },
+      { id: 'c', action: 'skipped', ok: true, skippedReason: 'already closed' },
+      { id: 'd', action: 'missing', ok: false, skippedReason: 'not found' },
+    ];
+    expect(summarizeBulk(results)).toEqual({ changed: 2, skipped: 1, missing: 1, total: 4 });
+  });
+
+  it('counts reopened and updated as changed', () => {
+    const results: BulkItemResult[] = [
+      { id: 'a', action: 'reopened', ok: true },
+      { id: 'b', action: 'updated', ok: true },
+    ];
+    expect(summarizeBulk(results)).toEqual({ changed: 2, skipped: 0, missing: 0, total: 2 });
+  });
+
+  it('summarizes an empty result set', () => {
+    expect(summarizeBulk([])).toEqual({ changed: 0, skipped: 0, missing: 0, total: 0 });
+  });
+});
+
+describe('toJsonResult', () => {
+  it('omits skippedReason when absent', () => {
+    expect(toJsonResult({ id: 'a', action: 'closed', ok: true })).toEqual({
+      id: 'a',
+      action: 'closed',
+      ok: true,
+    });
+  });
+
+  it('includes skippedReason when present', () => {
+    expect(
+      toJsonResult({ id: 'a', action: 'skipped', ok: true, skippedReason: 'already closed' }),
+    ).toEqual({ id: 'a', action: 'skipped', ok: true, skippedReason: 'already closed' });
+  });
+});
+
+describe('emitBulkSummary', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('prints one summary line (changed, skipped, missing) plus the sync hint in text mode', () => {
+    const out = new OutputManager(makeCtx());
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    emitBulkSummary(
+      out,
+      [
+        { id: 'a', action: 'closed', ok: true },
+        { id: 'b', action: 'skipped', ok: true, skippedReason: 'already closed' },
+        { id: 'c', action: 'missing', ok: false, skippedReason: 'not found' },
+      ],
+      { verb: 'Closed', skippedNote: 'already closed' },
+    );
+    const lines = log.mock.calls.map((c) => String(c[0]));
+    expect(
+      lines.some((l) => l.includes('Closed 1, skipped 1 (already closed), not found 1: a b c')),
+    ).toBe(true);
+    expect(lines.some((l) => l.includes('Unsynced changes'))).toBe(true);
+  });
+
+  it('omits the skipped clause for verbs that never skip (update)', () => {
+    const out = new OutputManager(makeCtx());
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    emitBulkSummary(
+      out,
+      [
+        { id: 'a', action: 'updated', ok: true },
+        { id: 'b', action: 'updated', ok: true },
+      ],
+      { verb: 'Updated', skippedNote: 'unchanged' },
+    );
+    const lines = log.mock.calls.map((c) => String(c[0]));
+    expect(lines.some((l) => l.includes('Updated 2: a b'))).toBe(true);
+    expect(lines.some((l) => l.includes('skipped'))).toBe(false);
+  });
+
+  it('emits structured results, summary, and sync.pending under --json', () => {
+    const out = new OutputManager(makeCtx({ json: true }));
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    emitBulkSummary(
+      out,
+      [
+        { id: 'proj-a', action: 'closed', ok: true },
+        { id: 'proj-b', action: 'skipped', ok: true, skippedReason: 'already closed' },
+      ],
+      { verb: 'Closed', skippedNote: 'already closed' },
+    );
+    expect(log).toHaveBeenCalledTimes(1);
+    const payload = JSON.parse(String(log.mock.calls[0]![0]));
+    expect(payload.results).toEqual([
+      { id: 'proj-a', action: 'closed', ok: true },
+      { id: 'proj-b', action: 'skipped', ok: true, skippedReason: 'already closed' },
+    ]);
+    expect(payload.summary).toEqual({ changed: 1, skipped: 1, missing: 0, total: 2 });
+    expect(payload.sync).toEqual({ pending: true, hint: 'Run `tbd sync` to publish.' });
+  });
+
+  it('omits sync when nothing changed', () => {
+    const out = new OutputManager(makeCtx({ json: true }));
+    const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    emitBulkSummary(
+      out,
+      [{ id: 'a', action: 'skipped', ok: true, skippedReason: 'already closed' }],
+      { verb: 'Closed', skippedNote: 'already closed' },
+    );
+    const payload = JSON.parse(String(log.mock.calls[0]![0]));
+    expect(payload.summary.changed).toBe(0);
+    expect(payload.sync).toBeUndefined();
+  });
+});
diff --git a/packages/tbd/tests/cli-advanced.tryscript.md b/packages/tbd/tests/cli-advanced.tryscript.md
index a889875f..ff3b5d1e 100644
--- a/packages/tbd/tests/cli-advanced.tryscript.md
+++ b/packages/tbd/tests/cli-advanced.tryscript.md
@@ -478,7 +478,6 @@ Global Options:
   --json                   Output as JSON
   --color <when>           Colorize output: auto, always, never (default:
                            "auto")
-  --no-sync                Skip automatic sync after write operations
   --debug                  Show internal IDs alongside public IDs for debugging
 
 Commands:
@@ -520,7 +519,6 @@ Global Options:
   --json                       Output as JSON
   --color <when>               Colorize output: auto, always, never (default:
                                "auto")
-  --no-sync                    Skip automatic sync after write operations
   --debug                      Show internal IDs alongside public IDs for
                                debugging
 
@@ -563,7 +561,6 @@ Global Options:
   --quiet            Suppress non-essential output
   --json             Output as JSON
   --color <when>     Colorize output: auto, always, never (default: "auto")
-  --no-sync          Skip automatic sync after write operations
   --debug            Show internal IDs alongside public IDs for debugging
 
 Commands:
@@ -605,7 +602,6 @@ Global Options:
   --json                    Output as JSON
   --color <when>            Colorize output: auto, always, never (default:
                             "auto")
-  --no-sync                 Skip automatic sync after write operations
   --debug                   Show internal IDs alongside public IDs for debugging
 
 Commands:
diff --git a/packages/tbd/tests/cli-body-input.tryscript.md b/packages/tbd/tests/cli-body-input.tryscript.md
new file mode 100644
index 00000000..8b81d7e6
--- /dev/null
+++ b/packages/tbd/tests/cli-body-input.tryscript.md
@@ -0,0 +1,210 @@
+---
+sandbox: true
+env:
+  NO_COLOR: '1'
+  FORCE_COLOR: '0'
+path:
+  - ../dist
+timeout: 30000
+patterns:
+  SHORTID: '[0-9a-z]{4,5}'
+before: |
+  # Set up a test git repository
+  git init --initial-branch=main
+  git config user.email "test@example.com"
+  git config user.name "Test User"
+  git config commit.gpgsign false
+  echo "# Test repo" > README.md
+  git add README.md
+  git commit -m "Initial commit"
+  # Initialize tbd with test prefix
+  tbd init --prefix=test
+---
+# tbd CLI: File and stdin body input
+
+Phase 1 agent CLI ergonomics.
+Free-text bodies (`--description`, `--notes`, `--reason`) accept a value inline, from a
+file, or from stdin via the `-` convention — so agents can pass shell-sensitive text
+(`$`, backticks, quotes) without fighting shell escaping.
+
+`printf '%s'` with a single-quoted argument writes the literal text, which is what these
+tests round-trip through `show --json`.
+
+* * *
+
+## Description from a file and from stdin (create)
+
+# Test: create --file reads a shell-sensitive description verbatim
+
+```console
+$ printf '%s' 'price=$9 `whoami` "ok"' > desc.txt
+? 0
+```
+
+```console
+$ tbd create "Body A" -f desc.txt --json | jq -r '.id' | tee ba.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd show $(cat ba.txt) --json | jq -r '.description'
+price=$9 `whoami` "ok"
+? 0
+```
+
+# Test: create -d - reads the description from stdin
+
+```console
+$ printf '%s' 'pipe=$X `cmd` "y"' | tbd create "Body B" -d - --json | jq -r '.id' | tee bb.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd show $(cat bb.txt) --json | jq -r '.description'
+pipe=$X `cmd` "y"
+? 0
+```
+
+# Test: create -f - reads the description from stdin
+
+```console
+$ printf '%s' 'file-dash $Z `q`' | tbd create "Body C" -f - --json | jq -r '.id' | tee bc.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd show $(cat bc.txt) --json | jq -r '.description'
+file-dash $Z `q`
+? 0
+```
+
+# Test: inline text and a file together is rejected
+
+```console
+$ tbd create "Conflict" -d hi -f desc.txt 2>&1
+[..]
+? 1
+```
+
+* * *
+
+## Reason from a file and from stdin (close)
+
+# Test: close --reason-file reads a shell-sensitive reason verbatim
+
+```console
+$ tbd create "Body D" --json | jq -r '.id' | tee bd.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ printf '%s' 'fixed $BUG via `patch`' > reason.txt
+? 0
+```
+
+```console
+$ tbd close $(cat bd.txt) --reason-file reason.txt --quiet
+? 0
+```
+
+```console
+$ tbd show $(cat bd.txt) --json | jq -r '.close_reason'
+fixed $BUG via `patch`
+? 0
+```
+
+# Test: close --reason - reads the reason from stdin
+
+```console
+$ tbd create "Body E" --json | jq -r '.id' | tee be.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ printf '%s' 'stdin $REASON `now`' | tbd close $(cat be.txt) --reason - --quiet
+? 0
+```
+
+```console
+$ tbd show $(cat be.txt) --json | jq -r '.close_reason'
+stdin $REASON `now`
+? 0
+```
+
+# Test: --reason and --reason-file together is rejected
+
+```console
+$ tbd close $(cat bd.txt) --reason hi --reason-file reason.txt 2>&1
+[..]
+? 1
+```
+
+* * *
+
+## Notes and description from a file and stdin (update)
+
+`tbd show --json` only surfaces working `notes` after the first notes write (tbd-649r, a
+pre-existing read-back quirk), so the notes tests below establish a notes body first.
+`--description` round-trips on the first write.
+
+# Test: update --description - reads the description from stdin
+
+```console
+$ tbd create "Body F" --json | jq -r '.id' | tee bf.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ printf '%s' 'desc $D `r` "s"' | tbd update $(cat bf.txt) --description - --quiet
+? 0
+```
+
+```console
+$ tbd show $(cat bf.txt) --json | jq -r '.description'
+desc $D `r` "s"
+? 0
+```
+
+# Test: update --notes-file reads shell-sensitive notes verbatim
+
+Establish a notes body first (see tbd-649r):
+
+```console
+$ tbd update $(cat bf.txt) --notes "established" --quiet
+? 0
+```
+
+```console
+$ printf '%s' 'note $N `x` "y"' > notes.txt
+? 0
+```
+
+```console
+$ tbd update $(cat bf.txt) --notes-file notes.txt --quiet
+? 0
+```
+
+```console
+$ tbd show $(cat bf.txt) --json | jq -r '.notes'
+note $N `x` "y"
+? 0
+```
+
+# Test: update --notes - reads notes from stdin
+
+```console
+$ printf '%s' 'stdin note $Z `q`' | tbd update $(cat bf.txt) --notes - --quiet
+? 0
+```
+
+```console
+$ tbd show $(cat bf.txt) --json | jq -r '.notes'
+stdin note $Z `q`
+? 0
+```
diff --git a/packages/tbd/tests/cli-bulk-mutation.tryscript.md b/packages/tbd/tests/cli-bulk-mutation.tryscript.md
new file mode 100644
index 00000000..596a9085
--- /dev/null
+++ b/packages/tbd/tests/cli-bulk-mutation.tryscript.md
@@ -0,0 +1,368 @@
+---
+sandbox: true
+env:
+  NO_COLOR: '1'
+  FORCE_COLOR: '0'
+path:
+  - ../dist
+timeout: 30000
+patterns:
+  SHORTID: '[0-9a-z]{4,5}'
+before: |
+  # Set up a test git repository
+  git init --initial-branch=main
+  git config user.email "test@example.com"
+  git config user.name "Test User"
+  git config commit.gpgsign false
+  echo "# Test repo" > README.md
+  git add README.md
+  git commit -m "Initial commit"
+  # Initialize tbd with test prefix
+  tbd init --prefix=test
+---
+# tbd CLI: Bulk Mutation
+
+Tests for variadic `tbd close` and `tbd reopen` (Phase 1 agent CLI ergonomics).
+Single-ID behavior is covered by cli-crud; this file covers the multi-target (bulk)
+paths.
+
+* * *
+
+## Bulk close
+
+# Test: Seed three open issues
+
+```console
+$ tbd create "Bulk A" --json | jq -r '.id' | tee a.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Bulk B" --json | jq -r '.id' | tee b.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Bulk C" --json | jq -r '.id' | tee c.txt
+test-[SHORTID]
+? 0
+```
+
+# Test: Close two issues at once (one summary line + visible sync hint)
+
+```console
+$ tbd close $(cat a.txt) $(cat b.txt)
+✓ Closed 2: test-[SHORTID] test-[SHORTID]
+• Unsynced changes[..]
+? 0
+```
+
+# Test: Closing again reports both as skipped (bulk idempotent)
+
+```console
+$ tbd close $(cat a.txt) $(cat b.txt)
+✓ Closed 0, skipped 2 (already closed): test-[SHORTID] test-[SHORTID]
+? 0
+```
+
+# Test: An unknown ID fails closed and changes nothing
+
+```console
+$ tbd close $(cat c.txt) test-zzzz 2>&1
+[..]
+? 1
+```
+
+# Test: c is still open after the aborted batch
+
+```console
+$ tbd show $(cat c.txt) --json | jq -r '.status'
+open
+? 0
+```
+
+# Test: --ignore-missing closes the known ID and reports the unknown
+
+```console
+$ tbd close $(cat c.txt) test-zzzz --ignore-missing
+✓ Closed 1, not found 1: test-[SHORTID] test-zzzz
+• Unsynced changes[..]
+? 0
+```
+
+# Test: --json emits a structured results array and summary
+
+```console
+$ tbd create "Bulk D" --json | jq -r '.id' | tee d.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Bulk E" --json | jq -r '.id' | tee e.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd close $(cat d.txt) $(cat e.txt) --json | jq -r '.summary.changed'
+2
+? 0
+```
+
+# Test: --quiet is silent on success (bulk)
+
+```console
+$ tbd create "Bulk F" --json | jq -r '.id' | tee f.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Bulk G" --json | jq -r '.id' | tee g.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd close $(cat f.txt) $(cat g.txt) --quiet
+? 0
+```
+
+* * *
+
+## Bulk reopen
+
+# Test: Seed two issues and close them
+
+```console
+$ tbd create "Reopen A" --json | jq -r '.id' | tee ra.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Reopen B" --json | jq -r '.id' | tee rb.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd close $(cat ra.txt) $(cat rb.txt) --quiet
+? 0
+```
+
+# Test: Reopen two issues at once (one summary line + visible sync hint)
+
+```console
+$ tbd reopen $(cat ra.txt) $(cat rb.txt)
+✓ Reopened 2: test-[SHORTID] test-[SHORTID]
+• Unsynced changes[..]
+? 0
+```
+
+# Test: Reopening again reports both as skipped (bulk idempotent)
+
+```console
+$ tbd reopen $(cat ra.txt) $(cat rb.txt)
+✓ Reopened 0, skipped 2 (already open): test-[SHORTID] test-[SHORTID]
+? 0
+```
+
+# Test: An unknown ID fails closed and changes nothing
+
+```console
+$ tbd reopen $(cat ra.txt) test-zzzz 2>&1
+[..]
+? 1
+```
+
+# Test: --ignore-missing reopens the known ID and reports the unknown
+
+Re-close `ra` so there is something to reopen:
+
+```console
+$ tbd close $(cat ra.txt) --quiet
+? 0
+```
+
+```console
+$ tbd reopen $(cat ra.txt) test-zzzz --ignore-missing
+✓ Reopened 1, not found 1: test-[SHORTID] test-zzzz
+• Unsynced changes[..]
+? 0
+```
+
+# Test: --json emits a structured results array and summary
+
+```console
+$ tbd create "Reopen C" --json | jq -r '.id' | tee rc.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Reopen D" --json | jq -r '.id' | tee rd.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd close $(cat rc.txt) $(cat rd.txt) --quiet
+? 0
+```
+
+```console
+$ tbd reopen $(cat rc.txt) $(cat rd.txt) --json | jq -r '.summary.changed'
+2
+? 0
+```
+
+# Test: --quiet is silent on success (bulk)
+
+```console
+$ tbd create "Reopen E" --json | jq -r '.id' | tee re.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Reopen F" --json | jq -r '.id' | tee rf.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd close $(cat re.txt) $(cat rf.txt) --quiet
+? 0
+```
+
+```console
+$ tbd reopen $(cat re.txt) $(cat rf.txt) --quiet
+? 0
+```
+
+* * *
+
+## Bulk update
+
+# Test: Seed two open issues
+
+```console
+$ tbd create "Update A" --json | jq -r '.id' | tee ua.txt
+test-[SHORTID]
+? 0
+```
+
+```console
+$ tbd create "Update B" --json | jq -r '.id' | tee ub.txt
+test-[SHORTID]
+? 0
+```
+
+# Test: Bulk-set shared fields (priority + label) on both
+
+```console
+$ tbd update $(cat ua.txt) $(cat ub.txt) --priority 0 --add-label delivered
+✓ Updated 2: test-[SHORTID] test-[SHORTID]
+• Unsynced changes[..]
+? 0
+```
+
+# Test: The shared label was applied
+
+```console
+$ tbd show $(cat ua.txt) --json | jq -r '.labels[0]'
+delivered
+? 0
+```
+
+# Test: A per-ID-only flag (--title) is rejected for multiple IDs
+
+```console
+$ tbd update $(cat ua.txt) $(cat ub.txt) --title "Nope" 2>&1
+[..]
+? 1
+```
+
+# Test: --status is rejected for bulk (no bulk-close bypass)
+
+```console
+$ tbd update $(cat ua.txt) $(cat ub.txt) --status closed 2>&1
+[..]
+? 1
+```
+
+# Test: Both are still open (the rejected bulk close changed nothing)
+
+```console
+$ tbd show $(cat ua.txt) --json | jq -r '.status'
+open
+? 0
+```
+
+# Test: An unknown ID fails closed and changes nothing
+
+```console
+$ tbd update $(cat ua.txt) test-zzzz --priority 1 2>&1
+[..]
+? 1
+```
+
+# Test: --ignore-missing updates the known ID and reports the unknown
+
+```console
+$ tbd update $(cat ua.txt) test-zzzz --assignee alice --ignore-missing
+✓ Updated 1, not found 1: test-[SHORTID] test-zzzz
+• Unsynced changes[..]
+? 0
+```
+
+# Test: --json emits a structured results array and summary
+
+```console
+$ tbd update $(cat ua.txt) $(cat ub.txt) --add-label shipped --json | jq -r '.summary.changed'
+2
+? 0
+```
+
+# Test: Updating with no fields is a usage error (exit 2)
+
+```console
+$ tbd update $(cat ua.txt) $(cat ub.txt) 2>&1
+[..]
+? 2
+```
+
+# Test: --quiet is silent on success (bulk)
+
+```console
+$ tbd update $(cat ua.txt) $(cat ub.txt) --priority 2 --quiet
+? 0
+```
+
+* * *
+
+## Removed `--no-sync`
+
+The legacy global `--no-sync` was a no-op (it set a context flag no mutator read) and is
+gone; issue writes always stage locally and `tbd sync` publishes.
+Passing it now errors as an unknown option rather than silently doing nothing.
+
+# Test: `close` rejects the removed `--no-sync`
+
+```console
+$ tbd close test-zzzz --no-sync 2>&1
+error: unknown option '--no-sync'
+? 1
+```
+
+# Test: `update` rejects the removed `--no-sync`
+
+```console
+$ tbd update test-zzzz --priority 1 --no-sync 2>&1
+error: unknown option '--no-sync'
+? 1
+```
diff --git a/packages/tbd/tests/cli-closing.tryscript.md b/packages/tbd/tests/cli-closing.tryscript.md
index ba83dc5b..b5b9969d 100644
--- a/packages/tbd/tests/cli-closing.tryscript.md
+++ b/packages/tbd/tests/cli-closing.tryscript.md
@@ -109,7 +109,6 @@ Global Options:
   --quiet         Suppress non-essential output
   --json          Output as JSON
   --color <when>  Colorize output: auto, always, never (default: "auto")
-  --no-sync       Skip automatic sync after write operations
   --debug         Show internal IDs alongside public IDs for debugging
 
 IMPORTANT:
diff --git a/packages/tbd/tests/cli-help-all.tryscript.md b/packages/tbd/tests/cli-help-all.tryscript.md
index 26c2ea3b..d9d06e3d 100644
--- a/packages/tbd/tests/cli-help-all.tryscript.md
+++ b/packages/tbd/tests/cli-help-all.tryscript.md
@@ -87,7 +87,7 @@ $ tbd update --help | grep -c "\-\-priority"
 
 ```console
 $ tbd close --help | grep -c "\-\-reason"
-1
+2
 ? 0
 ```
 
@@ -95,7 +95,7 @@ $ tbd close --help | grep -c "\-\-reason"
 
 ```console
 $ tbd reopen --help | grep -c "\-\-reason"
-1
+2
 ? 0
 ```
 
diff --git a/packages/tbd/tests/cli-import.tryscript.md b/packages/tbd/tests/cli-import.tryscript.md
index 49b5d811..adc46735 100644
--- a/packages/tbd/tests/cli-import.tryscript.md
+++ b/packages/tbd/tests/cli-import.tryscript.md
@@ -73,7 +73,6 @@ Global Options:
   --quiet             Suppress non-essential output
   --json              Output as JSON
   --color <when>      Colorize output: auto, always, never (default: "auto")
-  --no-sync           Skip automatic sync after write operations
   --debug             Show internal IDs alongside public IDs for debugging
 ...
 ? 0
diff --git a/packages/tbd/tests/cli-prime.tryscript.md b/packages/tbd/tests/cli-prime.tryscript.md
index 641663c2..6cde0588 100644
--- a/packages/tbd/tests/cli-prime.tryscript.md
+++ b/packages/tbd/tests/cli-prime.tryscript.md
@@ -224,7 +224,6 @@ Global Options:
   --quiet         Suppress non-essential output
   --json          Output as JSON
   --color <when>  Colorize output: auto, always, never (default: "auto")
-  --no-sync       Skip automatic sync after write operations
   --debug         Show internal IDs alongside public IDs for debugging
 
 IMPORTANT:
diff --git a/packages/tbd/tests/cli-setup-commands.tryscript.md b/packages/tbd/tests/cli-setup-commands.tryscript.md
index e957375e..9172c68f 100644
--- a/packages/tbd/tests/cli-setup-commands.tryscript.md
+++ b/packages/tbd/tests/cli-setup-commands.tryscript.md
@@ -54,7 +54,6 @@ Global Options:
   --quiet            Suppress non-essential output
   --json             Output as JSON
   --color <when>     Colorize output: auto, always, never (default: "auto")
-  --no-sync          Skip automatic sync after write operations
   --debug            Show internal IDs alongside public IDs for debugging
 
 IMPORTANT:
diff --git a/packages/tbd/tests/cli-setup.tryscript.md b/packages/tbd/tests/cli-setup.tryscript.md
index fa1bb87c..92084247 100644
--- a/packages/tbd/tests/cli-setup.tryscript.md
+++ b/packages/tbd/tests/cli-setup.tryscript.md
@@ -43,7 +43,6 @@ Options:
   --json                        Output as JSON
   --color <when>                Colorize output: auto, always, never (default:
                                 "auto")
-  --no-sync                     Skip automatic sync after write operations
   --debug                       Show internal IDs alongside public IDs for
                                 debugging
   --help                        Display help for command
@@ -69,9 +68,9 @@ Setup & Configuration:
 Working With Issues:
   create [options] [title]      Create a new issue
   show [options] <id>           Show issue details
-  update [options] <id>         Update an issue
-  close [options] <id>          Close an issue
-  reopen [options] <id>         Reopen a closed issue
+  update [options] <ids...>     Update one or more issues
+  close [options] <ids...>      Close one or more issues
+  reopen [options] <ids...>     Reopen one or more closed issues
   search [options] <query>      Search issues by text
 
 Views and Filtering:
@@ -149,7 +148,6 @@ Global Options:
   --quiet               Suppress non-essential output
   --json                Output as JSON
   --color <when>        Colorize output: auto, always, never (default: "auto")
-  --no-sync             Skip automatic sync after write operations
   --debug               Show internal IDs alongside public IDs for debugging
 
 IMPORTANT:
diff --git a/packages/tbd/tests/cli-sync-concurrent-epic-155.tryscript.md b/packages/tbd/tests/cli-sync-concurrent-epic-155.tryscript.md
index ae6e71e4..4e41ae9b 100644
--- a/packages/tbd/tests/cli-sync-concurrent-epic-155.tryscript.md
+++ b/packages/tbd/tests/cli-sync-concurrent-epic-155.tryscript.md
@@ -61,7 +61,7 @@ done
 # Test: Session A appends Child A locally without pulling B’s change
 
 ```console
-$ tbd create "Child A" --parent "$(cat ../epic.txt)" --no-sync >/dev/null 2>&1; echo done
+$ tbd create "Child A" --parent "$(cat ../epic.txt)" >/dev/null 2>&1; echo done
 done
 ? 0
 ```
diff --git a/packages/tbd/tests/cli-sync-push-retry-155.tryscript.md b/packages/tbd/tests/cli-sync-push-retry-155.tryscript.md
index 437ce840..701ba3d9 100644
--- a/packages/tbd/tests/cli-sync-push-retry-155.tryscript.md
+++ b/packages/tbd/tests/cli-sync-push-retry-155.tryscript.md
@@ -61,7 +61,7 @@ done
 # Test: Session A appends Child A locally (committed on next push, not pulled)
 
 ```console
-$ tbd create "Child A" --parent "$(cat ../epic-pr.txt)" --no-sync >/dev/null 2>&1; echo done
+$ tbd create "Child A" --parent "$(cat ../epic-pr.txt)" >/dev/null 2>&1; echo done
 done
 ? 0
 ```
diff --git a/packages/tbd/tests/cli-uninstall.tryscript.md b/packages/tbd/tests/cli-uninstall.tryscript.md
index 19cc0d71..98b6bb2a 100644
--- a/packages/tbd/tests/cli-uninstall.tryscript.md
+++ b/packages/tbd/tests/cli-uninstall.tryscript.md
@@ -49,7 +49,6 @@ Global Options:
   --quiet          Suppress non-essential output
   --json           Output as JSON
   --color <when>   Colorize output: auto, always, never (default: "auto")
-  --no-sync        Skip automatic sync after write operations
   --debug          Show internal IDs alongside public IDs for debugging
 
 IMPORTANT:
diff --git a/packages/tbd/tests/common-dir-layout-doctor.test.ts b/packages/tbd/tests/common-dir-layout-doctor.test.ts
index 39308673..ccfebec6 100644
--- a/packages/tbd/tests/common-dir-layout-doctor.test.ts
+++ b/packages/tbd/tests/common-dir-layout-doctor.test.ts
@@ -71,7 +71,7 @@ async function setupRepo(): Promise<string> {
   const init = runTbd(dir, ['init', '--prefix=test']);
   expect(init.status).toBe(0);
   // Create an issue so the shared worktree is fully populated.
-  const create = runTbd(dir, ['create', 'Seed', '--type', 'task', '--json', '--no-sync']);
+  const create = runTbd(dir, ['create', 'Seed', '--type', 'task', '--json']);
   expect(create.status).toBe(0);
   return dir;
 }
@@ -270,7 +270,7 @@ describeUnlessWindows('common-dir layout via CLI', { timeout: 30000 }, () => {
       // main checkout's f03 → f04 commit.
       await writeFile(configPath, original.replace('tbd_format: f06', 'tbd_format: f03'));
 
-      const create = runTbd(dir, ['create', 'sibling-bump probe', '--type', 'task', '--no-sync']);
+      const create = runTbd(dir, ['create', 'sibling-bump probe', '--type', 'task']);
       expect(create.status).toBe(0);
       // The notice goes to stderr so it cannot pollute JSON output on stdout.
       expect(create.stderr).toContain('tbd_format');
@@ -281,7 +281,7 @@ describeUnlessWindows('common-dir layout via CLI', { timeout: 30000 }, () => {
       expect(after).toContain('tbd_format: f06');
 
       // Second mutating call must NOT re-emit the notice: nothing left to migrate.
-      const second = runTbd(dir, ['create', 'sibling-bump probe 2', '--type', 'task', '--no-sync']);
+      const second = runTbd(dir, ['create', 'sibling-bump probe 2', '--type', 'task']);
       expect(second.status).toBe(0);
       expect(second.stderr).not.toContain('tbd_format');
     });
@@ -308,13 +308,7 @@ describeUnlessWindows('common-dir layout via CLI', { timeout: 30000 }, () => {
         // A plain data command must succeed (NOT fail with a layout/config
         // mismatch), migrate the config, re-stamp the layout, and emit the
         // one-time migration notice.
-        const create = runTbd(dir, [
-          'create',
-          `upgrade probe ${round}`,
-          '--type',
-          'task',
-          '--no-sync',
-        ]);
+        const create = runTbd(dir, ['create', `upgrade probe ${round}`, '--type', 'task']);
         expect(create.status).toBe(0);
         expect(create.stderr).toContain('f04 → f06');
         expect(await readFile(configPath, 'utf-8')).toContain('tbd_format: f06');
@@ -326,7 +320,7 @@ describeUnlessWindows('common-dir layout via CLI', { timeout: 30000 }, () => {
       await migrateOnceFromF04(2);
 
       // Steady state afterwards: no further migration notices.
-      const steady = runTbd(dir, ['create', 'steady probe', '--type', 'task', '--no-sync']);
+      const steady = runTbd(dir, ['create', 'steady probe', '--type', 'task']);
       expect(steady.status).toBe(0);
       expect(steady.stderr).not.toContain('tbd_format');
     });
@@ -362,7 +356,7 @@ describeUnlessWindows('common-dir layout via CLI', { timeout: 30000 }, () => {
         'tbd_format: f06',
       );
 
-      const create = runTbd(dir, ['create', 'resume probe', '--type', 'task', '--no-sync']);
+      const create = runTbd(dir, ['create', 'resume probe', '--type', 'task']);
       expect(create.status).toBe(0);
       expect(create.stderr).toContain('f04 → f06');
       expect(await readFile(configPath, 'utf-8')).toContain('tbd_format: f06');
diff --git a/packages/tbd/tests/git-env-isolation-e2e.test.ts b/packages/tbd/tests/git-env-isolation-e2e.test.ts
index e2c6cc65..4a527325 100644
--- a/packages/tbd/tests/git-env-isolation-e2e.test.ts
+++ b/packages/tbd/tests/git-env-isolation-e2e.test.ts
@@ -79,7 +79,7 @@ describe('ambient GIT_DIR isolation (product)', { timeout: 120_000 }, () => {
       () => null,
     );
 
-    const create = runTbdHostile(['create', 'isolation probe issue', '--no-sync']);
+    const create = runTbdHostile(['create', 'isolation probe issue']);
     expect(create.status).toBe(0);
     expect(create.stderr).toContain('ignoring inherited GIT_DIR');
     // Warned once, not per git call.
diff --git a/packages/tbd/tests/lockfile-acquire-eperm.test.ts b/packages/tbd/tests/lockfile-acquire-eperm.test.ts
new file mode 100644
index 00000000..aea41127
--- /dev/null
+++ b/packages/tbd/tests/lockfile-acquire-eperm.test.ts
@@ -0,0 +1,71 @@
+/**
+ * Acquire-side hardening for `withLockfile`: a transient Windows mkdir failure
+ * (EBUSY/EPERM/EACCES raised when acquisition races a concurrent rmdir of the same
+ * lock directory) must be retried, but a *persistent* permission failure — the
+ * genuinely-unwritable-lock case that `tbd doctor` reports — must still surface.
+ *
+ * These run on every platform with a mocked `node:fs/promises` so the behavior is
+ * deterministic; the real Windows race is timing-dependent and not reproducible in
+ * CI. See lockfile.ts and tbd-29k3 / the lockfile.test.ts concurrency test.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const { mkdirMock } = vi.hoisted(() => ({ mkdirMock: vi.fn() }));
+
+vi.mock('node:fs/promises', () => ({
+  mkdir: mkdirMock,
+  rmdir: vi.fn().mockResolvedValue(undefined),
+  rename: vi.fn().mockResolvedValue(undefined),
+  stat: vi.fn().mockResolvedValue({ isDirectory: () => true, mtimeMs: Date.now() }),
+}));
+
+const { withLockfile } = await import('../src/utils/lockfile.js');
+
+function eperm(): NodeJS.ErrnoException {
+  const error = new Error('EPERM: operation not permitted, mkdir') as NodeJS.ErrnoException;
+  error.code = 'EPERM';
+  return error;
+}
+
+describe('withLockfile acquire: transient Windows mkdir EPERM', () => {
+  afterEach(() => {
+    mkdirMock.mockReset();
+  });
+
+  it('retries a transient mkdir EPERM and then acquires the lock', async () => {
+    mkdirMock
+      .mockRejectedValueOnce(eperm())
+      .mockRejectedValueOnce(eperm())
+      .mockResolvedValueOnce(undefined);
+    const critical = vi.fn().mockResolvedValue('ok');
+
+    await expect(withLockfile('/tmp/transient.lock', critical, { pollMs: 1 })).resolves.toBe('ok');
+    expect(critical).toHaveBeenCalledTimes(1);
+    expect(mkdirMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('still surfaces a persistent EPERM (genuinely unwritable dir) after the bounded budget', async () => {
+    mkdirMock.mockRejectedValue(eperm());
+    const critical = vi.fn();
+
+    await expect(
+      withLockfile('/tmp/unwritable.lock', critical, { pollMs: 1 }),
+    ).rejects.toMatchObject({ code: 'EPERM' });
+    expect(critical).not.toHaveBeenCalled();
+    // The 5-retry budget plus the final attempt that re-raises the original error.
+    expect(mkdirMock).toHaveBeenCalledTimes(6);
+  });
+
+  it('throws non-transient mkdir errors (e.g. ENOSPC) immediately, without retrying', async () => {
+    const enospc = new Error('ENOSPC: no space left on device') as NodeJS.ErrnoException;
+    enospc.code = 'ENOSPC';
+    mkdirMock.mockRejectedValue(enospc);
+    const critical = vi.fn();
+
+    await expect(withLockfile('/tmp/full.lock', critical, { pollMs: 1 })).rejects.toMatchObject({
+      code: 'ENOSPC',
+    });
+    expect(critical).not.toHaveBeenCalled();
+    expect(mkdirMock).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/packages/tbd/tests/output.test.ts b/packages/tbd/tests/output.test.ts
index 891ea280..cda82aae 100644
--- a/packages/tbd/tests/output.test.ts
+++ b/packages/tbd/tests/output.test.ts
@@ -24,7 +24,6 @@ function createMockContext(overrides: Partial<CommandContext> = {}): CommandCont
     quiet: false,
     json: false,
     color: 'never', // Disable colors for testing
-    sync: true,
     debug: false,
     ...overrides,
   };
diff --git a/packages/tbd/tests/quiet-notices.test.ts b/packages/tbd/tests/quiet-notices.test.ts
new file mode 100644
index 00000000..63c5fb75
--- /dev/null
+++ b/packages/tbd/tests/quiet-notices.test.ts
@@ -0,0 +1,48 @@
+/**
+ * The low-level data layer emits two incidental stderr notices — worktree
+ * auto-heal and config-format migration. Under `--quiet` they must be silent so
+ * agents no longer need `2>&1 | tail -1`. Both honor the process-wide quiet flag
+ * recorded by getCommandContext(); these tests exercise the exported worktree
+ * notice (the migration notice is private but uses the identical gate). See
+ * tbd-29k3 / plan-2026-06-13-agent-cli-ergonomics.md.
+ */
+import { afterEach, describe, it, expect, vi } from 'vitest';
+
+import { notifyWorktreeRepaired } from '../src/cli/lib/data-context.js';
+import { quietNoticesActive, setQuietNotices } from '../src/cli/lib/context.js';
+
+describe('incidental data-layer notices honor --quiet', () => {
+  afterEach(() => {
+    setQuietNotices(false);
+    vi.restoreAllMocks();
+  });
+
+  it('setQuietNotices toggles the process-wide flag', () => {
+    setQuietNotices(true);
+    expect(quietNoticesActive()).toBe(true);
+    setQuietNotices(false);
+    expect(quietNoticesActive()).toBe(false);
+  });
+
+  it('prints the worktree-heal notice at the default level', () => {
+    setQuietNotices(false);
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    notifyWorktreeRepaired('missing');
+    expect(write).toHaveBeenCalledTimes(1);
+    expect(String(write.mock.calls[0]![0])).toContain('tbd-sync worktree was missing');
+  });
+
+  it('is silent under --quiet', () => {
+    setQuietNotices(true);
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    notifyWorktreeRepaired('missing');
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it('stays silent for a no-op (undefined) status regardless of quiet', () => {
+    setQuietNotices(false);
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+    notifyWorktreeRepaired(undefined);
+    expect(write).not.toHaveBeenCalled();
+  });
+});