create-agdf 0.30.0 → 0.32.0

package/generated/plugins/agdf/companion/run-state.mjs

@@ -1,106 +1,105 @@
-import { projectStoredRun } from './core.mjs';
-// Bounded, read-only current-Run projection. Typed records and display policy come
-// from the canonical pure Core modules. This does not qualify seals or file evidence
-// and never authorizes a gate or command. File access remains injected by the host.
+// Run view reader (SD SDD-010): obtains the Core run view through the plugin runtime's read-only
+// `run-view` command and maps it to the companion's runs. The companion derives no run semantics of
+// its own: status, gate path, missing approval, next step and figure come from the status card's
+// evaluator. Process access is injected by the host ({ run(argv, init) }, as `$.process` provides).
 
-export const GATES = Object.freeze(['UR', 'PRD', 'SD', 'TP', 'QA', 'UAT', 'OR']);
-// The internal steps between an approved TP and QA, shown as the build phase (SDD-02, SDD-03).
+export const RUN_VIEW_SCHEMA = 'run-view/1';
+export const RUN_VIEW_TIMEOUT_MS = 10_000;
+// Why a run-view read failed; each has a catalog text under `unreadable` (shown with the failure).
+export const READ_FAILURE_REASONS = Object.freeze(['timeout', 'unavailable', 'exit', 'malformed', 'source_changed']);
+// Store reasons of a read that may succeed on the next attempt (a write during the read, the read
+// budget); they keep the last good view, marked stale, like a failed read (CR delta review RV-1).
+export const TRANSIENT_STORE_REASONS = Object.freeze(['source_changed', 'timeout']);
+// Evaluation errors of a single run that make the whole view incomplete (a write during its read).
+export const TRANSIENT_RUN_REASONS = Object.freeze(['source_changed']);
+// The internal steps between an approved TP and QA, shown as the build phase in the gate bar.
 export const BUILD_GATES = Object.freeze(['Brownfield Analysis', 'CD+Tests', 'CR']);
 export const isStructured = route => route === 'structured_delivery' || route === 'structured_slice';
-// The host rejects reads over 4 MiB; the largest observed run state is about 280 KB.
-export const MAX_RUN_STATE_BYTES = 1024 * 1024;
 const TEXT_LIMIT = 240;
+const clip = text => { const value = String(text ?? ''); return value.length > TEXT_LIMIT ? `${value.slice(0, TEXT_LIMIT - 1)}…` : value; };
 
-// The run lifecycles the core reader accepts (`LIFECYCLES` in run-state-parser.js); the logic suite
-// asserts that both sets are equal, so a new core lifecycle fails it instead of reading unreadable.
-export const LIFECYCLES = Object.freeze(['active', 'completed', 'superseded', 'abandoned']);
-const KNOWN_LIFECYCLES = new Set(LIFECYCLES);
-const plain = value => String(value ?? '').replace(/`/gu, '').trim();
-const clip = text => (text.length > TEXT_LIMIT ? `${text.slice(0, TEXT_LIMIT - 1)}…` : text);
-
-// Body of a level-two section, without its heading; '' when absent.
-export function section(text, heading) {
-  const lines = text.split('\n');
-  const start = lines.findIndex(line => line.trimEnd() === `## ${heading}`);
-  if (start < 0) return '';
-  const rest = lines.slice(start + 1);
-  const end = rest.findIndex(line => line.startsWith('## '));
-  return (end < 0 ? rest : rest.slice(0, end)).join('\n');
+// The only command the companion runs: the read-only run view of one project root.
+export function runViewArgv({ pluginRoot, root, language, runIds = [] }) {
+  return ['node', `${pluginRoot}/runtime/agdf-local.js`, 'run-view', '--dir', root, '--json', '--language', language,
+    ...runIds.flatMap(runId => ['--run', runId])];
 }
 
-const field = (body, key) => plain(body.match(new RegExp(`^- ${key}:[ \\t]*(.*)$`, 'mu'))?.[1]);
-
-// Canonical writers keep a review or gate result in the Artefacts row of the step that produced it
-// (`CR | … | revise`, `QA | … | block`); a Quick Task's Code Review is the CR row. The Run Meta
-// `decision` stays `in_progress` (CR-F02).
-const RESULT_ROWS = Object.freeze({ 'Quick Task Execution': ['CR'] });
-const RESULTS = new Set(['revise', 'block', 'blocked']);
-// The core's decision-content placeholder rule (`isDecisionContentPlaceholder`,
-// decision-content-readiness.js), so a template objective is never shown as the run's goal.
-const PROMPTS = new Set(['describe the trustworthy outcome.', 'what outcome should become possible?',
-  'which tp tasks are fully done, partially done or not done?', 'what remains unverified?', 'which risks remain and what is their impact?']);
-export function isPlaceholderText(value) {
-  if (typeof value !== 'string') return true;
-  const text = value.trim().replace(/^`([^`]+)`$/u, '$1').replace(/\s+/gu, ' ').toLowerCase();
-  return !text || PROMPTS.has(text)
-    || /^(?:todo|tbd|<[^>]+>|(?:draft|done|ready|blocked|pass|revise|block)(?:\s*\|\s*(?:draft|done|ready|blocked|pass|revise|block))+)$/u.test(text);
+// One run-view entry as the companion's run.
+export function companionRun(entry) {
+  return Object.freeze({
+    id: entry.run_id,
+    lifecycle: entry.lifecycle,
+    evaluated: entry.evaluated === true,
+    gate: entry.current_gate ?? null,
+    route: entry.mode ?? null,
+    updatedAt: entry.last_activity ?? '',
+    missing: entry.missing_approval ?? 'none',
+    next: entry.next_step ?? '',
+    nextText: entry.next_step_text ?? '',
+    blockingText: entry.blocking_text ?? '',
+    path: Object.freeze((entry.path ?? []).map(({ gate, status }) => Object.freeze({ gate, status }))),
+    figure: entry.figure,
+    // Bound documents changed after recording (SDD-008), as the run view reports them.
+    drift: Object.freeze((entry.drift ?? []).map(item => Object.freeze({ ...item }))),
+    // The authored objective, never the status card's run title or a template text.
+    objective: clip(entry.objective ?? ''),
+    // The run's stable human title (registered UR heading, else the authored objective); empty while
+    // only the run id could name it. The goal is the objective in the display language where the UR
+    // states one.
+    title: clip(entry.run_title ?? ''),
+    goal: clip(entry.goal ?? entry.objective ?? ''),
+  });
 }
 
-// Returns { ok: true, run } or { ok: false, id, reason } with reason missing | too_large | format.
-// Only version 4 typed records are accepted; retired persisted derived tables are refused.
-export function parseRunState(id, text) {
-  if (typeof text !== 'string') return { ok: false, id, reason: 'missing' };
-  if (text.length > MAX_RUN_STATE_BYTES) return { ok: false, id, reason: 'too_large' };
-  const normalized = text.replace(/^/u, '').replace(/\r\n?/gu, '\n');
-  const meta = section(normalized, 'Run Meta');
-  let projection; try { projection = projectStoredRun(normalized); } catch { return { ok: false, id, reason: 'format' }; }
-  const control = projection.control;
-  const runId = field(meta, 'run_id');
-  const lifecycle = field(meta, 'lifecycle');
-  const gate = control.current_gate;
-  const decision = lifecycle === 'completed' ? 'completed' : 'in_progress';
-  const updatedAt = Number.isNaN(Date.parse(field(meta, 'updated_at'))) ? '' : field(meta, 'updated_at');
-  if (!meta || runId !== id || !KNOWN_LIFECYCLES.has(lifecycle) || !gate) return { ok: false, id, reason: 'format' };
-  const objective = section(normalized, 'Objective').split('\n').map(line => line.trim()).find(Boolean) ?? '';
-  const statuses = new Map([...projection.facts.artefacts].map(([name, row]) => [name, row.status]));
-  const gateResult = (RESULT_ROWS[gate] ?? [gate]).map(type => statuses.get(type)).find(status => RESULTS.has(status)) ?? null;
-  return { ok: true, run: Object.freeze({
-    id,
-    lifecycle,
-    gate,
-    decision,
-    route: projection.route,
-    gateResult,
-    gateDecision: control.presentation_decision?.action ?? null,
-    updatedAt,
-    missing: clip(projection.facts.artefacts.get(gate)?.path || gate === 'UAT' ? control.missing_approval ?? '' : 'none'),
-    next: clip(control.next_allowed_action ?? ''),
-    approved: Object.freeze([...projection.facts.approvals].filter(([, row]) => row.status === 'approved').map(([name]) => name)),
-    objective: isPlaceholderText(objective) ? '' : clip(objective),
-  }) };
+// stdout of the command as a snapshot: { status, root, runs, unreadable, diagnosis, readAt }.
+// status is ok, no_control, unavailable (store diagnosis with reason) or failed (no usable view).
+export function snapshotFromRunView(stdout, { now }) {
+  let view;
+  try { view = JSON.parse(stdout); } catch { return { status: 'failed', runs: [], unreadable: [], readAt: now, error: 'malformed' }; }
+  if (view?.schema_version !== RUN_VIEW_SCHEMA || !Array.isArray(view.runs) || !view.store) {
+    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: 'malformed' };
+  }
+  if (view.store.status === 'unavailable' && TRANSIENT_STORE_REASONS.includes(view.store.reason)) {
+    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: view.store.reason };
+  }
+  // A run read while its files changed (after the run view's bounded retries) makes the view incomplete;
+  // like a transient store failure it keeps the last good view instead of showing that run as blocked.
+  // A single run that ran into the read budget is not transient: it stays that run's own reason, so the
+  // other runs are still shown.
+  const changedRun = view.runs.find(run => TRANSIENT_RUN_REASONS.includes(run?.evaluation_error));
+  if (changedRun) return { status: 'failed', runs: [], unreadable: [], readAt: now, error: changedRun.evaluation_error };
+  const status = view.store.status === 'ok' ? 'ok' : view.store.status === 'no_control' ? 'no_control' : 'unavailable';
+  return {
+    status,
+    root: view.root,
+    reason: view.store.reason ?? null,
+    // The run folders of an unsupported store, which the run view counts without reading them (AC-002).
+    runFolders: Number.isSafeInteger(view.store.run_folders) && view.store.run_folders > 0 ? view.store.run_folders : null,
+    runs: view.runs.filter(entry => entry.valid !== false && entry.listed !== false).map(companionRun),
+    unreadable: (view.diagnosis?.unreadable ?? []).map(({ run_id, reason }) => ({ id: run_id, reason })),
+    diagnosis: view.diagnosis ?? null,
+    // A run that ran into the read budget may read on the next attempt: the adapter keeps no
+    // fingerprint for such a view, so the next check reads again instead of waiting for a file change.
+    retry: view.runs.some(run => run?.evaluation_error === 'timeout'),
+    readAt: now,
+  };
 }
 
-// Reads every run state below <projectRoot>/.agdf/control/runs through the injected file access
-// ({ exists, list, read }, as `$.fs` provides). Never writes. A failing directory read is
-// transient (status 'failed'); a single unreadable run state is reported per run. Without a
-// control folder the snapshot names the checked project root, so the panel can say where it looked.
-export async function readSnapshot(fs, projectRoot, { now }) {
-  const runsDir = `${projectRoot}/.agdf/control/runs`;
+// Runs the command through the host and never throws: a process failure, a timeout or malformed
+// output is a failed snapshot with its cause, which the adapter settles as stale.
+export async function readSnapshot(processes, { pluginRoot, root, language, runIds = [], now, clock = () => Date.now() }) {
+  let ran;
+  const started = await clock();
   try {
-    if (!(await fs.exists(`${projectRoot}/.agdf/control`))) return { status: 'no_control', root: projectRoot, runs: [], unreadable: [], readAt: now };
-    if (!(await fs.exists(runsDir))) return { status: 'ok', runs: [], unreadable: [], readAt: now };
-    const folders = (await fs.list(runsDir)).filter(entry => entry.kind === 'dir' && !entry.isLink);
-    const results = await Promise.all(folders.map(folder => fs.read(`${runsDir}/${folder.name}/RUN_STATE.md`)
-      .then(text => parseRunState(folder.name, text), () => ({ ok: false, id: folder.name, reason: 'missing' }))));
-    return {
-      status: 'ok',
-      runs: results.filter(result => result.ok).map(result => result.run),
-      unreadable: results.filter(result => !result.ok).map(({ id, reason }) => ({ id, reason })),
-      readAt: now,
-    };
-  } catch (error) {
-    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: String(error?.message ?? error).slice(0, TEXT_LIMIT) };
+    ran = await processes.run(runViewArgv({ pluginRoot, root, language, runIds }), { timeoutMs: RUN_VIEW_TIMEOUT_MS });
+  } catch {
+    // `$.process.run` rejects when the command cannot start or is still running at the timeout; its
+    // message format is not specified, so the elapsed time tells the two apart (CR finding CIR-06).
+    const elapsed = (await clock()) - started;
+    return { status: 'failed', runs: [], unreadable: [], readAt: now, error: elapsed >= RUN_VIEW_TIMEOUT_MS ? 'timeout' : 'unavailable' };
   }
+  if (ran.exitCode !== 0 && ran.exitCode !== 2) return { status: 'failed', runs: [], unreadable: [], readAt: now, error: 'exit' };
+  return snapshotFromRunView(ran.stdout, { now });
 }
 
 // A transient failure keeps the last good snapshot, marked stale with the failed read time (AC-006).

package/generated/plugins/agdf/companion/state.mjs

@@ -1,37 +1,11 @@
-// State rules (AC-003, AC-002 of the follow-up): which of the five moods a run shows and why, as a
-// reason descriptor the view localizes. A run matching no rule is reported unreadable rather than
-// guessed (SDD-04).
+// Figure state of a run (SD SDD-004): the Core run view carries the derived mood and reason, so the
+// companion only overlays its own turn activity. It derives no run semantics itself.
 
-import { BUILD_GATES, isStructured } from './run-state.mjs';
+export const MOODS = Object.freeze(['laeuft', 'baut', 'wartet', 'blockiert', 'fertig', 'bereit']);
 
-export const MOODS = Object.freeze(['laeuft', 'baut', 'wartet', 'blockiert', 'fertig']);
-const BLOCKING = new Set(['revise', 'block', 'blocked', 'decline']);
-const AWAITING = new Set(['pending', 'awaiting_uat']);
-const WORKING = new Set(['in_progress', 'pass', 'qa_approved', 'completed']);
-
-// The gate a pending approval names, as in "Exact Approval: QA." or "Exact Approval: PRD for the new revision."
-export const pendingApproval = missing => String(missing ?? '').match(/\bApproval: (UR|PRD|SD|TP|QA|UAT|OR)\b/u)?.[1] ?? null;
-
-// The blocking outcome of a run: a legacy Run Meta decision, the current gate's recorded result
-// (`revise`, `block`, `blocked`) or a deliberate decision on its presented material.
-function blockingOutcome(run) {
-  if (BLOCKING.has(run.decision)) return run.decision;
-  if (run.gateResult) return run.gateResult;
-  return { reject: 'decline', request_change: 'revise' }[run.gateDecision] ?? null;
-}
-
-// { mood, reason: { key, gate?, decision? } } or { mood: null, reason: { key: 'unknownState' } }.
-// A structured run between an approved TP and QA (Brownfield Analysis, CD+Tests, CR) is being built.
+// { mood, reason: { key, gate?, decision?, reason? } } as the run view derived it.
 export function runState(run) {
-  if (run.lifecycle === 'completed') return { mood: 'fertig', reason: { key: 'done' } };
-  const outcome = blockingOutcome(run);
-  if (outcome) return { mood: 'blockiert', reason: { key: 'blocked', gate: run.gate, decision: outcome } };
-  const approval = pendingApproval(run.missing);
-  if (approval) return { mood: 'wartet', reason: { key: 'waitingApproval', gate: approval } };
-  if (AWAITING.has(run.decision)) return { mood: 'wartet', reason: { key: 'waitingDecision', gate: run.gate } };
-  if (WORKING.has(run.decision) && isStructured(run.route) && BUILD_GATES.includes(run.gate)) return { mood: 'baut', reason: { key: 'building', gate: run.gate } };
-  if (WORKING.has(run.decision)) return { mood: 'laeuft', reason: { key: 'working', gate: run.gate } };
-  return { mood: null, reason: { key: 'unknownState' } };
+  return run?.figure ?? { mood: 'bereit', reason: { key: 'idle' } };
 }
 
 // Moods a main-loop turn does not cover: a run being built stays baut, and a run waiting for an
@@ -43,6 +17,6 @@ const THROUGH_TURN = new Set(['baut', 'wartet']);
 // the turn.
 export function displayState(run, { isTurnActive = false } = {}) {
   const derived = runState(run);
-  if (isTurnActive && derived.mood !== null && !THROUGH_TURN.has(derived.mood)) return { mood: 'laeuft', reason: { key: 'turnActive' } };
+  if (isTurnActive && !THROUGH_TURN.has(derived.mood)) return { mood: 'laeuft', reason: { key: 'turnActive' } };
   return derived;
 }

package/generated/plugins/agdf/companion/view.mjs

@@ -3,81 +3,256 @@
 // host-independent; the adapter draws it on desktop or as text in the terminal.
 
 import { assignRun } from './assignment.mjs';
-import { FIGURE_TEXT } from './figure.mjs';
+import { FIGURE_TEXT, INVITE_TEXT } from './figure.mjs';
 import { condensedGateBar, gateBar, gateMarks } from './gate-bar.mjs';
-import { gateTitle, label, localizeNextStep } from './localization.mjs';
-import { displayState } from './state.mjs';
+import { gateRationale, gateTitle, label } from './localization.mjs';
+import { displayState, runState } from './state.mjs';
+import { isStructured, READ_FAILURE_REASONS } from './run-state.mjs';
+import { eventText, latestReview, PANE_EVENTS, shortDigest, shortRunId } from './events.mjs';
 
 const two = value => String(value).padStart(2, '0');
+// Preview lines the terminal text shows beneath the material line.
+export const TERMINAL_PREVIEW_LINES = 3;
 // Last part of a project root in either path form ("C:\Work\app\" → "app").
 const folderName = root => String(root ?? '').replace(/[\\/]+$/u, '').split(/[\\/]/u).pop() || String(root ?? '');
 // Host-local wall-clock time, HH:MM.
 export const clockText = ms => { const at = new Date(ms); return `${two(at.getHours())}:${two(at.getMinutes())}`; };
 
+// The name a person reads for the shown run: its stable title, else the catalog's "new run". The run
+// id never names a run; it stays a reference line at the panel's end.
+export const runName = (run, t) => run.title || t('fields.newRun');
+// A listed run needs a name that tells it from its neighbours, so an untitled one adds its short id.
+export const listedRunName = (run, t) => run.title || `${t('fields.newRun')} · ${shortRunId(run.id)}`;
+
+// Whose move it is (owner request of 2026-11-11): read from the figure state Core derived, so the
+// block never decides anything itself. `tone` is you (an approval or decision is yours), claude (the
+// agent works on the gate), next (the step is up next and nobody works on it) or halt (the run is
+// blocked). This function words the moves that are yours and the block; activityOf below words the work.
+// A state that concerns no gate work has no such block, and neither has the terminal's turn overlay
+// beside a run that is not working: its reason already says that Claude works.
+export function turnOf(state, run, t, gateName) {
+  const { key, gate, decision } = state.reason;
+  const at = gate ?? run.gate;
+  if (!at) return null;
+  if (key === 'waitingApproval') {
+    return { tone: 'you', who: t('turn.you'), what: t('turn.approve', { gate: gateName(at) }),
+      how: run.missing && run.missing !== 'none' ? t('turn.inChat', { approval: run.missing }) : null, gate: at };
+  }
+  if (key === 'waitingDecision') return { tone: 'you', who: t('turn.you'), what: t('turn.decide', { gate: gateName(at) }), how: null, gate: at };
+  if (key === 'blocked') {
+    return { tone: 'halt', who: t('turn.blocked'), what: t('reasons.blocked', { gate: gateName(at), decision: run.blockingText || decision || '' }), how: null, gate: at };
+  }
+  return null;
+}
+
+// Which kind of work a step is; the catalog's `activity` section words each kind once. A step the
+// table does not know is worded by its name.
+export const ACTIVITY_KINDS = Object.freeze({ UR: 'draft', PRD: 'draft', SD: 'draft', TP: 'draft',
+  'Brownfield Review': 'analysis', 'Brownfield Analysis': 'analysis', 'Mode/Slice Decision': 'route',
+  'CD+Tests': 'build', 'Quick Task Execution': 'build', 'Verified Change Execution': 'build',
+  CR: 'review', QA: 'quality', UAT: 'acceptance', OR: 'closeout' });
+
+// What a run is busy with (owner request of 2026-11-12: "läuft" named no activity). Read from the run's
+// own state, a step Claude works on or builds, never from the turn overlay. While a main-loop turn runs,
+// the line says what is being done and the block asks for a moment. Otherwise the run rests: the line
+// says what is up next and the block how to carry on. Returns { label, turn, resting } or null.
+export function activityOf(derived, run, isTurnActive, t, title) {
+  const { key, gate } = derived.reason;
+  const at = gate ?? run.gate;
+  if ((key !== 'working' && key !== 'building') || !at) return null;
+  const kind = ACTIVITY_KINDS[at] ?? 'other';
+  const named = title(at);
+  // A document or approval gate keeps its short name beside its title; an internal step has only a title.
+  const step = named !== at && /^[A-Z]{2,3}$/u.test(at) ? `${named} (${at})` : named;
+  const label = t(`activity.${kind}.${isTurnActive ? 'working' : 'idle'}`, { gate: at, step: named });
+  const drafting = kind === 'draft';
+  const turn = isTurnActive
+    ? { tone: 'claude', who: t('turn.moment'), what: drafting ? t('turn.drafting', { step }) : t('turn.workingOn', { step }), how: null, gate: at }
+    : { tone: 'next', who: t('turn.next'), what: drafting ? t('turn.draft', { step }) : step, how: t('turn.resume'), gate: at };
+  return { label, turn, resting: !isTurnActive };
+}
+
+// About two pane lines of the goal, cut at a word, so the block that asks for a move stays in sight.
+const GOAL_LINES = 2;
+export function goalLine(goal, columns) {
+  const room = Math.max(40, (Number.isFinite(columns) ? columns : 60) * GOAL_LINES);
+  if (goal.length <= room) return goal;
+  const cut = goal.slice(0, room - 1), at = cut.lastIndexOf(' ');
+  return `${(at > room / 2 ? cut.slice(0, at) : cut).replace(/[\s,;:.–-]+$/u, '')}…`;
+}
+
+// The delivery path and the position on it, e.g. "Strukturierte Lieferung · Schritt 2 von 8". Before
+// the path is decided only that is said; a path that names no current entry gives no position.
+export function routeLine(run, marks, t) {
+  const key = isStructured(run.route) ? 'structured' : run.route === 'quick_task' || run.route === 'verified_change' ? run.route
+    : (run.route === 'undecided' || run.route == null) && run.evaluated && run.lifecycle === 'active' ? 'undecided' : null;
+  if (!key) return null;
+  const at = marks.findIndex(({ mark }) => mark === 'current');
+  return key === 'undecided' || at < 0 ? t(`routes.${key}`) : `${t(`routes.${key}`)} · ${t('fields.step', { position: at + 1, count: marks.length })}`;
+}
+
 // input: { snapshot, sessionStartedAt, selection, mention, isBrowsing, isTurnActive, registry, labels,
-// locale, columns, isObjectiveExpanded }. Display only: the adapter persists selection changes.
+// locale, columns, isInfoExpanded, events, eventsAvailable }. Display only: the adapter persists
+// selection changes. `events` are this root's journal events since the last main-loop turn, newest first.
 export function buildPanelView(input) {
   const { snapshot, registry, labels, locale } = input;
   const t = (path, params) => label(labels, locale, path, params);
-  const base = { title: t('title'), locale, mood: 'neutral', stateLabel: t('states.neutral'),
+  const base = { title: t('title'), locale, mood: 'bereit', stateLabel: t('states.bereit'),
     readAt: snapshot ? t('fields.lastRead', { time: clockText(snapshot.readAt) }) : null,
     stale: snapshot?.stale ? t('messages.stale', { time: clockText(snapshot.stale.failedAt), readAt: clockText(snapshot.readAt) }) : null,
     canRetry: true, openRuns: [] };
-  const neutral = (message, extra = {}) => ({ ...base, message, ...extra });
+  // Event lines name only runs other than the shown one (owner request of 2026-11-06, T-013).
+  const events = shownRunId => eventFields(input, t, { shownRunId, runs: snapshot?.runs ?? [] });
+  const neutral = (message, extra = {}) => ({ ...base, ...events(null), message, ...extra });
   const unreadable = reason => neutral(t('messages.unreadable', { reason: t(`unreadable.${reason}`) }));
 
   if (!snapshot) return neutral(t('messages.reading'), { readAt: null });
-  if (snapshot.status === 'failed') return unreadable('failed');
+  if (snapshot.status === 'failed') {
+    const reason = READ_FAILURE_REASONS.includes(snapshot.error) ? snapshot.error : 'unavailable';
+    return neutral(t('messages.runViewUnavailable', { reason: t(`unreadable.${reason}`) }));
+  }
+  if (snapshot.status === 'unavailable') {
+    // An unsupported store names how many run folders it holds and why none is readable (AC-002).
+    const reason = snapshot.reason ?? 'read_failed';
+    return snapshot.runFolders
+      ? neutral(t('messages.unreadableRuns', { count: snapshot.runFolders, reasons: t(`unreadable.${reason}`) }))
+      : unreadable(reason);
+  }
   if (snapshot.status === 'no_control') {
-    return neutral(t('messages.noControl', { folder: folderName(snapshot.root) }), { hint: t('messages.noControlHint', { path: snapshot.root ?? '' }) });
+    // A project without AGDF is invited to start, not told about a missing folder (owner request of
+    // 2026-11-12): the figure holds the start sign, and the checked path and the finding sit behind the (i).
+    return neutral(t('messages.notSetUp'), { hint: t('messages.notSetUpHint'), invite: true, idle: true,
+      isInfoExpanded: Boolean(input.isInfoExpanded), info: [
+        { label: t('fields.checkedFolder'), text: snapshot.root ?? '' },
+        { label: t('fields.finding'), text: t('messages.noControl', { folder: folderName(snapshot.root) }) }] });
   }
 
   const { run, origin, open, chatRunId } = assignRun({ runs: snapshot.runs, sessionStartedAt: input.sessionStartedAt, selection: input.selection,
     mention: input.mention ?? null, isBrowsing: Boolean(input.isBrowsing) });
+  // Unreadable runs stay visible as a count with their reasons beside the readable ones (AC-002, AC-003).
+  const reasons = [...new Set(snapshot.unreadable.map(item => t(`unreadable.${item.reason}`)))].join(', ');
+  const unreadableHint = snapshot.unreadable.length ? t('messages.unreadableRuns', { count: snapshot.unreadable.length, reasons }) : null;
   // Each open run carries its condensed gate bar for the list (owner request of 2026-10-28).
-  const openRuns = open.map(item => ({ id: item.id, objective: item.objective, bar: condensedGateBar(gateMarks(item)) }));
+  const openRuns = open.map(item => ({ id: item.id, name: listedRunName(item, t), objective: item.objective, bar: condensedGateBar(gateMarks(item)) }));
   if (!run) {
     const broken = input.selection && snapshot.unreadable.find(item => item.id === input.selection);
-    if (broken) return { ...unreadable(broken.reason), openRuns, chatRunId };
-    if (!open.length) return neutral(t('messages.noOpenRuns'));
-    return neutral(t('messages.noRunAssigned'), { hint: t('messages.noRunAssignedHint'), openRuns, chatRunId,
+    if (broken) return { ...unreadable(broken.reason), openRuns, chatRunId, unreadableHint };
+    // A readable project without an assigned run idles: the figure blinks but shows no run state.
+    if (!open.length) {
+      if (unreadableHint) return neutral(unreadableHint, { idle: false });
+      const runs = snapshot.runs ?? [];
+      // "All done" only when every run completed; superseded or abandoned runs did not finish.
+      if (!runs.length) return neutral(t('messages.noRunsYet'), { idle: true, hint: t('messages.noRunsYetHint') });
+      if (runs.every(item => item.lifecycle === 'completed')) return neutral(t('messages.allRunsDone'), { idle: true, allDone: true, hint: t('messages.allRunsDoneHint') });
+      return neutral(t('messages.noOpenRuns'), { idle: true });
+    }
+    return neutral(t('messages.noRunAssigned'), { idle: true, hint: t('messages.noRunAssignedHint'), openRuns, chatRunId, unreadableHint,
       openCount: t('fields.openRuns', { count: open.length }) });
   }
 
   const position = open.findIndex(item => item.id === run.id);
   const openCount = position >= 0 ? t('fields.position', { position: position + 1, count: open.length }) : t('fields.openRuns', { count: open.length });
-  const state = displayState(run, { isTurnActive: input.isTurnActive });
-  // A run in an unknown state keeps stepping and the way back to the chat's run (CR-F01).
-  if (state.mood === null) return { ...unreadable('unknownState'), runId: run.id, openRuns, chatRunId, openCount };
-  const reasonParams = { gate: gateTitle(registry, locale, state.reason.gate), decision: t(`decisions.${state.reason.decision}`) };
+  const derived = runState(run);
+  const state = input.showRunState ? derived : displayState(run, { isTurnActive: input.isTurnActive });
+  const reasonParams = { gate: gateTitle(registry, locale, state.reason.gate), decision: run.blockingText || state.reason.decision,
+    reason: state.reason.reason ? t(`unreadable.${state.reason.reason}`) : '' };
+  // A gate by its localized title with its short name, e.g. "Produktanforderungen (PRD)".
+  const gateName = gate => { const title = gateTitle(registry, locale, gate); return title === gate ? gate : `${title} (${gate})`; };
+  const marks = gateMarks(run);
+  const name = runName(run, t);
+  const activity = activityOf(derived, run, Boolean(input.isTurnActive), t, gate => gateTitle(registry, locale, gate));
+  const turn = activity?.turn ?? turnOf(state, run, t, gateName);
+  // The goal in the display language; a goal that only repeats the name is not said twice.
+  const goal = run.goal || run.objective;
+  const objective = goal && goal !== name ? goal : '';
+  // What the gate in question decides; a blocked run names its block instead.
+  const rationale = turn && turn.tone !== 'halt' ? gateRationale(registry, locale, turn.gate) : null;
+  // A completed run names no next step, unless it is blocked: then the step says what to do about it.
+  const step = run.lifecycle === 'completed' && run.figure?.reason?.key !== 'blocked' ? null : run.nextText || null;
+  // For an approval the turn block already says what to do and how, so the next step only repeats it.
+  const stepRepeats = Boolean(step) && state.reason.key === 'waitingApproval' && Boolean(turn);
+  // The goal stands under the run's name, before whose move it is: it is what an approval is measured
+  // against (owner request of 2026-11-12). About two pane lines of it; the rest is behind the (i).
+  const goalShown = objective ? goalLine(objective, input.columns) : '';
+  // Details a person opens on purpose behind the (i): a goal that was cut, what the gate decides, and
+  // a next step that only repeats the approval. Closed by default.
+  const info = [
+    objective && goalShown !== objective ? { label: t('fields.objective'), text: objective } : null,
+    rationale ? { label: t('fields.gatePurpose'), text: rationale } : null,
+    stepRepeats ? { label: t('fields.nextStep'), text: step } : null,
+  ].filter(Boolean);
   return {
     ...base,
+    ...events(run.id),
+    ...(input.showRunState ? { figure: state } : {}),
     mood: state.mood,
-    stateLabel: t(`states.${state.mood}`),
+    workGate: input.showRunState && run.evaluated && !snapshot.stale ? run.gate : undefined,
+    // A working run names its activity; every other state keeps its word.
+    stateLabel: activity?.label ?? t(`states.${state.mood}`),
+    // The run rests: the step is up next and no main-loop turn works on it.
+    resting: activity?.resting === true,
     reason: t(`reasons.${state.reason.key}`, reasonParams),
-    gateBar: gateBar(gateMarks(run), input.columns),
+    gateBar: gateBar(marks, input.columns),
     runId: run.id,
-    objective: run.objective,
-    isObjectiveExpanded: Boolean(input.isObjectiveExpanded),
-    nextStep: run.lifecycle === 'completed' ? null : localizeNextStep(registry, locale, run.next).text,
+    name,
+    route: routeLine(run, marks, t),
+    turn,
+    rationale,
+    objective,
+    goal: goalShown,
+    info,
+    isInfoExpanded: Boolean(input.isInfoExpanded),
+    // The next step stays in sight where it says something the turn block does not.
+    nextStep: stepRepeats ? null : step,
+    unreadableHint,
     origin: t(`origin.${origin}`),
     originKind: origin,
     chatRunId,
     openRuns,
     openCount,
+    drift: run.drift?.length ? run.drift.map(item => t('messages.drift', { document: item.document,
+      recorded: shortDigest(item.recorded_digest), current: shortDigest(item.current_digest) })) : null,
+  };
+}
+
+// Pane entries of the journal (decision P1) and the review facts of the newest staging or recording
+// (decision P2); without a readable journal the pane says so and invents nothing. `naming` is
+// { shownRunId, runs }: the shown run's events name no run.
+function eventFields(input, t, naming) {
+  const events = (input.events ?? []).slice(0, PANE_EVENTS);
+  const gate = value => gateTitle(input.registry, input.locale, value);
+  return {
+    events: events.length ? events.map(event => `${clockText(Date.parse(event.at))} ${eventText(event, t, { gateTitle: gate, ...naming })}`) : null,
+    review: latestReview(events, t),
+    eventsHint: input.eventsAvailable === false ? t('messages.eventsUnavailable') : null,
   };
 }
 
 // Text fallback for surfaces without Svg: state, gate bar and next step on separate lines.
 export function terminalText(view, { labels, locale }) {
   const t = path => label(labels, locale, path);
-  const lines = [view.title, `${FIGURE_TEXT[view.mood]} ${view.stateLabel}${view.reason ? ` · ${view.reason}` : ''}`];
+  // The turn line says what the reason would; without one the reason stays beside the state.
+  const lines = [view.title, `${view.invite ? INVITE_TEXT : FIGURE_TEXT[view.mood]} ${view.stateLabel}${view.reason && !view.turn ? ` · ${view.reason}` : ''}`];
   if (view.message) lines.push(view.message);
   if (view.hint) lines.push(view.hint);
+  if (view.unreadableHint && view.unreadableHint !== view.message) lines.push(view.unreadableHint);
+  if (view.name) lines.push(view.route ? `${view.name} · ${view.route}` : view.name);
+  if (view.goal) lines.push(`${t('fields.objective')}: ${view.goal}`);
+  if (view.turn) lines.push(`${view.turn.who}: ${view.turn.what}${view.turn.how ? ` · ${view.turn.how}` : ''}`);
   if (view.gateBar) lines.push(view.gateBar);
-  if (view.runId) lines.push(view.origin ? `${view.runId} · ${view.origin}` : view.runId);
-  if (view.objective) lines.push(`${t('fields.objective')}: ${view.objective}`);
   if (view.nextStep) lines.push(`${t('fields.nextStep')}: ${view.nextStep}`);
+  // The (i) details appear only once opened; its button is drawn beside this text.
+  if (view.isInfoExpanded) for (const item of view.info ?? []) lines.push(`${item.label}: ${item.text}`);
+  for (const warning of view.drift ?? []) lines.push(warning);
+  if (view.events) lines.push(`${t('fields.events')}:`, ...view.events);
+  if (view.review) {
+    lines.push(`${t('fields.material')}: ${view.review.summary} · ${view.review.match}${view.review.truncated ? ` · ${view.review.truncated}` : ''}`);
+    // The terminal shows the start of the preview too (PRD M1, AC-007; CR finding B10).
+    if (view.review.preview) lines.push(...view.review.preview.split('\n').slice(0, TERMINAL_PREVIEW_LINES).map(line => `  ${line}`));
+  }
+  if (view.eventsHint) lines.push(view.eventsHint);
+  // The run id is a reference, so it stands after what a person reads.
+  if (view.runId) lines.push(view.origin ? `${view.runId} · ${view.origin}` : view.runId);
   if (view.stale) lines.push(view.stale);
   if (view.readAt) lines.push(view.readAt);
   return lines.join('\n');

package/generated/plugins/agdf/control/README.md

@@ -11,6 +11,7 @@ Explicit initialization creates `control_layout: "run-folders-v1"`. This is the
   SOT_REGISTRY.md
   CONTEXT_GRAPH.md
   AGENT_QUALITY_CONTRACTS.json
+  BRAND.md
   templates/
   planned/<plan_id>/UR.md
   runs/<run_id>/
@@ -28,6 +29,10 @@ Explicit initialization creates `control_layout: "run-folders-v1"`. This is the
 
 Configuration, templates and curated project context stay project-wide. A multi-Run closure preview is a target-wide decision proposal under `closure-previews/`; it changes no Run until deliberately applied. Run-owned outputs never use a separate top-level artefacts directory.
 
+`BRAND.md` starts as a neutral English worksheet. Complete it with the project's
+own design intent and declare the finished source in `SOT_REGISTRY.md` when it is
+authoritative for design work.
+
 `RUN_STATE.md` keeps identity, objective, mode and typed decisions, source bindings and operations. Approval status, current gate, current document references, relationship chains, evidence summaries and inventory are derived when read. They are not separately writable tables or a second state file. A binding embeds its reviewer attestation; no separate RECORD/REVIEW JSON repeats its mapping. A planned handoff records its source in the creation receipt and immutable planning snapshot, without an origin JSON copy.
 
 Create a fresh scaffold in an explicitly confirmed existing Git repository:

package/generated/plugins/agdf/control/templates/BRAND.md

@@ -0,0 +1,28 @@
+# Brand and Design Intent
+
+Complete this worksheet with confirmed project decisions. Declare the completed
+profile in `SOT_REGISTRY.md` when it is the project's authoritative design source.
+
+## Owner and scope
+
+Name the accountable owner, the product, and the surfaces and audiences covered.
+
+## Design intent
+
+Describe what people should understand, feel, or be able to do when using the
+product. Tie each priority to a concrete user task or situation.
+
+## Information and visual priorities
+
+Explain what deserves emphasis in relevant states and how the project balances
+competing priorities. Record any confirmed constraints and their sources.
+
+## Observable checks
+
+For each applicable priority, name the scenario, the expected observable outcome,
+and the evidence that would verify it. Record open decisions with their owners.
+
+## Related sources
+
+Link the project's design system, implementation values, and brand usage policy
+where applicable.

package/generated/plugins/agdf/control/templates/artefacts/PRD.md

@@ -69,6 +69,17 @@ visible feedback, blocker/failure behavior, recovery/next action, observable suc
 evidence. Specify observable behavior, not implementation. Do not leave the section empty or retain
 placeholders when requesting approval.
 
+Use separate field names; never combine them (for example,
+`observable_success_required_evidence` is not `observable_success`). For same-language approval,
+each criterion needs at least one nonempty `observable_success`, `visible_feedback` or
+`expected_effective_state`. Keep applicable UX fields separate as well. Example:
+
+```markdown
+- criterion_id: AC-001
+  - observable_success: A later list command shows the saved task unchanged.
+  - required_evidence: A real CLI test across separate processes.
+```
+
 ## 6. Non-Goals
 
 What remains out of scope?