diff --git a/docs/USAGE.md b/docs/USAGE.md index d64edd0d..62ccafa3 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -104,7 +104,7 @@ To compare a model, an effort or a setting on real Objectives, run some Objectiv ## What you see on the issue -While a job runs, one comment on the issue (edited in place, one per run) reads at a glance, in the finish card's look. Its first line names the state (⏳ running, ✅ delivered, ⛔ Blocked, ❓ has a Question, ⏸️ paused or waiting, ⏹️ stopped), the stage, its PR (or the issue), how long it has run and its cost in dollars and cents; the second line gives its times, what the dollars are (API-equivalent, not billed; billed to your API key; Copilot AI credits, billed to your seat) and its AI runs of unknown cost, never counted as $0. A Blocked, Question, paused or waiting stage has a "What to do" line under it, with the reason or the question. The table has one row per kind of step (Set up, Built the change, Waited for CI, Fixed CI, Flake check, Reviewed the change, Answered N review comments, Checked the answers, AI judge calls) in order of its first time, ×N for repeats, how long it took and its own cost; a CI loop of any length stays three rows. Took comes only from recorded starts and ends (an AI run's record, a wait's own start and end), and — means no AI ran in that step. While the stage runs, its last row says which step is in progress (none between steps): a wait in progress is that row alone, and its finished row once it ends. A send-back's rebase names itself a Rebase from its first write. An AI run's cost shows in its own row and the headline as soon as the run ends; at the end, a Total row and a collapsed timeline chart. Times are in the Objective's zone ([INSTALL.md](INSTALL.md#time-zone), Time zone), with dates only when a run crosses midnight. A collapsed **Run details** block holds the run, the agent and models, the session, the AI judge's verdicts, what the unknown-cost runs are, and the **Full log**: the stage's header and every line with its clock (setup, install, harness, each validation pass, reviewer, answer pass, exit), as the scorecard reads them. The marker lines (harness, spend, ledger, findings) follow it, unchanged. Near GitHub's comment size limit the chart goes first, then the Step cells shorten, then Run details' explanations, then the ledger line's cut form; the Full log's middle lines go only when GitHub would refuse the comment otherwise. A cloud sandbox stage's vendor comment has the same two-line headline over its line. The review starts while the PR's first required-check run is still going: its reviewer line then ends `beside the required checks on `, and a later line says when the checks ended (`... while the reviewer runs`) or that the stage waits for them after the reviewer. The last row's live status comes from the harness's own event stream, not from its prose: elapsed minutes, turns, tool calls, the sub-agents running and what each was asked to do, when the last event arrived, tokens so far, the last tool it ran. Silence alone kills no harness. Pendulum checks a running harness every 30 minutes, and one that printed nothing across such a window is killed as hung, and retried once, only when its own state says so. With a command open in its stream, it is hung when no command process of the run used CPU or read or wrote a byte, counted from when Pendulum first finds them. A command process is any process the harness started that does not write its stream and is not a helper from the harness's own install directory, so a background server left from an earlier command counts too; a long build, test or download that prints nothing goes on until the wall clock. With none open, the harness is waiting on its model: Claude Code and Copilot print the answer as it arrives (Pendulum runs them with `--include-partial-messages` and `--stream on`, and keeps those lines out of the events file), so one silent for the window has a stalled model stream and is hung. Codex prints no such lines and ends a stalled model stream itself (its `stream_idle_timeout_ms`, then its retries), so its silence with nothing open decides nothing. Work outside the harness's own processes (a Docker daemon's containers, a daemon started before the run, a remote build) counts as no progress, and so does a command that waits on purpose. On macOS Pendulum reads no I/O counts, so an open command there is judged by its CPU alone. Whatever Pendulum cannot read decides nothing. The line says so when a harness is killed. The labels (`pendulum:running`, `pendulum:in-review`, `pendulum:blocked`, `pendulum:question`) and the board column are the state; the plan comment is the harness's own checklist, ticked as it goes; the PR carries the validation marker (or, while its first required-check run goes on beside the review, the hand-off marker) and the review. +While a job runs, one comment on the issue (edited in place, one per run) reads at a glance, in the finish card's look. Its first line names the state (⏳ running, ✅ delivered, ⛔ Blocked, ❓ has a Question, ⏸️ paused or waiting, ⏹️ stopped), the stage, its PR (or the issue), how long it has run and its cost in dollars and cents; the second line gives its times, what the dollars are (API-equivalent, not billed; billed to your API key; Copilot AI credits, billed to your seat) and its AI runs of unknown cost, never counted as $0. A Blocked, Question, paused or waiting stage has a "What to do" line under it, with the reason or the question. The table has the stage's steps in time order (Set up, Built the change, Waited for CI, Fixed CI, Flake check, Reviewed the change, Answered N review comments, Checked the answers), each with how long it took and its own cost. Consecutive steps of one kind fold into one row, ×N for repeats; a step after a step of another kind is a row of its own, so a CI loop is a row per wait and a row per fix. A CI wait that goes on past the reviewer stays one row. The AI judge calls have one row. Took comes only from recorded starts and ends (an AI run's record; a CI wait's from the start of the validation pass that waits to the checks' result), and — means no AI ran in that step. While the stage runs, its last row says which step is in progress (none between steps): a wait in progress is that row alone, and its finished row once it ends. A send-back's rebase names itself a Rebase from its first write. An AI run's cost shows in its own row and the headline as soon as the run ends; at the end, a Total row and a collapsed timeline chart: one section per table row that took a recorded time, in the table's order and named as its row (a CI wait's with how it ended, `CI · passed` or `CI · red`; a name that repeats is numbered, `CI 1 · red`), AI runs amber with their duration and cost, waits and other steps grey with their duration, a CI wait that ended red in red. Times are in the Objective's zone ([INSTALL.md](INSTALL.md#time-zone), Time zone), with dates only when a run crosses midnight. A collapsed **Run details** block holds the run, the agent and models, the session, the AI judge's verdicts, what the unknown-cost runs are, and the **Full log**: the stage's header and every line with its clock (setup, install, harness, each validation pass, reviewer, answer pass, exit), as the scorecard reads them. The marker lines (harness, spend, ledger, findings) follow it, unchanged. Near GitHub's comment size limit the chart goes first, then the Step cells shorten, then Run details' explanations, then the ledger line's cut form; the Full log's middle lines go only when GitHub would refuse the comment otherwise. A cloud sandbox stage's vendor comment has the same two-line headline over its line. The review starts while the PR's first required-check run is still going: its reviewer line then ends `beside the required checks on `, and a later line says when the checks ended (`... while the reviewer runs`) or that the stage waits for them after the reviewer. The last row's live status comes from the harness's own event stream, not from its prose: elapsed minutes, turns, tool calls, the sub-agents running and what each was asked to do, when the last event arrived, tokens so far, the last tool it ran. Silence alone kills no harness. Pendulum checks a running harness every 30 minutes, and one that printed nothing across such a window is killed as hung, and retried once, only when its own state says so. With a command open in its stream, it is hung when no command process of the run used CPU or read or wrote a byte, counted from when Pendulum first finds them. A command process is any process the harness started that does not write its stream and is not a helper from the harness's own install directory, so a background server left from an earlier command counts too; a long build, test or download that prints nothing goes on until the wall clock. With none open, the harness is waiting on its model: Claude Code and Copilot print the answer as it arrives (Pendulum runs them with `--include-partial-messages` and `--stream on`, and keeps those lines out of the events file), so one silent for the window has a stalled model stream and is hung. Codex prints no such lines and ends a stalled model stream itself (its `stream_idle_timeout_ms`, then its retries), so its silence with nothing open decides nothing. Work outside the harness's own processes (a Docker daemon's containers, a daemon started before the run, a remote build) counts as no progress, and so does a command that waits on purpose. On macOS Pendulum reads no I/O counts, so an open command there is judged by its CPU alone. Whatever Pendulum cannot read decides nothing. The line says so when a harness is killed. The labels (`pendulum:running`, `pendulum:in-review`, `pendulum:blocked`, `pendulum:question`) and the board column are the state; the plan comment is the harness's own checklist, ticked as it goes; the PR carries the validation marker (or, while its first required-check run goes on beside the review, the hand-off marker) and the review. ## An Objective's lifecycle diff --git a/plugin/scripts/lib/card-kit.mjs b/plugin/scripts/lib/card-kit.mjs index 065900e6..ebd8c5ef 100644 --- a/plugin/scripts/lib/card-kit.mjs +++ b/plugin/scripts/lib/card-kit.mjs @@ -244,7 +244,7 @@ export function causeSentences(counts = []) { export const AGENTS = Object.freeze({ claude: "Claude Code", codex: "Codex", copilot: "Copilot" }); /** The timeline's theme: the cards' gantt colours, with a grey for time on hold and a red for a Blocked or Question end. */ -export const ganttTheme = (leftPadding = 80) => ({ ...GANTT_THEME, themeVariables: { ...GANTT_THEME.themeVariables, doneTaskBkgColor: "#8b949e", doneTaskBorderColor: "#6e7781", critBkgColor: "#b3402a", critBorderColor: "#7a2a1c" }, gantt: { ...GANTT_THEME.gantt, leftPadding } }); +export const ganttTheme = (leftPadding = 80, width = null) => ({ ...GANTT_THEME, themeVariables: { ...GANTT_THEME.themeVariables, doneTaskBkgColor: "#8b949e", doneTaskBorderColor: "#6e7781", critBkgColor: "#b3402a", critBorderColor: "#7a2a1c" }, gantt: { ...GANTT_THEME.gantt, ...(width ? { useWidth: width } : {}), leftPadding } }); /** The tick for a time span: about five ticks across. */ export function tickFor(span) { const steps = [["1minute", 6e4], ["2minute", 12e4], ["5minute", 3e5], ["10minute", 6e5], ["15minute", 9e5], ["30minute", 18e5], ["1hour", 36e5], ["2hour", 72e5], ["6hour", 216e5], ["12hour", 432e5], ["1day", 864e5], ["1week", 6048e5]]; @@ -255,9 +255,10 @@ const isoSecond = (t) => new Date(t).toISOString().slice(0, 19); * A Mermaid gantt (pure) over `rows` ({section, bars: [{start, end, tag, label?}]}, ms; `tag` active, crit or done), in * `zone`'s wall time: a section name that repeats is numbered ("Review 1", "Review 2"), since Mermaid merges sections of * one name and would put the names beside the wrong bars. Each bar's label is its duration, then its own words. - * `days`: the axis carries dates. Null with no bar. + * `days`: the axis carries dates; `leftPadding`: the room for the section names; `width`: the chart's own, when it + * needs more than the theme's. Null with no bar. */ -export function ganttChart(rows, { zone, days = false, leftPadding = 80 }) { +export function ganttChart(rows, { zone, days = false, leftPadding = 80, width = null }) { const bars = rows.flatMap((r) => r.bars); if (!bars.length) return null; const from = Math.min(...bars.map((b) => b.start)); @@ -277,7 +278,7 @@ export function ganttChart(rows, { zone, days = false, leftPadding = 80 }) { lines.push(` ${durationShort(end - b.start)}${b.label ? ` ${mermaidLabel(b.label, 20)}` : ""} :${b.tag || "active"}, ${isoSecond(b.start + shift)}, ${isoSecond(end + shift)}`); } } - return ["```mermaid", mermaidInit(ganttTheme(leftPadding)), ...lines, "```"].join("\n"); + return ["```mermaid", mermaidInit(ganttTheme(leftPadding, width)), ...lines, "```"].join("\n"); } /** Text inside a Mermaid quoted string: one line, no quotes, at most 60 characters. */ diff --git a/plugin/scripts/lib/progress-card.mjs b/plugin/scripts/lib/progress-card.mjs index 03706479..446d6326 100644 --- a/plugin/scripts/lib/progress-card.mjs +++ b/plugin/scripts/lib/progress-card.mjs @@ -3,10 +3,12 @@ // stepOf each line's step, as the stage wrote it (`{step, ...fields}`), its fields checked and kept; the card // decides on those fields and on the passes' labels, never on a line's words. A step object the stage // keeps may get its end (`end`) and its result (`outcome`) later: they are read at each write; -// progressData the steps as rows, one per kind of step in order of first occurrence, ×N for repeats; each row's -// Took from recorded starts and ends only (an AI run's record; a wait's own start and end), its cost -// from the AI runs that ended in it; the AI judge calls in a row of their own. The table and the -// timeline chart read this one data; +// progressData the steps as rows in time order: consecutive steps of one kind fold into one row, ×N for repeats, +// and a step written after a step of another kind is a row of its own (a CI loop is a row per wait +// and a row per fix); each row's +// Took from recorded starts and ends only (an AI run's record; a wait's own span, from the line that +// began its round to its end), its cost from the AI runs that ended in it; the AI judge calls in a row +// of their own. The table and the timeline chart read this one data; // progressCard the markdown: the two-line headline, the action line, the table, the timeline chart, Run details. // Run details ends with the Full log: the comment as every reader reads it (session.mjs progressReporter writes it there // byte for byte: its header, its `-