@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/harness/opencode/plugins/syn-watch-arm.js

@@ -0,0 +1,521 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { encodeRoddOperationalInput } from "./lib/rodd-operational-input.js";
+
+// Sýn — Brokk primary watcher-arm continuity for OpenCode.
+//
+// Sýn ("watchful sight") owns the watcher cycle in the persistent OpenCode TUI.
+// The plugin listens for session.idle, spawns bin/syn-watch-arm.sh --restart
+// without awaiting it, and owns every later successor launch so no model tool
+// call and no model tokens are spent on ordinary re-arming. Ported from the
+// upstream agent-distro reference and retargeted to the Brokk runtime
+// (docs/plans/29-brokk-distro-runtime.md).
+
+const COORDINATOR_KEY = "__brokkOpenCodeWatchArm";
+// 35s on Windows so the budget stays above arm's MSYS confirm default (30s in
+// bin/syn-watch-arm.sh): a slow but successful Git Bash cold start must not be
+// SIGTERMed mid-confirmation. Conditioned on win32 so other platforms keep 12s.
+const ARM_READY_TIMEOUT_DEFAULT_MS = process.platform === "win32" ? 35000 : 12000;
+const ARM_READY_TIMEOUT_MS = positiveInteger("BROKK_OPENCODE_ARM_READY_TIMEOUT_MS", ARM_READY_TIMEOUT_DEFAULT_MS);
+const ARM_RETIRE_TIMEOUT_MS = positiveInteger("BROKK_WATCH_ARM_RETIRE_TIMEOUT_MS", 1000);
+const REARM_RETRY_BASE_MS = positiveInteger("BROKK_WATCH_REARM_RETRY_BASE_MS", 250);
+const REARM_RETRY_MAX_MS = positiveInteger("BROKK_WATCH_REARM_RETRY_MAX_MS", 4000);
+const REARM_RETRY_LIMIT = positiveInteger("BROKK_WATCH_REARM_RETRY_LIMIT", 5);
+
+let child = null;
+let armStatus = "idle";
+let retryTimer = null;
+let retryFailures = 0;
+let launchInFlight = null;
+let restorationInFlight = null;
+let armClose = new WeakMap();
+let armReadiness = new WeakMap();
+let armRecovery = new WeakMap();
+
+function positiveInteger(name, fallback) {
+  const value = Number(process.env[name]);
+  if (!Number.isFinite(value) || value <= 0) return fallback;
+  return Math.floor(value);
+}
+
+function setArmStatus(status) {
+  armStatus = status;
+}
+
+function waitForArmReady(armChild) {
+  const readiness = armReadiness.get(armChild);
+  if (!readiness) return Promise.resolve("failed");
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve("timeout"), ARM_READY_TIMEOUT_MS);
+    timer.unref();
+    void readiness.then((status) => {
+      clearTimeout(timer);
+      resolve(status);
+    });
+  });
+}
+
+function runProcess(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const proc = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      ...options,
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    proc.on("error", (error) => resolve({ code: 127, stdout, stderr: String(error?.message ?? error) }));
+    proc.on("close", (code) => resolve({ code: code ?? 0, stdout, stderr }));
+  });
+}
+
+async function resolveRoot(anchor) {
+  if (!anchor) return "";
+  const result = await runProcess("git", ["-C", anchor, "rev-parse", "--show-toplevel"]);
+  const root = result.stdout.trim();
+  if (result.code === 0 && root) return root;
+  return resolvePath(anchor);
+}
+
+function resolvePath(anchor) {
+  try {
+    return realpathSync(anchor);
+  } catch {
+    return resolve(anchor);
+  }
+}
+
+function effectivePaths(root) {
+  const brokkRoot = process.env.BROKK_ROOT_OVERRIDE || root;
+  const brokkHome = process.env.BROKK_HOME || process.env.BROKK_ROOT_OVERRIDE || brokkRoot;
+  const state = process.env.BROKK_STATE_OVERRIDE || `${brokkHome}/state`;
+  const config = process.env.BROKK_CONFIG_OVERRIDE || `${brokkHome}/config`;
+  return { root: brokkRoot, home: brokkHome, state, config };
+}
+
+async function isPrimaryRoot(root, home) {
+  if (!root) return false;
+  if (!existsSync(`${root}/AGENTS.md`) || !existsSync(`${root}/bin`)) return false;
+  const gitDir = await runProcess("git", ["-C", root, "rev-parse", "--git-dir"]);
+  const commonDir = await runProcess("git", ["-C", root, "rev-parse", "--git-common-dir"]);
+  if (gitDir.code !== 0 || commonDir.code !== 0) return false;
+  // A linked worktree (an Eindri home) reports a different git-dir; only the
+  // true primary checkout owns supervision.
+  return gitDir.stdout.trim() === commonDir.stdout.trim();
+}
+
+function shouldArm(paths) {
+  if (existsSync(`${paths.state}/.afk`)) return false;
+  if (existsSync(`${paths.config}/x-mode.env`)) return true;
+  try {
+    if (readdirSync(paths.state).some((name) => name.endsWith(".meta"))) return true;
+  } catch {
+    return false;
+  }
+  // Continuity: supervision was armed before, so the guard expects a live
+  // watcher even when no task metadata remains. Re-arm rather than go blind.
+  return existsSync(`${paths.state}/.supervision-armed`);
+}
+
+// The resolved session-lock path (machine-global for the primary, per-home for
+// an Eindri-home). gleipnir-lock-lib.sh records it in state/.lock-path; a
+// pre-contract session still lives at the legacy state/.lock.
+function resolvedLockPath(paths) {
+  try {
+    const pointer = readFileSync(`${paths.state}/.lock-path`, "utf8").trim();
+    if (pointer) return pointer;
+  } catch {
+    // no pointer yet — pre-machine-lock session
+  }
+  return `${paths.state}/.lock`;
+}
+
+async function sessionOwnsLock(paths) {
+  let lockPid = "";
+  try {
+    lockPid = readFileSync(resolvedLockPath(paths), "utf8").trim();
+  } catch {
+    return false;
+  }
+  if (!/^[0-9]+$/.test(lockPid) || lockPid === "1") return false;
+  let pid = String(process.pid);
+  for (let i = 0; i < 8; i += 1) {
+    if (pid === lockPid) return true;
+    const result = await runProcess("ps", ["-o", "ppid=", "-p", pid]);
+    if (result.code !== 0) return false;
+    pid = result.stdout.trim();
+    if (!pid || pid === "1") return false;
+  }
+  return false;
+}
+
+function classifyArmClose(stdout, stderr, code, signal) {
+  const combined = `${stdout}\n${stderr}`;
+  const reason = combined.split(/\r?\n/).find((line) => /^(signal:|stale:|check:|heartbeat($|:))/.test(line));
+  if (reason) return { kind: "actionable", message: reason };
+  const healthy = combined.split(/\r?\n/).find((line) => /^watcher: healthy\b/.test(line));
+  if (healthy) {
+    return {
+      kind: "failure",
+      message: `watcher: FAILED - OpenCode arm child found an external healthy watcher instead of owning wake delivery\n${healthy}`,
+    };
+  }
+  const failed = combined.split(/\r?\n/).find((line) => /^watcher: FAILED/.test(line));
+  if (failed) return { kind: "failure", message: failed };
+  if (signal) {
+    return {
+      kind: "failure",
+      message: `watcher: FAILED - OpenCode arm child ended from ${signal}${combined.trim() ? `\n${combined.trim()}` : ""}`,
+    };
+  }
+  if (code && code !== 0) {
+    return {
+      kind: "failure",
+      message: `watcher: FAILED - syn-watch-arm.sh exited ${code}${combined.trim() ? `\n${combined.trim()}` : ""}`,
+    };
+  }
+  return {
+    kind: "failure",
+    message: "watcher: FAILED - OpenCode arm cycle ended without an actionable reason",
+  };
+}
+
+function observeArmOutput(stdout, stderr, settleReadiness) {
+  const combined = `${stdout}\n${stderr}`;
+  if (combined.split(/\r?\n/).some((line) => /^(signal:|stale:|check:|heartbeat($|:))/.test(line))) {
+    setArmStatus("wake");
+    settleReadiness("wake");
+    return;
+  }
+  if (combined.split(/\r?\n/).some((line) => /^watcher: (?:started|attached)\b/.test(line))) {
+    setArmStatus("armed");
+    settleReadiness("armed");
+    return;
+  }
+  if (combined.split(/\r?\n/).some((line) => /^watcher: healthy\b/.test(line))) {
+    setArmStatus("external");
+    settleReadiness("external");
+    return;
+  }
+  if (combined.split(/\r?\n/).some((line) => /^watcher: FAILED/.test(line))) {
+    setArmStatus("failed");
+    settleReadiness("failed");
+  }
+}
+
+async function sendPrompt(paths, client, sessionID, text) {
+  const encoded = await encodeRoddOperationalInput(paths.root, "watcher", text);
+  await client.session.promptAsync({
+    path: { id: sessionID },
+    body: {
+      parts: [{ type: "text", text: encoded }],
+    },
+  });
+}
+
+function confirmHandlingDelivery(paths, recovery) {
+  try {
+    const result = spawnSync(
+      "bash",
+      [`${paths.root}/bin/syn-watch-arm.sh`, "--handling-delivered", recovery.generation, "--watcher-pid", recovery.watcherPid],
+      {
+        cwd: paths.root,
+        encoding: "utf8",
+        env: { ...process.env, BROKK_HOME: paths.home, BROKK_STATE_OVERRIDE: paths.state, BROKK_ROOT_OVERRIDE: paths.root },
+      },
+    );
+    if (result.status === 0) return { ok: true, detail: "" };
+    const stderr = String(result.stderr || "").trim();
+    return {
+      ok: false,
+      detail: `watcher: FAILED - handling delivery confirmation was rejected (status=${result.status ?? "none"} generation=${recovery.generation} watcherPid=${recovery.watcherPid})${stderr ? `\n${stderr}` : ""}`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: `watcher: FAILED - handling delivery confirmation could not be executed (generation=${recovery.generation} watcherPid=${recovery.watcherPid})\n${String(error?.message ?? error)}`,
+    };
+  }
+}
+
+function confirmHandlingDeliveryWithRetry(paths, recovery) {
+  const snapshot = () => armRecovery.get(child) ?? recovery;
+  const first = confirmHandlingDelivery(paths, snapshot());
+  if (first.ok) return first;
+  return confirmHandlingDelivery(paths, snapshot());
+}
+
+async function deliverActionableWake(paths, client, sessionID, message, recovery) {
+  if (recovery) {
+    const confirmed = confirmHandlingDeliveryWithRetry(paths, recovery);
+    if (!confirmed.ok) {
+      if (recovery.watcherPid) {
+        try {
+          process.kill(Number(recovery.watcherPid), 0);
+        } catch {
+          await retireArm(child);
+        }
+      }
+      await sendPrompt(paths, client, sessionID, wakePrompt(`${message}\n\n${confirmed.detail}`));
+      return;
+    }
+  }
+  await sendPrompt(paths, client, sessionID, wakePrompt(message));
+}
+
+function wakePrompt(reason) {
+  return `WATCHER FIRED - drain queued wakes with bin/saga-wake-drain.sh and handle the reported wake. Watcher continuity is plugin-owned.\n\n${reason}`;
+}
+
+function surfaceFailure(paths, client, sessionID, reason) {
+  void sendPrompt(paths, client, sessionID, wakePrompt(reason)).catch(() => {
+    // OpenCode owns delivery errors; continuity restoration never waits on prompting.
+  });
+}
+
+function retryDelay(attempt) {
+  return Math.min(REARM_RETRY_MAX_MS, REARM_RETRY_BASE_MS * 2 ** Math.max(0, attempt - 1));
+}
+
+function waitForRetry(attempt) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, retryDelay(attempt));
+    timer.unref();
+  });
+}
+
+async function retireArm(armChild) {
+  if (!armChild) return true;
+  armChild.kill("SIGTERM");
+  const closed = armClose.get(armChild);
+  if (!closed) return false;
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), ARM_RETIRE_TIMEOUT_MS);
+    timer.unref();
+    void closed.then(() => {
+      clearTimeout(timer);
+      resolve(true);
+    });
+  });
+}
+
+function restorationFailure(status) {
+  if (status === "read-only") {
+    return "watcher: FAILED - OpenCode cannot restore continuity because this session no longer owns the lock";
+  }
+  return `watcher: FAILED - OpenCode could not verify a ready successor watcher (${status || "idle"})`;
+}
+
+async function restoreAfterActionableClose(paths, sessionID, client, predecessorArmPid) {
+  let failure = "";
+  for (let attempt = 0; attempt <= REARM_RETRY_LIMIT; attempt += 1) {
+    const { status, armChild } = await ensureArm(paths, sessionID, client, predecessorArmPid, true);
+    if (status === "armed") return { failure: "", recovery: armRecovery.get(armChild) };
+    // An actionable line belongs to this arm's close handler.
+    // Do not retire it before that handler can start the successor cycle.
+    if (status === "wake") return { failure: "", recovery: armRecovery.get(armChild) };
+    failure = restorationFailure(status);
+    if (!(await retireArm(armChild))) {
+      setArmStatus("failed");
+      return { failure: `${failure}\nwatcher: FAILED - OpenCode could not restore watcher continuity because the unready successor arm did not exit within ${ARM_RETIRE_TIMEOUT_MS}ms` };
+    }
+    if (status === "read-only" || status === "not-primary" || status === "skipped") break;
+    if (attempt === REARM_RETRY_LIMIT) break;
+    await waitForRetry(attempt + 1);
+  }
+  setArmStatus("failed");
+  return { failure: `${failure}\nwatcher: FAILED - OpenCode could not restore watcher continuity after ${REARM_RETRY_LIMIT} retries` };
+}
+
+async function scheduleRetry(paths, sessionID, client, reason, predecessorArmPid) {
+  if (child || retryTimer) return;
+  if (!(await sessionOwnsLock(paths))) {
+    setArmStatus("failed");
+    surfaceFailure(paths, client, sessionID, `watcher: FAILED - OpenCode cannot restore continuity because this session no longer owns the lock\n${reason}`);
+    return;
+  }
+  retryFailures += 1;
+  if (retryFailures > REARM_RETRY_LIMIT) {
+    setArmStatus("failed");
+    surfaceFailure(paths, client, sessionID, `watcher: FAILED - OpenCode could not restore watcher continuity after ${REARM_RETRY_LIMIT} retries\n${reason}`);
+    return;
+  }
+  setArmStatus("retrying");
+  const timer = setTimeout(() => {
+    if (retryTimer === timer) retryTimer = null;
+    void ensureArm(paths, sessionID, client, predecessorArmPid).then((status) => {
+      if (["armed", "starting", "wake"].includes(status)) return;
+      surfaceFailure(paths, client, sessionID, `watcher: FAILED - OpenCode could not launch a continuity retry (${status})`);
+    });
+  }, retryDelay(retryFailures));
+  timer.unref();
+  retryTimer = timer;
+}
+
+function spawnArm(paths, sessionID, client, predecessorArmPid = "") {
+  setArmStatus("starting");
+  const env = {
+    ...process.env,
+    BROKK_HOME: paths.home,
+    BROKK_ROOT_OVERRIDE: paths.root,
+    BROKK_CONFIG_OVERRIDE: paths.config,
+    BROKK_STATE_OVERRIDE: paths.state,
+    BROKK_WATCH_PREDECESSOR_ARM_PID: predecessorArmPid,
+  };
+  const armChild = spawn("bash", ["-lc", 'config_dir="${BROKK_CONFIG_OVERRIDE:-$BROKK_HOME/config}"; [ -f "$config_dir/x-mode.env" ] && . "$config_dir/x-mode.env"; exec "$BROKK_ROOT_OVERRIDE/bin/syn-watch-arm.sh" --restart'], {
+    cwd: paths.root,
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  child = armChild;
+  let stdout = "";
+  let stderr = "";
+  let settled = false;
+  let resolveClosed = null;
+  let readinessSettled = false;
+  let resolveReadiness = null;
+  const readiness = new Promise((resolve) => {
+    resolveReadiness = resolve;
+  });
+  armReadiness.set(armChild, readiness);
+  const settleReadiness = (status) => {
+    if (readinessSettled) return;
+    readinessSettled = true;
+    resolveReadiness(status);
+  };
+  const closed = new Promise((resolveClosedChild) => {
+    resolveClosed = resolveClosedChild;
+  });
+  armClose.set(armChild, closed);
+  const releaseChild = () => {
+    if (child === armChild) child = null;
+  };
+  const observeRecovery = () => {
+    const recovery = `${stdout}\n${stderr}`.match(/^watcher: started pid=([0-9]+).* recovery-generation=([A-Za-z0-9._-]+)$/m);
+    if (recovery) armRecovery.set(armChild, { watcherPid: recovery[1], generation: recovery[2] });
+  };
+  armChild.stdout.on("data", (chunk) => {
+    stdout += chunk.toString();
+    observeRecovery();
+    observeArmOutput(stdout, stderr, settleReadiness);
+  });
+  armChild.stderr.on("data", (chunk) => {
+    stderr += chunk.toString();
+    observeRecovery();
+    observeArmOutput(stdout, stderr, settleReadiness);
+  });
+  armChild.on("close", (code, signal) => {
+    if (settled) return;
+    settled = true;
+    resolveClosed();
+    releaseChild();
+    const classification = classifyArmClose(stdout, stderr, code, signal);
+    settleReadiness(classification.kind === "actionable" ? "wake" : "failed");
+    const predecessor = String(armChild.pid ?? "");
+    if (classification.kind === "actionable") {
+      if (restorationInFlight) return;
+      retryFailures = 0;
+      setArmStatus("wake");
+      const restoration = restoreAfterActionableClose(paths, sessionID, client, predecessor);
+      restorationInFlight = restoration;
+      void restoration.then(async (result) => {
+        try {
+          const message = result.failure ? `${classification.message}\n\n${result.failure}` : classification.message;
+          await deliverActionableWake(paths, client, sessionID, message, result.recovery);
+        } finally {
+          if (restorationInFlight === restoration) restorationInFlight = null;
+        }
+      }).catch((error) => {
+        if (restorationInFlight === restoration) restorationInFlight = null;
+        surfaceFailure(
+          paths,
+          client,
+          sessionID,
+          `watcher: FAILED - OpenCode could not deliver an actionable wake\n${String(error?.message ?? error)}`,
+        );
+      });
+      return;
+    }
+    if (restorationInFlight) {
+      setArmStatus("failed");
+      return;
+    }
+    void scheduleRetry(paths, sessionID, client, classification.message, predecessor);
+  });
+  armChild.on("error", (error) => {
+    if (settled) return;
+    settled = true;
+    resolveClosed();
+    releaseChild();
+    settleReadiness("failed");
+    if (restorationInFlight) {
+      setArmStatus("failed");
+      return;
+    }
+    void scheduleRetry(
+      paths,
+      sessionID,
+      client,
+      `watcher: FAILED - OpenCode arm child failed: ${error.message}`,
+      String(armChild.pid ?? ""),
+    );
+  });
+  return armChild;
+}
+
+async function beginArm(paths, sessionID, client, predecessorArmPid) {
+  if (!sessionID) return { status: "skipped", armChild: null };
+  if (!(await isPrimaryRoot(paths.root, paths.home))) return { status: "not-primary", armChild: null };
+  if (!(await sessionOwnsLock(paths))) return { status: "read-only", armChild: null };
+  if (child) return { status: "existing", armChild: child };
+  if (retryTimer) return { status: "retrying", armChild: null };
+  if (!shouldArm(paths)) return { status: "not-needed", armChild: null };
+  return { status: "spawned", armChild: spawnArm(paths, sessionID, client, predecessorArmPid) };
+}
+
+function armAttempt(status, armChild, includeArmChild) {
+  return includeArmChild ? { status, armChild } : status;
+}
+
+async function ensureArm(paths, sessionID, client, predecessorArmPid = "", includeArmChild = false) {
+  let launchResult = null;
+  if (!launchInFlight) {
+    const launch = beginArm(paths, sessionID, client, predecessorArmPid);
+    launchInFlight = launch;
+    try {
+      launchResult = await launch;
+    } finally {
+      if (launchInFlight === launch) launchInFlight = null;
+    }
+  } else {
+    launchResult = await launchInFlight;
+  }
+  const armChild = launchResult.armChild;
+  if (!armChild) {
+    return armAttempt(launchResult.status, null, includeArmChild);
+  }
+  return armAttempt(await waitForArmReady(armChild), armChild, includeArmChild);
+}
+
+export const SynWatchArm = async ({ client, directory, worktree }) => {
+  const root = worktree ? resolvePath(worktree) : await resolveRoot(directory);
+  const paths = effectivePaths(root);
+  globalThis[COORDINATOR_KEY] = {
+    ensureArmed: (sessionID, activeClient) => ensureArm(paths, sessionID, activeClient ?? client),
+  };
+
+  return {
+    event: async ({ event }) => {
+      if (event.type !== "session.idle") return;
+      const sessionID = event.properties?.sessionID;
+      if (!sessionID) return;
+      void ensureArm(paths, sessionID, client);
+    },
+  };
+};

package/.agents/memory/README.md

@@ -0,0 +1,46 @@
+# MIMIRSBRUNN — Vector Memory & Audit Ledger
+
+Long-term memory and the system audit trail for **this machine**.
+
+## What is tracked here, and what is not
+
+The well is **per-machine**. It is "one repo-local store shared by every agent"
+on *this* host — never shared between hosts or users. A fresh clone must start
+empty and build its own memory; it must never inherit someone else's.
+
+```
+memory_contract[5]{path,tracked,why}:
+  "README.md","yes","this contract — the only file that belongs in git"
+  "kaia.engram","NO","the store: this machine's private memory (gitignored)"
+  "kaia.engram-wal / -shm","NO","SQLite volatile sidecars; a stale WAL can corrupt a fresh clone"
+  "well/*.jsonl","NO","the append log: the same per-machine data"
+  "runes_audit.md","careful","append-only ledger; see the note below"
+```
+
+`.gitignore` enforces this (`.agents/memory/kaia.engram*`, `*.db`, `well/*.jsonl`).
+If a file here is tracked and mutates at runtime, that is a bug: it dirties every
+checkout and leaks one machine's data to every other.
+
+**Rebuilding the store.** The JSONL log is the source of truth for re-seeding;
+`bin/mimir-ingest.sh` drinks a directory into it. A new machine starts with no
+store and fills it as it works — that is correct, not a failure.
+
+## Audit ledger note
+
+`workspace/memory/runes_audit.md` is the append-only Runes ledger. It is tracked
+because the audit trail is part of the record, but it is written by every machine
+that runs Ymir. When two machines both append, the checksum chain diverges. The
+law: **one writer per ledger.** If a merge would fork the chain, keep the
+canonical chain and preserve the other side as a `state/*.bak` file rather than
+interleaving entries.
+
+## Files
+
+- `kaia.engram` — the store (episodes, facts, entities, edges). Per machine.
+- `well/*.jsonl` — the raw episode log (source of truth for re-seeding).
+- `runes_audit.md` — the append-only audit ledger (see the note above).
+
+## Memory Tiers
+
+1. **Hot** — `svartalfaheim/<realm>/workspace/*.md`
+2. **Deep** — the engram store, indexed from workspace changes

package/.agents/memory/runes_audit.md

@@ -0,0 +1,5 @@
+# YGGDRASIL Audit Trail
+> Append-only log of all significant system actions
+
+---
+