feat: read what a tab has learned, pin a working set, and stop claiming sends landed

[motin]

Six gaps measured while driving a 13-tab fleet. The common thread: cctabs
reported outcomes it had not established — a spawn that returned counted as a
tab that worked, a paste chip counted as a delivery, a null session_id meant
three different things.

Branched fresh off origin/main (v0.5.3). feat/whoami is untouched — see
"On the two local commits" below.

Items 1 and 3 — the two that change how a fleet is driven

cctabs transcript <tab> [n] (alias findings) prints a tab's last n
assistant messages, read from the transcript rather than the screen.
scrollback returns the last painted frame, so a tab mid-turn shows a spinner
and nothing else — which is why sessions were briefing each other from stale
pictures. It searches every Claude config dir: a tab on a backend preset
writes beneath that preset's own root, and looking in only ~/.claude/projects
reports "no transcript" for a healthy session, which reads as dead. It exits
non-zero and names which failure it hit, including a count of transcripts that
do exist for the tab's directory — that number distinguishes a tab renamed out
from under a live session from a directory nothing has ever run in.

cctabs sort --first a,b,c pins a chosen set to the front. The plugin's
POST /api/tabs/reorder already had exactly the needed semantics (unlisted tabs
keep their relative order and sort after the listed ones); no CLI verb exposed
it. Pinning skips the activity scan entirely, which is ~7.7s of transcript
reading on a 65-tab fleet. If any name doesn't resolve to exactly one tab,
nothing moves and it exits non-zero.

Items 2, 5, 6

• sessions --json says why a session_id is missing — session_lookup is
  one of found / not-found (with sessions_in_dir) / no-cwd /
  lookup-failed (with the error). A lookup that threw was previously
  swallowed into the same null as "searched and found nothing", and those call
  for opposite responses.
• restore reports the count it achieved. It re-reads the tab list after
  spawning, checks each tab has a process, resolves its session from disk, and
  reports N verified, N unconfirmed, N failed, exiting non-zero on failure. A
  tab that came back as a different session counts as failed: --resume on an
  id it can't find opens a fresh conversation, so the tab looks perfect and the
  context is gone. unconfirmed is a first-class outcome rather than rounded
  either way. (This needed a title-index cache reset — the cache was built while
  planning and would have cheerfully confirmed the pre-restore world.)
• send --submit presses Enter only. Also: an empty body with no
  --submit now says so instead of silently pressing Enter in someone's
  session, and contradictory text sources are rejected rather than silently
  ranked.
• send refuses payloads over 1 KB into a tab with a turn in flight
  (--force overrides). Short replies into a busy tab — yes, 2 — are what
  sending into an active tab is for and still work.

Item 4 — and a correction worth reading

The measured incident: 6,835 bytes sent into an idle tab, 756 bytes
recorded, front-clipped, both ends reporting success. Root cause found:
sendTextWithConfirmation accepted [Pasted text appearing anywhere in the
buffer as proof, and that chip renders no matter how little arrived.

My first fix compared the chip's +N lines against the payload. That fix was
wrong, and the verification the brief asked for is what caught it. Sending
6,892 bytes into an idle tab and then asking the receiving session what it got:

ACK front=alpha-7391 end=omega-5520

Front and tail both arrived — the payload delivered complete — while the
chip on screen read +10 lines. So the chip's count does not track the payload,
and failing a send on a shortfall fails healthy sends. I could not reproduce
front-truncation at 6.9 KB at all.

What that leaves is a real conclusion: for a collapsed paste the screen cannot
establish completeness. So send now separates three claims that used to be
one check-mark line —

• nothing arrived → hard failure, and the body is not submitted, because
  pressing Enter on a fragment sends something that reads as a complete message.
  Text is left in the input box; exit 1.
• arrived, completeness unverified → a warning naming the two remedies.
• verified → success.

— and --verify does the comparison item 4(b) actually asked for, against
ground truth: it reads the target's own transcript, which records the user
message as received, and checks the payload's front and tail fingerprints,
naming which end went missing.

✔ Sent to a92fc9bf and verified: the session received the whole payload
  (front and tail both present in its transcript, 5748 non-whitespace chars sent)

--path (item 4c) is first-class: it hands the tab a file path and lets the
receiving session read it, so only a path crosses the prompt line and there is
no truncation surface. Verified end to end.

--wait-for-prompt tested only the buffer's last non-empty line, and Claude
renders notices below its input line — a Restart to update banner defeated
it for the full timeout. It now reads the whole tail of the window.

Verified against the live 86-tab fleet, with the new build installed

• transcript on a tab whose session lives under ~/.claude-enterprise —
  resolved it, reported backend=enterprise, printed the turn.
• sessions --json: 82 found, 4 not-found. One of those, ltv-cac-ent,
  reports 99 transcripts in its directory — previously an indistinguishable
  session_id: null.
• sort --first applied for real (two tabs to the front, rest kept relative
  order), then the original 86-tab order restored exactly.
• send at 6,892 bytes into a confirmed-idle tab, with --verify; --path
  handoff; the nonexistent---path and contradictory-source refusals.
• Exit codes checked directly, not inferred from output.

On the two local commits

The brief said to preserve feat/whoami's two local-only commits. git ls-remote origin feat/whoami is indeed empty, so they are unpushed as commits — but
their content is already on main: f9d8331 landed squash-merged as
bb9a05c (#20), and the send-confirm work plus a later optionalAdapter
refinement shipped in v0.5.3. git diff origin/main feat/whoami shows the
branch removing work main has, so rebasing it would revert those refinements.
I branched fresh off origin/main and left feat/whoami untouched at
e352987.

Not done, and why

• Item 7 (the trust-dialog fall-through) was outside the assigned set.
  Untouched.
• npm run sync-plugin not run: it writes to ../plugins, and the repo's
  own prepack sync check is already failing on main (plugins repo at 0.5.1
  vs package.json 0.5.3) independently of this branch. That's a release step.
• No version bump, no tag, no publish. The local global install was done
  from a packed tarball of the working tree, not a registry install.
• @types/bun was missing from the stale local node_modules, so
  npm run typecheck failed on main too; npm ci fixed it. No source change
  involved.

npm run check: 322 pass, 0 fail, typecheck and build clean.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying cctabs with    Cloudflare Pages

Latest commit:	42fd4da
Status:	⚡️  Build in progress...

View logs

[motin]

Both reports fixed and pushed (8d42199)

Thank you for the empty-preview observation — that detail is what made BUG 2
findable in one probe rather than by bisecting a send.

BUG 2 — confirmed, and your hypothesis was right about the cause

The mechanism is slightly broader than option-consumption: the parser drops
any argv element containing --, and the token is lost from positionals
and values alike. Probed directly:

argument	result
"hello world"	kept
"hello -x"	kept
"mentions --verify here"	dropped
"--leading"	dropped
"a--b"	dropped
"trailing --"	dropped

So it isn't that a flag name gets consumed as an option — nothing is set in
values either. A single dash survives; -- anywhere does not. Your text
contained --file, --path and --verify, so the whole argument vanished,
send fell through to reading stdin, stdin was empty, and the empty preview
followed. Exactly the two symptoms you predicted, and exactly the diagnosis you
proposed as the fix.

Fixed as you suggested: positionals now come from process.argv directly
(core/send-argv.ts) rather than from the parser that loses them, and -- is
supported as an explicit terminator for text that is entirely flag-shaped.
Both forms verified end to end against a live tab:

$ cctabs send <tab> "BUG 1 — the --path option does not hand over a path... --file ... --verify" --verify
✔ Sent and verified: the session received the whole payload (109 non-whitespace chars sent)

$ cctabs send <tab> -- --verify is broken and --path too
✔ Sent to cbfb77e9: "--verify is broken and --path too" ⏎

16 test cases cover it, including a--b and a tab name containing --.

And the class of failure, not just the instance: an empty body is now a hard
error (exit 1) instead of a ✔, because reporting success for a delivery of
nothing is the same defect as the restore success line that could not fail. A
deliberate bare Enter reports Submitted Enter only (no body), so an empty
preview can never follow a ✔ again — your tell is now unambiguous by
construction.

BUG 1 — --path is not pasting; --verify was lying to you

I could not reproduce a paste. On a 2,470-byte fixture, the payload sent was the
257-char handoff, and the file was never read by send.

What actually went wrong is --verify. Claude records a tool's output as a
role: "user" message, and a --path handoff instructs the tab to read the
file — so the newest user-role entry becomes the file's contents. Verify
compared the handoff against the file. Straight from the transcript:

user[str]         len=284   'Read the file at /private/tmp/.../bug1-fixture.txt...'
user[TOOL_RESULT] len=2469  'BUG REPORT (test fixture, 2421 bytes target)...'

That 2,469 is your 2,651. It is the file being read, which is --path working —
and comparing against it produced "matches neither end of what was sent", which
reads precisely like a front-clipped paste. Your inference was the only
reasonable one from the evidence the tool gave you; the tool gave you the wrong
evidence.

Verify now skips tool results (the entry's toolUseResult field identifies
them) and searches every real message instead of only the newest, so a payload
stays findable after the session has moved on. Both ends turning up in
different messages is still not a delivery.

I also fixed a second verify defect found while reproducing: it resolved the
session once, before its poll loop, so a freshly spawned tab failed
instantly with no session resolved for tab a second before its transcript
existed. Lookup now retries for the whole window.

--path's help text also overclaimed in the way that set this up — it implied
nothing of the file crosses into the session's record. It now says the receiving
session reads the file, so the contents appear in its transcript as a tool
result, and that this is the handoff working rather than a paste.

Smaller note — confirmed non-zero

$ cctabs send <tab> "payload" --verify --verify-timeout 0
 ERROR  ... delivery does NOT check out: no session ... appeared within 0s
$ echo $?
1

A verify mismatch exits 1. (Worth flagging that I made your exact mistake twice
in this session — cmd | tail reports the pipe's status, so I re-checked every
exit code without a pipe.)

npm run check: 346 pass, 0 fail. Reinstalled globally from the working
tree. Both scratch tabs closed; the fleet is back as it was.