Agent Smith · Implementation Plan

Smith PR-Drive, made durable — auto-armed watches + a Temporal backstop that can drive

Status: proposed · 2026-08-14 · Repo: PropFlow-Technologies/agent-smith · Future home: docs/planning/smith-pr-drive-durable.md

0 · The incident, in one paragraph

2026-08-14: Smith opened propflowai #5749, said "I'll drive it to mergeable and let you know", and ended the turn without running smith-pr-watch add 5749 — the one manual CLI step that binds the GitHub webhook to the thread. The bot's 🟡 CHANGES SUGGESTED verdict landed into a dead session; nothing woke Smith; five hours of silence until the human asked "You never gave an update, why." One manual smith-pr-watch add later, the rest of the drive worked flawlessly (webhook → wake → fix → re-review → 🟢 → merge). The machinery works; the arming is manual, the durable primitive can't act, and there is no backstop when the webhook path is dark.

1 · Design decision — extend SmithTaskWatchWorkflow vs. new SmithPrDriveWorkflow

Decision: (b) — a new per-PR SmithPrDriveWorkflow, modeled on approval.py. Do not extend SmithTaskWatchWorkflow.

This is not a §1 (DRY) violation, because the two candidate parents are different precedents for different jobs, and §2 says match the named precedent:

• workflows/approval.py is the named long-lived, per-PR, gh-polling precedent. It already holds a durable timer for up to 24h keyed smith-approval-<repo__slug>-<pr>, already polls merge_gate_activity on a cadence (_GATE_POLL / _READY_POLL), already handles WorkflowAlreadyStartedError idempotent re-arm, already runs as an ABANDON child started by a reply-workflow end-of-turn hook (start_approval_if_mergeable, approval.py:631). The drive is its structural sibling on the pre-mergeable half of a PR's life; the approval owns the post-mergeable half.
• workflows/task_watch.py cannot serve without forking its own identity, for four concrete reasons:
  1. Keying (task_watch.py:561): its id is {WATCH_WF_ID_PREFIX}{chat_jid}-{key} — one watch per thread. The requirement is per-PR ("a thread can spawn several PRs"); two PRs from one thread would collide on one workflow id.
  2. Caps (watch_intent.py:42-47): MAX_LIFETIME_SECONDS = 2h, re-clamped inside run() (task_watch.py:161-171) so the caps are a property of the watch. A PR drive routinely spans longer (the approval alone waits 24h). Raising the caps for one probe forks the cap semantics.
  3. Safety constitution (docstring, task_watch.py:36-43): "It sends no email, opens no PR, merges nothing, runs no shell. Disarmed of real-send risk by construction, not by a flag." A "nudge" that spawns a claude -p turn — which pushes commits and re-triggers reviews — is exactly the action surface that docstring exists to exclude. Adding it deletes the watch's safety property rather than extending it.
  4. Terminality: the watch's done-test is thread-level (thread_phase.is_terminal). A per-PR drive terminates on that PR's merge/close — a different object.

SmithTaskWatchWorkflow stays exactly what it is — the thread narrator. Its docstring's gap sentence ("a drive with no webhook traffic never wakes anything") gets updated to point at the new workflow.

What stays DRY — no second store, poller, or registry

2 · Auto-arm — where arming happens so no manual step remains

Decision: layer (i) — the runner activity — as the primary, evidence-based arm; the reply-workflow end-of-turn hook arms the durable drive off the same evidence; pr_event.py signal-with-starts the drive as the third belt. The brain's smith-pr-watch add prompt instruction stays as a fallback for create paths the detector can't see.

2.1 Detection — gh pr create observed in the turn's own log

New src/agent_smith/pr_open_detect.py (pure, no I/O — the watch_intent.py posture):

PR_URL_RE  # reuse phase_table.PR_URL_RE — one definition (§1)
def opened_prs(stream_json_lines: Iterable[str]) -> list[tuple[str, int]]

Parses the claude stream-json activity log for a Bash tool_use whose command contains gh pr create, pairs it (by tool_use_id) with its tool_result containing a GitHub PR URL (gh pr create prints the URL on success), and returns deduped (repo, pr_number) pairs. Keying on the create-command + its result is what makes this fire on PRs opened this turn and not on PRs merely mentioned — the false-positive the prompt-text candidates could not exclude. Precedent: audit_session_activity already post-scans this same log for git-commit evidence.

2.2 Primary arm — inside claude_runner_activity (Gap A, zero workflow-history impact)

activities/claude_runner.py already reads the log post-run (_extract_error_detail) and already holds the conversation binding — it injects SMITH_CONV_CHAT_JID / SMITH_CONV_THREAD_TS / SMITH_CONV_ANCHOR_KEY into the child env (lines 393–407). After the subprocess completes, on the non-error path:

opened = pr_open_detect.opened_prs(log_lines)          # pure
for repo, pr in opened:                                 # fail-soft, try/except OSError
    pr_watch.add_watch(repo, pr, input.chat_jid, input.thread_ts,
                       anchor_key=input.anchor_key)
reply.opened_prs = [f"{repo}#{pr}" for repo, pr in opened]

• Activity-internal change — no new workflow commands, no patch gate, deployable in isolation. The webhook fast path is armed the instant the turn ends, even if the brain forgot the CLI.
• Both-fire idempotency: pr_watch.add_watch is a documented idempotent overwrite (pr_watch.py:57-88), and the brain's own CLI reads the same env vars the activity injected — identical payload, same file.
• Skip when chat_jid is empty (adhoc runs; same guard the CLI enforces). ClaudeReply gains opened_prs: list[str] = field(default_factory=list) (additive-defaulted, types.py rule 3).

2.3 Durable-drive arm — end-of-turn hook in reply.py (twin of the existing two hooks)

New start_pr_drive_for_opened(chat_jid, opened_prs, *, thread_ts, anchor_key) in workflows/pr_drive.py, called in SmithReplyWorkflow._run_turn immediately after the task-watch hook (reply.py:1358-1373). Starts one drive per opened PR as an ABANDON child, id smith-pr-drive-<repo__slug>-<pr> (mirrors the approval keying, approval.py:669); WorkflowAlreadyStartedError → leave the running drive alone.

2.4 Third belt — pr_event.py signal-with-start

After the existing dispatch (pr_event.py:222-232), best-effort:

await client.start_workflow(
    SmithPrDriveWorkflow.run, drive_request_from_watch(args.repo, args.pr, watch),
    id=pr_drive_workflow_id(args.repo, args.pr), task_queue=TASK_QUEUE,
    start_signal="note_event", start_signal_args=[args.kind],
)

Effect: any PR with a watch file — however armed (auto-arm, brain CLI, a human by hand) — gets its durable drive on the first webhook event, and every event thereafter resets the drive's stall clock via note_event.

3 · SmithPrDriveWorkflow — the durable reconciler

New src/agent_smith/workflows/pr_drive.py. Determinism rules as everywhere: no config import, workflow-local timedelta constants, all I/O in activities, workflow.unsafe.imports_passed_through() for activity/type imports.

3.1 Types (types.py, additive)

@dataclass
class PrDriveRequest:
    repo: str
    pr_number: int
    chat_jid: str          # Slack channel of the driving conversation
    thread_ts: str = ""    # PR thread root when known ("" → anchor resolution at wake time)
    anchor_key: str = ""   # synthetic-drive anchor identity (decider case)
    url: str = ""
    title: str = ""

@dataclass
class PrDriveWakeInput:
    repo: str
    pr_number: int
    kind: str              # "reconcile" — joins pr_event.KINDS' vocabulary
    summary: str           # the gate's reason, verbatim (incl. dead-review playbook hint)
    chat_jid: str = ""     # fallback binding when the watch file is missing/corrupt
    thread_ts: str = ""

@dataclass
class PrWatchRemoveInput:
    repo: str
    pr_number: int

3.2 Signals / query

3.3 Constants (workflow-local; proposed defaults — founder question 9.1)

_RECONCILE_INTERVAL = timedelta(minutes=10)   # tick cadence; ~2 gh reads/tick, trivial vs. 5000/hr
_STALL_AFTER       = timedelta(minutes=15)    # unchanged actionable fingerprint must persist this long
_ONE_WAKE_PER_FP   = True                     # bounded by construction (§3.4)
_MAX_WAKES         = 12                       # absolute 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 dead-review playbook), then end the turn."

3.4 The loop

deadline = now + _DRIVE_LIFETIME
last_fp = None; fp_since = now; woken_fps = []; escalated_fps = []; wakes = 0
while workflow.now() < deadline and not (self._merged or self._stopped):
    await wait_condition(lambda: self._merged or self._stopped or self._event_seen,
                         timeout=_RECONCILE_INTERVAL)     # durable timer, early-wake on signal
    if self._event_seen: self._event_seen = False; fp_since = now   # webhook alive → stall resets
    if self._merged or self._stopped: break
    gate = merge_gate_activity(repo, pr)                  # the ONE probe (reused)
    if gate.pr_state in ("MERGED", "CLOSED"): break       # terminal from GitHub truth
    fp = f"{gate.head_sha}|{gate.ok}|{gate.recoverable}|{gate.reason}"
    if fp != last_fp: last_fp, fp_since = fp, now; continue   # movement = someone is acting
    if not _actionable(gate): continue                    # CI running / bot mid-review → wait
    if now - fp_since < _STALL_AFTER: continue
    if fp in woken_fps:
        if fp not in escalated_fps and wakes > 0:
            post "⏱ backstop: woke a turn and #N is still stuck on <reason> — needs a human"
            escalated_fps.append(fp)
        continue                                          # one wake + one escalation per fp, then silent
    if wakes >= _MAX_WAKES: post budget line; return "wake_budget_exhausted"
    await pr_drive_wake_activity(repo, pr, "reconcile", summary_for(gate))
    wakes += 1; woken_fps.append(fp)
# terminal
pr_watch_remove_activity(repo, pr)   # best-effort cleanup of the webhook router file
return "merged" | "closed" | "stopped" | "expired"

_actionable(gate) (pure module-level function, unit-tested):

• gate.ok → actionable (green + clean, and nothing announced/merged it for the whole stall window, means the announce/approval step is the thing that's stuck).
• not ok and not recoverable → actionable (bot 🟡/🔴, merge conflict, stale 🟢, unresolved threads — reason says which).
• not ok and recoverable → given the stall window to resolve on its own, then treated as stalled. This one rule covers both dead review (recoverable "awaiting bot verdict" that never resolves — summary_for appends the playbook hint so the woken brain fires gh workflow run claude-code-review.yml -f pr_number=<N> itself) and hung CI, with no special cases. The workflow never runs shell; the claude turn is the only actor.

Posting discipline: the drive posts at most 2 + len(escalated_fps) one-liners over its whole life, threaded under thread_ts via the existing slack_send_activity (retry policy verbatim from task_watch.py:77). When thread_ts is empty it first tries thread_anchor_get_activity with anchor_key. Everything louder comes from the turns it wakes, which ride the existing pr_live_status collapse — no new status surface.

3.5 Activities (new src/agent_smith/activities/pr_drive.py)

Refactor inside pr_event.py (§1 — one wake path): extract the body of main() between watch-load and dispatch into async def wake(...); main() becomes parsing + wake() + the merged-cleanup block. Byte-equivalent CLI behavior, pinned by the existing tests/test_pr_event.py.

4 · File-level change list

No changes to: listener.js (webhook path untouched), pr_watch.py, approval.py, pr_live_status.py, thread_phase.py, watch_intent.py, dispatcher.py.

5 · Failure-mode table

6 · pr_watch.py — kept as the webhook router (not retired)

1. The listener needs a zero-dependency filter. listener.js:384 checks for the watch file before shelling Python at all — non-Smith PRs cost a stat(), nothing more. Replacing that with a Temporal visibility query from Node adds a client, credentials, and a network dependency to a fail-soft-local hot path.
2. It is the wake activity's thread-binding source (with the drive's own request as fallback), and the anchor-key carrier for thread-less decider drives.
3. Retirement buys nothing: ~40 lines of tested registry; the drive holds lifecycle, the file holds routing.

Two free improvements: the drive removes the file on close-without-merge (today only lazy-expired after 3 days), and a corrupt/missing file no longer kills a wake (activity fallback binding).

7 · Test plan

Patterns: time-skipping WorkflowEnvironment + name-matched mock activities (tests/test_task_watch_workflow.py), pure-function tables (tests/test_watch_intent.py), CLI/env round-trips (tests/test_pr_watch.py), drift guards (tests/test_canonical_paths.py, tests/test_worker_registration.py). Gate for every PR: uv run ruff check src tests scripts && uv run mypy && uv run pytest -q.

8 · Rollout

PR sequence — each independently shippable; merge auto-deploys via smith-sync-from-main.sh

Deploy per PR: merge to main → ~/.claude/scripts/smith-sync-from-main.sh (worker restart). No listener restart at any step (listener.js untouched). No Temporal schedule — drives are child-started, not scheduled.

Prod verification

• Acceptance test = the next real PR drive. Watch for: watch file appears with no smith-pr-watch add in the transcript; temporal workflow list shows smith-pr-drive-… Running; verdict → wake → fix → 🟢 → Mergeable: → ✅ → merged → drive Completed + watch file gone.
• Synthetic drill — the backstop must be exercised against the case it exists for, not assumed:
  1. Have Smith open a throwaway PR (whitespace doc change in agent-smith).
  2. Confirm auto-arm: watch file exists; drive workflow Running.
  3. launchctl stop gui/$(id -u)/com.propflow.review-webhook — kill the listener.
  4. Wait for the bot's verdict; nothing wakes Smith fast (webhook dark).
  5. Confirm the backstop: within ~25 min a github-sourced reconcile turn appears in the thread with the gate's reason.
  6. Restart the listener (launchctl kickstart -k …), drive the PR closed, confirm the drive completes and removes the watch.
• Observability during bake: temporal workflow query --type status on a live drive; worker-log lines at each wake/escalation.

9 · Open questions for the founder

1. Backstop numbers. Proposed: 10-min tick, 15-min stall window, one wake + one escalation per stuck fingerprint, 12 wakes max, 36h drive lifetime. Faster (5-min tick) is cheap on gh quota but wakes more turns; slower doubles the worst-case silent window (~25 min as proposed).
2. Scope: non-Smith PRs. Auto-arm covers PRs opened in a Smith turn; the brain's CLI covers "drive PR X for me". Should the listener also arm a drive for any Smith-authored PR with no watch? Proposed: no — an unasked-for driver on someone's PR is exactly the unbidden noise the watch-intent parser was built to avoid.
3. Noise tolerance. The escalation line ("backstop woke a turn and #N is still stuck — needs a human") and the expiry line are the only new posts. Acceptable per stuck state, or route escalations to #alerts instead of the PR thread?
4. Dead-review auto-retrigger. Proposed: the woken brain runs gh workflow run claude-code-review.yml -f pr_number=<N> itself (bounded by one-wake-per-fingerprint). Alternative: post the playbook to #alerts for a human. Proposed default: the brain does it — it's the existing playbook and already something Smith does when asked.
5. Drive lifetime vs. approval window. 36h chosen to outlive the approval's 24h human window. If a PR routinely waits days for a human ✅, should the drive re-arm itself (continue-as-new with a fresh budget) instead of expiring? Proposed: expire honestly — a multi-day PR is a human's queue, not a robot's.