Capture¶

bob capture writes tasks and bullets, queues bare public links as background reference jobs, and manages Pomodoro sessions without opening desktop Obsidian. The job confirmation says reading queue. The background job files the note when it runs; a queued clip appears in bob ref list after the host's intake drain (bob ref scan -i). Companion commands parse in-progress drafts, complete markers and wikilinks, list routes and tasks, assign block IDs, and name Pomodoros. Bob Mac Capture is the macOS menu-bar frontend: it owns the hotkey and panel, then delegates grammar, preview, completion, and vault writes to these bob commands.

bob capture --help is the concise usage contract. This page is the full workflow guide.

Contents¶

• Grammar at a glance
• bob capture
• Routing and insertion
• Global destination declaration
• Scheduling and priority
• Multi-item capture
• Bulk templates
  • Saved templates
• Authored sub-bullets
• Clipboard
• Saving links to your reading queue
• Task with a requested block ID
• Pomodoro-linked tasks
• Starting the session atomically
• Linking and starting existing tasks
• Picking any open task with ':'
• Going to a task with '/'
• Adding prerequisites with '&'
• Blocking existing tasks with '*'
• Relating existing tasks with '&' and '*'
• Linking tasks with '~' and '~~'
• Completing tasks with '!'
• Routing inbox tasks out
• Plan budget and strict mode
• Starting the next Pomodoro
• Starting a named Pomodoro
• Adjusting the current Pomodoro
• Shifting the current Pomodoro
• Closing the running Pomodoro
  • Retired close spellings
  • Choosing each Task Link's outcome
  • Logging work while closing
• Chaining session operators on one line
• Project notes
• Sub-bullets under existing tasks
• Task Link toggle
• Pomodoro notes
• Section bullets
• Command-line options
• Input, stdin, and JSON output
• Interactive editor markers
• bob capture-parse
• bob capture-related
• bob capture-rewrite
• bob capture-complete
• Discovery commands
• bob capture-templates
• bob capture-task-id
• bob capture-pomodoro-name

Grammar at a glance¶

One capture item is a parent line plus optional authored child bullets. Blank physical lines split a draft into multiple items; each item is planned before anything is written, and any failure rolls the whole batch back.

# is not one marker. Read it by what it is attached to:

A # after @route+id follows the item's mode: with no body text it names a Pomodoro for the task toggle, and once body text is present it names an ALL-CAPS task section for the child bullet. A # in the middle of the body stays ordinary text. @route::id is retired; use @route^id for an ordinary task with a block ID.

Leading @route text is accepted only on an item's first physical line. Later lines in the same item take trailing markers only. @@... has no such restriction: a declaration token may appear on any parent or authored child line. Terminal s:<N>, $<N>, %..., and @... markers configure the whole item no matter which of its lines they appear on.

bob capture¶

bob capture [OPTIONS] [--] [TEXT]...

Captures tasks, ordinary Markdown bullets, task sub-bullets, or reference links without requiring desktop Obsidian to be open. Reference links queue for background capture as described in Saving links. TEXT is one or more physical lines: the first nonblank line is the captured parent, and whitespace within each line is normalized, but line breaks are meaningful -- see "Authored sub-bullets" below for the bounded hierarchy later lines accept. Task mode writes - [ ] #task <text> [created::YYYY-MM-DD] when unscheduled, or [?] when a scheduled property is resolved, and routes to mac_inbox.md by default; bullet mode writes into a selected non-Tasks section as described below. The created date uses the local date from BOB_NOW, DATE, or the system clock.

Routing and insertion¶

Automatic routing uses a leading @route text prefix when present; otherwise a trailing text @route suffix is used. A draft-wide @@route or @@route+block-id declaration, described below, supplies the same destination to every item that has no local route or mode marker. Route names use A-Z, a-z, 0-9, _, and -, are lower-cased, and write to <route>.md at the vault root. Existing target files, including mac_inbox.md, prefer a Markdown Tasks section: new captures insert after the last top-level #task block in that section, or after one blank line below the Tasks heading when the section has no tasks yet. When bob task reconcile (formerly bob task-status-hooks, still accepted) has generated a status-count badge row directly below the heading, the empty-section insertion point is below that row. Files without a Tasks section keep the older fallback of inserting after the last top-level #task block and its indented continuation lines, or appending at EOF.

Global destination declaration¶

A global declaration is a whitespace-free @@<route> or @@<route>+<block-id> token anywhere in the draft. It may sit at the end of an item, on an authored child line, in the middle of a line, or on a line by itself:

Buy milk @@groceries

Parent task
- child detail @@work

First task

Second task @@foo

A physical line whose tokens are all @@... declarations is metadata only. It is removed before blank-line item splitting, so the historical top-of-draft spelling still behaves the same:

@@foo
First task

Second task

@@foo

First task

Second task

@@<route> sends every otherwise-unrouted item to <route>.md as a task. @@<route>+<block-id> inserts every otherwise-unrouted item as its own direct child beneath that task, in source order; authored children stay nested under their own capture parent. Route and block-ID validation match @route and @route+block-id.

The declaration is metadata, never capture text: it is absent from item counts, semantic capture text, preview bodies, and note contents. A draft that contains only a declaration fails with an actionable "add a capture item" error. @@ is reserved for this grammar. A second declaration fails with a duplicate global destination error naming both lines:

@@foo
Buy milk @@bar

Unsupported forms such as @@foo#Ideas, @@foo^id, @@foo:id, @@foo^id+, and @@foo:id+ are errors rather than literal task text. Wrap @@... in inline code to keep it literal.

An item-local marker still wins for that item. If the same item also owns the declaration, bob capture-parse reports a global_destination_shadowed warning and bob capture surfaces the same warning:

Buy milk @dev @@groceries

Other task

Here Buy milk routes to dev.md; Other task inherits groceries.md.

Do not combine a textual @@ declaration with --route, --section, --task, or --task-section. Clipboard, scheduling, priority, dry-run, formatting, and stdin remain composable.

Each real item resolves in this order:

1. An item-local route or mode marker wins. That includes @bar, @bar+b-id, @bar#..., @bar^..., @bar:..., @bar^id+, and a trailing bare #.
2. Otherwise inherit the complete @@... declaration.
3. Otherwise keep today's mac_inbox.md task default.

A local override is not a duplicate-route diagnostic merely because a declaration exists. Later items still see earlier staged edits to the same note or parent, and any failure rolls every target back.

Scheduling and priority¶

Append a lowercase s:<N> token to schedule the capture N days from today. It is recognized only in the terminal token region and may appear on either side of a trailing route marker. The token is removed from the body and adds [scheduled::YYYY-MM-DD] after the created stamp. Checkbox-bearing captures with a resolved scheduled property start Blocked ([?]), including s:0. Ordinary bullet and sub-bullet captures still render without a checkbox. N is a non-negative integer. An offset that cannot be added to today inside the representable calendar — for example s:9999999999 — fails before any write. Human output is bob capture: scheduled offset is out of range (exit 2). With --format json, stdout is {"ok": false, "error": "scheduled offset is out of range"}. A $<N> roll that lands outside that calendar uses the same error.

Append a $ or $<N> token to write a priority level, where N selects the Nth level in the bullet-property config file. A bare $ means $1. Bob looks for that file at BOB_CONFIG_FILE, then $XDG_CONFIG_HOME/bob/config.yml, then ~/.config/bob/config.yml — the same file the Obsidian picker reads. A missing or unreadable file is an error; $<N> has no built-in default levels. The currently deployed file uses four levels:

The token writes [priority::<value>] and rolls a random [scheduled::YYYY-MM-DD] date inside that level's day window. Each capture rolls independently, so a --dry-run preview differs from the real capture unless BOB_PRIORITY_ROLL_SEED is set. A task with no priority field is implicitly P0 (do it now, no roll), so there is no $0. An explicit s:<N> wins the scheduled date; $<N> still writes the priority. A rolled $<N> date also writes a 🗓️ **SCHEDULE LOG** child bullet with one dated 🎲 … entry recording why, byte-for-byte matching what the Obsidian Ctrl+Shift+P picker writes for the same level with no reason prompt:

- [?] #task someday idea [created::2026-08-07] [priority::lowest] [scheduled::2026-11-06]
    - 🗓️ **SCHEDULE LOG**
        - *2026-11-06* — 🎲 P0 → P4 · in **91** (91–365) days

The bold number is the exact relative day offset selected for that scheduled date. The parenthesized range is the configured priority window.

A $<N> s:<N> capture writes no entry, since s:<N> wins the scheduled date and no roll happened. A $<N> past the configured level count is a usage error (exit 2). The message is $<N> is not a configured priority level; use $ or $1 through $<count> (<labels>). Any resolved scheduled property makes a checkbox-bearing capture start Blocked ([?]); bob task reconcile still reconciles tasks whose schedules are edited later.

$/$<N> is recognized only in the terminal marker region, so a mid-line amount stays text: Pay $3 to Bob. In a shell, single-quote the token (bob capture buy milk '$2'); an unquoted or double-quoted $2 is expanded by the shell.

To keep a trailing dollar amount as task text, escape it the same way as \& / \*: Pay Bob \$3 writes body Pay Bob $3 with no priority, and Pay Bob \$3 $2 @cash writes body Pay Bob $3 at level 2 routed to cash. Elsewhere \$ stays verbatim (cost \$3 today keeps the backslash).

Multi-item capture¶

One or more blank or whitespace-only physical lines split TEXT into ordered capture items. Leading, trailing, and repeated separator runs are ignored, so a draft with at least one nonempty item is valid even if it starts or ends with blank rows. Each item uses the normal capture grammar independently: the first nonblank line is that item's parent, later contiguous authored bullet rows belong only to that item, and terminal s:<N>, $<N>, %..., and @... markers configure only that item.

Bob plans the whole batch against in-memory note and daily-ledger snapshots before writing anything. Later items see earlier planned edits to the same target, so order, insertion points, duplicate block-ID checks, sub-bullet lookups, and Pomodoro links match a successful sequential capture. If any item fails to parse, read the clipboard, validate, stage, or replace, Bob leaves notes, ledgers, and newly-created clipboard files at their original state. --dry-run uses the same planner with the commit step disabled.

Before replacing a note, Bob checks that its on-disk contents still match the planning snapshot. The check runs before any temporary files are created, again after those files exist, and once more immediately before each replacement. A mismatch refuses the batch with exit 1 and one of these messages:

• refusing to overwrite <path>: note changed on disk after planning
• refusing to overwrite <path>: note was deleted on disk after planning
• refusing to overwrite <path>: note was created on disk after planning

Reload the affected note and rerun the capture. The checks narrow the race with another writer; they do not lock the file. If a later replacement fails, Bob restores notes it already replaced in this batch. A successful rollback appends ; rolled back earlier note writes. A failed rollback names the file: rollback of <path> failed: ….

Reference jobs are written before note files. If the note write fails, Bob removes the jobs it just created and appends ; removed ref jobs created by this capture. A later clip failure writes a fallback inbox task for that link and leaves the other captured items in place.

Same-line session-operator chains split the same way: a physical line holding only whitespace-separated session operators (+2 x) yields one item per token, in order, exactly like the same operators on blank-line-separated rows. See Chaining session operators on one line.

Single-item success JSON keeps the legacy shape. A multi-item success keeps the first result in the legacy top-level fields and adds an ordered captures array containing every per-item result. When a @@ declaration is present, success JSON also adds an optional top-level global_destination object with mode, route, and optional block_id. The declaration never creates an extra result. Human output numbers batch items as 1/N, 2/N, and so on, and prints a compact global foo.md (or global foo.md · under ^a-id) summary when a declaration was used.

Bulk templates¶

A draft whose first nonblank line is @@template: expands one capture item per row. The planner receives the same text that bob capture -E prints, so a template capture has the same results, ordering, and all-or-nothing writes as capturing that expansion directly. Editors that run capture-rewrite, including the Mac capture panel, turn a typed @@@ at the very start of a draft into the template header and place the caret on the next line.

@@template:
Apply to {0}! @job^apply-{1}
- **URL**: {2}

Foobar foo http://foobar.com/career/some_foo_job
"Two Sigma" two-sigma https://www.twosigma.com/careers/some_role

This expands to two ordinary items, preserving the authored child bullet:

Apply to Foobar! @job^apply-foo
- **URL**: http://foobar.com/career/some_foo_job

Apply to Two Sigma! @job^apply-two-sigma
- **URL**: https://www.twosigma.com/careers/some_role

The template is one item: a parent line and optional authored child bullets. It ends at the first blank line after the header. Blank lines after that separate rows and are ignored. Each nonblank row supplies one capture, except a template using only {0} takes one capture per space-separated value, so values may share a line or sit one per line; rows cannot have child bullets yet.

A {0}-only template takes one capture per value:

@@template:
foo: {0}! @sase:foo-{0}

bar baz bam

This expands to three ordinary items, exactly like one value per line:

foo: bar! @sase:foo-bar

foo: baz! @sase:foo-baz

foo: bam! @sase:foo-bam

Values are inserted once and are not scanned again. Every ordinary marker in the template applies independently to each row, including routes and sections, s:<N>, $<N>, & and * dependencies, completion (!note:id), task links, and reference URLs. Duplicate block IDs across rows are refused by the normal planner. A row with an empty or incomplete picker value gets the existing capture error, scoped to that template row.

Use @route:{1} when each row should link its task under the one selected Pomodoro; the normal plan.max_links warning applies. Use @route^apply-{1} when rows should create plain Ready tasks that you link as you work them.

Templates refuse other @@ declarations, clipboard capture, and Pomodoro session operators. This includes % markers even with --no-clip, --clip, whole-item forms such as =, x, +N, and ++N, and start/close suffixes on task markers. URL % remains allowed when it is the reference listen marker. In a {0}-only template, keep the marker on its URL by quoting the row ("https://example.com/one %") or by putting % in the template ({0} % covers the all-listen case); an unquoted https://example.com/one % row is two values and refuses naming row 2. A template is limited to 1,000 rows and 1 MiB of expanded text; it is refused rather than truncated when it exceeds either bound.

Template errors use stable codes in JSON mode. Execution reports the first problem in draft order and writes nothing:

Success JSON adds a top-level template summary (line, field_count, and row_count) and a template_row (row, line) on each result item. Human output prints a dim row-count and source-line summary before the numbered items. -E, --expand prints the expanded text and exits before vault access or planning; JSON mode returns it as expanded with the same template summary. On drafts without the header, -E returns the original text.

Saved templates¶

Every successful real @@template: capture saves its template block to a bob-owned shelf, so the next wave reuses it instead of retyping it. Only the block is saved, never the rows: rows carry one-off values that must not replay.

Saving happens after the vault write succeeds, once per invocation (not once per row), and only for real captures: --dry-run, -E, failed or refused captures, drafts without a header, and forced -r/-s/-t destinations never touch the shelf. capture-parse, capture-complete, and capture-rewrite never touch it either. Saving is best-effort and never fails a capture: the exit code stays 0, and a shelf failure prints bob capture: warning: template not saved: <reason> on stderr with template.not_saved in JSON.

The shelf lives at ${XDG_STATE_HOME:-~/.local/state}/bob-cli/capture/templates.json. BOB_CAPTURE_TEMPLATES_FILE overrides the exact file path. The directory is 0700 and the file is 0600. Entries are keyed by the first 12 hex digits of SHA-256 over the canonical block text (trailing spaces and tabs stripped, lines joined with \n), ordered most recently touched first, with first_saved_at, last_used_at, and a use_count of successful captures.

capture.max_saved_templates in the Bob config caps the shelf from 0 to 36 and defaults to 36. Every write trims to the cap by dropping the least recently used entries. 0 turns saving off: bob never writes the shelf except for an explicit delete or clear, and existing entries stay listed and usable. An invalid value or a config read error prints one stderr warning and uses 36.

A save may carry the app's checkout origin: when the used block differs from the checked-out entry, the edited version replaces the original in the same locked write and keeps its history, so edits never pile up near-duplicates. Abandoning a checked-out draft leaves the shelf untouched, and the copy on disk is never deleted by picking it.

Use bob capture-templates to manage the shelf. Bare invocation and list show the newest templates first. show TEMPLATE prints the ready-to-insert draft (@@template: header, definition, and an empty rows area) without styling, so it can be piped or copied directly. TEMPLATE is a 1-based list index of one or two digits, or the content id shown by list.

bob capture-templates
bob capture-templates show 1
bob capture-templates save -f json < template-draft.txt
bob capture-templates delete 1 9c1f0e2a7b3d
bob capture-templates clear

save accepts TEXT arguments joined with spaces or a complete draft on stdin. It checks the definition (header, separator, placeholders, and block-level markers) while ignoring missing rows and row errors. Saving a definition does not increment use_count. The hidden --template-origin ID supports the Mac client's checkout flow; it replaces an edited origin atomically while keeping its history. delete is idempotent and reports unresolved selectors in JSON's missing array. clear also removes a corrupt quarantine copy and is allowed when the shelf was written by a newer schema.

list -f json returns schema_version, capacity, saving, the resolved file, and entries with their canonical text, insertion draft, UTF-8 byte cursor, field_count, line_count, route, capture-parse spans, and usage timestamps. The Mac client can render and insert those values without parsing the capture language. Shelf and config warnings appear in warnings.

Authored sub-bullets¶

TEXT may carry authored bullets beneath the parent line:

Prepare the launch review
- Confirm the rollout owner
  - Send the owner the final date
- Attach the final checklist @work $1
  - Verify the links

Within one capture item, every physical line after the first must be a first-level Markdown item at column zero or a nested Markdown item prefixed by exactly two ASCII spaces. At either level, -, *, or + must be followed by at least one space or tab. The source marker and separating whitespace are stripped, and each item is rendered with the canonical - <body> marker. First-level items render one indentation unit beneath the captured parent; nested items render two units beneath the parent and attach to the nearest preceding nonempty first-level authored item. The unit matches the target note's dominant tab-or-two-space child indentation, with a tab for a fresh note:

- [ ] #task Prepare the launch review [created::2026-08-14] [priority::high]
    - Confirm the rollout owner
        - Send the owner the final date
    - Attach the final checklist
        - Verify the links

A marker with nothing after it (- or - alone) is a harmless placeholder and produces no child; this keeps interactive editors safe while a row is only half-typed. Placeholder rows do not clear the current first-level owner, so a later nested item still attaches to it. A true blank row ends the item and starts the next item at the following nonblank line. One-space, three-or-more-space, tabbed, wrapped, or ordinary continuation prose is a usage error naming the physical line number. A nonempty nested item before any first-level authored item is an orphaned_nested_bullet error, and an item that becomes empty only because its whole body was a capture marker is rejected the same way. Every recognized terminal s:<N>, $<N>, %..., and @route/@route#/@route^block-id/ @route:block-id/@route+block-id/@route^block-id+ marker is an item-wide directive no matter which physical line in that item it appears on -- as shown above, @work and $1 on the last child still route and prioritize that item -- and is stripped from the rendered line it was typed on. A second line in the same item that resolves the same marker slot (two routes, two schedules, two priorities, or two clipboard markers) is ambiguous and fails with a usage error before anything is written. Only the first physical line of an item keeps the established leading @route text form; later lines compose trailing markers only. A sub_bullet capture (@route+block-id) nests the newly captured line under the selected existing task, then preserves both authored levels relative to that new line.

Authored children render before clipboard children and the priority schedule log, so the full block order is: parent line, authored children, clipboard children, then the schedule log.

Clipboard¶

Append one of these whitespace-delimited terminal markers to capture clipboard content beneath the new task or bullet:

• % captures the live clipboard once without a header.
• %<positive integer> captures exactly that many values without headers: the live clipboard first, followed by recent history newest first. For example, bob capture research links %3 captures three values. For ordinary non-reference task text, %1 is equivalent to %, leading zeroes are accepted, and %0 stays literal.
• %<nonnumeric header> captures the live clipboard once under an explicit header. Headers accept letters, digits, _, and -, render in uppercase, and replace underscores with spaces; for example, %build_log renders **BUILD LOG:**.

The grammar is context-dependent for an eligible URL-only reference: exact standalone URL % requests companion audio before clipboard parsing, so it does not read the clipboard even in live preview's --no-clip mode. Use URL %1 or --clip URL to explicitly request clipboard capture for a URL; non-reference text %, %N, and %header keep their clipboard meanings.

The marker composes with s:<N>, $<N>, ordinary routes, bullet routes, ID-only task routes, and Pomodoro routes in either terminal order. Invalid %... tokens and % tokens in the middle of the body stay literal. A counted capture requires every requested entry to read, normalize, classify, and plan successfully; insufficient or invalid history aborts the capture instead of writing a partial result.

Clipboard content is rendered according to its shape:

• One text line up to 1,000 characters becomes an inline child bullet.
• Two to ten flat text lines become child bullets, nested beneath an explicit header when one is present.
• One to ten top-level unordered Markdown list items using -, *, or + become child bullets. Their source list markers and separating whitespace are removed while inline Markdown, including checkbox text, is preserved.
• Absolute file paths (including quoted paths, file:// URIs, and ~/...) become attachments. Images are copied to img/ and embedded at 400px; other files are copied to file/ and linked.
• Long, indented, blank-line-separated, or other Markdown-structured text is saved verbatim as file/clip-YYYYMMDD-HHMMSS[-slug].md and linked without the .md suffix. Ordered, nested, wrapped, mixed, or empty-item lists use this snippet fallback instead of being partially normalized.

Each value in a counted history capture is classified independently, so limits such as the ten-attachment maximum apply per entry. All resulting lines are flattened in source order as direct, headerless children; entries receive no index labels, container bullets, or separators.

Clipboard children use the target note's dominant tab-or-two-space indentation and fall back to a tab, matching the sub-bullet capture rule.

Without a header, one item is written as a direct child and multiple items are written as direct sibling children:

- [ ] #task Parent
    - clipboard text
- [ ] #task Another parent
    - first line
    - second line

For example, a clipboard containing this flat Markdown list:

- first copied item
* second item with **inline Markdown**
+ [ ] third checkbox item

is normalized beneath the captured parent without doubling the source markers:

- [ ] #task Parent
    - first copied item
    - second item with **inline Markdown**
    - [ ] third checkbox item

An explicit header stays inline for one item and owns a nested list for multiple items:

- [ ] #task Parent
    - **BUILD LOG:** clipboard text
- [ ] #task Another parent
    - **BUILD LOG:**
        - first line
        - second line

Attachment names are sanitized for Obsidian links. An existing identical file is reused; differing content receives an eight-character SHA-256 suffix. Up to ten attachment paths may be pasted at once. Clipboard text must be non-empty UTF-8 without NUL bytes; binary clipboard contents should be represented by a copied file path. Clipboard and note edits are planned before anything is written, and newly created clipboard files are removed if the note write fails. --dry-run performs the same planning but creates no directories or files.

Use -c, --clip[=HEADER] to force clipboard capture without a marker. Bare --clip captures without a header, while --clip=build_log supplies an explicit header. Both forms force a single live value and keep % tokens in the captured text literal. A numeric header can be requested unambiguously with --clip=20; use -n, --no-clip when a genuine trailing %N or other %... token should remain literal. --clip and --no-clip conflict.

Saving links to your reading queue¶

A capture item that is nothing but one bare public link becomes a reference item (kind: "ref") instead of an inbox task. bob capture 'https://example.com/essay' saves a background job under mac_inbox. Add exactly one ordinary leading or trailing @route (URL @sase or @sase URL), a bare URL under a plain @@sase declaration, or a bare URL with -r sase to file it under that route instead: aliases resolve to the canonical route (so URL @bob-cli files under bob). The body holds only the URL; the input token and its canonical parent stay distinct, and the parent source is explicit, global, or default. A new link prints queued example.com/essay → sase with the detail new to your library · reading task lands in sase.md (or → mac_inbox with file it later for the default inbox). That line means the job was saved. The reading queue in bob ref list is the reference note. The background job files it when it runs; a queued clip appears after the host's intake drain (bob ref scan -i). Quote the URL when the shell would treat # as a comment.

Append a standalone % immediately after the URL (the next whitespace-delimited token on the same line, one or more spaces/tabs) to request companion audio: https://example.blog.com/somepost % clips like bob ref create <URL> -P <resolved-parent> -L. The shipped standalone @ spelling remains a compatible alias. URL % @sase and @sase URL % combine listen with an explicit parent; URL % alone uses the default, @@route global, or -r forced parent. Do not attach the directive to the URL, or put it in a query, fragment, encoded %25/%40, or userinfo — those bytes stay part of the URL. One optional <...> wrapper around the URL is still accepted. Exact URL % takes reference precedence over clipboard parsing; URL %1, --clip URL, and -R 'URL %' explicitly keep the clipboard/task path. Outside an admitted reference shape, % keeps its clipboard meaning, and --no-clip leaves ordinary clipboard markers literal. In live preview, --no-clip does not suppress a recognized URL reference listen marker. A non-URL bare @ and prefixes such as @sa remain route completion, and completing a claimed listen marker never replaces it (a separate @sa after URL % still completes the parent). A marked item prints queued … · Listen with · companion audio requested; it needs a configured highlights.listen_command. Inline intake files the PDF and MP3 together, and a queued capture is paired by bob ref scan -i or the local timer. Unlike an explicit ref create -L, the shorthand never adds audio to existing captures: a marked duplicate, pending job, or library hit queues nothing and shows no new listen job was queued · to attach audio run: bob ref create <URL> -P <parent> -L.

Anything more — an extra word, #tag, s:, $<N>, a clipboard marker, an operator, a child line, a @@route+block-id declaration, task/destination flags beyond -r (-s -t -S -c, --task-ref), or a second @route — keeps the item a task. -R also keeps it a task. Hosts without a dot (http://go/x, localhost), IP literals, and excluded hosts (see the URL routing policy) stay tasks too. An unresolvable route fails the item with near-miss hints and the whole batch rolls back; it never silently creates a new note. A pasted blank-line-free block in which every line is a bare URL splits into one item per line, and each line is then classified on its own, so mixed lists queue the links and keep the rest as tasks. A plain @@sase routes default (routeless) refs to sase while an explicit local @route keeps local precedence; @@sase+block-id keeps the item a task. Ordinary task @route capture does not resolve aliases.

Submit never touches the network and returns at once: it writes a durable ref job staged with the resolved parent and a detached background worker clips it through the same engine as bob ref create. If the clip fails, the link falls back to the parent note (<parent>.md) with exactly the URL task line capture previewed, plus a ⚠️ child with the reason and a bob ref create <url> -P <parent> retry command. bob ref jobs lists pending, clipping, and stuck jobs plus finished jobs from the last 7 days (--all shows older finished jobs); see ref jobs.

--dry-run is offline and writes nothing, including no job. Its headline and one detail line follow the library verdict (with the resolved parent):

A real submit uses queued in place of would queue. The not_found detail becomes clipping in the background · reading task lands in <parent>.md (· file it later for mac_inbox); legacy and unknown keep the details above. placement is "queued" for not_found, legacy, and unknown (a job will be written) and "unchanged" for the other verdicts (no new job). Reference items report routed: false, route: null, route_label: "", and task_line: "", plus an additive ref object with the classified URL, the library verdict, the canonical parent: {route, label, kind, source, alias} (including already-known URLs), the staged job, and the parent fallback on queued items. ref.job stays null until the commit, so every dry run has job: null. Marked references add ref.listen: true; when the URL is already known, ref.listen_hint gives the explicit bob ref create ... -P ... -L command because this shorthand never attaches audio or upgrades an existing job. bob capture-parse reports ref_parent: {token, source} on ref items outside needs (explicit token, inherited global route, or mac_inbox; source explicit|global|default), and a local route token keeps its ordinary route span. An eligible URL listen reference also reports ref_listen: true and a ref_listen span over the standalone % (or compatible @) token; both additions are omitted when listen is false. Route completion also matches project_name_aliases with match_kind: "alias" after canonical prefix matches. Opt out per capture with -R, --no-ref, or per entry point with highlights.url_routing.capture: false (silent; an invalid config warns and also keeps the link a task).

Task with a requested block ID¶

Use a leading or trailing @<route>^<block-id> marker to create an ordinary open task with a requested Obsidian block ID, without creating or modifying a Pomodoro task link. For example, bob capture '@dev^foobar' 'Some ordinary task.' writes:

- [ ] #task Some ordinary task. [created::2026-07-10] ^foobar

The route is lower-cased, and the destination may be an existing note or a missing note that can be created like any ordinary routed task. The task remains an ordinary [ ] task when unscheduled, or starts [?] when scheduled: priority and scheduled properties render before the final ^block-id, and the JSON kind stays "task". The block ID uses the same validator as other Bob task block IDs (letters, digits, and -). Before a real capture or --dry-run reports success, Bob rejects an ID that already appears anywhere in the destination note, leaving the note unchanged. This form never reads, validates, creates, or writes today's daily note; an invalid or missing BOB_DAY_FILE has no effect. The retired @<route>::<block-id> spelling is no longer accepted; use @<route>^<block-id> instead.

#now is retired¶

The #now weekly-bet tag was retired: the Next lane took over what it tracked, and Today is read from the ledger at render time (see docs/plan.md). A trailing #now is now the ordinary trailing-tag error like any other #tag, and a #now in the body stays plain text. Existing vault lines that still carry #now keep working — the text is ignored.

p:<N> is retired¶

The p:<N> priority marker is retired. Write $<N> instead (a bare $ means $1). A typed p:2 fails with `p:2` is retired; write `$2` for priority level 2 (a bare `$` means `$1`) and capture-parse reports retired_priority_marker on that token. A malformed p:x was never a marker and stays ordinary text.

Pomodoro-linked tasks¶

Use a leading or trailing @<route>:<block-id> marker to create a Pomodoro-linked next task. For example, bob capture '@dev:foobar' 'Some foobar task.' writes:

- [*] #task Some foobar task. [created::2026-07-10] ^foobar

It also adds [[dev#^foobar]] as a child bullet of an eligible open Pomodoro in today's daily note. The route is lower-cased and may contain letters, digits, _, and -. The block ID may contain letters, digits, and -, the same rule as @route^id. Scheduled offsets work in either terminal order; a scheduled Pomodoro-linked task starts [?], and the block ID remains the final task token after any [scheduled::YYYY-MM-DD] property. A newly captured task that is Blocked after the gesture is never linked (docs/task-dependencies.md §13.5): a future s:<N> (N ≥ 1), open & prerequisites, or a blocked destination project lands the new task [?] (plus #prj_is_blocked in a blocked project) with no Task Link. The open prerequisites rise along the task's edges instead, and JSON reports link_guard (reasons with the §13.9 kinds, promoted with route#^block identities, and a one-sentence detail); human output prints the same sentence after the task line.

The daily note is selected from BOB_DAY_FILE when set, otherwise from <bob-dir>/YYYY/YYYYMMDD.md using BOB_NOW or the local date. Within its Pomodoros section, capture prefers the single open top-level entry with a recognized bold or legacy time range; when there is no timed entry, it uses the first open top-level entry. Completed and nested entries are ignored. Multiple open timed entries are treated as an invariant error for this implicit selection. The link is inserted after the selected entry's existing children and reuses their indentation when possible.

An optional #<pomodoro> component names the target: @sase:deep-fix#bugs links under the open Pomodoro named BUGS and leaves the current Pomodoro alone. The selector is a slug — ASCII-lowercase, internal whitespace collapsed to - — using A-Z, a-z, 0-9, and & ' ( ) + , . / -. That is the task-section selector character set plus +. Matching is a whole-slug match in document order, else the first slug-prefix match, so #bugs and #bug both reach BUGS, and #memory still reaches MEMORY when MEMORY WORK appears first. Duplicate names resolve to the first open match; give the second a distinct name to target it. A typed # with an empty name is incomplete — it never falls back to "any Pomodoro". An existing open match is explicit, so it resolves even when the ledger has more than one open timed entry. Quote the name after # (@sase:deep-fix#"SASE V18", with straight or curly quotes) to spell it exactly: the literal matches by key equality, never by slug or prefix, so SASE V18 and SASE-V18 stay distinct and #"BOB" creates BOB even with BOB BUILD open. An unterminated literal (@sase:deep-fix#"SASE V) is incomplete, never a mistake.

When the selector has no matching open entry, capture treats the authored component as the name of a new future Pomodoro. The visible name uses the same canonicalization as bob capture-pomodoro-name: whitespace is collapsed, ASCII letters are uppercased, and allowed punctuation is preserved, so #after-tui-fix creates AFTER-TUI-FIX. The new entry renders as - [ ] () — NAME followed by the captured task link as its child. It is inserted after the current Pomodoro's complete block when there is one, otherwise after the last completed Pomodoro's complete block, otherwise before the first Pomodoro in the section. Completed-only matches create a new future Pomodoro keeping the completed entry's spelling — reusing completed deep-work creates DEEP WORK, never DEEP-WORK; completed history is not modified. Cancelled, nested, and fenced lookalikes are not anchors. Multiple open timed entries remain an invariant error when a new named entry would need the current-Pomodoro anchor.

The routed note and daily note are both parsed and validated before either is replaced. A missing daily note or Pomodoros section, no eligible unnamed target, timed ambiguity for implicit or named-creation captures, invalid Pomodoro name, malformed marker, duplicate block ID, or duplicate Pomodoro link leaves both notes unchanged. --dry-run and multi-item batches use the same staged daily-note snapshot as a real capture, so a later batch item can reuse a Pomodoro created by an earlier item without creating a duplicate.

Starting the session atomically¶

Append =<X> to a @<route>:<block-id>[#<pomodoro>] marker to start the selected Pomodoro in the same transaction: bob capture 'Write outline @sase:outline=3' creates the task, links it to today's next session, and starts a 15-minute session. @sase:outline#deep-work=-2 uses the named target and starts a default 25-minute session with a 10-minute offset. Prefer the short name spelling: bob capture '@sase:deep-fix=bugs' links under BUGS and starts it, exactly like @sase:deep-fix#bugs=.

<X> is exactly the suffix of the Obsidian bob-ledger-tools se<X> snippet:

An omitted duration means five 5-minute units (25 minutes); an omitted offset with - means one unit; no - means zero offset. 0 and leading zeros are valid. At the capture clock's local hour/minute, start = ceil((nowMinutes - 5*offsetUnits)/5)*5 and end = start + 5*durationUnits, displayed modulo 24 hours as (**HHMM-HHMM** [t:: Nm]) byte-for-byte like the snippet's range. BOB_NOW/Bob's existing clock sets the time; numeric overflow is a useful error rather than a wrong time.

The suffix is item-local and applies only to new : task captures — not + ensures, project-note + forms, global @@ declarations, or ordinary text. It cannot combine with s:<N> or $<N>: a scheduled Blocked task cannot start its session, so those combinations fail before anything is written. Only an untimed, open placeholder is ever started. Any open timed Pomodoro — including one past its nominal end — is restarted by a whole-item = start, with a visible warning before the write. Link starts keep the existing "finish the current Pomodoro first" error because they never override a running entry; only x closes one. A selected non-placeholder or structurally ambiguous ledger fails with the same error. A newly created started entry uses the same placement as named creation: after the last completed Pomodoro's complete block, otherwise before the first Pomodoro in the section. Starting an existing placeholder moves it, with its child block, to that same slot. JSON output keeps every existing key and adds an additive pomodoro_start object (resolved start/end, duration_minutes, offset_units, destination name/line, whether the entry was created); human output names the Pomodoro and its time.

Linking and starting existing tasks¶

Capture a whole item that is only @route:block-id[#pomodoro][=<X>] (or the ^route:block-id[#pomodoro][=<X>] active-task spelling, including the short @route:block-id=name / ^route:block-id=name suffix) to link an existing task into today's Pomodoro ledger and optionally start that session atomically. bob ref today reuses this planner for a reference's reading task; its exact-name (-e) and entry-ref (-P) targets are bob ref today-only and the capture grammar is unchanged. For example, bob capture '^sase:deep-fix=' links the existing ^deep-fix task in sase.md and starts its session, and bob capture '@sase:deep-fix=bugs' links it under BUGS and starts that session. The marker must be the entire capture item: no body text, no authored child bullets, no %/--clip, no s:<N>/$<N>, and no forced destination flags. A token with the complete ^route:block-id… shape claims its item; anything else on the item fails with an invalid_pomodoro_link error instead of becoming task text. Partial shapes (^, ^fragment, ^route:, ^route:block-id#) are incomplete editing states when they are the whole item and ordinary prose otherwise. Anything else starting with ^ (^_^, ^^, ^.) stays ordinary text, and ^ is only recognized as the first token of an item's first line. ^…+ and ^…! are rejected with messages naming the @route^block-id+ project-note and @route+block-id! toggle spellings. A @@ declaration never applies to a ^ item. Body-bearing <text> @route:block-id[#name][=<X>] keeps its exact current new-task meaning.

The existing task resolves with the task-toggle lookup, so missing notes, missing IDs (with a close-match suggestion plus a hint to add text for a new Pomodoro-linked task), duplicate IDs, and non-task block IDs reuse those errors. Ready [ ] and Blocked [?] tasks become Next [*]; Next stays Next and In Progress [/] is never demoted. A single valid future [scheduled::] is retired with the pull-forward Schedule Log entry when a log already exists — all under the existing Ensure Next rules, plus the §13.5 link guard: a target that is Blocked after the gesture stays unlinked while its open prerequisites (own plus inherited) rise, unless §13.5.1 permits capture to drop its own prerequisites and link in the same staged write. Project-blocked tasks and ^prj targets keep their prerequisites and stay unlinked. A refused drop adds drop_refused to link_guard. The one refusal is a ^prj whose only reason is its own future schedule: it fails with "move the project date from the ^prj Schedule action" instead of pulling the date forward. Done, canceled, and unknown statuses fail: only Ready, Blocked, Next, and In Progress tasks can be linked.

Let Q be the open Pomodoro whose children hold the task's dedicated [[route#^id]] Task Link (links under completed Pomodoros are history and are never edited; more than one movable link is the existing write-free invariant error). With #pomodoro, the existing named selection applies: whole-slug then prefix over open entries, else the canonical named future Pomodoro is created, and Q's complete subtree moves there (or a new link is inserted when there is no Q). Without a name, an already-queued task respects the queue: the destination is Q and nothing moves. Without a name and no Q, the implicit current/next Pomodoro is used, exactly like a new-task capture. =<X> uses the same se<X> math, clock, and guards: any open timed Pomodoro fails with "finish the current Pomodoro first"; #name=<X> needs an untimed open placeholder or creates a started entry; no-name with Q starts Q (it must be an untimed open placeholder); no-name without Q uses the first open untimed placeholder or creates an unnamed started entry. Every started entry moves, with its child block, to the current slot: right after the last completed Pomodoro's complete block, otherwise before the first other open Pomodoro.

With BOB_NOW=2026-07-10 09:02:00 and a ledger holding completed PLAN, open BUGS (with [[sase#^deep-fix]] plus child notes), and an open unnamed entry, while sase.md holds [*] ^deep-fix, [/] ^outline, and [ ] ^ready:

Successful JSON reports kind "pomodoro_link" with text: "", the post-image task_line, placement: "linked", the task-toggle vocabulary (block_id, day_file, block_link, previous_task_line, previous_status_symbol / _name, status_symbol / _name, status_changed, removed_scheduled, schedule_log when written, pomodoro_name, creates_pomodoro), pomodoro_link_action ("linked", "moved", or "already_current"), pre-image pomodoro_link_source (only when a link existed), post-image pomodoro_link_destination, pomodoro_link_placement (when a link was inserted or moved), and the exact pomodoro_start object pomodoro_task uses (only with =<X>). It emits no toggle_direction/toggle_behavior. When the guard consumes the gesture, JSON uses the additive kind "link_guard", omits block_link, creates_pomodoro, pomodoro_link_action and its endpoints, pomodoro_link_placement, and pomodoro_name, and reports link_guard (reasons, promoted, detail). When existing live links are removed, top-level removed_pomodoro_links and day_file report the cleanup; neither field is copied into the nested link_guard object. With no cleanup, both fields are omitted. This neutral kind lets older clients show a generic preview instead of a false link confirmation; newer clients can render the guard details. Any live links removed from today's open Pomodoros appear in the batch-level pomodoro_blocks diff. Human output says not linked and reports the guard detail without a generic capture confirmation. Successful human output follows the Ensure Next style: a link/would link or start/would start header, a status line ([ ] → [*], [*] already Next, [/] stays In Progress), a ledger line (Linked … under BUGS, Moved Task Link BUGS → FOCUS (created FOCUS), Task Link already in BUGS; no ledger change., or the ⛔ not linked (…) · promoted … guard sentence), and the existing start phrasing.

Picking any open task with ':'¶

Type : at the very start of an input to fuzzy-search linkable open tasks (Ready [ ], Blocked [?], Next [*], or In Progress [/]) in the routable inbox, area, and non-terminal project notes listed by bob capture-targets. Nested notes, reference notes, untyped notes other than the inbox, and terminal projects are outside this catalog. An ID-less row requires the explicit Add block ID action before it can be accepted. Accepting an identified row replaces the : query with the canonical @route:block-id link, which captures exactly like a typed link: as-is it links the task, and with a trailing = it also starts that session. Acceptance edits the draft; submitting it performs the vault write. A : query is only ever a picker query — it is never executable and never a third spelling of the link.

An item is a task-link query exactly when it has one physical line and that line (ignoring leading and trailing whitespace) is a single whitespace-delimited token starting with :. The token is the sigil plus a query of any non-whitespace characters, possibly empty. Each item of a blank-line-separated batch draft is judged alone, so bulk linking works, and a @@ declaration never applies to a query item.

bob capture (and --dry-run) rejects a claimed item before any other item parser, so the whole batch rolls back and forced flags change nothing. The teaching errors keep the usual capture item K starting on line L: … prefix. T1 reads `:dee` opens the task picker; pick a task to insert its `@<route>:<block-id>` link, or write the link yourself (for example `@sase:deep-fix`). T2 applies when ^ plus the query parses as a complete caret link, and reads `:sase:deep-fix=` opens the task picker; to link that task, write `@sase:deep-fix=`. A finished query can never silently become a junk inbox task.

Only statuses the link path accepts are listed: Ready [ ], Blocked [?], Next [*], and In Progress [/]. Notes are the capture-targets set: the inbox (when the file exists), area notes A→Z, then non-terminal project notes A→Z. Done, canceled, and unknown statuses are excluded, as are notes in terminal projects and untyped vault-root files.

Groups, in precedence: queued (an identified task whose dedicated [[route#^id]] link sits under an open Pomodoro today), in_progress, next, and note (everything else). The empty query keeps the canonical order: queued in ledger order, then in_progress and next each by route then line, then note tasks in targets order and document order. Ranking splits the query into lowercase whitespace-separated terms that must all match over route:block-id, the block ID, the text, the route, the section, and the Pomodoro name — field prefix first, then word prefix, substring, and in-order subsequence — with ties keeping the canonical order.

Tasks without a block ID always list, with requires_block_id: true, an empty replacement clients must never insert, and up to 3 deterministic block_id_suggestions that are free in that note (for example Fix flaky gkeep test suggests fix-flaky-gkeep). Name one with bob capture-task-id --route sase --task-ref <ref> --block-id fix-flaky-gkeep using the candidate's route and ref, then capture the link with an optional = as usual. Linking retires a single future [scheduled::YYYY-MM-DD] exactly like a typed link; candidates flag that with pulls_forward: true and the scheduled date.

Going to a task with '/'¶

Type / as the whole capture draft to fuzzy-search the same catalog : uses: linkable open tasks (Ready [ ], Blocked [?], Next [*], or In Progress [/]) in the routable inbox, area, and non-terminal project notes listed by bob capture-targets, as described in Picking any open task. Picking a row opens that task in Obsidian at its home note — caret at column 0, line centred — instead of inserting a link. Go To never writes: no block-ID minting, no freshness stamps, no lane changes, no ledger edits, no walk moves, no Task Card opens, no completions.

A draft is a Go To query exactly when the whole draft is one whitespace-delimited token starting with / and holding no second /. The token is the sigil plus a query of any non-whitespace characters, possibly empty. Unlike :, the claim is per draft, not per item.

bob capture (and --dry-run) refuses a claimed draft before any other item parser — before the & dependency scan, and so before the : refusal — so the whole batch rolls back and forced flags such as -r and -s change nothing. No vault file changes. The teaching error (T3) keeps the usual capture item 1 starting on line L: … prefix and reads `/dee` opens the Go To picker; pick a task to open it in Obsidian — it never captures (the quoted token is the exact typed token, so a bare / reads `/` opens …).

bob capture-parse reports a claimed draft as mode incomplete needing task_goto, with one interactive_placeholder span over the whole token, sigil included, and no diagnostics. bob capture-complete serves context task_goto: the same rows and order as task_link for the same query, including ID-less rows (every row opens directly) and the inbox. Each candidate carries replacement (always ""; clients never insert it), ref (<line>:<digest>), route, note_kind, note_path (the exact vault-relative path with extension), target (the absolute path, bob_dir.join(note_path)), nullable block_id, status_symbol, status_name, status_type, text, nullable section, depth, 1-based line, group, nullable scheduled (context only), nullable pomodoro, and task_kind (omitted when absent). There is no requires_block_id, block_id_suggestions, or pulls_forward. The query is the token text between the sigil and the cursor (empty at or just after the sigil); the replacement covers the whole token, sigil included, so refetching at replacement.start returns the unfiltered list. The response carries no query field and no picker descriptor, exactly like task_link. Human rows read [status] text · note_path:line, with · scheduled YYYY-MM-DD whenever the task carries a scheduled date; the shell format yields no rows, because nothing is insertable. The navigation itself runs through bob-navigation-hotkeys' obsidian://bob-goto-task URI, whose contract is in the Go to task URI reference.

Choosing a parent task with +¶

Type + at the start of an otherwise empty item, or after a space at the end of a capture line, to search the same task catalog as the : picker. Typing letters before the picker response arrives seeds the search, so +bank finds matching tasks. A terminal + in prose such as Call the bank + appends the selected task marker to that line; a leading + in a fresh item produces the marker by itself. The selector is unresolved input: bob capture refuses it until an editor replaces the token with an identified @route+block-id marker.

The picker searches open Ready, Blocked, Next, and In Progress tasks in the routable inbox, area notes, and non-terminal project notes. It uses the full capture-target catalog across notes; it does not search arbitrary nested or unroutable notes, or closed tasks. Results keep the : picker order and ranking, including ID-less tasks. An ID-less row has no insertable replacement; accepting it explicitly opens the stale-safe Add block ID flow. After a successful capture-task-id --route assignment Bob returns a parent_replacement such as @sase+fix-flaky-gkeep for the editor to insert. Choosing an identified row only prepares the draft: a body-bearing marker appends a note under the task, while a solo marker keeps the existing Ensure Next behavior.

The exact lone + is dual-use. Editors offer the task picker and show the Escape hint to extend the running Pomodoro by five minutes. Escape preserves the draft, so submitting + still performs that existing adjustment. Numeric adjustments (+N), double-plus shifts (++N), and numeric near misses remain Pomodoro operators. A prose-terminal + is always a task selector. Shell completion lists only identified @route+block-id rows and never assigns an ID or writes the vault.

Adding prerequisites with '&'¶

&note:block-id means "the task I am capturing or explicitly targeting depends on the task at note.md / ^block-id". It adds a plain task dependency link (normally [[note#^block-id]]) to the dependent's managed ⛓️ **DEPENDS ON:** child line (see docs/task-dependencies.md). The note is a vault-relative identity, not a capture destination: simple root notes use &foo:bar, nested notes use &projects/foo:bar, and notes with whitespace or reserved punctuation use a quoted component such as &"Shopping List":bar (inside quotes only \" and \\ are escapes; case and Unicode are preserved). Block IDs keep Bob's existing rules. The note component is extensionless, like current routes; an explicit relative path resolves first, otherwise a unique basename. Absolute paths, empty components, and ./.. are rejected.

Modifiers sit at the leading or trailing marker positions of the parent line, interleaving with destination, schedule, priority, and clipboard markers in either order, or close an authored child line (a child holding only modifiers contributes no empty bullet). Both runs skip the same trailing-transparent marker shapes (@…, #…, s:, $/$<N>, schedule, priority, and clip tokens), so @cash &foo:bar Buy milk is a dependency on a cash.md task, not literal text. An explicit @route+task-id selects the existing parent even with child-bullet text; a bare solo @route:task-id alongside modifiers is a narrow alias for the same owner. Without &, both spellings keep their existing link/toggle meanings.

capture-parse reports each modifier in per-item dependencies (raw, decoded note and block_id, sigil-inclusive range) with dependency_sigil, dependency_note, and dependency_block_id spans, plus dependency_target (new_task or existing_task ownership). A complete dependency-only action reports mode task_dependency; new-task and sub-bullet captures keep their mode and gain the modifier fields. Frozen v1 examples (schema version 1, additive fields only):

// bob capture-parse -f json -- 'Buy Groceries! @home &foo:bar &cash:budget'
{
  "body": "Buy Groceries!",
  "mode": "task",
  "route": "home",
  "needs": [],
  "dependencies": [
    {
      "raw": "&foo:bar",
      "note": "foo",
      "block_id": "bar",
      "quoted": false,
      "range": { "start": 21, "end": 29 }
    },
    {
      "raw": "&cash:budget",
      "note": "cash",
      "block_id": "budget",
      "quoted": false,
      "range": { "start": 30, "end": 42 }
    }
  ],
  "dependency_target": { "kind": "new_task", "route": "home" }
}

// bob capture-parse -f json -- '&foo:bar @body+excercise'
{
  "body": "",
  "mode": "task_dependency",
  "route": "body",
  "block_id": "excercise",
  "needs": [],
  "dependencies": [
    {
      "raw": "&foo:bar",
      "note": "foo",
      "block_id": "bar",
      "quoted": false,
      "range": { "start": 0, "end": 8 }
    }
  ],
  "dependency_target": {
    "kind": "existing_task",
    "route": "body",
    "block_id": "excercise"
  }
}

capture-complete serves context task_dependency with a replacement range covering exactly the active modifier (sigil and quoted note included), the decoded query, the lexical owner, and the vault-wide candidate list:

// bob capture-complete -b VAULT -c 19 -f json -- 'Buy Groceries! &foo'
{
  "cursor": 19,
  "replacement": { "start": 15, "end": 19 },
  "context": "task_dependency",
  "candidates": [],
  "query": "foo",
  "owner": { "kind": "new_task", "text": "Buy Groceries!" }
}

The discovery scan lists every task-bearing vault note — untyped root notes, nested folders, ref notes, terminal projects, daily notes, hidden tasks, and completed/cancelled/archive history — excluding only dot-directories, _templates, _generated, _conflicts, fenced code, and non-task block anchors. It never requires today's ledger file. Empty-query order is same-note open tasks, In Progress, Next, other open tasks grouped by note, then completed/cancelled history, with hidden tasks last within their section; queries rank with the same tiered AND-term matcher as the : picker (task text, exact note locator, block ID, path, section) and keep completed history findable behind open matches. Each row carries the exact note_path (with extension, never a lowercased route), display locator, stable group, already_dependency, and optional disabled_reason; ID-less rows carry requires_block_id with suggestions and no insertable replacement, and self/already-selected/duplicate-ID rows stay visible with their guard reason. Refetching at replacement.start returns the unfiltered snapshot.

Contract status: parsing, spans, needs, completion ranges, the candidate wire shape, and the discovery scan are frozen above, and bob capture executes the modifiers through the staged batch writer: the dependent gains (or merges into) the managed ⛓️ **DEPENDS ON:** child line plus the derived [dependsOn:: …] field, open prerequisites flip it to [?] Blocked, existing dependents are freshness-stamped, and repeats are idempotent (0 added). Each added prerequisite's 🧱 **BLOCKS:** line is staged in the same batch (the dependent's minted ^id when it has none), reported as blocks_line_updates plus minted_dependent_block_id when a mint happens; the prerequisite is reported as a dependency_target task block (task-dependencies.md §14). Multi-note batches plan every note before writing anything; a failed preimage check or write aborts the batch and rolls back notes already staged, and dry runs plan through the same planner without touching the vault. A draft with prerequisites never captures without them. Section bullets, project/note constructions, Pomodoro ledger links, and session operators reject the modifiers with a targeted diagnostic, as do suffixed (#name, =…) or !-toggled dependency-only owners; missing notes, missing block IDs, self-dependencies, and batch cycles fail with an actionable error and leave the vault intact.

& aimed at a project's ^prj writes the same Depends-On line and field, plus the project side effects (docs/task-dependencies.md §13.10): targets inside the same project note refuse (a project cannot wait on its own tasks), while pre-existing hand-authored same-note links stay on the line unprojected. When any target is open, ^prj and every open resident flip to [?] in the same write, residents gain exactly one #prj_is_blocked, and their live links leave today's open Pomodoros. Open prerequisites rise to at least the strongest lane among ^prj and its residents — never onto a ^prj target, which the walk passes through to that project's own prerequisites. More generally, any & that leaves its dependent Blocked consumes that dependent's live links in the same write. Capture consumption is one shared path for &, *, and the link-guard Consume branches: match by identity, keep authored notes under a consumed link-only bullet, delete only Pomodoro entries this capture emptied, and report consumed_links[] plus removed Pomodoro blocks (Blocking existing tasks with '*'; task-dependencies.md §13.5, PDL8–PDL11). Reconcile and plugins keep removing the whole subtree (PDL7). Human output prints the structured − consumption lines and suppresses the legacy removed N live Pomodoro link(s) to newly Blocked task(s) warning string, which still appears in warnings[] for older clients.

A successful & item always carries dependency_update and dependency_updates[] (the array's first entry equals the singular field, with role: "dependent"). See Dependency updates and consumed links.

Blocking existing tasks with '*'¶

Obsidian's existing-task twin is the reverse Blocks stage, documented in task-dependencies.md §15.

*note:block-id is the dual of &note:block-id. Let N be the item's task (new, or an existing owner) and T the task named with *. Arrows mean "depends on":

The edge lives only on T's ⛓️ **DEPENDS ON:** line, and N's 🧱 **BLOCKS:** line is the usual generated mirror. No new data model, field, or tag is added. * shares &'s ownership rules (resolve_execution_ownership, @@ inheritance, forced --task/--route), child-line trailing runs, and rejections. Quote * on the shell, because zsh globs it: bob capture 'Ask Kelly *job:cleanup'.

Grammar¶

* is a directive only when all of these hold:

1. Placement. It starts a whitespace-delimited token in the parent line's leading run or in any line's trailing run, exactly where & is allowed. A mid-line *foo:bar stays body text. Both runs skip the is_trailing_transparent marker shapes (@…, #…, s:, $/$<N>, schedule, priority, and clip tokens).
2. Next byte. The byte after * is neither whitespace nor *. This keeps **bold**, * bullet, and 5 * 3 literal.
3. Rest of the token. The rest of the token contains no *, which keeps *urgent* literal. validate_note rejects * in the note component for both sigils, since Obsidian file names cannot contain it (&no*te:id and *no*te:id are invalid).
4. Bare *. A bare * is a directive (it opens the picker) only as the last token of a line that has other text before it. A line-initial * is always literal or a list marker. This differs from &, whose bare form also works as the first parent token.
5. Escape. \* escapes it, but only where an unescaped token would have been a directive under rules 1–3. Elsewhere \* stays verbatim Markdown.

Rejections:

• Whole-item x*… / x* are close park operators. ==* is not a close and teaches x*. Link suffixes keep =x*….
• Session operators, +N/-N, section bullets, project-note construction, ! completions, --task-ref pickers, and suffixed owners reject * exactly as they reject &. Error text names the sigil the user typed. A claimed ! keeps precedence (!sase:x *foo stays the bang teaching error).
• @route:id=x… *T and <text> @route:id=x… *T are also rejected: closing and blocking in one item is incoherent. Capture the close first, then N *T as a separate blank-line item.

Parse vectors STP are the rows of this table plus those extras. capture-parse reports each * modifier in per-item and top-level blocked_tasks (raw, decoded note and block_id, quoted, sigil-inclusive range) with blocked_task_sigil, blocked_task_note, and blocked_task_block_id spans. Never put a direction flag on dependencies[]. A complete existing-owner action reports mode task_dependency; new-task and sub-bullet captures keep their mode and gain the blocked_tasks fields. A partial * needs blocked_task. A complete * with no owner needs dependency_target, the same need & uses. Frozen v1 examples (schema version 1, additive fields only):

// bob capture-parse -f json -- 'Ask Kelly *job:cleanup *job:send-batch'
{
  "body": "Ask Kelly",
  "mode": "task",
  "route": null,
  "needs": [],
  "blocked_tasks": [
    {
      "raw": "*job:cleanup",
      "note": "job",
      "block_id": "cleanup",
      "quoted": false,
      "range": { "start": 10, "end": 22 }
    },
    {
      "raw": "*job:send-batch",
      "note": "job",
      "block_id": "send-batch",
      "quoted": false,
      "range": { "start": 23, "end": 38 }
    }
  ],
  "dependency_target": { "kind": "new_task" }
}

// bob capture-parse -f json -- '*job:cleanup @bob+ask-kelly'
{
  "body": "",
  "mode": "task_dependency",
  "route": "bob",
  "block_id": "ask-kelly",
  "needs": [],
  "blocked_tasks": [
    {
      "raw": "*job:cleanup",
      "note": "job",
      "block_id": "cleanup",
      "quoted": false,
      "range": { "start": 0, "end": 12 }
    }
  ],
  "dependency_target": {
    "kind": "existing_task",
    "route": "bob",
    "block_id": "ask-kelly"
  }
}

capture-complete serves context blocked_task with a replacement range covering exactly the active modifier (sigil and quoted note included), the decoded query, the lexical owner, and the open-editable candidate list:

// bob capture-complete -b VAULT -c 13 -f json -- 'Ask Kelly *jo'
{
  "cursor": 13,
  "replacement": { "start": 10, "end": 13 },
  "context": "blocked_task",
  "candidates": [],
  "query": "jo",
  "owner": { "kind": "new_task", "text": "Ask Kelly" }
}

Rows reuse the DependencyCandidate shape, plus already_blocked (omitted when false) and disabled_reason:

• the owner task itself
• would create a dependency cycle
• a project cannot depend on its own resident
• the existing duplicate-block-ID reason

The pool is open, editable tasks only: refuse daily notes, done/, _templates, _generated, _conflicts, dot-directories, and fenced code. With an empty query, ranking is (1) today's linked tasks (the running entry's first), (2) Pending [/], (3) Next [*], (4) the owner's note, (5) everything else. With a non-empty query, ranking is match score first, then the same order. Replacements use * (replacement_for_sigil). Shell completion adds a blocked tasks group.

Execution¶

The whole draft plans before anything is written. For an item with blocked_tasks:

1. Resolve and check every target. Dedupe by resolved identity. The note resolves vault-wide exactly like &note: path or basename, nested, quoted, plus staged notes. T must be an open, editable task. Refuse targets in daily notes, done/, _templates, _generated, _conflicts, dot-directories, or fenced code. Also refuse a self target; a T with several or malformed Depends-On lines; and a ^prj T when N lives in that project's note or a descendant project (a guaranteed deadlock). A repeat is a no-op reported as already_present.
2. Give N a block ID. Use the typed ^id or :id. Otherwise mint one with this batch's reservations, even when dependencies.blocks_lines: false. When the ID was minted, report it as minted_blocker_block_id. Never reuse minted_dependent_block_id, which means the opposite (&'s BLOCKS mirror for N-as-dependent).
3. Plan N as today. N's own & prerequisites come first, so N may be born [?]. Insert N and stage its Task Link if :id/#pomodoro asked for one and the existing link guard allows it. This is the "link N, then consume T" order: N @mac_inbox:id *T keeps the session alive by putting N into T's slot before T's link is consumed.
4. Run one writer pass per T, in typed order. Each pass is the existing-dependent writer with dependent = T (vault path plus block ID) and prerequisites = [N]. It merges the line and fields, stamps T fresh, flips T to [?], blocks and tags ^prj residents, consumes links, and stages N's BLOCKS line. Commitment transfer: an open N rises to T's pre-capture lane (for a ^prj T, the strongest resident lane), capped at Next [*] when N is new in this capture. The cap applies to the whole promotion walk that this pass seeds. An existing owner gets the normal §5 transfer and may become [/]. A ^prj N is never raised. Re-locate N by block ID after every pass.
5. Existing owners go through the dependency-only path. The sub-bullet path (Note text @route+id *T) and forced --task/--route mirror &.
6. Cycles. Direct, transitive, cross-item, and &+* cycles are refused; the vault stays byte-identical.
7. Later link gestures. A later @T:id in the same batch drops N from T's line under capture's own-prerequisite drop. That is intended, and the final preview reports it accurately. Capture does not auto-link N into T's slot; the explicit N @mac_inbox:id *T idiom covers it.

Capture consumption¶

Every capture path that consumes live links (plan_existing_task_dependencies, plan_resident_block, and the link-guard Consume branches) follows this contract. Reconcile and plugins are unchanged (PDL7).

• Scope. Only live (unstruck) Task Links under today's open Pomodoros (running and planned), every occurrence. Closed entries, 🍅 history, other days, prose outside ## Pomodoros, and dependency lines are never touched. A missing day file means there is nothing to consume.
• Identity. Match by resolved (vault-relative path, block id), not by text. Aliases (|x), [[#^local]], basename, path, and case spellings all match.
• Notes kept (PDL8). A consumed link-only bullet with children is not deleted. Its link token is replaced by the task's clean display text: the same text capture reports, with checkbox, tags, inline fields, and ^id stripped, and any [[…#^…]] inside it flattened to plain text. The marker, indentation, and children stay unchanged, and the bullet carries no Task Link. A childless link-only bullet is deleted. A prose bullet loses only the token (PDL6).
• Only entries this capture emptied (PDL9). "Pomodoro" means the column-0 entry, never the ## Pomodoros heading. An entry is deleted only if it had a child list item before this consumption and has none after it, judged after all of the item's edits. That includes a running timed entry. Entries that were already childless stay.
• Reported (PDL11). Each consumed link becomes a consumed_links[] row. Each deleted entry appears in pomodoro_blocks with removed: true. Human output names the session. The legacy warnings[] consumption string stays for older clients; human output prints the − lines instead, so the same fact is never printed twice.

Human output¶

These lines are from a real ST3 capture; the final plan-budget footer is omitted because its limits come from local configuration.

✓ captured  mac_inbox.md
  - [*] #task Ask Kelly for references! [created::2026-10-14] [id:: mac_inbox__ask-kelly-references] ^ask-kelly-references
  🧱 blocks "Do cleanup tasks!"  job.md ^cleanup  [/] → [?] Blocked
  − removed its Task Link from JOB 10:10–10:35 (running) · deleted the empty Pomodoro

Variants:

• − kept its notes under JOB 10:10–10:35 as plain text
• · blocked 4 project tasks for a ^prj T (dry run: · would block 4 project tasks)
• would … in dry runs (🧱 would block "…", 🧱 would now block "…")
• A typed duplicate * target is skipped; a repeat that adds nothing prints 🧱 already blocks "Cleanup" job.md ^cleanup with no status arrow, live and dry-run
• Existing-owner items use the update header and owner status row, then print one relationship row per target; for example ✓ updated body.md, [/] → [?] Exercise ^excercise, and 🧱 now blocks "Do cleanup tasks" job.md ^cleanup [*] → [?] Blocked. Dry runs use would update / would now block.

& consumption prints the same − lines.

Selected fields from the real ST3 bob capture -f json result are shown below; the absolute target path and unrelated fields are omitted. The created and [id::] properties are part of the emitted task line.

{
  "ok": true,
  "kind": "task",
  "text": "Ask Kelly for references!",
  "relative_target": "mac_inbox.md",
  "block_id": "ask-kelly-references",
  "task_line": "- [*] #task Ask Kelly for references! [created::2026-10-14] [id:: mac_inbox__ask-kelly-references] ^ask-kelly-references",
  "dependency_update": {
    "role": "blocked_task",
    "dependent_note": "job.md",
    "dependent_block_id": "cleanup",
    "dependent_text": "Do cleanup tasks!",
    "new_task": false,
    "added": 1,
    "already_present": 0,
    "open_prerequisites": 1,
    "prerequisites": [
      {
        "note": "mac_inbox.md",
        "block_id": "ask-kelly-references",
        "link": "[[mac_inbox#^ask-kelly-references]]",
        "status_symbol": " ",
        "status_name": "Todo",
        "text": "Ask Kelly for references!",
        "open": true
      }
    ],
    "dependent_status": "?",
    "dependent_status_name": "Blocked",
    "status_changed": true,
    "previous_status": "/",
    "previous_status_name": "In Progress"
  },
  "dependency_updates": [
    {
      "role": "blocked_task",
      "dependent_note": "job.md",
      "dependent_block_id": "cleanup",
      "dependent_text": "Do cleanup tasks!",
      "new_task": false,
      "added": 1,
      "already_present": 0,
      "open_prerequisites": 1,
      "prerequisites": [
        {
          "note": "mac_inbox.md",
          "block_id": "ask-kelly-references",
          "link": "[[mac_inbox#^ask-kelly-references]]",
          "status_symbol": " ",
          "status_name": "Todo",
          "text": "Ask Kelly for references!",
          "open": true
        }
      ],
      "dependent_status": "?",
      "dependent_status_name": "Blocked",
      "status_changed": true,
      "previous_status": "/",
      "previous_status_name": "In Progress"
    }
  ],
  "consumed_links": [
    {
      "day_file": "2026/20261014.md",
      "line": 3,
      "link": "[[job#^cleanup]]",
      "note": "job.md",
      "block_id": "cleanup",
      "text": "Do cleanup tasks!",
      "action": "removed",
      "pomodoro": {
        "line": 2,
        "name": "JOB",
        "time_range": "1010-1035",
        "status": "running",
        "removed": true
      }
    }
  ],
  "minted_blocker_block_id": {
    "path": "mac_inbox.md",
    "line": 1,
    "block_id": "ask-kelly-references"
  },
  "pomodoro_blocks": [
    {
      "relative_target": "2026/20261014.md",
      "line": 2,
      "name": "JOB",
      "time_range": "1010-1035",
      "status": "running",
      "created": false,
      "removed": true,
      "roles": ["removed"],
      "lines": [
        {"text": "- [ ] (1010-1035) — JOB", "depth": 0, "change": "removed"},
        {"text": "  - [[job#^cleanup]]", "depth": 1, "change": "removed"}
      ]
    }
  ],
  "task_blocks": [
    {
      "relative_target": "job.md",
      "route": "job",
      "line": 1,
      "block_id": "cleanup",
      "text": "Do cleanup tasks!",
      "status_symbol": "?",
      "status_name": "Blocked",
      "created": false,
      "roles": ["dependency"]
    },
    {
      "relative_target": "mac_inbox.md",
      "route": "mac_inbox",
      "line": 1,
      "block_id": "ask-kelly-references",
      "text": "Ask Kelly for references!",
      "status_symbol": "*",
      "status_name": "Next",
      "created": true,
      "roles": ["dependency_target"]
    }
  ]
}

dependency_update equals dependency_updates[0]. For N *T that is T's update (dependent T, prerequisites [N]), which older Mac builds already render as a dependency on T. &-only items carry the array too, with role: "dependent". blocked_residents is omitted when 0. consumed_links[].action is removed, token_removed, or notes_kept. line values are 1-based in the item's pre-state day text. Execution vectors ST1–ST19 live in task-dependencies.md §13.5.2.

Relating existing tasks with '&' and '*'¶

& adds a prerequisite to the item's owner; * makes the named task depend on that owner. When the item has task text, that text creates the owner. When it has no task text and names an existing task, that existing task is the owner. An existing owner is edited in place and is never recreated as a new bullet.

The aliases stay narrow: @route:id and ^route:id name an owner only when used bare with relationship modifiers. Without & or *, their existing Pomodoro-link behavior remains unchanged. &, *, ~, and ~~ are all relationship modifiers: the first two change status and lanes, while ~ / ~~ only write inert relation lines (Linking tasks with '~' and '~~'). The familiar two-item form still keeps a blocked task in a session while it takes over the blocker’s slot:

@bob:ask-kelly

@bob+ask-kelly *job:cleanup

An owner must be in a location that @route can write: the inbox, an area note, or a non-terminal project note. The prerequisite or blocked task can be anywhere in the vault. If only one task is routable, flip the relationship so that task owns it; for example, use @cash+budget *projects/house/kitchen:cabinets instead of trying to own the relationship from the unroutable project task.

Authoring flows¶

1. Choose the owner first. Type @body+ for the note-scoped picker or + for the vault-wide picker, choose Exercise, then add &foo:bar or *job:cleanup. In relationship mode, the picker explains which task will depend on or block the named task. Self-edges and cycles are disabled with Bob’s reason.
2. Choose the relationship first. Type &foo:bar or *job:cleanup, then type task text to create the owner. To use an existing owner, type + and choose it; the replacement is the canonical @route+id spelling. capture-parse reports dependency_target while the owner is missing and task_parent while the + picker is open. A draft waiting for an owner shows a dependency_target hint in Bob Mac Capture instead of a failed preview.
3. Use the current task. Pick the active task with ^, then add & or *. The resulting bare ^route:id names the owner without adding or moving a Pomodoro Task Link.

For several prerequisites or blocked tasks, the picker names the first and counts the rest, for example “Buy shoes + 1 more”. When only one relationship direction is present, the owner picker says which task will depend on or block the selected task; with both directions, it names both relationships.

Refusals¶

An unresolved + is never captured as task text. On submit it refuses with:

`+` needs a task selection; choose the task to relate before capture

Submitting a completed relationship modifier without either task text or an existing owner also refuses rather than creating a task named after the modifier. The ownerless & and * messages are:

task relationships need a dependent: add task text or '@note+task-id' for the task that should use the '&note:block-id' modifier(s)
task relationships need a dependent: add task text or '@note+task-id' for the task that should use the '*note:block-id' modifier(s)

The interactive + picker is the route for selecting an existing owner.

A relationship-only item with an existing owner edits only the Depends-On and BLOCKS lines. It cannot carry $<N>, s:<N>, %…, or authored child bullets because those need task text. Parse emits the ranged error diagnostic relationship_needs_text, and execution returns the same message. The offending token is named in the message; for example:

`$2` needs task text: `@body+excercise` with no text only adds task relationships; add text to write a sub-bullet (`Note @body+excercise &foo:bar $2`)

The same template applies to s:3, a clipboard token such as %header, and child bullets. To write a child bullet, add parent task text to the owner line, as in Waiting @body+excercise &foo:bar followed by - detail.

An existing task that is Done or Canceled cannot be the owner of *; capture refuses without changing the vault. The exact error is:

task ^old in foo.md is Done; a finished task cannot block another task (reopen it first)

The status word is Canceled for a canceled owner. Existing & closed-owner refusal wording is unchanged. Suffixed owners (#name, =…, or !) keep the existing “must be bare” refusal, since they combine relationships with a Pomodoro action.

Terminal output¶

An existing-owner relationship uses the update layout: one header, one owner status row, then one row per relationship. Status arrows appear only when the status changes. A successful live example is:

✓ updated  body.md
  [/] → [?]  Exercise  ^excercise
  ⛓ now depends on "Buy shoes"  foo.md ^bar  [ ] → [/] In Progress
  🧱 now blocks "Do cleanup tasks"  job.md ^cleanup  [*] → [?] Blocked
  − removed its Task Link from BODY 10:10–10:35 (running) · deleted the empty Pomodoro

That live example is one capture of @body+excercise &foo:bar *job:cleanup while Exercise is In Progress and linked in the running Pomodoro. The final plan-budget footer is omitted because its limits come from local configuration.

A dry run begins [dry-run] ok would update body.md; relationship rows say would now depend on and would now block. An unchanged owner row uses the toggle wording, for example [ ] stays Ready Exercise ^excercise. Repeated relationships say already depends on or already blocks, with no status arrow and no write. The existing · blocked N project tasks chip stays on 🧱 rows.

New-task owners use the same per-relationship row shape, for example:

  ⛓ depends on "Buy shoes"  foo.md ^bar  [ ] Ready

For a sub-bullet owner, output prints the bullet and its authored children first, then the relationship rows. The under row shows the parent’s final status, such as under [ ] → [?] Exercise ^excercise. Consumption continues to use the structured − rows.

Completion wire additions¶

The schema stays version 1 and these fields are additive. In capture-complete, owner gains optional text, note_path, status_symbol, and status_name fields. For an existing owner they describe the resolved task; for new_task, text is the non-empty draft body. Unresolved existing owners retain the old owner shape. Drafts without & or * keep their current JSON byte-for-byte.

// Selected fields from bob capture-complete -b VAULT -c 17 -f json -- '@body+excercise &'
{
  "context": "task_dependency",
  "cursor": 17,
  "replacement": { "start": 16, "end": 17 },
  "query": "",
  "owner": {
    "kind": "existing_task",
    "route": "body",
    "block_id": "excercise",
    "text": "Exercise",
    "note_path": "body.md",
    "status_symbol": "/",
    "status_name": "In Progress"
  }
}

When a complete &/* modifier is present in a task_parent or scoped task picker, its picker descriptor gains a relationship object. Each entry carries the typed raw marker, exact vault-relative note_path, block_id, and resolved task text; unresolved entries omit only text. Candidate rows gain disabled_reason for self-edges, cycles, and a project depending on its own resident. A disabled row has no insertable replacement, and shell completion omits it. These selected fields show the vault-wide + picker in owner mode; its self row is disabled and a cycle row uses the same guard:

// Selected fields from bob capture-complete -b VAULT -c 10 -f json -- '&foo:bar +'
{
  "context": "task_parent",
  "query": "",
  "replacement": { "start": 9, "end": 10 },
  "picker": {
    "kind": "parent_task",
    "scope": "vault",
    "scope_token": "+",
    "marker_range": { "start": 9, "end": 10 },
    "trigger_removal_range": { "start": 9, "end": 10 },
    "relationship": {
      "dependencies": [
        { "raw": "&foo:bar", "note_path": "foo.md", "block_id": "bar", "text": "Buy shoes" }
      ],
      "blocked_tasks": []
    }
  },
  "candidates": [
    { "replacement": "", "text": "Buy shoes", "disabled_reason": "the prerequisite itself" },
    { "replacement": "", "text": "Cycle candidate", "disabled_reason": "would create a dependency cycle" }
  ]
}

Conformance vectors¶

Each RX execution vector checks parsing, exact vault bytes, JSON, human output, dry-run/live agreement, and a second live run as a no-op where applicable. foo.md#^bar is Buy shoes, body.md#^excercise is Exercise, and job.md#^cleanup is Do cleanup tasks.

Completion vectors RXC check the additive wire contract:

The RXC4 JSON excerpt above freezes the relationship descriptor and guard strings. The RX8 parse shape for + &foo:bar keeps the incomplete parent selection and typed modifier, without diagnostics:

// Selected fields from bob capture-parse -f json -- '+ &foo:bar'
{
  "input": "+ &foo:bar",
  "body": "",
  "mode": "incomplete",
  "needs": ["task_parent"],
  "dependencies": [
    {
      "raw": "&foo:bar",
      "note": "foo",
      "block_id": "bar",
      "quoted": false,
      "range": { "start": 2, "end": 10 }
    }
  ],
  "diagnostics": []
}

Linking tasks with '~' and '~~'¶

~ links the item's task to another task; ~~ links another task to the item's task. Both write entries on 🪢 **LINKS:** lines and let reconcile maintain the 🪢 **LINKED FROM:** mirrors, exactly as Task relations specifies. Owners use exactly the & / * spellings: task text creates the owner, @route+id names an existing owner, @@route+id is inherited, and bare @route:id / ^route:id alias without linking. A relation-only existing-owner item uses mode task_dependency and reports relationship_needs_text, as & does.

Fix flaky capture retries ~bob_done:capture-star|"follow-up of"
Write the outline ~~sase_blog:prj|"next step"
@bob+fix-retries ~sase:retry-design|see
Fix trip ~work:foo||prompted-by

Meaning. ~note:block-id means this item's task relates to that task. ~~note:block-id means that task relates to this item's task. A label after | is phrased from the source's side (S — ‹label› → T); write |"follow-up of" for multi-word labels. Labels obey the relation label rules. A label after || is a one-off: the stored Markdown is identical to the | form, but the label hides from suggestions once the capture succeeds. Hiding a visible existing label warns with its link count; hiding an already-hidden label is a silent no-op. A failed journal append never fails the capture — it warns with the exact bob relations hide retry command instead.

Guards. A ~ / ~~ token is a directive only when it sits in the same leading or trailing run as & / *, whitespace-delimited. A mid-line ~foo:bar stays body text. The byte after the sigil is not whitespace or / (so ~/Downloads stays literal), and not a digit when the token has no : (so ~5m, ~2h, ~5pm stay literal). ~~old~~ is strikethrough, x~~1 / =~~2 teach "use one ~ list", and =~2 / x~1 keep their drop-list meaning. A third pipe is a teaching error (use || to hide a label, | to name one). \~ escapes the sigil where it would otherwise be a directive; [[…]] and backtick spans are never scanned. An unresolved bare or partial sigil refuses on submit with `~` needs a task; choose one, or write `\~` for a literal tilde.

Targets. A ~ target is any task with a block id: open, closed, any active note, a daily note, or done/. A mirror is skipped for archived and previous-daily targets. A ~~ target's LINKS line is written, so it must be editable: the refusal set is the same as *'s (daily notes, done/, _templates, _generated, _conflicts, dot-directories, fenced code). Self-relations, non-task targets, and id-less targets are refused with a teaching error.

Refusals. A relation after x is an operator_relation_error. Suffixed owners (#name, =…, !) keep the existing "must be bare" refusal. A relation-only item cannot carry $<N>, s:<N>, %…, or authored child bullets (relationship_needs_text).

Shell quoting. Quote ~ where the shell expands it (bob capture 'Fix it ~work:foo'). In zsh, ~ at a word start can glob; single-quote the draft.

Inertness. Relations never block, consume, schedule, stamp, or route anything. Fix it ~work:foo leaves every status, lane, and Pomodoro link exactly as it was, apart from a minted ^id.

Human output. Successful captures print 🪢 rows in the dependency style, for example:

✓ captured  mac_inbox.md
  - [ ] #task Fix flaky capture retries [created::2026-10-14]
  🪢 links to "Capture * blocks existing tasks" · follow-up of   done/bob_done.md ^capture-star · archived

An existing-owner rerun of the same edge reports 🪢 unchanged; a new label reports 🪢 relabeled. A one-off hide prints 🪢 hides "see" from suggestions (2 links). Dry runs say would link to / would now link here / would relabel.

JSON. Every schema_version stays 1 and every field is additive. capture-parse adds relations[] (top-level and per item), the relation_target / relation_label needs, the five relation_* span kinds, and top-level relation_grammar: 1 whenever the draft contains a ~ byte. capture-complete adds the relation_to / relation_from / relation_label contexts, with an additive relation object (direction plus the sigil-to-| range) and owner on relation_label responses. capture-task-id adds relation_to_replacement and relation_from_replacement. capture adds, per item, relation_updates[], linked_from_line_updates[], minted_relation_block_ids[], mirror_skipped[], and relation_label_hides[] ({label, key, existing_count, was_hidden, action: hide|already_hidden}, pre-capture counts, omitted when empty), plus a hides_existing_relation_label warning object ({code, label, count, message}) when a one-off hides a visible existing label. See Task relations.

Completing tasks with '!'¶

A capture item that is exactly !note:block-id marks that existing open task Done, without closing a Pomodoro. The token names the task with the same vault-wide note locator &note:block-id uses, so ! and & share one lexer, one resolver, and one replacement formatter: simple root notes use !foo:bar, nested notes use !projects/foo:bar, and notes with whitespace or reserved punctuation use a quoted component such as !"Shopping List":milk (inside quotes only \" and \\ are escapes). Single-quote the draft on shells that history-expand !: bob capture '!sase:fix-flaky'.

A complete token must be the entire capture item: no body text, children, %, s:, $<N>, #name, =…, @@, or forced destination flags. Anything extra is a teaching error, never a junk inbox task. Bulk means one ! item per blank-line-separated block; every item is planned against the same staged snapshot, and any failure rolls the whole batch back.

bob capture refuses a claimed query before any other item parser, with the usual capture item K starting on line L: prefix and exit 2: `!fix` opens the task picker; pick a task to insert its `!<note>:<block-id>` token, or write one yourself (for example `!sase:fix-flaky`). A claimed invalid item reads `!sase:fix-flaky` completes an existing task and must be the whole capture item; remove `more` (or remove its child lines), plus the targeted hints above. @@ declarations never apply to a ! item.

capture-parse (schema 1, additive) reports query items with mode incomplete, needs ["task_complete"], an empty body, and one interactive_placeholder span over the whole token, sigil included. It reports complete items with mode task_complete, block_id, three spans (task_complete_sigil over the !, task_complete_note over the note with quotes, task_complete_block_id over the ID), and the per-item task_complete object (raw, decoded note, block_id, quoted, and the sigil-inclusive range). When the draft has one item and that item is task_complete, the same task_complete object is emitted at the top level of the capture-parse result, mirroring how top-level dependencies is emitted; other drafts omit it. Claimed invalid items report mode task_complete with an invalid_task_complete diagnostic, the same mode handling invalid_pomodoro_link uses for a padded ^route:id.

Execution completes the named task through the shared task-completion engine, in this order and all against the staged batch snapshot:

1. Resolve. The note resolves exactly like &: an explicit relative path first, else a unique basename (notes staged earlier in the batch count too). The block ID resolves through the same lookup, with the same missing-with-suggestion, duplicate, and not-a-task errors.
2. Validate the status. Ready [ ], Blocked [?], Next [*], and In Progress [/] complete. An already-Done task is an idempotent no-op (action: "already_done", nothing written). Canceled and unknown statuses fail with an actionable error.
3. Refuse recurring tasks. A line with [repeat:: …], (repeat:: …), or 🔁 fails: complete recurring tasks in Obsidian so Tasks writes the next occurrence.
4. Close the tree exactly as x!N writes it: the root gets x plus [completion:: YYYY-MM-DD] (only when the line carries the global-filter tag), and embedded ![[…]] subtasks close recursively (Blocked, recurring, unknown-status, and over-cap descendants are left open and reported, never silently dropped). A Blocked descendant and everything below it stay open. Unlike x!N, the root may be Blocked.
5. Retire Task Links in today's daily note (when it has a ## Pomodoros section): every completed identity is struck, its bullets move to the running entry (else the last completed entry), emptied placeholders are removed, and a carried copy is dropped when the destination already links the task.
6. Recover dependents and offer successors. Blocked [?] dependents that name a completed task's [id::], have no other open dependency, and have no strictly future scheduled date recover to their derived rank, exactly like Task Status Cycler's Ctrl+Enter recovery. Every dependent this close fully unblocked, plus every available resident of a project whose ^prj this close unblocked and each project pull-in, is offered; only --pull-in picks are linked into the predecessor's slot and become Next in the same write, per task-dependencies.md §12. Capture never prompts and never auto-links. Picked successor links are placed before retirement runs (step 5), so retirement strikes or moves the predecessor around them and the vacated slot keeps the pick.

Status-group moves, ^prj frontmatter, #hide, and archiving stay with their existing writers (bob task reconcile, bob projects sync, and bob task archive); capture never writes them.

Worked example. Before (sase.md holds the task, today's daily note holds the link under the running CAPTURE session):

- [*] #task Fix flaky gkeep test ^fix-flaky

## Pomodoros
- [ ] (**0920-0950**) — CAPTURE
  - [[sase#^fix-flaky]]

bob capture '!sase:fix-flaky' writes - [x] #task Fix flaky gkeep test [completion:: 2026-10-05] ^fix-flaky, strikes the link in place to ~~[[sase#^fix-flaky]]~~, and prints:

✓ completed [*] → [x] Fix flaky gkeep test  sase.md ^fix-flaky
  ledger  Task Link struck in CAPTURE · 20261005.md

After, the day file reads:

## Pomodoros
- [ ] (**0920-0950**) — CAPTURE
  - ~~[[sase#^fix-flaky]]~~

Dry-run JSON equals real-run JSON except for dry_run. A dry-run excerpt for the same capture carries the additive task_complete object with its clean text and named ledger entries:

"task_complete": {
  "raw": "!sase:fix-flaky",
  "note": "sase",
  "note_path": "sase.md",
  "block_id": "fix-flaky",
  "action": "completed",
  "completion_date": "2026-10-05",
  "text": "Fix flaky gkeep test",
  "subtasks": [],
  "subtasks_left_open": [],
  "ledger": {
    "day_file": "20261005.md",
    "struck": 1,
    "struck_in": [{"line": 2, "name": "CAPTURE", "status": "running"}],
    "moved": [],
    "deduplicated": 0,
    "dropped": [],
    "removed_placeholders": []
  },
  "unblocked": []
}

The batch also carries top-level pull_in on every success (supported: true, offer_count, choice, picked_count). Dry-run JSON equals real-run JSON with the same flags, including --pull-in. To pull in numbered offers, pass -p 1,2, -p all, or -p none:

bob capture -p 1 -- '!sase:fix-apollo'

An unknown or stale pick is a teaching error that writes nothing and lists current offers. Without -p, capture recovers and reports numbered offer N rows as not pulled in.

The ledger line names entries in this order, joined with ·, and ends with the day file: one Task Link struck in <NAME> row per entry with an in-place strike ((completed) appended when that entry is completed), one Task Link moved <FROM> → <TO> (struck) row per move, one Task Link already in <TO>; dropped the <FROM> copy row per deduplicated bullet, and one removed empty <NAME> row per removed placeholder. When an entry has no name, JSON carries "name": "" and the human line uses line N. Other variants from the same vocabulary:

  ledger  Task Link struck in PLAN (completed) · 20261005.md
  ledger  Task Link struck in SASE · Task Link moved SASE → CAPTURE (struck) · removed empty SASE · 20261005.md
  ledger  Task Link already in MORNING; dropped the SASE copy · removed empty SASE · 20261005.md

Refusals leave the vault byte-identical. Each failure prints bob capture: capture item K starting on line L: <message>; usage errors exit 2 and I/O-class errors exit 1:

Routing inbox tasks out¶

When a capture changes the checkbox of an existing task in inbox.md or a direct area child of inbox.md, bob reports it so a client can ask where the task should go. This comparison runs after the whole batch and successor recovery have been planned. It includes completions and other status changes caused indirectly by the batch. Edits to fields or children alone do not count. A nested status change reports its column-zero #task ancestor, since that is the block a move carries. New tasks, ^prj tasks, tasks in projects under an inbox area, and untyped notes under an inbox are not candidates.

Detection vectors (IR) run against a sandbox vault:

Apply vectors (IRA) answer the candidates with -i/--inbox-route:

Every successful capture JSON, including dry runs, carries inbox_route:

"inbox_route": {
  "supported": true,
  "candidate_count": 1,
  "routed_count": 0,
  "kept_count": 0,
  "candidates": [{
    "key": "mac_inbox.md#^route-task",
    "n": 1,
    "note_path": "mac_inbox.md",
    "inbox": "mac_inbox",
    "block_id": "route-task",
    "line": 8,
    "text": "Prepare the handoff",
    "previous_status_symbol": " ",
    "previous_status_name": "Ready",
    "status_symbol": "*",
    "status_name": "Next",
    "answer": null,
    "outcome": "pending"
  }],
  "destinations": [{
    "relative_path": "areas/health.md",
    "route": "areas/health",
    "label": "health",
    "kind": "area",
    "status": null,
    "parent": null,
    "blocked": false
  }]
}

Candidates are numbered by note path and original line. A task with a block ID uses path#^id as its key; an id-less task uses path@<sha8> and adds a ~N suffix when the display-text digest repeats in that note. Treat keys as opaque. Candidate status symbols and names describe the task block that would move. block_id is an empty string when the candidate has no block ID.

destinations is omitted when there are no candidates. It lists routable area notes and wip or waiting projects, sorted by vault-relative path. Inbox notes and notes under done/, _templates/, and _conflicts/ are excluded. Each row includes the resolved parent label when available and whether the destination's ^prj task is Blocked.

bob capture never opens a picker. Bob Mac Capture uses this report to ask, then submits the selected route with the capture. Its hidden --require-inbox-route-choice guard returns exit 1 with code: inbox_route_choice_required and the same inbox_route payload when a candidate has no answer; it writes nothing. The pull-in choice refusal runs first, so clients resolve successor offers before inbox routes.

Answer candidates with repeatable -i, --inbox-route ANSWER:

• <N|KEY>=<NOTE> moves the candidate to NOTE (a stem or vault-relative path, resolved like bob task move's DEST, and required to be in the destination set).
• <N|KEY>= keeps the candidate in its inbox.
• keep keeps every candidate not otherwise answered.

Two different destinations for one candidate are a usage error (exit 2). An answer naming an N or KEY that is not a current candidate fails with exit 2 and code: inbox_route_stale, listing the current candidates exactly as -p does for stale picks; it writes nothing. An answer whose destination does not resolve or is refused fails with exit 1 and code: inbox_route_refused, adding refused (key, n, destination, message) beside inbox_route; it writes nothing. Conflicting answers, stale answers, and refusals never write. Without the guard flag, unanswered candidates stay where they are and the real run still succeeds with outcome: pending.

Answered moves run as a new stage inside capture planning: after every item, the successor net post-pass, and candidate detection, and before the task and Pomodoro block trackers finish. The capture acts first, then moves each answered candidate through the bob task move engine (--inbox-route is the only caller that moves closed selections or selects by exact line) in one atomic batch: a full vault snapshot overlaid with the staged texts, per-group move plans, the freshness stamp on each moved root line, and the same link repair, collision renames, and preimage guard as any other batch write. A moved open task is stamped [fresh:: today] like a Ctrl+Shift+M move; a moved Done task is never stamped.

The move updates the batch outputs to their final, post-route text. answer becomes {"action": "move", "destination": "<relative_path>"} or {"action": "keep"}; outcome becomes moved or kept. A moved candidate gains moved (destination, line, block_id, previous_block_id, fresh, which is the stamped date or null). Once a move is applied, inbox_route also carries repaired_files (path, link_count, dependency_token_count), renamed_block_ids (path, old_block_id, new_block_id), and needs_reconcile. A routed task's task_blocks entry follows it to the destination path and its final lines and block ID, and an open_notes entry that would land on a routed task opens the destination at the moved line instead.

The human output prints one inbox row per pending candidate and a route hint, one kept <text> · still in <inbox> row per kept candidate, and one routed <text> <inbox> → <route> row per moved candidate, with · ^old renamed ^new and · N links repaired suffixes when they apply. In dry-run output the rows say would route; ordinary previews never write. The run 'bob task reconcile' to reconcile Blocked state hint prints when needs_reconcile is true.

Plan budget and strict mode¶

When a batch changes today's Pomodoros section, the result carries a top-level plan_budget with before/after meters (dry-run and real runs use the same planner, so they agree). It is never per item, and it is omitted when the ledger is unchanged:

"plan_budget": {"status": "over",
  "themes": {"count": 4, "cap": 3, "over": true, "before": 3},
  "links": {"count": 8, "cap": 10, "over": false, "before": 7},
  "added_themes": ["BOB"],
  "added_theme_refs": [{"key": "bob", "name": "BOB", "hue": "magenta",
    "hue_source": "hash"}],
  "warnings": [{"code": "plan_theme_cap_exceeded",
    "message": "today's plan now has 4/3 themes (adds BOB); queue it with ^ or defer with $<N>"}]}

Warnings fire only for plan_theme_cap_exceeded and plan_link_cap_exceeded, and only while the batch grows that meter past its cap (after > cap and after > before). A capture that leaves an over-cap plan alone stays quiet. Human output prints one meter line after the result (plan 4/3 themes · 8/10 links (+1 theme: BOB)) and one bob capture: warning: … stderr line per fired warning; the warnings never join the item warnings array. An invalid plan config skips the budget and pushes one plain string into warnings instead.

added_theme_refs is ordered with added_themes. Human Task Link destinations add a colored square before each known, non-exempt component when stdout is a color terminal; NO_COLOR keeps the existing destination text unchanged.

With plan.strict: true, the whole batch is refused, atomically, when a non-start item creates a new named Pomodoro entry past the theme cap (<text> @r:id#NAME, @r^id+#NAME project notes, @r+id#NAME toggles, and any other non-start creation path). Session starts and overrides (=, =<X>#NAME, #NAME=, and link starts) are never refused. A named start that creates a theme still reports plan_budget and the cap warning. The refusal is an I/O-class error (exit 1) whose JSON carries a machine-readable code:

{"ok": false, "error": "refusing capture: today's plan would grow to 4/3 themes (adds BOB); …", "code": "plan_theme_cap_exceeded"}

code appears on this refusal and on pull_in_choice_required (§12.14 when --require-pull-in-choice is set, offers exist, and no --pull-in was given); every other capture failure omits it.

Every pomodoro_link_destination carries a role naming how the entry was chosen: current (the running timed entry), next_up (implicitly chosen and not running), named (an existing entry matched by #NAME), or created (a new entry). New <text> @route:id[#NAME] Pomodoro-task captures report pomodoro_link_destination, pomodoro_name, and creates_pomodoro too, and human output names the landing spot: → into running GOALS (0945-1015), → under GOALS (next up), → under GOALS (named), or → new Pomodoro BOB. In the pomodoro_name completion context, creates_pomodoro rows preview the result with plan_themes_after and plan_themes_cap, omitted when the daily note or the plan config is unavailable. In the pomodoro_start_name context, the new and again rows carry plan_themes_after and plan_themes_cap too.

Starting the next Pomodoro¶

Capture a whole item =/=<X> to start today's next future Pomodoro now:

bob capture '='
bob capture '=3'
bob capture '=-2'
printf 'x\n\n=\n' | bob capture

Pomodoro sessions form a lifecycle, taught in this order:

Mnemonic: "= starts the next session — or restarts the running one; =name starts that one — or swaps it in; x stops the running one."

Recognition: let t be the item's first physical line trimmed of leading and trailing whitespace (the token after a chain split; see Chaining session operators on one line). A start token is = followed by the longest run matching the se<X> suffix grammar [0-9]*(-[0-9]*)?. A token is bare when its suffix is empty or contains no digit (=, =-) and counted when its suffix contains at least one digit (=3, =-2, =3-, =2-1, =0). The whole-item close is recognized first, as a bare lowercase x token (plain x, selection-shaped x…, or the x#… near miss), so a start token never consumes a close. An exact start (t is exactly one start token and the item has exactly one physical line) goes through the existing se<X> timing, so = is 25 minutes, =3 is 15 minutes, =- is 25 minutes with a 5-minute offset, =2-1 is 10 minutes with a 5-minute offset, 0 and leading zeros are valid, and an oversized value fails before any write. A counted token followed by anything else (=3 more, =-2 @work, =3s:1, =2-1-, =3x) or an exact token with child lines fails as an invalid start, never a task. A bare token followed by more text (= foo, =- foo, =-)), bare x lookalikes (xx, xa, X, X2), and mid-body tokens (Plan =3, Plan =bugs, Plan x, a=3) stay ordinary prose. =xx and =xa are named starts now, not prose. The retired == spelling stays prose when followed by more text, which protects Obsidian highlight syntax; a claimed == start token gets the retirement error and teaches the matching = spelling.

Guards, checked in order on the staged daily note: a missing day file, a missing ## Pomodoros section, more than one open timed entry, and no future Pomodoro (a bare = never creates an entry; =name creates and starts a named session (see "Starting a named Pomodoro"), and ^route:block-id= starts a task's session). "Next future Pomodoro" means the first entry in document order that is open, a placeholder, and untimed — the same session the x diagnostic names as "next up". If one open timed entry already runs, a whole-item = restarts it as described in Overriding the running Pomodoro; link starts keep their separate refusal.

Selection, time, rewrite, and transaction mirror Obsidian's se<X> + Tab: the () becomes the canonical (**HHMM-HHMM** [t:: Nm]) range, preserving checkbox, name, other bytes, children, CRLF, and a missing final newline, then the entry moves to the current slot. No entry is created, no link is added, and no task note is written. Later items see earlier staged edits and dry-run computes without committing; any failure rolls the whole batch back. Composable idioms: x, blank line, = switches sessions (or x = on one line; the x closes before = plans, so no override warning appears); =, blank line, +2 starts then extends; =, blank line, ^bob:ready starts then links a task into the now-running session. A @@ declaration never applies to start items, and forced --route/--section/--task/--task-ref/ --task-section/--clip fail on them; %, s:<N>, and $<N> after a counted token are shape errors by construction.

The started session reports its queued Task Links (direct-child Task Links of the started entry, resolved read-only). The lineup is numbered 1..N in ledger order on the staged pre-image, so every whole-item start shows which number a queued link holds: JSON kind pomodoro_start keeps schema version 1 with text = the raw token, task_line = the started ledger line, placement: "started", and the existing pomodoro_start object with created_pomodoro: false plus an additive tasks array where each row carries its index (its lineup number). The started session also appears in the batch-level pomodoro_blocks array; see Pomodoro blocks. Human output prints the started file, the session range and line, the canonical ledger line, one numbered row per queued task, and nothing queued when empty.

Quote = items in zsh, which expands a leading =word to a command path: bob capture '=', bob capture '=3', bob capture '=-2'. Single-quote close tokens that contain !, *, or ~ (bob capture 'x!1', bob capture 'x*').

Dropping queued Task Links as a session starts¶

Write a trailing ~<K> drop list on a whole-item start to start lean: =~2 starts the next session without queued Task Link 2. One-card mnemonic: ~ drops — x~2 drops task 2 from the session you stop, =~2 drops task 2 from the session you start, using the numbers the start lineup shows.

<K> is comma-separated task numbers, each at least 1, with no whitespace, in any order; JSON reports the list sorted ascending. The drop part always comes last: after <X>, and after #name when present. A named start's name part ends at the first ASCII whitespace or ~. Any start token with a drop part claims its item, near misses included; a bare = followed by separate text (= ~2, = foo) stays prose. Link and task starts (^route:id=<X>, @route:id=<X>) do not take a drop part.

The lineup is the started entry's direct-child Task Links in ledger order, numbered 1..N on the staged pre-image (after earlier batch items and chain tokens have run). Every whole-item start reports these numbers, including a plain =. A named start that creates its session has an empty lineup, so any drop list fails before insertion.

Each dropped Task Link bullet is removed together with its nested child lines (which belong to that link in a session about to start — unlike a close, which keeps notes as history). No task note is written and no lane changes: a dropped task keeps its status. Dry-run computes without writing, and any failure rolls the whole batch back.

JSON kind pomodoro_start keeps schema version 1: text is the raw token, pomodoro_start.drop is the typed list (omitted when empty), pomodoro_start.tasks[] are the rows still queued (each with index), and pomodoro_start.dropped[] are the removed rows (with index, the pre-image ledger_line, and nested_lines, omitted when 0). Human output numbers the queued rows, prints dropped rows inline (dropped 2 [[T]] · stays Next · +1 nested line), follows with a dim Dropped <K> summary, and prints nothing queued when nothing is left.

Worked example (BOB_NOW=2026-09-30 09:42:00, TAB indentation; ^capture-stop, ^web-capture, and ^axe-restart are [*]):

## Pomodoros

- [x] (**0830-0855** [t:: 25m]) — PLAN
  - 🍅 [[bob#^capture-stop]]
- [ ] () — CAPTURE
  - [[bob#^capture-stop]]
  - [[bob#^web-capture]]
    - remember the URL parser
  - [[sase#^axe-restart]]
- [ ] () — SASE

bob capture '=' numbers the lineup 1 ^capture-stop, 2 ^web-capture, 3 ^axe-restart. bob capture '=~2' writes:

## Pomodoros

- [x] (**0830-0855** [t:: 25m]) — PLAN
  - 🍅 [[bob#^capture-stop]]
- [ ] (**0945-1010** [t:: 25m]) — CAPTURE
  - [[bob#^capture-stop]]
  - [[sase#^axe-restart]]
- [ ] () — SASE

(bob.md and sase.md are untouched.)

Starting a named Pomodoro¶

Capture a whole item =name to start one named Pomodoro now (=#name is the same token):

bob capture '=bugs'
bob capture '=3#bugs'
bob capture 'x =bugs'

A named start token is = plus an se<X> suffix (possibly empty) plus a name: either a bare name right after = (=bugs), or # plus a name part (=#bugs). A bare name starts with an ASCII letter, is not close-shaped, and does not start with x#/X#; it ends exactly where a #name part ends (whitespace, ~, or @). The # spelling is still always valid: write # only when a number comes first (=3#bugs) or the name starts with a digit or reads as a close (=#2fa, =#x, =#x2). =bugs and =#bugs lex to one token and produce the same CaptureKind, vault writes, and capture-parse semantics; only input/body echoes and span offsets differ. The <X> goes before # or last after @ (=bugs@3 means =3#bugs). The name part is a Pomodoro selector with the usual charset (A-Z, a-z, 0-9, & ' ( ) + , . / -); write spaces in names as -. To spell the name exactly, quote it after #: =#"DEEP WORK" (or =#“DEEP WORK” with curly quotes) names DEEP WORK verbatim, matched by key equality instead of the whole-slug/else-prefix rule, so SASE V18 and SASE-V18 stay distinct and =#"BOB" creates BOB even with BOB BUILD open. Bob always emits straight quotes; \" and \\ are the only escapes inside the quotes. The token runs through the closing quote, and a literal without its closing quote (=#"DEEP) is an incomplete editing state, never a mistake. The bare =name spelling never takes quotes: ="BOB" is ordinary prose. Every #name position takes the literal — named starts, link suffixes (@route:id#"…", @route+id#"…", ^route:id#"…"), project-note bullets, toggles, and close positions — so one rule holds everywhere. A named start claims its item and is never prose: an exact token (the item's only text, on exactly one physical line) starts the session, and anything else is a precise error. Unchanged: = without a name, every close form, = #foo and = bugs (a bare = with prose stays prose), mid-body tokens (Plan =bugs stays prose; put any word before it to capture a task that must begin with =word, and use a child bullet for a Work Log entry that must end in =word), doubled == (which keeps protecting Obsidian highlights), and the link forms (^route:id#name=<X> keep their #name=<X> order alongside the new =name suffix). x#… is a claimed close near miss with a teaching error; it used to be prose.

Resolution runs against the staged daily note, so chains and batches see earlier edits. Open entries match first (whole slug, else prefix), then completed ones the same way:

Creation inserts the placeholder after the last completed entry's block, otherwise before the first entry, otherwise at the section start — the same placement the named link start uses — and the subsequent move is then a no-op. An invalid name fails before anything is written, and when the name is only a near miss of an open entry the capture still succeeds but pushes a did you mean …? warning naming the open entry. A created entry reports tasks: []; a started open entry reports its direct-child Task Links through the existing queued lineup, exactly like an unnamed start, with the same tasks[].index numbering.

Guards, checked in order: a missing day file (the message still names the canonicalized selector), a missing ## Pomodoros section, name resolution, then more than one open timed entry. With exactly one timed entry, a different named target swaps in behind the same override warning as =. A counted start naming the running Pomodoro restarts it with the requested timing; an empty suffix naming that same session is refused because it would not change which session runs:

`=#capture` names CAPTURE, which is already running (0920-0945, line 5): restart it with `=` or `=<X>`, close it with `x`, or name another Pomodoro to swap in

When a running session must stay untouched, Bob Mac Capture passes the hidden --refuse-override guard until the warning has appeared in its preview. A matched open entry that is not an untimed placeholder or the running target fails with the existing selected-Pomodoro wording instead of starting.

With BOB_NOW=2026-07-10 09:02:00 and a ledger holding completed PLAN, open BUGS (with [[sase#^deep-fix]]), open DEEP WORK (with [[bob#^outline]] and [[bob#^draft]]), and an open unnamed entry:

The bytes contract matches the unnamed start: checkbox, name, children, CRLF, and a missing final newline are preserved. Dry-run computes the same result without writing, and any failure rolls the whole batch back. JSON kind pomodoro_start keeps schema version 1 with text = the raw token, task_line, placement: "started", the existing pomodoro_start object plus pomodoro_name, created_pomodoro, and the additive tasks array. The started session also appears in the batch-level pomodoro_blocks array; see Pomodoro blocks. Human output prints started (dry-run: would start), the session name, range, and line with (created) when the entry was created, the canonical ledger line, one numbered row per queued task, and nothing queued when empty. A @@ declaration never applies to named starts, and forced --route / --section / --task / --task-ref / --task-section / --clip fail on them with the existing start error. Quote named starts in zsh like every other = item: zsh's EQUALS expansion rewrites a word that starts with =, so bob capture =focus fails unquoted. Always single-quote (bob capture '=bugs', bob capture 'x =bugs', bob capture '=#"DEEP WORK"').

Overriding the running Pomodoro¶

A whole-item = / =<X> restarts the single running session with fresh se<X> timing. A whole-item =name starts or swaps in the named session. The warning appears in the preview before the write, so the person can see which running session will be replaced. Link starts such as @route:id=<X> and ^route:id=<X> keep their existing refusal while a session is running; only a whole-item start overrides.

bob capture '='
bob capture '=3'
bob capture '=-2'
bob capture '=bugs'
bob capture '=3#bugs'

For a restart, = means 25 minutes, =3 is 15 minutes, and =-2 is 25 minutes with a 10-minute offset. The running session stays the same; Bob replaces its parenthesized time ledger and moves it to the current slot. A trailing ~<K> drops Task Links from the session that remains running, numbered from the start lineup. Restarting is allowed even when the running session is overdue or has notes; plan.strict never refuses a start or override.

The dry-run warning is printed ahead of the result. With the worked example below, Bob prints these exact lines:

⚠ overrides the running CAPTURE 0920-0945 · capture `x =` to close it first
CAPTURE 0920-0945 → 0935-1000 (25m) at line 5

A swap names the target in its close-first draft:

⚠ overrides the running CAPTURE 0920-0945 · capture `x =bugs` to close it first

When the session is overdue, the warning says so:

⚠ overrides CAPTURE 0920-0945, still open past its end · capture `x =` to close it first

For an unnamed running session with Task Links, the warning, the swap demoted line, and the --refuse-override error name its derived homes chip after the range:

⚠ overrides the running session 0920-0945 ○ sase · capture `x =` to close it first
session 0920-0945 ○ sase → first future at line 7 · keeps 2 Task Links

An unlinked unnamed session prints exactly as before.

A named start resolves an open whole-slug match first, then a prefix match; a completed match starts again with that name, and no match creates it. When a different session is running, =bugs swaps BUGS in and hands it the running session's ledger byte-for-byte (ledger: "kept"); =3#bugs swaps it in with fresh 15-minute timing. =5#bugs explicitly swaps in with fresh 25-minute timing. The old session returns intact to the first future slot, including its links and notes. Drops apply to the session that ends up running. A swap follows the same warning and guard as a restart.

Naming the running session with an empty suffix is refused because it would not change which session runs. Add timing to restart it, or choose another name to swap in. For example, Bob reports:

`=#capture` names CAPTURE, which is already running (0920-0945, line 5): restart it with `=` or `=<X>`, close it with `x`, or name another Pomodoro to swap in

With exactly one open timed entry, the pomodoro_start.override object is present on the pomodoro_start result. Its action is restart or swap; ledger is fresh for a restart or a timed swap, and kept for an empty- <X> swap. previous describes the running session before the write; pomodoro_name is omitted for an unnamed session. overdue is omitted when false and true once the current time reaches the session end. close_first is the draft that would close the running session first. An unnamed session also carries the derived R9 homes object (forecast) on previous and, for a swap, on demoted; named sessions do no resolution and omit it:

"override": {
  "action": "restart",
  "ledger": "fresh",
  "previous": {"pomodoro_name": "CAPTURE", "pomodoro_line": 5,
               "start": "0920", "end": "0945", "duration_minutes": 25,
               "time_range": "0920-0945"},
  "close_first": "x ="
}

An overdue session adds "overdue": true to previous. A swap adds demoted, describing the old session in its first-future position, and uses the matching close draft:

"override": {
  "action": "swap",
  "ledger": "kept",
  "previous": {"pomodoro_name": "CAPTURE", "pomodoro_line": 5,
               "start": "0920", "end": "0945", "duration_minutes": 25,
               "time_range": "0920-0945"},
  "demoted": {"pomodoro_name": "CAPTURE", "pomodoro_line": 7,
              "entry_line": "- [ ] () — CAPTURE", "task_links": 2,
              "has_notes": false},
  "close_first": "x =bugs"
}

A plain start with nothing running has no override object. The result's existing pomodoro_start fields describe the session now running; the batch-level pomodoro_blocks reports it with role started and a swapped- out session with role reset.

Bob Mac Capture passes hidden --refuse-override when the on-screen preview for the current draft has not shown an override warning. If the state changes before submit, Bob refuses with code: pomodoro_override_refused; the client shows a fresh preview and requires another Return. This guards the warning seen before a commit without adding a confirmation step. For an unnamed running session with Task Links the refusal names the derived chip after the range (would restart the running session (0920-0945 ○ sase) and --refuse-override is set); named and unlinked sessions read as before.

Worked example (BOB_NOW=2026-10-09 09:32:00, TAB indentation):

## Pomodoros

- [x] (**0830-0855** [t:: 25m]) — PLAN
  - 🍅 [[bob#^capture-stop]]
- [ ] (**0920-0945** [t:: 25m]) — CAPTURE
  - [[bob#^capture-stop]]
  - [[bob#^web-capture]]
- [ ] () — SASE
- [ ] () — BUGS
  - [[sase#^fix-flaky]]

=bugs writes:

## Pomodoros

- [x] (**0830-0855** [t:: 25m]) — PLAN
  - 🍅 [[bob#^capture-stop]]
- [ ] (**0920-0945** [t:: 25m]) — BUGS
  - [[sase#^fix-flaky]]
- [ ] () — CAPTURE
  - [[bob#^capture-stop]]
  - [[bob#^web-capture]]
- [ ] () — SASE

A swap resolves the name against the pre-image, applies ~<K> to the incoming session's lineup, then demotes the running session. Demoting clears the running ledger to () and moves the whole block before the earliest other open untimed placeholder, so the old session is first future. The headline suffix and every child byte stay intact, including Task Links, struck links, nested details, and stand-alone notes. There is no note gate, history row, task-note write, or Work Log. For an empty <X>, the incoming session receives the previous ledger bytes verbatim, including range-local annotations; for a non-empty <X>, it receives fresh timing. A note-free restart leaves the day file byte-identical to x0 =<X>; a kept-ledger swap matches x0 =#name except that the target receives the old running ledger.

Adjusting the current Pomodoro¶

Capture a whole item +[N] or -[N] to adjust today's current timed Pomodoro by N five-minute units:

bob capture +5
bob capture -- -2
bob capture +
printf '+5\n\nCall bank @Cash+\n' | bob capture

+5 extends by 25 minutes and -2 shortens by 10 minutes. The count is optional and defaults to 1, so a bare + or - is one unit rather than an incomplete state. The item must contain only the signed count (or share its line only with other session operators; see Chaining session operators on one line): trimmed text matching ^[+-][0-9]*$ with a positive magnitude. Leading/trailing whitespace is fine. +0/-0 fail, and oversized magnitudes fail checked parsing/arithmetic before any write. If a valid signed-count token starts an item but has extra text, a marker, or a child line, the item fails as an invalid adjustment instead of creating a task; Plan +5 stays ordinary prose.

The adjustment selects exactly one open timed, column-zero entry in today's ## Pomodoros section. Missing/unreadable day file or section, no open timed entry, multiple open timed entries, or an unparseable target range fail without writing. The start stays fixed; new_duration = max(0, old_duration + signed_units * 5) with checked arithmetic and new_end = (start + new_duration) modulo 24 hours. Only that ledger line is rewritten to Bob's canonical (**HHMM-HHMM** [t:: Nm]) form, preserving its checkbox, name, non-duration metadata, child bullets, newline style, and surrounding bytes. Subtraction clamps at zero and reports both requested units and actual applied minutes when clamping changes the delta.

A @@route declaration still routes ordinary items in the same draft but never turns +5 into a task or changes its destination. Forced destination/task/section and clipboard options (--route, --section, --task, --task-ref, --task-section, --clip, %, s:<N>, $<N>) are rejected on adjustment items with a specific error. Later items observe earlier staged edits to the same daily file through CaptureBatchPlanner, so a +5 after a session-start item can adjust the session created earlier in the draft; dry-run computes the same result without committing, and a later invalid item rolls back all earlier staged changes. The same holds on one line: +2 x extends then closes atomically.

JSON keeps every existing key and schema version 1 stable and reports a distinct pomodoro_adjust kind with an additive pomodoro_adjust object (direction/requested units, actual delta minutes, before/after start/end/duration, resolved line/name, rendered new range). The adjusted session also appears in the batch-level pomodoro_blocks array; see Pomodoro blocks. Human output names what changed and where; dry-run says what would change.

Shifting the current Pomodoro¶

Capture a whole item ++[N] or --[N] to shift today's running timed Pomodoro N five-minute units later or earlier, keeping its duration:

bob capture ++3
bob capture -- --2
bob capture --1
printf -- '--2\n\n+\n' | bob capture

One sign moves the end; two signs move the whole session. ++3 translates both endpoints 15 minutes later and --2 translates both 10 minutes earlier, exactly like Obsidian's 3\o / 2\O with the running Pomodoro selected. The count is optional and defaults to 1, so ++ and -- move one unit. The item must contain only the operator (or share its line only with other session operators; see Chaining session operators on one line): trimmed text matching ^(\+\+|--)[0-9]*$ with a positive magnitude. Leading/trailing whitespace is fine. ++0/--0 fail ("move nothing"), oversized magnitudes fail checked parsing/arithmetic before any write, and a counted token with extra text, a marker, or a child line (++3 more, ++3@work, --2 s:1) fails as an invalid shift instead of creating a task. A bare sign run followed by more text (-- aside, ++ plan), a run longer than two or mixed (+++, ---, +-), and mid-body tokens (Plan ++3, C++) stay ordinary prose.

Target selection mirrors the adjustment: exactly one open timed, column-zero entry in today's ## Pomodoros section. Both endpoints translate modulo 24 hours (new_start = (start + delta) mod 1440, new_end = (end + delta) mod 1440), so shifts wrap across midnight and never clamp; a ++288 wraps a full day. There is no overlap check against neighbouring entries. Only that ledger line is rewritten to Bob's canonical (**HHMM-HHMM** [t:: Nm]) form, preserving its checkbox, name, non-duration metadata, child bullets, newline style, and surrounding bytes. A @@route declaration never applies to shift items, and forced destination/task/section and clipboard options (--route, --section, --task, --task-ref, --task-section, --clip, %, s:<N>, $<N>) are rejected on shift items with a specific error. Later items observe earlier staged edits, dry-run computes without committing, and any failure rolls the whole batch back, so --2 then + in one draft composes (or --2 + on one line).

The shell sees a leading - as a flag: spell an earlier shift as bob capture -- --2, or bob capture --1 for one unit. A bare -- stays the end-of-options marker and carries no text; pipe the draft (printf -- '--\n' | bob capture) when that reads better.

JSON keeps every existing key and schema version 1 stable and reports a distinct pomodoro_shift kind with an additive pomodoro_shift object (direction, requested units, signed delta minutes, before/after start/end/duration, resolved line/name, rendered new range). The shifted session also appears in the batch-level pomodoro_blocks array; see Pomodoro blocks. Human output names what shifted and where (shifted 2026/20260928.md, FOCUS 0900-0925 to 0915-0940 (25m), 15m later at line 5); dry-run says what would shift.

Closing the running Pomodoro¶

Capture a whole item x (lowercase x only) to close today's running timed Pomodoro:

bob capture 'x'
bob capture 'x2'
bob capture 'x1!2'
bob capture 'x0'
bob capture '^bob:capture-stop=x'
bob capture '^bob:capture-stop=x!1'
printf -- '-2\n\nx\n' | bob capture
printf 'x\n\n=\n' | bob capture

Single-quote tokens that contain !, *, or ~: shells glob * and history-expand !. A bare x needs no =-word quoting.

Retired close spellings¶

Whole-item =x…, =*…, and =!… are claimed teaching errors. They write nothing. Each message names the typed token and the exact bare-x rewrite. Link and task suffixes keep =x…; only the short =* / =! aliases on those suffixes retire, rewriting to =x* / =x!.

Mid-body Plan =x stays ordinary prose. =xx and =xa are named starts now, not prose. Capitalizing the first letter (X post about the launch, X11 forwarding, X *job:cleanup) is the escape for a task that must start with the word x.

This ports Obsidian's Ctrl+Enter Pomodoro completion (task-status-cycler's completeActivePomodoroTask), not the Ctrl+Shift+Enter task-level pause: the ledger ends up byte-identical to Obsidian's completion except for the auto-decrement below, the deliberate atomicity divergences, and the intentional capture-only x0 reset exception (a note-free x0 resets to first future instead of completing; Obsidian completion remains separate). A session closed before its planned end is shortened to the stop time (BOB_NOW=2026-09-28 09:37:00 closing 0920-0950 writes 0920-0940 [t:: 20m]): remaining = end − now normalized into (−720, 720] minutes, and when remaining ≥ 5, units = floor(remaining / 5), new_duration = max(0, duration − 5·units), new_end = (start + new_duration) mod 1440, rewritten in the same canonical (**HHMM-HHMM** [t:: Nm]) form +N/-N writes. Otherwise the range bytes are untouched; Bob never extends a session, and an overrun is reported (ran 7m over). Closed at 09:49 or later, 0920-0950 stays unchanged.

The close's child lines are Work Log bullets, and one entry may sit on the close line itself (or it shares its line only with other session operators; see Chaining session operators on one line and Logging work while closing); xx, xa, x., x-ray, xylophone, capitalized X…, and mid-body Plan x stay ordinary prose, as does mid-body Plan =x and Plan =bugs. Capitalizing the first letter is the escape for a task that must start with the word x. x more logs the inline entry more to task 1, x86 build claims task 86, and x *job:cleanup is refused as a Pomodoro-operator relationship. (==x is a claimed near miss teaching the x close, never prose.) A bare = is now a whole-item start, not an incomplete state. When no session is running but a future Pomodoro exists, the close diagnostic names it with a (start it with=) hint. @route:block-id=x… and ^route:block-id=x… first put that existing task into the running session (Ready/Blocked become Next; the Task Link moves or is appended into the session's sub-bullet range) then close it; <text> @route:block-id=x… creates the new Next task in the running session then closes it. When the §13.5 link guard finds the existing-task target Blocked, §13.5.1 drops its own prerequisites first when every safety gate passes, then the ordinary link-and-close path runs. Otherwise the status stays as-is (a Blocked task never rises on a history link) while the link still lands under the closing entry as history; the open prerequisites rise and the result reports link_guard with drop_refused when an own dependency reason kept the prerequisites. Whole-item x#name fails (`x` always closes the running Pomodoro; remove `#name`, or write `x =name` to close it and then start that Pomodoro; `=name` swaps it in without closing the running session). Link #name=x fails (`=x` always closes the running Pomodoro; remove `#name` (drop `=x` to link under a named Pomodoro instead)). So do s:<N>/$<N>, project-note + forms, and forced flags on a whole-item close. A @@ declaration never applies to close items.

Sub-bullet classification (after stripping 🍅 markers): fenced lines stay untouched notes; ![[…#^id]] embeds are closed recursively — except Depends-On lines, which are never tree-closed, so closing a dependent never closes its prerequisites — and retired to ~~[[…]]~~; a body that is exactly one plain block link plus # is deferred (removed from the session, carried without the #, target not started); other plain block links are worked-on (kept, given exactly one 🍅, carried); a worked-on line that is exactly one bare link is startable ([ ]/[*] → [/], stamping [fresh:: TODAY] in the same write; see docs/freshness.md); everything else stays as an uncarried note. Completing a task (! selection → [x]) never stamps. Carried lines (worked-on then deferred, in source order, at original indentation) move into a new - [ ] () (or - [ ] () — NAME) placeholder inserted after the session's sub-bullet range, created iff something is carried or no later entry follows; with nothing carried the placeholder gets a \t- stub. Direct-child qualifying links with descendants write dated Work Log entries under a 🛠️ **WORK LOG** marker (newest on top) or append one after the task's child block. Notes stay in the ledger (copied, not moved). Close-time recovery plus successor offers run on every close that completes tasks, per task-dependencies.md §12: picked successors go into the same-name continuation, created when needed, and count as carried. Without --pull-in, capture recovers and reports numbered offers (not_selected). The continuation rule is the same-name entry search in §12.3: the created continuation first, else the first open same-name entry after the closed one, else a new placeholder at the continuation position. Completed-reference retirement outside the session still stays with reconcile.

Diagnostics (all write nothing): a missing day file, a missing Pomodoros section, no open timed entry (no running Pomodoro to close, plus ; next up is NAME at line N when an open placeholder exists), several open timed entries, and an unparseable-range warning that still closes without decrementing. The start guards now append (close it with `x`).

JSON keeps schema version 1 and reports kind "pomodoro_close" (link and task forms keep their kind) with an additive pomodoro_close object (timing, per-target transitions, carried links, notes, next session). A whole-item x close also reports the closed session — and the next session it names — in the batch-level pomodoro_blocks array; see Pomodoro blocks. Field notes:

• pomodoro_close.raw is the typed token exactly as typed: the bare token (x, x1*2!3~4) for whole-item closes, and the =-prefixed suffix (=x!1) for link and task closes.
• pomodoro_close.in_progress is the typed <N> list sorted ascending, null when no <N> was typed (x0 reports [], and x*2 keeps null), pomodoro_close.park is the typed *<P> list (possibly empty, omitted when empty), pomodoro_close.complete is the typed !<M> list (possibly empty), and pomodoro_close.drop is the typed ~<K> list, omitted when empty.
• pomodoro_close.log is the typed Work Log entries in typed order (bullets or the one inline entry; [{ "index": 2, "text": "wired the lexer" }]), omitted when empty. In bob capture JSON index is always the task the entry logged to, including for unnumbered bullets, which execution resolves positionally. Each entry carries details, the nested detail lines typed under it ([{ "index": 2, "text": "wired the lexer", "details": ["chose a hand-rolled lexer"] }]), omitted when the entry has none.
• pomodoro_close.tasks[].typed_work_log holds the dated entries (*YYYY-MM-DD* — text, a subset of work_log) that this capture's typed entries produced, in typed order, omitted when empty. pomodoro_close.tasks[].typed_work_log_details is aligned 1:1 with it: element i lists the detail lines written under typed entry i (undated sub-bullets of the dated entry, never counted in +N Work Log), with an empty list for entries without details; omitted when no typed entry on the row has details.
• pomodoro_close.task_links is the numbered lineup, always present and possibly empty, in number order. Each entry carries index (1-based), ledger_line (the close's pre-image, after any link step), block_link (never including the !), block_id, marker (plain, deferred, or embedded: the line's marker before the selection), outcome (in_progress, parked, deferred, complete, or dropped), and source (ledger when the outcome comes from the line's own marker, listed when its number was typed, unlisted when <N> was typed without it).
• tasks[].index is the number of the numbered line that produced the row, or null for unnumbered rows (struck, mentioned, subtask, and Work-Log-only); when one task is numbered on several lines, its single row carries the lowest number. tasks[].role keeps its current meaning: it is the role after the selection, so a completed row is embedded, a deferred row is deferred, and a dropped row is dropped. A parked row stays worked (or its existing unresolved role): parking never changes task resolution or status semantics, only carry. A client joins tasks[].index to task_links[index-1] for outcome/source.
• tasks[].carried is true only when that target's line was actually carried into the new placeholder, and agrees with the top-level carried list, the next-session count, rendered blocks, and plan budget. Parked rows report carried: false with no other independently carried reference to that target.
• Link forms (pomodoro_link, pomodoro_task) keep the placement their non-close counterpart reports; only whole-item x uses placement: "closed".
• Inside pomodoro_close, explicitly null (not omitted) appears for tasks[].warning, for tasks[].relative_target, text, previous_status_symbol, previous_status_name, status_symbol, and status_name on unresolved rows, for next_pomodoro.time_range, and for next_pomodoro itself when null — matching the top-level route: null / scheduled: null convention.
• Embedded and subtask row text omits the #task tag, like every other row.
• Whole-item x reports created as the clock's date string, as every other kind does.
• pomodoro_close carries the same unblocked[], still_blocked[], and unblocked_check fields as task_complete (see the task-complete result contract above): the same row shapes, the same offer object, the same not_linked reasons (not_selected, no_destination, project_member; never breaker or not_planned_today), the same trigger / hide_removed fields, and the same gate semantics over the close's completed set. Dry-run JSON equals real-run JSON with the same flags. The batch also carries top-level pull_in on every success.
• When the successor logic created the continuation, next_pomodoro reports it ({line, name, time_range: None, created: true}); picked successors count as carried.
• Added block lines that equal a surviving picked successor bullet carry "reason": "unblocked" in the pomodoro_blocks line objects; rows dropped by net batch reporting lose the reason.

Human output prints closed NAME old → new (Nm, −Xm) · file line N (or a single range with no decrement, plus (ran Nm over) on overruns), always naming the day file; one line per task as transition text route ^id plus +N Work Log counts; dropped rows read dropped <K> [[T]] (with a stays <status> lane caption: a dropped task keeps its status) and a Dropped <K> summary follows the rows; the same numbered offer N / linked / unblocked / still blocked successor rows the ! close prints, after the task rows; and the next session, which reads carries 1 link in the singular. When picked successors rode along, next: names them (next: BOB (created) at line N · carries K links · 1 unblocked). When at least one row is numbered, every task row is prefixed with a right-aligned index column (width = digits of the highest number) plus one space; unnumbered rows get blanks of the same width and Work Log preview lines indent to stay under the text. The index is bold, colored by outcome (in progress uses the / color, complete uses the x color, deferred is dim), and unlisted indices are dim too. With zero numbered rows the output is byte-identical to before. The "switch tasks" batch idiom is x, blank line, ^route:id= — close the running session, then start the next one through the existing start rules. The session switch idiom is x, blank line, = (or x = on one line) — close the running session, then start the next future Pomodoro.