[Feature]: maintainer agent — work a repo's issue queue automatically (triage → plan or draft PR → human approval)

[radroid]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server

Problem or use case

Maintaining several repos means the same manual loop, per repo, forever: someone opens an issue, I read it, I decide whether it is a five-minute fix or a design question, I open T3 Code, I create a thread, I paste the issue text in, I create a worktree, and only then does any agent work start. The mechanical part of that loop is the part I do dozens of times and the part T3 Code is already built to do — but nothing in T3 Code will start it for me.

What exists today, and where it stops:

• T3 Code can already dispatch a turn with no human in the loop. apps/server/src/t3x/autoResume/Reactor.ts:109 dispatches thread.turn.start through OrchestrationEngineService.dispatch and the comment above it says it is "byte-for-byte the path a keystroke produces". That is the whole autonomous-dispatch primitive, and it is already in the fork seam. But it only ever resumes an existing thread — it never creates one, and it is triggered by a Claude rate-limit event, not by anything outside the app.
• T3 Code can already talk to GitHub. apps/server/src/sourceControl/GitHubCli.ts:203 exposes a general execute({ cwd, args }) escape hatch onto the authenticated gh CLI, plus typed listOpenPullRequests / createPullRequest / getDefaultBranch. Nothing reads issues.
• T3 Code can already stand up an isolated workspace per unit of work. thread.turn.start carries a bootstrap that creates a thread, prepares a git worktree and runs the setup script (packages/contracts/src/orchestration.ts:671). But that bootstrap is not implemented in the orchestration engine — it lives inline in the WebSocket transport at apps/server/src/ws.ts:749 (dispatchBootstrapTurnStart). A server-side supervisor that calls engine.dispatch directly, the way AutoResumeReactor does, gets no thread creation, no worktree and no setup script. That gap is the single biggest reason this feature does not already exist as a 50-line reactor.
• Multi-project state is already queryable. ProjectionSnapshotQuery.getShellSnapshot() (apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts:83) returns every project with its workspaceRoot and an optional repositoryIdentity carrying owner / name (packages/contracts/src/environment.ts:87-95). Nothing walks it looking for work to do.

So every piece is present and none of them are connected. The result is that T3 Code is an excellent place to do maintenance work and a useless place to receive it.

Secondary problem: the routing decision is what actually costs me time, and it is not a decision an agent should make silently. Roughly a third of inbound issues are "this is a config mistake / won't do / needs a design conversation", a third are "here is a clear bug with a clear fix", and a third are somewhere in between. Today an unattended agent pointed at an issue queue would treat all three identically and start writing code for the ones that should have produced a paragraph instead.

Proposed solution

A fork-local server feature at apps/server/src/t3x/maintainer/, registered through the existing aggregator in apps/server/src/t3x/index.ts (T3xLayerLive, and later T3xRoutesLive). Same shape as autoResume/: a self-starting scoped fiber, a durable JSON state file in config.stateDir, pure decision functions with unit tests, and zero new upstream-file edits.

1. Detection — poll, not webhook, and REST rather than gh's GraphQL paths

Webhooks are the wrong answer here. T3 Code's server runs on a laptop; there is no stable public ingress (Tailscale serve is per-user and not a deployment target), and a webhook receiver means a GitHub App, a secret, and a public URL. Polling with the credentials the user already has is the only design that works with zero setup — which is the bar autoResume set (apps/server/src/t3x/autoResume/config.ts:63 — "Config is read from env with safe defaults, so the feature works with zero setup").

But polling must be done carefully, because the fork's parent repo already has a rate-limit incident from exactly this: upstream pingdotgg#3581 documents VcsStatusBroadcaster.retainRemotePoller → … → GitHubCli.listChangeRequests → gh pr list … fanning out per retained worktree branch and driving GitHub GraphQL usage from ~184 to ~3,879 of 5,000 points while the app sat idle, which then broke an unrelated gh pr create. gh pr list --json and gh issue list --json both go through GraphQL.

Concrete detection design:

• One fiber for all projects, not one per project and emphatically not one per thread. Iterate getShellSnapshot().projects sequentially with a per-project stagger.
• REST, via the existing escape hatch: GitHubCli.execute({ cwd: project.workspaceRoot, args: ["api", "-H", "Accept: application/vnd.github+json", repos/${owner}/${name}/issues?state=open&sort=updated&direction=desc&per_page=50&since=${lastSeenIso}] }). REST has its own 5,000 req/hr budget, separate from the GraphQL points budget [Bug]: Background PR status polling via gh pr list drains GitHub GraphQL rate limit pingdotgg/t3code#3581 exhausted, and one request per project per interval is a rounding error against it.
• Default interval 5 minutes, T3X_MAINTAINER_POLL_MS override, jittered.
• Two gotchas that must be handled or the feature misbehaves on day one: (a) GitHub's REST /issues collection includes pull requests — every item carrying a pull_request key must be dropped; (b) since is updated_at, so an old issue that gets a new comment reappears — dedupe on issue number against durable state, never on the cursor alone.
• Cursor + dedupe live in a fork-owned JSON file (t3x-maintainer.json in config.stateDir), following apps/server/src/t3x/autoResume/state.ts exactly: SynchronizedRef + atomic write via writeFileStringAtomically, decode failure falls back to empty, and the module comment there states the reason to avoid a DB migration ("the migration registry is upstream-owned, and adding to it would buy permanent conflict surface for what a ~single JSON file does fine").

Keep this behind one module boundary — detect.ts exporting something like pollProject(config): Effect<ReadonlyArray<DetectedIssue>>. See §7 for why that boundary is load-bearing.

2. Per-project enablement — a file in the repo, not a settings row

.t3x/maintainer.json at the project's workspaceRoot, mirroring the existing .t3x/resume-prompt.md convention (apps/server/src/t3x/autoResume/config.ts:88, RESUME_PROMPT_RELATIVE_PATH). Absent file = feature off for that project.

{
 "enabled": true,
 "repo": "owner/name", // default: project.repositoryIdentity.owner + .name
 "baseBranch": "main",
 "labels": { "allow": ["bug"], "deny": ["wontfix", "discussion"] },
 "maxOpenAtOnce": 3,
 "openDraftPr": false,
 "ignoreAuthors": []
}

This is deliberately not a T3 setting. packages/contracts/src/settings.ts is already a ledger row (+7/-2, churn 18, risk 162) and is a persisted schema — adding a field there costs a migration-shaped risk for a per-repo toggle. A repo-committed file also means "turn the maintainer agent off" is a commit with an author and a diff, which is the right audit story for a thing that opens branches.

Plus a global kill switch T3X_MAINTAINER_ENABLED (default false for v1 — unlike auto-resume, this one creates threads), resolved by a pure resolveConfig(env) exactly as autoResume/config.ts:63-73 does.

3. Thread creation — duplicate ws.ts's bootstrap, do not edit ws.ts

For each accepted issue, the reactor does what apps/server/src/ws.ts:891-933 does, but from inside t3x:

1. engine.dispatch({ type: "thread.create", … }) — schema at packages/contracts/src/orchestration.ts:554-568. projectId from the shell snapshot, title as #123 — <issue title> (a prefix the user and any later UI can filter on), modelSelection from project.defaultModelSelection, branch/worktreePath null for now.
2. gitWorkflow.fetchRemote → gitWorkflow.resolveRemoteTrackingCommit → gitWorkflow.createWorktree({ cwd: workspaceRoot, refName: <resolved base sha>, newRefName: "t3x/issue-123", baseRefName: config.baseBranch, path: null }) — the same three calls as ws.ts:908-930. GitWorkflowService is reachable from the t3x layer: T3xLayerLive is merged into ReactorLayerLive (apps/server/src/server.ts:224), and RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(… Layer.provideMerge(VcsLayerLive) …) at server.ts:346-352, with GitWorkflowLayerLive inside VcsLayerLive at server.ts:287.
3. engine.dispatch({ type: "thread.meta.update", branch, worktreePath }).
4. engine.dispatch({ type: "thread.turn.start", … }) — copy autoResume/Reactor.ts:96-119 verbatim, only the prompt text differs.

This duplication must be registered as a logic mirror in docs/t3x/SEAMS.md under "Logic mirrors (semantic dependencies, not code seams)" — the same treatment autoResume/http.ts's authenticateWithOperateScope already gets for mirroring http.ts's private authenticateRawRouteWithScope. Editing ws.ts to export the bootstrap instead would add a new ledger row on a hot upstream file, which the tripwire in SEAMS.md:21 forbids.

GitHubCli needs one extra step: GitHubCli.layer is Layer.provided into SourceControlProviderRegistry.layer (server.ts:248-251), not merged, so it is not in the reactor's environment. t3x must provide it itself inside t3x/index.ts. Its only dependency, VcsProcess, is merged at the outermost runtime layer (server.ts:632), so this resolves without touching server.ts.

4. Triage — one turn, one prompt, in the thread

Do not build a separate classifier service. Structured classification would mean extending TextGenerationService, which is a closed four-operation interface (apps/server/src/textGeneration/TextGeneration.ts:74) routed per provider instance — a fifth operation means five implementations, and three of the five providers have no native schema mode and fall back to prompt-instructed JSON anyway.

Instead, the first turn's prompt is the triage, and the routing is expressed as the thread's mode:

• Complex / ambiguous / impossible / won't-do → the thread is created with interactionMode: "plan" (packages/contracts/src/orchestration.ts:126). The turn produces an OrchestrationProposedPlan (orchestration.ts:244-254), which already renders in the plan surface and already has a one-click "implement in a new thread" path via implementationThreadId. Nothing touches the working tree.
• Easy → interactionMode: "default", runtimeMode: "auto-accept-edits", worktree prepared, and the prompt instructs: implement, run the project's checks, commit on the branch, stop. Do not push. Do not open a PR.

The cheap way to make the mode decision without a second model call: run the classification as a plan-mode turn for every issue, and have the prompt end with a machine-readable verdict line the reactor greps for (T3X-TRIAGE: easy|complex|declined). On easy, the reactor dispatches a second turn into the same thread after flipping interactionMode to default. This costs one extra turn per easy issue and buys a human-readable rationale in the transcript for every routing decision, including the wrong ones. UNVERIFIED that a thread.meta.update-style interaction-mode flip mid-thread is supported by the decider — see §8.

5. Safety rails

• Never full-access. full-access maps to Claude's bypassPermissions and T3's canUseTool auto-allows every tool (apps/server/src/provider/Layers/ClaudeAdapter.ts:3512-3517, :3372-3378). An unattended thread nobody asked for must not run in the mode where nothing can be refused. auto-accept-edits lets file edits through while commands still surface as approvals.
• Always a worktree, always a branch. t3x/issue-<n>, created off the resolved remote base. The reactor never calls switchRef and never operates in the project checkout.
• Never push, never open a PR in v1. openDraftPr defaults to false. When enabled in v1.1 it uses the existing typed GitHubCli.createPullRequest (GitHubCli.ts:232) and the PR is a draft. Never merge — the reactor has no merge path at all, by construction.
• Caps, durable. maxOpenAtOnce (default 3, counted across all projects), maxNewThreadsPerHour, and per-issue dedupe by number so a server restart cannot re-file. Mirror autoResume's maxResumesPer24h (config.ts:32) and its fired-history retention window (state.ts:25).
• A visible trail. Every decision — detected, accepted, skipped-by-label, capped, triaged-as-X — appended via thread.activity.append, copying autoResume/Reactor.ts:64-95 including its best-effort catchCause so a timeline failure never fails the run. A thread that appears on its own must explain itself.
• Fan-out ceiling is real, not theoretical. Provider session startup is serialized through a single DrainableWorker (apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1323), so N new threads = N sequential CLI spawns before any of them runs. And ProviderSessionReaper reaps idle sessions after 30 minutes by default (apps/server/src/provider/Layers/ProviderSessionReaper.ts:17), so a parked maintainer thread loses its process silently. Both argue for a small maxOpenAtOnce.

6. Multi-project

One supervisor fiber iterating getShellSnapshot().projects. Use getShellSnapshot(), not getSnapshot() — docs/t3x/SEAMS.md's logic-mirror table records a live open risk that getSnapshot() hydrates every message and activity payload and "has OOM-killed servers" upstream. Each project is independently enabled by its own .t3x/maintainer.json, so adding a repo is a commit in that repo and nothing else.

7. Relationship to upstream pingdotgg#3164 — this is a consumer, not a competitor

Upstream pingdotgg#3164 (Automations & Triggers, labeled 🚧 In Progress) owns the trigger transport: cron schedules plus GitHub / GitLab / Sentry / Linear triggers, project-scoped, user-configured in the UI. It has already absorbed pingdotgg#437 and pingdotgg#1390 as duplicates. This issue is explicitly not a competing trigger system.

The split: pingdotgg#3164 answers "how does something outside T3 Code start a turn?". This issue answers "given an inbound issue, what should the agent do with it, and what must a human still approve?" — the triage taxonomy, the plan-vs-implement routing, the never-push/never-merge contract, the per-repo enablement file, the caps.

That is why detection is isolated behind detect.ts. If pingdotgg#3164 lands with a GitHub issue trigger, detect.ts is deleted and replaced by a subscription to that trigger; everything in §3, §4 and §5 survives unchanged. The same applies to pingdotgg#4266 / PR pingdotgg#5003 (durable local GitHub waitpoints) — those wait on a condition for one known PR, which is a different primitive from draining a queue, but they would be the right mechanism for "wake this thread when CI goes green on the branch it just pushed", a natural v2.

8. Explicitly unverified, with the experiment that settles each

• Does REST polling stay cheap in practice? Claimed on the basis that [Bug]: Background PR status polling via gh pr list drains GitHub GraphQL rate limit pingdotgg/t3code#3581's incident was GraphQL and REST has a separate budget. Experiment: gh api -i rate_limit, then 20 gh api repos/OWNER/NAME/issues?since=… calls, then gh api -i rate_limit again; read the x-ratelimit-used delta for both the core and graphql resources. Also test whether gh api --cache 300s (flag confirmed present in gh 2.96.0) returns 304-backed responses that do not decrement core.
• Is GitHubCli constructible from inside t3x? The layer analysis in §3 says yes (only needs VcsProcess, merged at server.ts:632). Experiment: add GitHubCli.layer to T3xLayerLive and run the server typecheck — an unsatisfied requirement will surface as a type error, which is exactly the "must never widen an upstream signature" property t3x/index.ts documents.
• Does an engine-dispatched thread.create (bypassing ws.ts) produce a thread that shows up normally? Experiment: a test modeled on apps/server/src/t3x/autoResume/Reactor.test.ts that dispatches thread.create + thread.meta.update + thread.turn.start and asserts the thread appears in getShellSnapshot() with the right branch and worktree.
• Can interactionMode be flipped mid-thread by a fork-side dispatch? The §4 two-turn design depends on it. Experiment: grep apps/server/src/orchestration/decider.ts for the thread.turn.start interaction-mode handling and write a decider test. If it cannot, fall back to: triage in a throwaway plan thread, then create a second implementation thread for easy — more threads, same safety.
• Cost. One agent thread per inbound issue, unattended. Nobody has measured what a week of a busy repo costs. maxNewThreadsPerHour is the crude guard; a real per-thread budget does not exist in T3 today.

Why this matters

Maintainers with several repos pay a fixed per-issue tax that is almost entirely mechanical: read, classify, decide, create a thread, create a worktree, paste context. This removes the mechanical part and leaves exactly the two decisions that need a human — "was this triaged correctly?" and "should this land?" — as explicit, reviewable artifacts (a proposed plan, or a branch with a diff).

Concretely:

• The queue gets worked while I am asleep, and nothing lands while I am asleep. By the time I look, complex issues already have a plan I can accept or throw away, and easy issues already have a branch with a diff and passing checks. Neither state is irreversible.
• The routing decision becomes visible. Every issue gets a written rationale in a thread timeline before any code is written. That is strictly better than today, where the triage happens in my head and leaves no trace.
• It scales across repos without scaling my attention. Enablement is a committed file per repo; there is no dashboard to maintain and no per-repo setup in the app.
• It makes the fork's existing autonomous-dispatch primitive useful for something other than rate limits. AutoResumeReactor proved the fork can drive thread.turn.start from the server with no client attached. This is the second consumer of that pattern, and it forces the missing half — server-side thread + worktree creation — into a reusable fork-local module that [Feature]: supervise long-running threads — turns complete while background subagents are still working, and nothing restarts the run #38 (loop supervision) and any future orchestrator would also want.
• It is a safety design as much as a feature. The interesting output is not "an agent opened a PR", it is a written contract for what an unattended agent in T3 Code is allowed to do: never full-access, never the project checkout, never push, never merge, always capped, always with a timeline entry. That contract does not exist anywhere in the repo today and will be needed by every autonomous feature that follows.

Smallest useful scope

v1: one repo, plan-only, no PR, no UI, opt-in and off by default.

Ship apps/server/src/t3x/maintainer/ with:

1. config.ts — resolveConfig(env) for the global switch and interval (pattern: autoResume/config.ts:63), plus loading .t3x/maintainer.json from project.workspaceRoot (pattern: resolveResumePrompt, autoResume/config.ts:96-113, which never fails and falls through to a default).
2. detect.ts — one gh api repos/OWNER/NAME/issues?state=open&sort=updated&since=… call per enabled project per tick, via GitHubCli.execute; drops items with a pull_request key; applies the label allow/deny lists.
3. state.ts — durable JSON (t3x-maintainer.json in config.stateDir), holding lastSeenUpdatedAt and handled issue numbers per repo, plus the hourly-creation history for the cap. Verbatim structure from autoResume/state.ts.
4. decide.ts — pure: given detected issues, current state, and caps, return the list to act on. Fully unit-testable with no Effect services, like autoResume/decide.ts (71 lines).
5. Reactor.ts — self-starting scoped fiber: poll → decide → for each accepted issue, thread.create (interactionMode "plan", runtimeMode "auto-accept-edits") → thread.turn.start with a prompt containing the issue title, body and URL → thread.activity.append recording why the thread exists.
6. Registration: merge into T3xLayerLive in apps/server/src/t3x/index.ts. No other file changes except docs/t3x/SEAMS.md (see below).

Explicitly deferred out of v1: worktree creation, the implement path, draft PRs, the two-turn triage flip, any UI, and multi-project. v1 runs plan-mode only, in the project checkout's thread but with no working-tree writes, against a single repo I enable by hand.

v1 is done when: a new issue on radroid/t3code produces, within one poll interval and with no client connected, a T3 thread titled #NN — <title> containing a proposed plan and an activity entry naming the issue — and running the server for 24 hours with no new issues consumes a measured, negligible slice of the GitHub REST budget.

v1.1 adds the worktree (§3 steps 2-3), the easy implement path, and a per-project loop. v1.2 adds openDraftPr. UI is v2 at the earliest, because a per-thread overlay costs a ledger row — mounting <AutoResumeOverlay> cost apps/web/src/routes/_chat.$environmentId.$threadId.tsx at +10/-6, churn 5, risk 80 — and v1 needs none: the threads show up in the normal list and the timeline carries the reasoning.

Alternatives considered

Wait for upstream pingdotgg#3164 and build nothing. pingdotgg#3164 is 🚧 In Progress and includes a Linear "new issue" trigger, so a GitHub issue trigger is plausible. Rejected as a complete answer because pingdotgg#3164 is a trigger transport — it will not decide plan-vs-implement, will not define the never-push contract, and will not create per-issue worktrees. It also has no landing date, and this fork's experience is that upstream orchestration work (PR pingdotgg#3638, merged into the t3code/codex-turn-mapping stack behind still-open pingdotgg#2829) can sit off main for a long time. The mitigation is architectural rather than temporal: keep detection behind detect.ts so pingdotgg#3164 landing deletes one file instead of invalidating the feature.

A GitHub Actions workflow instead of an in-app reactor. The repo already has Actions (.github/workflows/t3x-ci.yml). A workflow on issues: [opened] could call an agent CLI directly — real webhooks, no polling, no rate-limit question. Rejected because the output would be a CI log, not a T3 thread: no worktree the user can open, no timeline, no approvals, no checkpoints, no diff view, no mobile. The entire value here is that the artifact lands inside T3 Code where the human already reviews work.

Webhook receiver in the T3 server. Cleanest detection semantically. Rejected for v1: needs public ingress and a GitHub App or webhook secret, which is real setup on a laptop-hosted server and breaks the zero-setup bar the fork's other features meet. Worth revisiting if pingdotgg#3164 ships ingress the feature can borrow.

gh issue list --json … instead of gh api. Simpler and already the house style in GitHubCli.ts. Rejected because gh issue list --json goes through GraphQL, which is precisely the budget pingdotgg#3581 documents being exhausted by background polling. If the §8 experiment shows REST and GraphQL costs are comparable at one call per project per five minutes, this becomes the simpler choice and should be taken.

Model-side scheduling — let the agent arm its own wake-ups. The Claude platform binary ships CronCreate / ScheduleWakeup tools and a scheduler that runs in the SDK (non-interactive) entrypoint, and T3's ClaudeAdapter passes no allowedTools / disallowedTools / hooks, so they are reachable today. Rejected as the mechanism here for three reasons: it is Claude-only, durable crons are gated off so a loop dies with the query() session, and — decisively — it produces a turn but cannot produce a thread, which is the thing this feature actually needs.

A new MCP toolkit (apps/server/src/mcp/toolkits/maintainer/) so the model drives the loop itself. The t3-code MCP server is already mounted by all five adapters with a thread-scoped credential, and toolkits/preview/ is a complete working template. Genuinely attractive and provider-agnostic. Rejected for v1 because it inverts the control flow: the loop would then depend on some thread being alive and choosing to poll, which reintroduces exactly the liveness problem #38 exists to solve. A server-side reactor runs whether or not any agent is thinking. The MCP route is the better v2 surface for a human-in-the-loop "work issue #123 now" command.

Reuse AutoResumeReactor by hand — create the thread manually, let auto-resume keep it alive. Zero new code, but it does not detect anything and does not triage; it only solves "keep going after a limit".

Risks or tradeoffs

Seam cost: zero new ledger rows for the v1 above, one mandatory logic-mirror row.

docs/t3x/SEAMS.md currently measures 34 upstream-owned files, +1616 / -187 against merge-base 64bf01619, with an explicit tripwire at SEAMS.md:21: "Before adding row 35, re-isolate something instead."

• apps/server/src/server.ts already has a row (+3, churn 29, risk 87) covering the one import / one Layer.provideMerge / one route entry. Registering through t3x/index.ts adds nothing to it — that is the aggregator's entire purpose (t3x/index.ts module comment: "To add a feature: build it under apps/server/src/t3x/<feature>/, then merge its self-starting layer into T3xLayerLive below. Do NOT add a new edit to any upstream-owned file.").
• New logic-mirror row required: the worktree bootstrap in §3 duplicates ~25 lines of apps/server/src/ws.ts:908-930 (fetchRemote → resolveRemoteTrackingCommit → createWorktree → thread.meta.update). Mirrors produce no rebase conflict, which is exactly why they are dangerous — SEAMS.md:99 says so directly: "These never conflict during rebase, so nothing warns you when the original changes and the mirror drifts." If upstream adds a precondition to worktree creation (a lock, a path-collision check, a repo-state guard), the fork's path silently keeps working without it. Register it and re-check it every sync.
• Also a parallel-paths hazard, not just a mirror. This feature adds a second way to create a thread alongside upstream's dispatchBootstrapTurnStart. SEAMS.md:111 calls this out as "Worse than a mirror". It belongs in the parallel-paths table, with the upstream guard named explicitly.
• Any UI costs a real row. For comparison, apps/web/src/routes/_chat.$environmentId.$threadId.tsx is +10/-6, churn 5, risk 80 for mounting one overlay. Hence "no UI in v1".
• Do not touch packages/contracts/src/settings.ts (+7/-2, churn 18, risk 162, and a persisted schema). Hence the repo-committed .t3x/maintainer.json.

Behavioural and product risks

• Wrong triage is the main failure mode, and it is asymmetric. Misfiling an easy issue as complex costs a wasted plan. Misfiling a complex issue as easy produces a confident, wrong branch that looks reviewable. The two-turn design in §4 exists to make the rationale readable before code is written; it does not make the classifier correct.
• Noise. Every accepted issue becomes a thread in the main list. There is no parent/child link in OrchestrationThreadShell and no way to group or hide them, so a busy repo will bury hand-started threads. The #NN — title prefix is a weak mitigation. maxOpenAtOnce defaulting to 3 is the real one.
• Notification storm. Every thread completion fires the fork's Web Push and needs-attention path (apps/server/src/t3x/webPush/attention.ts:40, attentionKindForEdge). Ten maintainer threads finishing overnight means ten phone notifications for work nobody asked for. v1 should suppress push for maintainer-created threads, or the feature will get turned off within a day.
• Interaction with fork issue [Bug]: auto-resume is cancelled as "user-took-over" by any user message — including one that was itself rejected by a limit #39. Auto-resume is cancelled as "user-took-over" by any user message. A maintainer-created thread that hits a usage limit and then receives a follow-up will inherit that bug. Worth confirming before v1.1's implement path, since long implement turns are exactly what hits limits.
• Interaction with fork issue [Feature]: supervise long-running threads — turns complete while background subagents are still working, and nothing restarts the run #38 (Loop Watch). A maintainer thread that stalls with background work outstanding is precisely [Feature]: supervise long-running threads — turns complete while background subagents are still working, and nothing restarts the run #38's subject. Do not build a second staleness watcher here. Also note [Feature]: supervise long-running threads — turns complete while background subagents are still working, and nothing restarts the run #38's recorded hazard — "never gate on session.status — synthetic turns deadlock it" — applies to any liveness check added around these threads.
• Rate limits, and the specific way they bite. [Bug]: Background PR status polling via gh pr list drains GitHub GraphQL rate limit pingdotgg/t3code#3581's lesson is that the damage is not the polling failing, it is that exhausting the shared budget breaks explicit user actions (gh pr create started failing). A maintainer agent that quietly eats the quota that gh pr create needs is worse than one that does not run. The poller must back off on 403/x-ratelimit-remaining low, and that backoff needs a test.
• Provider serialization. N accepted issues means N sequential provider spawns through ProviderCommandReactor.ts:1323's single-item worker, and the 30-minute idle reaper (ProviderSessionReaper.ts:17) will kill parked sessions during a slow run. Fan-out must stay small.
• Cost is unbounded and unmeasured. No per-thread budget exists in T3 today. maxNewThreadsPerHour is a proxy for a spend cap, not a spend cap.
• Upstream-conflict risk if [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 lands mid-build. Mitigated by the detect.ts boundary, but if [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 also introduces its own project-scoped automation config, .t3x/maintainer.json becomes a fork-local duplicate of an upstream concept — the "parallel paths" hazard again, one level up. Re-check [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164's shape before v1.1.

Examples or references

Upstream issues and PRs (pingdotgg/t3code)

• [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 — [Feature]: Add Automations & Triggers (for loops) — OPEN, enhancement, 🚧 In Progress. The canonical trigger-system issue: cron schedules plus GitHub / GitLab / Sentry / Linear triggers, project-scoped. This issue is a consumer of [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164, not a competitor — see Proposed solution §7. If [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 lands with a GitHub issue trigger, this feature deletes detect.ts and subscribes instead; the triage taxonomy, plan-vs-implement routing, safety contract and per-repo enablement all survive.
• Automations pingdotgg/t3code#437 — Automations — CLOSED as duplicate of [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164. Its body ("when something happens (like a new issue being created or a pr or a ticket), a prompt runs automatically to process or respond to it") covers this feature's trigger half. It does not cover triage, routing or approval.
• [Feature]: Schedule prompts ( after and in recurring intervals ) pingdotgg/t3code#1390 — [Feature]: Schedule prompts (after and in recurring intervals) — CLOSED as duplicate of [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164.
• [Bug]: Background PR status polling via gh pr list drains GitHub GraphQL rate limit pingdotgg/t3code#3581 — [Bug]: Background PR status polling via gh pr list drains GitHub GraphQL rate limit — OPEN. Directly shapes the detection design in §1: VcsStatusBroadcaster.retainRemotePoller → refreshRemoteStatus → readRemoteStatus → findLatestPr → GitHubCli.listChangeRequests → gh pr list … drove GraphQL usage from ~184 to ~3,879 of 5,000 points while idle, then broke an unrelated gh pr create. Read this before writing the poller.
• Add durable local GitHub waitpoints for agent threads pingdotgg/t3code#4266 — Add durable local GitHub waitpoints for agent threads — OPEN, with implementing PR Add durable GitHub waitpoints to orchestration V2 pingdotgg/t3code#5003 (OPEN). A host tool registering a durable GitHub waitpoint that returns immediately and starts one continuation turn when the condition fires, polled via the user's authenticated gh. Adjacent, not overlapping: waits on a condition for one known PR rather than draining a queue. The right mechanism for a v2 "wake when CI is green on the branch I just pushed".
• PR Add a host-managed wait tool for Codex sessions pingdotgg/t3code#4262 — Add a host-managed wait tool for Codex sessions — CLOSED unmerged. Prior art for a namespaced host tool (t3.wait) run in the T3 server with no model inference; explicitly deferred durable wake-up.
• Feature: /review slash command for automated code review pingdotgg/t3code#915 — Feature: /review slash command for automated code review — OPEN. The only automated-review issue in the repo; a manual slash command, not a queue worker.
• [Feature]: Import Linear Issues to Create Threads (with Multi-Issue Support) pingdotgg/t3code#3703 — [Feature]: Import Linear Issues to Create Threads and Add ability to create worktrees from a starting point (linear issue, pull request, etc.) pingdotgg/t3code#417 — create worktrees from a starting point (linear issue, pull request, etc.) — both OPEN, both human-initiated. Nearest issue-to-thread features; neither watches anything.
• [Feature]: Add an atomic guarded wake primitive for idle threads pingdotgg/t3code#5123 — [Feature]: Add an atomic guarded wake primitive for idle threads — OPEN. thread.wake-if-idle, deliberately scoped to exclude any scheduler. Cross-reference only.
• PR feat: scheduled tasks (automations) pingdotgg/t3code#3638 — feat: scheduled tasks (automations) — MERGED 2026-07-01, but into the orchestrator-v2 stack branch t3code/codex-turn-mapping, gated behind still-open feat(orchestrator): introduce new orchestrator pingdotgg/t3code#2829. Not an ancestor of upstream/main. Ships schedule_task / list_scheduled_tasks / update_scheduled_task / delete_scheduled_task as agent-facing MCP tools. Relevant as evidence that upstream's scheduling answer exists but is not on main.

Fork issues (radroid/t3code)

• [Feature]: supervise long-running threads — turns complete while background subagents are still working, and nothing restarts the run #38 — supervise long-running threads. Adjacent: a stalled maintainer thread is exactly its subject. Do not build a second staleness watcher. Its recorded constraint ("never gate on session.status") applies here.
• [Bug]: auto-resume is cancelled as "user-took-over" by any user message — including one that was itself rejected by a limit #39 — auto-resume cancelled as "user-took-over" by any user message. Will affect maintainer threads that hit a usage limit; confirm before the v1.1 implement path.

Code, with line references (paths relative to repo root)

Autonomous dispatch, the pattern to copy:

• apps/server/src/t3x/autoResume/Reactor.ts:96-119 — dispatchResume; engine.dispatch({ type: "thread.turn.start", … }), "byte-for-byte the path a keystroke produces"
• apps/server/src/t3x/autoResume/Reactor.ts:64-95 — appendActivity, best-effort thread.activity.append with catchCause
• apps/server/src/t3x/autoResume/state.ts:1-60 — durable JSON store, SynchronizedRef + atomic write, and the comment explaining why not a DB migration
• apps/server/src/t3x/autoResume/config.ts:63-73 — resolveConfig(env) with safe defaults; :88 RESUME_PROMPT_RELATIVE_PATH = ".t3x/resume-prompt.md"; :96-113 resolveResumePrompt, a never-failing repo-file read
• apps/server/src/t3x/autoResume/decide.ts (71 lines) — pure decision function, the testability model for decide.ts
• apps/server/src/t3x/autoResume/Reactor.test.ts (345 lines) — the reactor test harness to model new tests on

Registration and layer wiring:

• apps/server/src/t3x/index.ts — T3xLayerLive / T3xRoutesLive aggregator, with the "do NOT add a new edit to any upstream-owned file" rule in its module comment
• apps/server/src/server.ts:224 — Layer.provideMerge(T3xLayerLive) inside ReactorLayerLive
• apps/server/src/server.ts:346-352 — RuntimeCoreDependenciesLive = ReactorLayerLive.pipe(… provideMerge(VcsLayerLive) …); :287 GitWorkflowLayerLive inside VcsLayerLive → GitWorkflowService is reachable from t3x
• apps/server/src/server.ts:248-251 — GitHubCli.layer is Layer.provided into SourceControlProviderRegistry, not merged → t3x must provide it itself
• apps/server/src/server.ts:632 — Layer.provideMerge(VcsProcess.layer) at the outermost runtime → GitHubCli.layer's only dependency is satisfied

GitHub access:

• apps/server/src/sourceControl/GitHubCli.ts:199-247 — service shape; :203 execute({ cwd, args, timeoutMs }) general escape hatch; :232 createPullRequest; :239 getDefaultBranch
• apps/server/src/sourceControl/GitHubCli.ts:28-137 — typed gh failures (GitHubCliUnavailableError, GitHubCliAuthenticationError, …) to surface as timeline activity rather than crash the fiber
• gh 2.96.0 supports gh api --cache <duration> (verified locally) — relevant to the §8 rate-limit experiment

Thread + worktree creation:

• apps/server/src/ws.ts:749 — dispatchBootstrapTurnStart, where bootstrap actually lives (not the engine); :891-906 thread.create dispatch; :908-930 fetchRemote → resolveRemoteTrackingCommit → createWorktree → thread.meta.update; :933 runSetupProgram() then final dispatch
• apps/server/src/git/GitWorkflowService.ts:65-79 — createWorktree / fetchRemote / resolveRemoteTrackingCommit signatures
• packages/contracts/src/orchestration.ts:554-568 — ThreadCreateCommand; :671 ThreadTurnStartBootstrap; :118-128 RuntimeMode / ProviderInteractionMode ("default" | "plan") and their defaults; :244-254 OrchestrationProposedPlan with implementationThreadId

Projects and queries:

• apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts:83 — getShellSnapshot() (use this); :75 getSnapshot() (avoid — OOM risk recorded in SEAMS.md); :168 getThreadDetailById
• packages/contracts/src/orchestration.ts:398-408 — OrchestrationProjectShell (workspaceRoot, repositoryIdentity, defaultModelSelection, scripts)
• packages/contracts/src/environment.ts:87-95 — RepositoryIdentity with optional provider / owner / name

Safety and limits:

• apps/server/src/provider/Layers/ClaudeAdapter.ts:3512-3517 — runtimeMode → Claude permissionMode (full-access → bypassPermissions); :3372-3378 — canUseTool auto-allows everything in full-access
• apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1323 — single DrainableWorker, session startup is serialized
• apps/server/src/provider/Layers/ProviderSessionReaper.ts:17 — 30-minute idle session reap
• apps/server/src/t3x/webPush/attention.ts:40 — attentionKindForEdge, the path that will fire a push for every maintainer thread completion

Seam discipline:

• docs/t3x/SEAMS.md:5 — 34 files, +1616/-187 against 64bf01619; :21 the row-35 tripwire; :71 apps/server/src/server.ts row (+3, churn 29, risk 87); :61 the overlay-mount row (+10/-6, churn 5, risk 80); :96-109 logic-mirrors table; :111-119 parallel-paths table
• apps/server/src/t3x/autoResume/http.ts:1-12 and :35-45 — the raw-route pattern and an existing registered logic mirror, if a /api/t3x/maintainer route is ever added
• apps/web/src/t3x/AutoResumeOverlay.tsx + apps/web/src/routes/_chat.$environmentId.$threadId.tsx:18,92 — what a fork-local UI costs

---

Duplicate search performed before filing

Searched exhaustively across both repos before filing.

Upstream (pingdotgg/t3code), all 1,615 issues open+closed — the full title corpus was dumped locally (gh issue list --state all --limit 6000, count cross-checked against gh api search/issues … total_count = 1,615) and grepped for ~80 term variants, plus body-level gh search issues per concept, plus a gh search prs sweep. Terms included: auto triage, triage, respond to issues automatically, agent that watches, watch repo, issue bot, open a thread for each issue, implementation plan for each issue, draft PR, propose a fix, automatically open a PR, approve before, human approval, maintainer, automation, cron, schedule, trigger, webhook. Upstream Discussions are disabled (hasDiscussionsEnabled: false), so issues are the complete search surface.

Result: no duplicate. Nothing in either repo proposes an agent that watches a repo's issue queue, classifies each issue, and routes it to a plan or a reviewable branch. The closest issue-to-thread features — pingdotgg#3703 (manual Linear import) and pingdotgg#417 (worktree from a starting point) — are both human-initiated.

Real overlaps, disclosed and cross-referenced in the References section:

• [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 (Automations & Triggers, OPEN, 🚧 In Progress) overlaps this feature's detection half — its scope explicitly includes GitHub triggers and "Linear triggers (new issue etc)". It has already absorbed Automations pingdotgg/t3code#437 and [Feature]: Schedule prompts ( after and in recurring intervals ) pingdotgg/t3code#1390 as duplicates. This issue is deliberately framed as a consumer of [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164: the detection module is isolated behind detect.ts precisely so it can be replaced by a [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 subscription without touching the rest. What is unclaimed by [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164 — and is what this issue is actually about — is the output policy: triage taxonomy, plan-vs-implement routing, the never-push / never-merge / never-full-access contract, per-repo enablement, and the fan-out caps.
• Automations pingdotgg/t3code#437 (CLOSED as dup of [Feature]: Add Automations & Triggers (for loops) pingdotgg/t3code#3164) covers "when a new issue is created … a prompt runs automatically". Same trigger overlap, same distinction.
• Add durable local GitHub waitpoints for agent threads pingdotgg/t3code#4266 + PR Add durable GitHub waitpoints to orchestration V2 pingdotgg/t3code#5003 (durable local GitHub waitpoints) are adjacent but a different primitive: waiting on a condition for one known PR, not draining a queue. Named as the right mechanism for a possible v2.
• [Bug]: Background PR status polling via gh pr list drains GitHub GraphQL rate limit pingdotgg/t3code#3581 is a bug report, not a duplicate, but it directly constrains the design and is cited as such.
• PR feat: scheduled tasks (automations) pingdotgg/t3code#3638 (agent-facing schedule_task MCP tools) is merged onto the orchestrator-v2 stack branch, not main, and behind still-open feat(orchestrator): introduce new orchestrator pingdotgg/t3code#2829. It is scheduling infrastructure, not issue triage.

Fork (radroid/t3code), all 21 issues open+closed: no match. #38 (supervise long-running threads) and #39 (auto-resume cancellation bug) are adjacent and cross-referenced under Risks; neither proposes issue-queue work. Fork searches for maintainer, triage, coverage, architecture, parallel returned only unrelated t3x-sync and steering issues.

Contribution

• I would be open to helping implement this.

[radroid]

Priority triage — 2026-08-07: Rank 10 / 11 — Tier 6 (downstream, large)

Large, and leans on both a healthy sync loop (#49) and the orchestration cluster (#42/#38/#43). Deferred until those are in place.

[radroid]

Triage 2026-08-07 — blocked on #39, and its triage routing sits on plan-mode semantics upstream just changed

Two dependencies, one of which this issue already identifies.

1. #39 is a hard blocker for the implement path. This issue notes it under Risks; confirming that it is not merely a caveat. §4's routing dispatches a second turn into the same thread, and §5 caps unattended work — long unattended implement turns are precisely what hits a usage limit, and today ≈24% of armed resumes are destroyed by any user message arriving afterwards. A maintainer thread that hits a limit and gets a follow-up comment is stranded with no pending resume. Fix #39 first. It is fork-owned, sync-independent, and can start immediately.

2. The plan-vs-implement routing rests on surfaces upstream reworked. upstream/main is 103 commits ahead and unmerged (#49). In that range:

• a8cd2ad2 fix(web): plans stop hijacking the UI, fold into chat instead (#5558) and 48aa875c feat(web): remove Build/Plan toggle from the composer (#5551) — §4 routes complex issues to interactionMode: "plan" and relies on the plan surface rendering an OrchestrationProposedPlan with a one-click "implement in a new thread" path. Both of those commits change how plan mode presents. §8's open question — "Can interactionMode be flipped mid-thread by a fork-side dispatch?" — must be answered against the post-sync decider, not the current one.
• a2ca89aa feat: native subagent & workflow observability (#5219) adds ThreadBackgroundLiveness.ts. §5's fan-out ceiling and the "parked maintainer thread loses its process silently" concern are now partly observable natively, which is useful for the caps design.
• ws.ts takes 5 upstream commits — §3 mirrors ws.ts:891-933 for thread + worktree bootstrap. That mirror should be derived from the post-sync file, since a mirror written against a stale original is the exact silent-drift failure SEAMS.md:99 warns about.

Still valid and worth keeping: the safety contract in §5 (never full-access, always a worktree, never push, never merge, durable caps, a visible trail) is the most reusable part of this issue and is independent of all of the above. #38 and #42 both need it. It may be worth extracting into its own document before this feature is built.

Also re-confirm upstream pingdotgg#3164 (Automations & Triggers) status before starting — §7's whole architecture depends on detect.ts being disposable if it lands.

Priority: P6, after #39 and #49.