create-agdf 0.20.1 → 0.30.0

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

@@ -0,0 +1,444 @@
+// AGDF Companion host adapter (SDD-07 to SDD-10; follow-up SDD-05 to SDD-12): the `/agdf-companion`
+// command, the persisted choices, main-loop turn observation, the refresh cadence, the own pane, the
+// status line and toasts. Observation only: no gating hook, every hook passes its event on through a
+// catch path, and nothing is written under .agdf/control. Session state lives in this module and is
+// redrawn through `$.ui.invalidate`. Elements come from the surface table and are built with the
+// host's global `h`.
+
+import { assignRun, namedRun, openRuns, stepSelection } from './assignment.mjs';
+import { figureSvg } from './figure.mjs';
+import { chatLocale, label } from './localization.mjs';
+import { CHIME, chimeClip, noticeText, observeNotice, observedRun, statusText } from './notice.mjs';
+import { STATE_FILE, defaultCompanionState, parseCompanionState, pluginDataDir, serializeCompanionState } from './persistence.mjs';
+import { readSnapshot, settleSnapshot } from './run-state.mjs';
+import { buildPanelView, terminalText } from './view.mjs';
+
+export const PANE = 'agdf-companion';
+export const COMMAND = 'agdf-companion';
+export const REFRESH_MS = 30_000;
+export const MENU = 'menu';
+export const ABOUT_URL = 'https://agdf.iself.eu';
+const LISTED_RUNS = 6;
+// The surfaces whose element table has a picker; the mobile app draws none and turns one into an empty
+// box (`claude plugin test` 2.1.302), so its table entry alone does not decide.
+const PICKER_SURFACES = new Set(['terminal', 'desktop', 'vscode']);
+// Body rows the desktop spends around the run list, measured live on 2026-10-28 (a body row is about
+// 28 px): the figure with its state and reason, the framed footer with its picker, the About block,
+// the space between two blocks, and one spare row, since a body taller than the pane scrolls.
+const DESKTOP_ROWS = Object.freeze({ figure: 7, footer: 2, about: 7, gap: 0.6, spare: 1 });
+// Rows the desktop body leaves below the pane's body rows. The T-001 probe of 2026-10-28 showed no
+// scrollbar for a framed footer at 0, 0.25, 0.5 and 1 row in the narrow, widened and taller pane, so
+// the smallest reserve applies (chat-run navigation SDD-08).
+const BODY_RESERVE = 0;
+// Listed runs show their condensed gate bars beside the ids while at least this many characters of an id
+// stay beside the widest bar (owner request of 2026-10-28); a narrower pane lists the ids alone.
+const ID_ROOM = 18;
+const COLOR = Object.freeze({ laeuft: 'suggestion', baut: 'suggestion', wartet: 'warning', blockiert: 'error', fertig: 'success' });
+
+function createSession() {
+  return { startedAt: 0, root: '', registry: null, labels: null, locale: 'en', statePath: null, version: null, icon: null,
+    choices: defaultCompanionState(), isHidden: false, snapshot: null, isTurnActive: false, isObjectiveExpanded: false,
+    isAboutShown: false, isMenuOpen: false, timer: null, reads: 0, appliedRead: 0, observation: null,
+    chatMention: null, isBrowsing: false, conversation: null };
+}
+
+// One companion per session: the module is loaded once per session.
+const session = createSession();
+const t = (path, params) => label(session.labels, session.locale, path, params);
+const selection = () => session.choices.selections[session.root] ?? null;
+const redraw = $ => $.ui.invalidate('ui.render');
+// File access for the host-independent reader, each call spelled on `$` (read-only).
+const files = $ => ({ exists: path => $.fs.exists(path), list: path => $.fs.list(path), read: path => $.fs.read(path) });
+
+// Applies one change to this session's choices and, where the AGDF plugin data directory already
+// exists, to the freshly read state file, so choices another session stored meanwhile survive.
+// Without the directory the choices last for this session (SDD-07). The state file is the module's
+// only write. `change` sets values, never toggles, because it runs on both copies.
+async function persist($, change) {
+  change(session.choices);
+  if (!session.statePath) return;
+  const dir = session.statePath.slice(0, -STATE_FILE.length - 1);
+  if (!(await $.fs.exists(dir))) return;
+  const stored = (await $.fs.exists(session.statePath)) ? parseCompanionState(await $.fs.read(session.statePath)) : defaultCompanionState();
+  change(stored);
+  await $.fs.write(session.statePath, serializeCompanionState(stored));
+}
+
+// The status line and toasts follow the run-derived state of the run the panel shows without browsing,
+// so browsing never changes them (follow-up SDD-05 to SDD-07; chat-run navigation SDD-06). A stale snapshot keeps the last observation, so a failed read never
+// announces anything. Each host call has its own catch path: a missing channel stays silent (SDD-12).
+function announce($) {
+  const observed = observedRun({ snapshot: session.snapshot, sessionStartedAt: session.startedAt, selection: selection(),
+    mention: session.chatMention });
+  // Every applied read sets the line again, unchanged text included: the desktop dropped the one set
+  // during session start, before its surface was attached (live finding of 2026-10-27).
+  try { $.ui.status(statusText(observed, { labels: session.labels, locale: session.locale })); } catch { /* no status line on this host */ }
+  if (session.snapshot?.stale) return;
+  const { observation, notice } = observeNotice(session.observation, observed);
+  session.observation = observation;
+  if (!notice || !session.choices.notice) return;
+  try {
+    $.ui.toast(noticeText(observed.runId, notice, { registry: session.registry, labels: session.labels, locale: session.locale }));
+  } catch {
+    return; // no toast on this host, and so no chime either (CR-F01)
+  }
+  // The chime plays only with a shown toast; a host without a player skips it, a failure stays silent.
+  if (session.choices.sound) {
+    try { $.audio.play(chimeClip(), { gain: CHIME.gain }).catch(() => {}); } catch { /* no audio on this host */ }
+  }
+}
+
+// Switching off clears the status line, forgets the observation and discards reads still running, so
+// switching on starts from a fresh baseline without a toast (CR-F02).
+function silence($) {
+  session.observation = null;
+  session.appliedRead = session.reads + 1;
+  try { $.ui.status(undefined); } catch { /* no status line on this host */ }
+}
+
+// Reads the run states of the current project root, which `/cd` or a worktree move can change.
+// Only the newest of overlapping reads is applied. A snapshot without any runs, as during a branch
+// switch, never drops the remembered selection.
+async function refresh($) {
+  const read = ++session.reads;
+  try {
+    const root = await $.session.root();
+    await followConversation($);
+    const next = await readSnapshot(files($), root, { now: await $.clock.now() });
+    if (read < session.appliedRead) return;
+    session.appliedRead = read;
+    session.root = root;
+    session.snapshot = settleSnapshot(session.snapshot, next);
+    const chosen = selection();
+    if (chosen && next.status === 'ok' && next.runs.length) {
+      const { dropSelection } = assignRun({ runs: next.runs, sessionStartedAt: session.startedAt, selection: chosen });
+      if (dropSelection && !next.unreadable.some(item => item.id === chosen)) await persist($, choices => { delete choices.selections[root]; });
+    }
+  } catch (error) {
+    if (read < session.appliedRead) return;
+    session.appliedRead = read;
+    session.snapshot = settleSnapshot(session.snapshot, { status: 'failed', runs: [], unreadable: [], readAt: Date.now(), error: String(error?.message ?? error) });
+  }
+  if (session.choices.enabled) announce($);
+  redraw($);
+}
+
+// Takes the last open run a main-loop text names as the chat's run at host time `at` (chat-run navigation
+// SDD-01, SDD-02). Returns whether a mention was recorded: a repeated name can still move the chat's run
+// back from a later change, so every recorded mention is announced (CR-F02).
+function noteMention(text, at) {
+  const runs = session.snapshot?.status === 'ok' ? session.snapshot.runs : [];
+  const runId = namedRun(text, openRuns(runs).map(run => run.id));
+  if (!runId) return false;
+  session.chatMention = { runId, at };
+  return true;
+}
+
+// A `/clear` or a resumed transcript starts a new conversation without `session.start`: it starts without
+// a chat run and counts changes from its own start (CR-F03). A host without the id keeps the session's.
+async function followConversation($) {
+  let conversation = session.conversation;
+  try { conversation = await $.session.id(); } catch { /* no conversation id on this host */ }
+  if (session.conversation && conversation !== session.conversation) {
+    session.chatMention = null;
+    session.isBrowsing = false;
+    session.observation = null;
+    session.startedAt = await $.clock.now();
+  }
+  session.conversation = conversation;
+}
+
+function stopRefreshing() {
+  session.timer?.cancel();
+  session.timer = null;
+}
+
+// The timer is replaced before the first read, so overlapping starts never leave a second timer.
+async function startRefreshing($) {
+  stopRefreshing();
+  session.timer = $.clock.every(REFRESH_MS, () => { void refresh($); });
+  await refresh($);
+  return $.ui.open({ id: PANE, title: t('title') });
+}
+
+const openedText = opened => (opened?.isPlaced === false ? t('command.waiting', { reason: opened.reason }) : t('command.enabled'));
+
+async function loadSession($) {
+  session.startedAt = await $.clock.now();
+  session.root = await $.session.root();
+  session.labels = JSON.parse(await $.fs.read(`${$.plugin.root}/companion/locales.json`));
+  session.registry = JSON.parse(await $.fs.read(`${$.plugin.root}/meta/agdf-interaction-locales.json`));
+  const config = `${session.root}/.agdf/control/config.json`;
+  const configText = (await $.fs.exists(config)) ? await $.fs.read(config) : null;
+  // Without AGDF control, Claude's own `language` setting chooses the language (follow-up SDD-11).
+  let setting = null;
+  if (configText === null) {
+    try { setting = await $.settings.read({ key: 'language' }); } catch { /* no setting: the fallback locale */ }
+  }
+  session.locale = chatLocale(session.registry, configText, { setting, labels: session.labels });
+  // The About entry names the plugin version; a missing or unreadable manifest only leaves it out.
+  try {
+    const { version } = JSON.parse(await $.fs.read(`${$.plugin.root}/.claude-plugin/plugin.json`));
+    session.version = typeof version === 'string' ? version : null;
+  } catch { /* no version shown */ }
+  // The footer shows the plugin's own AGDF icon; without it the footer starts with the name.
+  try {
+    const icon = await $.fs.read(`${$.plugin.root}/assets/agdf-icon.svg`);
+    session.icon = icon.trimStart().startsWith('<svg') ? icon : null;
+  } catch { /* no icon shown */ }
+  const dir = pluginDataDir({ configDir: await $.env.get('CLAUDE_CONFIG_DIR'), userProfile: await $.env.get('USERPROFILE'), home: await $.env.get('HOME') });
+  session.statePath = dir ? `${dir}/${STATE_FILE}` : null;
+  if (session.statePath && (await $.fs.exists(session.statePath))) session.choices = parseCompanionState(await $.fs.read(session.statePath));
+}
+
+const wrappedRows = (value, columns) => (value ? Math.ceil(value.length / Math.max(columns, 10)) : 0);
+
+// How many open runs the desktop list shows: the body rows left beside the other blocks, never fewer
+// than the terminal's six (the pane then scrolls). One row of them goes to "+ N more" when runs remain.
+export function listCapacity(view, { rows, columns, isAboutShown = false }) {
+  const blocks = [view.message, view.hint, view.stale].filter(Boolean);
+  const fixed = DESKTOP_ROWS.figure + DESKTOP_ROWS.footer + DESKTOP_ROWS.spare + (isAboutShown ? DESKTOP_ROWS.about : 0) + 1
+    + blocks.reduce((sum, value) => sum + wrappedRows(value, columns), 0) + DESKTOP_ROWS.gap * (blocks.length + 3);
+  return Math.max(LISTED_RUNS, Math.floor(rows - fixed));
+}
+
+// A run id shortened in the middle to `room` characters, so its date and sequence stay readable.
+export function fitRunId(id, room) {
+  if (id.length <= room) return id;
+  const tail = Math.min(12, Math.floor((room - 1) / 2));
+  return `${id.slice(0, room - 1 - tail)}…${id.slice(id.length - tail)}`;
+}
+
+const press = ($, action) => async () => {
+  try { await action(); } catch { /* a failed action leaves the last drawing */ }
+  redraw($);
+};
+
+function body($, e, view) {
+  const { Box, Text, Button, Svg, Link, Select } = $.ui.resolve(e);
+  const isTerminal = e.surface === 'terminal' || !Svg;
+  const rows = e.props?.scroll?.bodyRows;
+  const fits = Number.isInteger(rows) && rows > 0;
+  const columns = Number.isInteger(e.props?.bodyColumns) ? e.props.bodyColumns : 40;
+  const select = runId => press($, async () => {
+    const root = session.root;
+    // A pick of another run than the chat's browses until the next main-loop turn (SDD-04, CR-F07).
+    if (view.chatRunId) session.isBrowsing = runId !== view.chatRunId;
+    await persist($, choices => { choices.selections[root] = runId; });
+    await refresh($);
+  });
+  const step = offset => press($, async () => {
+    const next = stepSelection(view.openRuns, view.runId ?? selection(), offset);
+    if (next) await select(next)();
+  });
+  const toggle = key => async () => { const value = !session.choices[key]; await persist($, choices => { choices[key] = value; }); };
+  // While another run than the chat's run is shown, the menu offers the way back first (SDD-05).
+  const canReturn = Boolean(view.chatRunId) && view.runId !== view.chatRunId;
+  const back = async () => { session.isBrowsing = false; };
+  const commands = [
+    ...(canReturn ? [['chat', t('actions.backToChat'), back]] : []),
+    ['still', session.choices.still ? t('actions.stillOff') : t('actions.stillOn'), toggle('still')],
+    ['retry', t('actions.retry'), () => refresh($)],
+    ['notice', session.choices.notice ? t('actions.noticeOff') : t('actions.noticeOn'), toggle('notice')],
+    ['sound', session.choices.sound ? t('actions.soundOff') : t('actions.soundOn'), toggle('sound')],
+    ['about', t('actions.about'), async () => { session.isAboutShown = true; }],
+  ];
+  // The actions open from the panel's foot (owner requests of 2026-10-28): the AGDF icon, the menu and
+  // the read time at the right edge, set off by a dim frame (a dim line on the terminal). Where the
+  // surface has a picker, the app draws the open menu itself as a popover above the footer; the picker
+  // always shows its neutral entry, the name, so every pick runs its action. The mobile app draws no
+  // picker and gets the name as a plain button that opens the entries above the footer.
+  const hasPicker = Boolean(Select) && PICKER_SURFACES.has(e.surface);
+  const run = action => press($, async () => { session.isMenuOpen = false; await action(); });
+  const trigger = hasPicker
+    ? h(Select, { key: MENU, value: MENU, options: [{ value: MENU, label: t('title') }, ...commands.map(([value, text]) => ({ value, label: text }))],
+      onSelect: value => { const command = commands.find(([key]) => key === value); return command ? run(command[2])() : undefined; } })
+    : h(Button, { key: MENU, plain: true, label: `${t('title')} ${session.isMenuOpen ? '▴' : '▾'}`,
+      onPress: press($, async () => { session.isMenuOpen = !session.isMenuOpen; }) });
+  const entries = !hasPicker && session.isMenuOpen
+    ? h(Box, { flexDirection: 'column', alignItems: 'flex-start', ...(isTerminal ? {} : { borderStyle: 'single', borderDimColor: true, paddingX: 1 }) },
+      ...commands.map(([key, text, action]) => h(Button, { key, plain: true, label: text, onPress: run(action) })))
+    : null;
+  const footer = h(Box, { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', gap: 1,
+    ...(isTerminal ? {} : { borderStyle: 'single', borderDimColor: true, paddingX: 1 }) },
+    h(Box, { flexDirection: 'row', alignItems: 'center', gap: 1, flexShrink: 1 },
+      !isTerminal && session.icon ? h(Svg, { source: session.icon, alt: 'AGDF', width: 20, height: 20 }) : null,
+      trigger),
+    view.readAt ? h(Box, { flexShrink: 0 }, h(Text, { dimColor: true }, view.readAt)) : null);
+  const actions = h(Box, { flexDirection: 'column', gap: isTerminal ? 0 : 1, flexShrink: 0 }, entries,
+    isTerminal ? h(Text, { dimColor: true }, '─'.repeat(Math.min(columns, 40))) : null, footer);
+  const about = session.isAboutShown ? h(Box, { flexDirection: 'column' },
+    h(Text, { weight: 'semibold' }, t('title')),
+    h(Text, { dimColor: true }, t('about.text')),
+    session.version ? h(Text, { dimColor: true }, t('about.version', { version: session.version })) : null,
+    Link ? h(Link, { href: ABOUT_URL, label: ABOUT_URL.slice('https://'.length) }) : h(Text, {}, ABOUT_URL),
+    h(Button, { key: 'about-close', plain: true, label: t('actions.closeAbout'), onPress: press($, async () => { session.isAboutShown = false; }) })) : null;
+  const capacity = !isTerminal && fits ? listCapacity(view, { rows: rows - BODY_RESERVE, columns, isAboutShown: session.isAboutShown }) : LISTED_RUNS;
+  // The terminal keeps its six; the desktop lists as many as fit and gives the last row to "+ N more".
+  const listed = isTerminal ? view.openRuns.slice(0, LISTED_RUNS)
+    : view.openRuns.length <= capacity ? view.openRuns : view.openRuns.slice(0, capacity - 1);
+  // One listed run: the id as a plain button and, where the pane has room for the widest listed bar, its
+  // condensed gate bar at the right edge, every id shortened to the same room (the same rule for all rows,
+  // live check of 2026-10-28). The bar keeps its width; an id that still runs over is cut by the surface.
+  const widest = Math.max(0, ...listed.map(run => run.bar?.length ?? 0));
+  const room = columns - widest - 2;
+  const withBars = widest > 0 && room >= ID_ROOM;
+  const runRow = run => {
+    const id = h(Button, { key: `run-${run.id}`, plain: true, label: withBars ? fitRunId(run.id, room) : run.id, onPress: select(run.id) });
+    return withBars && run.bar
+      ? h(Box, { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center', gap: 1 },
+        h(Box, { flexShrink: 1 }, id), h(Box, { flexShrink: 0 }, h(Text, { dimColor: true, mono: true }, run.bar)))
+      : id;
+  };
+  // The stepping row stands under every shown run, the chat's run included (SDD-04).
+  const runList = view.openRuns.length
+    ? (view.runId
+      // The count has its own line, so the two stepping buttons fit the default width. The desktop
+      // draws a Button's label, which also names it, so the label is the visible localized text.
+      ? h(Box, { flexDirection: 'column' },
+        h(Text, { dimColor: true }, view.openCount),
+        h(Box, { flexDirection: 'row', gap: 1, alignItems: 'center' },
+          h(Button, { key: 'previous', label: t('actions.previous'), onPress: step(-1) }),
+          h(Button, { key: 'next', label: t('actions.next'), onPress: step(1) })),
+        canReturn ? h(Button, { key: 'chat-return', plain: true, label: t('actions.backToChat'), onPress: press($, back) }) : null)
+      : h(Box, { flexDirection: 'column' },
+        h(Text, { dimColor: true }, view.openCount),
+        ...listed.map(runRow),
+        !isTerminal && view.openRuns.length > listed.length ? h(Text, { dimColor: true }, t('fields.moreRuns', { count: view.openRuns.length - listed.length })) : null))
+    : null;
+  if (isTerminal) {
+    return h(Box, { flexDirection: 'column', gap: 1 },
+      h(Text, { color: COLOR[view.mood] }, terminalText(view, { labels: session.labels, locale: session.locale })), runList, about, actions);
+  }
+  const figure = h(Svg, { source: figureSvg(view.mood, { still: session.choices.still, title: `${view.title}: ${view.stateLabel}` }),
+    alt: `${view.title}: ${view.stateLabel}`, width: 200, height: 140, isInteractive: !session.choices.still });
+  // The body is as tall as the pane's body rows less the probed reserve and the content grows, so the
+  // footer sits at the bottom edge; a taller body scrolls with the footer last (live probes of
+  // 2026-10-28: a cell count sizes the body, a percentage does not; SDD-08).
+  return h(Box, { flexDirection: 'column', gap: 1, ...(fits ? { minHeight: rows - BODY_RESERVE } : {}) }, h(Box, { flexDirection: 'column', gap: 1, flexGrow: 1 },
+    h(Box, { flexDirection: 'column', alignItems: 'center' },
+      figure,
+      h(Text, { color: COLOR[view.mood], size: 'heading', weight: 'bold' }, view.stateLabel),
+      view.reason ? h(Text, { dimColor: true, wrap: 'truncate-end' }, view.reason) : null),
+    view.message ? h(Text, {}, view.message) : null,
+    view.hint ? h(Text, { dimColor: true }, view.hint) : null,
+    view.gateBar ? h(Text, { mono: true, wrap: 'truncate-end' }, view.gateBar) : null,
+    view.runId ? h(Box, { flexDirection: 'column' },
+      h(Text, { weight: 'semibold', wrap: 'truncate-end' }, view.runId),
+      view.origin ? h(Text, { dimColor: true }, view.origin) : null) : null,
+    view.objective ? h(Box, { flexDirection: 'row', gap: 1, alignItems: 'center' },
+      h(Text, { dimColor: true, wrap: view.isObjectiveExpanded ? 'wrap' : 'truncate-end' }, view.objective),
+      h(Button, { key: 'objective', plain: true, label: view.isObjectiveExpanded ? t('actions.collapse') : t('actions.expand'),
+        onPress: press($, async () => { session.isObjectiveExpanded = !session.isObjectiveExpanded; }) })) : null,
+    view.nextStep ? h(Box, { flexDirection: 'column' },
+      h(Text, { dimColor: true }, t('fields.nextStep')),
+      h(Text, {}, view.nextStep)) : null,
+    runList,
+    view.stale ? h(Text, { color: 'warning' }, view.stale) : null,
+    about),
+    actions);
+}
+
+// Each registration carries a `.catch` that passes the event on, so even an overrun or a
+// misreturn leaves the host's own behaviour in place (SDD-10).
+const passOn = ($, e, next) => next(e);
+
+export const register = on => {
+  on('session.start', async ($, e, next) => {
+    try {
+      await loadSession($);
+      await $.command.register({ name: COMMAND, description: t('command.description'), immediate: true });
+      if (session.choices.enabled) await startRefreshing($);
+    } catch { /* the companion stays unavailable; AGDF is unaffected (SDD-10) */ }
+    return next(e);
+  }).catch(passOn);
+
+  on('command.run', { command: COMMAND }, async $ => {
+    try {
+      // A pane the person hid for this session comes back; the stored choice stays as it is.
+      if (session.choices.enabled && session.isHidden) {
+        session.isHidden = false;
+        return { text: openedText(await startRefreshing($)) };
+      }
+      const enabled = !session.choices.enabled;
+      if (!enabled) {
+        // Reading, the status line and the pane stop before the choice is stored, so a failing write
+        // leaves none of them running (CR-F03); the choice is stored even if closing the pane fails.
+        stopRefreshing();
+        silence($);
+        try {
+          await $.ui.close({ id: PANE });
+        } finally {
+          await persist($, choices => { choices.enabled = false; });
+        }
+        return { text: t('command.disabled') };
+      }
+      await persist($, choices => { choices.enabled = true; });
+      session.isHidden = false;
+      return { text: openedText(await startRefreshing($)) };
+    } catch (error) {
+      return { text: `${COMMAND}: ${String(error?.message ?? error).slice(0, 200)}` };
+    }
+  }).catch(() => ({ text: `${COMMAND}: unavailable` }));
+
+  on('turn.start', async ($, e, next) => {
+    try {
+      if (e.agentId === undefined && session.choices.enabled) {
+        // A main-loop turn ends browsing and may name the chat's run (chat-run navigation SDD-02, SDD-04);
+        // the host clock is read beside the event, never before it is passed on (SDD-11).
+        session.isBrowsing = false;
+        if (!session.isHidden) session.isTurnActive = true;
+        redraw($);
+        const prompt = e.text;
+        void $.clock.now().then(at => { if (noteMention(prompt, at)) { announce($); redraw($); } }).catch(() => {});
+      }
+    } catch { /* observation only */ }
+    return next(e);
+  }).catch(passOn);
+
+  on('turn.complete', async ($, e, next) => {
+    const answered = await next(e);
+    try {
+      if (e.agentId === undefined) {
+        // Cleared on every main-loop completion, also while switched off, so no stale overlay remains.
+        session.isTurnActive = false;
+        // The read runs after the host has its answer, never inside the hook; a hidden pane keeps
+        // the status line and toasts current (follow-up SDD-08). The turn's final answer (`e.answer`,
+        // else the text `next(e)` returned) is matched against that read at the turn's end time, so a
+        // run created during the turn counts (CR-F05, CR-F06).
+        if (session.choices.enabled) {
+          const answer = typeof e.answer === 'string' ? e.answer : answered?.text;
+          void (async () => {
+            const at = await $.clock.now();
+            await refresh($);
+            if (session.choices.enabled && noteMention(answer, at)) { announce($); redraw($); }
+          })().catch(() => {});
+        }
+      }
+    } catch { /* observation only */ }
+    return answered;
+  }).catch(passOn);
+
+  // Closing the pane by its own mark hides only the pane for this session (SDD-07); reading goes on
+  // for the status line and toasts until the companion is switched off (follow-up SDD-08). The host
+  // stamps `origin` as `{ kind: 'plugin' | 'person' | 'unload' }`.
+  on('ui.close', { id: PANE }, async ($, e, next) => {
+    try {
+      if (e.origin?.kind === 'person') session.isHidden = true;
+    } catch { /* observation only */ }
+    return next(e);
+  }).catch(passOn);
+
+  // A logic failure draws a neutral line instead of the panel; it never throws into the host.
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    try {
+      return body($, e, buildPanelView({ snapshot: session.snapshot, sessionStartedAt: session.startedAt, selection: selection(),
+        mention: session.chatMention, isBrowsing: session.isBrowsing,
+        isTurnActive: session.isTurnActive, registry: session.registry, labels: session.labels, locale: session.locale,
+        columns: e.props?.bodyColumns ?? Infinity, isObjectiveExpanded: session.isObjectiveExpanded }));
+    } catch (error) {
+      const { Text } = $.ui.resolve(e);
+      return h(Text, { dimColor: true }, `AGDF Companion: ${String(error?.message ?? error).slice(0, 200)}`);
+    }
+  });
+};

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

@@ -0,0 +1,110 @@
+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.
+
+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 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;
+
+// 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');
+}
+
+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);
+}
+
+// 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),
+  }) };
+}
+
+// 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`;
+  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) };
+  }
+}
+
+// A transient failure keeps the last good snapshot, marked stale with the failed read time (AC-006).
+export function settleSnapshot(previous, next) {
+  if (next.status !== 'failed' || !previous || previous.status === 'failed') return next;
+  return { ...previous, stale: { failedAt: next.readAt, error: next.error } };
+}

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

@@ -0,0 +1,48 @@
+// 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).
+
+import { BUILD_GATES, isStructured } from './run-state.mjs';
+
+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.
+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' } };
+}
+
+// Moods a main-loop turn does not cover: a run being built stays baut, and a run waiting for an
+// approval or a decision stays wartet, since the chat usually asks for it during that turn (chat-run
+// navigation SDD-07). A blocked run shows läuft, since the chat usually resolves it.
+const THROUGH_TURN = new Set(['baut', 'wartet']);
+
+// A main-loop turn in progress shows läuft for every other mood; the run-derived state returns after
+// 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' } };
+  return derived;
+}