feat: external task integration — intake, overnight scheduling, and result write-back ("cron for Claude Code")

[caoergou]

External task integration: make owloop the night shift for tasks defined during the day

Vision

Today's flow: user writes spec → owloop run → agent executes → results stay on local disk.

Target flow:

Day:    GitHub Issue / Jira / TAPD / Feishu task labeled `owloop:auto`
        │  owloop sync  (task → spec, with clarify gate + provenance)
Night:  ▼  scheduled `owloop run` (locked, budgeted, verified per #32/#33/#34)
        │  per-spec outcome write-back (comment + label + branch/PR)
Morning:▼  digest report to Slack/Feishu/issue — "here's what shipped, here's what's stuck"

This upgrades owloop from a dev tool you babysit into an automation teammate: "every night at 2 a.m., owloop picks up the tasks marked auto, runs them to green, and posts a report by 8 a.m." The tagline writes itself: cron for Claude Code.

This issue is the design + research record for that track. It deliberately builds on top of the trust core (#32 deterministic gate, #33 terminal states, #34 rollback) — unattended scheduling without those is how you wake up to a wrecked branch.

---

Part 1 — Where owloop stands today (code audit)

Capability	Status	Evidence
Task queue	✅ solid, file-based	spec_queue.py: priority, ## Depends On, topological get_next_ready_spec() — already a miniature dependency-aware task DB
Task intake from outside	🟡 embryonic	spec-from-issue (spec_from_issue.py): GitHub-only, one-shot, one-way; fetches via gh, renders spec template, checklist items → candidate criteria. Jira is a NotImplementedError stub. No provenance stored, no idempotency, no state write-back
Scheduling	❌ none	owloop run is a foreground process; "run overnight" currently means the user hand-writes a cron entry with no lock, no budget enforcement, no report delivery
Result output	🟡 local only	owloop_summary_latest.json, events.jsonl, HTML report (report.py + report_ai.py). Nothing leaves the machine; a loop that stops on BLOCKED at 2 a.m. wastes the night silently (already noted in #37 Phase 2)
Mid-run steering	✅	STEERING.md, run-notes.md, .owloop/learnings.md — good primitives to carry task-source context into iterations
Sessions/resume	✅	session_latest.json, --resume, per-session worktrees — the building blocks a scheduler needs to recover from interrupted nights

Key structural observation: the loop engine never needs to know about external systems. specs/ is already the interface. External integration should be an airlock around the loop (sync-in before, write-back after), not a modification of the loop itself. This preserves the "fresh context per iteration, state on disk" principle verbatim.

Part 2 — How comparable systems do it (research survey, verified 2026-07-06)

System	Task intake	Result output	Anti-chaos mechanism
Ralph lineage (fork parent, official plugin)	specs/*.md, IMPLEMENTATION_PLAN.md on disk	git commits; completion log; Telegram notify (fork)	backpressure = tests/lint/build; per-spec attempt counter → stuck after N tries → "decompose the spec"
OpenHands resolver	fix-me label on an issue or @openhands-agent comment	draft PR on success; on failure: WIP branch + issue comment explaining outcome	label removed after processing → trigger consumed exactly once (idempotency); iteration cap; humans review every PR
Copilot coding agent	assign an issue to Copilot	PR opened immediately; plan posted as a live checklist on the PR, items checked off as it works	ephemeral env per issue; egress firewall; CI on its commits needs human approval
Google Jules / OpenAI Codex cloud	task pool via UI / issue refs; AGENTS.md standing instructions	PRs	VM/container per task; Codex: setup-with-network then execute-offline; plan-approval step
claude-code-action	GitHub events, @claude mentions, schedule: cron with explicit prompt	issue/PR comments with progress checkboxes; branches; PRs	--max-turns per invocation; scoped app permissions; workflow timeouts
SWE-agent / mini-SWE-agent batch mode	task-list file, one isolated env per instance, N parallel workers	predictions/patch file	evaluation is a separate process the agent cannot touch; per-instance cost/step budgets
Aider scripting	--message / --message-file, looped by shell	direct commits	git as undo; --test-cmd/--lint-cmd gates
continuous-claude	one goal + SHARED_TASK_NOTES.md scratchpad	one merged PR per iteration	--max-cost USD cap, --max-duration; done-signal required 3 iterations in a row; stall threshold → pause + diagnostics for human
beads (Yegge)	JSONL issues in git + SQLite cache; dependency graph with auto-"ready" detection; hash IDs avoid multi-agent collisions	git-native	queue shared across agents/machines through git itself
Backlog.md / vibe-kanban	markdown+frontmatter tasks / Kanban over 10+ agents	board, PRs	worktree-per-attempt (converges with owloop); note: vibe-kanban is sunsetting — heavy orchestration UIs don't survive; file-based queues do
Spec Kit / Kiro	issue-shaped intent → constitution → spec → derived tasks	—	clarify gate before generation; EARS acceptance criteria; dependency waves

Cross-framework patterns that matter here

1. Label-as-trigger, label-removal-as-ack (OpenHands) is the cleanest idempotency contract for issue-tracker intake.
2. Failure must still produce an artifact — WIP branch + comment beats silent retry, everywhere it's tried.
3. Task intake converges on structured files in git; issue trackers are the second channel, synced in, never driving the loop live.
4. Multiple independent bounds, always: iteration + cost + wall-clock + per-task attempt caps; mature systems layer at least two.
5. Nobody auto-closes the source task. PRs/comments propose; humans dispose. Copilot, OpenHands, Jules, Codex all keep a human on merge.
6. A scheduled agent needs a scratchpad and a lock: PID-file locking with stale detection and persisted resume state are standard reliability plumbing for cron-driven agent runs.
7. Scheduled human intent-review every N tasks/hours — tests verify behavior, humans verify intent; drift that passes CI is still drift.

---

Part 3 — Proposed design (five layers, each independently shippable)

Layer 1 — Task intake: owloop sync + pluggable TaskSource

Evolve spec_from_issue.py into a TaskSource adapter interface (mirroring adapters.py for agents):

class TaskSource(Protocol):
    def poll(self) -> list[ExternalTask]      # tasks matching the trigger (e.g. label owloop:auto)
    def acknowledge(self, task) -> None       # consume the trigger (remove/flip label) — idempotency
    def write_back(self, task, outcome) -> None  # comment + label transition

• GitHub Issues first (gh already used), Jira next (stub exists), TAPD/Feishu/linear behind the same interface. A generic todo.md source (checklist file in-repo) covers the no-tracker case and is the cheapest to ship.
• Trigger contract: label owloop:auto (or checklist tag @auto). On sync, flip to owloop:queued — the trigger is consumed exactly once even if sync runs twice.
• Clarify gate at the boundary (feat(spec): clarify gate before generation + converge sweep after the queue empties #36's gate, applied to imports): an issue with no shell-verifiable acceptance criteria does not enter the night queue. It gets labeled owloop:needs-spec with a comment listing what's missing (spec linter feat: inject linter rules into spec generation and auto-retry on lint errors #9 + --dry-run calibration feat: add dry-run / one-shot mode to validate specs without burning tokens #11 as the mechanical check). Ambiguity that survives into a spec becomes an overnight run in the wrong direction — filter it at intake, in daylight, when a human can answer.

Layer 2 — Spec as contract: provenance frontmatter

Synced specs carry a machine-readable provenance block:

---
source: github            # github | jira | tapd | feishu | todo
source_id: "caoergou/owloop#123"
source_url: https://github.com/caoergou/owloop/issues/123
synced_at: 2026-07-06T18:00:00Z
source_hash: sha256:…     # hash of imported title+body
---

• source_hash makes re-sync idempotent (same issue → same spec, updated only if upstream changed) and makes divergence detectable: if the upstream issue changed after sync, the spec is flagged stale rather than silently running against yesterday's requirements.
• The loop never reads external systems. Sync-in and write-back are separate commands around the run — an airlock, not a live pipe. Fresh-context-per-iteration stays intact; a network-dead night still runs everything already in specs/.

Layer 3 — Night shift: owloop schedule / owloop night

• owloop schedule "02:00" --max-duration 300 --max-tokens 2m emits the right artifact per platform: cron/systemd-timer/launchd entry, or a GitHub Actions workflow (schedule: + claude-code-action-style bounded run) for repo-hosted nights.
• owloop night = the composed pipeline sync → run → write-back → report as one command, so the scheduler entry is a single line.
• Scheduled mode refuses to start unbounded: at least one of --max-iterations/--max-duration/--max-tokens (plus --max-cost when feat(adapter): pass native hard limits (--max-turns, budget caps) through to claude -p #35/feat: real-time token tracking with per-iteration budget cap #15 land) must be set. exhausted ≠ success per feat(engine): named terminal states + hard stop on stall (stuck detection as a first-class citizen) #33.
• Single-writer lock: PID lockfile with stale detection in .owloop/ — a 2 a.m. cron firing while yesterday's run is still going must no-op loudly, not double-run. Overlap is the feat: separate verifier agent from executor agent #1 source of the "错乱" this issue exists to prevent.
• Pre-run gate: only specs that pass owloop check and have ≥1 runnable acceptance command are eligible; the rest are skipped and reported, not attempted.

Layer 4 — Write-back: results flow to where the task came from

Per-spec terminal state (from #33's taxonomy) maps to source-side actions:

Outcome	Issue label	Comment	Git artifact
verified done (#32 gate passed)	owloop:done	summary + commit links + criteria results	pushed branch (or PR with --pr-per-spec)
stalled / stuck	owloop:stuck	failure classification, attempts, last error tail	WIP branch + discarded-diff patch (#34) — failure still produces an artifact
blocked / decide	owloop:blocked	the BLOCKED:/DECIDE: payload, verbatim — the morning human's first read	—

• Never auto-close the source issue. owloop proposes; the human disposes (unanimous across Copilot/OpenHands/Jules/Codex). Optionally auto-close only when a linked PR merges — GitHub's own machinery, not ours.
• Write-back is at-least-once with dedup: comments carry a <!-- owloop:run-id:spec --> marker so a re-run after a crash updates rather than duplicates.

Layer 5 — Morning report

• Extend report.py's existing summary/events into a digest: per-spec outcome table, tokens/cost, stuck items with reasons, links to branches/PRs. Deliver via generic webhook (Slack/Feishu/Discord all accept a JSON POST) and/or a pinned "night report" issue comment.
• Immediate (not morning) notification on BLOCKED/DECIDE/stalled — meta: loop-engineering roadmap — from prompt-level conventions to enforced invariants #37 Phase 2 already lists this; it's required for scheduled mode, since a silently-stopped 2 a.m. loop wastes the whole night.

Part 4 — Why this doesn't produce chaos (guarantee map)

Risk	Mitigation	Where
Same task imported/run twice	label-consumed-on-sync + source_hash idempotency	Layer 1/2
Two runs on one repo overnight	single-writer lockfile with stale detection	Layer 3
Vague day-time task → wrong overnight work	clarify gate at intake; unverifiable tasks parked as needs-spec in daylight	Layer 1
Agent self-reports success	engine-owned verification gate	#32 (prerequisite)
Failure loop burns the night	hard stop on stall, named terminal states, budget floors mandatory in scheduled mode	#33 (prerequisite) + Layer 3
Failed iteration poisons the next	rollback + discarded-diff patch	#34 (prerequisite)
Upstream issue edited mid-night	loop reads only the synced spec (airlock); staleness flagged at next sync	Layer 2
Results lost / duplicated on crash	at-least-once write-back with comment markers; session resume	Layer 4
Silent 2 a.m. stop	immediate notify on BLOCKED/DECIDE/stalled	Layer 5
Intent drift that passes tests	report is designed for a mandatory human morning review; nothing merges or closes itself	Layer 4/5

Phased plan

Phase I — intake foundations (no scheduler yet, immediately useful interactively)

• TaskSource protocol; refactor spec_from_issue.py into GitHubIssueSource
• Provenance frontmatter written on import; source_hash idempotent re-sync
• todo.md source (in-repo checklist with @auto tag)
• Intake clarify gate: linter + runnable-criteria check; needs-spec outcome

Phase II — night shift (gated on #32 + #33 + #34)

• Lockfile with stale detection
• owloop night composed command; scheduled mode requires bounds
• owloop schedule emitting cron/systemd/launchd/GitHub Actions artifacts

Phase III — write-back & report

• Per-spec outcome → label transition + deduped comment; WIP branch on stuck
• --pr-per-spec option
• Webhook digest (Slack/Feishu-compatible JSON POST) + immediate BLOCKED/DECIDE/stalled notify

Phase IV — more sources

• Jira (replace the stub), TAPD, Feishu tasks behind TaskSource

Non-goals

• No Kanban/orchestration UI — vibe-kanban's sunset is the cautionary tale; the file queue is the product.
• No live bidirectional sync during a run — airlock only.
• No auto-closing of external tasks, ever.
• No parallel workers here — that's perf: speed-focused deep analysis — cut wasted minutes per iteration, then parallelize #49 item 9, gated on its own prerequisites.

References

ghuntley.com/ralph · anthropics/claude-code ralph-wiggum plugin · fstandhartinger/ralph-wiggum · OpenHands resolver docs · GitHub Copilot coding agent docs · jules.google · developers.openai.com/codex/cloud · anthropics/claude-code-action · SWE-agent/mini-swe-agent batch mode · aider.chat/docs/scripting · AnandChowdhary/continuous-claude · steveyegge/beads · MrLesk/Backlog.md · BloopAI/vibe-kanban · github/spec-kit · kiro.dev/docs/specs

Relates to: #32 #33 #34 (prerequisites for Phase II) · #35 #15 (budget caps the scheduler depends on) · #36 (clarify gate reused at intake) · #37 (this is the "integration track" alongside its trust track) · #49 (perf track; parallelism explicitly out of scope here) · #9 #11 (linter/dry-run as the intake gate's mechanical checks)

[caoergou]

Layer 6 supplement — bidirectional answer channel ("the loop can ask; you can answer from your phone")

Why notification alone is not enough

Layer 5 above treats the human as a read-only subscriber. But the single biggest determinant of an overnight run's resolution rate is whether a DECIDE/BLOCKED question raised at 11 p.m. can be answered at 11:20 p.m. from a phone — turning a wasted night into a productive one. Two facts make this urgent and cheap for owloop:

1. Today DECIDE/BLOCKED are a global brake. engine.run() breaks the entire loop (engine.py promise handling) — one clarifying question on spec 1 kills the remaining 8 hours and every other ready spec. Survey result below: no surveyed framework halts everything on one question — owloop is currently the outlier.
2. The answer-injection mechanism already exists. STEERING.md is read into the prompt at every iteration start (engine.py:_build_prompt_with_context). A reply channel doesn't need to touch the engine's execution model at all — it just needs to be an authenticated remote write to a steering file. The airlock principle survives intact.

Survey: how existing systems do ask-and-answer (verified 2026-07-06)

System	Channel	Reply → resume semantics	Parking behavior
HumanLayer / 12-Factor Agents, Factor 7	Slack/email/Discord via cloud API	"Contact human" is a tool call; thread serialized to an event log, process exits; reply event appended later, thread reloaded and resumed	Non-blocking by design. (Note: SDK now deprecated — company pivoted to CodeLayer; copy the shape, not the dependency)
Devin Slack	Slack, 1 thread = 1 session	In-thread replies steer the live session; mute/(aside) keywords keep human chatter out of agent context	Strong: parallel sessions; a waiting session blocks only itself
OpenHands resolver	GitHub issue/PR comments	No process waits at all: failure → branch + comment; human replies → fresh run re-reads the whole thread. The issue thread is the durable state	Trivially — nothing runs between attempts. Replies gated by author association (OWNER/COLLABORATOR/MEMBER)
Copilot coding agent	PR comments + live-session prompt box	Comment batch spawns a fresh session against current PR state	Artifact-anchored, same as OpenHands
Claude Code Channels (official research preview)	Telegram / Discord / iMessage plugins	MCP plugin polls the Bot API (explicitly no public endpoint) and injects messages into the running session; can even relay permission prompts to your phone	Security model to copy: pairing-code bootstrap + sender allowlist, everyone else silently dropped. Known gap: no queue — offline messages lost
LangGraph interrupt()	channel-agnostic	State persisted by checkpointer; any process later calls Command(resume=value); the interrupted node re-executes from its start (idempotence required)	Parallel branches keep running; multiple pending interrupts resumable in one call
Temporal signals	any	wait_condition parks the workflow server-side at zero compute; external Signal sets state; durable timer enforces a default on timeout	Native — sibling workflows unaffected
Community Claude Code wrappers (claude-push, ntfy hooks, claude-code-telegram)	ntfy.sh / Telegram	Hook → push with action buttons → hook long-polls a response topic → exit code approves/denies	Converged pattern: outbound-only transports, no public endpoint

Transport reality check (owloop runs on a dev machine — no public HTTP endpoint)

Transport	Bidirectional without public endpoint?	Notes
Telegram Bot API	✅ getUpdates long-poll	stdlib-only (urllib), free, messages retained ~24 h server-side if poller is briefly down — strictly better than Channels' lossy design
ntfy.sh (two topics)	✅ publish = one curl; subscribe via poll=1/SSE; action buttons publish to a response topic	zero accounts; no threading/identity — pair with access tokens or self-host
Slack Socket Mode	✅ outbound WebSocket	fine for teams; needs SDK + app-token; barred from public Marketplace distribution
Feishu/飞书	⚠️ custom group-webhook bots are outbound-only — notify yes, receive no. Bidirectional requires a platform app with event subscription via callback or the SDK's long-connection (WebSocket) mode (no public IP needed, but full app registration; may be unavailable on international Lark)	Feishu = notify-only in v1, upgrade path documented
GitHub issue comments	✅ poll via API	zero new infra for GitHub-hosted repos; slow, and questions are public — the fallback, not the default

Proposed design

6.1 Park, don't halt (the scheduling change — the real unlock)

On DECIDE/BLOCKED, instead of break:

• mark that spec Status: WAITING_ON_HUMAN with a pointer to its question file,
• return to the queue and pick the next ready spec (get_next_ready_spec already excludes non-ready specs — a parked spec is just one more not-ready state),
• stop the run only when nothing is runnable and no answer can still arrive (or budget/duration ends).

A question at 11 p.m. then costs one spec, not the night. Depends on #33's per-spec terminal-state work; WAITING_ON_HUMAN should join that taxonomy.

6.2 Question outbox / answer inbox as files (airlock preserved)

The engine never talks to Telegram/Slack. It writes and reads disk:

.owloop/questions/012-fix-auth.md      # question, options, deadline, default, thread-id
.owloop/steering/012-fix-auth.md       # per-spec steering; answer lands here, attributed

• Question format reuses what spec_generator.py already emits for DECIDE (multiple |-separated questions with proposed defaults — the feat(spec): clarify gate before generation + converge sweep after the queue empties #36 clarify format). Every question carries a deadline + default action (Temporal pattern): "if no answer by 06:00 → skip this spec". An unanswered question must never wedge the night; unanswered questions headline the morning report.
• Generalize STEERING.md → per-spec .owloop/steering/<spec>.md (global file stays for run-wide guidance). The engine change is ~10 lines in _build_prompt_with_context.

6.3 AnswerChannel adapter (sibling of Layer 1's TaskSource)

class AnswerChannel(Protocol):
    def post(self, question: Question) -> str        # returns thread/message id
    def poll_replies(self) -> list[Reply]            # long-poll between iterations

The engine's between-iteration gap (where time.sleep(delay) lives today) is the natural poll point. Implementation order: Telegram first (best fit: bidirectional, endpoint-free, stdlib-only, offline-tolerant) → ntfy.sh two-topic (minimal-deps) → Slack Socket Mode (teams) → GitHub comments (fallback) → Feishu (notify-only until someone needs the long-connection app).

6.4 Resume semantics: fresh context makes this easier, not harder

No in-process resume is needed — owloop's own principle does the work. The answer is a durable event on disk; the parked spec re-enters the ready set; the next iteration on it starts fresh with the Q&A injected via steering. This is exactly LangGraph's "re-execute the interrupted node" semantics, which owloop gets for free because every iteration already restarts from disk. The spec queue is the checkpointer.

6.5 Safety (replies are untrusted input, and reply access = steering authority)

• Pairing-code bootstrap + sender allowlist (Claude Code Channels model); default allowlist = one user; everyone else silently dropped.
• Structured replies preferred: questions posted with numbered options / inline buttons; a bare 2 is an unambiguous answer. Free text is accepted but wrapped and attributed as data — Human reply via telegram @ 02:14: "..." — inside the steering file, never spliced raw into the prompt.
• Small command verb set, nothing else executes: /answer <n|text> · /skip · /retry · /steer <text> · /abort · /status. (Devin's mute/aside shows why an explicit command grammar beats interpreting every message.)
• Document plainly: anyone on the allowlist can steer the overnight agent — the Channels docs make the same point about permission relaying.

6.6 Ship order (each step is independently valuable)

1. Notify-first (extends Layer 5, ~1 day): one sendMessage/curl on DECIDE / BLOCKED / stalled / run-complete, carrying the question text and proposed default. Even with no reply path, seeing the question at 11 p.m. lets the user fix the spec and rerun.
2. Reply poller (AnswerChannel.poll_replies between iterations → steering file): with parking not yet built, an answer arriving while the run still lives simply un-wedges the current spec's next attempt.
3. Park-and-continue (gated on feat(engine): named terminal states + hard stop on stall (stuck detection as a first-class citizen) #33): the full "one question costs one spec, not the night" behavior.
4. Morning-report integration: answered questions shown with who/when/what; unanswered ones at the top as the human's first task of the day.

Amendments to the plan above

• Phase III gains: [ ] Notify on DECIDE/BLOCKED/stalled via AnswerChannel.post (Telegram + ntfy + webhook)
• New Phase III.5 — answer channel: [ ] AnswerChannel protocol + Telegram getUpdates poller · [ ] per-spec steering injection · [ ] allowlist + pairing + command grammar · [ ] question deadline/default handling
• Phase II (scheduling) gains a cross-dependency: parked-spec state (WAITING_ON_HUMAN) designed together with feat(engine): named terminal states + hard stop on stall (stuck detection as a first-class citizen) #33's taxonomy.
• Guarantee map gains a row: "Loop wedges all night on one question" → park-and-continue + question deadlines with safe defaults (skip, never guess).

---

Generated by Claude Code

[caoergou]

Layer 6 detailed design — question protocol, per-channel rendering, reply protocol, and non-interruption guarantees

The previous comment settled which channels and why. This one specifies the protocol level: what a question is, how it is rendered correctly for each channel, what quality bar the message must meet so the user can decide from the message alone, and how replies flow back without ever interrupting the running loop.

1. The quality problem starts before the channel: today's DECIDE payload is unanswerable

parse_promise_signal gives us one line of free text (promise.py:13). A 2 a.m. push saying "DECIDE: which auth approach should I use?" forces the user to open a laptop, read logs, read the spec — at which point the channel has added nothing. The channel layer can only be as good as the payload, so the first artifact is a canonical Question object with a hard quality contract, and only then per-channel rendering.

1.1 Canonical Question object

# .owloop/questions/q-<run>-<spec>-<seq>.yaml
id: q-a3f2-012-1
kind: decide                # decide | blocked | stalled | approval
spec: 012-fix-auth.md
iteration: 7
title: "Token refresh strategy for the auth middleware?"
context: |                  # ≤600 chars, laptop-free readable
  Implementing 012-fix-auth. The spec requires "sessions survive browser
  restart" but excludes changes to the DB schema. Two ways to satisfy both.
tried: |                    # what already happened, mechanically collected
  Attempt with httpOnly session cookies failed acceptance criterion 3:
  `pytest tests/test_auth.py::test_restart` → AssertionError: token expired
options:
  - key: "1"
    label: "Refresh-token rotation (in-memory store)"
    consequence: "No schema change; adds ~120 LoC to middleware; survives restart"
    recommended: true
  - key: "2"
    label: "Extend access-token TTL to 30 days"
    consequence: "Trivial diff, but weakens the security posture the spec's Style section asks for"
default:                    # what happens if nobody answers — MANDATORY
  action: skip_spec         # skip_spec | take_recommended | stay_parked
  at: "06:00"
links:
  branch: owloop/20260706-a3f2
  log: .owloop/logs/owloop_build_iter_7_*.log

Producer split — agent proposes, engine enriches, renderer never invents:

• The agent emits only what it alone knows: title, context, options with consequences, recommendation. Extend the promise protocol with a structured block the agent writes before the promise line:

  <question>{JSON as above, options+context only}</question>
  <promise>DECIDE:Token refresh strategy?</promise>
  

  Backward compatible: a bare DECIDE:text (old format) still works — the engine synthesizes two options: 1. proceed as the agent last proposed / 2. skip this spec, and marks the question low-fidelity so the renderer prefixes it with the log tail.
• The engine appends mechanical facts the agent may misreport: spec name, iteration, failing acceptance command + exit code + last 10 output lines, git diff --stat, branch name. These come from the engine's own state (_run_acceptance_criteria, _spec_status), not the agent's claims — same trust boundary as feat(engine): deterministic verification gate — engine must own commit, push, and spec completion #32.

1.2 Message quality contract (enforced, not hoped for)

A question is rejected back to the synthesizer (never silently posted raw) unless:

Rule	Why
context ≤ 600 chars and names concrete artifacts (spec, test, file)	must be readable on a lock screen
≥ 2 options, mutually exclusive, each with a one-line consequence	"what should I do?" is not a question; consequences are what let a human choose without reading code
exactly one recommended: true	the reply for the 80% case is one tap/character
default present with a deadline	an unanswered question must resolve itself (Temporal timer pattern); skip_spec is the safe default — never take_recommended unless the user opted in (--auto-default)
reply syntax line generated per channel (see §3)	the user should never have to remember the grammar

2. Channel capability matrix

The renderer targets capabilities, not channels. Adding a channel = filling one row.

Capability	Telegram	Slack (Socket Mode)	ntfy.sh	Feishu custom bot	GitHub comment	Email
Max message size	4096 chars	3000 chars/section block	~4 KB	card JSON limits	65536 chars	effectively unbounded
Rich formatting	HTML / MarkdownV2	Block Kit	plain + title/tags/emoji	interactive card (rich)	full markdown	plain/HTML
Native buttons	✅ inline keyboard; callback_data ≤ 64 bytes → carry question id + option key only	✅ Block Kit actions, action_id	✅ up to 3 action buttons; each can publish a preset reply to the response topic	⚠️ card buttons are URL-jump only for custom bots; callback buttons require a platform app	❌	❌
Threading / correlation	reply-to-message	real threads (thread_ts)	❌ → question id in body	❌ (custom bot)	comment chain on one issue	subject tag [owloop q-…]
Editable after post (ack-by-edit)	✅ editMessageText	✅ chat.update	❌ → post follow-up	❌	✅ edit comment	❌
Inbound path (no public endpoint)	getUpdates long-poll	Socket Mode WebSocket	long-poll response topic	❌ notify-only in v1	API poll for new comments	IMAP poll
Sender identity for allowlist	chat/user id	workspace user id	topic token (weak — self-host or tokens)	n/a	author association	From + DKIM (weak)

Rendering pipeline with graceful degradation

Question ──► render(q, caps) ──► ChannelMessage
degradation ladder, applied per capability:
  buttons          → numbered list + "reply with the number"
  ack-by-edit      → follow-up message ("✅ answered")
  threading        → question id embedded in body; replies must quote it
  rich formatting  → plain text, options as "1) … — consequence"
  size overflow    → context truncated first, then tried-tail; options and
                     default NEVER truncated (they are the decision)

One renderer, golden-file tests per channel (tests/test_channel_render.py — same pattern as the HTML report tests).

3. What the user actually sees (end-to-end example, Telegram)

🦉 owloop needs a decision          [q-a3f2-012-1]
Spec: 012-fix-auth (iteration 7, 2 of 5 specs done)

Token refresh strategy for the auth middleware?

Spec requires "sessions survive browser restart" but excludes DB
schema changes. First attempt (httpOnly session cookies) failed
criterion 3: test_restart → AssertionError: token expired.

1️⃣ Refresh-token rotation, in-memory  ← recommended
    no schema change · ~120 LoC in middleware · survives restart
2️⃣ Extend access-token TTL to 30 days
    trivial diff · weakens the security posture the Style section asks for

⏰ No answer by 06:00 → spec skipped, loop continues with 013.
Branch: owloop/20260706-a3f2

[ 1️⃣ rotation ] [ 2️⃣ TTL ] [ skip spec ]     ← inline buttons
Or reply: 1 / 2 / /skip / /steer <free text>

Every element earns its place: the id line enables correlation, the progress note (2 of 5) tells the user the night is still productive, tried prevents "did you try X?" round-trips, consequences make the options decidable, the deadline line removes the anxiety of having to answer, and the syntax line removes the need to remember anything. This is the quality bar; a channel message that can't carry all of it (ntfy) drops formatting, never content.

Same question on ntfy (degraded): title = question title; body = context + numbered options + deadline + reply: publish "q-a3f2-012-1 1" to <resp-topic>; 3 action buttons preset to option 1 / option 2 / skip. On GitHub: one comment per question with an HTML marker <!-- owloop:question:q-a3f2-012-1 -->, options as a markdown list, answer = reply comment /answer q-a3f2-012-1 1.

4. Reply protocol — correlation, validation, ack, conflicts

Correlation (matching a reply to a question), in priority order:

1. Button callback → carries {question_id, option_key} natively (Telegram callback_data, Slack action_id). Zero ambiguity.
2. Thread reply → thread id maps to question id (Slack; Telegram reply-to).
3. Text containing a question id → explicit match (q-a3f2-012-1 1).
4. Bare option key (1) → accepted only if exactly one question is pending; otherwise the channel answers with the pending-question list and asks the user to disambiguate. Never guess.

Validation, in order, each failure acked with a reason: sender on allowlist → question exists and is posted (not expired/answered) → option key valid or verb in the grammar (/answer /skip /retry /steer /abort /status). Free text after /steer is stored, attributed and fenced, in .owloop/steering/<spec>.md — data, never prompt.

Acknowledgment — the user must see that owloop heard them:

• ack-by-edit channels: original message edited to ✅ Answered: option 1 (by @eric, 02:14) — applies at next iteration on this spec; buttons removed.
• others: follow-up message with the same text.
• at deadline with no answer: edit/follow-up ⏰ Expired → default applied: spec skipped.

Conflicts & duplicates: first valid reply wins and freezes the question (answered); later replies get the current-state ack (already answered: option 1 by @eric at 02:14). A correction window exists until the answer is consumed: /override 2 re-opens iff the question is answered but not yet applied. Since answers are consumed only at an iteration boundary (§5), the window is real but race-free — the state file transition answered → applied happens in the engine's single thread.

Question lifecycle (all transitions are file/status writes, all emitted to events.jsonl):

pending ─post─► posted ─reply─► answered ─consumed─► applied ─spec-outcome─► resolved
                  │                                     
                  └────deadline────► expired ──► default_applied

5. Non-interruption guarantees — the loop never waits for, or on, the channel

This is the invariant the whole layer hangs on: channel I/O must be invisible to the iteration.

1. Posting never blocks. The engine writes the question file (durable, source of truth) and returns; a sender flushes the outbox with retry/backoff. Transport failure = question_post_failed event + the question still appears in the morning report. Files first, transport second — a dead Telegram API costs delivery, never correctness.
2. Polling lives in the dead time. The engine already sleeps between iterations (time.sleep(delay) in run()); replace with channel.poll_replies(timeout=delay) — the long-poll is the sleep. No new threads in v1. (If a poller thread is ever added for sub-iteration latency, its write scope is exactly one directory: .owloop/answers/. It never touches engine state.)
3. Answers apply only at iteration boundaries. A reply arriving mid-iteration is not injected into the running agent — fresh-context-per-iteration is load-bearing here. The next iteration on that spec picks the answer up via per-spec steering. Worst-case latency: one iteration. That is the honest cost of the airlock, and it's the right trade.
4. A question never stops the run (park-and-continue, previous comment): the asking spec goes WAITING_ON_HUMAN, get_next_ready_spec() serves the next spec. The run ends only when nothing is runnable and every pending question has hit its deadline-default.
5. Crash safety: questions, answers, and lifecycle states are files; a crashed and resumed run (--resume) re-posts nothing (state posted is durable), re-consumes nothing (state applied is durable), and Telegram's ~24 h server-side retention covers replies sent while owloop was down — the exact gap Claude Code Channels documents as its known flaw.

6. Scope additions to Phase III.5

• Question schema + quality contract + engine enrichment (mechanical facts from engine state, not agent claims)
• <question> block in the promise protocol, backward-compatible fallback synthesis for bare DECIDE:text
• Capability-matrix renderer with degradation ladder; golden-file tests per channel
• Reply protocol: correlation ladder, validation order, ack-by-edit, first-valid-wins + /override window
• Question lifecycle state machine on disk, all transitions in events.jsonl
• Non-interruption tests: post-with-transport-down, reply-mid-iteration applies next boundary, resume re-posts nothing

With §1's contract in place, the channels stop being a notification gimmick and become what they should be: the loop's way of borrowing 30 seconds of human judgment at 11 p.m. without spending anything else.

---

Generated by Claude Code

[caoergou]

Layer 6 amendment — the drunk test: night questions must be safe to answer badly

Applying a harder quality bar to the §3 example above: could the owner pick the right answer after three beers at 11 p.m.? Honest answer: no. "Refresh-token rotation (~120 LoC) vs. 30-day TTL (weakens security posture)" is a sober architectural tradeoff dressed up as a push notification. An impaired or half-asleep human will either pick wrong, pick randomly, or — worst — pick and not remember. The previous design optimized information completeness; the right night-time metric is different:

A question is night-safe not when it carries enough information to decide well, but when no possible answer causes harm.

This flips the design. Three changes:

1. Night questions are always the same binary, and both answers are safe

The engine never forwards a raw multi-way tradeoff to the channel at night. Whatever the agent asks, the channel message is downgraded to the one decision a tired human can safely make:

🦉 owloop | 012-fix-auth is stuck, I have a plan

I recommend: refresh-token rotation (in-memory) to satisfy
"sessions survive restart". No DB changes. Everything stays
on the branch for your morning review.

[ 👍 Go ahead ]      [ ⏭️ Skip it, ask me tomorrow ]

No answer by 06:00 → skipped automatically.
Either way, nothing merges tonight.

Why this passes the drunk test:

• One decision, recognition not recall: "do I trust the owl's plan enough to let it try?" — a gut call, not an analysis. ≤3 lines before the buttons.
• Both branches are safe: "Go ahead" runs on an isolated worktree branch that nothing merges (Layer 4: owloop never closes/merges anything itself); "Skip" costs one spec until morning. There is no button whose wrong press loses anything. The last line says so explicitly — removing decision anxiety is part of the protocol.
• The recommendation leads; the tradeoff analysis is demoted, not deleted — see §3.

This is also why the reversibility invariant (worktree-only, human-merges-in-the-morning) isn't just a safety feature — it's what makes night-time questions answerable at all. If answers were irreversible, no phrasing could make them drunk-safe.

2. Dangerous verbs can't be fat-fingered

The one-tap surface contains only harmless actions. Anything with real blast radius requires typed confirmation, never a button:

Action	Night interface
approve recommendation / skip spec	one tap
/steer <text>	allowed (it's data for the next iteration, reviewable in the morning report)
/abort (kill the run)	must type /abort a3f2 (run id) — no button, no bare /abort
/override a previous answer	must restate the question id

Sub-rule: free-text /steer sent between 00:00–06:00 gets echoed back in the morning report under "night-time steering you gave" — drunk instructions deserve a sober review too.

3. The full question survives for the sober morning

Downgrading the channel message must not destroy the decision's substance. The complete Question object — all options, consequences, the failing-test evidence — stays in .owloop/questions/… and in the morning report. Outcomes compose:

• Night answer "Go ahead" → agent proceeds with its recommendation; the morning report shows the question and the road not taken, so the owner can still reverse it before merging.
• Night answer "Skip" / expiry → the full multi-option question becomes the top item of the morning report, where multi-way choices belong.
• Configurable quiet hours (questions.night_mode: "22:00-08:00"): inside them, binary downgrade is forced; outside them, the full option list may be sent (a sober human at 3 p.m. can handle §3's original rich format).

So the two formats coexist by time and medium: the channel at night is a consent slip; the repo in the morning is the decision document. The previous comment's rich rendering spec still stands — it's the daytime/morning format; this comment defines the night gate in front of it.

Amended quality contract (supersedes §1.2 row 2–3 during quiet hours)

Rule (night mode)
Exactly 2 actions: approve-recommendation / park	multi-way never crosses the channel at night
Both actions provably reversible; message states it in one line	reversibility is what licenses tired answers
≤3 lines of prose before the buttons	lock-screen readable
Deadline + auto-park default always shown	not answering is a first-class, guilt-free option
Destructive verbs: typed confirmation with run/question id	no one-tap harm

One more checklist item for Phase III.5:

• Night-mode question gate: binary downgrade in quiet hours, typed-confirmation for destructive verbs, night-steering echo in morning report

---

Generated by Claude Code