pirl-framework-cli 0.0.0-stage → 1.0.0

package/dist/engine/protocol.js

@@ -0,0 +1,98 @@
+const SKILL = {
+    plan: '.skills/pirl-plan/SKILL.md',
+    implement: '.skills/pirl-implement/SKILL.md',
+    review: '.skills/pirl-review/SKILL.md',
+};
+const LAYER_NAME = { plan: 'Plan', implement: 'Implement', review: 'Review' };
+export function hostInstructions(context) {
+    const python = context.python ? [context.python.command, ...context.python.args].join(' ') : 'python';
+    const lines = [
+        '# PIRL CLI host',
+        '',
+        'You are the coordinator of the PIRL framework, run by PIRL CLI, a terminal UI, in non-interactive mode.',
+        `- The Hub (framework root) is your working directory: ${context.hub}. Read AGENTS.md there first and follow it, with CONTEXT.md for every answer.`,
+        context.target
+            ? `- The target repository is ${context.target}. Write it as an absolute path wherever a Plan or report records target_repo.`
+            : '- No target repository: the user started PIRL CLI outside a Git repository.',
+        `- Run every Python command of the framework as \`${python} -B ...\` from the Hub root (for example \`${python} -B .agents/evals/layer_record.py start\`). Other spellings are refused.`,
+        '- Run each framework command as one plain command from the Hub root: no `cd`, no heredoc, no pipe, no `&&`. Pass JSON through a file, for example `layer_record.py append --input .tmp/pirl-run/record.json`.',
+        context.target
+            ? `- Read the target repository's Git history with \`git -C ${context.target} log ...\` (also show, diff, status, ls-files, rev-parse, blame), the path written exactly like that.`
+            : '',
+        '- Temporary files go under `.tmp/pirl-run/` in the Hub; PIRL CLI deletes that directory when the run ends, so do not delete them yourself. Nothing outside the Hub and the target repository is writable; `/tmp` is refused.',
+        '- Run subagents in the foreground and wait for their results in this turn. Do not start background work or schedule wakeups: the run ends when your reply ends.',
+        '- The run\'s permissions are fixed by PIRL CLI and cannot change during the run. Never ask the user to grant a permission; when a command is refused, use the allowed form above, or say what could not be done.',
+        '- Write your replies to the user in the language of the user\'s request; the framework\'s files (Plans, reports, records) keep the language their format requires.',
+    ];
+    if (context.kind === 'chat') {
+        lines.push('- No layer was opened. The user typed text without a slash command: answer a question, do a standalone task or framework maintenance, per AGENTS.md "Choosing a layer".', '- If the user\'s words ask for a layer (create a Plan, implement a Plan, review), do not run it. End your reply with the slash command the user should type, in a fenced block:', '```pirl-suggest', '/pirl-plan <the request, restated>', '```');
+        if (context.recentOutputs?.length)
+            lines.push(`- Outputs of earlier runs in this session: ${context.recentOutputs.join('; ')}.`);
+    }
+    else {
+        const kind = context.kind;
+        lines.push(`- The user opened the ${LAYER_NAME[kind]} layer with /pirl-${kind}; that is their explicit request for this layer and for delegating its roles to agents. Run the layer through \`${SKILL[kind]}\`. Do not open any other layer.`, `- Delegate each role to the subagent of the same name (business-analyst, code-analyst, …), with the Agent tool. Run at most ${context.maxParallelRoles} role subagents at the same time.`);
+    }
+    lines.push('- Nobody can answer a prompt while you run. When a decision only the user can make is missing, finish the parts that do not depend on it, then end your reply with the questions in a fenced block; PIRL CLI shows them and resumes this session with the answers:', '```pirl-questions', '[{"id": "Q1", "question": "…", "options": ["…", "…"], "recommended": 0}]', '```', '- Do not commit, push or switch branches anywhere. Leave framework improvements uncommitted in the Hub: PIRL CLI shows them and asks the user whether to commit.', '- Some commands are refused by the run\'s permissions. When one is refused, do not retry it; say what could not be done.');
+    if (context.kind !== 'chat') {
+        lines.push('- At the very end of your final reply, after the closing block of CONTEXT.md, add the outputs of this run in a fenced block (paths absolute):', '```pirl-result', '{"plan_set": "<package directory or null>", "plan_file": "<Plan file or null>", "report": "<Review report or null>", "record_id": "<record id or null>"}', '```');
+    }
+    return lines.filter(line => line !== '').join('\n');
+}
+const blockPattern = (name) => new RegExp('```' + name + '\\s*\\n([\\s\\S]*?)\\n?```', 'g');
+/** Text of the last fenced block with this name, or null. */
+export function lastBlock(text, name) {
+    const matches = [...text.matchAll(blockPattern(name))];
+    return matches.length > 0 ? matches.at(-1)[1].trim() : null;
+}
+/** The reply as the user should read it: the machine-readable blocks are taken out. */
+export function stripBlocks(text) {
+    return ['pirl-questions', 'pirl-result', 'pirl-suggest']
+        .reduce((current, name) => current.replace(blockPattern(name), ''), text)
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function parseQuestions(text) {
+    const block = lastBlock(text, 'pirl-questions');
+    if (!block)
+        return [];
+    try {
+        const data = JSON.parse(block);
+        if (!Array.isArray(data))
+            return [];
+        return data
+            .filter((item) => !!item && typeof item === 'object' && typeof item['question'] === 'string')
+            .map((item, index) => ({
+            id: typeof item['id'] === 'string' ? item['id'] : `Q${index + 1}`,
+            question: String(item['question']),
+            options: Array.isArray(item['options']) ? item['options'].map(String) : [],
+            recommended: typeof item['recommended'] === 'number' ? item['recommended'] : undefined,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export function parseOutputs(text) {
+    const empty = { planSet: null, planFile: null, report: null, recordId: null };
+    const block = lastBlock(text, 'pirl-result');
+    if (!block)
+        return empty;
+    try {
+        const data = JSON.parse(block);
+        const value = (key) => (typeof data[key] === 'string' && data[key] !== 'null' && data[key] !== '' ? data[key] : null);
+        return { planSet: value('plan_set'), planFile: value('plan_file'), report: value('report'), recordId: value('record_id') };
+    }
+    catch {
+        return empty;
+    }
+}
+export const parseSuggestion = (text) => lastBlock(text, 'pirl-suggest')?.split('\n')[0]?.trim() || null;
+/** The message that resumes the session once the user has answered every question. */
+export function answersMessage(questions, answers) {
+    return [
+        'Câu trả lời của người dùng cho các câu hỏi trong khối pirl-questions:',
+        ...questions.map((question, index) => `- ${question.id} (${question.question}): ${answers[index] ?? '(không trả lời)'}`),
+        'Ghi các câu trả lời này đúng nguyên văn vào output của run như AGENTS.md yêu cầu, rồi tiếp tục.',
+    ].join('\n');
+}

package/dist/engine/run.js

@@ -0,0 +1,527 @@
+import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { exec as defaultExec, succeeded } from '../core/exec.js';
+import { roleAgents } from './agents.js';
+import { allowedPaths, changedPaths, commitImprovements, countRecords, discardImprovements, listPlanSets, outsideAllowed, readFrontmatter, } from './hubData.js';
+import { permissionsFor } from './permissions.js';
+import { answersMessage, hostInstructions, parseOutputs, parseQuestions, parseSuggestion, stripBlocks } from './protocol.js';
+import { emptyUsage, LAYER_LABELS } from './types.js';
+/** Entries kept in memory for the TUI; the log file keeps every entry. Bounded so a long run costs the same to draw. */
+export const LOG_LIMIT = 200;
+const MAX_REPAIRS = 2;
+/** One line for the log: the run's tokens so far by kind, and their price at the Claude API list price. */
+function usageDetail(usage) {
+    if (usage.cacheReadTokens + usage.cacheWriteTokens + usage.inputTokens + usage.outputTokens === 0)
+        return null;
+    const cost = usage.costUsd === null ? '' : `, ≈ $${usage.costUsd.toFixed(3)} theo giá API`;
+    return `Token đến giờ: ${usage.cacheReadTokens} đọc cache, ${usage.cacheWriteTokens} ghi cache, ${usage.outputTokens} ra, ${usage.inputTokens} vào mới${cost} (${usage.models.join(', ')})`;
+}
+/**
+ * One layer run, or one chat message, from start to the user's decision on framework improvements.
+ * The provider does the reasoning; this class does every deterministic step around it: the permission rules,
+ * the validator gate, the check that process-auditor wrote exactly one record, the Allowed paths check
+ * after Implement, and the commit question for improvements.
+ */
+export class RunController {
+    deps;
+    state;
+    listeners = new Set();
+    handle = null;
+    exec;
+    repairs = 0;
+    before = { hubChanges: [], records: 0, planSets: [], targetChanges: [] };
+    resumedBefore;
+    stopped = false;
+    /** The usage before the current provider call, and the provider session's totals reported so far. */
+    callBase = null;
+    key;
+    firstStartedAt;
+    providerTotals = {};
+    deniedIds = new Set();
+    logStream = null;
+    now;
+    constructor(deps, id, kind, request, resume) {
+        this.deps = deps;
+        this.exec = deps.exec ?? defaultExec;
+        this.now = deps.now ?? Date.now;
+        const startedAt = this.now();
+        this.key = resume?.key ?? `${logStamp(new Date(startedAt))}-${kind}-${id}`;
+        this.firstStartedAt = resume?.startedAt ?? new Date(startedAt).toISOString();
+        const logFile = deps.logDir ? join(deps.logDir, `${logStamp(new Date(startedAt))}-${kind}-${id}.log`) : null;
+        this.state = {
+            id,
+            kind,
+            request,
+            status: 'running',
+            sessionId: resume?.sessionId ?? null,
+            roles: [],
+            activity: null,
+            questions: resume?.questions ?? [],
+            answers: [],
+            reply: null,
+            outputs: { planSet: null, planFile: null, report: null, recordId: null },
+            checks: {},
+            improvements: null,
+            suggestion: null,
+            denials: [],
+            usage: emptyUsage(),
+            quota: { before: null, after: null },
+            error: null,
+            startedAt,
+            log: [],
+            logCount: 0,
+            logFile,
+        };
+        if (resume?.status === 'waiting' && resume.questions?.length)
+            this.state.status = 'waiting';
+        this.resumedBefore = resume?.before;
+        this.providerTotals = resume?.providerTotals ?? {};
+        this.firstPrompt = resume ? resume.prompt ?? 'Tiếp tục run bị dừng từ chỗ đã dừng.' : request;
+        // Attachments go with the user's own words: a new request or a chat message, not a "continue".
+        if (deps.attachments?.text && (!resume || resume.prompt))
+            this.firstPrompt = `${this.firstPrompt}\n\n${deps.attachments.text}`;
+    }
+    /** What the first call sends: the request, a chat message into an existing session, or "continue". */
+    firstPrompt;
+    /** What /resume needs to continue this run after PIRL CLI was closed. */
+    persisted() {
+        return {
+            key: this.key,
+            startedAt: this.firstStartedAt,
+            savedAt: new Date(this.now()).toISOString(),
+            kind: this.state.kind,
+            request: this.state.request,
+            sessionId: this.state.sessionId,
+            status: this.state.status,
+            questions: this.state.questions,
+            before: this.before,
+            providerTotals: this.providerTotals,
+        };
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    update(patch, entry) {
+        if (entry) {
+            const line = { at: this.now() - this.state.startedAt, ...entry };
+            patch = { ...patch, log: [...this.state.log.slice(-(LOG_LIMIT - 1)), line], logCount: this.state.logCount + 1 };
+            this.writeLog(line);
+        }
+        this.state = { ...this.state, ...patch };
+        if (patch.status && TERMINAL.includes(patch.status))
+            this.closeLog();
+        for (const listener of this.listeners)
+            listener(this.state);
+    }
+    /** Appends to the log file; a log that cannot be written never stops the run. */
+    writeLog(entry) {
+        if (!this.state.logFile)
+            return;
+        try {
+            if (!this.logStream) {
+                mkdirSync(dirname(this.state.logFile), { recursive: true });
+                this.logStream = createWriteStream(this.state.logFile, { flags: 'a', encoding: 'utf8' });
+                this.logStream.on('error', () => {
+                    this.logStream = null;
+                });
+            }
+            this.logStream.write(`${formatElapsed(entry.at)} ${entry.who.padEnd(18)} ${entry.text}\n`);
+        }
+        catch {
+            this.logStream = null;
+        }
+    }
+    closeLog() {
+        this.logStream?.end();
+        this.logStream = null;
+    }
+    get layer() {
+        return this.state.kind === 'chat' ? null : this.state.kind;
+    }
+    /** Records what is in the Hub and the target before the provider runs, to tell this run's changes apart. */
+    async snapshot() {
+        if (this.resumedBefore) {
+            // A resumed run compares against the state before it first started, not before the resume.
+            this.before = this.resumedBefore;
+            return;
+        }
+        const layer = this.layer;
+        this.before = {
+            hubChanges: await changedPaths(this.deps.hub, this.exec),
+            records: layer ? countRecords(this.deps.hub, layer) : 0,
+            planSets: listPlanSets(this.deps.hub),
+            targetChanges: this.deps.target && this.deps.target !== this.deps.hub ? await changedPaths(this.deps.target, this.exec) : [],
+        };
+    }
+    async start() {
+        this.update({}, { who: 'pirl', text: `${this.state.sessionId ? 'Chạy tiếp' : 'Bắt đầu'} ${LAYER_LABELS[this.state.kind]}: ${this.state.request.split('\n')[0].slice(0, 120)}` });
+        await this.guard(async () => {
+            await this.snapshot();
+            if (this.state.status === 'waiting')
+                return; // resumed with unanswered questions: wait for the user
+            await this.send(this.firstPrompt);
+        });
+    }
+    /** Any unexpected error ends the run as failed with its message, instead of leaving it running forever. */
+    async guard(work) {
+        try {
+            await work();
+        }
+        catch (error) {
+            this.handle = null;
+            const message = error instanceof Error ? error.message : String(error);
+            this.update({ status: 'failed', error: message }, { who: 'pirl', text: `Lỗi: ${message}`, tone: 'error' });
+        }
+    }
+    /** Answers to the questions, in order; resumes the provider session once all are given. */
+    async answer(answers) {
+        if (this.state.status !== 'waiting')
+            return;
+        const questions = this.state.questions;
+        this.update({ answers, status: 'running', questions: [] });
+        await this.guard(() => this.send(answersMessage(questions, answers)));
+    }
+    stop() {
+        this.stopped = true;
+        this.handle?.stop();
+        if (!this.handle)
+            this.update({ status: 'stopped' }, { who: 'pirl', text: 'Đã dừng' });
+    }
+    async send(prompt) {
+        // Stopped while the run was still preparing (the snapshot can take a moment): start no provider at all.
+        if (this.stopped) {
+            if (this.state.status !== 'stopped')
+                this.update({ status: 'stopped' }, { who: 'pirl', text: 'Đã dừng' });
+            return;
+        }
+        const deps = this.deps;
+        const request = {
+            cwd: deps.hub,
+            addDirs: [...(deps.target && deps.target !== deps.hub ? [deps.target] : []), ...(deps.attachments?.dirs ?? [])],
+            prompt,
+            systemPrompt: hostInstructions({
+                kind: this.state.kind,
+                hub: deps.hub,
+                target: deps.target,
+                python: deps.python,
+                maxParallelRoles: deps.maxParallelRoles,
+                recentOutputs: deps.recentOutputs,
+            }),
+            agents: deps.agents ?? roleAgents(deps.hub, undefined, deps.roleModel, deps.target && deps.target !== deps.hub ? deps.target : null, deps.effort),
+            permissions: permissionsFor(this.state.kind, { hub: deps.hub, target: deps.target }, deps.python),
+            resumeSessionId: this.state.sessionId ?? undefined,
+            model: deps.model,
+            effort: deps.effort,
+        };
+        let result = null;
+        // The first meters are read while the provider starts up, before its first model request.
+        if (this.state.usage.calls === 0)
+            void this.readQuota('before');
+        this.update({ status: 'running', error: null, usage: { ...this.state.usage, calls: this.state.usage.calls + 1 } });
+        this.callBase = this.state.usage;
+        this.handle = deps.runner.start(request, event => {
+            if (event.type === 'result')
+                result = event;
+            this.apply(event);
+        });
+        const exit = await this.handle.done;
+        this.handle = null;
+        void this.readQuota('after');
+        const spent = usageDetail(this.state.usage);
+        if (spent)
+            this.update({}, { who: 'pirl', text: spent });
+        if (this.stopped) {
+            this.update({ status: 'stopped', roles: this.state.roles.map(role => (role.state === 'running' ? { ...role, state: 'failed' } : role)) }, { who: 'pirl', text: 'Đã dừng theo yêu cầu', tone: 'warning' });
+            return;
+        }
+        const final = result;
+        if (!final || final.isError) {
+            const detail = final?.text || exit.stderr.trim().split('\n').slice(-3).join(' ') || `mã thoát ${exit.code}`;
+            this.update({ status: 'failed', error: detail, reply: final?.text ? stripBlocks(final.text) : this.state.reply }, { who: 'pirl', text: `Lỗi: ${detail.slice(0, 200)}`, tone: 'error' });
+            return;
+        }
+        await this.afterReply(final.text);
+    }
+    /**
+     * Replaces the live count of the provider call with its exact totals. They cover the whole provider session,
+     * so the totals reported by its earlier calls are taken off. The request count stays the live one.
+     */
+    applyTotals(models) {
+        const base = this.callBase ?? this.state.usage;
+        const usage = { ...base, requests: this.state.usage.requests, models: [...base.models] };
+        const keys = ['inputTokens', 'cacheWriteTokens', 'cacheReadTokens', 'outputTokens'];
+        for (const [model, total] of Object.entries(models)) {
+            const before = this.providerTotals[model];
+            for (const key of keys)
+                usage[key] += Math.max(0, total[key] - (before?.[key] ?? 0));
+            const cost = total.costUsd === null ? null : Math.max(0, total.costUsd - (before?.costUsd ?? 0));
+            usage.costUsd = usage.costUsd === null || cost === null ? null : usage.costUsd + cost;
+            if (!usage.models.includes(model))
+                usage.models.push(model);
+        }
+        this.providerTotals = models;
+        this.update({ usage });
+    }
+    async readQuota(when) {
+        if (!this.deps.quota)
+            return;
+        let rows = null;
+        try {
+            rows = await this.deps.quota();
+        }
+        catch { }
+        if (rows)
+            this.update({ quota: { ...this.state.quota, [when]: rows } });
+    }
+    roleName(toolUseId) {
+        return toolUseId ? this.state.roles.find(role => role.toolUseId === toolUseId)?.role ?? null : null;
+    }
+    apply(event) {
+        switch (event.type) {
+            case 'session':
+                // A new provider session starts its totals from zero.
+                if (this.state.sessionId && event.sessionId !== this.state.sessionId)
+                    this.providerTotals = {};
+                if (event.sessionId !== this.state.sessionId)
+                    this.update({ sessionId: event.sessionId }, { who: 'pirl', text: `Session ${event.sessionId.slice(0, 8)}` });
+                break;
+            case 'role-start':
+                this.update({ roles: [...this.state.roles, { toolUseId: event.toolUseId, role: event.role, description: event.description, state: 'running', activity: null }] }, { who: event.role, text: `bắt đầu: ${event.description}` });
+                break;
+            case 'role-end': {
+                const role = this.roleName(event.toolUseId);
+                if (role) {
+                    this.update({ roles: this.state.roles.map(item => (item.toolUseId === event.toolUseId ? { ...item, state: event.ok ? 'done' : 'failed' } : item)) }, { who: role, text: event.ok ? 'xong' : 'kết thúc với lỗi', tone: event.ok ? 'success' : 'error' });
+                }
+                break;
+            }
+            case 'activity': {
+                const role = this.roleName(event.agent);
+                if (role) {
+                    this.update({ roles: this.state.roles.map(item => (item.toolUseId === event.agent ? { ...item, activity: event.text } : item)) }, { who: role, text: event.text });
+                }
+                else {
+                    this.update({ activity: event.text }, { who: 'coordinator', text: event.text });
+                }
+                break;
+            }
+            case 'retry': {
+                const text = `Provider lỗi tạm thời (${event.error}), thử lại lần ${event.attempt}`;
+                this.update({ activity: text }, { who: 'pirl', text, tone: 'warning' });
+                break;
+            }
+            case 'denied':
+                // Claude Code reports a refusal while it happens and again in the result: count it once.
+                if (event.id ? this.deniedIds.has(event.id) : this.state.denials.includes(event.detail))
+                    break;
+                if (event.id)
+                    this.deniedIds.add(event.id);
+                this.update({ denials: [...this.state.denials, event.detail] }, { who: 'pirl', text: `Chặn (ngoài quyền của run): ${event.detail}`, tone: 'warning' });
+                break;
+            case 'usage': {
+                const usage = this.state.usage;
+                this.update({
+                    usage: {
+                        calls: usage.calls,
+                        requests: usage.requests + (event.request ? 1 : 0),
+                        inputTokens: usage.inputTokens + event.inputTokens,
+                        cacheWriteTokens: usage.cacheWriteTokens + event.cacheWriteTokens,
+                        cacheReadTokens: usage.cacheReadTokens + event.cacheReadTokens,
+                        outputTokens: usage.outputTokens + event.outputTokens,
+                        costUsd: usage.costUsd === null || event.costUsd === null ? null : usage.costUsd + event.costUsd,
+                        models: usage.models.includes(event.model) ? usage.models : [...usage.models, event.model],
+                    },
+                });
+                break;
+            }
+            case 'usage-totals':
+                this.applyTotals(event.models);
+                break;
+            case 'quota':
+                // The windows as they stand now; the level before the run comes only from the reading taken before it.
+                this.update({ quota: { ...this.state.quota, after: event.rows } });
+                break;
+            case 'result':
+                this.update({ sessionId: event.sessionId ?? this.state.sessionId });
+                break;
+            case 'text':
+                break;
+        }
+    }
+    async afterReply(text) {
+        const questions = parseQuestions(text);
+        const outputs = parseOutputs(text);
+        this.update({
+            reply: stripBlocks(text),
+            outputs: {
+                planSet: outputs.planSet ?? this.state.outputs.planSet,
+                planFile: outputs.planFile ?? this.state.outputs.planFile,
+                report: outputs.report ?? this.state.outputs.report,
+                recordId: outputs.recordId ?? this.state.outputs.recordId,
+            },
+            suggestion: this.state.kind === 'chat' ? parseSuggestion(text) : null,
+            roles: this.state.roles.map(role => (role.state === 'running' ? { ...role, state: 'done' } : role)),
+        });
+        if (questions.length > 0) {
+            this.update({ status: 'waiting', questions, answers: [] }, { who: 'pirl', text: `Chờ bạn trả lời ${questions.length} câu hỏi`, tone: 'warning' });
+            return;
+        }
+        if (this.layer) {
+            this.update({ status: 'checking' }, { who: 'pirl', text: 'Coordinator xong; kiểm tra kết quả' });
+            const repair = await this.checkLayer();
+            if (repair && this.repairs < (this.deps.maxRepairs ?? MAX_REPAIRS)) {
+                this.repairs += 1;
+                this.update({}, { who: 'pirl', text: `Gửi coordinator sửa (lần ${this.repairs})`, tone: 'warning' });
+                await this.send(repair);
+                return;
+            }
+        }
+        await this.findImprovements();
+    }
+    resolveHubPath(path) {
+        if (!path)
+            return null;
+        const full = isAbsolute(path) || /^[A-Za-z]:[\\/]/.test(path) ? path : join(this.deps.hub, path);
+        return existsSync(full) ? full : null;
+    }
+    async python(args) {
+        const python = this.deps.python;
+        if (!python)
+            return { code: null, stdout: '', stderr: '', error: 'Không tìm thấy Python' };
+        return this.exec(python.command, [...python.args, '-B', ...args], { cwd: this.deps.hub, timeoutMs: 120_000 });
+    }
+    /** The checks the layer's skill ends with, done by the CLI itself. Returns a repair message, or null. */
+    async checkLayer() {
+        const layer = this.layer;
+        const checks = {};
+        const repairs = [];
+        // Validator: the Plan package after Plan, the Plan file after Implement, the report after Review.
+        const newPlanSets = listPlanSets(this.deps.hub).filter(name => !this.before.planSets.includes(name));
+        const target = layer === 'plan'
+            ? this.resolveHubPath(this.state.outputs.planSet) ?? (newPlanSets.length === 1 ? join(this.deps.hub, newPlanSets[0]) : null)
+            : layer === 'implement'
+                ? this.resolveHubPath(this.state.outputs.planFile)
+                : this.resolveHubPath(this.state.outputs.report);
+        if (!target) {
+            checks.validator = { state: 'skipped', detail: 'không xác định được file kết quả của run' };
+        }
+        else {
+            const result = await this.python(['.agents/evals/validate_layer_artifact.py', '--kind', layer === 'review' ? 'review' : 'plan', '--path', target]);
+            if (succeeded(result))
+                checks.validator = { state: 'pass', detail: relative(this.deps.hub, target) || target };
+            else {
+                const detail = (result.stdout || result.stderr || result.error || '').trim().slice(0, 1500);
+                checks.validator = { state: 'fail', detail };
+                repairs.push(`Validator báo lỗi cho ${target}:\n${detail}\nSửa các lỗi này rồi chạy lại validator cho tới khi PASS.`);
+            }
+            if (layer === 'plan' && !this.state.outputs.planSet)
+                this.update({ outputs: { ...this.state.outputs, planSet: target } });
+        }
+        // Self-evaluation: exactly one new record for this layer, and the records still pass `check`.
+        const added = countRecords(this.deps.hub, layer) - this.before.records;
+        const check = await this.python(['.agents/evals/layer_record.py', 'check']);
+        if (added < 1) {
+            checks.record = { state: 'fail', detail: 'process-auditor chưa ghi record cho run này' };
+            repairs.push('Bước tự đánh giá chưa xong: process-auditor chưa ghi record nào cho run này. Hoàn tất bước đó theo skill của layer.');
+        }
+        else if (!succeeded(check)) {
+            checks.record = { state: 'fail', detail: (check.stdout || check.stderr).trim().slice(0, 800) };
+            repairs.push(`\`layer_record.py check\` báo lỗi:\n${checks.record.detail}\nSửa record cho đúng.`);
+        }
+        else {
+            checks.record = { state: 'pass', detail: added > 1 ? `${added} record mới` : '1 record mới' };
+        }
+        // Implement may change only the Plan's Allowed paths in the target repository.
+        if (layer === 'implement' && this.deps.target && this.deps.target !== this.deps.hub) {
+            const planFile = this.resolveHubPath(this.state.outputs.planFile);
+            const allowed = planFile ? allowedPaths(readFileSync(planFile, 'utf8')) : [];
+            const changed = (await changedPaths(this.deps.target, this.exec)).filter(path => !this.before.targetChanges.includes(path));
+            const outside = outsideAllowed(changed, allowed);
+            checks.paths =
+                allowed.length === 0
+                    ? { state: 'skipped', detail: 'Plan không có dòng Allowed paths' }
+                    : outside.length === 0
+                        ? { state: 'pass', detail: `${changed.length} file thay đổi, đều trong Allowed paths` }
+                        : { state: 'fail', detail: `Ngoài Allowed paths: ${outside.join(', ')}` };
+        }
+        const labels = { validator: 'Validator', record: 'Record', paths: 'Allowed paths' };
+        for (const [key, check] of Object.entries(checks)) {
+            const verdict = check.state === 'pass' ? 'PASS' : check.state === 'fail' ? 'FAIL' : 'bỏ qua';
+            this.update({}, { who: 'pirl', text: `${labels[key]}: ${verdict}${check.detail ? ` (${check.detail.split('\n')[0].slice(0, 120)})` : ''}`, tone: check.state === 'pass' ? 'success' : check.state === 'fail' ? 'error' : undefined });
+        }
+        this.update({ checks });
+        return repairs.length > 0 ? repairs.join('\n\n') : null;
+    }
+    /** Framework files this run changed in the Hub; files already changed before the run are left alone. */
+    async findImprovements() {
+        // The run's temporary files (.tmp/pirl-run/) are removed here, as the host instructions promise the coordinator.
+        rmSync(join(this.deps.hub, '.tmp', 'pirl-run'), { recursive: true, force: true });
+        const now = await changedPaths(this.deps.hub, this.exec);
+        const files = now.filter(path => !this.before.hubChanges.includes(path));
+        if (files.length === 0) {
+            this.update({ status: 'done' }, { who: 'pirl', text: 'Xong', tone: 'success' });
+            return;
+        }
+        this.update({ status: 'checking', activity: 'Chạy test của framework trên các cải tiến' }, { who: 'pirl', text: `${files.length} file framework thay đổi; chạy test của framework` });
+        const tests = await this.frameworkTests();
+        this.update({ status: 'improvements', improvements: { files, state: 'pending', tests } }, tests.state === 'fail'
+            ? { who: 'pirl', text: `Test framework: FAIL; cải tiến này không được commit (${tests.detail?.split('\n')[0]?.slice(0, 120) ?? ''})`, tone: 'error' }
+            : { who: 'pirl', text: `Test framework: ${tests.state === 'pass' ? 'PASS' : 'bỏ qua'}; chờ bạn quyết định commit`, tone: 'warning' });
+    }
+    /** The framework's own tests on the Hub as the run left it: a broken framework must never be committed to main. */
+    async frameworkTests() {
+        if (!this.deps.python)
+            return { state: 'skipped', detail: 'Không tìm thấy Python' };
+        const result = await this.python(['-m', 'unittest', 'discover', '-s', '.agents/evals/tests', '-p', 'test_*.py']);
+        if (succeeded(result))
+            return { state: 'pass' };
+        const output = `${result.stderr}\n${result.stdout}`.trim().split('\n');
+        const failures = output.filter(line => /^(FAIL|ERROR):/.test(line));
+        return { state: 'fail', detail: (failures.length ? failures : output.slice(-5)).join('\n') || result.error || `mã thoát ${result.code}` };
+    }
+    /** The user's decision on this run's framework improvements. */
+    async resolveImprovements(choice) {
+        const pending = this.state.improvements;
+        if (!pending || pending.state !== 'pending')
+            return;
+        if (choice === 'commit' && pending.tests?.state === 'fail') {
+            this.update({ improvements: { ...pending, error: 'Test của framework đang lỗi: không commit một framework hỏng vào Hub. Chọn bỏ cải tiến, hoặc giữ để sửa tay.' } });
+            return;
+        }
+        if (choice === 'keep') {
+            this.update({ status: 'done', improvements: { ...pending, state: 'kept' } }, { who: 'pirl', text: 'Giữ cải tiến, chưa commit. Xong', tone: 'success' });
+            return;
+        }
+        const result = choice === 'commit'
+            ? await commitImprovements(this.deps.hub, pending.files, { kind: this.state.kind, recordId: this.state.outputs.recordId, summary: this.state.request.slice(0, 200) }, this.exec)
+            : await discardImprovements(this.deps.hub, pending.files, this.exec);
+        if (!result.ok) {
+            this.update({ improvements: { ...pending, error: result.error ?? 'lỗi không rõ' } });
+            return;
+        }
+        this.update({ status: 'done', improvements: { files: pending.files, state: choice === 'commit' ? 'committed' : 'discarded' } }, { who: 'pirl', text: `${choice === 'commit' ? 'Đã commit' : 'Đã bỏ'} ${pending.files.length} file cải tiến. Xong`, tone: 'success' });
+    }
+    /** Task ID and title of the Plan file this run produced or worked on, for the run block. */
+    planSummary() {
+        const file = this.resolveHubPath(this.state.outputs.planFile);
+        if (!file)
+            return null;
+        const fields = readFrontmatter(readFileSync(file, 'utf8'));
+        return `${fields['task_id'] ?? ''} ${fields['title'] ?? ''}`.trim() || null;
+    }
+}
+const TERMINAL = ['done', 'failed', 'stopped'];
+/** mm:ss since the run started, or h:mm:ss after an hour. */
+export function formatElapsed(ms) {
+    const total = Math.max(0, Math.floor(ms / 1000));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    const two = (value) => String(value).padStart(2, '0');
+    return hours > 0 ? `${hours}:${two(minutes)}:${two(seconds)}` : `${two(minutes)}:${two(seconds)}`;
+}
+const logStamp = (date) => {
+    const two = (value) => String(value).padStart(2, '0');
+    return `${date.getFullYear()}${two(date.getMonth() + 1)}${two(date.getDate())}-${two(date.getHours())}${two(date.getMinutes())}${two(date.getSeconds())}`;
+};