@pmelab/gtd 3.4.0 → 3.5.0

package/dist/gtd.bundle.mjs

@@ -191766,6 +191766,40 @@ const renderStateTemplate = (template, context) => eta.renderString(template, co
 */
 const EMPTY_TREE$1 = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
 const subjectOf$1 = (message) => (message.split("\n")[0] ?? "").trim();
+const COST_TRAILER_PREFIX = "Gtd-Cost: ";
+const COST_TRAILER_RE = /^Gtd-Cost:[ \t]*([0-9]+(?:\.[0-9]+)?)(?:[ \t]+(.+?))?[ \t]*$/gm;
+/** The bucket a cost with no `--model` tag is grouped under, kept distinct so a mixed history still totals correctly. */
+const UNATTRIBUTED_MODEL = "unspecified";
+/**
+* Append a `Gtd-Cost: <cost>[ <model>]` trailer (after a blank line) to a
+* commit `subject`, or return the subject unchanged when no cost was supplied.
+* The subject (first line) is never touched, so `parseStateSubject`/
+* `resolveState` still read `gtd(<actor>): <state>` back exactly as before.
+*/
+const withCostTrailer = (subject, cost, model) => cost === void 0 ? subject : `${subject}\n\n${COST_TRAILER_PREFIX}${cost}${model !== void 0 ? ` ${model}` : ""}`;
+/** Every `Gtd-Cost:` entry found across the given commit messages (each entry's model defaults to `UNATTRIBUTED_MODEL`). */
+const parseCostTrailers = (messages) => {
+	const entries = [];
+	for (const message of messages) for (const match of message.matchAll(COST_TRAILER_RE)) {
+		const model = match[2]?.trim();
+		entries.push({
+			cost: Number(match[1]),
+			model: model !== void 0 && model !== "" ? model : UNATTRIBUTED_MODEL
+		});
+	}
+	return entries;
+};
+/** The total token cost across the given entries (`0` when none). */
+const totalCostOf = (entries) => entries.reduce((sum, entry) => sum + entry.cost, 0);
+/** Per-model token totals, highest-cost first (ties broken by model name for a stable order). */
+const costByModel = (entries) => {
+	const byModel = /* @__PURE__ */ new Map();
+	for (const entry of entries) byModel.set(entry.model, (byModel.get(entry.model) ?? 0) + entry.cost);
+	return [...byModel.entries()].map(([model, cost]) => ({
+		model,
+		cost
+	})).sort((a, b) => b.cost - a.cost || a.model.localeCompare(b.model));
+};
 /** Collapse an arbitrary git status letter to the pattern grammar's closed `A|M|D` set (mirrors the plan's decision 5 — only those three are meaningful statuses). */
 const normalizeStatus = (raw) => raw === "A" ? "A" : raw === "D" ? "D" : "M";
 /** Resolve HEAD's subject against the active workflow definition (the bundled default, or a compiled `.gtdrc` `workflow:` key). */
@@ -191810,7 +191844,8 @@ const computeProcessRun = (git, def) => gen(function* () {
 	if (!(yield* git.hasCommits())) return {
 		startHash: "",
 		startParentHash: EMPTY_TREE$1,
-		trace: []
+		trace: [],
+		costEntries: []
 	};
 	const initialState = initialStateOf(def);
 	const history = yield* git.commitHistory();
@@ -191821,12 +191856,15 @@ const computeProcessRun = (git, def) => gen(function* () {
 		i--;
 	}
 	const startIdx = i + 1;
-	const trace = history.slice(startIdx).map((h) => parseStateSubject(subjectOf$1(h.message)).state);
+	const processCommits = history.slice(startIdx);
+	const trace = processCommits.map((h) => parseStateSubject(subjectOf$1(h.message)).state);
+	const costEntries = parseCostTrailers(processCommits.map((h) => h.message));
 	const startParentHash = i >= 0 ? history[i].hash : EMPTY_TREE$1;
 	return {
 		startHash: startIdx < history.length ? history[startIdx].hash : history[history.length - 1].hash,
 		startParentHash,
-		trace
+		trace,
+		costEntries
 	};
 });
 /** The `GTD_VAR_`-prefix stripped, exact-case, from every matching entry — the highest-precedence `it.vars` layer. A `value === undefined` entry (a name declared-but-unset in the environment) is skipped, never coerced to the string `"undefined"`. */
@@ -191863,13 +191901,27 @@ const toTemplateEdges = (edges) => (edges ?? []).map(([pattern, target, describe
 	pattern,
 	target
 });
-/** Build the `PatternTemplates.TemplateContext` for rendering `state`'s content at the resolved rest. `vars` is the already-merged three-layer map (see `resolveVars`); `edges` is the resting state's own `on` edges (see `toTemplateEdges`). */
-const buildTemplateContext = (git, read, state, actor, run, vars, edges) => gen(function* () {
+/**
+* Build the `PatternTemplates.TemplateContext` for rendering `state`'s content
+* at the resolved rest. `vars` is the already-merged three-layer map (see
+* `resolveVars`); `edges` is the resting state's own `on` edges (see
+* `toTemplateEdges`). `currentCost`/`currentModel` are the in-flight step's own
+* `--cost`/`--model` (folded into the process's committed cost entries so a
+* `commit:` squash template sees the whole-process total AND per-model
+* breakdown including the squashing step) — `0`/absent for the pure emitters
+* (`gtd next`/`gtd status`), where no step is being performed.
+*/
+const buildTemplateContext = (git, read, state, actor, run, vars, edges, currentCost = 0, currentModel) => gen(function* () {
 	const hasCommits = yield* git.hasCommits();
 	const currentCommit = hasCommits ? yield* git.resolveRef("HEAD") : "";
 	const previousCommit = hasCommits ? yield* git.resolveRef("HEAD~1").pipe(catchAll(() => succeed$3(run.startParentHash))) : "";
 	const processDiff = [yield* git.diffRef(run.startParentHash).pipe(catchAll(() => succeed$3(""))), yield* git.diffHead().pipe(catchAll(() => succeed$3("")))].filter((d) => d.trim().length > 0).join("\n\n");
 	const lastDiff = run.trace.length > 0 ? yield* git.commitDiff(currentCommit).pipe(catchAll(() => succeed$3(""))) : "";
+	const stepEntry = currentCost > 0 || currentModel !== void 0 ? [{
+		cost: currentCost,
+		model: currentModel ?? "unspecified"
+	}] : [];
+	const allCostEntries = [...run.costEntries, ...stepEntry];
 	return {
 		startCommit: run.startHash,
 		currentCommit,
@@ -191878,6 +191930,8 @@ const buildTemplateContext = (git, read, state, actor, run, vars, edges) => gen(
 		actor,
 		processDiff,
 		lastDiff,
+		processCost: totalCostOf(allCostEntries),
+		processCostByModel: costByModel(allCostEntries),
 		read,
 		vars,
 		edges: toTemplateEdges(edges)
@@ -191945,18 +191999,22 @@ const renderRest = (rest, context) => gen(function* () {
 });
 /**
 * Execute a `PatternMachine.step` decision: a `"commit"` decision stages and
-* commits everything pending under the decided subject; a `"squash"`
-* decision renders the commit-state template against the PENDING tree — a
-* render failure REFUSES the step, touching nothing — then soft-resets to
-* the process's start parent, writes ONE commit with the rendered message
-* (via `commitAsIs`, so the still-uncommitted template file is excluded), and
-* discards everything left pending (the template file included). A `"noop"`
-* performs no IO.
-*/
-const executeDecision = (git, run, decision, context) => gen(function* () {
+* commits everything pending under the decided subject, with an optional
+* `Gtd-Cost: <cost>[ <model>]` trailer (the invocation's `--cost`/`--model`,
+* persisted in the git log); a `"squash"` decision renders the commit-state
+* template against the PENDING tree — a render failure REFUSES the step,
+* touching nothing — then soft-resets to the process's start parent, writes
+* ONE commit with the rendered message (via `commitAsIs`, so the
+* still-uncommitted template file is excluded), and discards everything left
+* pending (the template file included). A squash records no trailer of its own
+* — the whole-process total and per-model breakdown reach the message through
+* `it.processCost`/`it.processCostByModel` in the rendered template. A
+* `"noop"` performs no IO.
+*/
+const executeDecision = (git, run, decision, context, cost, model) => gen(function* () {
 	switch (decision.kind) {
 		case "commit":
-			yield* git.commitAllWithPrefix(decision.subject);
+			yield* git.commitAllWithPrefix(withCostTrailer(decision.subject, cost, model));
 			return {
 				kind: "commit",
 				subject: decision.subject
@@ -364727,6 +364785,8 @@ const buildFileModeMap = (def, vars, root) => {
 				actor: "",
 				processDiff: "",
 				lastDiff: "",
+				processCost: 0,
+				processCostByModel: [],
 				read: (path) => {
 					throw new Error(`"file:" is not readable while building the path→mode map (path: ${path})`);
 				},
@@ -364978,7 +365038,10 @@ const HELP_TEXT = `Usage: gtd [command] [options]
 Commands:
   step <actor>     Authenticate as <actor>, match the resolved rest's
                    declared patterns against the pending changes, and commit
-                   (or squash) the one resulting transition
+                   (or squash) the one resulting transition. Pass
+                   --cost=<n> (optionally --model=<name>) to record the
+                   just-finished invocation's token cost and model on the
+                   turn commit (summed into it.processCost/processCostByModel)
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   run              Execute the resolved rest's emitted script, then step its
@@ -364992,6 +365055,8 @@ Commands:
 
 Options:
   --json           Output structured JSON instead of plain text
+  --cost=<n>       (gtd step only) record the invocation's token cost
+  --model=<name>   (gtd step only, with --cost) tag that cost's model
   --version, -v    Print version and exit
   --help, -h       Print this help and exit
 `;
@@ -365007,6 +365072,58 @@ const markEnveloped = (error) => Object.assign(error, { [ENVELOPED]: true });
 const isEnveloped = (error) => typeof error === "object" && error !== null && error[ENVELOPED] === true;
 /** Non-flag positional arguments past the subcommand name (argv[3..]). */
 const commandArgs = (argv) => argv.slice(3).filter((a) => a.length > 0 && !a.startsWith("--"));
+const COST_FLAG = "--cost=";
+/**
+* Parse the optional `--cost=<n>` flag (only `gtd step` accepts it — see
+* `makeProgram`). `<n>` is the token cost of the invocation that produced the
+* pending changes, recorded as a `Gtd-Cost:` trailer on the turn commit. Must
+* be a non-negative finite number; a bare `--cost` (no `=`) or a non-numeric/
+* negative value is a usage error. Returns `undefined` when the flag is absent.
+*/
+const parseCostFlag = (argv) => {
+	if (argv.slice(2).includes("--cost")) return fail$2(/* @__PURE__ */ new Error("gtd: --cost requires a value — use --cost=<number>"));
+	const flag = argv.slice(2).find((a) => a.startsWith(COST_FLAG));
+	if (flag === void 0) return succeed$3(void 0);
+	const raw = flag.slice(7);
+	const n = Number(raw);
+	if (raw.trim() === "" || !Number.isFinite(n) || n < 0) return fail$2(/* @__PURE__ */ new Error(`gtd: --cost must be a non-negative number — got "${raw}"`));
+	return succeed$3(n);
+};
+const MODEL_FLAG = "--model=";
+/**
+* Parse the optional `--model=<name>` flag (only `gtd step`, and only
+* alongside `--cost` — see `makeProgram`). `<name>` tags the recorded cost
+* with the model the invocation ran on, appended to the `Gtd-Cost:` trailer
+* and grouped in `it.processCostByModel`. Must be non-empty and single-line
+* (it rides on one trailer line); a bare `--model` (no `=`) or an empty/
+* multiline value is a usage error. Returns `undefined` when the flag is absent.
+*/
+const parseModelFlag = (argv) => {
+	if (argv.slice(2).includes("--model")) return fail$2(/* @__PURE__ */ new Error("gtd: --model requires a value — use --model=<name>"));
+	const flag = argv.slice(2).find((a) => a.startsWith(MODEL_FLAG));
+	if (flag === void 0) return succeed$3(void 0);
+	const raw = flag.slice(8);
+	if (raw.trim() === "" || /[\r\n]/.test(raw)) return fail$2(/* @__PURE__ */ new Error("gtd: --model must be a non-empty, single-line value"));
+	return succeed$3(raw);
+};
+/**
+* Parse and validate the `--cost`/`--model` step flags together. Both are
+* orthogonal to `--json` but only meaningful to `gtd step` — rejected on any
+* other command rather than silently ignored (same discipline as `--json` on
+* `format`) — and `--model` requires `--cost` (a model tag with no token count
+* records nothing to sum).
+*/
+const parseStepFlags = (argv, positional) => gen(function* () {
+	const cost = yield* parseCostFlag(argv);
+	const model = yield* parseModelFlag(argv);
+	if (cost !== void 0 && positional !== "step") return yield* fail$2(/* @__PURE__ */ new Error("gtd: --cost is only valid for `gtd step`"));
+	if (model !== void 0 && positional !== "step") return yield* fail$2(/* @__PURE__ */ new Error("gtd: --model is only valid for `gtd step`"));
+	if (model !== void 0 && cost === void 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd: --model requires --cost — it tags the recorded cost with the model that ran"));
+	return {
+		cost,
+		model
+	};
+});
 /** Rejects extra positional arguments for a subcommand that takes none (`status`, `run`). */
 const rejectExtraArgs = (command, argv) => {
 	const args = commandArgs(argv);
@@ -365055,6 +365172,8 @@ const resolveRestContext = (git) => gen(function* () {
 		context: yield* buildTemplateContext(git, worktree.read, rest.state, rest.actor, run, vars, rest.stateDef.on)
 	};
 });
+/** The user-facing message for a `step` refusal — out-of-turn names the awaited actor, no-match names every declared pattern. */
+const formatStepRefusal = (invoker, refusal) => refusal.reason === "out-of-turn" ? `gtd step ${invoker}: out of turn — "${refusal.state}" awaits ${refusal.awaits}` : `gtd step ${invoker}: no declared pattern matches the pending changes at "${refusal.state}" — declared patterns: ${refusal.patterns.length > 0 ? refusal.patterns.join(", ") : "(none)"}`;
 /**
 * Authenticate `invoker` against the resolved rest and perform the one
 * resulting transition (commit or squash), shared by `gtd step` and
@@ -365063,7 +365182,7 @@ const resolveRestContext = (git) => gen(function* () {
 * `subject: null` rather than failing (exit zero, per the plan's "clean
 * no-op exits zero").
 */
-const stepAsActor = (invoker) => gen(function* () {
+const stepAsActor = (invoker, cost, model) => gen(function* () {
 	const git = yield* GitService;
 	const config = yield* ConfigService;
 	const worktree = yield* WorktreeReader;
@@ -365075,37 +365194,40 @@ const stepAsActor = (invoker) => gen(function* () {
 		changes,
 		processTrace: run.trace
 	});
-	if (decision.kind === "refusal") {
-		const message = decision.reason === "out-of-turn" ? `gtd step ${invoker}: out of turn — "${decision.state}" awaits ${decision.awaits}` : `gtd step ${invoker}: no declared pattern matches the pending changes at "${decision.state}" — declared patterns: ${decision.patterns.length > 0 ? decision.patterns.join(", ") : "(none)"}`;
-		return yield* fail$2(new Error(message));
-	}
+	if (decision.kind === "refusal") return yield* fail$2(new Error(formatStepRefusal(invoker, decision)));
 	if (decision.kind === "noop") return {
 		state: decision.state,
-		subject: null
+		subject: null,
+		cost: null,
+		model: null
 	};
 	const executable = decision;
 	const vars = resolveVars(config.workflowVars, config.rcVars, envVars.all);
 	const renderedState = decision.kind === "squash" ? decision.state : rest.state;
-	const outcome = yield* executeDecision(git, run, executable, yield* buildTemplateContext(git, worktree.read, renderedState, invoker, run, vars, rest.def.states[renderedState]?.on));
+	const outcome = yield* executeDecision(git, run, executable, yield* buildTemplateContext(git, worktree.read, renderedState, invoker, run, vars, rest.def.states[renderedState]?.on, cost ?? 0, model), cost, model);
 	return {
 		state: rest.state,
-		subject: outcome.kind === "noop" ? null : outcome.subject
+		subject: outcome.kind === "noop" ? null : outcome.subject,
+		cost: cost ?? null,
+		model: model ?? null
 	};
 });
 /** Renders `stepAsActor`'s result the same way for both `gtd step` and `gtd run`. */
 const reportStepResult = (result, json, write) => {
 	if (json) write(JSON.stringify({
 		state: result.state,
-		subject: result.subject
+		subject: result.subject,
+		...result.cost !== null ? { cost: result.cost } : {},
+		...result.model !== null ? { model: result.model } : {}
 	}) + "\n");
 	else write(result.subject !== null ? `committed: ${result.subject}\n` : `nothing to do at "${result.state}"\n`);
 };
-/** `gtd step <actor>`: authenticate as `<actor>` and perform the one resulting transition. */
-const runStepCommand = (argv, json, write) => gen(function* () {
+/** `gtd step <actor> [--cost=<n>] [--model=<name>]`: authenticate as `<actor>` and perform the one resulting transition, recording `--cost`/`--model` as a `Gtd-Cost:` trailer. */
+const runStepCommand = (argv, json, write, cost, model) => gen(function* () {
 	const args = commandArgs(argv);
 	if (args.length === 0) return yield* fail$2(/* @__PURE__ */ new Error("gtd step: missing actor argument"));
 	if (args.length > 1) return yield* fail$2(/* @__PURE__ */ new Error(`gtd step: too many arguments — expected one actor, got: ${args.join(", ")}`));
-	const result = yield* stepAsActor(args[0]);
+	const result = yield* stepAsActor(args[0], cost, model);
 	reportStepResult(result, json, write);
 });
 /** `gtd next [--json]`: pure emitter of the resolved rest's rendered content (no mutation). */
@@ -365164,8 +365286,21 @@ const computeStatusChanges = (onEdges, changes) => changes.map((change) => {
 		pattern: matchedRow?.[0] ?? null
 	};
 });
-/** `gtd status --json`'s emission — `{state, actor, changes, model?, memory?, file?, mode?}`. */
-const writeStatusJson = (write, rest, statusChanges, model, memory, file) => {
+/**
+* True when the per-model breakdown adds information beyond the `Cost:` total:
+* more than one model, or a single model that carries an actual `--model` tag
+* (a lone `unspecified` bucket just restates the total, so it's suppressed).
+*/
+const breakdownIsInformative = (byModel) => byModel.length > 1 || byModel.length === 1 && byModel[0].model !== "unspecified";
+/** The plain-text `Cost:` line(s) for `gtd status` — empty when nothing recorded, plus an indented per-model split when informative. */
+const costStatusLines = (cost, byModel) => {
+	if (cost <= 0) return [];
+	const lines = [`Cost: ${cost}`];
+	if (breakdownIsInformative(byModel)) for (const m of byModel) lines.push(`  ${m.model}: ${m.cost}`);
+	return lines;
+};
+/** `gtd status --json`'s emission — `{state, actor, changes, model?, memory?, file?, mode?, cost?, costByModel?, edges?}`. */
+const writeStatusJson = (write, rest, statusChanges, model, memory, file, cost, costByModel) => {
 	const edges = toTemplateEdges(rest.stateDef.on);
 	write(JSON.stringify({
 		state: rest.state,
@@ -365175,16 +365310,19 @@ const writeStatusJson = (write, rest, statusChanges, model, memory, file) => {
 		...memory !== void 0 ? { memory } : {},
 		...file !== void 0 ? { file } : {},
 		...rest.stateDef.mode !== void 0 ? { mode: rest.stateDef.mode } : {},
+		...cost > 0 ? { cost } : {},
+		...cost > 0 ? { costByModel } : {},
 		...edges.length > 0 ? { edges } : {}
 	}) + "\n");
 };
-/** `gtd status`'s plain-text emission — `State:`/`Awaits:`/`Model:`/`Memory:`/`File:`/`Mode:`/`Pending:` lines. */
-const writeStatusPlain = (write, rest, statusChanges, model, memory, file) => {
+/** `gtd status`'s plain-text emission — `State:`/`Awaits:`/`Model:`/`Memory:`/`File:`/`Mode:`/`Cost:`/`Pending:` lines. */
+const writeStatusPlain = (write, rest, statusChanges, model, memory, file, cost, costByModel) => {
 	const lines = [`State: ${rest.state}`, `Awaits: ${rest.actor}`];
 	if (model !== void 0) lines.push(`Model: ${model}`);
 	if (memory !== void 0) lines.push(`Memory: ${memory}`);
 	if (file !== void 0) lines.push(`File: ${file}`);
 	if (rest.stateDef.mode !== void 0) lines.push(`Mode: ${rest.stateDef.mode}`);
+	lines.push(...costStatusLines(cost, costByModel));
 	if (statusChanges.length === 0) lines.push("Pending: (clean)");
 	else {
 		lines.push("Pending:");
@@ -365202,8 +365340,8 @@ const runStatusCommand = (argv, json, write) => gen(function* () {
 	const memory = yield* renderMemory(rest.stateDef, context);
 	const file = yield* renderFile(rest.stateDef, context);
 	const statusChanges = computeStatusChanges(rest.stateDef.on ?? [], changes);
-	if (json) writeStatusJson(write, rest, statusChanges, model, memory, file);
-	else writeStatusPlain(write, rest, statusChanges, model, memory, file);
+	if (json) writeStatusJson(write, rest, statusChanges, model, memory, file, context.processCost, context.processCostByModel);
+	else writeStatusPlain(write, rest, statusChanges, model, memory, file, context.processCost, context.processCostByModel);
 });
 /**
 * `gtd mermaid`: pure emitter of the active workflow's SHAPE (not the
@@ -365269,9 +365407,9 @@ const assertRunningFromRepoRoot = (git, fs) => gen(function* () {
 	if ((yield* fs.realPath(topLevel)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd must be run from the repository root (${topLevel}); the current directory is ${process.cwd()}`));
 });
 /** Dispatches to the named `run*Command` handler for every known subcommand. */
-const dispatchKnownSubcommand = (sub, argv, json, write) => {
+const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 	switch (sub) {
-		case "step": return runStepCommand(argv, json, write);
+		case "step": return runStepCommand(argv, json, write, cost, model);
 		case "next": return runNextCommand(json, write);
 		case "run": return runRunCommand(argv, json, write);
 		case "status": return runStatusCommand(argv, json, write);
@@ -365299,8 +365437,9 @@ function makeProgram(opts = {}) {
 	const positional = argv.slice(2).find((a) => !a.startsWith("--"));
 	return gen(function* () {
 		if (runVersionOrHelp(argv, write)) return;
-		const unknownOption = argv.slice(2).find((a) => a.startsWith("--") && a !== "--json");
+		const unknownOption = argv.slice(2).find((a) => a.startsWith("--") && a !== "--json" && a !== "--cost" && a !== "--model" && !a.startsWith(COST_FLAG) && !a.startsWith(MODEL_FLAG));
 		if (unknownOption !== void 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd: unknown option '${unknownOption}' — see \`gtd --help\``));
+		const { cost, model } = yield* parseStepFlags(argv, positional);
 		if (positional === "format") return yield* runFormatCommand(argv, json);
 		if (positional === "lsp") return yield* runLspCommand(argv, json);
 		const sub = yield* requireKnownSubcommand(positional, json, write);
@@ -365309,7 +365448,7 @@ function makeProgram(opts = {}) {
 		yield* assertRunningFromRepoRoot(git, fs);
 		yield* closeReviewWindow;
 		yield* (yield* ConfigInit).ensure;
-		const outcome = yield* either(dispatchKnownSubcommand(sub, argv, json, write));
+		const outcome = yield* either(dispatchKnownSubcommand(sub, argv, json, write, cost, model));
 		const rearm = yield* either(openReviewWindow);
 		if (isLeft(outcome)) return yield* fail$2(outcome.left);
 		if (isLeft(rearm)) return yield* fail$2(rearm.left);

package/docs/cli.md

@@ -6,7 +6,10 @@ Usage: gtd [command] [options]
 Commands:
   step <actor>     Authenticate as <actor>, match the resolved rest's
                    declared patterns against the pending changes, and commit
-                   (or squash) the one resulting transition
+                   (or squash) the one resulting transition. Pass
+                   --cost=<n> (optionally --model=<name>) to record the
+                   just-finished invocation's token cost and model on the
+                   turn commit (summed into it.processCost/processCostByModel)
   next             Print the resolved rest's rendered script/prompt/message
                    (no mutation)
   run              Execute the resolved rest's emitted script, then step its
@@ -20,6 +23,8 @@ Commands:
 
 Options:
   --json           Output structured JSON instead of plain text
+  --cost=<n>       (gtd step only) record the invocation's token cost
+  --model=<name>   (gtd step only, with --cost) tag that cost's model
   --version, -v    Print version and exit
   --help, -h       Print this help and exit
 ```
@@ -32,11 +37,15 @@ without touching the repository. Every other command must be run from the
 history relative to cwd, so it refuses with a clear error if invoked from a
 subdirectory.
 
-`--json` is the only long option. Any other `--` option (including a typo like
-`--jsn`) is rejected with a usage error rather than silently ignored, so a
-mistyped flag can never degrade a JSON caller to plain-text mode.
+`--json`, `--cost=<n>`, and `--model=<name>` (the latter two only for
+`gtd step`) are the only long options. Any other `--` option (including a typo
+like `--jsn`) is rejected with a usage error rather than silently ignored, so a
+mistyped flag can never degrade a JSON caller to plain-text mode. A bare
+`--cost`/`--model` with no value, a non-numeric or negative `--cost`, an empty
+`--model`, `--model` without `--cost`, or either flag on any command other than
+`gtd step` are all usage errors.
 
-## `gtd step <actor>`
+## `gtd step <actor> [--cost=<n>] [--model=<name>]`
 
 Authenticates `<actor>` against the resolved rest and performs the ONE resulting
 transition. Unlike v2, there is no fixpoint chain to drive: the pattern
@@ -45,6 +54,16 @@ authors at most one commit (a normal turn) or performs one squash
 (§[STATES.md](../STATES.md#8-the-squash-lifecycle)) — never both, never a chain
 of several. A caller that wants several transitions issues several invocations.
 
+`--cost=<n>` records the token cost of the invocation that produced the pending
+changes (a non-negative number), and the optional `--model=<name>` tags it with
+the model that ran, as a `Gtd-Cost: <n> <model>` trailer on the turn commit —
+persisted in the git log, summed across the process into `it.processCost` and
+grouped by model into `it.processCostByModel` (see
+[Configuration: Token cost](configuration.md#token-cost)). `--model` requires
+`--cost`. On a squash they are folded into the process total/breakdown the
+`commit:` template renders rather than written as a trailer. Both are orthogonal
+to `--json`.
+
 - **Out-of-turn refusal** — `<actor>` isn't the resolved state's declared actor:
   exit non-zero, zero commits.
   `gtd step <actor>: out of turn — "<state>" awaits <awaited-actor>`
@@ -69,10 +88,17 @@ or, at a no-op:
 nothing to do at "idle"
 ```
 
-`--json` emits `{state, subject}` — `subject` is `null` at a no-op:
+`--json` emits `{state, subject}` — `subject` is `null` at a no-op — plus
+`cost`/`model` keys echoing what `--cost`/`--model` recorded (each omitted when
+not passed):
 
 ```json
-{ "state": "grilling", "subject": "gtd(human): grilling" }
+{
+  "state": "grilling",
+  "subject": "gtd(human): grilling",
+  "cost": 1450,
+  "model": "claude-opus-4-8"
+}
 ```
 
 ## `gtd next [--json]`
@@ -171,15 +197,21 @@ Pending:
 or, on a clean tree: `Pending: (clean)`. A `Model: <value>` line appears right
 after `Awaits:` when the resolved state declares a `model:` hint, and
 `Memory: <value>`/`File: <value>`/`Mode: <value>` lines appear after that (in
-that order) when declared — each independently, only when set.
+that order) when declared — each independently, only when set. A `Cost: <n>`
+line appears after those when the current process has accumulated any
+`Gtd-Cost:` (see [`gtd step --cost`](#gtd-step-actor---costn-model-name)),
+omitted when the running total is `0`; when the breakdown adds information (more
+than one model, or a single tagged model), indented `  <model>: <cost>` lines
+follow it.
 
 `--json` emits
-`{state, actor, changes: [{status, path, pattern}], model?, memory?, file?, mode?, edges?}`
+`{state, actor, changes: [{status, path, pattern}], model?, memory?, file?, mode?, cost?, costByModel?, edges?}`
 — `pattern` is `null` when no declared row matches that change;
 `model`/`memory`/`file`/`mode` are present only when the resolved state declares
-them (omitted entirely, never `null`, otherwise); `edges` is the resting state's
-`on` edges as `[{ pattern, target, describe? }]` (same as `gtd next --json`),
-omitted when the state has no `on`:
+them; `cost`/`costByModel` (the `[{model, cost}]` breakdown) only when the
+running process total is above `0`; and `edges` is the resting state's `on`
+edges as `[{ pattern, target, describe? }]` (same as `gtd next --json`), omitted
+when the state has no `on` (all omitted entirely, never `null`, otherwise):
 
 ```json
 {

package/docs/configuration.md

@@ -322,17 +322,66 @@ head is preserved under `refs/gtd/review-head` (the base under
 Every `script`/`prompt`/`message`/`commit`/`model`/`memory`/`file` template is
 rendered as an Eta template (`it.<name>`) with:
 
-| Variable         | Meaning                                                                                                                                                                                                                                 |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `startCommit`    | The hash the current process started from (before its first turn).                                                                                                                                                                      |
-| `currentCommit`  | HEAD's hash at render time.                                                                                                                                                                                                             |
-| `previousCommit` | The hash before the last transition (HEAD's parent, in-process).                                                                                                                                                                        |
-| `state`          | The state whose content is being rendered.                                                                                                                                                                                              |
-| `actor`          | The actor this render is for.                                                                                                                                                                                                           |
-| `processDiff`    | `startCommit..HEAD` plus the pending working-tree diff.                                                                                                                                                                                 |
-| `lastDiff`       | The diff of the last transition alone.                                                                                                                                                                                                  |
-| `read(path)`     | Reads a working-tree file (pending contents, not HEAD's) by repo-relative path. Throws for a missing/unreadable path — for a `commit:` template, that throw refuses the step (see [STATES.md §8](../STATES.md#8-the-squash-lifecycle)). |
-| `vars`           | The merged three-layer variable map, always a flat `Record<string, string>` — see ["Variables"](#variables) below.                                                                                                                      |
+| Variable             | Meaning                                                                                                                                                                                                                                                                                                                                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `startCommit`        | The hash the current process started from (before its first turn).                                                                                                                                                                                                                                                                         |
+| `currentCommit`      | HEAD's hash at render time.                                                                                                                                                                                                                                                                                                                |
+| `previousCommit`     | The hash before the last transition (HEAD's parent, in-process).                                                                                                                                                                                                                                                                           |
+| `state`              | The state whose content is being rendered.                                                                                                                                                                                                                                                                                                 |
+| `actor`              | The actor this render is for.                                                                                                                                                                                                                                                                                                              |
+| `processDiff`        | `startCommit..HEAD` plus the pending working-tree diff.                                                                                                                                                                                                                                                                                    |
+| `lastDiff`           | The diff of the last transition alone.                                                                                                                                                                                                                                                                                                     |
+| `processCost`        | The accumulated token cost of the current process — the sum of every `Gtd-Cost:` trailer recorded by `gtd step <actor> --cost=<n>` across its turn commits, plus the in-flight step's own `--cost` (so a `commit:` squash template sees the whole-process total). A number, `0` when none recorded. See ["Token cost"](#token-cost).       |
+| `processCostByModel` | The same accumulated cost broken down per model: an array of `{ model, cost }`, highest-cost first, one entry per distinct `--model` tag (costs recorded with no `--model` group under `"unspecified"`). A squash template iterates it to itemize the feature's cost per model. Empty when none recorded. See ["Token cost"](#token-cost). |
+| `read(path)`         | Reads a working-tree file (pending contents, not HEAD's) by repo-relative path. Throws for a missing/unreadable path — for a `commit:` template, that throw refuses the step (see [STATES.md §8](../STATES.md#8-the-squash-lifecycle)).                                                                                                    |
+| `vars`               | The merged three-layer variable map, always a flat `Record<string, string>` — see ["Variables"](#variables) below.                                                                                                                                                                                                                         |
+
+### Token cost
+
+A loop driver that knows how many tokens the invocation it just drove cost — and
+on which model — can record both with
+`gtd step <actor> --cost=<n> [--model=<name>]` (`<n>` a non-negative number).
+gtd appends them to that turn's commit as a `Gtd-Cost: <n> <model>` trailer — a
+blank line then the trailer, below the untouched `gtd(<actor>): <state>` subject
+— so the per-turn cost and model are persisted in the git log:
+
+```
+gtd(agent): reviewing
+
+Gtd-Cost: 1450 claude-opus-4-8
+```
+
+`--model` is optional and requires `--cost` (a model tag with no token count
+records nothing to sum); a cost recorded without a model is grouped under
+`"unspecified"`. `gtd status` shows the process's running total and, when the
+breakdown adds information, a per-model split (a `Cost:` line with indented
+`<model>: <cost>` lines / a `cost` number and a `costByModel` array, omitted
+when nothing has been recorded). `gtd step --json` echoes what it recorded
+(`{ "state": …, "subject": …, "cost": 1450, "model": "claude-opus-4-8" }`).
+
+Every template sees the running total as `it.processCost` and the per-model
+breakdown as `it.processCostByModel` (the table above): the current process's
+turn-commit entries, plus the in-flight step's own `--cost`/`--model`. Their
+intended use is a `commit:` squash template, which renders against the pending
+tree as the process collapses — so the whole feature's total AND its per-model
+itemization (including the squashing step itself) land in the squash message
+even though the intermediate per-turn trailers are discarded with the turns they
+rode on:
+
+```yaml
+done:
+  commit: |
+    feat: ship it
+
+    Total token cost: <%= it.processCost %>
+    <% it.processCostByModel.forEach(function(m){ %>
+    - <%= m.model %>: <%= m.cost %>
+    <% }) %>
+```
+
+`--cost`/`--model` are accepted only by `gtd step` (a usage error on any other
+command), and gtd never interprets the number's unit (tokens, cents, whatever
+the driver records) or the model name — it only records, sums, and groups them.
 
 ## Variables
 

package/docs/examples/advanced-workflow.md

@@ -405,9 +405,25 @@ workflow:
         "M .gtd/COMMIT_MSG.md": done
 
     done:
-      commit: '<%~ it.read(".gtd/COMMIT_MSG.md") %>'
+      commit: |
+        <%~ it.read(".gtd/COMMIT_MSG.md") %>
+
+        Token cost: <%= it.processCost %>
+        <% it.processCostByModel.forEach(function(m){ %>
+        - <%= m.model %>: <%= m.cost %>
+        <% }) %>
 ````
 
+The `done` commit appends a token-cost summary to the squashed message: if the
+loop driving this workflow passes `gtd step <actor> --cost=<n> --model=<name>`
+after each agent turn, `it.processCost` is the summed cost of the whole cycle
+(including the `squashing` step itself) and `it.processCostByModel` itemizes it
+per model — so the single squash commit records the feature's complete cost,
+broken down by which model spent what, even though the per-turn trailers are
+discarded with the turns they collapsed. Drop these lines if your driver doesn't
+track cost — `it.processCost` is `0` and `it.processCostByModel` empty then. See
+[Configuration: Token cost](../configuration.md#token-cost).
+
 A clean `gtd step human` at `grilling-answer`/`architecting-answer` (the `C`
 event) accepts the current phase's draft and moves on; any other pending change
 loops back for another round. `picking` is a `script` state whose only job is to

package/docs/loop.md

@@ -5,7 +5,10 @@ gtd (v3, the pattern machine) exposes three commands a loop driver combines:
 - **`gtd step <actor>`** — authenticate as `<actor>`, match the resolved rest's
   declared patterns against the pending changes, and commit (or squash) the one
   resulting transition. Performs AT MOST one transition — there is no fixpoint
-  chain to drive.
+  chain to drive. Pass `--cost=<n>` (optionally `--model=<name>`) to record the
+  just-finished invocation's token cost and model on the turn commit; gtd sums
+  them across the process into `it.processCost`/`it.processCostByModel` (see
+  [Configuration: Token cost](configuration.md#token-cost)).
 - **`gtd next`** — print the resolved rest's rendered script/prompt/message,
   without mutating anything.
 - **`gtd run`** — execute the resolved rest's emitted script (only for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {