A running coding loop is opaque over MCP — coding_timeline is written during the run and no MCP tool reads it

[serge-ivo]

A live coding run is opaque over MCP, and the data it needs is already being written

Owner's ask, recorded by their own agent as feedback fd60c895-bc18-4ee3-b4f1-de9b351ad4f7
(2026-08-15 02:19, instance bd43f4de-ef35-4051-bdec-43f8571414a1, status:"open") and repeated
directly to me on 2026-08-15:

expose a live, per-step trace of a loop run to the owner — each iteration's tool calls with
arguments and results, and streaming or incremental output — through the same MCP surface that
starts the run. agent_trace exists for chat turns; loop runs need the equivalent, queryable
while the run is still in flight, not just after it ends.

What an external MCP client can see today, while a run is running

Tool	What it gives	Gap
coding_loop_status / check_instance_loop	status, iteration, lastProgressAt, detail (only once finished)	No steps, no tool calls, no output
coding_session_capture	last pane text + runState	A rolling terminal buffer, not a record; needs the session id
agent_trace source:"coding"	act.consequential rows, and errors only via lib/coding-failure.ts:341 on a classified failure	Nothing per-step; a run that stalls writes nothing
instance_activity	chat-session events only	Feedback: "shows nothing at all from loop runs, so during a run it looks idle even though work is happening"

Measured consequence in #580: a run whose engine died at step 1 reported running for 4.35 hours,
and the only place the truth existed was the pane.

The data is already recorded — it just has no MCP reader

coding_timeline (migration 0023, append-only, seq-ordered) is written during the run.
workers/api/src/routes/coding.ts:416 is explicit:

/** Persist a system/status message to the coding timeline (loop events, errors). */

There is an API route — GET /:instanceId/coding/sessions/:sessionId/timeline
(routes/coding.ts:430) — backed by loadTimeline in lib/coding-timeline.ts.

$ grep -rl 'coding_timeline' workers/mcp/src/
(no matches)

Thirteen coding tools on the MCP surface and none of them reads it. This is the same absence
#527 names for the finished-run case. #527 and this issue are one tool apart: a
seq-cursored reader answers both, because "audit a finished run" and "watch a running one" differ
only in whether you keep asking.

Design

One tool, cursor-paged the way instance_messages now is after #566:

coding_timeline(instance_id, session_id?, since_seq?, limit?) → { events[], nextSeq, hasMore, runState }

• since_seq makes it a live feed. Poll with the last nextSeq; get only what is new. No
  streaming transport needed, and it is the same shape Notify proactively when an agent run finishes (webhook / event feed) - investigation #579 Phase 2 proposes for run completion —
  build one cursor convention, not two.
• session_id optional → newest active session, so a caller that only has an instance id can
  still watch.
• Include runState so a caller learns "no new events AND idle" (dead) apart from "no new
  events AND working" (a long step). That distinction is the actual question in A run whose engine died at step 1 reported 'running' for 4.35 hours with a fresh lastProgressAt, and wrote nothing to the trace #580 and cannot be
  answered by an event list alone.

Payload-size constraint, learned the hard way today

#569 measured list_instance_tools at 66,042 B in production — over the 64 KiB wire limit — after
a guard passed at ~54 KB, because jsonText pretty-printed after the assertion. #578 is open
on the same tool 433 B over on its opt-in path. A timeline reader is unbounded by nature, so:

1. limit must have a real default and the response must be measured on the deployed tool, not
   on the API body.
2. Terminal snapshots are the bulk. Consider returning them by reference or truncated-with-a-count
   rather than inline, and state the decision.

Acceptance criteria

1. An MCP client can read a coding run's per-step record while the run is in flight, without
   knowing a session id in advance.
2. since_seq returns only newer events; repeated polling with the returned cursor never
   re-delivers or skips. A test drives two overlapping pages and asserts disjointness, as instance_messages returns nextCursor and hasMore: true and has no cursor input — every message older than the first page is unreachable over MCP #566's
   fix does.
3. The response distinguishes no new events because idle/dead from no new events because a step
   is long.
4. Response size asserted against the wire limit, measured at the layer the client receives, with
   the denominator stated per ADR 0002.
5. A finished coding run is unauditable over MCP — 13 coding tools, none reads coding_timeline, and coding_session_capture answers an ended session with an empty pane #527's finished-run audit case is satisfied by the same tool, or the issue states why it needs a
   second one.
6. A test reproduces A run whose engine died at step 1 reported 'running' for 4.35 hours with a fresh lastProgressAt, and wrote nothing to the trace #580's case: engine dies at step 1, and the timeline read shows the terminal
   error rather than silence.

Verified vs inferred

• Verified: the feedback row and its text; the empty grep -rl coding_timeline workers/mcp/src/;
  routes/coding.ts:416 and :430; coding-failure.ts:341 as the sole coding-trace writer;
  A finished coding run is unauditable over MCP — 13 coding tools, none reads coding_timeline, and coding_session_capture answers an ended session with an empty pane #527's open state and title; the four tools' current payloads, called live 2026-08-15; the list_instance_tools documents 2 of the 4 tier values it returns, and its default response is 117 KB — enough to exceed a host's limit on one instance #569
  production measurement.
• Inferred: that coding_timeline contains enough per-step detail to satisfy the ask —
  it demonstrably carries loop events and errors, but whether it holds each tool call with
  arguments and results was not confirmed. That is the first thing to establish: if it does not,
  this issue grows a write-side half and should say so rather than shipping a reader over a record
  that lacks what was asked for.

[serge-ivo]

The inferred claim is resolved: the timeline carries a narrative, not structured tool calls

The issue flagged as unverified "whether coding_timeline holds each tool call with arguments and
results", and said that if it does not, this issue grows a write-side half. Checked.

What it actually holds

Migration 0023_coding_timeline.sql:

CREATE TABLE coding_timeline (
  seq         INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id  TEXT NOT NULL REFERENCES coding_sessions(id),
  …
  type        TEXT NOT NULL,   -- chat_user | chat_assistant | terminal | command | brain | outcome | system
  content     TEXT NOT NULL,
  created_at  TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_coding_timeline_session ON coding_timeline(session_id, seq);

Its own header: "interleaves EVERYTHING in chronological order: the co-pilot conversation, terminal
snapshots, commands the user sent, the brain's actions, and outcomes."

So the record is real and rich — command, brain, terminal, outcome — but content is
free text. There is no structured argument/result pair.

The structured half exists, elsewhere and partially

agent_events act.consequential rows DO carry structure — as read live on 2026-08-15:

{"act":"file.delete","command":"cd /tmp && rm -rf pas-sdk-check && …","target":null,
 "irreversible":true,"ok":true,"sessionId":"csess_c306e923-…"}

That is a tool call with its argument and its outcome. But only consequential acts are recorded —
the classifier decides what qualifies, and (per #582) it currently mislabels what it does capture.
An ordinary read, grep or file open produces no such row.

Net: the ask splits in two, and only one half needs new writes

Owner's ask	Available today	Verdict
per-step narrative, live	coding_timeline (command/brain/terminal/outcome, seq-ordered)	Reader only — the data is there
streaming / incremental output	terminal rows + /capture	Reader only
each tool call with arguments and results	only consequential acts, via agent_events	Needs write-side work

This should ship as the reader first. A since_seq feed over coding_timeline answers "what is
it doing right now", which is the question in #580 and the one costing the owner real time — without
waiting on a structured tool-call record. The structured half is a separate, larger change and should
not gate it.

Recommend amending AC1 to scope explicitly to the narrative record, and adding:

• AC7: the issue states plainly which part of the ask the reader does not satisfy — a
  per-tool-call argument/result log — so the owner is not told a partial answer is the whole one,
  and that gap is tracked separately rather than silently dropped.

Verified vs inferred, updated

• Verified now: the full coding_timeline schema and its six type values; the migration
  header verbatim; the act.consequential context shape read live from agent_trace.
• No longer inferred: whether the timeline holds structured tool calls. It does not.
• Still inferred: that brain rows contain the instruction text sent to the engine. The
  migration header says "the brain's actions"; the exact content was not sampled, and it determines
  how useful the narrative reader actually is. Sample one before building — it is the difference
  between a live feed worth having and a list of timestamps.

[serge-ivo]

Shipped as the reader — da4bcec, live in production

coding_timeline(instance_id, session_id?, since_seq?, limit?) is registered and deployed.
GET https://mcp.proagentstore.online/health → "tools": 136, and the backing route answers 401
(not 404) at GET /v1/instances/:id/coding/timeline, against 404 for a nonexistent path under the
same prefix.

AC7 — what this reader does NOT satisfy, stated plainly

The ask has three parts and this closes two of them.

Ask	Status
per-step narrative, live	done — command/brain/terminal/outcome, seq-ordered
streaming / incremental output	done — since_seq poll + terminal tails
each iteration's tool calls with their arguments and results	NOT DONE

coding_timeline.content is free text. There is no structured argument/result pair anywhere in
this record, and no amount of reading it will produce one. The structured half exists only for
consequential acts, in agent_events — reachable as agent_trace(source:"coding") — and only the
acts the classifier decides qualify; an ordinary read, grep or file open produces no such row.

So: if the question is "what is it doing right now", this answers it. If the question is "show me
every tool call this iteration made, with its inputs and outputs", it does not, and cannot.
That half needs write-side work and is not tracked by this issue. The tool's own description says
so, in the text a model reads, so a caller is not handed a partial answer as the whole one.

The inferred claim, resolved — and it was wrong in a way that mattered

Your comment flagged: "Still inferred: that brain rows contain the instruction text sent to the
engine … Sample one before building." Sampled, from production D1, before building. They do
not.

brain is written three times per run, all at the start (coding-session.ts:611-616): the
objective, the repo's working state, the merge authority. Never per iteration.

The per-iteration instruction is a command row (coding-session.ts:524) — driven, the
verbatim text the Pilot sent the engine, ungated by loopRunId so a hand-driven session records it
too. Live sample:

seq 8977  brain    "AI run started — objective: Fix issue #26 in freegamestore-online/platform: CI is green but only runs tests for 3 of 11 packages…"
seq 8976  command  "Please read GitHub issue #57 from the repository proappstore-online/platform using the gh CLI: run `gh issue view 57 …`"
seq 8965  outcome  "done — Issue #120 is fully resolved. Commit `1fbb124` landed on `main` with 13 files changed (+791/-103)…"

Distribution across 2,757 rows: command n=483 mean 427 chars · brain n=118 mean 608 ·
outcome n=105 mean 361 · terminal n=914 mean 8,068, max 12,000.

Verdict on your question: a live feed worth having. But had the reader been built assuming
brain was the per-step record, it would have returned three rows per run and looked like the list
of timestamps you warned about.

Payload — measured on the deployed tool, denominator stated

terminal is 914 of 2,757 rows at mean 8,068 / max 12,000 chars, so five untouched snapshots
overflow a 64 KiB response. A row cap alone cannot bound that, so the page is bounded twice:

1. per row — terminal keeps its 400-char tail (the live end of a pane), everything else
   its 1,200-char head; a cut row carries chars, its true length.
2. per page — 40,000 serialised bytes, counted on JSON.stringify of each row so escaping
   and multi-byte characters are inside the measurement. The first row is always emitted, so one
   large row cannot stall the cursor.

Measured at the layer the client receives (ADR 0002): 79 rows of 12,000-char panes → 40,304 B
compact, against the 65,536 B limit; the same rows inline would be 948,000 chars. The tool sends
compact — jsonText pretty-prints by default, which is the exact ~22% that turned #569's asserted
54 KB into a served 66,042 B — and the budget leaves 1.5× headroom, so serialisation style is not
what keeps it under.

AC coverage

1. ✅ readable in flight without a session id — resolves newest active, else most recent.
2. ✅ since_seq disjointness — two overlapping pages driven against the real schema
   (realSchemaD1), asserted disjoint, complete and ordered. Empty page echoes the cursor back
   rather than restarting the session.
3. ✅ runState distinguishes idle/dead from a long step. An ended session reports ended, and
   an unreachable runner offline, rather than the runner's idle.
4. ✅ above.
5. ✅ A finished coding run is unauditable over MCP — 13 coding tools, none reads coding_timeline, and coding_session_capture answers an ended session with an empty pane #527 satisfied by the same tool — see the comment there.
6. ✅ A run whose engine died at step 1 reported 'running' for 4.35 hours with a fresh lastProgressAt, and wrote nothing to the trace #580's case reproduced as a test: engine emits the weekly-limit error at step 1, the read
   shows it rather than silence, with hasMore:false + a non-working runState.

One thing I did not do

store/docs / e2e were not run — nothing in store/ or agents/coder/web changed. Everything else
in ci.yml ran green, and CI is green on main.

[serge-ivo]

AC7 closed — 7932473, corrected by cbc44e4, live in production

The reader shipped in da4bcec stated the half it could not answer: "show me every tool call this
iteration made, with its inputs and outputs". That half is now closed, and it needed no new
writes — which was not the expected answer.

The record was already crossing the wire, in the rows this feed already served

headless.ts:670 pushes EVERY tool_use into the transcript as ⚙ <tool> <input>, and :676
every tool_result as ↳ <result>. That transcript is the pane, the pane is what a terminal
row stores. Sampled from production D1 on 2026-08-15:

measurement	value
terminal rows carrying ⚙ and ↳	883 of 914 (96.6%)
tool calls per row (one 86-row session, 1,036 lines)	mean 12.05
how many of those twelve the feed showed	at most one

FEED_TERMINAL_CHARS keeps a 400-char tail of an 8,000-char pane, so ~95% of the record you asked
for was being cut away by a size bound rather than being absent.

Why deriving beats writing, stated as a decision

1. it covers every run already recorded — a runner change covers only runs made after a CLI
   publish and a user upgrade;
2. no D1 writes; a write-side record is ~12 rows per snapshot, ~10k for the corpus that exists;
3. it stays behind engine-acts.ts, the one place the platform already treats the runner's report
   as evidence rather than truth, so nothing new has to be trusted;
4. its fidelity ceiling is the runner's own display caps — 160 chars of input
   (headless.ts:899), 240 of result (:910) — which the parser reports (inputCut/outputCut)
   instead of hiding.

De-duplication is the load-bearing half, not a refinement

Consecutive snapshots are tails of one growing transcript. 1,036 parsed call lines reduce to 610
occurrences — 41.1% duplication. The raw parse would hand a poller the same twelve calls every
three seconds and break AC2's "never re-delivers or skips" at call granularity.

The anchor is the last settled call, not the last call. Anchoring on the last one marks the
in-flight call delivered, so its result — arriving one snapshot later, and the single thing a live
watcher is waiting for — would never reach the reader. There is a test that fails on exactly that.
Matching is positional and takes the LAST occurrence, so a command genuinely run twice is reported
twice. When the anchor has scrolled out of the window the row says toolCallGap rather than
pretending continuity — 35 of 86 rows on the sampled session.

The budget, and the two wrong answers before the right one (cbc44e4)

This is the part I got wrong in the first commit and only production data caught.

budget=6000   delivered=486  omitted=124   <- shipped in 7932473
budget=8000   delivered=557  omitted=53
budget=10000  delivered=600  omitted=10
budget=12000  delivered=610  omitted=0     maxRowBytes=11331
budget=16000  delivered=610  omitted=0

6,000 B was sized from the mean production row and shipped under a docblock claiming omission
was "reserved for a genuinely abnormal row". Replaying 86 real rows through the deployed reader said
124 of 610 calls omitted, 20%. The mean was the wrong statistic: a row that loses continuity
re-emits its whole window, so the row that has to fit is the largest. 12,000 is the measured knee.
(An earlier 1,600 was sized from the page's point of view and omitted 9 of every 12.)

The asymmetry that decides this: a row dropped by the page budget costs one more poll; a call
dropped by the row budget is gone.

AC4's measurement, re-stated for the new payload

Worst case (40 snapshots, twelve calls each, sharing nothing so de-duplication removes nothing):
7 events, 39,973 B against the 65,536 B limit the host in #569 applied. The first version of
that test reused one call block across all 40 rows, so rows 2-40 emitted nothing and it was
measuring the de-duplicator instead of the payload — #569's mistake in a new place. The test now
says so, in the test.

Verified in production

86 real terminal rows replayed through the deployed reader: 610 of 610 calls delivered, 0
omitted, 8 pages, largest page 39,797 B. Sample of what a caller receives:

Bash {"command":"git pull","description":"Pull latest changes from remote"}

Route live (401 on GET /v1/instances/:id/coding/timeline against 404 for a nonexistent path
under the same prefix); MCP tools: 136, unchanged — no tool and no inputSchema changed, so no
surface bump was required and check-surface-lock stayed green. The tool's description was
rewritten: it previously promised the opposite ("not a structured tool-call log"), and descriptions
are excluded from the fingerprint by surface-lock.ts's stated decision.

What is still NOT claimed

Whether a call succeeded. The runner reads block.is_error at headless.ts:750 but
toolResult() never writes it into the transcript, so an ok here would be derived rather than
observed — the guess describeEngineAct refuses on the same data. A pending call reports
output: null, which is a real and live state, and a failed call reports its error text like any
other. Closing that is a one-line runner change plus a CLI publish; worth its own issue and I
have not filed one.

The 400-char tail stays beside the calls: #580's case is an engine error printed to the pane, not a
tool call, and a reader that only saw tool calls would miss the one thing AC6 exists to prove is
visible.

CI green on 7932473; cbc44e4 green through dc68e2a. test:e2e not run — nothing in store/
or agents/coder/web changed.