Next standalone skill: the agent logs. The plan and five questions.

[suleimansh]

Next skill after the queue: the agent logs. You picked it before routines because it is the uncertain one. This issue is the plan and the questions. Nothing is built yet.

1. What exists. The daemon archives every finished run on the agents-logs branch, as agents/<git email>/<id>.json plus <id>.jsonl. The .json is the run's record: intent, driver, branch, PR, ticket, outcome. The .jsonl is the framework's event log of the run: what the agent said, which tools it called by name, the cost, the handoff. It is not the chat transcript. Only the dashboard and the daemon read these files. No agent reads or writes anything there today.

2. What is decided. agents/ moves onto agent-data beside tickets/ and the queue, and agents-logs goes (Skills as capabilities: the queue and the routines as their own skills, the file-store code out of skill-branches, agent-driver per driver #1750 point 1). That part is a fold, not a skill.

3. The questions. I need your call on five things before I build. Each has its options in the plan below.

   • Q1, what agents get: read past runs (by ticket, by branch, the latest), write a note on their own run, both, or neither. Neither means only the fold.
   • Q2, what the branch stores per run: the record and the event log as today, or the record and the agent's note, with the event log staying local.
   • Q3, the email in the path. The repo is public. The same email is already the author of every commit on the branch. Run ids never collide, so the per-user directory groups the runs and protects nothing.
   • Q4, the command, and what the SKILL.md tells an agent to do with it.
   • Q5, what the daemon and the dashboard need. They list, replay, patch and delete records. The record's shape is the framework's, 25 fields. A standalone skill cannot own that shape without framework names in it.

4. Names follow the rule in force: package skill-logs, skill and command logs. You are renaming to skills-<x>, so no name carries any weight in the plan.

5. The fold rides in the same PR or lands first. My call once you answer.

---

🤖 curated · Fable 5.1 — the plan, as the agent wrote it after reading the code on main (8a89547) and the agents-logs branch on origin; I read it and I stand behind the questions above.

The plan

What it is. The third skill after branches, tickets and queue: the record of what agents did to a project. Today the framework writes that record for its own dashboard. The question this round answers is what an agent gets from it, and what the skill owns. The rule from #1750 holds: a skill depends on git and on @gemstack/agent-data, never on another skill. The framework is the caller.

The branch on origin, 2026-09-09:

runs archived	208 (07-26 to 09-08)
files	415: 208 records, 207 event logs
size	5.25 MB
commits	159
record size	1 to 2 KB
event log size	114 B to 155 KB
user directories	2: git@brillout.com, suleiman@averotech.com
runs by driver	claude-web 107, claude-code 95, actions 4, codex 1, unknown 1
cost recorded	$238.64, over 104 usage events

The largest event log is a ten-leg run. 105 KB of its 155 KB is the start prompt, repeated once per leg. The agent's own text lines are 6 KB of it.

What the code does today (the facts the plan rests on, with where):

• Write. At teardown the daemon reads the git identity, then archives the run through the branch's write funnel: daemon-runtime.ts:596-609 (resolveUserDir, withFileBranch(LOGS_BRANCH), archiveWorktreeAgent). The copy is the checkout's agent.json and events.jsonl, renamed <id>.json and <id>.jsonl (store/agent-store.ts:696-703), into .branches/agents-logs/agents/<user>/ (agent-store.ts:647-649). A run still marked running is flipped to stopped first, and the branch holding its commits is stamped on the record, the last moment it can be read (agent-store.ts:766-795). One commit per run: [The Framework] archive session <id>.
• The user directory. agent-archive.ts:40-67: git config user.email, lowercased, unsafe characters replaced, anonymous when unusable. Its stated reason is that two people's machines must not write the same paths (agent-archive.SPEC.md). An id is the start time to the millisecond (agent-store.SPEC.md, "An agent id is its start time"), so two paths collide only when two machines start a run in the same millisecond. The same email is the author of the branch's commits: git log --format=%ae origin/agents-logs shows the two addresses plus claude@brillout.com and noreply@anthropic.com.
• A second, transient copy. .the-framework/agents/ holds runs with no worktree and the crash rescue (agent-store.ts:638-640, 707-713). Empty on this machine today.
• Read. Every <user>/ directory plus the transient one, de-duplicated by id, committed copy first (agent-store.ts:680-690, 859-871). listAgents(cwd, fs, since) (agent-store.ts:880) feeds the dashboard's History list (dashboard-rpc/reads.ts:81-93), the CI watch (ci-watch.ts:142-146, the mergeOutcome scan), the routine-lock release on boot (daemon-services.ts:248), the keep-or-remove decision for a worktree (worktrees.ts:66-73, 181), and the continue, which reads the recorded branch (daemon-runtime.ts:490-494). The event log is replayed for a run's page (reads.ts:194, loadAgentEvents at agent-store.ts:1046), tailed for an ended run (store/agent-checkout.ts:54), read for the failure detail that earns a transient retry (daemon-runtime.ts:645-646), and put back into a checkout when a run is continued (restoreArchivedAgent, agent-store.ts:725).
• Patch. Two late facts, branch and pr (ArchivePatch, agent-store.ts:1111), written through the funnel by archived-agent-patch.ts:16-27. Callers: cloud adoption, which matches a waiting web run to its claude/* head and records branch and PR, within a 48-hour window (cloud-work.ts:32, 152-220); the dashboard's Open PR button (dashboard-rpc/control.ts:280).
• Delete. The dashboard's Remove deletes the record and the log as one committed, pushed change (worktrees.ts:255-263).
• Sync. Every other tick the daemon pulls agents-logs after it converged agent-data, one data-sync error slot for both (daemon-services.ts:128-137).
• Routine locks. routines/<name>.lock.md on the same branch (routine-locks.ts:22-30, 68). None on origin right now.
• Names. LOGS_BRANCH and LOGS_CHECKOUT_DIR (framework-dir.ts:17, 23); the LAYOUT marker line logs-branch: (layout.ts:42, lockstep test layout.test.ts:56-66); the comment inside the written .gitignore (framework-gitignore.ts:21).
• Agent-facing. Nothing. No preset, prompt or SKILL.md names the archives (grep over prompts/ and the three SKILL.md: zero hits). An agent's PATH carries branches, tickets, queue (daemon-runtime.ts:110-119), and its id as AGENT_ID.
• Text that says agents-logs. packages/framework/SPEC.md:5, src/SPEC.md:9-10, framework-dir.SPEC.md, agent-archive.SPEC.md, archived-agent-patch.SPEC.md, routine-locks.SPEC.md, daemon-services.SPEC.md:16,44,92,133, project-errors.SPEC.md:5, auto-pm.SPEC.md:12, framework-gitignore.SPEC.md, store/agent-store.SPEC.md; dashboard ProjectErrorBanner.SPEC.md:5, RoutineWork.SPEC.md:12, AgentHistory.SPEC.md:55, ProjectHome.tsx:52, AgentHistory.tsx:629, ProjectErrorBanner.tsx:6; FEATURES-SPEC.md:92,133,151,193. Tests: agent-archive.test.ts, archived-agent-patch.test.ts, routine-locks.test.ts, store/agent-store.test.ts:486,710,727, store/agent-checkout.test.ts:65.

What a record holds (the union over the 208 on origin): id, status, startedAt, updatedAt, intent, branch, pid, host, handoff, workspace, driver, sessionLink, sessionId, version, passes, target, scope, kind, handoffReport, model, readyForMerge, handoffSkip, cloudAnchor, ticket (23 records), mergeOutcome, sessionName, pr (8), queueEntry (6), pendingChoice. host is the machine name and workspace an absolute path under the user's home.

What an event log holds: driver events (the agent's text lines, tool calls by label only, the start prompt per leg, the result, rate limits), bootstrap, system-prompt, intent, session, branch, handoff-armed, handoff, usage (cost and tokens), choice and choice-resolved, ready-for-merge, settled, ticket, queue-entry, pull-request, open-pr, cloud-anchor, end, error. No tool inputs or outputs, no diff. agent-store.SPEC.md: "The agent's own chat transcript is deliberately not persisted; the wrapped CLI owns that."

So a past run answers, for an agent: what was asked, on which ticket or queue entry, by which driver and model, where the work went (branch, PR), how it ended, what it cost, and what the agent said along the way. The diff lives on the branch and the PR. The record is the join between a ticket, a run, a branch and a PR that neither git nor GitHub has.

---

1. Names

	package	skill (name:)	command	on agent-data
logs	@gemstack/skill-logs	logs	logs	agents/

The rule in force, skill-<x> and <x>. The directory on the branch stays agents/, as #1750 point 1 says. A rename to skills-<x> is a find-and-replace and changes nothing below.

2. Q1: the capability

Three pieces, each in or out:

• (a) Agents read past runs. logs lists the runs of this project, newest first; logs --ticket <file> the runs that worked one ticket; logs --branch <name> the runs on one branch; logs show <id> one run. The use case is a second attempt: a drain or a plan on a ticket someone worked before starts by reading how the last run ended. Today the tickets claim says who holds a ticket. Nothing says what happened to it last time. 23 records name a ticket, 6 a queue entry.
• (b) Agents write a note on their own run. logs note <text>, keyed on AGENT_ID like a claim. A run reaches the branch only at teardown, after the agent's process is gone, so a note written during the run has no record to attach to yet. Two ways: the note is its own file, agents/<user>/<id>.md, and the record lands beside it later; or the record is written at start and updated at the end, which is two commits per run instead of one.
• (c) The daemon keeps writing the record and the event log. This is the caller's write through the skill's library, whatever (a) and (b) say. If neither (a) nor (b) is wanted, there is no SKILL.md to write, and this round is the fold only, with the archive code staying in the framework or moving to a library like agent-data.

What "read" gives an agent that it cannot get from git or gh: the ticket-to-run-to-PR join, the outcome, the cost, the agent's narration. What it does not give: the diff, the tool outputs, the chat.

3. Q2: the store

	on the branch, per run	reads that keep working	what changes
A, as today	record + event log	all of §"Read" above	nothing
B, record + note	record + the agent's note; the event log stays in .the-framework/ on the machine that ran it	History list, CI watch, adoption, continue's branch	the run page replays nothing on another machine; the retry's failure detail and the continue's log restore work only on the machine that ran the run
C, as today, the prompt once	record + event log with the start prompt written once, not per leg	all	the largest logs shrink by two thirds

Numbers for A: 415 files and 5.25 MB in 44 days, about 9 files and 120 KB a day, about 43 MB a year at today's pace. Git handles it; a clone of the branch pays for it. On 08-31 you said, about recording conversations, that lossless plus timestamped is right and history is immutable. If that applies here it is A or C.

4. Q3: the identity in the path

Today: agents/<email>/<id>.json. The email is the git identity, sanitized (agent-archive.ts:40-48). The repo is public, and the branch is pushed. The same address is the author of every archive commit, so the path adds nothing the branch's history does not show. The ids cannot collide, so the directory groups the runs by who ran them and does not prevent conflicts.

• A, keep the email. Nothing changes. The grouping stays visible in a file listing.
• B, flat agents/<id>.json, the author inside the record as a field, like host already is. One directory to list. The dashboard marks another machine's runs by host already (reads.ts:113-120).
• C, the git user.name instead of the email. Same shape, a name instead of an address, and two people can share a name.

The record also carries host and workspace, an absolute path under the home directory. Whatever the path decision, say whether those two stay.

5. Q4: the command and the SKILL.md

Depends on §2. If (a) only:

logs                       the project's runs, newest first, JSON
logs --ticket <file>       the runs that worked one ticket
logs --branch <name>       the runs on one branch
logs show <id>             one run: its record, and its note when it has one

If (b) too:

logs note <text>           a note on your own run (AGENT_ID); replaces the last one

The SKILL.md then says one of two things. Either "before you plan or work a ticket, read its runs: logs --ticket <file>; a stopped or failed run tells you what to avoid", which puts a read in every drain and plan. Or nothing about when, only what the command is, and the presets decide. The first costs a fetch per run start. The second leaves the capability unused until a preset names it.

The library side, for the caller: list with since, find by id, read the event log, write a run (record and log), patch a record, delete a run. The same functions the framework calls today, moved.

6. Q5: what the caller needs, and who owns the record's shape

The framework reads eight fields for its own decisions: status, host, startedAt, branch, pr, mergeOutcome, target, and cloudAnchor with handoff for adoption. The dashboard renders about twenty. The record type is AgentMeta, the framework's, with names like handoffSkip, cloudAnchor, readyForMerge. Your rule says a standalone skill must not carry framework names.

• A, the skill owns a small record: id, startedAt, endedAt, status, intent, driver, model, branch, pr, ticket, note, cost. The framework keeps the rest of AgentMeta in the same file under a key of its own, or in a second file. The skill reads only its fields; the framework reads both.
• B, the record is opaque to the skill: the skill stores and lists JSON files and the event log, and knows only id and startedAt from the filename. logs --ticket is then not possible without the skill knowing where the ticket sits in the record.
• C, the skill owns AgentMeta as it is, renamed field by field. The largest move, and the dashboard follows every rename.

The event log's shape is the framework's event stream. Under A and B the skill stores it as lines and does not parse it.

Whatever the skill owns on the branch is its public API under the semver rule agreed on 09-09: a change to it is a major, and it needs the by-hand cutover, since the consumer is another machine on the older version reading the same branch.

7. The fold, and the cutover

The fold is the same whatever Q1 to Q5 say:

• LOGS_BRANCH and LOGS_CHECKOUT_DIR go (framework-dir.ts:12-23). Every use points at DATA_BRANCH from @gemstack/agent-data: routine-locks.ts:68, archived-agent-patch.ts:23, worktrees.ts:256-259, daemon-services.ts:128-137 (one pull, not two), daemon-runtime.ts:602, framework-gitignore.ts:21, store/agent-store.ts:648,682.
• layout.ts:42 drops the logs-branch line; .the-framework/LAYOUT is regenerated in the same commit, or layout.test.ts fails.
• The routine locks move too: routines/ on agent-data, as Skills as capabilities: the queue and the routines as their own skills, the file-store code out of skill-branches, agent-driver per driver #1750 point 4 foresaw.
• Every SPEC and text file in the list above, FEATURES-SPEC.md lines 92, 133, 151 and 193, and the five test files.

The cutover is by hand, per machine, before that machine's daemon runs the new build: copy agents/ from agents-logs onto agent-data (git checkout agent-data, git checkout agents-logs -- agents/, commit, push), release any routine lock on agents-logs, delete agents-logs on origin and locally, remove .branches/agents-logs. Three projects on my machine. Your machines too: a daemon on the old build after the fold archives onto agents-logs again, the ghost-branch problem agents-data had.

8. PR shape

One PR if Q1 says (a) or (b): the package, the fold, the framework adopting the library, DECISIONS.md and the SPECs, dogfooded on the rig. Two PRs if the fold should land first: the fold alone is about 20 files and one cutover. My call after the answers. Publish after merge with the other three. FEATURES-SPEC.md gains the agent-facing lines and loses the agents-logs ones.

9. Not in this round

Reading the chat transcript (the CLI owns it). Summaries written by the framework instead of the agent. Retention or pruning of old runs. Routines.

[suleimansh]

My picks, one per question. For each: the story I used to decide, the options, what the agent recommended, and what I picked. They are proposals. Your call stands.

---

Q1, what agents get

Story. An agent starts on a ticket. Another agent tried it last week and failed. Today the new agent sees only the claim, who holds the ticket. It cannot see that there was an earlier try, how it ended, or what that agent said before it died.

Options.

• A. Read only: agents list and open past runs, by ticket, by branch, the latest. The daemon keeps writing the records.
• B. Read and note: reads, plus logs note <text> so an agent leaves a message on its own run. More work: the record lands on the branch only after the agent is gone, so a note needs its own file or a record written at start.
• C. Neither: no skill this round, only the fold onto agent-data.

🤖 recommended: A. Cheap, clear use, and a note only pays if agents write useful ones, which we cannot know before reads exist.
👤 I picked: A. Notes can come as a later minor version.

---

Q2, what stays on the branch per run

Story. You start an agent on your laptop. The daemon writes two files: a small card (what was asked, branch, PR, how it ended) and a long diary (what the agent said, tool names, cost). The next day I open your run on my dashboard. What do I see?

Options.

• A. Both files pushed, as today: I read the card and the diary, an agent on my machine can too, a wiped laptop loses nothing. About 5 MB every six weeks.
• B. Card only pushed: the diary stays on your laptop, in a folder git ignores. My run page is empty, and a wiped laptop loses its diaries for good, which is the bug that made us commit the archives in the first place.
• C. Both pushed, diary trimmed: like A, the start prompt written once per run instead of once per leg. Two thirds of the largest files. A fix on the writer, not on the skill.

🤖 recommended: A now, C as a later cleanup.
👤 I picked: A.

---

Q3, the email in the path

Story. Each run sits in a folder named after the person's git email, agents/<email>/<id>.json, on a public repo. The folder was made so two machines never write the same file name. But a file name is the run's start time to the millisecond, so there is no collision to prevent. The folder only groups the runs by person. The same email is the author of every commit on the branch, so the folder shows nothing new.

Options.

• A. Keep the email folder: nothing moves, grouping stays visible in a file listing.
• B. One flat folder, agents/<id>.json, the person written inside the card: simpler reader, one file move in the cutover we do anyway.
• C. Folder by git user name: same shape, a name instead of an address, two people can share a name.

🤖 recommended: B. The folder protects nothing and the flat reader is simpler.
👤 I picked: A. It is your design, the gain from B is small, and the email is on the commits anyway. The skill's DECISIONS.md says in one line that the folder groups and does not protect. If you prefer B, now is the free moment, since the files move in the cutover anyway. The card keeps the machine name and the disk path, the dashboard and the continue use them.

---

Q4, the command and the SKILL.md

Story. The agent has logs on its PATH like tickets and queue. Four commands: logs, logs --ticket <file>, logs --branch <name>, logs show <id>. The question is when the agent is told to look back.

Options.

• 1. The skill says when: one rule in the SKILL.md, "before you plan or work a ticket, read its runs; a stopped or failed run tells you what to avoid". Same shape as the claim rule in the tickets skill. One lookup per run, about a second. Works in every product that loads the skill.
• 2. Only the command: the SKILL.md lists the commands, our presets decide when to look. Outside our daemon nobody ever reads the logs.

🤖 recommended: 1.
👤 I picked: 1.

And what show prints:

• Card plus what the agent said, its result, its ending, its cost.
• Card plus the whole diary, up to 155 KB.
• Card only.

🤖 recommended: card plus what the agent said. An agent cannot read 155 KB whole; the raw diary is for the dashboard.
👤 I picked: the same.

---

Q5, who owns the card's shape

Story. The card today is the framework's type, 25 fields, with names like cloudAnchor and mergeOutcome that mean nothing outside our product. Someone installs the skill in another repo and their agent runs logs show. If the skill reads those fields, their product has to write them too. And you would see our product's insides in a package sold as standalone.

Options.

• A. A small card owned by the skill: eleven plain fields (id, start and end time, status, intent, driver, model, branch, PR, ticket, cost). The daemon keeps its bookkeeping under one key of its own in the same file, caller, and reads one level deeper. Same for the diary: the skill knows four kinds of line (what the agent said, its result, its ending, its cost) and skips every other kind the daemon writes.
• B. The card is opaque to the skill: it only stores and lists files. Then logs --ticket and show are impossible. Died with Q1.
• C. The skill owns all 25 fields, renamed: everything moves, the dashboard follows every rename, and framework-only fields stay inside a standalone skill.

🤖 recommended: A. The only shape that is standalone and still does what Q1 needs. Under today's semver rule those eleven fields are the public API of the branch, so they stay few.
👤 I picked: A.

---

🤖 curated · Fable 5.1 — the stories and the recommendations are the agent's, told to me while I decided; the picks are mine.

[suleimansh]

Done in #1771, closing.