create-egregore 0.19.33 → 0.20.0

package/runtime/prime/.prime/agent/extensions/egregore.ts

@@ -0,0 +1,460 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import {
+  isConsentCommand,
+  isMutatingBash,
+  isMutatingIpython,
+  isRuntimeStatePath,
+  mutatesOnlyRuntimeState,
+} from "../../../bin/pi-branch-policy.mjs";
+import {
+  activityDataPath,
+  captureSessionEnd,
+  createHandoff,
+  lastActivityJson,
+  parseViewRequest,
+  publishScroll,
+  renderActivity,
+  renderGreeting,
+  renderView,
+  workflowPrompt,
+} from "../../../bin/pi-product-workflows.mjs";
+
+const PROTECTED_BRANCHES = new Set(["main", "master", "develop"]);
+// Prime Agent built-in slash commands (README Commands table) plus
+// conservative extras for surfaces added around launch. An Egregore skill
+// with a colliding name stays reachable via /skill:<name>.
+const BUILTIN_COMMANDS = new Set([
+  "login", "logout", "model", "effort", "scoped-models", "settings", "resume",
+  "new", "clear", "name", "session", "traces", "usage", "tree", "fork",
+  "clone", "compact", "copy", "btw", "side", "export", "share", "reload",
+  "hotkeys", "changelog", "quit", "skill", "mcp",
+  "refine", "autonomous", "trust", "import", "agents", "harness", "schedule",
+  "goal", "memory",
+  // Observed at runtime (not in the README command table); Prime warns and
+  // skips conflicting extension commands in autocomplete, so any future
+  // collision is visible and non-fatal — add it here to keep startup quiet.
+  "update",
+]);
+const PRODUCT_COMMANDS = new Set(["activity", "view", "handoff", "scroll"]);
+const PRIME_SPEC = { runtimeName: "Prime Agent", specPath: ".prime/agent/APPEND_SYSTEM.md" };
+
+function skillDescription(skillFile) {
+  try {
+    const body = readFileSync(skillFile, "utf8");
+    return body.match(/^description:\s*['"]?(.+?)['"]?\s*$/m)?.[1] || "Run an Egregore workflow";
+  } catch {
+    return "Run an Egregore workflow";
+  }
+}
+
+function messageText(result) {
+  return (result?.content || [])
+    .filter((item) => item?.type === "text")
+    .map((item) => item.text)
+    .join("\n");
+}
+
+function compactToolResult(result, options, theme, working) {
+  if (options.isPartial) return new Text(theme.fg("muted", working), 0, 0);
+  const text = result?.details?.text || messageText(result) || "Done";
+  return new Text(result?.details?.text ? text : theme.fg("error", text), 0, 0);
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function nearestExistingDirectory(candidate) {
+  let cursor = resolve(candidate);
+  try {
+    if (existsSync(cursor) && !statSync(cursor).isDirectory()) cursor = dirname(cursor);
+  } catch {}
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    cursor = parent;
+  }
+  return cursor;
+}
+
+async function gitContext(pi, candidate) {
+  const probe = nearestExistingDirectory(candidate);
+  const topResult = await pi.exec("git", ["-C", probe, "rev-parse", "--show-toplevel"], { timeout: 5000 });
+  const top = String(topResult.stdout || "").trim();
+  if (!top) return null;
+  const commonResult = await pi.exec("git", ["-C", top, "rev-parse", "--git-common-dir"], { timeout: 5000 });
+  const commonRaw = String(commonResult.stdout || "").trim();
+  return {
+    top: resolve(top),
+    common: resolve(top, commonRaw || ".git"),
+  };
+}
+
+export default function egregore(pi) {
+  const root = process.cwd();
+  const skillsDir = join(root, ".codex", "skills");
+  let workflowCount = 0;
+  let lastSyncAt = 0;
+  let activeWorkflow = "";
+  const hasEntryRenderer = typeof pi.registerEntryRenderer === "function";
+  const prompt = (name, args, extra = "") => workflowPrompt(name, args, extra, PRIME_SPEC);
+
+  const appendCard = (kind, text) => {
+    const content = String(text || "").trimEnd();
+    if (hasEntryRenderer) {
+      pi.appendEntry("egregore-card", { kind, text: content });
+      return;
+    }
+    pi.sendMessage({
+      customType: "egregore-card",
+      content,
+      display: true,
+      details: { kind },
+    }, { triggerTurn: false });
+  };
+
+  const setBusy = (ctx, label) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setStatus("egregore-workflow", label ? `● ${label}` : undefined);
+  };
+
+  const sendQuietWorkflow = (name, args, ctx, options = {}) => {
+    activeWorkflow = name;
+    if (ctx.hasUI) {
+      ctx.ui.setToolsExpanded?.(false);
+      ctx.ui.setWorkingMessage?.(options.working || `Running /${name}…`);
+    }
+    const content = options.prompt || prompt(name, args, options.extra || "");
+    if (typeof pi.sendMessage === "function") {
+      pi.sendMessage({
+        customType: "egregore-workflow",
+        content,
+        display: false,
+        details: { command: name },
+      }, { triggerTurn: true, deliverAs: "steer" });
+    } else {
+      pi.sendUserMessage(content);
+    }
+  };
+
+  if (hasEntryRenderer) {
+    pi.registerEntryRenderer("egregore-card", (entry) => {
+      return new Text(String(entry.data?.text || ""), 0, 0);
+    });
+  } else if (typeof pi.registerMessageRenderer === "function") {
+    pi.registerMessageRenderer("egregore-card", (message) => {
+      return new Text(String(message.content || ""), 0, 0);
+    });
+  }
+
+  pi.registerTool({
+    name: "egregore_handoff",
+    label: "Egregore Handoff",
+    description: "Create one internal Egregore team handoff from structured session context. Use only for the /handoff workflow.",
+    parameters: Type.Object({
+      topic: Type.String({ description: "Short operational topic" }),
+      recipient: Type.Optional(Type.String({ description: "Known teammate handle; omit when uncertain" })),
+      briefing: Type.String({ description: "Concise operational briefing" }),
+      key_decisions: Type.String({ description: "Markdown bullets of settled decisions" }),
+      current_state: Type.String({ description: "Exact implementation and verification state" }),
+      open_threads: Type.String({ description: "Markdown bullets of unresolved work" }),
+      next_steps: Type.String({ description: "Ordered, actionable next steps" }),
+      entry_points: Type.String({ description: "Exact files, branches, commands, and URLs" }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const receipt = await createHandoff(pi, root, params, signal);
+      return {
+        content: [{ type: "text", text: `Handoff created${receipt.path ? ` at ${receipt.path}` : ""}.` }],
+        details: { ...receipt },
+      };
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("muted", "⇌ Preparing handoff…"), 0, 0);
+    },
+    renderResult(result, options, theme) {
+      return compactToolResult(result, options, theme, "⇌ Preparing handoff…");
+    },
+  });
+
+  pi.registerTool({
+    name: "egregore_publish_scroll",
+    label: "Publish Egregore Scroll",
+    description: "Validate, publish, open, and receipt a completed Egregore scroll. Use only as the final action of /scroll.",
+    parameters: Type.Object({
+      source: Type.String({ description: "Project-relative tmp/<slug>/index.html source" }),
+      slug: Type.String({ description: "Stable scroll id reused across versions" }),
+      title: Type.String(),
+      author: Type.String(),
+      description: Type.String(),
+      version: Type.String({ description: "Version marker such as v1" }),
+    }),
+    async execute(_toolCallId, params, signal) {
+      const receipt = await publishScroll(pi, root, params, signal);
+      return {
+        content: [{ type: "text", text: `Scroll ${receipt.version} opened at ${receipt.url || receipt.path}.` }],
+        details: { ...receipt },
+      };
+    },
+    renderCall(_args, theme) {
+      return new Text(theme.fg("muted", "◉ Publishing scroll…"), 0, 0);
+    },
+    renderResult(result, options, theme) {
+      return compactToolResult(result, options, theme, "◉ Publishing scroll…");
+    },
+  });
+
+  if (existsSync(skillsDir)) {
+    for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() || BUILTIN_COMMANDS.has(entry.name)) continue;
+      const skillFile = join(skillsDir, entry.name, "SKILL.md");
+      if (!existsSync(skillFile)) continue;
+      workflowCount += 1;
+      if (PRODUCT_COMMANDS.has(entry.name)) continue;
+      pi.registerCommand(entry.name, {
+        description: skillDescription(skillFile),
+        handler: async (args, ctx) => sendQuietWorkflow(entry.name, args, ctx),
+      });
+    }
+  }
+
+  pi.registerCommand("activity", {
+    description: skillDescription(join(skillsDir, "activity", "SKILL.md")),
+    handler: async (_args, ctx) => {
+      setBusy(ctx, "Refreshing activity");
+      try {
+        const shouldSync = Date.now() - lastSyncAt > 60_000;
+        const card = await renderActivity(pi, root, ctx.signal, { sync: shouldSync });
+        lastSyncAt = Date.now();
+        appendCard("activity", card);
+      } catch (error) {
+        ctx.ui.notify(`Activity: ${errorMessage(error)}`, "error");
+        return;
+      } finally {
+        setBusy(ctx, "");
+      }
+
+      if (!ctx.hasUI) return;
+      const focus = await ctx.ui.select("Focus", ["Handoffs", "Questions", "Recent work", "Dashboard", "Done"]);
+      if (!focus || focus === "Done") return;
+      const command = focus === "Dashboard" ? "dashboard" : "activity";
+      // Hand the model the complete data the extension already fetched, as a
+      // file: one fast kernel read, never truncated, no reason to re-run the
+      // time-capped data script or spelunk renderer sources.
+      const cached = lastActivityJson();
+      const focusPrompt = focus === "Dashboard"
+        ? prompt("dashboard", "")
+        : [
+          `Continue the Egregore /activity workflow with focus: ${focus.toLowerCase()}.`,
+          "Output nothing except the final rendered result — no prose, planning, or narration between commands.",
+          cached
+            ? `The complete activity data is already fresh at ${relative(root, activityDataPath(root))} — read that file in one call; do NOT re-run bin/activity-data.sh, read renderer sources, or run other data commands.`
+            : "",
+          "If required data is missing or a command fails, render the single line '◦ activity data unavailable' and stop — never debug data plumbing inside this workflow.",
+          "Rows without a topic: show the branch name instead; with neither, omit the row — never print (untitled).",
+        ].filter(Boolean).join("\n");
+      sendQuietWorkflow(command, "", ctx, { prompt: focusPrompt, working: `Opening ${focus.toLowerCase()}…` });
+    },
+  });
+
+  pi.registerCommand("view", {
+    description: skillDescription(join(skillsDir, "view", "SKILL.md")),
+    handler: async (args, ctx) => {
+      let request = parseViewRequest(root, args);
+      if (request.kind === "choose" && ctx.hasUI) {
+        const choice = await ctx.ui.select("Open a view", ["Activity", "Board", "Network", "Document or topic…"]);
+        if (!choice) return;
+        if (choice === "Document or topic…") {
+          const target = await ctx.ui.input("Document or topic", "path, handoff, quest, or subject");
+          if (!target) return;
+          request = parseViewRequest(root, target);
+        } else {
+          request = parseViewRequest(root, choice.toLowerCase());
+        }
+      }
+
+      if (request.kind === "choose-file" && ctx.hasUI) {
+        const labels = request.matches.map((file) => relative(root, file));
+        const selected = await ctx.ui.select("Choose a source", labels);
+        if (!selected) return;
+        request = { kind: "native", type: request.type, source: join(root, selected), fast: request.fast };
+      }
+
+      if (request.kind !== "native") {
+        sendQuietWorkflow("view", args, ctx, {
+          working: "Composing view…",
+          extra: "Open the browser artifact and return only the compact receipt required by the skill.",
+        });
+        return;
+      }
+
+      setBusy(ctx, "Opening view");
+      try {
+        const receipt = await renderView(pi, root, request, ctx.signal);
+        appendCard("view", receipt.text);
+      } catch (error) {
+        ctx.ui.notify(`View: ${errorMessage(error)}`, "error");
+      } finally {
+        setBusy(ctx, "");
+      }
+    },
+  });
+
+  pi.registerCommand("handoff", {
+    description: skillDescription(join(skillsDir, "handoff", "SKILL.md")),
+    handler: async (args, ctx) => {
+      const people = existsSync(join(root, "memory", "people"))
+        ? readdirSync(join(root, "memory", "people"))
+          .filter((name) => name.endsWith(".md") && name !== "README.md")
+          .map((name) => name.replace(/\.md$/, ""))
+          .slice(0, 40)
+        : [];
+      const handoffPrompt = [
+        "Create the requested internal Egregore handoff from the current conversation and repository context.",
+        "Call egregore_handoff exactly once. Do not call bash, write, edit, or read the handoff skill; the tool implements the full contract.",
+        "Keep every field concise and operational. Include exact files, branch, commands, open questions, and verification state.",
+        "Omit recipient when uncertain. Do not use the deprecated egregore-handoff CLI.",
+        args?.trim() ? `User arguments: ${args.trim()}` : "Infer the topic and intended recipient from the conversation.",
+        people.length ? `Known teammate handles: ${people.join(", ")}` : "",
+        "After the tool succeeds, do not repeat its card or add a success preamble.",
+      ].filter(Boolean).join("\n");
+      sendQuietWorkflow("handoff", args, ctx, { prompt: handoffPrompt, working: "Preparing handoff…" });
+    },
+  });
+
+  pi.registerCommand("scroll", {
+    description: skillDescription(join(skillsDir, "scroll", "SKILL.md")),
+    handler: async (args, ctx) => {
+      sendQuietWorkflow("scroll", args, ctx, {
+        working: "Composing scroll…",
+        extra: [
+          "Use egregore_publish_scroll exactly once as the final validation, publish, open, and receipt step.",
+          "Do not run publish-artifact.sh or a browser opener directly.",
+          "Return only what changed, the stable URL or local path, the source path, and the versioned decision fence.",
+        ].join("\n"),
+      });
+    },
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setToolsExpanded?.(false);
+    if (workflowCount > 0) ctx.ui.setStatus("egregore", `Egregore · ${workflowCount} workflows`);
+    if (event.reason !== "startup") return;
+
+    setBusy(ctx, "Loading team context");
+    try {
+      const card = await renderGreeting(pi, root, ctx.signal, "prime-session-start.sh");
+      lastSyncAt = Date.now();
+      appendCard("greeting", card);
+    } catch (error) {
+      ctx.ui.notify(`Startup: ${errorMessage(error)}`, "warning");
+    } finally {
+      setBusy(ctx, "");
+    }
+  });
+
+  pi.on("session_shutdown", async (event, ctx) => {
+    // Reload keeps the same logical session alive. Every other graceful
+    // shutdown is Prime Agent's equivalent of Claude Code's SessionEnd hook.
+    if (event?.reason === "reload") return;
+    try {
+      await captureSessionEnd(pi, root, ctx.sessionManager.getSessionFile(), undefined, "prime");
+    } catch {
+      // Loss-prevention capture must never prevent the harness from exiting.
+      // The attendant remains the fallback for interrupted or failed shutdowns.
+    }
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (!activeWorkflow || !ctx.hasUI) return;
+    activeWorkflow = "";
+    ctx.ui.setWorkingMessage?.();
+    ctx.ui.setToolsExpanded?.(false);
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    const isFileWrite = event.toolName === "write" || event.toolName === "edit";
+    const command = String(event.input?.command || "");
+    // Prime Agent's default surface is the persistent IPython kernel: file
+    // writes and shell escapes arrive as Python code, not bash tool calls.
+    const ipythonCode = event.toolName === "ipython" ? String(event.input?.code || "") : "";
+    const mutates = isFileWrite ||
+      (event.toolName === "bash" && isMutatingBash(command)) ||
+      (event.toolName === "ipython" && isMutatingIpython(ipythonCode, ctx.cwd));
+    if (!mutates) return;
+
+    // Resolve the branch in the git context the write actually lands in.
+    // Task worktrees from `bin/agent.sh branch` live outside ctx.cwd but sit
+    // on a task branch, so checking ctx.cwd alone blocks legitimate worktree
+    // edits whenever the session checkout itself is on develop. Memory and
+    // managed repos have a different Git common dir and are outside this guard.
+    const hub = await gitContext(pi, ctx.cwd);
+    if (event.toolName === "bash" && mutatesOnlyRuntimeState(command, hub?.top || ctx.cwd)) return;
+    if (event.toolName === "ipython" && hub && hub.top !== ctx.cwd &&
+        !isMutatingIpython(ipythonCode, hub.top)) return;
+    let operation = hub;
+    if (isFileWrite) {
+      const targetPath = String(event.input?.path || "");
+      const abs = isAbsolute(targetPath) ? targetPath : join(ctx.cwd, targetPath);
+      if (hub && isRuntimeStatePath(abs, hub.top)) return;
+      operation = await gitContext(pi, abs);
+      if (!operation && hub) {
+        const rel = relative(hub.top, abs);
+        if (rel.startsWith("..") || isAbsolute(rel)) return;
+      }
+    } else if (event.toolName === "bash") {
+      // bash: `git -C PATH` or a leading `cd DIR &&` retargets the command
+      // away from ctx.cwd — resolve the branch where it actually runs so
+      // worktree commits (git -C $WT commit) aren't misjudged by the session
+      // checkout's branch.
+      const gitC = command.match(/(?:^|[;&|]\s*)git\s+-C\s+("[^"]*"|'[^']*'|\S+)/);
+      const cdAnd = command.match(/^\s*cd\s+("[^"]*"|'[^']*'|\S+)\s*&&/);
+      const raw = (gitC && gitC[1]) || (cdAnd && cdAnd[1]);
+      if (raw) {
+        const target = raw.replace(/^['"]|['"]$/g, "");
+        const abs = isAbsolute(target) ? target : join(ctx.cwd, target);
+        operation = await gitContext(pi, abs);
+      }
+    }
+
+    if (hub && operation && operation.common !== hub.common) return;
+    const gitDir = operation?.top || hub?.top || ctx.cwd;
+    const result = await pi.exec("git", ["-C", gitDir, "branch", "--show-current"], { timeout: 5000 });
+    const branch = String(result.stdout || "").trim();
+    let configuredBase = "develop";
+    try {
+      const config = JSON.parse(readFileSync(join(gitDir, "egregore.json"), "utf8"));
+      if (typeof config.base_branch === "string" && config.base_branch.trim()) {
+        configuredBase = config.base_branch.trim();
+      }
+    } catch {}
+    if (!PROTECTED_BRANCHES.has(branch) && branch !== configuredBase) return;
+
+    // The documented escape hatch must itself be runnable: recording consent
+    // (echo 'develop' into .egregore-branch-consent) contains a redirect and
+    // would otherwise be blocked by this very gate.
+    if (event.toolName === "bash" || event.toolName === "ipython") {
+      const probe = event.toolName === "bash"
+        ? String(event.input?.command || "").trim()
+        : ipythonCode.replace(/^\s*!/, "").trim();
+      if (isConsentCommand(probe, branch)) return;
+    }
+
+    const consentFile = join(gitDir, ".egregore-branch-consent");
+    if (existsSync(consentFile) && readFileSync(consentFile, "utf8").trim() === branch) return;
+
+    return {
+      block: true,
+      reason: [
+        `Protected branch (${branch}). Move project work to a task branch before writing.`,
+        `If the work topic is clear, run bin/agent.sh branch --topic "<work topic>" automatically and continue in the printed worktree; do not ask for routine Git permission.`,
+        `Ask only when the topic is genuinely ambiguous.`,
+        `Only when the user explicitly requested ${branch}, record consent with: echo '${branch}' > .egregore-branch-consent`,
+        "Memory, managed-repo, and runtime-state writes should bypass this project guard.",
+      ].join("\n"),
+    };
+  });
+}

package/runtime/prime/.prime/agent/settings.json

@@ -0,0 +1,4 @@
+{
+  "skills": ["../../.codex/skills"],
+  "enableSkillCommands": false
+}

package/runtime/prime/.prime/agent/skills/egregore/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: egregore
+description: Egregore mechanics as kernel functions — search shared memory, read team activity, create handoffs, save work, branch, and prepare notification plans without re-deriving bin/ CLI usage. Import and call directly; every function wraps the same runtime-neutral bin/ scripts the other harnesses use.
+---
+
+# egregore — kernel bridge to Egregore mechanics
+
+Python-backed skill. The module is installed into the kernel venv; call the
+functions directly instead of grepping `bin/` scripts to reconstruct CLI usage:
+
+```python
+import egregore
+
+egregore.search("pricing decision")          # ranked shared-memory recall
+egregore.activity()                          # team activity JSON
+egregore.handoff(to="renc", topic="...", body="...")
+egregore.save(message="Save: topic", topic="topic")
+egregore.branch("new topic")                 # task branch + worktree
+egregore.notify_plan(recipient="renc", message="...")  # proposal ONLY
+```
+
+Ground rules:
+
+- Every function shells out to the corresponding `bin/` script with a generous
+  internal timeout and returns its text output. `bin/` stays the single
+  mechanics layer — this module contains no logic of its own.
+- `notify_plan` only CREATES a notification plan. Approval and dispatch remain
+  subject to the explicit human Send / Edit / Cancel checkpoint: show the plan,
+  get the user's approval, then run `bin/notify.sh approve` / `dispatch` with
+  the plan's one-use approval token. Never call approve or dispatch without a
+  fresh human yes in this conversation.
+- Functions raise `RuntimeError` with the script's stderr on failure — report
+  the single relevant line, do not debug the plumbing mid-workflow.
+- `help()` on the module or any function shows signatures and semantics.

package/runtime/prime/.prime/agent/skills/egregore/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "egregore"
+version = "0.1.0"
+description = "Egregore mechanics as Prime Agent kernel functions (thin wrappers over bin/ scripts)"
+requires-python = ">=3.10"
+dependencies = []
+
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

package/runtime/prime/.prime/agent/skills/egregore/src/egregore/__init__.py

@@ -0,0 +1,156 @@
+"""Egregore mechanics as kernel functions.
+
+Thin wrappers over the runtime-neutral ``bin/`` scripts of the enclosing
+Egregore checkout. No logic lives here: every function resolves the instance
+root from the current working directory, shells out to the same script the
+other harnesses use, and returns its text output.
+
+Consent boundary: :func:`notify_plan` only creates a proposal. Approving and
+dispatching a notification require an explicit human Send / Edit / Cancel
+checkpoint in the conversation — this module deliberately provides no
+``notify_approve``/``notify_dispatch`` so that step stays visible.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+__all__ = [
+    "activity",
+    "branch",
+    "handoff",
+    "instance_root",
+    "notify_plan",
+    "run",
+    "save",
+    "search",
+]
+
+_DEFAULT_TIMEOUT = 120
+
+
+def instance_root(start: str | os.PathLike | None = None) -> Path:
+    """Walk up from ``start`` (default: cwd) to the directory holding egregore.json."""
+    cursor = Path(start or os.getcwd()).resolve()
+    for candidate in (cursor, *cursor.parents):
+        if (candidate / "egregore.json").is_file():
+            return candidate
+    raise RuntimeError(
+        "not inside an Egregore instance (no egregore.json above %s)" % cursor
+    )
+
+
+def _run_script(args: list[str], timeout: int = _DEFAULT_TIMEOUT) -> str:
+    root = instance_root()
+    script = root / args[0]
+    if not script.is_file():
+        raise RuntimeError(f"missing script: {script}")
+    try:
+        result = subprocess.run(
+            ["bash", *args],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            start_new_session=True,
+        )
+    except subprocess.TimeoutExpired as exc:
+        # Own process group (start_new_session) so the timeout kills the real
+        # workers, not just the bash wrapper; surface it as the documented
+        # RuntimeError instead of an uncaught traceback in the kernel.
+        raise RuntimeError(f"{args[0]} timed out after {timeout}s") from exc
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip().splitlines()
+        raise RuntimeError(
+            f"{args[0]} failed (exit {result.returncode}): {detail[-1] if detail else 'no output'}"
+        )
+    return result.stdout.strip()
+
+
+def search(query: str, limit: int = 6) -> str:
+    """Ranked shared-memory recall (decisions, handoffs, knowledge, meetings)."""
+    return _run_script(["bin/search.sh", "query", query, "-n", str(limit)])
+
+
+def activity(for_user: str | None = None) -> str:
+    """Team activity: handoffs, questions, and recent work.
+
+    Returns the runtime-neutral ``bin/agent.sh activity`` text view; pass
+    ``for_user`` to scope to a handle.
+    """
+    args = ["bin/agent.sh", "activity"]
+    if for_user:
+        args += ["--for", for_user]
+    return _run_script(args)
+
+
+def branch(topic: str) -> str:
+    """Create a task branch + worktree for ``topic``; returns branch and path."""
+    return _run_script(["bin/agent.sh", "branch", "--topic", topic])
+
+
+def save(message: str, topic: str, pr_body: str | None = None) -> str:
+    """Commit, push, and open/update the PR for the current working branch."""
+    args = ["bin/agent.sh", "save", "--message", message, "--topic", topic]
+    if pr_body:
+        args += ["--pr-body", pr_body]
+    return _run_script(args, timeout=300)
+
+
+def handoff(
+    to: str | None,
+    topic: str,
+    body: str,
+    sender: str | None = None,
+    notify: bool = False,
+) -> str:
+    """Create an internal handoff document addressed to ``to``.
+
+    ``notify=False`` (default) skips the notification leg entirely; enabling it
+    still routes through the plan/approve/dispatch consent protocol.
+    """
+    root = instance_root()
+    if sender is None:
+        try:
+            state = json.loads((root / ".egregore-state.json").read_text())
+            sender = state.get("github_username") or "unknown"
+        except (OSError, ValueError):
+            sender = "unknown"
+    args = [
+        "bin/agent.sh", "handoff",
+        "--from", sender,
+        "--topic", topic,
+        "--body", body,
+    ]
+    if to:
+        args += ["--to", to]
+    if not notify:
+        args += ["--no-notify"]
+    return _run_script(args, timeout=300)
+
+
+def notify_plan(recipient: str | None, message: str) -> str:
+    """Create a notification PLAN (proposal only — nothing is sent).
+
+    ``recipient`` is a person's handle for a DM, or ``None`` for the group
+    channel. Show the returned plan (recipient, channel, exact message, plan
+    id and one-use approval token) to the user in a Send / Edit / Cancel
+    checkpoint. Only after an explicit yes run ``bin/notify.sh approve`` and
+    ``dispatch`` yourself — this module intentionally stops at the plan.
+    """
+    if recipient:
+        return _run_script(["bin/notify.sh", "plan", "send", recipient, message])
+    return _run_script(["bin/notify.sh", "plan", "group", message])
+
+
+def run() -> str:
+    """Discovery entry point: list the bridge functions and the consent rule."""
+    return (
+        "egregore kernel bridge — search(query), activity(for_user=None), "
+        "branch(topic), save(message, topic), handoff(to, topic, body), "
+        "notify_plan(recipient, message). notify_plan is proposal-only: "
+        "approval and dispatch require an explicit human checkpoint."
+    )

package/runtime/prime/.prime/agent/spec-manifest.json

@@ -0,0 +1,12 @@
+{
+  "generatedBy": "bin/prime-render-spec.mjs",
+  "source": "AGENTS.md generated Codex spec",
+  "sourceHash": "72d7c3986402",
+  "outputHash": "6d17e4953725",
+  "adaptations": [
+    "Prime Agent APPEND_SYSTEM delivery from .prime/agent/",
+    "Prime Agent tool_call branch gate incl. ipython classification",
+    "Prime Agent slash-command extension over shared portable skills",
+    "rlm() subagents are not Loom lanes; Loom preambles run inline"
+  ]
+}