@staix/agent-research 0.0.0-stage → 0.2.1

package/src/study.ts

@@ -0,0 +1,324 @@
+import { validateAutonomy, validateAutonomyMode, resolveAutonomy, ACCEPT_ARTIFACTS, type Autonomy, type Phase, type AcceptArtifact } from "./autonomy.ts";
+export type { Autonomy } from "./autonomy.ts";
+import { hostname } from "node:os";
+import { spawnSync } from "node:child_process";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, mkdirSync, openSync, readSync, renameSync, statSync, unlinkSync, writeSync, appendFileSync, lstatSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+
+export type Mode = "survey" | "experiment";
+export type GateName = "scope" | "screen" | "design" | "final" | "review" | `plan:${string}` | `accept:${AcceptArtifact}`;
+export const GATES: readonly GateName[] = ["scope", "screen", "design", "final", "review"];
+export interface Study { v: 1 | 2; id: string; question: string; mode: Mode; autonomy: Autonomy; createdAt: string }
+export interface Actor { kind: "person" | "agent" | "auto"; id?: string }
+export function requireExperiment(study: Study): void {
+  if (study.mode !== "experiment") throw new Error("experiment command: study mode must be experiment; create a study with ares init <dir> --question TEXT --mode experiment");
+}
+export interface LedgerEvent { v: 1; at: string; actor: Actor; type: string; data: Record<string, unknown> }
+
+const EVENT_BYTES = 65_536, LEDGER_BYTES = 64 * 1024 * 1024;
+const LOCK_STALE_MS = 10 * 60_000;
+const QUESTION_MAX = 2000;
+export const STUDY_BYTES = 65_536;
+
+/** Agent environment markers the family uses; the first match names the actor. */
+const AGENT_MARKERS: readonly [string, string | undefined][] = [
+  ["AGENTHUB_PEER_ID", undefined], ["CLAUDECODE", "claude"], ["CLAUDE_CODE_SESSION_ID", "claude"], ["CODEX_THREAD_ID", "codex"], ["PI_SESSION_ID", "pi"],
+];
+export function detectActor(env: NodeJS.ProcessEnv): Actor {
+  for (const [marker, name] of AGENT_MARKERS) {
+    const value = env[marker]?.trim();
+    if (value) return { kind: "agent", id: (name ?? value).slice(0, 64) };
+  }
+  return { kind: "person" };
+}
+
+export const sha256 = (data: string | Uint8Array) => createHash("sha256").update(data).digest("hex");
+
+/**
+ * Write a file by temp + fsync + rename so readers never see a partial file. `maxBytes` must be the bound the
+ * file's reader uses, so nothing is written that the tool cannot read back.
+ */
+export function writeAtomic(path: string, text: string, maxBytes: number, mode = 0o644): void {
+  assertWritable(text, maxBytes, path);
+  const tmp = `${path}.${randomUUID()}.tmp`;
+  const fd = openSync(tmp, "wx", mode);
+  try { writeSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  try { renameSync(tmp, path); } catch (error) { try { unlinkSync(tmp); } catch { /* already gone */ } throw error; }
+}
+
+/** Read a regular file, stopping one byte past `maxBytes`: special files and oversize files are refused without buffering them. */
+export interface ReadOptions { noFollow?: boolean; uid?: number }
+export function readBytesBounded(path: string, maxBytes: number, options: ReadOptions = {}): Buffer {
+  // Non-blocking open: a FIFO without a writer would otherwise block before the type check.
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | (options.noFollow ? constants.O_NOFOLLOW : 0));
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile()) throw new Error(`${path}: not a regular file`);
+    if (options.uid !== undefined && info.uid !== options.uid) throw new Error(`${path}: owned by another user`);
+    const buffer = Buffer.alloc(Math.min(maxBytes + 1, 1 << 20)), parts: Buffer[] = [];
+    let total = 0;
+    for (;;) {
+      const n = readSync(fd, buffer, 0, buffer.length, null);
+      if (n === 0) break;
+      total += n;
+      if (total > maxBytes) throw new Error(`${path}: larger than ${maxBytes} bytes`);
+      parts.push(Buffer.from(buffer.subarray(0, n)));
+    }
+    return Buffer.concat(parts);
+  } finally { closeSync(fd); }
+}
+export function readTextBounded(path: string, maxBytes: number, options: ReadOptions = {}): string {
+  try { return new TextDecoder("utf-8", { fatal: true }).decode(readBytesBounded(path, maxBytes, options)); }
+  catch (error) { if (error instanceof TypeError) throw new Error(`${path}: not valid UTF-8`); throw error; }
+}
+export function readJsonFile(path: string, maxBytes: number): unknown {
+  const text = readTextBounded(path, maxBytes);
+  try { return JSON.parse(text); } catch { throw new Error(`${path}: not valid JSON`); }
+}
+/** Refuse a write that the matching bounded read could not load back. */
+export function assertWritable(text: string, maxBytes: number, what: string): void {
+  if (Buffer.byteLength(text) > maxBytes) throw new Error(`${what} would exceed ${maxBytes} bytes`);
+}
+
+export const plain = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
+
+/** Refuse keys outside `allowed`, so a typo never silently drops a field. */
+export function onlyKeys(value: Record<string, unknown>, allowed: readonly string[], what: string): void {
+  const extra = Object.keys(value).filter(key => !allowed.includes(key));
+  if (extra.length) throw new Error(`${what}: unknown field ${extra[0]}`);
+}
+
+export function boundedText(value: unknown, what: string, max: number, min = 1): string {
+  if (typeof value !== "string" || value.includes("\0")) throw new Error(`${what}: text required`);
+  const text = value.trim();
+  if (text.length < min || text.length > max) throw new Error(`${what}: ${min}..${max} characters`);
+  return text;
+}
+
+export function studyFile(dir: string, ...parts: string[]): string { return join(dir, ...parts); }
+
+/** Resolve a study directory: it must hold a valid study.json. */
+export function openStudy(dir: string): { dir: string; study: Study } {
+  const root = resolve(dir), file = join(root, "study.json");
+  if (!existsSync(file)) throw new Error(`${root}: no study.json (run ares init first)`);
+  return { dir: root, study: validStudy(readJsonFile(file, STUDY_BYTES)) };
+}
+
+function validStudy(raw: unknown): Study {
+  if (plain(raw) && raw.v !== 1 && raw.v !== 2) throw new Error("study.json: unsupported schema version; use an ares version that supports this study, keeping the original file unchanged");
+  if (!plain(raw) || (raw.v !== 1 && raw.v !== 2) || typeof raw.id !== "string" || typeof raw.question !== "string" || typeof raw.createdAt !== "string" ||
+    !["survey", "experiment"].includes(raw.mode as string)) throw new Error("study.json: malformed");
+  let autonomy: Autonomy;
+  try { autonomy = validateAutonomy(raw.autonomy); }
+  catch { throw new Error("study.json: unsupported or malformed autonomy policy; restore the last valid study.json or use a compatible ares version before retrying"); }
+  if (raw.v === 1 && (typeof autonomy !== "string" || autonomy === "copilot" || autonomy === "step")) throw new Error("study.json: this autonomy policy requires study v2; restore the valid v1 study and use ares autonomy set with a compatible ares version");
+  return { ...raw, autonomy } as unknown as Study;
+}
+
+export function initStudy(dir: string, options: { question: string; mode?: string; autonomy?: string }, actor: Actor): Study {
+  const root = resolve(dir);
+  if (existsSync(join(root, "study.json"))) throw new Error(`${root}: a study already exists here`);
+  const mode = options.mode ?? "survey", autonomy = validateAutonomyMode(options.autonomy ?? "gates");
+  if (mode !== "survey" && mode !== "experiment") throw new Error("--mode: survey or experiment");
+  const study: Study = { v: autonomy === "auto" || autonomy === "gates" ? 1 : 2, id: randomUUID(), question: boundedText(options.question, "--question", QUESTION_MAX), mode, autonomy, createdAt: new Date().toISOString() };
+  for (const sub of ["", "literature", "literature/cards", "refs"]) mkdirSync(join(root, sub), { recursive: true });
+  // link() refuses an existing target, so two concurrent inits cannot both create the study.
+  const text = JSON.stringify(study, null, 2) + "\n", tmp = join(root, `study.json.${randomUUID()}.tmp`);
+  assertWritable(text, STUDY_BYTES, "study.json");
+  const fd = openSync(tmp, "wx", 0o644);
+  try { writeSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  try { linkSync(tmp, join(root, "study.json")); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`${root}: a study already exists here`); throw error; }
+  finally { unlinkSync(tmp); }
+  appendEvent(root, actor, "study.init", { id: study.id, mode, autonomy });
+  return study;
+}
+
+/**
+ * Exclusive write lock for one study. A lock older than 10 minutes is treated as abandoned and replaced.
+ * ponytail: mtime-based staleness, no owner liveness check. The inode check before unlink is best-effort:
+ * a replacement between lstat and unlink can still be removed, after stale takeover of a live owner has
+ * already broken exclusion. Upgrade path: an owner liveness probe, including shared-host ownership.
+ */
+const ownedStudyLocks = new Set<() => void>();
+/** MCP termination only: call immediately before process exit, never while continuing async work. */
+export function releaseStudyLocksForExit(): void { for (const release of [...ownedStudyLocks]) release(); }
+export class StudyLockBusyError extends Error {}
+export async function withLock<T>(dir: string, fn: () => Promise<T> | T, inspectOwner: (fd: number) => ReturnType<typeof fstatSync> = fstatSync): Promise<T> {
+  const path = join(dir, ".ares.lock");
+  let fd: number;
+  try { fd = openSync(path, "wx", 0o600); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    let age = 0;
+    try { age = Date.now() - statSync(path).mtimeMs; } catch { /* removed meanwhile */ }
+    if (age < LOCK_STALE_MS) throw new StudyLockBusyError(`study is locked by another ares command (${path}); retry when it finishes`);
+    try { unlinkSync(path); } catch { /* raced with another cleaner */ }
+    fd = openSync(path, "wx", 0o600);
+  }
+  let owner: ReturnType<typeof fstatSync>;
+  try { owner = inspectOwner(fd); }
+  catch (error) {
+    try { unlinkSync(path); } catch { /* the just-created lock may already be absent */ }
+    finally { try { closeSync(fd); } catch { /* preserve the original probe failure */ } }
+    throw error;
+  }
+  let released = false;
+  const release = () => {
+    if (released) return; released = true;
+    try { const current = lstatSync(path); if (current.dev === owner.dev && current.ino === owner.ino) unlinkSync(path); }
+    catch { /* absent or replaced; never remove a different owner's lock */ }
+    finally { try { closeSync(fd); } catch { /* process exit also closes owned descriptors */ } ownedStudyLocks.delete(release); }
+  };
+  ownedStudyLocks.add(release);
+  try { writeSync(fd, `${process.pid} ${new Date().toISOString()}\n`); }
+  catch (error) { release(); throw error; }
+  // Keep the descriptor open until release so an unlinked inode cannot be reused by a replacement lock.
+  try { return await fn(); } finally { release(); }
+}
+
+export interface PendingEvent { actor: Actor; type: string; data: Record<string, unknown> }
+export type FileWrite = [path: string, text: string, maxBytes: number];
+
+/** Validate command capacity without writing; callers can reserve receipt space before outward effects. */
+export function prepareCommit(dir: string, files: FileWrite[], pending: PendingEvent[]): { events: LedgerEvent[]; lines: string[] } {
+  const at = new Date().toISOString(), events: LedgerEvent[] = pending.map(e => ({ v: 1, at, ...e }));
+  const lines = events.map(e => JSON.stringify(e) + "\n");
+  lines.forEach((line, i) => { if (Buffer.byteLength(line) > EVENT_BYTES) throw new Error(`ledger event ${events[i]!.type} exceeds ${EVENT_BYTES} bytes`); });
+  const ledger = join(dir, "ledger.jsonl"), size = existsSync(ledger) ? statSync(ledger).size : 0;
+  if (size + Buffer.byteLength(lines.join("")) > LEDGER_BYTES) throw new Error(`ledger.jsonl would exceed ${LEDGER_BYTES} bytes; start a new study`);
+  for (const [path, text, max] of files) assertWritable(text, max, path);
+  return { events, lines };
+}
+/**
+ * Apply one command's changes: every file and ledger bound is checked first (file sizes, event sizes, the ledger's
+ * total against its read limit), then the files are written and all events appended in one write. A failed check
+ * changes nothing.
+ * ponytail: no write-ahead log; a crash between the file writes and the append leaves files without their event.
+ */
+export function commit(dir: string, files: FileWrite[], pending: PendingEvent[]): LedgerEvent[] {
+  const { events, lines } = prepareCommit(dir, files, pending), ledger = join(dir, "ledger.jsonl");
+  for (const [path, text, max] of files) { mkdirSync(dirname(path), { recursive: true }); writeAtomic(path, text, max); }
+  if (lines.length) appendFileSync(ledger, lines.join(""), { mode: 0o644 });
+  return events;
+}
+
+export function appendEvent(dir: string, actor: Actor, type: string, data: Record<string, unknown>): LedgerEvent {
+  return commit(dir, [], [{ actor, type, data }])[0]!;
+}
+
+/** Read the whole ledger; a malformed line fails closed with its line number. */
+export function readLedger(dir: string): LedgerEvent[] {
+  const path = join(dir, "ledger.jsonl");
+  if (!existsSync(path)) return [];
+  const lines = readTextBounded(path, LEDGER_BYTES).split("\n");
+  const events: LedgerEvent[] = [];
+  lines.forEach((line, index) => {
+    if (!line.trim()) return;
+    let event: unknown;
+    try { event = JSON.parse(line); } catch { throw new Error(`ledger.jsonl line ${index + 1}: not JSON`); }
+    if (plain(event) && event.v !== 1) throw new Error(`ledger.jsonl line ${index + 1}: unsupported schema version; use an ares version that supports this ledger, keeping all original lines unchanged`);
+    if (!plain(event) || event.v !== 1 || typeof event.type !== "string" || !plain(event.data) || !plain(event.actor)) throw new Error(`ledger.jsonl line ${index + 1}: malformed event`);
+    events.push(event as unknown as LedgerEvent);
+  });
+  return events;
+}
+
+export interface GateState { gate: GateName; state: "none" | "pending" | "approved" | "rejected"; current?: string; decided?: { decision: "approve" | "reject"; binding: string; actor: Actor; at: string; reason?: string } }
+
+/** The content a gate approval binds to. `undefined` means there is nothing to decide yet. */
+export type Binder = (gate: GateName) => string | undefined;
+
+export function gateState(gate: GateName, events: LedgerEvent[], binder: Binder): GateState {
+  const current = binder(gate);
+  let decided: GateState["decided"];
+  for (const event of events) {
+    if ((event.type === "gate.approve" || event.type === "gate.reject") && event.data.gate === gate && typeof event.data.binding === "string")
+      decided = { decision: event.type === "gate.approve" ? "approve" : "reject", binding: event.data.binding, actor: event.actor, at: event.at, ...(typeof event.data.reason === "string" ? { reason: event.data.reason } : {}) };
+  }
+  if (current === undefined) return { gate, state: "none", ...(decided ? { decided } : {}) };
+  if (!decided || decided.binding !== current) return { gate, state: "pending", current, ...(decided ? { decided } : {}) };
+  return { gate, state: decided.decision === "approve" ? "approved" : "rejected", current, decided };
+}
+
+export function decideGate(dir: string, gate: GateName, decision: "approve" | "reject", actor: Actor, binder: Binder, reason?: string): GateState {
+  if (!GATES.includes(gate) && !ACCEPT_ARTIFACTS.some(artifact => gate === `accept:${artifact}`) && !gate.startsWith("plan:")) throw new Error(`unknown gate: ${gate}; run ares gate list to select a gate`);
+  const before = gateState(gate, readLedger(dir), binder);
+  if (before.state === "none" && gate.startsWith("accept:")) throw new Error(`gate ${gate}: no current copilot draft; inspect ares autonomy show, create the phase artifact, then use ares gate list and ares gate approve <dir> ${gate}`);
+  if (before.state === "none") throw new Error(`gate ${gate}: nothing to decide yet${gate.startsWith("plan:") ? "; finish every upstream node with output references, then run ares gate list" : ""}`);
+  if (decision === "reject" && !reason) throw new Error(`gate ${gate}: a rejection needs --reason`);
+  appendEvent(dir, actor, decision === "approve" ? "gate.approve" : "gate.reject", { gate, binding: before.current!, ...(reason ? { reason } : {}) });
+  return gateState(gate, readLedger(dir), binder);
+}
+
+/**
+ * Pass when the gate is approved for the current content. In auto mode a pending gate passes too, and the returned
+ * `auto` approval goes into the command's own commit only when the command succeeds, so a failed command never
+ * changes a gate.
+ */
+export function requireGate(dir: string, study: Study, gate: GateName, binder: Binder, guardedPhase?: Phase): PendingEvent[] {
+  if (gate === "design" || gate === "final") requireExperiment(study);
+  const state = gateState(gate, readLedger(dir), binder);
+  if (state.state === "approved") return [];
+  if (state.state === "pending" && !gate.startsWith("accept:") && resolveAutonomy(study.autonomy, gate, guardedPhase) === "auto") return [{ actor: { kind: "auto" }, type: "gate.approve", data: { gate, binding: state.current! } }];
+  if (state.state === "none" && gate.startsWith("accept:")) throw new Error(`gate ${gate}: no current copilot draft; create the phase artifact, then run ares gate list and ares gate approve <dir> ${gate}`);
+  if (state.state === "none" && gate === "final") throw new Error("gate final: complete reserved seeds and close investigate/required ablate inputs before final approval");
+  if (state.state === "none" && gate.startsWith("plan:")) throw new Error(`gate ${gate}: upstream outputs are not complete; finish every upstream node and run ares gate list again`);
+  if (state.state === "none") throw new Error(gate === "scope" ? "gate scope: no scope yet (run ares scope)" : gate === "design" ? "gate design: no protocol yet (run ares protocol)" : "gate screen: no included candidates yet");
+  if (state.state === "rejected") throw new Error(`gate ${gate} is rejected${state.decided?.reason ? `: ${state.decided.reason}` : ""}; change the content and ask again`);
+  throw new Error(`gate ${gate} is pending: run ares gate approve <dir> ${gate}`);
+}
+
+
+export interface PlanOwner { pid: number; host: string; startedAt: string; token: string }
+/** Kernel process start identity, rather than lock age, detects a reused PID. */
+export function processStart(pid: number): string | undefined {
+  const result = spawnSync("ps", ["-p", String(pid), "-o", "lstart="], { encoding: "utf8", timeout: 2000, maxBuffer: 4096, env: { PATH: process.env.PATH ?? "/usr/bin:/bin", LC_ALL: "C" } });
+  if (result.status === 0 && result.stdout.trim()) return result.stdout.trim();
+  return undefined;
+}
+export function readPlanOwner(dir: string): PlanOwner | undefined {
+  const file = join(dir, ".ares.plan.lock");
+  let stat;
+  try { stat = lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("plan controller lock: regular file required; restore the study lock file without links before running ares run");
+  const raw = readJsonFile(file, 4096);
+  if (!plain(raw) || !Number.isSafeInteger(raw.pid) || (raw.pid as number) < 1 || typeof raw.host !== "string" || !raw.host || typeof raw.startedAt !== "string" || !raw.startedAt || typeof raw.token !== "string" || !raw.token) throw new Error("plan controller lock: malformed owner; inspect the owner process and restore a valid lock before ares run");
+  return raw as unknown as PlanOwner;
+}
+export function assertPlanOwner(dir: string, owner: PlanOwner): void {
+  const current = readPlanOwner(dir);
+  if (!current || current.token !== owner.token || current.pid !== owner.pid || current.host !== owner.host || current.startedAt !== owner.startedAt) throw new Error("plan controller: ownership changed; stop this controller and inspect ares plan show before restarting");
+}
+export async function withPlanLock<T>(dir: string, fn: (owner: PlanOwner) => Promise<T>): Promise<T> {
+  const startedAt = processStart(process.pid);
+  if (!startedAt) throw new Error("plan controller: process start identity unavailable; check local ps access before running ares run");
+  const owner: PlanOwner = { pid: process.pid, host: hostname(), startedAt, token: randomUUID() };
+  await withLock(dir, () => {
+    const previous = readPlanOwner(dir);
+    if (previous) {
+      const busy = () => new Error(`plan controller: owned by pid ${previous.pid} on ${previous.host} (started ${previous.startedAt}); stop that controller or run on its host after it exits`);
+      if (previous.host !== owner.host) throw busy();
+      let alive = true;
+      try { process.kill(previous.pid, 0); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code === "ESRCH") alive = false; else throw busy(); }
+      if (alive) {
+        const observed = processStart(previous.pid);
+        if (!observed || observed === previous.startedAt) throw busy();
+      }
+      // Short study lock serializes contenders. Never recover by age.
+      unlinkSync(join(dir, ".ares.plan.lock"));
+    }
+    const fd = openSync(join(dir, ".ares.plan.lock"), "wx", 0o600);
+    try { writeSync(fd, JSON.stringify(owner) + "\n"); fsyncSync(fd); } finally { closeSync(fd); }
+  });
+  try { return await fn(owner); }
+  finally {
+    // A live matching owner cannot be replaced by any valid contender.
+    try {
+      const current = readPlanOwner(dir);
+      if (current?.token === owner.token) unlinkSync(join(dir, ".ares.plan.lock"));
+    } catch { /* Preserve the original failure; never remove a malformed or unverified owner. */ }
+  }
+}

package/src/ui/panel.css

@@ -0,0 +1,11 @@
+.ares { display: flex; flex-direction: column; gap: var(--acon-space-3); min-width: 0; }
+.ares-bar { display: flex; flex-wrap: wrap; align-items: center; gap: var(--acon-space-2); }
+.ares-bar h2 { flex: 1; margin: 0; min-width: 0; font-size: var(--acon-text-lg); overflow-wrap: anywhere; }
+.ares-card { display: flex; flex-direction: column; gap: var(--acon-space-2); min-width: 0; }
+.ares-card h3 { margin: 0; font-size: var(--acon-text-base, 1rem); }
+.ares-card > p, .ares-prose { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; }
+.ares-sub { margin: 0; color: var(--acon-text-2); overflow-wrap: anywhere; }
+.ares-pre { margin: 0; max-height: 40vh; overflow: auto; padding: var(--acon-space-3); white-space: pre-wrap; overflow-wrap: anywhere; background: var(--acon-surface-2); border: 1px solid var(--acon-line); border-radius: var(--acon-radius-2); font: var(--acon-text-sm)/1.5 var(--acon-font-mono); }
+.ares-list { margin: 0; padding-left: 1.5em; overflow-wrap: anywhere; }
+.ares-list li + li { margin-top: var(--acon-space-1); }
+@media (max-width: 600px) { .ares-bar { align-items: flex-start; } .ares-bar h2 { flex-basis: 100%; } }

package/src/ui/panel.js

@@ -0,0 +1,161 @@
+// acon api 1: the shell owns polling and confirmation; decision controls use host.ui and host.action.
+export default (host) => {
+  const { ui } = host;
+  const { h } = ui;
+  const root = h("div", { class: "ares" });
+  host.mount.append(root);
+  let panel = "studies", params = {}, visible = true, destroyed = false, generation = 0, last = null;
+  const viewKey = () => JSON.stringify([panel, params]);
+  const text = (value, fallback = "Unavailable") => typeof value === "string" && value ? value : fallback;
+  const number = (value) => typeof value === "number" && Number.isFinite(value) ? String(value) : "Unavailable";
+  const rows = (value) => Array.isArray(value) ? value : [];
+  const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const autonomyLabel = (value) => typeof value === "string" ? text(value)
+    : `${text(record(value).default)}${Object.keys(record(record(value).phases)).length ? " (phase overrides)" : ""}`;
+  const line = (value, max = 180) => {
+    const valueText = text(value, "").replace(/\s+/g, " ").trim();
+    return valueText.length > max ? `${valueText.slice(0, max - 3)}...` : valueText;
+  };
+  const at = (value) => typeof value === "string" ? value.replace("T", " ").replace(/\.\d+Z$/, " UTC") : "Time unavailable";
+  const go = (target, extra = {}) => host.navigate(host.tool, target, extra);
+  const tone = (state) => ["accepted", "approved", "qualified", "succeeded", "ready"].includes(state) ? "ok"
+    : ["failed", "unknown", "unavailable"].includes(state) ? "err"
+      : ["pending", "proposed", "not_qualified", "rejected"].includes(state) ? "warn" : "neutral";
+  const decisionNotice = () => ui.notice("Each decision opens a preview. Nothing is written until you confirm.", "neutral");
+  const perform = async (input) => {
+    try { await host.action(input); }
+    catch { if (!destroyed) host.toast("The decision could not be requested. Refresh the study and retry."); }
+  };
+  const askDecision = (title, input, requirePr = false) => {
+    const body = host.sheet.open(title), errors = h("div", { "aria-live": "polite" });
+    const fields = [{ name: "reason", label: "Reason", required: true }, ...(requirePr ? [{ name: "pr", label: "Reviewed PR URL", required: true }] : [])];
+    const form = ui.form(fields, { label: "Review decision", primary: true }, (values) => {
+      const reason = text(values.reason, "").trim(), pr = text(values.pr, "").trim();
+      if (!reason) { errors.replaceChildren(ui.notice("Enter a reason before continuing.", "err")); return; }
+      if (requirePr) {
+        try { const url = new URL(pr); if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) throw new Error(); }
+        catch { errors.replaceChildren(ui.notice("Enter the reviewed HTTP(S) PR URL without credentials.", "err")); return; }
+      }
+      host.sheet.close();
+      void perform({ ...input, reason, ...(requirePr ? { pr } : {}) });
+    });
+    body.append(ui.notice(input.action.startsWith("skill.") ? "Skill decisions are final. Review the evidence and reason before confirming." : "Review the evidence and reason. The next step shows the confirmation preview.", "neutral"), form, errors, ui.button("Cancel", () => host.sheet.close()));
+  };
+  const block = (title, value) => {
+    if (value === undefined || value === null) return ui.empty(`${title} unavailable`);
+    const content = JSON.stringify(value, null, 2), bound = 20_000;
+    return h("section", { class: "ares-card" }, h("h3", { text: title }),
+      h("pre", { class: "ares-pre", text: content.length > bound ? `${content.slice(0, bound)}\n...` : content }),
+      content.length > bound ? h("p", { class: "ares-sub", text: "Preview shortened. Inspect the complete records with the ares CLI." }) : null);
+  };
+  const refresh = async () => {
+    const current = generation;
+    try {
+      const snapshot = await host.snapshot({ ...params, panel, after: 0 });
+      if (!destroyed && visible && current === generation) render(snapshot);
+    } catch {
+      if (!destroyed && visible && current === generation) root.replaceChildren(ui.notice("Research could not refresh. Retry or inspect the console System view.", "err"));
+    }
+  };
+  const toolbar = (title, back = false) => h("div", { class: "ares-bar" },
+    back ? ui.button("All studies", () => go("studies")) : null,
+    h("h2", { text: title }), ui.button("Refresh", refresh));
+  const gateRows = (gates, study) => h("section", { class: "ares-card" },
+    ui.table({ caption: "Gate states", columns: [{ key: "gate", label: "Gate" }, { key: "state", label: "State" }],
+      rows: rows(gates).map((gate) => ({ gate: text(gate.gate), state: text(gate.state) })) }),
+    typeof study === "string" ? ui.rows(rows(gates).filter((gate) => gate.state === "pending" && typeof gate.gate === "string"), (gate) => ui.row({
+      title: gate.gate, sub: "Pending decision", chip: { text: "pending", tone: "warn" }, verbs: [
+        ui.button("Approve", () => perform({ action: "gate.approve", study, gate: gate.gate }), { tone: "primary" }),
+        ui.button("Reject", () => askDecision(`Reject ${gate.gate}`, { action: "gate.reject", study, gate: gate.gate }), { tone: "danger" }),
+      ],
+    })) : null);
+  const attemptRows = (attempts) => {
+    const value = record(attempts), byStatus = record(value.byStatus);
+    if (value.available === false) return h("section", { class: "ares-card" }, h("h3", { text: "Attempts unavailable" }),
+      ui.notice(line(value.reason) || "Attempt records could not be read. Inspect the study records and refresh.", "err"));
+    return h("section", { class: "ares-card" }, h("h3", { text: `Attempts: ${number(value.total)}` }),
+      ui.rows(Object.entries(byStatus), ([state, count]) => ui.row({ title: state, sub: number(count), chip: { text: state, tone: tone(state) } })) ?? ui.empty("No attempt status details"));
+  };
+  const studies = (snapshot) => {
+    const list = rows(snapshot.studies);
+    return [toolbar("Research studies"), decisionNotice(),
+      ui.rows(list, (study) => {
+        const available = study.available !== false;
+        const finalState = study.final?.status, reviewState = study.review?.ready === true ? "Review ready" : study.review ? "Review pending" : "Review unavailable";
+        const watchState = study.lastWatch ? `${study.lastWatch.ok ? "Watch answered" : "Watch failed"}: ${number(study.lastWatch.added)} added` : "No watch run";
+        const attempts = study.attempts?.available === false ? `Attempts unavailable: ${line(study.attempts.reason) || "Attempt records could not be read."}` : `${number(study.attempts?.total)} attempts`;
+        const pending = rows(study.gates).filter((gate) => gate.state === "pending").length;
+        return ui.row({ title: line(study.question) || text(study.id, "Unavailable study"),
+          sub: available ? [text(study.mode), autonomyLabel(study.autonomy), attempts, `${pending} pending gates`, finalState ? `Final ${finalState}` : "Final unavailable", reviewState, watchState].join(" | ") : text(study.reason, "Study cannot be read; its registration is retained."),
+          chip: { text: available ? text(study.mode, "study") : "unavailable", tone: available ? "neutral" : "err" },
+          ...(typeof study.dir === "string" ? { onOpen: () => go("study", { study: study.dir }) } : {}) });
+      }) ?? ui.empty("No registered studies", "Register one with ares console add <dir>. Ares does not scan the disk for studies.")];
+  };
+  const skillRows = (skills, study) => ui.rows(rows(skills), (skill) => ui.detail({
+    kind: "Skill proposal", title: text(skill.name), state: { text: text(skill.state), tone: tone(skill.state) }, summary: text(skill.summary, ""),
+    actions: skill.state === "proposed" && typeof skill.name === "string" && typeof study === "string" ? [
+      ui.button("Accept...", () => askDecision(`Accept ${skill.name}`, { action: "skill.accept", study, name: skill.name }, true), { tone: "primary" }),
+      ui.button("Reject...", () => askDecision(`Reject ${skill.name}`, { action: "skill.reject", study, name: skill.name }), { tone: "danger" }),
+      ui.button("Withdraw...", () => askDecision(`Withdraw ${skill.name}`, { action: "skill.withdraw", study, name: skill.name }), { tone: "danger" }),
+    ] : [],
+    sections: [{ title: "Steps", body: h("ol", { class: "ares-list" }, ...rows(skill.steps).map((step) => h("li", { text: String(step) }))) },
+      { title: "Evidence", body: h("ul", { class: "ares-list" }, ...rows(skill.evidence).map((ref) => h("li", { text: String(ref) }))) },
+      ...(skill.decision ? [{ title: "Recorded decision", body: h("pre", { class: "ares-pre", text: JSON.stringify(skill.decision, null, 2) }) }] : [])],
+    footer: typeof skill.sha256 === "string" ? [skill.sha256] : [],
+  })) ?? ui.empty("No skill proposals");
+  const studyView = (snapshot) => {
+    const study = snapshot.study;
+    if (!study) return [toolbar("Study", true), ui.notice(text(snapshot.error, "Choose a registered study from the studies panel."), "warn")];
+    const sections = [toolbar(text(study.question, "Study"), true), decisionNotice()];
+    if (study.available === false) return [...sections, ui.notice(text(study.reason, "Study unavailable; its registration is retained."), "err"), h("p", { class: "ares-sub", text: text(study.dir, "") })];
+    sections.push(h("div", { class: "ares-bar" }, ui.chip(text(study.mode), "neutral"), ui.chip(autonomyLabel(study.autonomy), "neutral")),
+      h("p", { class: "ares-sub", text: text(study.dir, "") }), gateRows(study.gates, study.dir), attemptRows(study.attempts));
+    if (study.autonomy && typeof study.autonomy === "object") sections.push(block("Autonomy policy", study.autonomy));
+    const final = record(study.final);
+    sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Final status" }),
+      typeof final.status === "string" ? ui.chip(final.status, tone(final.status)) : ui.empty("No current closed final"),
+      typeof final.reason === "string" ? h("p", { text: final.reason }) : null));
+    const review = record(study.review);
+    sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Review readiness" }),
+      study.review ? ui.chip(review.ready === true ? "ready" : "not ready", review.ready === true ? "ok" : "warn") : ui.empty("Review unavailable"),
+      ui.rows(rows(review.unmet), (item) => ui.row({ title: text(item.code, "Review requirement"), sub: text(item.message, "") })),
+      rows(review.openBlocking).length ? ui.notice(`${review.openBlocking.length} blocking findings remain open.`, "warn") : null));
+    if (typeof study.manuscript?.id === "string") sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Built manuscript" }),
+      ui.link({ asset: study.manuscript.id }, "Open manuscript text")));
+    const investigationArtifact = record(study.investigationArtifact);
+    if (investigationArtifact.state === "missing") sections.push(ui.notice(text(investigationArtifact.message, "Investigation artifact missing; displayed result is recalculated. Restore the artifact or run ares investigate close."), "warn"));
+    sections.push(block("Investigation", study.investigation), block("Posthoc exploration", study.posthoc));
+    const watch = record(study.watch), watchConfig = record(watch.config);
+    sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Watch" }),
+      typeof watchConfig.rubric === "string" ? h("div", {}, h("strong", { text: "Display-only rubric" }), h("p", { class: "ares-prose", text: watchConfig.rubric })) : null,
+      ui.rows(rows(watch.runs), (run) => ui.row({ title: run.ok ? "Source answered" : run.cause === undefined ? "All sources failed" : ["terminated", "filesystem", "internal", "network", "rate", "server", "client", "format"].includes(run.cause) ? `Watch run failed (${run.cause})` : "Watch run failed (unknown cause)", sub: `${at(run.at)} | ${number(run.added)} added | ${number(run.addedIdsTotal)} recorded ids`, chip: { text: run.ok ? "answered" : "failed", tone: run.ok ? "ok" : "err" } })) ?? ui.empty("No watch runs")));
+    const candidates = rows(record(watch.newCandidates).candidates).filter((candidate) => candidate.status === "new" && typeof candidate.id === "string");
+    sections.push(h("section", { class: "ares-card" }, h("h3", { text: "New candidates" }),
+      ui.rows(candidates, (candidate) => ui.row({ title: line(candidate.title) || candidate.id, sub: `${candidate.id}${typeof candidate.year === "number" ? ` | ${candidate.year}` : ""}`, verbs: typeof study.dir === "string" ? [
+        ui.button("Include...", () => askDecision("Include candidate", { action: "screen.include", study: study.dir, ids: [candidate.id] }), { tone: "primary" }),
+        ui.button("Exclude...", () => askDecision("Exclude candidate", { action: "screen.exclude", study: study.dir, ids: [candidate.id] }), { tone: "danger" }),
+      ] : [] })) ?? ui.empty("No new candidates waiting")));
+    sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Skill proposals" }), skillRows(study.skills, study.dir)));
+    const pending = study.archive?.pendingCount;
+    sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Archive lessons" }),
+      Number.isSafeInteger(pending) && pending >= 0 ? h("p", { text: pending ? `${pending} pending lesson notes. Preview the next export batch before confirming.` : "No pending lesson notes." }) : ui.empty("Archive preview unavailable"),
+      typeof study.dir === "string" && Number.isSafeInteger(pending) && pending > 0 ? ui.button("Preview archive...", () => perform({ action: "archive.confirm", study: study.dir }), { tone: "primary" }) : null));
+    const errors = Object.entries(record(study.errors));
+    if (errors.length) sections.push(h("section", { class: "ares-card" }, h("h3", { text: "Unavailable records" }),
+      ui.rows(errors, ([name, reason]) => ui.row({ title: name, sub: String(reason) }))));
+    return sections;
+  };
+  const render = (snapshot) => {
+    if (destroyed || !visible || snapshot.changed === false) return;
+    last = { key: viewKey(), snapshot };
+    const body = snapshot.error && panel !== "study" ? [ui.notice(String(snapshot.error), "err")]
+      : panel === "studies" ? studies(snapshot) : panel === "study" ? studyView(snapshot) : [ui.empty("Unknown research panel", "Choose Studies from the console.")];
+    root.replaceChildren(...body.filter(Boolean));
+  };
+  host.onSnapshot(render);
+  return {
+    show(id, input = {}) { generation++; panel = id; params = { ...input }; visible = true; root.hidden = false; if (last?.key === viewKey()) render(last.snapshot); else root.replaceChildren(ui.notice("Loading research view...", "neutral")); },
+    hide() { generation++; visible = false; root.hidden = true; },
+    destroy() { generation++; destroyed = true; root.remove(); },
+  };
+};