bug: outbox silently drops directory entries (e.g. `guides/`) — silent loss of intended deliveries on every session

[nathanschram]

Audit-filed by untether-staging monitor loop, pass 1, run 20260513T015418Z, at 2026-05-13T01:54Z.

Source: untether.service on lba-1, 0.35.3rc13.

Type: Enhancement opportunity (ENH-PATCH)

Observation:
On 2026-05-13 at 11:54:46 AEST, after a successful Claude Code run in chat -5173025382 (project auditor-toolkit, session 4e15a844-0632-477c-a9c3-c0be07573de0, 7 turns, $3.44), the outbox delivery scan logged:

2026-05-13T01:54:46.022294Z [info] outbox.skipped
  branch=None chat_id=-5173025382
  cwd=/home/nathan/claude-code-tools/lba/tools/auditor-toolkit/main
  engine=claude project=auditor-toolkit
  resume=4e15a844-0632-477c-a9c3-c0be07573de0
  skipped=[('guides', 'directory')]
  user_msg_id=51258

The agent had placed an item named guides (a directory) into .untether-outbox/. The outbox delivery code (outbox_delivery.py) treated directories as unsupported and dropped the entry. No surface was given to the user — the structured log is the only trace. The user finishing the run never learned the agent intended to deliver a folder.

Opportunity:
Either:

• (A) Surface the skipped item to the user. Append a single line to the final message footer: 📎 skipped (unsupported): guides (directory) or include it inline near the existing 📎 attachments block. Tells the user something was intended, prompts the agent to re-attempt with a supported approach (zip/tarball, individual files).
• (B) Auto-zip directories. On encountering a directory in the outbox, transparently zip -r guides.zip guides/ and deliver as a single archive. Add a size cap (outbox_max_files already exists — add outbox_max_archive_bytes) and abort to (A) if too large.

(A) is cheap and unambiguous; (B) is a richer feature but adds packaging logic and a new failure surface (oversized archives, deny-globbed files inside the directory tree).

Why it matters:

• User impact: anyone whose agent generates a folder of outputs (docs, screenshots, exported reports). With workspace-mode and longer Claude/Codex runs becoming standard, agents producing folder structures is increasingly natural.
• Frequency: occasional today — agents have to be specifically prompted to deliver folders. Will rise as users get more comfortable asking agents to produce multi-file deliverables.
• Friction: silent failure. The user has no idea anything was lost. The agent's "I've prepared the guides folder for you" final message becomes a lie with no indication.

Suggested approach:

1. Stage 1 — Surface (A): in src/untether/telegram/outbox_delivery.py (scan_outbox / deliver_outbox), keep the existing outbox.skipped log line but also accumulate skipped items into a return value used by runner_bridge when composing the final message. Append a **📎 skipped:** line listing each (name, reason) pair. Add an [transports.telegram.files] config flag notify_skipped_outbox = true (default true) so users can opt out.
2. Stage 2 — Optional zip (B): only after (A) ships. Add outbox_zip_directories = false config flag (opt-in initially), use zipfile from stdlib, respect deny-globs while zipping, cap at outbox_max_archive_bytes (default 50 MiB), fall back to (A) on cap exceed.
3. Update docs/reference/transports/telegram.md outbox section.
4. Tests in tests/test_outbox_delivery.py (does this exist? tests/test_telegram_files.py covers helpers; outbox_delivery may not have a dedicated test file yet).

Related code/files:

• src/untether/telegram/outbox_delivery.py (scan_outbox, deliver_outbox, the outbox.skipped log site)
• src/untether/telegram/files.py (deduplication / deny-glob primitives — would be reused for zip variant)
• src/untether/runner_bridge.py (final message composition)
• docs/reference/transports/telegram.md (outbox docs)
• untether.toml [transports.telegram.files] section
• tests/test_telegram_files.py (17 tests, file helpers)

Related issues / prior conversations:

• feat: agent-initiated file delivery via .untether-outbox/ #143 (feat: agent-initiated file delivery via .untether-outbox/, the original outbox feature) — CLOSED, established the mechanism. This is a follow-up gap.

Effort estimate: S for (A) alone; M for (A)+(B).

Milestone: v0.35.4 (reasoning: small surfacing change with clear user benefit; B can defer).

— filed by untether-staging monitor loop, pass 1

[nathanschram]

Pass-3 follow-up from untether-staging monitor loop, run 20260513T015418Z.

Three more outbox.skipped directory drops in the 20-min window starting 2026-05-13T02:15Z — confirming this is a recurring pattern across multiple projects, not a one-off:

2026-05-13T02:18:06.713152Z [info] outbox.skipped chat_id=-5235455627
  cwd=/home/nathan/claude-code-tools/lba/marketing/brand-copilot/main
  engine=claude project=brand-copilot user_msg_id=51271
  skipped=[('30-day-output-quality-tuning', 'directory')]

2026-05-13T02:20:08.075822Z [info] outbox.skipped chat_id=-5235455627
  cwd=/home/nathan/claude-code-tools/lba/marketing/brand-copilot/main
  engine=claude project=brand-copilot user_msg_id=51285
  skipped=[('30-day-output-quality-tuning', 'directory')]

2026-05-13T02:21:12.674823Z [info] outbox.skipped chat_id=-5189982707
  cwd=/home/nathan/claude-code-tools/lba/apps/mcp-servers/australian-history-mcp
  engine=claude project=aushistory user_msg_id=51275
  skipped=[('sqlite-dq-hardening-2026-04-24', 'directory')]

That's 4 separate occurrences in a ~30-min window today (including the original guides skip from pass 1 on auditor-toolkit). Three distinct projects (brand-copilot, aushistory, auditor-toolkit); three distinct directory names; on two of them the SAME directory was skipped twice in a row (same playbook re-run), so the agent isn't learning that its outbox-directory drop was silently dropped — it's putting it back next time.

Frequency upgraded from "occasional" to every time the agent attempts a directory output, which under workspace-mode + multi-deliverable playbooks is increasingly common. Strengthens the case for shipping at least surface-option (A) before the next release.

— filed by untether-staging monitor loop, pass 3

[nathanschram]

Pass-4 follow-up. Same 30-day-output-quality-tuning directory dropped a third time on the same chat (-5235455627/brand-copilot), 14 minutes after the first drop:

2026-05-13T02:32:41.808478Z [info] outbox.skipped
  chat_id=-5235455627 project=brand-copilot
  resume=ae3ff3d6-7f2a-47c0-b178-cc8ee99f117b
  skipped=[('30-day-output-quality-tuning', 'directory')]
  user_msg_id=51291

Cumulative count for this audit window: 5 outbox.skipped directory drops across 3 projects in ~90 minutes (brand-copilot ×3 same dir, aushistory ×1, auditor-toolkit ×1 from pass 1).

The "same directory dropped repeatedly on the same session" signal is the most interesting one — the agent has zero feedback that its deliverable is being silently dropped, so it just keeps trying. This argues strongly for surface-option (A) — even just a line in the final message saying "📎 skipped: 30-day-output-quality-tuning (directory)" would break the loop, because the agent would see it in the next turn's context.

— filed by untether-staging monitor loop, pass 4

[nathanschram]

Audit evidence — untether-fleet monitor loop, pass 2 at 2026-05-14T02:35:24Z (run 20260514T021800Z).

Three further occurrences observed on lba-1 (0.35.3rc13) during a single 20-minute window:

[lba-1] 2026-05-14T02:20:44.006693Z [info  ] outbox.skipped [untether.telegram.outbox_delivery] chat_id=-5189982707 project=aushistory skipped=[('sqlite-dq-hardening-2026-04-24', 'directory')]
[lba-1] 2026-05-14T02:23:11.488942Z [info  ] outbox.skipped [untether.telegram.outbox_delivery] chat_id=-5235455627 project=brand-copilot skipped=[('30-day-output-quality-tuning', 'directory')]
[lba-1] 2026-05-14T02:33:01.946211Z [info  ] outbox.skipped [untether.telegram.outbox_delivery] chat_id=-5189982707 project=aushistory skipped=[('sqlite-dq-hardening-2026-04-24', 'directory')]

Notes:

• Two distinct directories caught across two distinct projects in 20 min.
• Same (sqlite-dq-hardening-2026-04-24, directory) was skipped twice for the aushistory chat (12:20 and 12:33) — same agent re-creating the dir between runs, or watcher rescan.
• All three are silent at the user end — the user only sees the final answer, no indication these dirs existed in .untether-outbox/.

Reinforces the original signal that outbox.skipped events warrant a user-facing surface (Telegram footer line or follow-up message). Not yet escalating severity, but recurrence frequency is meaningful.

— filed by untether-fleet monitor loop, pass 2

[nathanschram]

Audit-filed by untether-staging monitor loop, pass 1, run 20260516T032233Z, at 2026-05-16T03:23Z.

Source: untether.service on lba-1, 0.35.3rc16.
Host: lba-1

Still observed on rc16 — pattern recurring across 3 distinct projects with 6 distinct directories over the last 24h.

Evidence (last 24h, outbox.skipped log events):

time (UTC)	chat	project	skipped
2026-05-15T06:46:29	-5206058965	nathanschram	platform-icons-screenshots, screenshots, screenshots-1-5, screenshots-logos
2026-05-15T06:54:19	-5206058965	nathanschram	(same 4 directories — resumed session, same outbox)
2026-05-15T07:00:00	-5206058965	nathanschram	(same 4 directories)
2026-05-15T07:03:41	-5206058965	nathanschram	(same 4 directories)
2026-05-15T07:06:35	-5206058965	nathanschram	(same 4 directories)
2026-05-15T07:34:34	-5206058965	nathanschram	(same 4 directories)
2026-05-15T08:16:30	-5206058965	nathanschram	(same 4 directories)
2026-05-15T20:18:12	-5235455627	brand-copilot	30-day-output-quality-tuning
2026-05-15T20:31:45	-5189982707	aushistory	sqlite-dq-hardening-2026-04-24
2026-05-15T21:47:41	-5235455627	brand-copilot	30-day-output-quality-tuning
2026-05-15T22:10:08	-5235455627	brand-copilot	30-day-output-quality-tuning
2026-05-16T02:18:07	-5235455627	brand-copilot	30-day-output-quality-tuning

13 total outbox.skipped events. Same 4 nathanschram directories were dropped on seven consecutive runs because the agent kept writing them — it has no way to know its delivery attempts are no-ops, so it keeps trying. The brand-copilot 30-day-output-quality-tuning directory dropped on four consecutive runs for the same reason.

Impact reinforcement:

• Multi-project, multi-day pattern (not a one-off)
• Agent has no feedback, so the same skipped directory recurs every cron/manual run that touches that path → wastes user time and outbox cycles
• Users would not realise output exists in cwd/<dir>/ unless they SSH/git pull manually
• All entries are [info] level → daemon doesn't file → only /monitor catches it

Sample sole-evidence log line:

2026-05-16T02:18:07.146977Z [info] outbox.skipped [untether.telegram.outbox_delivery]
  chat_id=-5235455627 cwd=/home/nathan/claude-code-tools/lba/marketing/brand-copilot/main
  engine=claude project=brand-copilot resume=None
  skipped=[('30-day-output-quality-tuning', 'directory')] user_msg_id=51934

Restating the suggested fix axes from the original issue (so a v0.35.4 implementer has the full surface in one place):

1. Surface a Telegram message: "📁 Skipped 1 directory (30-day-output-quality-tuning) — outbox delivers files only"
2. Optionally auto-zip the directory and ship as <name>.zip if under outbox size cap
3. Send a control_request back to the agent so it sees its delivery failed and can adjust (write a single archive next time, or render inline)

— filed by untether-staging monitor loop, pass 1

[nathanschram]

End-of-window synthesis from untether-staging monitor loop, run 20260516T032233Z (passes 1-9).

Source: untether.service on lba-1, 0.35.3rc16.

This synthesis consolidates the pass-1 evidence comment above with 16 additional occurrences observed during the 2h audit window — confirming the resumed-session feedback-gap pattern flagged in this run's watch-list.

Window totals (2026-05-16, 13:22 – 15:22 AEST)

project	distinct directories	occurrences in window	resumed-session pattern?
brand-copilot	30-day-output-quality-tuning	4 (passes 3, 6, 9, plus pre-window evidence on the same dir)	✓ yes — same dir dropped on every brand-copilot completion across 4+ runs
(no other projects fired in this window)	—	—	—

Combined with the 24h pre-window evidence from the pass-1 comment, the total observation is 17 outbox.skipped events / 6 distinct directories / 3 projects — and the resumed-session pattern is now definitively confirmed: the agent has no feedback loop, so whenever a project resumes a session that wrote outputs to a directory, the agent writes to the same directory again on the next turn, hits the same silent skip, and the same 30-day-output-quality-tuning/ (or whichever directory) is dropped repeatedly until the user notices.

Why this matters for priority

This is no longer "agent occasionally writes to wrong place" — it's "agent consistently writes outputs the user never receives, with zero feedback signal until the user goes looking in cwd/ on disk". The chronic recurrence rate (every brand-copilot completion in the window) means the originally proposed fix axes deserve renewed attention:

1. Surface a Telegram message on skipped items — even a one-liner "📁 Skipped 1 directory (<name>) — outbox delivers files only" would close the feedback loop both for the user (they know to look on disk or zip it) and for the agent (it sees the message in next-turn context and adjusts).
2. Auto-zip directories under the outbox size cap — most directories I've seen skipped (4 nathanschram screenshot dirs, brand-copilot tuning dir, aushistory hardening dir) are <10MB and would deliver cleanly as ZIPs.
3. Send a control_request back to the agent so it discovers the skip and adjusts (write a single archive next time, or render inline).

Option 1 alone fixes the user-facing UX. Option 3 alone fixes the agent-loop. Both together fix it definitively.

No new evidence beyond this window needed

Closing this synthesis with: monitor-source comment cap reached (5/5). Further /monitor runs should not add per-pass evidence on this issue — the pattern is now thoroughly documented and the cap protects against signal-bloat. If the underlying behaviour changes in a future release (e.g. fix lands or telemetry shape changes), open a fresh tracking issue rather than re-opening evidence on this one.

— end-of-window synthesis · run 20260516T032233Z