@orkestrel/scaffold 0.0.77 → 0.0.79

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

@@ -0,0 +1,259 @@
+// Probe a bench with one bounded round trip and resolve its entry. Run from the checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS]
+//   node .agents/skills/orkestrel-dispatch/scripts/bench.ts --codex [--model ID] [--sandbox MODE] [--cap SECONDS]
+//   node .agents/skills/orkestrel-dispatch/scripts/bench.ts --claude [--model ALIAS] [--cap SECONDS]
+// --cursor resolves the Cursor CLI entry (the newest versioned install under LOCALAPPDATA on
+// Windows, `agent` on PATH elsewhere), reads its version (an entry that cannot answer `--version` is
+// dark, with or without --resolve), and runs one bounded prompt through
+// launch.ts into tmp/cursor/bench.jsonl; --resolve stops after printing the entry. --codex reads
+// `codex --version` and `codex login status`, then runs one bounded exec into tmp/codex/bench.jsonl
+// under the sandbox the host allows (danger-full-access on Windows, read-only elsewhere). --claude
+// reads `claude --version` and runs one bounded print-mode prompt into tmp/claude/bench.jsonl. The
+// JSON summary carries the command, the version, the session id, the answer, and `live`. Exit 0 when
+// the bench answered READY, 3 when it is dark, 64 on usage.
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, extname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readJsonObject, readMissingFlags, readNumber, readOption, readString } from './helpers.ts'
+
+const SCRIPTS = dirname(fileURLToPath(import.meta.url))
+// The checkout runs the `.ts` sources and a built twin under `dist/agents` runs `.js` siblings.
+const EXTENSION = extname(fileURLToPath(import.meta.url))
+const PROMPT = 'Reply with the single word READY and nothing else.'
+const CURSOR_MODEL = process.env.CURSOR_GROK_MODEL ?? 'grok-4.7-high'
+const CODEX_MODEL = process.env.CODEX_ASTRA_MODEL ?? 'gpt-6-astra'
+const CLAUDE_MODEL = 'opus'
+const DEFAULT_CAP = 180
+
+interface Entry {
+	readonly command: readonly string[]
+	readonly version: string | undefined
+	readonly error: string | undefined
+}
+
+interface Summary {
+	readonly session: string | undefined
+	readonly answer: string | undefined
+	readonly exit: number | undefined
+	readonly capped: boolean
+	readonly durationMs: number | undefined
+}
+
+function readVersion(command: readonly string[]): string | undefined {
+	const [file, ...args] = command
+	if (file === undefined) return undefined
+	const result = spawnSync(file, [...args, '--version'], { encoding: 'utf8', windowsHide: true })
+	return result.status === 0 ? result.stdout.trim() : undefined
+}
+
+function resolveCursor(): Entry {
+	if (process.platform !== 'win32') {
+		return { command: ['agent'], version: readVersion(['agent']), error: undefined }
+	}
+	const local = process.env.LOCALAPPDATA
+	if (local === undefined)
+		return { command: [], version: undefined, error: 'LOCALAPPDATA is not set' }
+	const versions = join(local, 'cursor-agent', 'versions')
+	if (!existsSync(versions) || !statSync(versions).isDirectory()) {
+		return { command: [], version: undefined, error: `${versions} is not a directory` }
+	}
+	const newest = readdirSync(versions, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory() && /^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/u.test(entry.name))
+		.map((entry) => entry.name)
+		.sort()
+		.at(-1)
+	if (newest === undefined) {
+		return { command: [], version: undefined, error: `no versioned install under ${versions}` }
+	}
+	const node = join(versions, newest, 'node.exe')
+	const index = join(versions, newest, 'index.js')
+	if (!existsSync(node) || !existsSync(index)) {
+		return { command: [], version: undefined, error: `${newest} lacks node.exe or index.js` }
+	}
+	return { command: [node, index], version: readVersion([node, index]), error: undefined }
+}
+
+function runRoundTrip(
+	bench: 'cursor' | 'codex' | 'claude',
+	command: readonly string[],
+	cap: number,
+): Summary {
+	const journal = `tmp/${bench}/bench.jsonl`
+	const errors = `tmp/${bench}/bench.err`
+	const answer = `tmp/${bench}/bench-answer.md`
+	const launch = spawnSync(
+		process.execPath,
+		[
+			join(SCRIPTS, `launch${EXTENSION}`),
+			'--journal',
+			journal,
+			'--errors',
+			errors,
+			'--cap',
+			String(cap),
+			'--',
+			...command,
+		],
+		{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true },
+	)
+	const launched = readJsonObject(launch.stdout)
+	const result = spawnSync(
+		process.execPath,
+		[join(SCRIPTS, `result${EXTENSION}`), `--${bench}`, journal, '--out', answer],
+		{ encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true },
+	)
+	const read = readJsonObject(result.stdout)
+	return {
+		session: readString(read, 'session'),
+		answer: existsSync(answer) ? readFileSync(answer, 'utf8').trim().slice(0, 200) : undefined,
+		exit: readNumber(launched, 'exit'),
+		capped: launched?.capped === true,
+		durationMs: readNumber(launched, 'durationMs'),
+	}
+}
+
+function isLive(summary: Summary): boolean {
+	return (
+		summary.session !== undefined &&
+		summary.exit === 0 &&
+		!summary.capped &&
+		summary.answer !== undefined &&
+		/^READY\.?$/u.test(summary.answer.trim())
+	)
+}
+
+function probeCursor(argv: readonly string[]): number {
+	const entry = resolveCursor()
+	const model = readOption(argv, '--model') ?? CURSOR_MODEL
+	if (entry.error !== undefined || entry.version === undefined) {
+		console.log(JSON.stringify({ bench: 'cursor', ...entry, live: false }))
+		return 3
+	}
+	if (argv.includes('--resolve')) {
+		console.log(JSON.stringify({ bench: 'cursor', command: entry.command, version: entry.version }))
+		return 0
+	}
+	const cap = Number(readOption(argv, '--cap') ?? DEFAULT_CAP)
+	const summary = runRoundTrip(
+		'cursor',
+		[
+			...entry.command,
+			'-p',
+			'--trust',
+			'--mode=ask',
+			'--model',
+			model,
+			'--output-format',
+			'stream-json',
+			PROMPT,
+		],
+		cap,
+	)
+	const live = isLive(summary)
+	console.log(
+		JSON.stringify({
+			bench: 'cursor',
+			command: entry.command,
+			version: entry.version,
+			model,
+			...summary,
+			live,
+			journal: 'tmp/cursor/bench.jsonl',
+		}),
+	)
+	return live ? 0 : 3
+}
+
+function probeCodex(argv: readonly string[]): number {
+	const version = readVersion(['codex'])
+	const login = spawnSync('codex', ['login', 'status'], { encoding: 'utf8', windowsHide: true })
+	const model = readOption(argv, '--model') ?? CODEX_MODEL
+	const sandbox =
+		readOption(argv, '--sandbox') ??
+		(process.platform === 'win32' ? 'danger-full-access' : 'read-only')
+	const status = `${login.stdout}${login.stderr}`.trim()
+	if (version === undefined || login.status !== 0) {
+		console.log(JSON.stringify({ bench: 'codex', version, login: status, live: false }))
+		return 3
+	}
+	const cap = Number(readOption(argv, '--cap') ?? DEFAULT_CAP)
+	const summary = runRoundTrip(
+		'codex',
+		[
+			'codex',
+			'exec',
+			'--json',
+			'-C',
+			process.cwd(),
+			'--sandbox',
+			sandbox,
+			'--model',
+			model,
+			'-c',
+			'model_reasoning_effort="low"',
+			'--output-last-message',
+			'tmp/codex/bench-last.md',
+			PROMPT,
+		],
+		cap,
+	)
+	const live = isLive(summary)
+	console.log(
+		JSON.stringify({
+			bench: 'codex',
+			version,
+			login: status,
+			model,
+			sandbox,
+			...summary,
+			live,
+			journal: 'tmp/codex/bench.jsonl',
+		}),
+	)
+	return live ? 0 : 3
+}
+
+function probeClaude(argv: readonly string[]): number {
+	const version = readVersion(['claude'])
+	const model = readOption(argv, '--model') ?? CLAUDE_MODEL
+	if (version === undefined) {
+		console.log(JSON.stringify({ bench: 'claude', version, live: false }))
+		return 3
+	}
+	const cap = Number(readOption(argv, '--cap') ?? DEFAULT_CAP)
+	const summary = runRoundTrip(
+		'claude',
+		['claude', '-p', PROMPT, '--output-format', 'stream-json', '--verbose', '--model', model],
+		cap,
+	)
+	const live = isLive(summary)
+	console.log(
+		JSON.stringify({
+			bench: 'claude',
+			version,
+			model,
+			...summary,
+			live,
+			journal: 'tmp/claude/bench.jsonl',
+		}),
+	)
+	return live ? 0 : 3
+}
+
+function main(argv: readonly string[]): number {
+	const missing = readMissingFlags(argv, ['--model', '--cap', '--sandbox'])
+	if (missing.length > 0) {
+		console.error(`bench: ${missing.join(', ')} given with no value`)
+		return 64
+	}
+	if (argv.includes('--cursor')) return probeCursor(argv)
+	if (argv.includes('--codex')) return probeCodex(argv)
+	if (argv.includes('--claude')) return probeClaude(argv)
+	console.error(
+		'usage: bench.ts --cursor [--resolve] [--model ID] [--cap SECONDS] | --codex [--model ID] [--sandbox MODE] [--cap SECONDS] | --claude [--model ALIAS] [--cap SECONDS]',
+	)
+	return 64
+}
+
+process.exitCode = main(process.argv.slice(2))

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

@@ -0,0 +1,110 @@
+// Write a unit brief from the template, or check that every path a brief names resolves. Run from
+// the checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]
+//   node .agents/skills/orkestrel-dispatch/scripts/brief.ts --check tmp/codex/UNIT-brief.md
+// The first form copies the brief template beside this skill (`../../../templates/brief.md`, so a
+// target's installed copy finds it too) to tmp/<lane>/<unit>-brief.md with UNIT_ID and SHORT_SUBJECT
+// filled, and writes <unit>-brief-<n>.md when a brief already exists, so a launched brief is never
+// edited. The second form reads every backticked token carrying a slash (a backslash counts and is
+// read as a slash), strips a `:line` or
+// `:line-line` suffix, resolves it from the working directory, and prints the ones that do not
+// exist; a bare filename is outside the check. Exit 3 when any is missing, 64 on usage.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readMissingFlags, readOption } from './helpers.ts'
+
+const TEMPLATE = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	'..',
+	'..',
+	'..',
+	'templates',
+	'brief.md',
+)
+const LANES: Readonly<Record<string, string>> = Object.freeze({
+	units: 'tmp/units',
+	cursor: 'tmp/cursor',
+	codex: 'tmp/codex',
+	claude: 'tmp/claude',
+})
+
+function readsAsPath(token: string): boolean {
+	if (token.includes('://') || /[<>*{}\s]/u.test(token)) return false
+	if (/[A-Z]{2,}_[A-Z]/u.test(token)) return false
+	if (token.startsWith('@') || token.startsWith('-') || token.startsWith('$')) return false
+	if (!/^[A-Za-z0-9_.~/-]+$/u.test(token)) return false
+	return token.includes('/')
+}
+
+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)
+	}
+	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 writeBrief(argv: readonly string[]): number {
+	const unit = readOption(argv, '--unit')
+	const lane = readOption(argv, '--lane')
+	const directory = lane === undefined ? undefined : LANES[lane]
+	if (unit === undefined || directory === undefined || !/^[A-Za-z0-9._-]+$/u.test(unit)) {
+		console.error('usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT]')
+		return 64
+	}
+	if (!existsSync(TEMPLATE)) {
+		console.error(`brief: the template is missing at ${TEMPLATE}`)
+		return 64
+	}
+	mkdirSync(directory, { recursive: true })
+	const path = resolveBriefPath(directory, unit)
+	const subject = readOption(argv, '--subject') ?? 'SHORT_SUBJECT'
+	const content = readFileSync(TEMPLATE, 'utf8')
+		.replace(/UNIT_ID/gu, unit)
+		.replace(/SHORT_SUBJECT/gu, subject)
+	writeFileSync(path, content)
+	console.log(JSON.stringify({ brief: path, template: TEMPLATE }))
+	return 0
+}
+
+function checkBrief(path: string): number {
+	if (!existsSync(path) || !statSync(path).isFile()) {
+		console.error(`brief: ${path} is not a file`)
+		return 64
+	}
+	const paths = extractPaths(readFileSync(path, 'utf8'))
+	const missing = paths.filter((candidate) => !existsSync(resolve(candidate)))
+	console.log(JSON.stringify({ brief: path, checked: paths.length, missing }))
+	return missing.length === 0 ? 0 : 3
+}
+
+function main(argv: readonly string[]): number {
+	const missing = readMissingFlags(argv, ['--unit', '--lane', '--subject', '--check'])
+	if (missing.length > 0) {
+		console.error(`brief: ${missing.join(', ')} given with no value`)
+		return 64
+	}
+	const check = readOption(argv, '--check')
+	if (check !== undefined && argv.includes('--unit')) {
+		console.error('brief: --check and --unit are two modes; name one')
+		return 64
+	}
+	if (check !== undefined) return checkBrief(check)
+	if (argv.includes('--unit')) return writeBrief(argv)
+	console.error(
+		'usage: brief.ts --unit UNIT --lane units|cursor|codex|claude [--subject TEXT] | --check PATH',
+	)
+	return 64
+}
+
+process.exitCode = main(process.argv.slice(2))

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

@@ -0,0 +1,115 @@
+// Check that every `file:line` citation in a report, verdict, or distillate resolves. Run from the
+// checkout root:
+//   node .agents/skills/orkestrel-dispatch/scripts/cite.ts PATH [--root DIR] [--json]
+// A citation resolves when its path exists under the root (a path relative to the root resolves
+// first, and a backslash reads as a slash) and the line is within the file, where a trailing line
+// break ends the last line. A citation naming a bare filename that no root-relative
+// file matches resolves when exactly one file under the root carries that name, outside
+// node_modules, dist, tmp, .git, .orkestrel, and .idea. The summary lists every citation that does
+// not resolve, with the reason. Exit 0 when all resolve, 3 when any does not, 64 on usage.
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { basename, relative, resolve } from 'node:path'
+import { listFiles, normalizeSlashes, readMissingFlags, readOption } from './helpers.ts'
+
+const CITATION =
+	/(?<![\w/\\.-])((?:\.{1,2}[/\\])?\.?[A-Za-z0-9_@][A-Za-z0-9_./\\@-]*\.[a-z]{1,5}):(\d+)(?:[-–](\d+))?(?![\w:])/gu
+
+interface Unresolved {
+	readonly citation: string
+	readonly reason: string
+}
+
+interface Resolution {
+	readonly path: string | undefined
+	readonly reason: string | 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
+}
+
+function countLines(path: string): number {
+	const text = readFileSync(path, 'utf8')
+	if (text === '') return 0
+	const lines = text.split(/\r\n|\n/)
+	// A trailing line break ends the last line rather than opening a phantom one.
+	return lines.at(-1) === '' ? lines.length - 1 : lines.length
+}
+
+function resolveFile(
+	root: string,
+	file: string,
+	index: () => ReadonlyMap<string, readonly string[]>,
+): Resolution {
+	const direct = resolve(root, normalizeSlashes(file))
+	if (existsSync(direct) && statSync(direct).isFile()) return { path: direct, reason: undefined }
+	if (/[/\\]/u.test(file)) return { path: undefined, reason: 'file does not exist' }
+	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' }
+	return { path: undefined, reason: `ambiguous basename: ${candidates.join(', ')}` }
+}
+
+function judgeLines(
+	path: string,
+	line: number,
+	end: number | undefined,
+	counts: Map<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}`
+	return undefined
+}
+
+function main(argv: readonly string[]): number {
+	const missing = readMissingFlags(argv, ['--root'])
+	if (missing.length > 0) {
+		console.error(`cite: ${missing.join(', ')} given with no value`)
+		return 64
+	}
+	const root = readOption(argv, '--root') ?? process.cwd()
+	const path = argv.find(
+		(argument, position) => !argument.startsWith('--') && argv[position - 1] !== '--root',
+	)
+	if (path === undefined || !existsSync(path)) {
+		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 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 })
+	}
+	if (argv.includes('--json')) {
+		console.log(JSON.stringify({ path, root, citations, unresolved }))
+	} else {
+		console.log(`cite: ${citations} citation(s) in ${path}, ${unresolved.length} unresolved`)
+		for (const entry of unresolved) console.log(`cite: ${entry.citation} — ${entry.reason}`)
+	}
+	return unresolved.length === 0 ? 0 : 3
+}
+
+process.exitCode = main(process.argv.slice(2))