PLAN v2 · agent-smith · 2026-08-14

Smith PR-Drive v2 — Temporal is the driver

Supersedes v1 after the founder's inversion. Repo: PropFlow-Technologies/agent-smith · future home docs/planning/smith-pr-drive-durable.md

0 · The incident, and what changed since v1

2026-08-14: Smith opened propflowai #5749, said "I'll drive it to mergeable", and ended the turn without running smith-pr-watch add 5749 — the one manual step binding the GitHub webhook to the thread. The bot's 🟡 verdict landed into a dead session; five hours of silence until the human asked why.

v1's answer kept the webhook as the primary driver and added a Temporal backstop — a 10-minute reconcile tick — plus triple auto-arm belts and dedup machinery so the two drivers wouldn't trip over each other.

v2's answer (the founder's): there is one driver, and it is the durable one. SmithPrDriveWorkflow owns the loop: a durable timer (~45s while the PR is active), GitHub truth via the already-registered merge_gate_activity — the exact instrument SmithApprovalWorkflow already polls (approval.py:76,88) — a state fingerprint, and exactly one reasoning turn (claude -p via the synthetic-inbound path) when something actionable changed. The GitHub webhook is removed from Smith's drive path entirely.

Accepted trade-off, precisely: reaction latency becomes one poll tick (~45s worst case vs ~2s webhook) — irrelevant against the 5-hour silent failure this fixes. Cost: merge_gate_activity issues ≤3 gh requests per call (merge_gate.py:116,87,184). At a 45s tick: ≤80 polls/hr → ≤240 requests/hr per open drive; five concurrent drives ≈ 1,200/hr ≈ 24% of the 5,000/hr authenticated REST budget (the GraphQL leg draws ~80 points/hr on its separate budget — noise). For calibration, the approval workflow's existing _GATE_POLL is already 15s during gating.

Merge stays human-gated, untouched. The drive never merges. A woken turn that reaches green announces Mergeable:; start_approval_if_mergeable starts the untouched SmithApprovalWorkflow; a human ✅ approves; the approval merges. The drive observes MERGED on its next tick and completes.

1 · What v1 got wrong — owned explicitly

v1 treated the webhook as the asset and Temporal as the insurance. That inverted the actual reliability ordering: the webhook path is a chain of five single-points-of-failure (GitHub delivery → cloudflared tunnel → launchd → Node listener → watch-file registry), while the Temporal worker is the one component whose liveness the agent already depends on and monitors. v1 then spent its complexity budget making two drivers coexist instead of asking whether the second driver should exist. The founder caught it: approval.py had already proven the pattern (a durable timer polling merge_gate_activity for up to 24h per PR); the drive is the same loop on the pre-mergeable half of the PR's life, and the webhook adds a ~43-second latency improvement priced at three failure modes.

What survives from v1 unchanged: the pr_open_detect.py pure parser and its mentioned-vs-opened discipline; the decision against extending SmithTaskWatchWorkflow (wrong keying, wrong caps, and its "disarmed of real-send risk by construction" safety constitution, task_watch.py:36-43, which a turn-spawning drive would delete); the approval-precedent match; the wake path through dispatcher.dispatch(); one-wake-per-fingerprint + escalation + budget; the replay-safety reasoning for the reply hook.

2 · Constitution fit (§1 DRY, §2 precedents)

3 · SmithPrDriveWorkflow — the driver

3.1 Identity & types

• Workflow id: smith-pr-drive-<repo__slug>-<pr> via new PR_DRIVE_WF_ID_PREFIX in agent_ident.py (beside APPROVAL_WF_ID_PREFIX). One drive per (repo, PR); re-arm of an open drive is a no-op; after completion the same id may start fresh.
• Task queue: propflow-smith (interactive pool, the approval child's sibling; single-home registration per the worker manifest invariant).
• PrDriveRequest carries repo, pr_number, chat_jid, thread_ts, anchor_key, url, title plus CAN carriers (wakes_so_far, woken_fps, escalated_fps, remaining_seconds). The thread binding lives inside durable workflow state — this is what lets the file registry retire. The runner already injects SMITH_CONV_* (claude_runner.py:393-407).

3.2 Signals / query

3.3 Constants (workflow-local; founder question 1)

_TICK            = timedelta(seconds=45)   # primary cadence while the current fp is un-acted
_IDLE_TICK       = timedelta(minutes=5)    # after this fp was woken/escalated — waiting on an
                                           # external actor (Smith's turn, the human ✅); any
                                           # fp change restores _TICK
_STALL_AFTER     = timedelta(minutes=15)   # how long a WAIT-state may sit unchanged before it
                                           # is treated as stalled (dead review, hung CI)
_MAX_WAKES       = 12                      # absolute wake ceiling per drive
_DRIVE_LIFETIME  = timedelta(hours=36)     # > approval's 24h window; then one honest expiry line
_DEAD_REVIEW_HINT = "If no bot verdict exists for the current head, re-trigger it:
  `gh workflow run claude-code-review.yml -f pr_number=<N>` (the #alerts playbook)."

The idle back-off is approval's _READY_WATCH_CEILING instinct (approval.py:90-95) expressed as a two-speed tick instead of a stop: the drive must never stop looking (terminal detection is its job), but it has no business polling at 45s while a human sleeps on an ✅.

3.4 State classification (pure, unit-tested)

_classify(gate) → class replaces both v1's _actionable() heuristic and its raw-reason fingerprint (raw reasons carry volatile text like exit=255 that would churn the fingerprint). Fingerprint: cls|head_sha|unresolved_threads.

3.5 The loop

deadline = now + (remaining_seconds or _DRIVE_LIFETIME)
wakes, woken, escalated = carried-from-request; last_fp = None; fp_since = now
while workflow.now() < deadline and not stopped:
    tick = _IDLE_TICK if last_fp in woken else _TICK
    wait_condition(stopped or poked, timeout=tick)        # durable timer, early-wake on signal
    gate = merge_gate_activity(repo, pr)                  # ≤3 gh reads — the ONE probe
    cls  = _classify(gate)
    if cls in (MERGED, CLOSED): return finish(cls)        # §3.6
    fp = f"{cls}|{head_sha}|{unresolved}"
    if fp != last_fp:
        last_fp, fp_since = fp, now
        if not _wakes_immediately(cls): continue          # WAIT-state: give it the stall window
    else:
        if not _wakes_immediately(cls) and now - fp_since < _STALL_AFTER: continue
        if fp in woken:
            escalate once per fp ("still stuck — needs a human"), then silence
            continue
    if wakes >= _MAX_WAKES: post budget line; return "wake_budget_exhausted"
    pr_drive_wake_activity(repo, pr, "reconcile", summary(cls, gate), binding)
    wakes += 1; woken.add(fp)
    if is_continue_as_new_suggested(): continue_as_new(carried state)
post expiry line; return "expired"

• One wake per fingerprint is the entire dedup story. A turn that fixes things moves the fp (new head) and re-opens the cycle; a turn that crashes leaves the fp → one escalation line → silence until something changes.
• CAN belt also checks on a slow heartbeat (~every 500 ticks) so a long-idle drive can't outgrow history. A full 36h at 45s ≈ 15k events — under the 50k ceiling, but the belt is load-bearing (the reply.py:166 rule). New class → no patch gates in v1; the docstring carries the standard future-patch-gate note.
• Posting discipline: ≤ len(escalated) + 2 one-liners over its life, threaded via slack_send_activity (_SEND_RETRY verbatim from task_watch.py:77; empty thread_ts → thread_anchor_get_activity). SendRefusedError is logged and swallowed — waking turns is the job, posting is best-effort.

3.6 Terminal transitions

3.7 Activities (new activities/pr_drive.py)

• pr_drive_wake_activity (smith_pr_drive_wake) — the extracted pr_event.wake(...): compose → resolve anchor → build_trigger → record_phase → dispatch(). Binding from arguments, never a file. Timeout 60s, ≤2 attempts — dispatch start-or-signals, so a duplicate wake beats a lost one.
• pr_drive_finalize_activity (smith_pr_drive_finalize) — best-effort terminal cleanup: phase-row stamp + thread-anchor clear. Replaces v1's pr_watch_remove_activity — there is no watch file to remove.

4 · Auto-start — opening the PR arms the driver

1. Detection — pr_open_detect.py (new, pure): parse the turn's stream-json log for a Bash tool_use containing gh pr create paired by tool_use_id with a URL-bearing tool_result → deduped (repo, pr). Fires on PRs opened this turn, never merely mentioned. Precedent: audit_session_activity already post-scans this log.
2. claude_runner_activity populates ClaudeReply.opened_prs (additive-defaulted). No watch-file writes — the activity's output is evidence, the workflow acts on it.
3. Reply-workflow end-of-turn hook — start_pr_drive_for_opened(...) beside the existing approval + task-watch hooks (reply.py:~1301, ~1358). ABANDON child per opened PR; WorkflowAlreadyStartedError → no-op. Replay-safe without a patch gate by the abstain precedent (reply.py:1263-1276): the trigger is an additive-defaulted activity-result field, so every pre-deploy history replays opened_prs=[] → zero commands.
4. CLI fallback — smith-pr-drive (replaces smith-pr-watch): add binds from the runner-injected SMITH_CONV_* env; stop signals; list; adopt (migration). Stays in prompts.py for creates the detector can't see — but the prompt now says the drive auto-starts.

The incident replay under v2: Smith opens #5749 and ends the turn having run nothing. The runner logged the create; the hook starts the drive; the first tick sees CI_RUNNING and waits; when the 🟡 lands, the next tick classifies NEEDS_FIXES — new fingerprint, immediate wake — and Smith is working the verdict within ~1 minute of it posting. No human, no CLI, no listener.

5 · What happens to the webhook plumbing

6 · File-level change list

No changes to: approval.py, dispatcher.py, pr_live_status.py, thread_phase.py, thread_anchor.py, watch_intent.py.

7 · Failure-mode table (single-driver semantics)

8 · Pattern-adoption survey — who else needs a durable driver

The pattern, named: a long-lived Temporal workflow owns the loop — durable timer, polls the source of truth through an activity, spawns an ephemeral reasoning turn only when something actionable changed, carries dedup/budget/binding in workflow history instead of files, preserves human gates as signals. The failure class it cures: ephemeral brain + bespoke fragile wake plumbing (nohup, detached Popen, launchd one-shots, webhook chains, in-process asyncio.sleep loops) + manual arming + fire-and-forget death with no receipt.

The fleet already contains the pattern done right — daemon_liveness.py and deploy_freshness.py, whose docstring states the principle: "a monitor inside the thing being monitored cannot report its own absence." The nightly/morning queues are durable, continue-on-failure, per-step-alerting — done right (one caveat: a SIGKILL'd subprocess skips its own automation_run exit alert; the queue's synthesized error JobResult still reddens the roll-up).

8.1 Ranked candidates

8.2 The Construct manifest — the honest not-Temporal list

Of ~103 live automations, only rows 4, 5, 7, 9, 10 above are drive-loops in disguise. The rest divide cleanly:

• Correct as crons — stateless idempotent fences: the drift-fence family (conversation-capture-drift*, conformance, outbound-language, cotenant-*, touch-ledger, detector.*), every AppFolio EventBridge mirror, the metric-snapshot Lambdas, spend-snapshot, listings-sync, the outreach-reconcile backstops (which heal into durable Temporal cadences). Fresh independent measurements with externalized dedup — Temporal would add nothing but cost.
• Correct as crons — watchers that must live OUTSIDE the watched system: renewal-workflow-health / leasing-workflow-health poll Temporal from Vercel — a Temporal workflow cannot report Temporal's own absence. Keep. Same principle keeps daemon-liveness on Temporal (watching launchd) and the review watchdog on GitHub Actions (§8.4).
• The one cross-cutting fix that is NOT Temporal: the fences scan a 25h window on a 24h cadence — two missed runs punch a permanent, undetectable evidence hole, and the manifest admits "it does NOT detect the job not running at all." Cheap fix: a per-job maxStaleness on the manifest entry, checked by the fleet digest against latest.startedAt — closes the gap for ~40 jobs at once, preserving the correct stateless shape.
• The real Construct argument for Temporal is state durability, not cadence: Smith-side lanes keep memory in ~/.claude/smith-state/*.json on one un-replicated disk (episode ledgers, noise rulings, at-most-once markers, poll cursors, a zero-byte lock file standing in for a mutex), while the TS side keeps equivalents in DDB. Rows 5–6 move the highest-stakes of that state into workflow history.

8.3 The Operators — what moves, what stays local, the first slice

The operator plane is entirely files + tmux + one launchd node daemon: the AgentFlow Supervisor (60s sweep — respawn after 2 confirmed-dead readings, cap 5, quiet-stop parks, an answer bridge), detached nudge bash watchers, msg (tmux send-keys + parked inbox files), the blocked ledger (Cloudflare KV canonical + local JSON index), and the Claude CLI's dispatch daemon. Six measured failures (ground truth): the roster-as-prompt spawn loop (~0% of dispatches start; 6.1 GB disk, +2.7 GB/day; 5,054 files in dispatch/rejected/), nudge clamping to 60s while a block is open, msg 8-char-prefix wrong-session delivery, blocked adopt falsely orphaning background sessions' blocks, answered blocks staying "open" with no write-back (humans answer twice), parked instructions draining out of causal order with no expiry.

What must stay local — Temporal cannot type into a terminal. The interactive session, tmux delivery, pane capture, start-operator's spawn dance, nudge's countdown-on-stillness. Durable workflows in this plane drive through activities on the mini's worker — the delivery arm stays local; the loop ownership and state move.

1. First slice — DecisionBlockWorkflow. One workflow per raised block, id = block id, on propflow-smith. Raise = start (activity publishes the decision page, today's path). The workflow polls the KV answer on a durable timer (subsuming the answer bridge — whose log is currently spinning on Cloudflare read failures) and, on answer, drives the answered→executed leg that today is hoped for: a msg-delivery activity wakes the raiser with the verbatim answer, re-nags on a durable timer until the raiser (or adopter) signals resolved, and escalates if the raiser is provably dead — via the shared three-valued liveness primitive, never collapsing unknown into dead. The human semantics survive exactly: "resolved means the raiser consumed the answer and acted — a claim only the raiser can make" becomes a signal only the raiser's session sends, instead of an unenforced convention. Smallest surface, kills the friction the founder personally feels (answering twice), two measured incidents behind it, and structurally identical to the PR drive. Effort M.
2. Second — OperatorTaskWorkflow (liveness/respawn/watchdog): per-task workflow subsuming the Supervisor's sweeps, with durable dead-streak counters (today an in-memory map that resets to zero on every Supervisor bounce), durable respawn budget, quiet-stop latches, "operator went dark" escalation. Activities: roster/tmux probes, spawn, loop release. Effort L — after the block slice proves the mini-worker activity seam.
3. Not Temporal — the dispatch-daemon rot. Roster-as-prompt and the unbounded rejected/ growth are Claude-CLI-layer bugs; wrap nothing — fix at source, plus a prune line in the existing morning hygiene sweep.
4. Not Temporal — nudge and msg themselves. They are the delivery arm; a durable workflow re-implementing "type into a pane" buys nothing.

8.4 The dead-review watchdog boundary (propflowai #5581)

review-verdict-watchdog.yml is a repo-wide, from-outside sweep that pages #alerts (addressed to Smith) when any active PR waits too long for a verdict that is never coming. The drive subsumes the detection for Smith-driven PRs: AWAITING_VERDICT unchanged past 15 min produces a wake carrying the same playbook — faster than the sweep, threaded in the drive's own conversation, acted on by the same brain without the #alerts hop. The watchdog stays, unchanged: it covers human and non-driven PRs, and its own header argues the principle that keeps it outside the review system it watches. Steady state: for driven PRs the drive fixes dead reviews before the watchdog's window elapses, so its pages concentrate on non-driven PRs. A redundant page on a PR with a live drive is harmless; building dedup between them would re-import exactly the two-driver coordination this plan deletes.

9 · Test plan

Gate for every PR: uv run ruff check src tests scripts && uv run mypy && uv run pytest -q.

10 · PR sequence · rollout · drill

1. PR-1 — the driver, armable but not yet auto-armed. Workflow + activities + wake() extraction + types + prefix + registration + CLI (add/stop/list) + tests. Legacy webhook path untouched; a CLI-armed drive on a throwaway PR (no watch file → no webhook wakes) exercises the driver in genuine isolation — no two-driver window on any real PR.
2. PR-2 — the cutover. Detection + runner + reply hook + prompts rewrite + delete pr_watch.py + delete pr_event.main() + adopt. Deploy, then run smith-pr-drive adopt — in-flight watch files become drives; the listener's Smith branch goes structurally dead.
3. PR-3 (propflowai, within a week) — delete the inert listener branch; /review-turns untouched.

Deploy per PR: merge → smith-sync-from-main.sh (worker restart; new class → no patch-gate hazard). No Schedule to register — drives are child- or CLI-started.

Synthetic drill (proves the inversion against the case it exists for):

1. launchctl stop …review-webhook — kill the listener for the entire drill. v1 killed it mid-way to test a backstop; v2 kills it up front to prove the loop never needed it.
2. Smith opens a throwaway PR. Confirm smith-pr-drive-… Running with zero manual arming (PR-2) / one CLI call (PR-1 bake).
3. Verdict lands → wake within ~2 min → fix loop → 🟢 → Mergeable: → approval child → ✅ → merged → drive Completed with the wrap-up turn.
4. temporal workflow query --type status mid-drive shows class/ticks/wakes/fp.
5. Restart the listener. Confirm nothing about the drive changes.
6. Negative leg: smith-pr-drive stop on a second drive → "stopped", no further wakes.

Prod acceptance: the next real Smith PR runs cover-to-cover — open → drive Running unprompted → verdict → wake ≤2 min → fix → Mergeable → human ✅ → merged → Completed — with smith-pr-watch absent from the transcript and the listener's Smith branch logging zero invocations.

11 · Open questions for the founder

1. Tick numbers. 45s active / 5-min idle / 15-min stall / 12 wakes / 36h + CAN. Five concurrent drives at 45s ≈ 24% of the gh REST budget (30s ≈ 36%, 60s ≈ 18%). Bless or adjust.
2. Non-Smith PRs. Auto-start covers Smith-opened; the CLI covers "drive PR X for me." Recommendation unchanged: never auto-drive a human's PR.
3. Merged wrap-up turn. Keep the final turn (it posts the done-table today), or reduce to a one-liner? Proposed: keep.
4. The poke hint. Re-point the listener at it later (~2s reaction), or delete the branch and never look back? Proposed: delete (PR-3); revisit only if 45s demonstrably matters.
5. Dead-review boundary. Drive subsumes detection for driven PRs; the repo-wide watchdog stays for everything else (§8.4). Agree?
6. Pattern adoption. Which of §8.1's candidates get green-lit, in what order? Proposed first wave: maintenance_eval (P1), DecisionBlockWorkflow (P1), voice-call-reconciler (P1).