chore: release v0.35.1

[Nathan Schram (nathanschram)]

Summary

Promotes v0.35.1 from dev → master for PyPI publish. Aggregates all v0.35.1rc1 → rc6 staging work plus final release polish.

Headline changes (see full changelog for entries with issue links):

Trigger enhancements (7 major features)

• Timezone support for cron triggers (feat: timezone support for cron triggers #270)
• SSRF protection utility (feat: SSRF protection utility for outbound HTTP requests #276)
• Non-agent webhook actions: file_write, http_forward, notify_only (feat: non-agent webhook actions (file_write, http_forward, notify_only) #277)
• Multipart form data support for webhooks (feat: multipart form data and file payload support for webhooks #278)
• Data-fetch cron triggers with HTTP/file_read (feat: data-fetch cron triggers (HTTP, file read, shell command) #279)
• Hot-reload for trigger configuration (feat: hot-reload support for triggers, watchdog, and progress settings #269)
• /at command + run_once cron flag (feat: one-shot delayed triggers — /at command and run_once cron flag #288)
• Trigger visibility: /ping summary + meta footer provenance (feat: trigger visibility — indicators, discovery, and run history #271)

Reliability & restarts

• sd_notify + update_id persistence → ~5s restart gap (research: graceful restart improvements — reduce downtime and user impact #287)
• Hot-reload for Telegram bridge settings (feat: unfreeze TelegramBridgeConfig for hot-reload of voice, files, chat_ids, timing settings #286)
• Stall warning false-positive reduction (v0.35.1: Stall warnings fire false positives during normal Agent/Bash workflows #264)
• Systemd OOM policy fix: OOMScoreAdjust=-100, OOMPolicy=continue (Orphaned workerd processes accumulate after SIGTERM cascade — 316 processes, 37GB RAM #275)
• Auto-continue no longer death-spirals on SIGTERM/SIGKILL

Security hardening (6 issues)

• Callback sender validation in group chats (security: callback query sender not validated in group chats #192)
• CI tag name escaping (security: tag name injection in notify-website CI workflow #193)
• Flag-like prompt sanitisation across all runners (security: user prompt passed as CLI arg without -- separator (flag injection) #194)
• Bot token redaction in structured logs (security: bot token leaked in structured log URLs #190)
• 10 MB JSONL line buffer cap (security: unbounded JSONL line buffer can cause OOM crash #191)
• Diff preview gate bypass after plan approval (bug: diff_preview gate requires manual approval for every tool after ExitPlanMode in plan mode #283)

Bug fixes

• Multipart webhook HTTP 500 (bug: multipart webhooks return HTTP 500 — raw_body consumed before request.multipart() #280)
• Webhook rate limiter 429 fire-and-forget dispatch (bug: webhook rate limiter never returns 429 under burst load #281)
• /ping uptime reset on restart (bug: /ping uptime does not reset on service restart #234)
• scripts/healthcheck.sh set -e + journalctl meta line (healthcheck.sh exits prematurely due to ((var++)) under set -e #302)

Docs & observability

• 38 new structlog calls across 13 files (fix: add 38 missing structlog calls across 13 files (logging audit) #299)
• Update/uninstall guides + README transparency section (docs: add update and uninstall guides + README transparency section #305)
• Comprehensive v0.35.1 documentation audit — 8 gap fills (docs: comprehensive v0.35.1 documentation audit — 8 gap fills across 121 files #306)

Staging record

• rc1–rc6 staged to TestPyPI across 2026-04-01 → 2026-04-15
• rc5 ran on @hetz_lba1_bot since 2026-04-14 without issues
• rc6 ran on @hetz_lba1_bot since earlier today, added doc audit + healthcheck fix + uninstall guides

Pre-release validation (all passing)

• `python3 scripts/validate_release.py` — 3 passed, 0 failed
• `uv run ruff format --check src/ tests/` — 260 files clean
• `uv run ruff check src/` — all checks passed
• `uv lock --check` — lockfile in sync
• `uv run pytest` — 2164 passed, 1 skipped, 81.65% coverage
• `uv build` — wheel + sdist built
• All 19 CI checks green on dev (format, ruff, ty, pytest 3.12/3.13/3.14, build, lockfile, docs, pip-audit, bandit, CodeQL, install-test, release-validation, Socket Security, CodeRabbit)

Nathan must do (release guard)

• Review and approve this PR
• Squash-merge to master (Claude Code is blocked from master merges by release guard)
• Tag: `git tag v0.35.1 && git push origin master --tags`
• Approve the `pypi` environment in the release workflow (required reviewer gate)

On tag push, `release.yml` will:

1. Validate tag matches `pyproject.toml` version (`0.35.1`)
2. Run full pytest suite on Python 3.12/3.13/3.14
3. Build wheel + sdist, validate with `twine check` and `check-wheel-contents`
4. Publish to PyPI via trusted publishing (OIDC) — pauses at `pypi` environment for manual approval
5. Create GitHub Release with auto-generated notes and dist artifacts

Post-release verification (after PyPI publishes)

```bash
pip index versions untether # should show 0.35.1
gh release view v0.35.1
pipx upgrade untether && untether --version # should print 0.35.1
scripts/healthcheck.sh --version 0.35.1 # post-deploy health check
```

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • /at one-shot delayed runs with /cancel, per-chat caps, and trigger provenance shown in run footers and /ping.
  • Timezone-aware cron scheduling, run_once crons, cron data-fetch, and non-agent webhook actions (file write, HTTP forward, notify).
  • Hot-reload for trigger and Telegram bridge settings; persisted Telegram polling offset and systemd readiness/stop notifications.

• Bug Fixes

  • Improved multipart webhook handling, rate-limiting behavior, stall-warning accuracy, and JSONL stdout safety; faster, safer restarts.

• Documentation

  • New update/uninstall guides, expanded trigger, cron, SSRF, and group-button authorization docs.

[coderabbitai]

📝 Walkthrough

Walkthrough

Implemented a trigger subsystem (cron/webhook) with timezone-aware scheduling, hot-reloadable trigger/Telegram transport settings, one‑shot /at delayed runs, multipart webhook handling, SSRF protections, run provenance propagation into run metadata/footers, tree-CPU-aware stall detection/suppression, persisted Telegram offset and systemd READY/STOPPING notifications, plus extensive docs and tests.

Changes

Cohort / File(s)	Summary
Trigger system core src/untether/triggers/manager.py, src/untether/triggers/dispatcher.py, src/untether/triggers/cron.py, src/untether/triggers/server.py	New mutable TriggerManager for hot-reload; dispatchers always set RunContext.trigger_source; cron scheduler timezone resolution, run_once behavior, and fetch pre-step; webhook server parses multipart, returns 202 and schedules background dispatch.
Trigger actions & fetch src/untether/triggers/actions.py, src/untether/triggers/fetch.py, src/untether/triggers/ssrf.py	New non-agent webhook actions (file_write, http_forward, notify_only); cron fetch implementations (http/file) with parsing and prompt injection; SSRF validation with DNS checks and blocked-network rules.
Trigger schema & templating src/untether/triggers/settings.py, src/untether/triggers/templating.py, src/untether/triggers/describe.py, src/untether/triggers/__init__.py, src/untether/triggers/auth.py	Schema additions: CronFetchConfig, per-cron timezone, run_once, optional prompt_template, multipart fields, action-driven webhook fields; render_template_fields and describe_cron utilities; structured auth logging.
Telegram bridge & transport src/untether/telegram/bridge.py, src/untether/telegram/loop.py, src/untether/telegram/offset_persistence.py, src/untether/telegram/parsing.py, src/untether/telegram/offset_persistence.py	TelegramBridgeConfig made mutable with update_from() and trigger_manager field; poll loop resumes from persisted update_id, installs /at scheduler, hot-reloads transport and triggers, sends sd_notify READY/STOPPING, and flushes offset via DebouncedOffsetWriter.
Commands & /at scheduler src/untether/telegram/commands/at.py, src/untether/telegram/commands/cancel.py, src/untether/telegram/commands/ping.py, src/untether/telegram/commands/config.py, src/untether/telegram/at_scheduler.py	New /at command and at_scheduler module (install/uninstall, schedule/cancel, per-chat cap, in-memory only); /cancel cancels pending /at; /ping shows trigger summaries; config UI updated for on/off + engine-specific reasoning.
Run provenance & progress src/untether/context.py, src/untether/runner_bridge.py, src/untether/progress.py, src/untether/markdown.py	Added RunContext.trigger_source; runner_bridge seeds progress_tracker.meta["trigger"] from context; ProgressTracker.note_event now merges StartedEvent.meta (not replace); markdown footer includes trigger provenance when present.
Stall detection & proc diagnostics src/untether/utils/proc_diag.py, src/untether/runner_bridge.py	ProcessDiag now aggregates tree CPU ticks; is_tree_cpu_active helper; stall monitor considers active children with a higher threshold, suppresses repeated warnings when children are busy, and exposes separate total vs per-warning counts.
Prompt sanitization & runners src/untether/runner.py, src/untether/runners/*.py	Added JsonlSubprocessRunner.sanitize_prompt to prefix leading-space for flag-like prompts; runners updated to use sanitize_prompt; added config validation warnings (logger.warning) before raising ConfigError in several runners.
Systemd notify & service src/untether/sdnotify.py, contrib/untether.service	New minimal sd_notify client; service unit switched to Type=notify, NotifyAccess=main, faster RestartSec, and OOMPolicy/OOMScoreAdjust changes.
Settings & CLI wiring src/untether/settings.py, src/untether/commands.py, src/untether/cli/run.py	WatchdogSettings gains subagent_timeout; CommandContext gains trigger_manager and default_chat_id; CLI run errors now log structured messages on lock/config failures.
Telegram helpers & persistence src/untether/telegram/client_api.py, src/untether/telegram/topic_state.py, src/untether/telegram/engine_overrides.py	Added logs for message deletion and topic-state persistence; engine overrides add max reasoning level and helpers to surface engine default effort.
Offset persistence & debounce src/untether/telegram/offset_persistence.py, src/untether/telegram/parsing.py	New offset file last_update_id.json, load/save APIs, DebouncedOffsetWriter for coalesced writes; parsing.poll_incoming accepts on_offset_advanced callback to feed the writer.
Tests & docs tests/** (many new/updated), docs/**, CHANGELOG.md, pyproject.toml, README etc.	Extensive unit/integration tests for triggers, SSRF, fetch, actions, at_scheduler, offset persistence, sd_notify, stall behavior, and UI changes. Documentation and changelog updated for v0.35.1; entry point untether.command_backends.at added and version bumped.
Misc / Ops scripts/healthcheck.sh, .github/workflows/*, zensical.toml	Bugfix to shell arithmetic to avoid set -e breakage; CI workflow action pin updates; website notify payload construction changed; docs nav updated with Update/Uninstall pages.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Telegram
    participant TelegramLoop
    participant TriggerManager
    participant CronScheduler
    participant TriggerDispatcher
    participant FetchModule
    participant SSRFValidator
    participant RunJob

    User->>Telegram: Edit untether.toml (crons/webhooks)
    Telegram->>TelegramLoop: Config change detected (watch_config=true)
    TelegramLoop->>TriggerManager: update(new_settings)
    TriggerManager->>TriggerManager: Replace _crons and _webhooks lists
    TriggerManager-->>TelegramLoop: Updated (info log with counts)
    
    Note over CronScheduler: Tick loop running continuously
    CronScheduler->>TriggerManager: Read current crons and default_timezone
    CronScheduler->>CronScheduler: _resolve_now() - convert UTC to local tz
    CronScheduler->>CronScheduler: Check if minute/hour matches schedule
    
    alt Cron matches
        CronScheduler->>FetchModule: fetch configured data (if present)
        alt Fetch succeeds
            FetchModule-->>CronScheduler: fetched_data + rendered_prompt
        else Fetch fails
            FetchModule-->>CronScheduler: None (abort dispatch)
        end
        
        CronScheduler->>TriggerDispatcher: dispatch_cron(cron_config)
        TriggerDispatcher->>SSRFValidator: validate_url_with_dns() if fetch used
        alt SSRF blocked
            SSRFValidator-->>TriggerDispatcher: SSRFError
            TriggerDispatcher->>Telegram: Send failure notification
        else SSRF passed
            TriggerDispatcher->>RunJob: run_job(prompt, trigger_source="cron:id")
        end
        
        alt run_once enabled
            CronScheduler->>TriggerManager: remove_cron(id)
        end
    end

Loading

sequenceDiagram
    participant Client as External Client
    participant WebhookServer
    participant TriggerManager
    participant RateLimiter
    participant Dispatcher
    participant Actions as Action Executor
    participant SSRF as SSRF Validator
    participant HTTPClient
    participant Telegram

    Client->>WebhookServer: POST /webhook/path with auth header
    WebhookServer->>TriggerManager: webhook_for_path(path)
    WebhookServer->>WebhookServer: Verify auth (bearer/HMAC)
    
    alt Auth fails
        WebhookServer-->>Client: 401 Unauthorized
    else Auth passes
        WebhookServer->>RateLimiter: allow(webhook_id)
        
        alt Rate limited
            WebhookServer-->>Client: 429 Too Many Requests
        else Rate OK
            WebhookServer->>WebhookServer: Parse multipart/JSON payload
            WebhookServer->>WebhookServer: Save multipart files if present
            WebhookServer-->>Client: 202 Accepted (fire-and-forget)
            
            par Async dispatch (background)
                WebhookServer->>Dispatcher: Schedule dispatch task
                alt webhook.action == "agent_run"
                    Dispatcher->>Dispatcher: Render prompt_template
                    Dispatcher->>Dispatcher: Create RunContext(trigger_source)
                else action == "file_write"
                    Dispatcher->>Actions: execute_file_write()
                    Actions->>Actions: Validate path, deny-globs, size
                    Actions-->>Dispatcher: success + message
                else action == "http_forward"
                    Dispatcher->>Actions: execute_http_forward()
                    Actions->>SSRF: validate_url_with_dns(forward_url)
                    SSRF-->>Actions: Validated (or blocked)
                    Actions->>HTTPClient: POST raw body to forward_url
                    HTTPClient-->>Actions: response
                    Actions-->>Dispatcher: success + status
                else action == "notify_only"
                    Dispatcher->>Actions: execute_notify_message()
                    Actions-->>Dispatcher: rendered_message
                end
                Dispatcher->>Telegram: Send notification if notify_on_success/failure
            end
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Possibly related issues

• feat: trigger visibility — indicators, discovery, and run history #271 — Implements trigger provenance in run context and footer, matching the trigger-visibility objectives.
• docs: add update and uninstall guides + README transparency section #305 — Adds update/uninstall docs and README transparency items present in this PR.
• healthcheck.sh exits prematurely due to ((var++)) under set -e #302 — Fixes healthcheck.sh arithmetic/post-increment issue; same change included here.

Possibly related PRs

• fix: rc6 integration test fixes (#145-#150) #151 — Related to runner-bridge and progress metadata handling (overlaps with meta seeding and progress merging).
• chore: staging 0.34.5rc3 — docs screenshots + bug fixes #130 — Related to stall-detection and proc-diag/tree-CPU logic changes.
• feat: RC4 — /config UX overhaul, resume line toggle, cost budget, model metadata #132 — Related to footer formatting (markdown.format_meta_line) changes.

Poem

🐰 Hopping through crons, webhooks, and time,

I stitch triggers and safety into a rhyme.
/at waits a moment, then springs into run,
sd_notify whispers when startup is done.
Docs and tests bundled — now the festival's begun! 🥕

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	aiohttp@​3.13.3 ⏵ 3.13.5	+1	+10

View full report

[Nathan Schram (nathanschram)]

Unblocked by merging #310 (sync master → dev). The applies_to: frontmatter from master's v0.35.0 release commit had never back-merged to dev; -X ours merge preserved both master's additions and dev's v0.35.1 content. All pre-sync validation re-passing on the updated PR.

[coderabbitai]

Actionable comments posted: 16

Note

Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

docs/reference/specification.md (1)

1-8: ⚠️ Potential issue | 🟡 Minor

Synchronise version reference in the Scope section.

Line 1 says v0.35.1, but Line 7 still says Untether v0.35.0 specifies:. This leaves the normative version ambiguous.

🛠️ Proposed fix

- Untether v0.35.0 specifies:
+ Untether v0.35.1 specifies:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/specification.md` around lines 1 - 8, The header shows
"Untether Specification v0.35.1" but the Scope text still reads "Untether
v0.35.0 specifies:"; update the Scope sentence to match the document version by
changing "Untether v0.35.0 specifies:" to "Untether v0.35.1 specifies:" (locate
the string "Untether v0.35.0 specifies:" in the specification.md and make the
version consistent with the header).

tests/test_claude_control.py (1)

79-89: ⚠️ Potential issue | 🟡 Minor

Reset the runner registries before each test as well.

This fixture only clears after yield, so the first test in this module can still inherit dirty global state from an earlier module. With these registries living at module scope, that makes the new _PLAN_EXIT_APPROVED coverage order-dependent. Run the same cleanup before yield too.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_claude_control.py` around lines 79 - 89, The fixture
_clear_registries currently only clears globals after the test (after yield),
which allows earlier state to leak into the first test; modify the
_clear_registries fixture to perform the same cleanup both before yield and
after yield by calling _ACTIVE_RUNNERS.clear(), _SESSION_STDIN.clear(),
_REQUEST_TO_SESSION.clear(), _REQUEST_TO_INPUT.clear(),
_HANDLED_REQUESTS.clear(), _DISCUSS_COOLDOWN.clear(),
_PLAN_EXIT_APPROVED.clear(), and re-importing _DISCUSS_FEEDBACK_REFS from
untether.telegram.commands.claude_control before the yield so the registries are
reset for each test start as well as test teardown.

src/untether/telegram/commands/config.py (2)

1859-1866: ⚠️ Potential issue | 🟡 Minor

Add a toast for the new rs:max action.

answer_early=True makes this table the confirmation path for button presses, but rs:max currently falls through to None. Selecting Max will clear the spinner without any feedback.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/telegram/commands/config.py` around lines 1859 - 1866, The rs
mapping currently lacks an entry for the 'rs:max' action so pressing the Max
button (with answer_early=True) falls through and gives no toast; add a "max":
"Reasoning: max" (or equivalent user-facing string) to the "rs" dict so the
'rs:max' action produces the same confirmation/toast as the other rs actions and
ensure the key matches the action name 'rs:max' used by the button handler.

---

1088-1113: ⚠️ Potential issue | 🟠 Major

Guard reasoning actions against engine-supported levels.

This branch accepts any _RS_ACTIONS value, so config:rs:max can still be persisted for Codex even though allowed_reasoning_levels("codex") excludes it. That leaves chat prefs holding a value the downstream engine-specific arg builder may not understand.

Suggested fix

     if action in _RS_ACTIONS:
         level = _RS_ACTIONS[action]
+        if level not in allowed_reasoning_levels(current_engine):
+            logger.warning(
+                "config.reasoning.unsupported_level",
+                chat_id=chat_id,
+                engine=current_engine,
+                action=action,
+                level=level,
+            )
+            await _page_reasoning(ctx)
+            return
         current = await prefs.get_engine_override(chat_id, current_engine)
         updated = EngineOverrides(
             model=current.model if current else None,
             reasoning=level,

Based on learnings: Build CLI arguments for all 6 engines with model/reasoning/permission flags; engine-specific flag names and defaults.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/telegram/commands/config.py` around lines 1088 - 1113, The code
stores any value from _RS_ACTIONS into EngineOverrides without checking whether
the chosen reasoning level is valid for the engine; update the logic in the
branch handling action in _RS_ACTIONS to validate level against
allowed_reasoning_levels(current_engine) (or similar engine validation function)
before persisting: fetch allowed = allowed_reasoning_levels(current_engine) (or
compute allowed set), if level not in allowed then map it to a safe default
(e.g., the highest supported level or None) or return an error message to user,
and only then call prefs.set_engine_override(chat_id, current_engine, updated)
with the validated level; use the same symbols shown (prefs.get_engine_override,
EngineOverrides, prefs.set_engine_override, _RS_ACTIONS) so reviewers can locate
and update the code path.

🟡 Minor comments (12)

src/untether/triggers/ssrf.py-190-222 (1)

190-222: ⚠️ Potential issue | 🟡 Minor

DNS rebinding TOCTOU consideration.

The validation approach has an inherent TOCTOU (time-of-check to time-of-use) gap: DNS is resolved during validation, but the actual HTTP client will resolve DNS again when making the request. A malicious DNS server could return a public IP during validation and a private IP during the actual request (DNS rebinding attack).

This is a known limitation that's difficult to fully mitigate without using the resolved IP directly for the connection. Consider either:

1. Documenting this limitation clearly
2. Using the validated IP addresses directly when making the request (if httpx/aiohttp supports connecting to a specific IP)

For most use cases, the current protection is reasonable since it blocks obvious SSRF attempts. DNS rebinding requires a sophisticated attacker controlling DNS.

httpx connect to specific IP address instead of hostname

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/ssrf.py` around lines 190 - 222, The current
validate_url_with_dns suffers from DNS rebinding TOCTOU because it only
validates DNS at check time; change it to return (or expose) a validated numeric
IP to be used for the actual connection so the HTTP client can connect to that
IP instead of resolving the hostname again: update resolve_and_validate (or add
a new resolve_and_select function) to return the chosen allowed
ipaddress.IPv4Address/IPv6Address, update validate_url_with_dns to call that and
return both the validated_url and the resolved_ip (or a small struct), and
modify callers to make httpx connect to "http(s)://<resolved_ip>:port/..." while
setting the original hostname in the Host header (or using httpx transport that
binds to the IP) so name-based TLS/Host checks still work; reference
resolve_and_validate, validate_url_with_dns, validate_url and ensure callers
preserve the original hostname in request headers when connecting to the numeric
IP.

docs/reference/runners/claude/runner.md-182-182 (1)

182-182: ⚠️ Potential issue | 🟡 Minor

Clarify that --effort max is Opus 4.6 only.

Verification confirms max is a valid value for the --effort flag, but upstream documentation indicates it is restricted to Opus 4.6. Update line 182 to note this model requirement.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/runners/claude/runner.md` at line 182, Update the docs bullet
that mentions the `--effort <level>` flag to clarify that the `max` value is
only supported on Opus 4.6: change the line "* add `--effort <level>` if a
reasoning override is set (low/medium/high/max)." to explicitly note "`--effort
max` (Opus 4.6 only)" and ensure the list of valid values remains
"low/medium/high" for other models while documenting that "max" requires Opus
4.6.

docs/how-to/update.md-17-27 (1)

17-27: ⚠️ Potential issue | 🟡 Minor

These standalone shell blocks still trip MD046.

The fenced blocks at Line 19 and Line 25 do not match the repo's configured code-block style, so this new page ships with known markdownlint warnings. Please convert them to the expected indented form or align the file with whatever style the docs lint is enforcing.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/update.md` around lines 17 - 27, The markdown uses fenced code
blocks for the commands ("untether --version" and "systemctl --user restart
untether") which violates the repo's MD046 rule; replace those fenced blocks
with the repository's preferred code-block style (e.g., convert to indented code
blocks or whatever the docs lint expects) so the commands are formatted without
backticks and the markdownlint warning is resolved.

docs/how-to/troubleshooting.md-247-254 (1)

247-254: ⚠️ Potential issue | 🟡 Minor

/cancel is described as read-only here, but the implementation deletes the timers.

handle_cancel() now calls cancel_pending_for_chat(chat_id) on a bare /cancel, so following this advice will actually remove the pending /at jobs. Please either document it as a destructive cancel action or point readers at a non-destructive inspection command.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/troubleshooting.md` around lines 247 - 254, The docs incorrectly
state `/cancel` is read-only while the implementation in handle_cancel() calls
cancel_pending_for_chat(chat_id) and deletes timers; update the troubleshooting
text to reflect that `/cancel` is destructive (it removes pending /at jobs) or
add a note pointing to a non-destructive inspection command (e.g., a specific
"list_pending" or "inspect_pending" endpoint/command) — mention the exact
function names handle_cancel() and cancel_pending_for_chat(chat_id) so
maintainers can find the behavior in code and either change the docs to warn
users or update the docs to reference the non-destructive inspection command.

docs/reference/config.md-455-459 (1)

455-459: ⚠️ Potential issue | 🟡 Minor

Clarify restart-only vs hot-reload semantics for trigger settings.

This note can conflict with other docs that describe trigger controls as hot-reloadable. Please align the exact behaviour for enabled/rate-limit/server settings in one canonical way to avoid operator mistakes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/config.md` around lines 455 - 459, The tip text is ambiguous
about which trigger settings hot-reload applies to; update the copy so it
consistently states that when watch_config = true only
webhook/cron/schedule/timezone changes are hot-reloaded and that server settings
(host, port, rate_limit) and the enabled toggle require a restart; also align
and cross-reference the Triggers reference — Hot-reload section
(triggers/triggers.md) so both places use the exact same canonical phrasing for
watch_config, enabled, host, port, and rate_limit semantics to avoid
contradictions.

docs/how-to/operations.md-167-175 (1)

167-175: ⚠️ Potential issue | 🟡 Minor

Hot-reload list likely overstates triggers.enabled behaviour.

Line 167 lists triggers.enabled as immediately hot-reloadable, but other docs in this PR describe the trigger enabled toggle as restart-only. Please align this to one source of truth.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/operations.md` around lines 167 - 175, The docs currently list
`triggers.enabled` as hot-reloadable but other docs say it is restart-only;
update this section so `triggers.enabled` is listed under the **Restart-only**
group (remove it from the hot-reload list), and ensure any related mention
(e.g., "Trigger system" line and its bullets) no longer claim immediate
hot-reload for `triggers.enabled`; edit the entries referencing
`triggers.enabled` to match the restart-only behavior described elsewhere.

docs/how-to/schedule-tasks.md-9-13 (1)

9-13: ⚠️ Potential issue | 🟡 Minor

Add a language tag to the fenced code block (MD040).

This will keep docs lint clean and consistent with markdownlint expectations.

Suggested fix

-```
+```text
 /at 30m Check the build
 /at 2h Review the PR feedback
 /at 60s Say hello

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/how-to/schedule-tasks.md around lines 9 - 13, The fenced code block in
docs/how-to/schedule-tasks.md is missing a language tag (MD040); update the
opening fence from to a tagged fence such astext for the shown block
containing "/at 30m Check the build", "/at 2h Review the PR feedback", and "/at
60s Say hello" so markdownlint stops flagging it and the docs remain consistent.

</details>

</blockquote></details>
<details>
<summary>docs/reference/changelog.md-38-38 (1)</summary><blockquote>

`38-38`: _⚠️ Potential issue_ | _🟡 Minor_

**Don't point release docs at the moving `dev` branch.**

After this release is merged to `master`, this link will show whatever `dev` contains later, not the `v0.35.1` notes users are reading now. A relative link or tag-specific link keeps the release docs stable.


<details>
<summary>🔗 Suggested fix</summary>

```diff
-See [CHANGELOG.md](https://github.com/littlebearapps/untether/blob/dev/CHANGELOG.md#v0351-2026-04-14) for full implementation details.
+See [CHANGELOG.md](../../CHANGELOG.md#v0351-2026-04-14) for full implementation details.
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@docs/reference/changelog.md` at line 38, The link in the line that reads "See
[CHANGELOG.md](https://github.com/littlebearapps/untether/blob/dev/CHANGELOG.md#v0351-2026-04-14)"
points at the moving dev branch; update that anchor to a stable target by
replacing the URL with either a relative/stable repo link (e.g.,
../CHANGELOG.md#v0.35.1 or /CHANGELOG.md#v0.35.1) or a tag-specific GitHub blob
URL for v0.35.1 so the "See [CHANGELOG.md](...)" reference always resolves to
the v0.35.1 notes after merge.
```

</details>

</blockquote></details>
<details>
<summary>docs/how-to/webhooks-and-cron.md-137-141 (1)</summary><blockquote>

`137-141`: _⚠️ Potential issue_ | _🟡 Minor_

**These new code blocks are tripping markdownlint.**

The added fences are currently hitting MD040/MD046: the command/output examples at Lines 289, 301, and 308 need a language, and the other new fenced blocks should match the repo's configured code-block style.




Also applies to: 255-261, 275-281, 289-310

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/webhooks-and-cron.md` around lines 137 - 141, The new fenced code
blocks in docs/how-to/webhooks-and-cron.md are missing language tags and
inconsistent with the repo's code-block style; update the fences so the toml
snippet containing "[triggers]" uses a "toml" tag, mark command examples with
"bash" (or "sh") and mark command output examples with a neutral tag like "text"
(or "console") to satisfy MD040/MD046, and make all other new fences (the
earlier blocks and the command/output examples) use the same consistent tagging
convention throughout the file.
```

</details>

</blockquote></details>
<details>
<summary>src/untether/telegram/offset_persistence.py-56-58 (1)</summary><blockquote>

`56-58`: _⚠️ Potential issue_ | _🟡 Minor_

**Reject booleans for `last_update_id`.**

`bool` is an `int` in Python, so `{"last_update_id": true}` is accepted here as `1`. That turns a malformed state file into a bogus offset.



<details>
<summary>Possible fix</summary>

```diff
-    if isinstance(raw, int) and raw >= 0:
+    if isinstance(raw, int) and not isinstance(raw, bool) and raw >= 0:
         return raw
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/untether/telegram/offset_persistence.py` around lines 56 - 58, The code
treating raw = data.get("last_update_id") accepts booleans because bool is a
subclass of int; update the validation in offset_persistence so that booleans
are explicitly rejected (e.g., check type(raw) is int or add "and not
isinstance(raw, bool)") before returning the value and still ensure raw >= 0;
specifically modify the conditional around raw (in the function handling
last_update_id) to exclude bools while preserving the non-negative integer
check.
```

</details>

</blockquote></details>
<details>
<summary>CHANGELOG.md-3-105 (1)</summary><blockquote>

`3-105`: _⚠️ Potential issue_ | _🟡 Minor_

**Add the missing `### tests` subsection for `v0.35.1`.**

This release entry skips the tests section even though the release clearly includes new coverage and validation work. Please keep the release notes aligned with the repo's changelog structure.



Based on learnings, "Update `CHANGELOG.md` with every version bump using format `## vX.Y.Z (YYYY-MM-DD)` with subsections for fixes, changes, breaking, docs, and tests".

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 3 - 105, Add a missing "### tests" subsection
under the existing "## v0.35.1 (2026-04-15)" header in CHANGELOG.md that lists
the test work included in this release (e.g. "13 new tests in
test_trigger_manager.py; existing 2038 tests still pass" and any other test
coverage/validation notes referenced in the release), keeping the same changelog
style and placement alongside the fixes/changes/docs subsections so the entry
includes fixes, changes, docs, and tests.
```

</details>

</blockquote></details>
<details>
<summary>src/untether/triggers/server.py-46-54 (1)</summary><blockquote>

`46-54`: _⚠️ Potential issue_ | _🟡 Minor_

**Use `asyncio.get_running_loop()` instead of `asyncio.get_event_loop()` and avoid direct StreamReader instantiation.**

The `asyncio.get_event_loop()` call is deprecated in Python 3.10+. Additionally, `streams.StreamReader` should not be instantiated directly; it's an internal implementation detail of aiohttp. Consider refactoring this logic to use aiohttp's public API or an alternative approach that aligns with Python 3.12+ best practices and the anyio async pattern guideline.

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/server.py` around lines 46 - 54, Replace the deprecated
asyncio.get_event_loop() call with asyncio.get_running_loop() and stop
instantiating streams.StreamReader directly; instead create an async-compatible
payload from raw_body (e.g., using aiohttp.payload.BytesPayload or another
public aiohttp payload helper) and construct the MultipartReader via aiohttp's
public API (e.g., MultipartReader.from_payload or other public factory) using
the Content-Type header built from content_type; adjust the code paths
referencing raw_body, content_type, and MultipartReader to consume the payload
rather than a directly instantiated StreamReader.
```

</details>

</blockquote></details>

</blockquote></details>

<details>
<summary>🧹 Nitpick comments (12)</summary><blockquote>

<details>
<summary>tests/test_describe_cron.py (1)</summary><blockquote>

`73-85`: **Add fallback regression cases for unsupported `dom`/`mon` and invalid DOW.**

Please add explicit cases for `*/N` in day/month fields and out-of-range DOW values so fallback behaviour stays locked in.


<details>
<summary>Suggested test additions</summary>

```diff
         [
             "*/15 * * * *",  # stepped minutes
             "0 */4 * * *",  # stepped hours
+            "0 9 */2 * *",  # stepped day-of-month
+            "0 9 * */2 *",  # stepped month
             "0 9 1 * *",  # day-of-month
             "0 9 * 6 *",  # specific month
+            "0 9 * * 8",  # invalid day-of-week
+            "0 9 * * 1-5/2",  # stepped day-of-week
             "invalid",  # totally wrong
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_describe_cron.py` around lines 73 - 85, Update the pytest
parameter list in tests/test_describe_cron.py (the pytest.mark.parametrize block
for "schedule") to include explicit fallback regression cases: add a
day-of-month stepped case like "0 9 */2 * *", a month-stepped case like "0 9 *
*/3 *", an out-of-range numeric DOW like "0 9 * * 8", and an invalid DOW token
like "0 9 * * MON" so the test covers unsupported dom/mon "*/N" and invalid DOW
fallback behavior.
```

</details>

</blockquote></details>
<details>
<summary>src/untether/triggers/settings.py (1)</summary><blockquote>

`143-153`: **Consider extracting shared timezone validation.**

Both `_validate_timezone` and `_validate_default_timezone` perform identical `ZoneInfo` validation. You could extract a module-level helper to reduce duplication:

<details>
<summary>♻️ Optional refactor</summary>

```diff
+def _check_iana_timezone(tz: str) -> None:
+    """Raise ValueError if tz is not a valid IANA timezone."""
+    try:
+        ZoneInfo(tz)
+    except (ZoneInfoNotFoundError, KeyError):
+        raise ValueError(
+            f"unknown timezone {tz!r}; use IANA names like 'Australia/Melbourne'"
+        ) from None
+
+
 class CronConfig(BaseModel):
     ...
     `@field_validator`("timezone")
     `@classmethod`
     def _validate_timezone(cls, v: str | None) -> str | None:
         if v is not None:
-            try:
-                ZoneInfo(v)
-            except (ZoneInfoNotFoundError, KeyError):
-                raise ValueError(
-                    f"unknown timezone {v!r}; use IANA names like 'Australia/Melbourne'"
-                ) from None
+            _check_iana_timezone(v)
         return v
```
</details>




Also applies to: 171-181

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/settings.py` around lines 143 - 153, Both
_validate_timezone and _validate_default_timezone duplicate IANA timezone
validation; extract that logic into a module-level helper (e.g.,
validate_iana_timezone(value: str | None) -> str | None) and have both class
validators call it. Update the validators _validate_timezone and
_validate_default_timezone to delegate to the new helper and preserve the same
error type/message (raise ValueError with the existing message) and return
behavior so behavior remains identical.
```

</details>

</blockquote></details>
<details>
<summary>src/untether/triggers/manager.py (1)</summary><blockquote>

`80-82`: **Avoid returning mutable internal state from `crons`.**

Line 82 returns the internal list directly, so external callers can mutate manager state and bypass `update()`/`remove_cron()` invariants. Prefer returning a snapshot.



<details>
<summary>Proposed fix</summary>

```diff
     `@property`
     def crons(self) -> list[CronConfig]:
         """Current cron list — the scheduler iterates this each tick."""
-        return self._crons
+        return list(self._crons)
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/manager.py` around lines 80 - 82, The crons() method
exposes internal mutable state by returning self._crons directly; change it to
return an immutable snapshot (e.g., a shallow copy or tuple) so callers cannot
mutate the manager's internal list and bypass invariants enforced by update()
and remove_cron(); update the impl of crons() to return list(self._crons) or
tuple(self._crons) and ensure any callers expecting mutability are adjusted to
work with the snapshot.
```

</details>

</blockquote></details>
<details>
<summary>.github/workflows/notify-website.yml (1)</summary><blockquote>

`20-24`: **Make the dispatch step fail on HTTP errors.**

Right now this can pass even when GitHub returns 4xx/5xx, which hides failed website notifications.


<details>
<summary>Suggested hardening</summary>

```diff
-          curl -s -X POST \
+          curl --fail-with-body --show-error --silent -X POST \
             -H "Accept: application/vnd.github+json" \
+            -H "Content-Type: application/json" \
             -H "Authorization: Bearer ${{ secrets.WEBSITE_DISPATCH_TOKEN }}" \
             https://api.github.com/repos/littlebearapps/littlebearapps.com/dispatches \
             -d "$(jq -n --arg tag "$TAG_NAME" '{"event_type":"release-published","client_payload":{"repo":"untether","tag":$tag}}')"
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/notify-website.yml around lines 20 - 24, The curl step
that posts to the repository dispatch currently doesn't fail on HTTP errors;
update the curl invocation (the curl -s -X POST call that uses $TAG_NAME and
WEBSITE_DISPATCH_TOKEN) to fail on non-2xx responses by adding the --fail (or
-f) flag and keep useful output with -S, or capture the HTTP status and exit
non-zero when it indicates an error; ensure the workflow exits with a non-zero
code on 4xx/5xx so the dispatch step correctly fails the job.
```

</details>

</blockquote></details>
<details>
<summary>tests/test_trigger_dispatcher.py (1)</summary><blockquote>

`265-267`: **Prefer condition-based waiting over fixed 10ms sleeps in async tests.**

These sleeps can intermittently race in slower CI runners.


<details>
<summary>Deterministic wait pattern</summary>

```diff
+async def _wait_for_calls(capture: RunJobCapture, *, min_calls: int = 1) -> None:
+    with anyio.fail_after(1):
+        while len(capture.calls) < min_calls:
+            await anyio.sleep(0)
+
 ...
-        await anyio.sleep(0.01)
+        await _wait_for_calls(run_job)
         tg.cancel_scope.cancel()

 ...
-        await anyio.sleep(0.01)
+        await _wait_for_calls(run_job)
         tg.cancel_scope.cancel()
```
</details>


Also applies to: 291-293

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_dispatcher.py` around lines 265 - 267, The test uses a
fixed await anyio.sleep(0.01) after calling
dispatcher.dispatch_webhook(_make_webhook(), "Plain"), which can race on slow
CI; replace the fixed sleep with a deterministic condition-based wait such as
awaiting an anyio.Event or polling a predicate with timeout that signals when
the webhook handler has completed (e.g., set an Event inside the handler or
check a shared flag updated by dispatch_webhook), then await that event or
predicate before calling tg.cancel_scope.cancel(); apply the same pattern for
the similar block around lines that call dispatch_webhook at 291-293.
```

</details>

</blockquote></details>
<details>
<summary>docs/tutorials/install.md (1)</summary><blockquote>

`441-441`: **Optional wording polish for repeated sentence openings.**

Three consecutive sentences start with “To”, which reads a bit repetitive.

<details>
<summary>✍️ Suggested wording tweak</summary>

```diff
-To uninstall completely (CLI, config, and state), see the [uninstall guide](../how-to/uninstall.md). To learn more about updates, see [Update Untether](../how-to/update.md).
+For complete removal (CLI, config, and state), see the [uninstall guide](../how-to/uninstall.md). For update details, see [Update Untether](../how-to/update.md).
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@docs/tutorials/install.md` at line 441, The three consecutive sentences
starting with "To" are repetitive; update the sentence that begins "To uninstall
completely (CLI, config, and state), see the [uninstall guide]..." and/or the
sentence "To learn more about updates, see [Update Untether]..." so the openings
vary—e.g., change the uninstall sentence to "For a complete uninstall (CLI,
config, and state), see the [uninstall guide]" and the updates sentence to
"Learn more about updates in [Update Untether]"—make sure the revised lines
preserve the links and meaning.
```

</details>

</blockquote></details>
<details>
<summary>tests/test_trigger_templating.py (1)</summary><blockquote>

`67-86`: **Add `-> None` to the new test methods.**

The four added tests are unannotated, which drifts from the repo’s Python typing baseline.  


As per coding guidelines, "Add type hints on all public functions in Python".

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_templating.py` around lines 67 - 86, Add explicit return
type annotations -> None to the four test methods in TestRenderTemplateFields:
test_substitution, test_no_untrusted_prefix, test_nested_path, and
test_missing_field_renders_empty so they conform to the repo typing baseline;
open the class TestRenderTemplateFields and update each method signature to
include "-> None" while leaving the body and assertions unchanged (these tests
call render_template_fields and reference _UNTRUSTED_PREFIX but only the method
signatures need the type hint).
```

</details>

</blockquote></details>
<details>
<summary>tests/test_callback_dispatch.py (1)</summary><blockquote>

`484-486`: **Minor: Inline imports of `patch` are redundant.**

Consider importing `patch` at module level alongside the existing `AsyncMock` import from `unittest.mock`. This is a minor style nit — not blocking.



<details>
<summary>♻️ Suggested refactor</summary>

```diff
 from unittest.mock import AsyncMock
+from unittest.mock import patch

 import pytest
```

Then remove the inline `from unittest.mock import patch` statements inside each test function.
</details>


Also applies to: 527-529, 557-559

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_callback_dispatch.py` around lines 484 - 486, Move the inline
"from unittest.mock import patch" imports to the module-level imports alongside
AsyncMock (i.e., add patch to the existing unittest.mock import) and remove the
redundant inline import lines inside test functions; specifically update tests
that use with patch("untether.telegram.commands.dispatch.get_command",
return_value=backend): and other occurrences (the similar blocks at the other
noted locations) to rely on the module-level patch import instead.
```

</details>

</blockquote></details>
<details>
<summary>tests/test_trigger_server.py (1)</summary><blockquote>

`418-463`: **Path traversal test could be more explicit.**

The sanitization test correctly verifies no escape above `tmp_path` (line 462), but the primary assertion on line 460 is weak — it only checks *something* was written, not *what* the sanitized filename became.



<details>
<summary>♻️ Suggested improvement</summary>

Consider verifying the actual sanitized filename. Based on common sanitization patterns, the filename might become something like `passwd` or `upload.bin`:

```diff
-    # Must land inside the expected directory, not escape.
-    assert (dest / "upload.bin").exists() or any(dest.glob("*"))
+    # Must land inside the expected directory with sanitized name, not escape.
+    written_files = list(dest.glob("*"))
+    assert len(written_files) == 1, f"expected exactly one file, got {written_files}"
+    assert written_files[0].read_bytes() == b"evil"
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_server.py` around lines 418 - 463, The test
test_multipart_unsafe_filename_sanitised currently only asserts that "something"
was written to dest which is weak; update the assertions to explicitly verify
the sanitized filename and that it did not retain traversal components. In the
test (using variables dest, tmp_path, file_destination template
"{{file.filename}}", and the POST to "/hooks/mp"), enumerate files in dest and
assert there is exactly one uploaded file whose name contains no path separators
(no ".." or "/" or "\"), and assert its basename equals the expected sanitized
name (e.g., "passwd" or "upload.bin" depending on your sanitizer) or otherwise
matches the sanitizer's deterministic output; keep the existing check ensuring
no file was written outside tmp_path.
```

</details>

</blockquote></details>
<details>
<summary>CLAUDE.md (1)</summary><blockquote>

`205-226`: **Consider avoiding exact per-file test counts in this long-lived doc.**

These numbers drift quickly and create recurring doc churn. Prefer qualitative scope descriptions (or generate counts automatically in CI).

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@CLAUDE.md` around lines 205 - 226, The CLAUDE.md listing includes exact
per-file test counts (e.g., "test_exec_runner.py — 22 tests") which will drift;
update the entries that reference individual test files (like
test_exec_runner.py, test_build_args.py, test_trigger_ssrf.py, etc.) to remove
hard-coded numbers and instead use qualitative scopes or summaries (e.g., "tests
covering event tracking, recent_events ring buffer, PID in StartedEvent meta")
or replace the whole block with a generated summary inserted by CI;
alternatively add a note that counts are auto-generated and switch to a script
in CI to inject current counts into the doc instead of maintaining numeric
literals manually.
```

</details>

</blockquote></details>
<details>
<summary>tests/test_exec_bridge.py (1)</summary><blockquote>

`3953-3978`: **Use the shared event factories in these new tests.**

These cases reintroduce hand-built `Action`/`ActionEvent` payloads, which makes the tests drift-prone when the event contract changes. Reusing the existing factories keeps the fixtures aligned with production events.


As per coding guidelines, "Use EventFactory for event construction, never construct dataclasses directly."


Also applies to: 4067-4075

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_exec_bridge.py` around lines 3953 - 3978, Replace the
hand-constructed Action and ActionEvent instances with the shared event factory:
instead of calling Action(id="a1", kind="tool", title="Read") and
ActionEvent(...), use the project's EventFactory (e.g.,
EventFactory.action_event(...) or EventFactory.create_action_event(...)) to
build the same started-phase events and pass them to edits.on_event; do the same
for the second event (a2/Grep) and the other occurrence around the 4067-4075
region so tests use the centralized factory rather than direct dataclass
construction.
```

</details>

</blockquote></details>
<details>
<summary>tests/test_trigger_manager.py (1)</summary><blockquote>

`71-85`: **Consider adding type annotations to list fields.**

The `tasks` and `calls` fields lack element type annotations, which reduces IDE support and type checker effectiveness.


<details>
<summary>🔧 Suggested type annotations</summary>

```diff
 `@dataclass`
 class FakeTaskGroup:
-    tasks: list = field(default_factory=list)
+    tasks: list[tuple[Any, tuple[Any, ...]]] = field(default_factory=list)

     def start_soon(self, fn, *args):
         self.tasks.append((fn, args))


 `@dataclass`
 class RunJobCapture:
-    calls: list = field(default_factory=list)
+    calls: list[tuple[Any, ...]] = field(default_factory=list)

     async def __call__(self, *args, **kwargs):
         self.calls.append(args)
```
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

```
Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_manager.py` around lines 71 - 85, The dataclass list
fields lack element type annotations which harms type checking; update
FakeTaskGroup.tasks to a typed list e.g. List[Tuple[Callable[..., Any],
Tuple[Any, ...]]] and update RunJobCapture.calls to List[Tuple[Any, ...]] (or a
more specific tuple type if known), add the necessary imports (from typing
import List, Tuple, Callable, Any) and keep the existing start_soon and async
__call__ behavior intact so type checkers and IDEs can infer element types for
FakeTaskGroup.start_soon and RunJobCapture.__call__.
```

</details>

</blockquote></details>

</blockquote></details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro

**Run ID**: `68e1a01f-8ea5-4c51-8fc1-1e36f17fbcc6`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between e5bff3c93e3335f72ecf7b72dfa566aa2b992a18 and 909fbf586aa2c9fdeb80fe8ab0f048988d9c969d.

</details>

<details>
<summary>⛔ Files ignored due to path filters (1)</summary>

* `uv.lock` is excluded by `!**/*.lock`

</details>

<details>
<summary>📒 Files selected for processing (110)</summary>

* `.claude/rules/runner-development.md`
* `.claude/rules/telegram-transport.md`
* `.claude/rules/testing-conventions.md`
* `.claude/skills/untether-architecture/SKILL.md`
* `.github/workflows/ci.yml`
* `.github/workflows/notify-website.yml`
* `.github/workflows/release.yml`
* `CHANGELOG.md`
* `CLAUDE.md`
* `README.md`
* `contrib/untether.service`
* `docs/explanation/architecture.md`
* `docs/how-to/group-chat.md`
* `docs/how-to/index.md`
* `docs/how-to/inline-settings.md`
* `docs/how-to/interactive-approval.md`
* `docs/how-to/model-reasoning.md`
* `docs/how-to/operations.md`
* `docs/how-to/plan-mode.md`
* `docs/how-to/schedule-tasks.md`
* `docs/how-to/security.md`
* `docs/how-to/troubleshooting.md`
* `docs/how-to/uninstall.md`
* `docs/how-to/update.md`
* `docs/how-to/voice-notes.md`
* `docs/how-to/webhooks-and-cron.md`
* `docs/reference/changelog.md`
* `docs/reference/commands-and-directives.md`
* `docs/reference/config.md`
* `docs/reference/dev-instance.md`
* `docs/reference/glossary.md`
* `docs/reference/integration-testing.md`
* `docs/reference/runners/amp/runner.md`
* `docs/reference/runners/claude/runner.md`
* `docs/reference/runners/gemini/runner.md`
* `docs/reference/specification.md`
* `docs/reference/triggers/triggers.md`
* `docs/tutorials/first-run.md`
* `docs/tutorials/install.md`
* `incoming/v0.35.1rc4-integration-test-plan.md`
* `pyproject.toml`
* `scripts/healthcheck.sh`
* `src/untether/cli/run.py`
* `src/untether/commands.py`
* `src/untether/context.py`
* `src/untether/markdown.py`
* `src/untether/progress.py`
* `src/untether/runner.py`
* `src/untether/runner_bridge.py`
* `src/untether/runners/amp.py`
* `src/untether/runners/claude.py`
* `src/untether/runners/codex.py`
* `src/untether/runners/gemini.py`
* `src/untether/runners/opencode.py`
* `src/untether/runners/pi.py`
* `src/untether/sdnotify.py`
* `src/untether/settings.py`
* `src/untether/telegram/at_scheduler.py`
* `src/untether/telegram/bridge.py`
* `src/untether/telegram/client_api.py`
* `src/untether/telegram/commands/at.py`
* `src/untether/telegram/commands/cancel.py`
* `src/untether/telegram/commands/config.py`
* `src/untether/telegram/commands/dispatch.py`
* `src/untether/telegram/commands/ping.py`
* `src/untether/telegram/commands/threads.py`
* `src/untether/telegram/engine_overrides.py`
* `src/untether/telegram/loop.py`
* `src/untether/telegram/offset_persistence.py`
* `src/untether/telegram/parsing.py`
* `src/untether/telegram/topic_state.py`
* `src/untether/triggers/__init__.py`
* `src/untether/triggers/actions.py`
* `src/untether/triggers/auth.py`
* `src/untether/triggers/cron.py`
* `src/untether/triggers/describe.py`
* `src/untether/triggers/dispatcher.py`
* `src/untether/triggers/fetch.py`
* `src/untether/triggers/manager.py`
* `src/untether/triggers/rate_limit.py`
* `src/untether/triggers/server.py`
* `src/untether/triggers/settings.py`
* `src/untether/triggers/ssrf.py`
* `src/untether/triggers/templating.py`
* `src/untether/utils/proc_diag.py`
* `tests/test_at_command.py`
* `tests/test_bridge_config_reload.py`
* `tests/test_build_args.py`
* `tests/test_callback_dispatch.py`
* `tests/test_claude_control.py`
* `tests/test_config_command.py`
* `tests/test_describe_cron.py`
* `tests/test_exec_bridge.py`
* `tests/test_offset_persistence.py`
* `tests/test_ping_command.py`
* `tests/test_proc_diag.py`
* `tests/test_sdnotify.py`
* `tests/test_telegram_bridge.py`
* `tests/test_telegram_engine_overrides.py`
* `tests/test_trigger_actions.py`
* `tests/test_trigger_cron.py`
* `tests/test_trigger_dispatcher.py`
* `tests/test_trigger_fetch.py`
* `tests/test_trigger_manager.py`
* `tests/test_trigger_meta_line.py`
* `tests/test_trigger_server.py`
* `tests/test_trigger_settings.py`
* `tests/test_trigger_ssrf.py`
* `tests/test_trigger_templating.py`
* `zensical.toml`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Version bump should be minor, not patch, for a new command feature.

Line 5 sets 0.35.1, but Line 81 introduces a new /at command backend. That is a feature addition and should use a minor bump.

🔧 Suggested fix

-version = "0.35.1"
+version = "0.36.0"

As per coding guidelines, "Version bumps must match semantic versioning: patch for bug fixes/schema additions, minor for features/new commands."

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	version = "0.35.1"
	version = "0.36.0"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pyproject.toml` at line 5, Change the package version from the patch bump to
a minor bump to reflect the new feature: update the version value currently set
to "0.35.1" in pyproject.toml to "0.36.0" because you added the new /at command
backend; ensure the version string in pyproject.toml (the line containing
version = "...") is updated and consistent with any release metadata or
CI/version checks that read the same value.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Take a real snapshot before mutating manager.crons.

crons = manager.crons is only an alias. If remove_cron() mutates the backing list in place, removing a run_once entry during iteration can skip the next matching cron in the same tick. Snapshot with list(...) and defer removals until after the loop.

♻️ Suggested fix

-        crons = manager.crons
+        crons = list(manager.crons)
         default_timezone = manager.default_timezone
+        remove_after_tick: list[str] = []
         for cron in crons:
@@
-                if cron.run_once:
-                    manager.remove_cron(cron.id)
+                if cron.run_once:
+                    remove_after_tick.append(cron.id)
+
+        for cron_id in remove_after_tick:
+            manager.remove_cron(cron_id)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/cron.py` around lines 98 - 120, The code currently
iterates over manager.crons by reference which can be mutated by
manager.remove_cron(cron.id) and skip entries; fix by first taking a real
snapshot (e.g., crons = list(manager.crons)) and, instead of calling
manager.remove_cron(...) inside the loop, collect cron ids with cron.run_once
into a to_remove set/list and after the for loop call manager.remove_cron(id)
for each id; keep existing logic around _resolve_now, cron_matches, last_fired,
logger, and dispatcher.dispatch_cron unaffected.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Validate duplicate cron IDs and webhook paths before replacing state.

Line 47 silently overwrites earlier webhooks sharing the same path, and Line 135 only removes the first matching cron ID. That creates ambiguous routing/removal semantics and can mask config mistakes.

Proposed fix

     def update(self, settings: TriggersSettings) -> None:
         """Replace cron and webhook configuration.
@@
-        self._crons = list(settings.crons)
-        self._webhooks_by_path = {wh.path: wh for wh in settings.webhooks}
+        cron_ids = [c.id for c in settings.crons]
+        if len(cron_ids) != len(set(cron_ids)):
+            raise ValueError("Duplicate cron ids are not allowed")
+
+        webhook_paths = [wh.path for wh in settings.webhooks]
+        if len(webhook_paths) != len(set(webhook_paths)):
+            raise ValueError("Duplicate webhook paths are not allowed")
+
+        self._crons = list(settings.crons)
+        self._webhooks_by_path = {wh.path: wh for wh in settings.webhooks}

Run this to confirm whether upstream settings validation already enforces uniqueness:

#!/bin/bash
set -euo pipefail

fd -a "settings.py" src/untether/triggers
rg -n -C3 --type=py 'class (TriggersSettings|CronConfig|WebhookConfig)|validator|validate|webhooks|crons|path|id' src/untether/triggers/settings.py

Also applies to: 135-137

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/manager.py` around lines 46 - 48, Detect and reject
duplicate webhook paths and cron IDs before replacing internal state: when
assigning self._webhooks_by_path from settings.webhooks and self._crons from
settings.crons, validate that no two WebhookConfig items share the same path and
no two CronConfig items share the same id; if duplicates exist, raise a clear
ValueError (or propagate a ValidationError) rather than silently overwriting.
Also update the cron removal logic (the method that currently removes only the
first matching id around the remove logic at/near where self._crons is mutated)
to remove all crons with the given id (or explicitly enforce uniqueness earlier
and assert exactly one removal) so semantics are unambiguous. Ensure the checks
reference settings.webhooks, settings.crons, self._webhooks_by_path and
self._crons so reviewers can find the changes.

[Nathan Schram (nathanschram)]

CodeRabbit (@coderabbitai) review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[Nathan Schram (nathanschram)]

CodeRabbit (@coderabbitai) full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[Nathan Schram (nathanschram)]

CodeRabbit findings status — all addressed

CodeRabbit posted 16 inline comments + 4 outside-diff comments on this PR at 05:00 UTC. They have been triaged and addressed in commit b979fec (originally PR #311, squash-merged into dev at 05:39 UTC and now part of this PR's diff).

Fixed (15)

P0 — Critical functional regressions:

• ✅ PyPI page shows broken links and raw license text instead of SPDX identifier #11 triggers/cron.py:113 — daily/weekly crons stop after first day. Fixed by keying last_fired with full date+time. Regression test added.
• ✅ feat: restructure startup message for v0.23.1 #4 runner_bridge.py:806 — subagent runs force-killed at MAX_WARNINGS. Fixed by exempting tree_active when active children present.
• ✅ Release workflow reports failure due to defunct Telegram notification scripts #9 triggers/actions.py:155 — append_timestamp race. Fixed with time.time_ns() + collision probe.

P1 — Functional bugs:

• ✅ fix: handle missing OAuth credentials on macOS (Keychain support) #5 runners/claude.py:568 — _PLAN_EXIT_APPROVED not set in auto-approve drain. Fixed in both auto-mode and post-discuss paths.
• ✅ Noisy warning for unrecognised rate_limit_event JSONL type #8 telegram/parsing.py:254 — offset persisted before yield. Fixed by reordering.
• ✅ [auto] handle.worker_failed: FileNotFoundError #16 triggers/rate_limit.py:33 — warning log spam. Dropped to debug.
• ✅ docs: comprehensive documentation audit and upgrade #20 config.py:1088 — reasoning level not validated against engine. Defensive validation added. Test split per-engine.
• ✅ fix: add rate_limit_event to Claude stream-json schema #6 bridge.py:145 — misleading docstring. Corrected.

P2 — Doc/display:

• ✅ docs: comprehensive documentation audit and upgrade #13/Enrich error reporting in Telegram messages and structlog #14 triggers/describe.py — invalid DOW values & */N substring check. Both now fall back to raw schedule. 6 regression tests added.
• ✅ feat: enrich error reporting in Telegram and structlog #19 config.py:1859 — missing rs:max toast. Added.
• ✅ feat: v0.23.0 — meta line, startup refresh, README rewrite #3 README.md:315 — access matrix overstated isolation. Now accurate.
• ✅ feat: interactive enhancements — AskUserQuestion, export, browse, cost, triggers #1 integration-testing.md:27 — bot ID misused as DM chat ID. Clarified.
• ✅ [auto] handle.runner_failed: ExceptionGroup #17 specification.md:7 — version reference inconsistency. Synced to v0.35.1.
• ✅ [auto] config.read.toml_error: Invalid value (at line 135, column 11) #18 test_claude_control.py:79 — fixture cleanup only post-yield. Now pre+post.

Skipped — false positives (verified against actual code, 3)

• feat: public release — docs, PyPI metadata, GitHub templates #2 version bump suggestion — Nathan's call, not auto-applicable mid-cycle
• Crash on macOS: FileNotFoundError for Claude OAuth credentials #7 restart-only keys hot-reloaded — false positive: update_from() is selective (lines 181-191 of bridge.py) and only touches hot fields
• test_doctor_voice_checks fails due to env var leak from pydantic_settings #12 cron snapshot iteration — false positive: remove_cron() REPLACES the list (line 137 of manager.py), doesn't mutate in place

Deferred to follow-up issues (2)

• Test failure on Python 3.12/3.13: uuid.uuid7 does not exist #10 http_forward Content-Type override → #312
• [auto] handle.worker_failed: ReadTimeout #15 duplicate cron ID/webhook path validation → #313

Why no fresh CodeRabbit review on this PR

I tried @coderabbitai review (rate limited) and @coderabbitai full review (acknowledged at 05:57 UTC but no new review posted in 15+ min). CodeRabbit's incremental review system doesn't re-review files it has already commented on, even with full review. The 16 inline comments on this PR are from the 05:00 review against pre-fix commits and remain visible in the GitHub UI — please cross-reference each against the table above when reviewing.

Verification

• 2172 unit tests pass (was 2164, +8 regression tests covering PyPI page shows broken links and raw license text instead of SPDX identifier #11, docs: comprehensive documentation audit and upgrade #13/Enrich error reporting in Telegram messages and structlog #14, [auto] config.read.toml_error: Invalid value (at line 135, column 11) #18, docs: comprehensive documentation audit and upgrade #20)
• 81.51% coverage
• ruff format/lint/lockfile/build all clean
• All 19 required CI checks green on this PR with fix commits applied

Ready for your review.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@nathanschram: Thank you for the thorough triage. I've reviewed your status report against the code context and can confirm the following:

False positive validations — confirmed ✅

• Crash on macOS: FileNotFoundError for Claude OAuth credentials #7 (bridge.py restart-only keys): The AI summary of bridge.py confirms update_from() mutates only the hot-reloadable fields (show_resume_line, voice transcription fields, coalescing/debounce floats, allowed_user_ids, files). Architectural fields (bot_token, chat_id, session_mode, topics, message_overflow) are correctly excluded. False positive confirmed.
• test_doctor_voice_checks fails due to env var leak from pydantic_settings #12 (manager.py iteration safety): The AI summary explicitly states remove_cron() "removes a cron by ID by replacing _crons with a new list." No in-place mutation — the same atomic replacement strategy used in update(). False positive confirmed.

Fixes — all P0/P1 issues acknowledged ✅

The three P0 fixes are particularly important: the last_fired date-keying fix for daily/weekly crons, the tree_active exemption in the stall monitor, and the time.time_ns() collision probe for append_timestamp. These are the right fixes with regression tests to prevent regressions.

Deferred issues ✅

#312 (Content-Type passthrough for http_forward) and #313 (duplicate cron ID/webhook path validation) are appropriately scoped as follow-up work — neither is a blocker for this release.

I'll resolve my open comments and approve the PR.

[resolve]
[approve]

---

🧠 Learnings used

Learnt from: CR
Repo: littlebearapps/untether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T06:38:04.537Z
Learning: Never skip staging for minor/major releases; always dogfood TestPyPI rc on `hetz_lba1_bot` for 1+ week before PyPI release

---

Learnt from: CR
Repo: littlebearapps/untether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T06:38:04.537Z
Learning: Applies to .github/workflows/*.yml : Use PyPI trusted publishing with OIDC for automated release deploys; require Nathan's approval in GitHub Actions UI before PyPI publish

---

Learnt from: CR
Repo: littlebearapps/untether PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T06:38:04.537Z
Learning: Auto-approve dependency updates via dependabot for patch/minor Python deps; flag major bumps for manual review

[coderabbitai]

Actionable comments posted: 20

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/untether/telegram/commands/config.py (1)

1527-1563: ⚠️ Potential issue | 🟡 Minor

Validate cu:*_* callbacks before indexing the action map.

This branch accepts any callback containing _, then does {"on": ..., "off": ..., "clr": ...}[act]. A malformed callback such as config:cu:ac_bad will throw KeyError instead of safely returning to the page.

Possible fix

     if action and "_" in action:
         prefix, act = action.split("_", 1)
+        valid_acts = {"on": True, "off": False, "clr": None}
+        if act not in valid_acts:
+            logger.warning(
+                "config.cost_usage.invalid_action",
+                chat_id=chat_id,
+                engine=current_engine,
+                action=action,
+            )
+            await _page_cost_usage(ctx)
+            return
         current = await prefs.get_engine_override(chat_id, current_engine)
         ac_val = current.show_api_cost if current else None
         su_val = current.show_subscription_usage if current else None
         bg_val = current.budget_enabled if current else None
         bc_val = current.budget_auto_cancel if current else None
 
         if prefix == "ac" and has_api_cost:
-            ac_val = {"on": True, "off": False, "clr": None}[act]
+            ac_val = valid_acts[act]
             logger.info("config.api_cost.set", chat_id=chat_id, value=ac_val)
         elif prefix == "su" and has_sub_usage:
-            su_val = {"on": True, "off": False, "clr": None}[act]
+            su_val = valid_acts[act]
             logger.info("config.subscription_usage.set", chat_id=chat_id, value=su_val)
         elif prefix == "bg":
-            bg_val = {"on": True, "off": False, "clr": None}[act]
+            bg_val = valid_acts[act]
             logger.info("config.budget_enabled.set", chat_id=chat_id, value=bg_val)
         elif prefix == "bc":
-            bc_val = {"on": True, "off": False, "clr": None}[act]
+            bc_val = valid_acts[act]
             logger.info("config.budget_auto_cancel.set", chat_id=chat_id, value=bc_val)
+        else:
+            logger.warning(
+                "config.cost_usage.invalid_prefix",
+                chat_id=chat_id,
+                engine=current_engine,
+                action=action,
+            )
+            await _page_cost_usage(ctx)
+            return

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/telegram/commands/config.py` around lines 1527 - 1563, The
branch that handles callbacks with an underscore splits action into prefix and
act and blindly indexes {"on","off","clr"}[act], which raises KeyError for
malformed acts (e.g., "ac_bad"); validate act against the allowed set before
indexing and bail out (or return to the page) on invalid values. Update the
block where action is split (the variables prefix and act) to check act in
("on","off","clr") and only map to booleans when valid; if invalid, log a
warning (using logger) and call the same safe exit path (await
_page_cost_usage(ctx) and return) instead of proceeding to build EngineOverrides
and calling prefs.set_engine_override. Ensure you reference the current
variables (action, prefix, act), the mapping uses only validated keys, and keep
the subsequent use of EngineOverrides and prefs.set_engine_override unchanged
when act is valid.

♻️ Duplicate comments (1)

pyproject.toml (1)

5-5: ⚠️ Potential issue | 🟠 Major

Use a minor bump for this feature release.

Line 5 uses a patch bump, but Line 81 adds a new command backend (at), which is a feature-level change and should be released as a minor version.

🔧 Proposed fix

-version = "0.35.1"
+version = "0.36.0"

As per coding guidelines, "Version bumping must follow semantic versioning: patch for bug fixes/schema additions/dependency updates, minor for new features/commands/engines/config, major for breaking changes".

Also applies to: 81-81

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@pyproject.toml` at line 5, The version in pyproject.toml is currently a patch
bump ("0.35.1") but a new command backend "at" was added (feature-level change),
so update the version to a minor bump (e.g., "0.36.0") in pyproject.toml; locate
the version key in the file (version = "...") and replace the patch-level value
with the next minor version to reflect the new "at" command addition.

🧹 Nitpick comments (10)

.claude/skills/untether-architecture/SKILL.md (1)

283-283: Clarify SHA1 as legacy and prefer SHA256 in webhook auth docs.

Given this is an architecture/security-facing doc, add a short note that HMAC-SHA256 is preferred and SHA1 is legacy/compat-only (if still supported).

As per coding guidelines "Maintain cross-file consistency, path verification, version accuracy, and command accuracy in AI context files".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/skills/untether-architecture/SKILL.md at line 283, Update the
webhook auth documentation near run_webhook_server() and the
[[triggers.webhooks]] section to mark SHA1 as legacy/compat-only and state
HMAC-SHA256 as the preferred algorithm; specifically, add a concise note that
HMAC-SHA256 should be used for new integrations, that SHA1 support (if present)
exists only for backward compatibility, and recommend migrating SHA1 users to
SHA256 while keeping wording consistent with other docs and path/version
mentions in this file.

src/untether/context.py (1)

10-13: Consider replacing free-form provenance with structured fields.

trigger_source: str | None (e.g. "cron:daily-review") is easy to misuse and pushes string parsing downstream. Consider a typed split like trigger_kind + trigger_id for safer handling.

♻️ Proposed refactor

 `@dataclass`(frozen=True, slots=True)
 class RunContext:
     project: str | None = None
     branch: str | None = None
-    # rc4 (`#271`): trigger_source is set when a run is initiated by a cron
-    # or webhook (e.g. "cron:daily-review", "webhook:github-push") so the
-    # Telegram meta footer can show the provenance.
-    trigger_source: str | None = None
+    # Trigger provenance for footer/telemetry.
+    trigger_kind: str | None = None   # e.g. "cron" | "webhook"
+    trigger_id: str | None = None     # e.g. "daily-review"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/context.py` around lines 10 - 13, The current free-form field
trigger_source on the Context model should be replaced with structured fields to
avoid downstream string parsing; add two fields (e.g., trigger_kind:
Literal['cron','webhook','manual',...] | str | None and trigger_id: str | None)
in place of trigger_source, update the Context dataclass/constructor (and any
factory/parse methods) to accept and populate these two fields, and change all
usages (serialization, logging, Telegram meta footer generation, tests) that
read trigger_source to use trigger_kind and trigger_id (or compose them only
where a combined string is explicitly needed). Ensure backward-compatible
parsing of existing "kind:id" style strings where necessary in any
deserialization code.

docs/tutorials/install.md (1)

441-441: Optional: smooth out repetitive sentence starts.

Line 441 begins consecutive sentences with “To …”; minor rewording would read cleaner.

✏️ Suggested wording

-To uninstall completely (CLI, config, and state), see the [uninstall guide](../how-to/uninstall.md). To learn more about updates, see [Update Untether](../how-to/update.md).
+For complete removal (CLI, config, and state), see the [uninstall guide](../how-to/uninstall.md). For update details, see [Update Untether](../how-to/update.md).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/tutorials/install.md` at line 441, The two consecutive sentences
starting with "To ..." in the paragraph ("To uninstall completely (CLI, config,
and state), see the [uninstall guide](../how-to/uninstall.md). To learn more
about updates, see [Update Untether](../how-to/update.md).") are repetitive;
reword the second sentence to avoid repeating "To" (for example start with
"Learn more about updates in [Update Untether](...)" or "For update information,
see [Update Untether](...)") so the flow reads smoother while keeping the same
links and meaning.

.claude/rules/runner-development.md (1)

37-40: Scope mismatch between rule content and applies_to metadata.

Line 39 defines requirements for src/untether/runner_bridge.py and src/untether/progress.py, but the file scope (Line 2) excludes both paths. Please either expand applies_to or move these requirements to a rule file that targets those modules.

Suggested metadata fix

-applies_to: "src/untether/runners/**,src/untether/runner.py"
+applies_to: "src/untether/runners/**,src/untether/runner.py,src/untether/runner_bridge.py,src/untether/progress.py"

As per coding guidelines, AI context files must maintain path verification and cross-file consistency ({CLAUDE.md,AGENTS.md,.claude/**/*.md}: Maintain cross-file consistency, path verification, version accuracy, and command accuracy in AI context files).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/rules/runner-development.md around lines 37 - 40, The rule's content
references src/untether/runner_bridge.py and src/untether/progress.py (symbols:
RunContext.trigger_source, runner_bridge.handle_message,
ProgressTracker.note_event, StartedEvent.meta) but the rule's applies_to scope
excludes those paths; fix by either expanding the rule's applies_to metadata to
include src/untether/** (or specifically src/untether/runner_bridge.py and
src/untether/progress.py) so the rule applies to those files, or move the
paragraphs about RunContext.trigger_source, runner_bridge.handle_message,
ProgressTracker.note_event, and StartedEvent.meta into a separate rule file
whose applies_to includes those module paths to restore cross-file consistency.

src/untether/utils/proc_diag.py (1)

167-169: Minor: descendants includes direct children redundantly.

_find_descendants(pid) already includes direct children (via _find_children internally), and children is collected separately on line 167. This isn't a bug (children is used for child_pids field, descendants for CPU aggregation), but the naming could cause confusion during future maintenance.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/utils/proc_diag.py` around lines 167 - 169, The code collects
both direct children via _find_children(pid) into children and all descendant
PIDs via _find_descendants(pid) into descendants which is confusing because
_find_descendants already includes direct children; rename the variable
descendants to all_descendants (or similar) and update its usages (e.g., passed
to _collect_tree_cpu) and related comment/field naming (child_pids remains
as-is) so the intent is explicit and future maintainers don't mistake redundancy
between children and descendants.

tests/test_trigger_server.py (1)

247-272: Use anyio primitives in these new async tests.

These tests use asyncio.sleep(), asyncio.gather(), and asyncio.Event() (lines 272, 534, 558–559), making them asyncio-specific despite being marked for pytest.mark.anyio. Replace with anyio equivalents so they remain backend-agnostic.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_server.py` around lines 247 - 272, Replace
asyncio-specific primitives with anyio equivalents in the async tests: remove
asyncio imports and use anyio.sleep instead of asyncio.sleep (e.g., in
test_dispatch_errors_dont_fail_http_response), use anyio.Event in place of
asyncio.Event, and replace asyncio.gather usage with an anyio.create_task_group
with start_soon (or anyio.gather if available in your anyio version) to remain
backend-agnostic; update imports and references for ExplodingDispatcher tests
and any other tests that used asyncio.*.

src/untether/triggers/actions.py (2)

268-285: Consider moving anyio import to module level.

The import anyio statements inside the retry loop (lines 269, 283) work but are inefficient. Moving to the top-level imports would be cleaner.

♻️ Suggested refactor

 import tempfile
 import time
 from pathlib import Path, PurePosixPath
 from typing import Any

+import anyio
 import httpx

Then remove the inline imports on lines 269 and 283.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/actions.py` around lines 268 - 285, Move the inline
imports of anyio out of the retry loop by adding "import anyio" to the
module-level imports in src/untether/triggers/actions.py and remove the two
inline "import anyio" statements inside the http_forward retry logic (the block
handling exceptions for httpx.ConnectError and httpx.TimeoutException and the
earlier sleep call). This keeps the retry/backoff calls (await anyio.sleep(...))
unchanged but avoids repeated imports; update any linter imports ordering if
needed.

---

51-65: Comment is misleading about symlink protection.

Lines 60-61 state the check prevents "escaping via symlinks," but the actual check on line 62 only examines raw_path for .. segments. This doesn't prevent symlink-based directory escapes where resolved points outside the intended directory.

Consider clarifying the comment or adding actual symlink validation if this is a security requirement.

📝 Suggested comment fix

-    # Block traversal via symlinks: the resolved path must start with
-    # the expanded parent to prevent escaping.
+    # Block explicit traversal sequences in the raw path.
+    # Note: This does not prevent symlink-based escapes.
     if ".." in Path(raw_path).parts:
         return None

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/actions.py` around lines 51 - 65, The docstring/comment
for _resolve_file_path is misleading: it claims to block "traversal via
symlinks" but the current check only inspects raw_path.parts for ".."; update
either the comment or implement real symlink validation. Fix option A: change
the comment/docstring to remove the symlink claim and accurately state that only
literal ".." segments in raw_path are rejected. Fix option B (preferred if
security requires it): after computing expanded = Path(raw_path).expanduser()
and resolved = expanded.resolve(strict=False), ensure resolved is inside the
intended base (e.g., require resolved.is_relative_to(expanded.parent) or compare
resolved.resolve().parts prefix against expanded.parent.resolve().parts) and
return None if resolved falls outside; keep the existing ".." check on raw_path
as well. Use the function name _resolve_file_path and variables raw_path,
expanded, and resolved to locate where to change.

src/untether/triggers/settings.py (1)

171-181: Consider extracting timezone validation to reduce duplication.

The timezone validation logic is duplicated between CronConfig._validate_timezone (lines 143-153) and TriggersSettings._validate_default_timezone (lines 171-181).

♻️ Optional refactor

def _validate_iana_timezone(v: str | None, field_name: str = "timezone") -> str | None:
    """Validate an IANA timezone string."""
    if v is not None:
        try:
            ZoneInfo(v)
        except (ZoneInfoNotFoundError, KeyError):
            raise ValueError(
                f"unknown {field_name} {v!r}; use IANA names like 'Australia/Melbourne'"
            ) from None
    return v

Then use @field_validator with _validate_iana_timezone(v) in both models.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/settings.py` around lines 171 - 181, Extract the
duplicated IANA timezone validation into a shared helper (e.g.,
_validate_iana_timezone) and call it from both CronConfig._validate_timezone and
TriggersSettings._validate_default_timezone; implement
_validate_iana_timezone(v: str | None, field_name: str = "timezone") to try
ZoneInfo(v) and raise the same ValueError message on
ZoneInfoNotFoundError/KeyError (including the field_name in the message), then
have each `@field_validator` call that helper so the validation logic is
centralized.

tests/test_trigger_actions.py (1)

47-50: Broaden the tilde expansion assertion for cross-platform compatibility.

The assertion on line 50 only checks for /home or /root, but macOS uses /Users/ and some systems may have other home directory locations.

♻️ Suggested fix

     def test_tilde_expansion(self) -> None:
         result = _resolve_file_path("~/data/output.json")
         assert result is not None
-        assert str(result).startswith("/home") or str(result).startswith("/root")
+        # Verify tilde was expanded to an absolute path (varies by OS)
+        assert result.is_absolute()
+        assert "~" not in str(result)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_actions.py` around lines 47 - 50, The test
test_tilde_expansion is too narrowly asserting that the expanded path starts
with "/home" or "/root"; update it to assert against the actual current user's
home directory by using os.path.expanduser("~") or pathlib.Path.home(): call
_resolve_file_path("~/data/output.json"), ensure the result is not None and that
str(result).startswith(str(Path.home())) (or compare resolved absolute paths) so
the test passes on macOS and other platforms; reference the test function
test_tilde_expansion and helper _resolve_file_path when making the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.claude/skills/untether-architecture/SKILL.md:
- Line 287: The doc line omits the non-agent webhook path: update the sentence
to include TriggerDispatcher.dispatch_action() alongside dispatch_cron() and
dispatch_webhook(), stating that non-agent webhook actions also flow into
dispatch_action() → send the Telegram notification (⏰/⚡) → call run_job() with
the prompt, threading under the notification; ensure you reference
TriggerDispatcher.dispatch_action, dispatch_webhook, dispatch_cron and run_job
so cross-file/path verification and version/command accuracy are preserved.

In `@CHANGELOG.md`:
- Around line 3-105: Under the "## v0.35.1 (2026-04-15)" entry add the missing
release-note subsections "### breaking" and "### tests" (keep the existing
"fixes", "changes", and "docs" blocks intact); if there are no breaking changes
include an explicit empty "### breaking" header with a one-line "No breaking
changes." statement, and add a short "### tests" bullet summarising new/updated
test coverage (e.g. mention "13 new tests in test_trigger_manager.py" and
overall test audit) so the changelog conforms to the required
fixes/changes/breaking/docs/tests structure.

In `@docs/how-to/schedule-tasks.md`:
- Around line 9-13: The fenced code block that currently starts with ``` and
contains the lines "/at 30m Check the build", "/at 2h Review the PR feedback",
"/at 60s Say hello" is missing a language tag; update the opening fence to
include a language (for example ```text) so the block is explicitly labeled and
markdownlint MD040 is satisfied.

In `@docs/how-to/troubleshooting.md`:
- Around line 252-253: Update the misleading `/cancel` description to clearly
state that invoking `/cancel` will cancel pending `/at` jobs in the chat (not
just inspect them) and warn users to avoid accidental destructive use;
specifically edit the line that mentions "Use `/cancel` to see how many pending
delays exist" to something like "Use `/cancel` to cancel all pending `/at` jobs
in this chat (this will remove scheduled jobs) — use with caution; to only view
pending jobs use `/list`" and ensure `/cancel` and `/at` are referenced so
readers understand the destructive effect.

In `@docs/how-to/update.md`:
- Around line 19-27: Replace the fenced shell code blocks with indented code
blocks to satisfy markdownlint MD046: remove the ```sh fences and indent the
command lines for both instances (the line containing "untether --version" and
the line containing "systemctl --user restart untether") by four spaces each,
keeping surrounding text and blank lines intact so the commands render as
top-level indented code blocks.

In `@docs/how-to/webhooks-and-cron.md`:
- Around line 180-188: The example places prompt_template inside the
[triggers.crons.fetch] subtable so it becomes fetch.prompt_template; remove the
prompt_template line from inside the [triggers.crons.fetch] block and re-add it
after that block under the parent table (e.g., as prompt_template under
[triggers.crons]) so the key is triggers.crons.prompt_template rather than
triggers.crons.fetch.prompt_template; update the snippet accordingly referencing
the existing triggers.crons.fetch table and the prompt_template key.

In `@docs/reference/changelog.md`:
- Line 38: Update the hard-coded GitHub URL in docs/reference/changelog.md to a
stable relative or default-branch link: replace the current
"https://github.com/littlebearapps/untether/blob/dev/CHANGELOG.md#v0351-2026-04-14"
with a repository-relative link like "CHANGELOG.md#v0351-2026-04-14" (or use the
default branch explicitly, e.g., "/blob/main/CHANGELOG.md#v0351-2026-04-14") so
the release reference in the changelog remains stable; modify the link text on
the single line containing that URL.

In `@docs/reference/integration-testing.md`:
- Around line 212-223: The markdown table has a 3-column header but rows R1–R10
contain extra unescaped pipe characters in the "Expected" column causing MD056;
edit the table rows (R1, R2, ..., R10) in the integration-testing table so each
row has exactly three cells by either escaping any literal "|" in the Expected
text (replace with "\|") or replace those pipe separators with semicolons or
combine into a single sentence, ensuring the header columns "#", "Scenario", and
"Expected" remain aligned.

In `@docs/reference/runners/claude/runner.md`:
- Line 182: Update the docs line that describes the `--effort <level>` flag to
note that the `max` effort level is only supported by the Claude Opus 4.6 model;
edit the bullet "add `--effort <level>` if a reasoning override is set
(low/medium/high/max)" (reference the `--effort` mention in runner.md) to
include a parenthetical or sentence like "(note: `max` is supported only with
Claude Opus 4.6)" so readers are not misled about availability on earlier
models.

In `@docs/reference/triggers/triggers.md`:
- Around line 432-440: The prompt_template is placed inside the nested trigger
table [triggers.crons.fetch], making it appear as a field of the HTTP fetch
trigger; move prompt_template out of [triggers.crons.fetch] into the parent cron
table for that cron (so prompt_template is a property of the cron, not of the
fetch trigger). Locate the prompt_template line and relocate it from the
[triggers.crons.fetch] block to the enclosing cron table for the "fetch" cron so
documentation shows prompt_template as a cron-level field.

In `@src/untether/runner_bridge.py`:
- Around line 1183-1194: The function _has_active_children currently treats high
diag.tcp_total as equivalent to having child processes; change it so it only
returns True when diag.child_pids is non-empty (i.e., preserve the child PID
check: if diag.child_pids: return True) and remove the tcp_total >
self._TCP_ACTIVE_THRESHOLD condition from this method; if you want to keep the
TCP heuristic, create a separate method (e.g., _has_elevated_tcp or
_tcp_activity_reason) that checks diag.tcp_total against _TCP_ACTIVE_THRESHOLD
and use that to generate a distinct reason/message instead of routing TCP
activity through the active-children branch.

In `@src/untether/telegram/at_scheduler.py`:
- Around line 146-149: The code currently inserts entry into _PENDING before
scheduling the task; if _TASK_GROUP.start_soon(_run_delayed, token) raises the
entry remains and counts against the per-chat cap. Change the order and/or add
exception handling around _TASK_GROUP.start_soon: either schedule the task first
and only set _PENDING[token] = entry after start_soon succeeds, or wrap
start_soon in try/except and on failure remove _PENDING[token] (and re-raise the
exception). Refer to symbols _PENDING, _TASK_GROUP.start_soon, _run_delayed,
token and entry when applying the fix so the orphaned entry is always cleaned up
if scheduling fails.

In `@src/untether/telegram/commands/at.py`:
- Around line 42-44: The helper _format_delay currently drops seconds for
durations >=1 hour; update _format_delay to compute hours, minutes, and seconds
(use divmod twice: hours, remainder = divmod(delay_s, 3600); minutes, seconds =
divmod(remainder, 60)) and return a string that includes seconds when non-zero
(e.g., "1h 1m 5s" or "1h 0m 5s" depending on desired precision) while keeping
the existing behavior for shorter durations—ensure the function name
_format_delay is modified accordingly and all callsites still receive a string.

In `@src/untether/telegram/commands/cancel.py`:
- Around line 117-121: The current guard in cancel handling (in
src/untether/telegram/commands/cancel.py around the condition referencing
cfg.allowed_user_ids and query.sender_id) treats a missing sender_id as allowed;
change the logic so that when cfg.allowed_user_ids is set, a None sender_id is
treated as unauthorized. Concretely, update the if condition used in the
cancellation checks (the block using cfg.allowed_user_ids and query.sender_id)
to deny when query.sender_id is None OR query.sender_id not in
cfg.allowed_user_ids; apply the same change to the similar guard at the other
location mentioned (the 127-131 block) so both places consistently implement
deny-by-default for missing sender IDs.

In `@src/untether/telegram/engine_overrides.py`:
- Around line 234-242: In the engine == "claude" branch, harden reading and
returning the user-controlled effortLevel: catch UnicodeDecodeError from
settings_path.read_text() in addition to the existing exceptions, and only
return the value if it's a str and present in
allowed_reasoning_levels("claude"); otherwise return None. Locate the
settings_path / read_text() call and the variable level in that block and
replace the current isinstance(level, str) && non-empty check with membership
validation against allowed_reasoning_levels("claude") while keeping json.loads()
error handling.

In `@src/untether/triggers/fetch.py`:
- Around line 141-160: The symlink guard is ineffective because
resolve(strict=False) is called before checking path.is_symlink(), so symlinks
are collapsed and bypass the check; change the order so you construct a raw Path
from fetch.file_path and call is_symlink() on that raw path before calling
expanduser()/resolve(), returning the same rejection message if true; keep the
existing deny-glob check using _deny_reason and subsequent resolved path logic
unchanged, but ensure you reference Path(fetch.file_path) for the traversal,
symlink and deny checks and only call expanduser().resolve() after those checks
pass.
- Around line 92-118: The current code buffers resp.content and enforces
max_bytes only after reading everything; change the HTTP call to use
httpx.AsyncClient.stream(...) (or client.request(..., stream=True)) and iterate
the response body in chunks (e.g., aiter_bytes) to accumulate up to max_bytes
while aborting the stream and returning the "too large" warning if the
accumulated size exceeds max_bytes; also pre-check Content-Length header on
resp.headers to short-circuit if it declares a size > max_bytes, preserve
existing behavior for status-code errors (the logger call using rendered_url and
resp.status_code stays the same), and still return the full bytes only if the
streamed total remains <= max_bytes; keep usage of rendered_url,
rendered_headers, method, fetch.body, render_template_fields, timeout, logger,
and max_bytes to locate where to change.

In `@src/untether/triggers/server.py`:
- Around line 94-121: Currently the code renders webhook.file_destination inside
the multipart loop as soon as a file part is encountered, which can miss form
fields that appear later; change the logic in the async reader loop that handles
part (where raw_name/safe_name, file_data, form_fields["file"] are set) to not
call render_template_fields there, but instead collect file metadata and bytes
(e.g., keep safe_name and file_data in a temp structure or keep
form_fields["file"] populated) and finish parsing all parts; after the async for
part in reader loop completes, if webhook.file_destination is set then call
render_template_fields(dest_template, template_ctx) using the fully-populated
form_fields and then perform the final destination path build and file save.
Ensure you update references to render_template_fields,
webhook.file_destination, form_fields, and the file write logic so rendering is
deferred until after parsing completes.
- Around line 203-206: Replace the ad-hoc asyncio.create_task usage and
_dispatch_tasks bookkeeping in the webhook dispatch logic with an anyio
TaskGroup: create an anyio.create_task_group() (or self._task_group managed on
startup/shutdown) and start webhook handler coroutines within that group instead
of asyncio.create_task; remove the done-callback and the _dispatch_tasks set,
and ensure the group's cancel/finish is invoked during runner.cleanup() (or
server shutdown) so in-flight dispatch handlers are cancelled and awaited
automatically. Target the code that spawns webhook handler coroutines (the
locations currently calling asyncio.create_task to run the dispatch/webhook
handler) and the shutdown path that calls runner.cleanup() to wire the task
group lifecycle.

In `@tests/test_trigger_meta_line.py`:
- Around line 9-26: Update the tests to pass the raw trigger source strings
(e.g., "cron:daily-review" and "webhook:github-push") into format_meta_line
instead of already-prefixed strings with icons; change assertions in
test_trigger_only, test_trigger_with_model and test_trigger_webhook to verify
that format_meta_line prepends the correct icon/prefix to the raw source (e.g.,
resulting string contains the expected icon + space + the raw source), and in
test_trigger_with_model ensure the computed part (the full "icon + space +
trigger" fragment) appears as the last element when splitting by " · " and that
the model name (e.g., "opus") appears earlier.

---

Outside diff comments:
In `@src/untether/telegram/commands/config.py`:
- Around line 1527-1563: The branch that handles callbacks with an underscore
splits action into prefix and act and blindly indexes {"on","off","clr"}[act],
which raises KeyError for malformed acts (e.g., "ac_bad"); validate act against
the allowed set before indexing and bail out (or return to the page) on invalid
values. Update the block where action is split (the variables prefix and act) to
check act in ("on","off","clr") and only map to booleans when valid; if invalid,
log a warning (using logger) and call the same safe exit path (await
_page_cost_usage(ctx) and return) instead of proceeding to build EngineOverrides
and calling prefs.set_engine_override. Ensure you reference the current
variables (action, prefix, act), the mapping uses only validated keys, and keep
the subsequent use of EngineOverrides and prefs.set_engine_override unchanged
when act is valid.

---

Duplicate comments:
In `@pyproject.toml`:
- Line 5: The version in pyproject.toml is currently a patch bump ("0.35.1") but
a new command backend "at" was added (feature-level change), so update the
version to a minor bump (e.g., "0.36.0") in pyproject.toml; locate the version
key in the file (version = "...") and replace the patch-level value with the
next minor version to reflect the new "at" command addition.

---

Nitpick comments:
In @.claude/rules/runner-development.md:
- Around line 37-40: The rule's content references src/untether/runner_bridge.py
and src/untether/progress.py (symbols: RunContext.trigger_source,
runner_bridge.handle_message, ProgressTracker.note_event, StartedEvent.meta) but
the rule's applies_to scope excludes those paths; fix by either expanding the
rule's applies_to metadata to include src/untether/** (or specifically
src/untether/runner_bridge.py and src/untether/progress.py) so the rule applies
to those files, or move the paragraphs about RunContext.trigger_source,
runner_bridge.handle_message, ProgressTracker.note_event, and StartedEvent.meta
into a separate rule file whose applies_to includes those module paths to
restore cross-file consistency.

In @.claude/skills/untether-architecture/SKILL.md:
- Line 283: Update the webhook auth documentation near run_webhook_server() and
the [[triggers.webhooks]] section to mark SHA1 as legacy/compat-only and state
HMAC-SHA256 as the preferred algorithm; specifically, add a concise note that
HMAC-SHA256 should be used for new integrations, that SHA1 support (if present)
exists only for backward compatibility, and recommend migrating SHA1 users to
SHA256 while keeping wording consistent with other docs and path/version
mentions in this file.

In `@docs/tutorials/install.md`:
- Line 441: The two consecutive sentences starting with "To ..." in the
paragraph ("To uninstall completely (CLI, config, and state), see the [uninstall
guide](../how-to/uninstall.md). To learn more about updates, see [Update
Untether](../how-to/update.md).") are repetitive; reword the second sentence to
avoid repeating "To" (for example start with "Learn more about updates in
[Update Untether](...)" or "For update information, see [Update Untether](...)")
so the flow reads smoother while keeping the same links and meaning.

In `@src/untether/context.py`:
- Around line 10-13: The current free-form field trigger_source on the Context
model should be replaced with structured fields to avoid downstream string
parsing; add two fields (e.g., trigger_kind:
Literal['cron','webhook','manual',...] | str | None and trigger_id: str | None)
in place of trigger_source, update the Context dataclass/constructor (and any
factory/parse methods) to accept and populate these two fields, and change all
usages (serialization, logging, Telegram meta footer generation, tests) that
read trigger_source to use trigger_kind and trigger_id (or compose them only
where a combined string is explicitly needed). Ensure backward-compatible
parsing of existing "kind:id" style strings where necessary in any
deserialization code.

In `@src/untether/triggers/actions.py`:
- Around line 268-285: Move the inline imports of anyio out of the retry loop by
adding "import anyio" to the module-level imports in
src/untether/triggers/actions.py and remove the two inline "import anyio"
statements inside the http_forward retry logic (the block handling exceptions
for httpx.ConnectError and httpx.TimeoutException and the earlier sleep call).
This keeps the retry/backoff calls (await anyio.sleep(...)) unchanged but avoids
repeated imports; update any linter imports ordering if needed.
- Around line 51-65: The docstring/comment for _resolve_file_path is misleading:
it claims to block "traversal via symlinks" but the current check only inspects
raw_path.parts for ".."; update either the comment or implement real symlink
validation. Fix option A: change the comment/docstring to remove the symlink
claim and accurately state that only literal ".." segments in raw_path are
rejected. Fix option B (preferred if security requires it): after computing
expanded = Path(raw_path).expanduser() and resolved =
expanded.resolve(strict=False), ensure resolved is inside the intended base
(e.g., require resolved.is_relative_to(expanded.parent) or compare
resolved.resolve().parts prefix against expanded.parent.resolve().parts) and
return None if resolved falls outside; keep the existing ".." check on raw_path
as well. Use the function name _resolve_file_path and variables raw_path,
expanded, and resolved to locate where to change.

In `@src/untether/triggers/settings.py`:
- Around line 171-181: Extract the duplicated IANA timezone validation into a
shared helper (e.g., _validate_iana_timezone) and call it from both
CronConfig._validate_timezone and TriggersSettings._validate_default_timezone;
implement _validate_iana_timezone(v: str | None, field_name: str = "timezone")
to try ZoneInfo(v) and raise the same ValueError message on
ZoneInfoNotFoundError/KeyError (including the field_name in the message), then
have each `@field_validator` call that helper so the validation logic is
centralized.

In `@src/untether/utils/proc_diag.py`:
- Around line 167-169: The code collects both direct children via
_find_children(pid) into children and all descendant PIDs via
_find_descendants(pid) into descendants which is confusing because
_find_descendants already includes direct children; rename the variable
descendants to all_descendants (or similar) and update its usages (e.g., passed
to _collect_tree_cpu) and related comment/field naming (child_pids remains
as-is) so the intent is explicit and future maintainers don't mistake redundancy
between children and descendants.

In `@tests/test_trigger_actions.py`:
- Around line 47-50: The test test_tilde_expansion is too narrowly asserting
that the expanded path starts with "/home" or "/root"; update it to assert
against the actual current user's home directory by using
os.path.expanduser("~") or pathlib.Path.home(): call
_resolve_file_path("~/data/output.json"), ensure the result is not None and that
str(result).startswith(str(Path.home())) (or compare resolved absolute paths) so
the test passes on macOS and other platforms; reference the test function
test_tilde_expansion and helper _resolve_file_path when making the change.

In `@tests/test_trigger_server.py`:
- Around line 247-272: Replace asyncio-specific primitives with anyio
equivalents in the async tests: remove asyncio imports and use anyio.sleep
instead of asyncio.sleep (e.g., in
test_dispatch_errors_dont_fail_http_response), use anyio.Event in place of
asyncio.Event, and replace asyncio.gather usage with an anyio.create_task_group
with start_soon (or anyio.gather if available in your anyio version) to remain
backend-agnostic; update imports and references for ExplodingDispatcher tests
and any other tests that used asyncio.*.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a491f96f-5c23-4679-91ae-5e9db662f354

📥 Commits

Reviewing files that changed from the base of the PR and between e5bff3c and b979fec.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (110)

• .claude/rules/runner-development.md
• .claude/rules/telegram-transport.md
• .claude/rules/testing-conventions.md
• .claude/skills/untether-architecture/SKILL.md
• .github/workflows/ci.yml
• .github/workflows/notify-website.yml
• .github/workflows/release.yml
• CHANGELOG.md
• CLAUDE.md
• README.md
• contrib/untether.service
• docs/explanation/architecture.md
• docs/how-to/group-chat.md
• docs/how-to/index.md
• docs/how-to/inline-settings.md
• docs/how-to/interactive-approval.md
• docs/how-to/model-reasoning.md
• docs/how-to/operations.md
• docs/how-to/plan-mode.md
• docs/how-to/schedule-tasks.md
• docs/how-to/security.md
• docs/how-to/troubleshooting.md
• docs/how-to/uninstall.md
• docs/how-to/update.md
• docs/how-to/voice-notes.md
• docs/how-to/webhooks-and-cron.md
• docs/reference/changelog.md
• docs/reference/commands-and-directives.md
• docs/reference/config.md
• docs/reference/dev-instance.md
• docs/reference/glossary.md
• docs/reference/integration-testing.md
• docs/reference/runners/amp/runner.md
• docs/reference/runners/claude/runner.md
• docs/reference/runners/gemini/runner.md
• docs/reference/specification.md
• docs/reference/triggers/triggers.md
• docs/tutorials/first-run.md
• docs/tutorials/install.md
• incoming/v0.35.1rc4-integration-test-plan.md
• pyproject.toml
• scripts/healthcheck.sh
• src/untether/cli/run.py
• src/untether/commands.py
• src/untether/context.py
• src/untether/markdown.py
• src/untether/progress.py
• src/untether/runner.py
• src/untether/runner_bridge.py
• src/untether/runners/amp.py
• src/untether/runners/claude.py
• src/untether/runners/codex.py
• src/untether/runners/gemini.py
• src/untether/runners/opencode.py
• src/untether/runners/pi.py
• src/untether/sdnotify.py
• src/untether/settings.py
• src/untether/telegram/at_scheduler.py
• src/untether/telegram/bridge.py
• src/untether/telegram/client_api.py
• src/untether/telegram/commands/at.py
• src/untether/telegram/commands/cancel.py
• src/untether/telegram/commands/config.py
• src/untether/telegram/commands/dispatch.py
• src/untether/telegram/commands/ping.py
• src/untether/telegram/commands/threads.py
• src/untether/telegram/engine_overrides.py
• src/untether/telegram/loop.py
• src/untether/telegram/offset_persistence.py
• src/untether/telegram/parsing.py
• src/untether/telegram/topic_state.py
• src/untether/triggers/__init__.py
• src/untether/triggers/actions.py
• src/untether/triggers/auth.py
• src/untether/triggers/cron.py
• src/untether/triggers/describe.py
• src/untether/triggers/dispatcher.py
• src/untether/triggers/fetch.py
• src/untether/triggers/manager.py
• src/untether/triggers/rate_limit.py
• src/untether/triggers/server.py
• src/untether/triggers/settings.py
• src/untether/triggers/ssrf.py
• src/untether/triggers/templating.py
• src/untether/utils/proc_diag.py
• tests/test_at_command.py
• tests/test_bridge_config_reload.py
• tests/test_build_args.py
• tests/test_callback_dispatch.py
• tests/test_claude_control.py
• tests/test_config_command.py
• tests/test_describe_cron.py
• tests/test_exec_bridge.py
• tests/test_offset_persistence.py
• tests/test_ping_command.py
• tests/test_proc_diag.py
• tests/test_sdnotify.py
• tests/test_telegram_bridge.py
• tests/test_telegram_engine_overrides.py
• tests/test_trigger_actions.py
• tests/test_trigger_cron.py
• tests/test_trigger_dispatcher.py
• tests/test_trigger_fetch.py
• tests/test_trigger_manager.py
• tests/test_trigger_meta_line.py
• tests/test_trigger_server.py
• tests/test_trigger_settings.py
• tests/test_trigger_ssrf.py
• tests/test_trigger_templating.py
• zensical.toml

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Dispatch flow docs are incomplete for webhook actions.

This line documents only dispatch_cron()/dispatch_webhook(), but the release scope also includes non-agent webhook actions (dispatch_action()). Please include that path to keep the architecture doc accurate.

As per coding guidelines "Maintain cross-file consistency, path verification, version accuracy, and command accuracy in AI context files".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.claude/skills/untether-architecture/SKILL.md at line 287, The doc line
omits the non-agent webhook path: update the sentence to include
TriggerDispatcher.dispatch_action() alongside dispatch_cron() and
dispatch_webhook(), stating that non-agent webhook actions also flow into
dispatch_action() → send the Telegram notification (⏰/⚡) → call run_job() with
the prompt, threading under the notification; ensure you reference
TriggerDispatcher.dispatch_action, dispatch_webhook, dispatch_cron and run_job
so cross-file/path verification and version/command accuracy are preserved.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add the standard ### tests / ### breaking subsections for v0.35.1.

This entry currently only has fixes/changes/docs, so it doesn't match the repository release-note template and it omits the new test coverage shipped in this release. If there were no breaking changes, add an explicit empty ### breaking section to keep the structure consistent.

As per coding guidelines, CHANGELOG.md must use format ## vX.Y.Z (YYYY-MM-DD) with subsections for fixes, changes, breaking, docs, and tests.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 3 - 105, Under the "## v0.35.1 (2026-04-15)" entry
add the missing release-note subsections "### breaking" and "### tests" (keep
the existing "fixes", "changes", and "docs" blocks intact); if there are no
breaking changes include an explicit empty "### breaking" header with a one-line
"No breaking changes." statement, and add a short "### tests" bullet summarising
new/updated test coverage (e.g. mention "13 new tests in
test_trigger_manager.py" and overall test audit) so the changelog conforms to
the required fixes/changes/breaking/docs/tests structure.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add a language tag to the fenced command block.

Line 9 opens a fenced block without a language, which trips markdownlint (MD040).

🛠️ Proposed fix

-```
+```text
 /at 30m Check the build
 /at 2h Review the PR feedback
 /at 60s Say hello

</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/how-to/schedule-tasks.md around lines 9 - 13, The fenced code block
that currently starts with and contains the lines "/at 30m Check the build", "/at 2h Review the PR feedback", "/at 60s Say hello" is missing a language tag; update the opening fence to include a language (for exampletext) so the
block is explicitly labeled and markdownlint MD040 is satisfied.

</details>

<!-- fingerprinting:phantom:poseidon:hawk -->

<!-- This is an auto-generated comment by CodeRabbit -->

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

/cancel description is misleading for pending /at runs.

This reads like inspection-only behaviour, but /cancel actually cancels pending /at jobs in that chat. Please reword to avoid accidental destructive use.

📝 Suggested wording

-- Use `/cancel` to see how many pending delays exist. If it says "nothing running", there are no pending delays.
+- Use `/cancel` to cancel pending delays in this chat; the reply includes how many were cancelled. If it says "nothing running", there were no pending delays.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	- Use `/cancel` to see how many pending delays exist. If it says "nothing running", there are no pending delays.
	- Minimum duration: 60 seconds. Maximum: 24 hours. Values outside this range are rejected.
	- Use `/cancel` to cancel pending delays in this chat; the reply includes how many were cancelled. If it says "nothing running", there were no pending delays.
	- Minimum duration: 60 seconds. Maximum: 24 hours. Values outside this range are rejected.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/troubleshooting.md` around lines 252 - 253, Update the misleading
`/cancel` description to clearly state that invoking `/cancel` will cancel
pending `/at` jobs in the chat (not just inspect them) and warn users to avoid
accidental destructive use; specifically edit the line that mentions "Use
`/cancel` to see how many pending delays exist" to something like "Use `/cancel`
to cancel all pending `/at` jobs in this chat (this will remove scheduled jobs)
— use with caution; to only view pending jobs use `/list`" and ensure `/cancel`
and `/at` are referenced so readers understand the destructive effect.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Align top-level shell snippets with markdownlint MD046.

These two blocks are fenced, but the configured style expects indented code blocks.

Proposed markdownlint-compliant change

 Check your current version:
 
-```sh
-untether --version
-```
+    untether --version
 
 After upgrading, restart the service if running as a systemd unit:
 
-```sh
-systemctl --user restart untether
-```
+    systemctl --user restart untether

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	```sh
	untether --version
	```
	After upgrading, restart the service if running as a systemd unit:
	```sh
	systemctl --user restart untether
	```
	untether --version
	After upgrading, restart the service if running as a systemd unit:
	systemctl --user restart untether

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

[warning] 19-19: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

---

[warning] 25-25: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/how-to/update.md` around lines 19 - 27, Replace the fenced shell code
blocks with indented code blocks to satisfy markdownlint MD046: remove the ```sh
fences and indent the command lines for both instances (the line containing
"untether --version" and the line containing "systemctl --user restart
untether") by four spaces each, keeping surrounding text and blank lines intact
so the commands render as top-level indented code blocks.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cat -n src/untether/triggers/fetch.py

Repository: littlebearapps/untether

Length of output: 9126

---

🏁 Script executed:

# Check if httpx is used elsewhere in the codebase
rg "httpx" --type py -A 3 -B 3

Repository: littlebearapps/untether

Length of output: 33635

---

🏁 Script executed:

# Check if streaming patterns are already used in the codebase
rg "\.stream\(" --type py -A 5

Repository: littlebearapps/untether

Length of output: 49

---

🏁 Script executed:

# Check httpx documentation/usage patterns for stream vs request
rg "aiter_bytes|aiter_raw" --type py

Repository: littlebearapps/untether

Length of output: 49

---

🏁 Script executed:

# Verify the current exception handling includes the HTTP section
sed -n '120,124p' src/untether/triggers/fetch.py

Repository: littlebearapps/untether

Length of output: 281

---

🏁 Script executed:

# Check if there are any tests that validate max_bytes behavior
rg "max_bytes|too_large" --type py -B 3 -A 3

Repository: littlebearapps/untether

Length of output: 19856

---

Enforce max_bytes while streaming the HTTP response, not after buffering.

resp = await client.request(...); body = resp.content buffers the entire response into memory before checking its size. A misconfigured or malicious endpoint can force arbitrarily large allocations, making the limit ineffective as a memory guard. The file-read function correctly pre-checks size via stat(), but HTTP should stream and enforce the limit incrementally.

Suggested fix

    try:
        async with httpx.AsyncClient(timeout=timeout) as client:
            kwargs: dict[str, Any] = {
                "headers": rendered_headers,
                "follow_redirects": False,
            }
            if method == "POST" and fetch.body:
                kwargs["content"] = render_template_fields(
                    fetch.body, env_payload
                ).encode()

            async with client.stream(method, rendered_url, **kwargs) as resp:
                if resp.status_code >= 400:
                    msg = f"fetch failed: HTTP {resp.status_code}"
                    logger.warning(
                        "triggers.fetch.http_error",
                        url=rendered_url,
                        status=resp.status_code,
                    )
                    return False, msg, None

                chunks: list[bytes] = []
                total = 0
                async for chunk in resp.aiter_bytes():
                    total += len(chunk)
                    if total > max_bytes:
                        msg = (
                            f"fetch response too large ({total} bytes, max {max_bytes})"
                        )
                        logger.warning("triggers.fetch.too_large", size=total)
                        return False, msg, None
                    chunks.append(chunk)
                body = b"".join(chunks)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/fetch.py` around lines 92 - 118, The current code
buffers resp.content and enforces max_bytes only after reading everything;
change the HTTP call to use httpx.AsyncClient.stream(...) (or
client.request(..., stream=True)) and iterate the response body in chunks (e.g.,
aiter_bytes) to accumulate up to max_bytes while aborting the stream and
returning the "too large" warning if the accumulated size exceeds max_bytes;
also pre-check Content-Length header on resp.headers to short-circuit if it
declares a size > max_bytes, preserve existing behavior for status-code errors
(the logger call using rendered_url and resp.status_code stays the same), and
still return the full bytes only if the streamed total remains <= max_bytes;
keep usage of rendered_url, rendered_headers, method, fetch.body,
render_template_fields, timeout, logger, and max_bytes to locate where to
change.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cat -n src/untether/triggers/fetch.py | sed -n '130,170p'

Repository: littlebearapps/untether

Length of output: 1742

---

🏁 Script executed:

cat -n src/untether/triggers/fetch.py | sed -n '135,170p'

Repository: littlebearapps/untether

Length of output: 1592

---

🏁 Script executed:

python3 << 'EOF'
# Let's trace through the logic to understand the actual issue
from pathlib import Path

# The current code order is:
# 1. path = Path(fetch.file_path).expanduser().resolve(strict=False)
# 2. Check ".." in path.parts
# 3. Check deny_reason(path)
# 4. Check path.is_symlink()

# After resolve(), symlinks to files are already collapsed
# So when we check is_symlink() later, it returns False for resolved paths

# BUT: The suggest fix checks BEFORE resolve()
# raw_path.is_symlink() would catch the final component
# But raw_path.parents that are symlinks also need checking

print("Current issue: is_symlink() check happens AFTER resolve()")
print("resolve() collapses symlinks to their targets")
print("So is_symlink() will always return False for symlinked files")
print()
print("Proposed fix: Check symlinks on raw_path (before resolve)")
print("This needs to check both the path itself AND parent directories")
EOF

Repository: littlebearapps/untether

Length of output: 354

---

🏁 Script executed:

python3 << 'EOF'
# Let's also check what the function signature and return type are
with open('src/untether/triggers/fetch.py', 'r') as f:
    lines = f.readlines()
    # Find the function containing line 141-160
    for i in range(140, 0, -1):
        if 'def ' in lines[i]:
            # Print from function definition to line 165
            for j, line in enumerate(lines[i:165], start=i+1):
                print(f"{j:3d} {line}", end='')
            break
EOF

Repository: littlebearapps/untether

Length of output: 1331

---

🏁 Script executed:

head -10 src/untether/triggers/fetch.py

Repository: littlebearapps/untether

Length of output: 333

---

🏁 Script executed:

grep -n "path = Path" src/untether/triggers/fetch.py

Repository: littlebearapps/untether

Length of output: 138

---

Check for symlinks before calling resolve(), which already collapses them.

resolve(strict=False) resolves symlinks to their targets before path.is_symlink() is called, making the symlink guard ineffective. A symlinked fetch target can bypass rejection and read from its resolved location instead. Move the symlink check to the raw path before resolving:

Suggested fix

-    path = Path(fetch.file_path).expanduser().resolve(strict=False)
+    raw_path = Path(fetch.file_path).expanduser()
 
     # Path traversal check.
     if ".." in Path(fetch.file_path).parts:
         msg = f"fetch file_read rejected: path traversal in {fetch.file_path!r}"
         logger.warning("triggers.fetch.path_rejected", path=fetch.file_path)
         return False, msg, None
+
+    if raw_path.is_symlink() or any(parent.is_symlink() for parent in raw_path.parents):
+        msg = f"fetch file_read rejected: {raw_path} uses a symlinked path"
+        logger.warning("triggers.fetch.symlink", path=str(raw_path))
+        return False, msg, None
+
+    path = raw_path.resolve(strict=False)
 
     # Deny-glob check.
     reason = _deny_reason(path)
     if reason is not None:
         msg = f"fetch file_read rejected: path matches deny glob {reason!r}"
         logger.warning("triggers.fetch.denied", path=str(path), deny_glob=reason)
         return False, msg, None
-
-    # Symlink check.
-    if path.is_symlink():
-        msg = f"fetch file_read rejected: {path} is a symlink"
-        logger.warning("triggers.fetch.symlink", path=str(path))
-        return False, msg, None

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/fetch.py` around lines 141 - 160, The symlink guard is
ineffective because resolve(strict=False) is called before checking
path.is_symlink(), so symlinks are collapsed and bypass the check; change the
order so you construct a raw Path from fetch.file_path and call is_symlink() on
that raw path before calling expanduser()/resolve(), returning the same
rejection message if true; keep the existing deny-glob check using _deny_reason
and subsequent resolved path logic unchanged, but ensure you reference
Path(fetch.file_path) for the traversal, symlink and deny checks and only call
expanduser().resolve() after those checks pass.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

Defer file_destination rendering until all form fields are parsed.

The destination template is rendered as soon as the file part is encountered. If the template references a form field that appears later in the multipart body, that value is still missing and the file is written to the wrong path. This makes upload behaviour depend on part order, even though the feature exposes form fields as template variables.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/server.py` around lines 94 - 121, Currently the code
renders webhook.file_destination inside the multipart loop as soon as a file
part is encountered, which can miss form fields that appear later; change the
logic in the async reader loop that handles part (where raw_name/safe_name,
file_data, form_fields["file"] are set) to not call render_template_fields
there, but instead collect file metadata and bytes (e.g., keep safe_name and
file_data in a temp structure or keep form_fields["file"] populated) and finish
parsing all parts; after the async for part in reader loop completes, if
webhook.file_destination is set then call render_template_fields(dest_template,
template_ctx) using the fully-populated form_fields and then perform the final
destination path build and file save. Ensure you update references to
render_template_fields, webhook.file_destination, form_fields, and the file
write logic so rendering is deferred until after parsing completes.

[coderabbitai]

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Check the file size first
wc -l src/untether/triggers/server.py

Repository: littlebearapps/untether

Length of output: 102

---

🏁 Script executed:

# Read the specific sections mentioned in the review
echo "=== Lines 203-206 ===" && sed -n '200,210p' src/untether/triggers/server.py && \
echo -e "\n=== Lines 314-347 ===" && sed -n '314,350p' src/untether/triggers/server.py

Repository: littlebearapps/untether

Length of output: 2122

---

🏁 Script executed:

# Get more context around those lines to understand the implementation
echo "=== Context around lines 203-206 ===" && sed -n '190,220p' src/untether/triggers/server.py && \
echo -e "\n=== Context around lines 314-347 ===" && sed -n '305,360p' src/untether/triggers/server.py

Repository: littlebearapps/untether

Length of output: 3403

---

🏁 Script executed:

# Check if runner.cleanup() exists and how it handles cleanup
echo "=== Looking for cleanup method ===" && rg -n "def cleanup|async def cleanup" src/untether/triggers/server.py -A 20

Repository: littlebearapps/untether

Length of output: 101

---

🏁 Script executed:

# Check imports to see if anyio or asyncio is being used
echo "=== Top of file (imports) ===" && head -50 src/untether/triggers/server.py

Repository: littlebearapps/untether

Length of output: 1641

---

🏁 Script executed:

# Search for anyio task group usage in the file
echo "=== Looking for anyio task group usage ===" && rg -n "create_task_group|TaskGroup|anyio" src/untether/triggers/server.py -B 2 -A 2

Repository: littlebearapps/untether

Length of output: 508

---

🏁 Script executed:

# Let me get the full file to understand the structure better
cat -n src/untether/triggers/server.py | head -100

Repository: littlebearapps/untether

Length of output: 3832

---

🏁 Script executed:

# Get the specific lines and full context for analysis
sed -n '1,50p' src/untether/triggers/server.py && \
echo "=== KEY SECTION: Lines 200-230 ===" && \
sed -n '200,230p' src/untether/triggers/server.py && \
echo "=== KEY SECTION: Lines 310-360 ===" && \
sed -n '310,360p' src/untether/triggers/server.py

Repository: littlebearapps/untether

Length of output: 4833

---

🏁 Script executed:

# Let's check the entire file efficiently
python3 <<'PYTHON_EOF'
with open('src/untether/triggers/server.py', 'r') as f:
    lines = f.readlines()

# Print lines 1-50 (imports and class start)
print("=== LINES 1-50 (Imports & Class Start) ===")
for i in range(0, min(50, len(lines))):
    print(f"{i+1:3d}: {lines[i]}", end='')

# Print lines 200-230 (dispatch_tasks declaration)
print("\n\n=== LINES 200-230 (Dispatch Tasks Declaration) ===")
for i in range(199, min(230, len(lines))):
    print(f"{i+1:3d}: {lines[i]}", end='')

# Print lines 310-360 (task creation & cleanup)
print("\n\n=== LINES 310-360 (Task Creation) ===")
for i in range(309, min(360, len(lines))):
    print(f"{i+1:3d}: {lines[i]}", end='')

# Search for cleanup method
print("\n\n=== CLEANUP METHOD ===")
for i, line in enumerate(lines):
    if 'def cleanup' in line or 'async def cleanup' in line:
        # Print context around cleanup
        start = max(0, i - 2)
        end = min(len(lines), i + 30)
        for j in range(start, end):
            print(f"{j+1:3d}: {lines[j]}", end='')
        break
PYTHON_EOF

Repository: littlebearapps/untether

Length of output: 5584

---

🏁 Script executed:

# Check if there's any anyio task group usage and how asyncio.create_task is used
python3 <<'PYTHON_EOF'
import re

with open('src/untether/triggers/server.py', 'r') as f:
    content = f.read()
    lines = content.split('\n')

# Check imports
print("=== IMPORTS ===")
for i, line in enumerate(lines[:60], 1):
    if 'import' in line.lower():
        print(f"{i:3d}: {line}")

# Search for asyncio.create_task usage
print("\n=== ASYNCIO.CREATE_TASK USAGE ===")
for i, line in enumerate(lines, 1):
    if 'create_task' in line.lower():
        start = max(0, i-3)
        end = min(len(lines), i+2)
        for j in range(start, end):
            marker = ">>>" if j == i-1 else "   "
            print(f"{marker} {j+1:3d}: {lines[j]}")
        print()

# Search for cleanup or cancel logic
print("\n=== CLEANUP/CANCEL PATTERNS ===")
for i, line in enumerate(lines, 1):
    if 'cleanup' in line.lower() or ('cancel' in line.lower() and i > 200):
        start = max(0, i-2)
        end = min(len(lines), i+8)
        for j in range(start, end):
            marker = ">>>" if j == i-1 else "   "
            print(f"{marker} {j+1:3d}: {lines[j]}")
        print()
PYTHON_EOF

Repository: littlebearapps/untether

Length of output: 1869

---

🏁 Script executed:

# Direct view of the file with line numbers - let's focus on key sections
cat -n src/untether/triggers/server.py | sed -n '1,60p' && echo "..." && \
cat -n src/untether/triggers/server.py | sed -n '195,225p' && echo "..." && \
cat -n src/untether/triggers/server.py | sed -n '305,360p'

Repository: littlebearapps/untether

Length of output: 6259

---

🏁 Script executed:

wc -l src/untether/triggers/server.py && \
echo "=== FULL FILE ===" && \
cat src/untether/triggers/server.py

Repository: littlebearapps/untether

Length of output: 13777

---

🏁 Script executed:

# Search for all create_task or dispatch_tasks references
rg -n "create_task|dispatch_tasks" src/untether/triggers/server.py -B 3 -A 3

Repository: littlebearapps/untether

Length of output: 1202

---

🏁 Script executed:

# Let's also check the runner class and its lifecycle
rg -n "class.*Server|def cleanup|async def cleanup|__aexit__|runner" src/untether/triggers/server.py -B 1 -A 1

Repository: littlebearapps/untether

Length of output: 315

---

🏁 Script executed:

# Check the exact file content one more time with proper formatting
python3 <<'PYTHON_EOF'
with open('src/untether/triggers/server.py', 'r') as f:
    lines = f.readlines()

print(f"Total lines: {len(lines)}\n")

# Print entire file with line numbers for analysis
for i, line in enumerate(lines, 1):
    print(f"{i:3d}: {line}", end='')
PYTHON_EOF

Repository: littlebearapps/untether

Length of output: 15646

---

🏁 Script executed:

# Get lines 314-347 specifically
sed -n '314,347p' src/untether/triggers/server.py | cat -n

Repository: littlebearapps/untether

Length of output: 1730

---

🏁 Script executed:

# Get full context including cleanup methods
python3 <<'PYTHON_EOF'
with open('src/untether/triggers/server.py', 'r') as f:
    content = f.read()

# Extract and print the exact lines
lines = content.split('\n')

# Show lines around the key areas
sections = [
    (0, 30, "IMPORTS & START"),
    (200, 210, "DISPATCH_TASKS DECLARATION"),
    (310, 350, "DISPATCH_WEBHOOK & TASK CREATION"),
]

for start, end, label in sections:
    print(f"\n{'='*60}")
    print(f"{label} (LINES {start+1}-{end+1})")
    print('='*60)
    for i in range(start, min(end, len(lines))):
        print(f"{i+1:3d}: {lines[i]}")

# Search for cleanup
print(f"\n{'='*60}")
print("CLEANUP METHODS")
print('='*60)
for i, line in enumerate(lines):
    if 'cleanup' in line.lower() or '__aexit__' in line:
        start = max(0, i - 2)
        end = min(len(lines), i + 25)
        for j in range(start, end):
            print(f"{j+1:3d}: {lines[j]}")
        print()
PYTHON_EOF

Repository: littlebearapps/untether

Length of output: 4164

---

🏁 Script executed:

# Comprehensive analysis of the code
python3 <<'PYTHON_EOF'
import re

with open('src/untether/triggers/server.py', 'r') as f:
    content = f.read()
    lines = content.split('\n')

# 1. Check imports
print("IMPORT ANALYSIS:")
print("-" * 60)
asyncio_imported = False
anyio_imported = False
for i, line in enumerate(lines[:50], 1):
    if 'import asyncio' in line:
        asyncio_imported = True
        print(f"Line {i}: {line} ✓ asyncio imported")
    if 'import anyio' in line:
        anyio_imported = True
        print(f"Line {i}: {line} ✓ anyio imported")

# 2. Check _dispatch_tasks declaration
print("\n_DISPATCH_TASKS DECLARATION:")
print("-" * 60)
for i, line in enumerate(lines[200:210], 201):
    if '_dispatch_tasks' in line:
        print(f"Line {i}: {line} ✓ Found")
        if 'asyncio.Task' in line:
            print("  → Uses asyncio.Task")

# 3. Check task creation in dispatch_webhook
print("\nTASK CREATION IN DISPATCH_WEBHOOK:")
print("-" * 60)
in_dispatch_webhook = False
for i, line in enumerate(lines, 1):
    if 'def dispatch_webhook' in line or 'async def dispatch_webhook' in line:
        in_dispatch_webhook = True
        start_idx = i - 1
    if in_dispatch_webhook and 'create_task' in line.lower():
        print(f"Line {i}: {line}")
        if 'asyncio.create_task' in line:
            print("  → Uses asyncio.create_task()")
        elif 'anyio' in line:
            print("  → Uses anyio")
        # Get context
        for j in range(max(0, i-5), min(len(lines), i+5)):
            if j != i-1:
                print(f"  {j+1:3d}: {lines[j]}")
        break

# 4. Check cleanup handling
print("\nCLEANUP HANDLING:")
print("-" * 60)
for i, line in enumerate(lines, 1):
    if '__aexit__' in line or 'async def cleanup' in line or 'def cleanup' in line:
        print(f"Found cleanup at line {i}: {line}")
        # Show context
        for j in range(max(0, i-2), min(len(lines), i+20)):
            print(f"  {j+1:3d}: {lines[j]}")
        if '_dispatch_tasks' in '\n'.join(lines[i:i+20]):
            print("  → _dispatch_tasks mentioned in cleanup ✓")
        else:
            print("  → _dispatch_tasks NOT mentioned in cleanup ✗")
        break

# 5. Task self-removal pattern
print("\nTASK SELF-REMOVAL PATTERN:")
print("-" * 60)
for i, line in enumerate(lines, 1):
    if 'remove' in line and '_dispatch_tasks' in line:
        for j in range(max(0, i-3), min(len(lines), i+3)):
            print(f"  {j+1:3d}: {lines[j]}")
        print()

PYTHON_EOF

Repository: littlebearapps/untether

Length of output: 674

---

Replace raw asyncio.create_task() with anyio task group management.

The code uses asyncio.create_task() (lines 329, 344) to spawn webhook handlers, bypassing anyio's structured concurrency. These tasks are tracked only in _dispatch_tasks with a done-callback; runner.cleanup() won't cancel or wait for them on shutdown, risking in-flight webhooks outliving the server and racing against transport teardown. Create dispatch tasks within an anyio task group to ensure they're properly cancelled on cleanup, per the coding guideline requiring anyio for async operations.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/untether/triggers/server.py` around lines 203 - 206, Replace the ad-hoc
asyncio.create_task usage and _dispatch_tasks bookkeeping in the webhook
dispatch logic with an anyio TaskGroup: create an anyio.create_task_group() (or
self._task_group managed on startup/shutdown) and start webhook handler
coroutines within that group instead of asyncio.create_task; remove the
done-callback and the _dispatch_tasks set, and ensure the group's cancel/finish
is invoked during runner.cleanup() (or server shutdown) so in-flight dispatch
handlers are cancelled and awaited automatically. Target the code that spawns
webhook handler coroutines (the locations currently calling asyncio.create_task
to run the dispatch/webhook handler) and the shutdown path that calls
runner.cleanup() to wire the task group lifecycle.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Test the raw trigger source shape here, not a preformatted footer fragment.

format_meta_line() is fed cron:<id> / webhook:<id> metadata in production, but these cases pass strings that already include ⏰ / ⚡. That means a regression in the icon/prefix mapping can still leave this file green.

💡 Suggested test update

-        out = format_meta_line({"trigger": "\u23f0 cron:daily-review"})
+        out = format_meta_line({"trigger": "cron:daily-review"})
         assert out == "\u23f0 cron:daily-review"
@@
-            {"trigger": "\u23f0 cron:daily-review", "model": "claude-opus-4-6"}
+            {"trigger": "cron:daily-review", "model": "claude-opus-4-6"}
@@
-        out = format_meta_line({"trigger": "\u26a1 webhook:github-push"})
+        out = format_meta_line({"trigger": "webhook:github-push"})
         assert out == "\u26a1 webhook:github-push"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	def test_trigger_only(self):
	out = format_meta_line({"trigger": "\u23f0 cron:daily-review"})
	assert out == "\u23f0 cron:daily-review"
	def test_trigger_with_model(self):
	out = format_meta_line(
	{"trigger": "\u23f0 cron:daily-review", "model": "claude-opus-4-6"}
	)
	assert out is not None
	assert "\u23f0 cron:daily-review" in out
	assert "opus" in out.lower()
	# Model must come before trigger in the part order.
	parts = out.split(" \u00b7 ")
	assert parts.index("\u23f0 cron:daily-review") == len(parts) - 1
	def test_trigger_webhook(self):
	out = format_meta_line({"trigger": "\u26a1 webhook:github-push"})
	assert out == "\u26a1 webhook:github-push"
	def test_trigger_only(self):
	out = format_meta_line({"trigger": "cron:daily-review"})
	assert out == "\u23f0 cron:daily-review"
	def test_trigger_with_model(self):
	out = format_meta_line(
	{"trigger": "cron:daily-review", "model": "claude-opus-4-6"}
	)
	assert out is not None
	assert "\u23f0 cron:daily-review" in out
	assert "opus" in out.lower()
	# Model must come before trigger in the part order.
	parts = out.split(" \u00b7 ")
	assert parts.index("\u23f0 cron:daily-review") == len(parts) - 1
	def test_trigger_webhook(self):
	out = format_meta_line({"trigger": "webhook:github-push"})
	assert out == "\u26a1 webhook:github-push"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/test_trigger_meta_line.py` around lines 9 - 26, Update the tests to
pass the raw trigger source strings (e.g., "cron:daily-review" and
"webhook:github-push") into format_meta_line instead of already-prefixed strings
with icons; change assertions in test_trigger_only, test_trigger_with_model and
test_trigger_webhook to verify that format_meta_line prepends the correct
icon/prefix to the raw source (e.g., resulting string contains the expected icon
+ space + the raw source), and in test_trigger_with_model ensure the computed
part (the full "icon + space + trigger" fragment) appears as the last element
when splitting by " · " and that the model name (e.g., "opus") appears earlier.