dorfl 0.1.1 → 0.2.0

package/src/watch-session.ts

@@ -13,6 +13,16 @@ import {open, type FileHandle} from 'node:fs/promises';
  * `--mode json` STREAM `ar-run.sh` piped. The tailer is pointed at that EXACT
  * path (no newest-by-mtime dir guessing), so the stale-sibling race is gone.
  *
+ * Studied (task `pi-harness-polish`, finding
+ * `work/notes/findings/pi-harness-channels.md`, pinned against pi 0.73.1 +
+ * session format v3): tailing the session file is deliberately the CHOSEN
+ * channel for `--watch`, not just what was easiest to reuse. `--mode json`'s
+ * STDOUT event vocabulary would be lower-latency but it is unversioned, would
+ * fork a second parser away from pi-remote's `session-pool.ts` reference walk
+ * this classifier mirrors, and the vocabulary-drift risk that already bit
+ * `do --watch` once applies MORE to it than to the versioned+migrated session
+ * file. Revisit only if pi's session format changes.
+ *
  * A session-log record is `{"type":"message", "message":{role, content[]}}` (or a
  * `session`/`model_change`/`thinking_level_change` preamble record). The earlier
  * classifier matched the STREAM vocabulary (`tool_start`/`message_end`/`agent_end`),
@@ -21,8 +31,10 @@ import {open, type FileHandle} from 'node:fs/promises';
  * surfaces the same high-signal level `ar-run.sh --watch` gave, read off the
  * SESSION-LOG shape:
  *
- *   - an `assistant` `message` → its `content[]` `text` parts, then `▶ <name>`
- *     (cyan) per `content[]` `toolCall` part;
+ *   - an `assistant` `message` → its `content[]` `text` parts, then
+ *     `▶ <name> <detail>` (cyan) per `content[]` `toolCall` part, where
+ *     `<detail>` is the high-signal argument for that tool (a `read`'s path, a
+ *     `bash`'s command, …), truncated to 64 chars with a trailing `…`;
  *   - `✓ agent finished` (green) on PROCESS EXIT — the session log has no
  *     `agent_end` event, so the tailer emits it once on `stop()`;
  *   - everything else (`session`/`model_change`/user messages/tool results/…) →
@@ -50,6 +62,77 @@ function paint(text: string, color: boolean, code: string): string {
 	return color ? `${code}${text}${RESET}` : text;
 }
 
+/**
+ * The max width of a tool-call DETAIL string (the `read <path>` / `bash <cmd>`
+ * argument summary appended after the tool name). A longer detail is truncated
+ * to this many characters with a trailing `…`, so a giant `bash` heredoc or a
+ * long path never floods the live view with one enormous line.
+ */
+const MAX_DETAIL_LENGTH = 64;
+
+/** Truncate `text` to {@link MAX_DETAIL_LENGTH} chars, appending `…` when cut. */
+function truncateDetail(text: string): string {
+	// Collapse any embedded newlines/tabs to single spaces first: a multi-line
+	// `bash` command must stay ONE line in the tail view.
+	const oneLine = text.replace(/\s+/g, ' ').trim();
+	if (oneLine.length <= MAX_DETAIL_LENGTH) {
+		return oneLine;
+	}
+	return `${oneLine.slice(0, MAX_DETAIL_LENGTH)}…`;
+}
+
+/**
+ * The FIRST non-empty string among `keys` in a tool-call's arguments object, or
+ * `undefined` when the args are absent / none of the keys carry a string. The
+ * args live under `arguments` (pi's canonical key) OR `args` (the variant seen
+ * in some session records), mirroring the `name || toolName` defensiveness used
+ * for the tool name itself.
+ */
+function firstArgString(
+	part: Record<string, unknown>,
+	keys: readonly string[],
+): string | undefined {
+	const rawArgs =
+		(typeof part.arguments === 'object' && part.arguments) ||
+		(typeof part.args === 'object' && part.args) ||
+		undefined;
+	if (!rawArgs || rawArgs === null) {
+		return undefined;
+	}
+	const args = rawArgs as Record<string, unknown>;
+	for (const key of keys) {
+		const value = args[key];
+		if (typeof value === 'string' && value !== '') {
+			return value;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * The high-signal ARGUMENT to show after a tool name, chosen per tool so the
+ * `▶ <name>` marker reads like the agent's actual action (`▶ read work/x.md`,
+ * `▶ bash pnpm -r build`). The mapping mirrors this harness's own tool set
+ * (read/edit/write/grep/find/ls take a `path`; bash a `command`; grep a
+ * `pattern`; find/ls a `pattern`/`path`); any unmapped tool falls back to a
+ * generic `path`/`command`/`pattern`/`query` probe so a new tool still shows
+ * *something* useful. Returns `''` when no informative arg is present.
+ */
+function toolCallDetail(name: string, part: Record<string, unknown>): string {
+	const byTool: Record<string, readonly string[]> = {
+		read: ['path'],
+		edit: ['path'],
+		write: ['path'],
+		ls: ['path'],
+		find: ['pattern', 'path'],
+		grep: ['pattern', 'path'],
+		bash: ['command'],
+	};
+	const keys = byTool[name] ?? ['path', 'command', 'pattern', 'query', 'file'];
+	const detail = firstArgString(part, keys);
+	return detail === undefined ? '' : truncateDetail(detail);
+}
+
 /**
  * A structural view of the pi SESSION-LOG records we classify. It mirrors the
  * `@earendil-works/pi-coding-agent` `SessionEntry` / `SessionMessageEntry`
@@ -94,9 +177,10 @@ export function boundaryLine(label: string, color: boolean): string {
  *   - a `{type:"message", message:{role:"assistant", content}}` record → for each
  *     `content[]` part: a `text` part yields its text (parts concatenated into
  *     ONE line, like the old `jq` `.content[]` select); a `toolCall` part yields
- *     `▶ <name>` (cyan; `name` OR `toolName`, defaulting to `tool`); a `thinking`
- *     part (and anything else) is skipped. A plain-string `content` yields one
- *     text line.
+ *     `▶ <name> <detail>` (cyan; `name` OR `toolName`, defaulting to `tool`;
+ *     `<detail>` is the per-tool argument summary, truncated to 64 chars with a
+ *     `…`); a `thinking` part (and anything else) is skipped. A plain-string
+ *     `content` yields one text line.
  *   - everything else (`session`/`model_change`/`thinking_level_change`, user
  *     messages, tool results, blank/malformed lines) → `[]` (skipped).
  *
@@ -138,7 +222,9 @@ export function formatWatchEvent(line: string, color: boolean): string[] {
  * pi-remote's `session-pool.ts` reference parser. The `text` parts are
  * concatenated into a SINGLE leading line (so a multi-part assistant turn reads
  * as one sentence, as `ar-run.sh --watch` showed it); each `toolCall` part adds a
- * `▶ <name>` line after it. A plain-string content yields the single text line.
+ * `▶ <name> <detail>` line after it (`<detail>` = the tool's high-signal
+ * argument, truncated to 64 chars). A plain-string content yields the single
+ * text line.
  * `thinking` parts and any other block type are skipped.
  */
 function assistantLines(content: unknown, color: boolean): string[] {
@@ -160,7 +246,9 @@ function assistantLines(content: unknown, color: boolean): string[] {
 				(typeof p.name === 'string' && p.name !== '' && p.name) ||
 				(typeof p.toolName === 'string' && p.toolName !== '' && p.toolName) ||
 				'tool';
-			lines.push(paint(`▶ ${name}`, color, CYAN));
+			const detail = toolCallDetail(name, p);
+			const label = detail === '' ? name : `${name} ${detail}`;
+			lines.push(paint(`▶ ${label}`, color, CYAN));
 		}
 		// `text` is collected by assistantContentText; `thinking` and any other
 		// block type are skipped.
@@ -203,6 +291,13 @@ function assistantContentText(content: unknown): string {
  * message:{role:"assistant", content[]}}` records, takes the LAST one carrying
  * non-empty `text`, and returns its concatenated text.
  *
+ * Kept as a PURE `string → string | undefined` function on purpose: the pi
+ * adapter reads the session file and passes the JSONL text in, but a future
+ * stream/HTTP-shaped harness (opencode-style) can accumulate its own event
+ * stream into the same JSONL-shaped text and reuse this reader unchanged — the
+ * file shape does NOT leak through the `LaunchResult.output` seam (Option C).
+ * See `work/notes/findings/pi-harness-channels.md` (task `pi-harness-polish`).
+ *
  * Returns `undefined` when the log has no assistant text at all — an absent log,
  * a malformed/short log, or a run whose only assistant turn was tool-calls (no
  * `text` part). A tool-only assistant turn is NOT a final answer, so a LATER

package/src/work-layout.ts

@@ -5,7 +5,7 @@ import {join} from 'node:path';
  * folder-name union/array, the item-scan predicate, and the prefix-task helpers
  * used across `src/`.
  *
- * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` prd — the de-risking
+ * This is Phase 0 of the `folder-taxonomy-reorg-and-rename` spec — the de-risking
  * checkpoint. EVERY raw work-path literal (`join(cwd, 'work', ...)`, `'work/<folder>'`,
  * `'work/<folder>/'.length` prefix-tasks) and EVERY folder-name union/array that
  * used to be scattered across ~70 files now routes through here. The NAMES are
@@ -16,7 +16,7 @@ import {join} from 'node:path';
  * {@link WORK_FOLDER_NAME} (and `git mv` the on-disk folders) and NOTHING ELSE.
  * Call sites reference folders by their SYMBOLIC key (`'tasks-ready'`,
  * `'specs-ready'`, …), never by a raw string, so a folder-VALUE flip never
- * re-touches a single call site (a KEY rename, e.g. the prd→spec cutover below,
+ * re-touches a single call site (a KEY rename, e.g. the spec→spec cutover below,
  * is a mechanical relabel of the key literal at each site — behaviour-preserving).
  *
  * Domain note (crown-jewel invariant): a `work/` tree is a set of governance
@@ -65,17 +65,19 @@ export const WORK_ROOT = 'work' as const;
  *     and `needs-attention` (both are really lock-ref state, NOT durable folders;
  *     routed here only so no reader hand-writes the literal).
  *
- * NOTE on the prd→spec vocabulary cutover
+ * NOTE on the spec→spec vocabulary cutover
  * (`rename-spec-work-layout-and-folders`, migrate-batch 1 of
  * `prd-to-spec-vocabulary-cutover-and-migration-command`): the spec-regime KEYS
  * below now read in the `spec` vocabulary (`specs-proposed`/`specs-ready`/
  * `specs-tasked`/`specs-dropped`) AND their VALUES flip to `work/specs/*` in
- * lockstep with the on-disk `git mv work/prds/* → work/specs/*`. Unlike the earlier
+ * lockstep with the on-disk `git mv work/specs/* → work/specs/*`. Unlike the earlier
  * key-only relabel, this batch moves the folders too, so the KEY and VALUE change
  * together and the self-renaming-folder guard stays green. The KEY rename is a
  * mechanical relabel of the key literal at each call site (behaviour-preserving);
- * the frontmatter `prd:` field (a DATA alias the migration command converts) is the
- * one deliberate survivor; the `--specs-land-in` flag/`specsLandIn` config + the
+ * the legacy frontmatter ''prd:'' field survives ONLY as un-migrated on-disk DATA the
+ * `dorfl prd-to-spec` command textually converts to `spec:` (HARD CUTOVER: it is no
+ * longer READ by `parseFrontmatter` — `spec:` is the only read key); the
+ * `--specs-land-in` flag/`specsLandIn` config + the
  * `Spec*` symbols were completed by the later batches + the contract task. The
  * folder-as-status invariant is unchanged.
  */
@@ -193,7 +195,7 @@ export function isWorkItemFile(name: string): boolean {
  * order: `in-progress` over `tasks-ready`, with `done` appended only behind the
  * stranded-continue gate. Order is load-bearing — kept exactly as the original
  * union/array. (`tasks-backlog` is NOT in this DEFAULT order: it is appended at
- * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, prd
+ * the LOWEST priority ONLY behind the explicit `--allow-backlog` flag, spec
  * `do-allow-backlog-drive-staged-tasks-without-promotion` — see
  * {@link TaskResolutionFolder}.)
  */
@@ -217,12 +219,15 @@ export type TaskResolutionFolder =
 /**
  * The task LIFECYCLE folders a `task:<slug>` / lone-task `issue:` can reside
  * in (spec-complete.ts + close-job.ts `TASK_FOLDERS`): `tasks-ready`, `in-progress`,
- * `needs-attention`, `done`.
+ * `done`. `needs-attention` was dropped post-cutover
+ * (`finish-needs-attention-folder-cutover-remove-legacy-recovery-readers`, ratified
+ * in `docs/adr/needs-attention-folder-cutover-followup-nits.md`): the folder is
+ * retired — a stuck item is the per-item lock `state: stuck` with the body resting
+ * in `tasks/ready/`, so no task ever resides in `work/needs-attention/`.
  */
 export const TASK_LIFECYCLE_FOLDERS = [
 	'tasks-ready',
 	'in-progress',
-	'needs-attention',
 	'done',
 ] as const satisfies readonly WorkFolderKey[];
 

package/src/workspace.ts

@@ -155,8 +155,8 @@ export interface CreateJobOptions {
 	/** The work slug being processed (→ branch `work/<type>-<slug>` + work-id). */
 	slug: string;
 	/**
-	 * The item TYPE — `'task'` (build) or `'prd'` (tasking) — namespacing the
-	 * work branch via {@link workBranchRef} so a same-slug task and prd never
+	 * The item TYPE — `'task'` (build) or `'spec'` (tasking) — namespacing the
+	 * work branch via {@link workBranchRef} so a same-slug task and spec never
 	 * collide. Defaults to `'task'`.
 	 */
 	type?: SlugNamespace;