@orkestrel/scaffold 0.0.101 → 0.0.102

package/dist/host/AGENTS.md

@@ -27,6 +27,7 @@ configs/  thin target wrappers around root Vite/TypeScript configuration
 - The browser surface is `src/browser`, `app/browser`, the journey, and the showcase; the styles surface is `src/styles` and its themes. An extension adds a face to a surface: the `vue` browser extension adds `src/vue` and `app/vue`, and a named styles extension adds `src/<name>`.
 - `src/vue` and each `src/<name>` may import `src/core` and `src/browser`. `app/vue` may import what `app/browser` may import, plus `app/browser` and `src/vue`. No extension face imports server code or another extension's face, with one exception: a styles extension that builds another styles extension's recreation for a utility library (`src/tailwindcss` building Bootstrap for Tailwind) may `@use` that extension's Sass partials, configured through their `_tokens.scss` switches, and imports none of its TypeScript.
 - Published source never imports private app code.
+- The root `studies/` directory holds consumer study code, the TypeScript adapters and JSON declarations the Study CLI runs. It sits outside the environment axes, is never built or shipped, and no `src` or `app` file imports it.
 - Enforce boundaries with the toolchain (Oxlint import restrictions, scoped TypeScript projects, Vite graphs). Add no second parser for TypeScript, Oxlint, Vue, HTML, CSS, or Vite.
 - `tsconfig.json`, `vite.config.ts`, and each `*/types.ts` are their sources of truth. Keep structural files even when empty.
 

package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md

@@ -10,16 +10,16 @@ description: >-
 
 ## Scripts
 
-| Script               | Does                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `scripts/bench.ts`   | `--cursor [--resolve]`, `--codex [--sandbox MODE]`, or `--claude`, each with `[--model ID] [--cap SECONDS]`: resolves the bench entry, reads its version and login, runs one bounded round trip into `tmp/<bench>/bench.jsonl`, and prints JSON with `live`; `--resolve` prints the Cursor entry alone. Exit 3 when the bench is dark.                                                                               |
-| `scripts/brief.ts`   | `--unit UNIT --lane units\|cursor\|codex\|claude [--subject TEXT]` writes the brief from `.agents/templates/brief.md` and never overwrites a launched one; `--check PATH` lists every slash-bearing path the brief names that does not resolve from the root. Exit 3 when one is missing.                                                                                                                            |
-| `scripts/launch.ts`  | `--journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]` runs the command with no shell and closed stdin, kills it at the cap (its process tree on Windows), records `git status --porcelain` before and after with `--status`, prints a spawn line carrying the `pid` when the command starts, writes that pid to `<journal>.pid`, and ends the errors file with `exit=`. Exit 124 when capped. |
-| `scripts/login.ts`   | `--codex [--cap SECONDS]` reads `codex login status`, runs `codex login --device-auth` journaled to `tmp/codex/login.log` when it is not logged in, prints the URL and the one-time code as they appear, and polls the status until it answers or the cap ends; `--claude` reads `claude auth status`. Exit 0 logged in, 3 not.                                                                                      |
-| `scripts/result.ts`  | `--cursor\|--claude\|--codex JOURNAL [--out PATH]` prints the session id, the answer length, the run's `exit`, `capped`, and `durationMs` from the errors file, and the journal's `bytes`, `ageMs`, and `lastEvent`. Exit 3 when the journal carries no session or answer.                                                                                                                                           |
-| `scripts/cite.ts`    | `PATH [--root DIR] [--json]` lists every `file:line` citation in a report whose file does not exist or whose line is past the end. Exit 3 when one does not resolve.                                                                                                                                                                                                                                                 |
-| `scripts/helpers.ts` | What every skill script shares: `readOption`, `readOptions`, `readList`, `listFiles`, `readJsonObject`, `readString`, `readNumber`, `normalizeSlashes`, `resolveNpm`, `runNpm`. It runs nothing; import it with the `.ts` extension.                                                                                                                                                                                 |
-| `scripts/sweep.ts`   | `--report` lists leftovers under `tmp/` and `.orkestrel/` by age and deletes nothing; `--tmp [--older-than MINUTES]` deletes stale launch files and refuses while a journal is changing; `--unit UNIT [--delete]` lists or deletes one accepted unit's brief, report, claims, journal, errors, status, pid, and last-message files.                                                                                  |
+| Script               | Does                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `scripts/bench.ts`   | `--cursor [--resolve]`, `--codex [--sandbox MODE]`, or `--claude`, each with `[--model ID] [--cap SECONDS]`: resolves the bench entry, reads its version and login, runs one bounded round trip into `tmp/<bench>/bench.jsonl`, and prints JSON with `live`; `--resolve` prints the Cursor entry alone. Exit 3 when the bench is dark.                                                                                                                                   |
+| `scripts/brief.ts`   | `--unit UNIT --lane units\|cursor\|codex\|claude [--subject TEXT]` writes the brief from `.agents/templates/brief.md` and never overwrites a launched one; `--check PATH` lists every slash-bearing path the brief names that does not resolve from the root. Exit 3 when one is missing.                                                                                                                                                                                |
+| `scripts/launch.ts`  | `--journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]` runs the command with no shell and closed stdin, kills it at the cap (its process tree on Windows), records `git status --porcelain` before and after with `--status`, prints a spawn line carrying the `pid` when the command starts, writes that pid to `<journal>.pid`, and ends the errors file with `exit=`. Exit 124 when capped; 64 on usage, including a cap above 2147483 seconds. |
+| `scripts/login.ts`   | `--codex [--cap SECONDS]` reads `codex login status`, runs `codex login --device-auth` journaled to `tmp/codex/login.log` when it is not logged in, prints the URL and the one-time code as they appear, and polls the status until it answers or the cap ends; `--claude` reads `claude auth status`. Exit 0 logged in, 3 not.                                                                                                                                          |
+| `scripts/result.ts`  | `--cursor\|--claude\|--codex JOURNAL [--out PATH]` prints the session id, the answer length, the run's `exit`, `capped`, and `durationMs` from the errors file, and the journal's `bytes`, `ageMs`, and `lastEvent`. Exit 3 when the journal carries no session or answer.                                                                                                                                                                                               |
+| `scripts/cite.ts`    | `PATH [--root DIR] [--json]` lists every `file:line` citation in a report whose file does not exist or whose line is past the end. Exit 3 when one does not resolve.                                                                                                                                                                                                                                                                                                     |
+| `scripts/helpers.ts` | What every skill script shares: `readOption`, `readOptions`, `readList`, `listFiles`, `readJsonObject`, `readString`, `readNumber`, `normalizeSlashes`, `resolveNpm`, `runNpm`. It runs nothing; import it with the `.ts` extension.                                                                                                                                                                                                                                     |
+| `scripts/sweep.ts`   | `--report` lists leftovers under `tmp/` and `.orkestrel/` by age and deletes nothing; `--tmp [--older-than MINUTES]` deletes stale launch files and refuses while a journal is changing; `--unit UNIT [--delete]` lists or deletes one accepted unit's brief, report, claims, journal, errors, status, pid, and last-message files.                                                                                                                                      |
 
 ## Write the brief
 

package/dist/host/agents/skills/orkestrel-dispatch/scripts/brief.ts

@@ -38,20 +38,17 @@ function readsAsPath(token: string): boolean {
 }
 
 function extractPaths(content: string): readonly string[] {
-	const found = new Set<string>()
-	for (const match of content.matchAll(/`([^`\n]+)`/gu)) {
-		const token = (match[1] ?? '').replace(/\\/gu, '/').replace(/:\d+(?:[-–]\d+)?$/u, '')
-		if (readsAsPath(token)) found.add(token)
-	}
+	const found = new Set(
+		[...content.matchAll(/`([^`\n]+)`/gu)]
+			.map((match) => (match[1] ?? '').replace(/\\/gu, '/').replace(/:\d+(?:[-–]\d+)?$/u, ''))
+			.filter(readsAsPath),
+	)
 	return [...found].sort()
 }
 
-function resolveBriefPath(directory: string, unit: string): string {
-	const base = join(directory, `${unit}-brief.md`)
-	if (!existsSync(base)) return base
-	let n = 2
-	while (existsSync(join(directory, `${unit}-brief-${n}.md`))) n += 1
-	return join(directory, `${unit}-brief-${n}.md`)
+function resolveBriefPath(directory: string, unit: string, count = 1): string {
+	const path = join(directory, count === 1 ? `${unit}-brief.md` : `${unit}-brief-${count}.md`)
+	return existsSync(path) ? resolveBriefPath(directory, unit, count + 1) : path
 }
 
 function writeBrief(argv: readonly string[]): number {

package/dist/host/agents/skills/orkestrel-dispatch/scripts/cite.ts

@@ -24,15 +24,20 @@ interface Resolution {
 	readonly reason: string | undefined
 }
 
+interface Citation {
+	readonly citation: string
+	readonly file: string
+	readonly line: number
+	readonly end: number | undefined
+}
+
 function indexBasenames(root: string): ReadonlyMap<string, readonly string[]> {
-	const index = new Map<string, string[]>()
-	for (const file of listFiles(root)) {
-		const name = basename(file.path)
-		const paths = index.get(name) ?? []
-		paths.push(normalizeSlashes(relative(root, file.path)))
-		index.set(name, paths)
-	}
-	return index
+	return new Map(
+		[...Map.groupBy(listFiles(root), (file) => basename(file.path))].map(([name, files]) => [
+			name,
+			files.map((file) => normalizeSlashes(relative(root, file.path))),
+		]),
+	)
 }
 
 function countLines(path: string): number {
@@ -43,15 +48,25 @@ function countLines(path: string): number {
 	return lines.at(-1) === '' ? lines.length - 1 : lines.length
 }
 
+function resolveDirect(root: string, file: string): string | undefined {
+	const direct = resolve(root, normalizeSlashes(file))
+	return existsSync(direct) && statSync(direct).isFile() ? direct : undefined
+}
+
+// A bare filename that no root-relative file matches is the one citation the basename index serves.
+function needsIndex(root: string, file: string): boolean {
+	return resolveDirect(root, file) === undefined && !/[/\\]/u.test(file)
+}
+
 function resolveFile(
 	root: string,
 	file: string,
-	index: () => ReadonlyMap<string, readonly string[]>,
+	index: ReadonlyMap<string, readonly string[]> | undefined,
 ): Resolution {
-	const direct = resolve(root, normalizeSlashes(file))
-	if (existsSync(direct) && statSync(direct).isFile()) return { path: direct, reason: undefined }
+	const direct = resolveDirect(root, file)
+	if (direct !== undefined) return { path: direct, reason: undefined }
 	if (/[/\\]/u.test(file)) return { path: undefined, reason: 'file does not exist' }
-	const candidates = index().get(basename(file)) ?? []
+	const candidates = index?.get(basename(file)) ?? []
 	const only = candidates.length === 1 ? candidates[0] : undefined
 	if (only !== undefined) return { path: resolve(root, only), reason: undefined }
 	if (candidates.length === 0) return { path: undefined, reason: 'file does not exist' }
@@ -62,10 +77,9 @@ function judgeLines(
 	path: string,
 	line: number,
 	end: number | undefined,
-	counts: Map<string, number>,
+	counts: ReadonlyMap<string, number>,
 ): string | undefined {
 	const total = counts.get(path) ?? countLines(path)
-	counts.set(path, total)
 	if (line < 1 || line > total) return `line ${line} is outside 1-${total}`
 	if (end !== undefined && (end < line || end > total))
 		return `range end ${end} is outside ${line}-${total}`
@@ -86,23 +100,39 @@ function main(argv: readonly string[]): number {
 		console.error('usage: cite.ts PATH [--root DIR] [--json]')
 		return 64
 	}
-	let index: ReadonlyMap<string, readonly string[]> | undefined
-	const counts = new Map<string, number>()
-	const unresolved: Unresolved[] = []
-	let citations = 0
-	for (const match of readFileSync(path, 'utf8').matchAll(CITATION)) {
-		const file = match[1]
-		const line = Number(match[2])
-		const end = match[3] === undefined ? undefined : Number(match[3])
-		if (file === undefined) continue
-		citations += 1
-		const resolved = resolveFile(root, file, () => (index ??= indexBasenames(root)))
+	const named = [...readFileSync(path, 'utf8').matchAll(CITATION)].flatMap((match): Citation[] =>
+		match[1] === undefined
+			? []
+			: [
+					{
+						citation: match[0],
+						file: match[1],
+						line: Number(match[2]),
+						end: match[3] === undefined ? undefined : Number(match[3]),
+					},
+				],
+	)
+	const citations = named.length
+	// The basename index walks the root, so it is built once and only when a citation needs it.
+	const index = named.some(({ file }) => needsIndex(root, file)) ? indexBasenames(root) : undefined
+	const resolutions = named.map((entry) => ({
+		entry,
+		resolved: resolveFile(root, entry.file, index),
+	}))
+	// Each resolved file is counted once, however many citations name it.
+	const counts = new Map(
+		[...new Set(resolutions.flatMap(({ resolved }) => resolved.path ?? []))].map((file) => [
+			file,
+			countLines(file),
+		]),
+	)
+	const unresolved = resolutions.flatMap(({ entry, resolved }): Unresolved[] => {
 		const reason =
 			resolved.path === undefined
 				? (resolved.reason ?? 'file does not exist')
-				: judgeLines(resolved.path, line, end, counts)
-		if (reason !== undefined) unresolved.push({ citation: match[0], reason })
-	}
+				: judgeLines(resolved.path, entry.line, entry.end, counts)
+		return reason === undefined ? [] : [{ citation: entry.citation, reason }]
+	})
 	if (argv.includes('--json')) {
 		console.log(JSON.stringify({ path, root, citations, unresolved }))
 	} else {

package/dist/host/agents/skills/orkestrel-dispatch/scripts/helpers.ts

@@ -69,12 +69,10 @@ export function readMissingFlags(
  * @returns The values in order, empty when the flag never appears.
  */
 export function readOptions(argv: readonly string[], name: string): readonly string[] {
-	const values: string[] = []
-	argv.forEach((argument, index) => {
+	return argv.flatMap((argument, index) => {
 		const value = argv[index + 1]
-		if (argument === name && value !== undefined && !value.startsWith('--')) values.push(value)
+		return argument === name && value !== undefined && !value.startsWith('--') ? [value] : []
 	})
-	return values
 }
 
 /**
@@ -87,12 +85,9 @@ export function readOptions(argv: readonly string[], name: string): readonly str
 export function readList(argv: readonly string[], name: string): readonly string[] {
 	const index = argv.indexOf(name)
 	if (index === -1) return []
-	const values: string[] = []
-	for (const argument of argv.slice(index + 1)) {
-		if (argument.startsWith('--')) break
-		values.push(argument)
-	}
-	return values
+	const rest = argv.slice(index + 1)
+	const end = rest.findIndex((argument) => argument.startsWith('--'))
+	return end === -1 ? rest : rest.slice(0, end)
 }
 
 /**

package/dist/host/agents/skills/orkestrel-dispatch/scripts/launch.ts

@@ -2,7 +2,8 @@
 //   node .agents/skills/orkestrel-dispatch/scripts/launch.ts --journal tmp/codex/UNIT.jsonl --errors tmp/codex/UNIT.err --cap 1500 [--status] -- codex exec --json ...
 // The command's stdout goes to --journal and its stderr to --errors; stdin is closed. Arguments after
 // `--` pass to the command verbatim, so no shell quoting is involved. --cap is in seconds: when it
-// expires the process tree is killed and the errors file records `capped=true`. --status records
+// expires the process tree is killed and the errors file records `capped=true`. A fractional cap
+// truncates to whole milliseconds, with 1 ms the least. --status records
 // `git status --porcelain` before and after beside the journal, which is how a read-only lane's
 // containment is checked. Stdout carries up to two JSON lines. The spawn line
 // `{"pid","journal","errors"}` prints as soon as the command starts, and the pid, as decimal digits
@@ -12,12 +13,23 @@
 // Windows kills the process tree; any other host kills the command alone, not its descendants.
 // The launcher's own flags are read before `--` alone. Exit: the command's code; 124 when capped;
 // 127 when the command could not start (the errors file names why); 64 on usage, including a
-// journal and errors path that are the same file and a cap that is not a number of seconds.
+// journal and errors path that are the same file and a cap that is not a number of seconds from 0
+// to 2147483.
 import { spawn, spawnSync } from 'node:child_process'
 import { appendFileSync, closeSync, mkdirSync, openSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 import { readMissingFlags, readOption } from './helpers.ts'
 
+// The longest wait a Node timer holds is 2147483647 ms; floored to whole seconds, a longer cap would
+// throw from `AbortSignal.timeout` after the spawn or clamp to 1 ms and kill the command at once.
+const MAX_CAP_SECONDS = 2_147_483
+
+// `AbortSignal.timeout` throws on a fractional delay, which `setTimeout` truncates and raises to 1 ms
+// from below, so the cap takes that form before the command starts.
+function computeCapMilliseconds(cap: number): number {
+	return Math.max(1, Math.trunc(cap * 1000))
+}
+
 function readStatus(): string {
 	const result = spawnSync('git', ['status', '--porcelain'], { encoding: 'utf8' })
 	return result.status === 0 ? result.stdout : `git status failed: ${result.stderr}`
@@ -64,15 +76,17 @@ async function main(argv: readonly string[]): Promise<number> {
 		journal === errors ||
 		!Number.isFinite(cap) ||
 		cap < 0 ||
+		cap > MAX_CAP_SECONDS ||
 		command === undefined ||
 		command === ''
 	) {
 		console.error(
-			'usage: launch.ts --journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]; the journal and the errors file differ, and the cap is a number of seconds (0 for none)',
+			`usage: launch.ts --journal PATH --errors PATH --cap SECONDS [--status] -- COMMAND [ARGS...]; the journal and the errors file differ, and the cap is a number of seconds from 0 to ${String(MAX_CAP_SECONDS)} (0 for none)`,
 		)
 		return 64
 	}
 	const status = own.includes('--status')
+	const capMilliseconds = cap > 0 ? computeCapMilliseconds(cap) : undefined
 	mkdirSync(dirname(journal), { recursive: true })
 	mkdirSync(dirname(errors), { recursive: true })
 	if (status) writeFileSync(`${journal}.status-before.txt`, readStatus())
@@ -85,16 +99,21 @@ async function main(argv: readonly string[]): Promise<number> {
 		writeFileSync(`${journal}.pid`, `${child.pid}\n`)
 		console.log(JSON.stringify({ pid: child.pid, journal, errors }))
 	}
-	let capped = false
-	const timer =
-		cap > 0
-			? setTimeout(() => {
-					capped = true
-					if (child.pid !== undefined) killTree(child.pid)
-				}, cap * 1000)
-			: undefined
+	// The signal aborts once the cap elapses, so whether it aborted is whether the cap ended the run.
+	// The timer cannot be cleared, so a cap that elapses after the child exited kills nothing: a
+	// reused pid is not this command's.
+	const deadline = capMilliseconds === undefined ? undefined : AbortSignal.timeout(capMilliseconds)
+	deadline?.addEventListener(
+		'abort',
+		() => {
+			if (child.pid !== undefined && child.exitCode === null && child.signalCode === null) {
+				killTree(child.pid)
+			}
+		},
+		{ once: true },
+	)
 	const exit = await waitForExit(child)
-	if (timer !== undefined) clearTimeout(timer)
+	const capped = deadline?.aborted === true
 	closeSync(journalFd)
 	closeSync(errorsFd)
 	const durationMs = Date.now() - started

package/dist/host/agents/skills/orkestrel-dispatch/scripts/login.ts

@@ -21,6 +21,12 @@ interface Status {
 	readonly text: string
 }
 
+interface Poll {
+	readonly url: string | undefined
+	readonly code: string | undefined
+	readonly live: boolean
+}
+
 function readStatus(command: string, args: readonly string[]): Status {
 	const result = spawnSync(command, args, { encoding: 'utf8', windowsHide: true })
 	if (result.error !== undefined)
@@ -44,6 +50,27 @@ function waitFor(ms: number): Promise<void> {
 	})
 }
 
+async function pollLogin(
+	started: number,
+	capSeconds: number,
+	url?: string,
+	code?: string,
+): Promise<Poll> {
+	if (Date.now() - started >= capSeconds * 1000) return { url, code, live: false }
+	await waitFor(POLL_MS)
+	const text = existsSync(JOURNAL) ? readFileSync(JOURNAL, 'utf8') : ''
+	const nextUrl = url ?? text.match(URL_PATTERN)?.[0]
+	if (url === undefined && nextUrl !== undefined) console.error(`login: open ${nextUrl}`)
+	const nextCode = code ?? text.match(CODE_PATTERN)?.[1]
+	if (code === undefined && nextCode !== undefined) {
+		console.error(`login: enter the code ${nextCode}`)
+	}
+	if (readStatus('codex', ['login', 'status']).live) {
+		return { url: nextUrl, code: nextCode, live: true }
+	}
+	return pollLogin(started, capSeconds, nextUrl, nextCode)
+}
+
 async function loginCodex(capSeconds: number): Promise<number> {
 	const before = readStatus('codex', ['login', 'status'])
 	if (before.live) {
@@ -57,29 +84,7 @@ async function loginCodex(capSeconds: number): Promise<number> {
 		stdio: ['ignore', journal, journal],
 		windowsHide: true,
 	})
-	let url: string | undefined
-	let code: string | undefined
-	let live = false
-	while (Date.now() - started < capSeconds * 1000) {
-		await waitFor(POLL_MS)
-		const text = existsSync(JOURNAL) ? readFileSync(JOURNAL, 'utf8') : ''
-		if (url === undefined) {
-			url = text.match(URL_PATTERN)?.[0]
-			if (url !== undefined) console.error(`login: open ${url}`)
-		}
-		if (code === undefined) {
-			code = text.match(CODE_PATTERN)?.[1]
-			if (code !== undefined) console.error(`login: enter the code ${code}`)
-		}
-		if (child.exitCode !== null && readStatus('codex', ['login', 'status']).live) {
-			live = true
-			break
-		}
-		if (child.exitCode === null && readStatus('codex', ['login', 'status']).live) {
-			live = true
-			break
-		}
-	}
+	const { url, code, live } = await pollLogin(started, capSeconds)
 	if (child.exitCode === null && child.pid !== undefined) killTree(child.pid)
 	closeSync(journal)
 	console.log(

package/dist/host/agents/skills/orkestrel-dispatch/scripts/result.ts

@@ -26,17 +26,19 @@ interface Errors {
 }
 
 function readEvents(path: string): ReadonlyArray<Record<string, unknown>> {
-	const events: Array<Record<string, unknown>> = []
-	for (const line of readFileSync(path, 'utf8').split(/\r\n|\n/)) {
-		if (line.trim() === '') continue
-		try {
-			const parsed: unknown = JSON.parse(line)
-			if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
-				events.push(Object.fromEntries(Object.entries(parsed)))
+	return readFileSync(path, 'utf8')
+		.split(/\r\n|\n/)
+		.flatMap((line) => {
+			if (line.trim() === '') return []
+			try {
+				const parsed: unknown = JSON.parse(line)
+				return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+					? [Object.fromEntries(Object.entries(parsed))]
+					: []
+			} catch {
+				return []
 			}
-		} catch {}
-	}
-	return events
+		})
 }
 
 function readAnswer(text: string | undefined): string | undefined {