@xemahq/opencode-xema-plugin 0.3.0 → 0.4.0

package/{plugin.mjs → plugin/xema-runtime-bridge/index.js}

@@ -4,16 +4,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/index.ts
-import { existsSync as existsSync4 } from "node:fs";
-import { join as join5 } from "node:path";
-
-// src/hooks/session-idle-autocommit.ts
-import { execFile } from "node:child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
-import { join as join2 } from "node:path";
-import { promisify } from "node:util";
-
 // src/context.ts
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -19703,9 +19693,6 @@ function debug(msg) {
   if (!DEBUG_ENABLED) return;
   console.log(`${PREFIX} [debug] ${msg}`);
 }
-function isDebug() {
-  return DEBUG_ENABLED;
-}
 
 // src/context.ts
 var ContextJsonSchema = external_exports.object({
@@ -19730,7 +19717,8 @@ var ContextJsonSchema = external_exports.object({
       // reviewable change set from those edits.
       "document"
     ]),
-    surface: external_exports.enum(["pipeline-run", "agent-session", "design-system-builder", "gate-review"]).optional()
+    surface: external_exports.enum(["pipeline-run", "agent-session", "design-system-builder", "gate-review"]).optional(),
+    stageKey: external_exports.string().nullish()
   }),
   project: external_exports.object({
     orgId: external_exports.string(),
@@ -19767,35 +19755,11 @@ var ContextJsonSchema = external_exports.object({
     // ship the llm-registry-api that drops the field.
   }),
   /**
-   * Optional `git` block consumed by the `session.idle` auto-commit hook
-   * (see `hooks/session-idle-autocommit.ts`). Written by the orchestrator
-   * when the session's `BranchMode` opts into per-turn auto-commit
-   * (`shared_dev_publish_to_prod` — the default). Absent / `disabled` for
-   * `branch_per_session` sessions, where commits are user-controlled.
-   *
-   * `repoSubPath` is the working repo's path relative to the workspace
-   * root. When omitted, the hook commits at the workspace root itself
-   * (single-repo workspace contract — multi-repo workspaces are handled
-   * by a future follow-up; see TODO(multi-repo) in the
-   * hook).
+   * Working files the platform materialised (kernel `ContextJson.workingFiles`).
+   * Only `slug` and `path` are read — by the compaction hook, which carries
+   * them as continuation invariants. Unread fields are not validated here.
    */
-  git: external_exports.object({
-    autoCommit: external_exports.enum(["enabled", "disabled"]),
-    repoSubPath: external_exports.string().nullish()
-  }).nullish(),
-  /**
-   * Optional `actor` block consumed by the `session.idle` auto-commit
-   * hook. Mirrors `ActorRefDto` in workspace-git-api: the subject that
-   * triggered the turn. Stamped at session-start by the orchestrator
-   * (single-user binding) or rotated per-turn by the multi-user session
-   * extension. Absent for non-session invocations (pipeline-run agents
-   * never auto-commit).
-   */
-  actor: external_exports.object({
-    kind: external_exports.enum(["org_user"]),
-    subjectRef: external_exports.string().min(1),
-    displayName: external_exports.string().min(1)
-  }).nullish()
+  workingFiles: external_exports.array(external_exports.object({ slug: external_exports.string(), path: external_exports.string() }).loose()).optional()
 });
 function readInvocationContextForHook(workspaceDir, hookName) {
   const path = join(workspaceDir, "context.json");
@@ -19815,220 +19779,186 @@ function readInvocationContextForHook(workspaceDir, hookName) {
   }
 }
 
-// src/hooks/session-idle-autocommit.ts
-var HOOK_NAME = "session.idle";
-var DEFAULT_JWT_PATH = "/run/xema/actor.jwt";
-var PUSH_RETRY_DELAY_MS = 5e3;
-var execFileAsync = promisify(execFile);
-var conflictFlagBySessionId = /* @__PURE__ */ new Map();
-var turnCounterBySessionId = /* @__PURE__ */ new Map();
-function buildSessionIdleAutocommit(workspaceDir) {
-  return async (input2) => {
-    const evt = input2.event;
-    if (evt.type !== "session.idle") {
+// src/hooks/compaction-invariants.ts
+var XEMA_COMPACTION_METADATA_KEY = "xema.compaction-invariants";
+var MAX_COMPACTION_INVARIANTS_CHARS = 2e3;
+var MAX_LISTED_ITEMS = 20;
+function buildCompactionInvariantsHook(directory) {
+  return (input2) => {
+    const ctx = readInvocationContextForHook(directory, "session.compaction");
+    if (!ctx) {
       return;
     }
-    const idleEvent = evt;
-    try {
-      await handleSessionIdle(workspaceDir, idleEvent);
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      warn(
-        `hook=${HOOK_NAME}: unexpected error swallowed (auto-commit is best-effort): ${message}`
-      );
+    const text = renderCompactionInvariants(ctx);
+    const part = {
+      type: "text",
+      text,
+      metadata: { [XEMA_COMPACTION_METADATA_KEY]: true }
+    };
+    const existing = input2.system.findIndex(
+      (entry) => entry.metadata?.[XEMA_COMPACTION_METADATA_KEY] === true
+    );
+    if (existing === -1) {
+      input2.system.push(part);
+    } else {
+      input2.system[existing] = part;
     }
+    debug(`session.compaction: contributed ${text.length} chars of continuation invariants`);
   };
 }
-async function handleSessionIdle(workspaceDir, evt) {
-  const sessionId = evt.properties.sessionID;
-  if (!sessionId) {
-    debug(`hook=${HOOK_NAME}: event missing sessionID; skipping`);
-    return;
-  }
-  const ctx = readInvocationContextForHook(workspaceDir, HOOK_NAME);
-  if (!ctx) {
-    return;
-  }
-  if (ctx.git?.autoCommit !== "enabled") {
-    debug(
-      `hook=${HOOK_NAME}: session=${sessionId} autoCommit not enabled (got ${ctx.git?.autoCommit ?? "absent"}); skipping`
-    );
-    return;
-  }
-  if (!ctx.actor) {
-    warn(
-      `hook=${HOOK_NAME}: session=${sessionId} has git.autoCommit=enabled but no actor in context.json; skipping. The orchestrator must stamp context.actor for sessions opted into per-turn auto-commit.`
-    );
-    return;
-  }
-  const apiUrl = process.env.WORKSPACE_GIT_API_URL;
-  if (!apiUrl || apiUrl.length === 0) {
-    warn(
-      `hook=${HOOK_NAME}: session=${sessionId} WORKSPACE_GIT_API_URL env not set; skipping auto-commit. Wire the env into the worker container envelope.`
-    );
-    return;
+function listed(items) {
+  const shown = items.slice(0, MAX_LISTED_ITEMS).join(", ");
+  const more = items.length - MAX_LISTED_ITEMS;
+  return more > 0 ? `${shown} (+${more} more)` : shown;
+}
+function renderCompactionInvariants(ctx) {
+  const inv = ctx.invocation;
+  const lines = [
+    'Xema continuation invariants. Preserve these facts verbatim in the summary (under "## Additional Context"); they identify the invocation and its deliverable contract and must survive compaction. Do not invent anything beyond them.',
+    `- invocation: role=${inv.role}` + (inv.surface ? `, surface=${inv.surface}` : "") + (inv.runId ? `, runId=${inv.runId}` : "") + (inv.stageKey ? `, stageKey=${inv.stageKey}` : "") + (inv.sessionId ? `, sessionId=${inv.sessionId}` : "") + `, attempt=${inv.attempt}`,
+    `- writePolicy: ${ctx.authority.writePolicy}`
+  ];
+  if (ctx.authority.mayWriteSlugs.length > 0) {
+    lines.push(`- deliverable slugs: ${listed(ctx.authority.mayWriteSlugs)}`);
   }
-  const jwtPath = process.env.WORKER_ACTOR_JWT_PATH ?? DEFAULT_JWT_PATH;
-  const actorJwt = readActorJwt(jwtPath);
-  if (actorJwt === null) {
-    warn(
-      `hook=${HOOK_NAME}: session=${sessionId} actor JWT not readable at ${jwtPath}; skipping auto-commit. Verify the orchestrator mounts the actor JWT before session start.`
-    );
-    return;
+  const files = ctx.workingFiles ?? [];
+  if (files.length > 0) {
+    lines.push(`- working files: ${listed(files.map((file2) => `${file2.slug} \u2192 ${file2.path}`))}`);
   }
-  const repoSubPath = ctx.git.repoSubPath ?? null;
-  const repoDir = repoSubPath ? join2(workspaceDir, repoSubPath) : workspaceDir;
-  const dirty = await isGitTreeDirty(repoDir);
-  if (dirty === void 0) {
-    return;
+  const text = lines.join("\n");
+  return text.length > MAX_COMPACTION_INVARIANTS_CHARS ? `${text.slice(0, MAX_COMPACTION_INVARIANTS_CHARS - 1)}\u2026` : text;
+}
+
+// src/runtime-events.ts
+var TERMINAL_EVENT_TYPES = Object.freeze({
+  "session.execution.succeeded": "succeeded" /* Succeeded */,
+  "session.execution.failed": "failed" /* Failed */,
+  "session.execution.interrupted": "interrupted" /* Interrupted */
+});
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function parseRuntimeSessionEvent(event) {
+  if (!isRecord(event) || typeof event.type !== "string" || !isRecord(event.data)) {
+    return void 0;
   }
-  if (!dirty) {
-    debug(
-      `hook=${HOOK_NAME}: session=${sessionId} clean tree at ${repoDir}; skipping auto-commit`
-    );
-    return;
+  const sessionId = event.data.sessionID;
+  if (typeof sessionId !== "string" || sessionId.length === 0) {
+    return void 0;
   }
-  const turn = nextTurn(sessionId);
-  const body = {
-    turn,
-    actor: {
-      kind: ctx.actor.kind,
-      subjectRef: ctx.actor.subjectRef,
-      displayName: ctx.actor.displayName
-    },
-    // Wire contract: the worker reports the OUTCOME. For the v1
-    // hook we forward "needs commit; service will perform / record it
-    // via the workspace-proxy bridge once available". Until then
-    // workspace-git-api treats `committed=true` as "you produced a
-    // commit locally, please record it"; the actual git push happens
-    // through the bridge.
-    committed: true,
-    sha: null,
-    pushFailed: false
-  };
-  const endpoint = buildAutocommitUrl(apiUrl, sessionId);
-  const response = await postAutocommit(endpoint, actorJwt, body, ctx);
-  if (response === null) {
-    return;
+  if (event.type === "session.created") {
+    const parent = event.data.parentID;
+    return {
+      kind: "created",
+      sessionId,
+      parentId: typeof parent === "string" && parent.length > 0 ? parent : void 0
+    };
   }
-  if (response.conflictDetected) {
-    conflictFlagBySessionId.set(sessionId, { at: Date.now(), turn });
-    info(
-      `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} conflict detected (remote diverged); next user message will surface the Publish affordance`
-    );
-    return;
+  const outcome = Object.hasOwn(TERMINAL_EVENT_TYPES, event.type) ? TERMINAL_EVENT_TYPES[event.type] : void 0;
+  if (outcome === void 0 || typeof event.id !== "string" || event.id.length === 0) {
+    return void 0;
   }
-  if (response.pushFailed) {
-    info(
-      `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} push failed; retrying once after ${PUSH_RETRY_DELAY_MS}ms`
-    );
-    await sleep(PUSH_RETRY_DELAY_MS);
-    const retry = await postAutocommit(endpoint, actorJwt, body, ctx);
-    if (retry === null || retry.pushFailed) {
+  return { kind: "terminal", sessionId, outcome, executionId: event.id };
+}
+
+// src/hooks/root-turn-completion.ts
+var HOOK_NAME = "turn-completed";
+var TURN_COMPLETED_PATH = "/runtime/turn-completed";
+var WORKSPACE_PROXY_URL_ENV = "WORKSPACE_PROXY_URL";
+var SERVER_PASSWORD_ENV = "OPENCODE_SERVER_PASSWORD";
+var MAX_REMEMBERED_KEYS = 1e3;
+function createRootTurnCompletion(options) {
+  const parentBySession = /* @__PURE__ */ new Map();
+  const delivered = /* @__PURE__ */ new Set();
+  async function isRoot(sessionId) {
+    if (parentBySession.has(sessionId)) return parentBySession.get(sessionId) === void 0;
+    try {
+      const parent = await options.resolveParentId(sessionId);
+      parentBySession.set(sessionId, parent);
+      return parent === void 0;
+    } catch (err) {
       warn(
-        `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} push failed twice; giving up (auto-commit is best-effort). User-driven Publish flow remains available.`
+        `hook=${HOOK_NAME}: cannot tell whether session=${sessionId} is a root (${err instanceof Error ? err.message : String(err)}); skipping rather than guessing.`
       );
-      return;
-    }
-    if (retry.conflictDetected) {
-      conflictFlagBySessionId.set(sessionId, { at: Date.now(), turn });
-      info(
-        `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} retry surfaced conflict`
-      );
-      return;
+      return void 0;
     }
-    info(
-      `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} retry committed=${retry.committed} sha=${retry.sha ?? "-"}`
-    );
-    return;
   }
-  info(
-    `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} committed=${response.committed} sha=${response.sha ?? "-"}`
-  );
-}
-function nextTurn(sessionId) {
-  const prev = turnCounterBySessionId.get(sessionId) ?? 0;
-  const next = prev + 1;
-  turnCounterBySessionId.set(sessionId, next);
-  return next;
-}
-function readActorJwt(path) {
-  try {
-    if (!existsSync2(path)) {
-      return null;
+  function remember(key) {
+    delivered.add(key);
+    if (delivered.size > MAX_REMEMBERED_KEYS) {
+      const oldest = delivered.values().next().value;
+      if (oldest !== void 0) delivered.delete(oldest);
     }
-    const raw = readFileSync2(path, "utf-8").trim();
-    return raw.length > 0 ? raw : null;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    warn(`hook=${HOOK_NAME}: failed to read actor JWT at ${path}: ${message}`);
-    return null;
-  }
-}
-async function isGitTreeDirty(repoDir) {
-  try {
-    const { stdout } = await execFileAsync(
-      "git",
-      ["-C", repoDir, "status", "--porcelain"],
-      { encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 }
-    );
-    return stdout.trim().length > 0;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    warn(
-      `hook=${HOOK_NAME}: git status failed in ${repoDir}: ${message}. Skipping auto-commit for this turn.`
-    );
-    return void 0;
   }
-}
-function buildAutocommitUrl(apiBase, sessionId) {
-  const base = apiBase.endsWith("/") ? apiBase.slice(0, -1) : apiBase;
-  return `${base}/sessions/${encodeURIComponent(sessionId)}/autocommit`;
-}
-async function postAutocommit(url2, actorJwt, body, ctx) {
-  try {
-    const res = await fetch(url2, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${actorJwt}`
-      },
-      body: JSON.stringify(body)
-    });
-    if (!res.ok) {
-      const text = await safeReadBody(res);
+  async function onSessionTerminal(sessionId, outcome, executionId) {
+    try {
+      if (outcome !== "succeeded" /* Succeeded */) {
+        debug(`hook=${HOOK_NAME}: session=${sessionId} ended ${outcome}; not a commit point`);
+        return;
+      }
+      const key = `${sessionId}:${executionId}`;
+      if (delivered.has(key)) {
+        debug(`hook=${HOOK_NAME}: ${key} already notified`);
+        return;
+      }
+      if (await isRoot(sessionId) !== true) return;
+      const env = options.env ?? process.env;
+      const base = env[WORKSPACE_PROXY_URL_ENV];
+      const password = env[SERVER_PASSWORD_ENV];
+      if (!base || !password) {
+        warn(
+          `hook=${HOOK_NAME}: ${!base ? WORKSPACE_PROXY_URL_ENV : SERVER_PASSWORD_ENV} is not set; cannot notify workspace-proxy that session=${sessionId} completed a turn.`
+        );
+        return;
+      }
+      const url2 = `${base.replace(/\/$/, "")}${TURN_COMPLETED_PATH}`;
+      const res = await fetch(url2, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}`,
+          "Idempotency-Key": key
+        },
+        body: JSON.stringify({ runtimeSessionId: sessionId, executionId, outcome })
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<unreadable body>");
+        warn(`hook=${HOOK_NAME}: POST ${url2} responded ${res.status}: ${text.slice(0, 512)}`);
+        return;
+      }
+      remember(key);
+      debug(`hook=${HOOK_NAME}: notified ${key}`);
+    } catch (err) {
       warn(
-        `hook=${HOOK_NAME}: POST ${url2} responded ${res.status} ${res.statusText} (role=${ctx.invocation.role}, runId=${ctx.invocation.runId ?? "-"}): ${text}`
+        `hook=${HOOK_NAME}: unexpected error swallowed (best-effort): ` + (err instanceof Error ? err.message : String(err))
       );
-      return null;
     }
-    const parsed = await res.json();
-    return parsed;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    warn(`hook=${HOOK_NAME}: POST ${url2} failed: ${message}`);
-    return null;
   }
+  return {
+    onSessionCreated: (sessionId, parentId) => {
+      parentBySession.set(sessionId, parentId);
+    },
+    onSessionTerminal
+  };
 }
-async function safeReadBody(res) {
-  try {
-    const text = await res.text();
-    return text.length > 512 ? `${text.slice(0, 512)}\u2026` : text;
-  } catch {
-    return "<unreadable body>";
+
+// src/hooks/shell-env-hygiene.ts
+var SERVER_PASSWORD_ENV_KEYS = Object.freeze([
+  "OPENCODE_PASSWORD",
+  "OPENCODE_SERVER_PASSWORD"
+]);
+function scrubShellEnv(input2) {
+  for (const key of SERVER_PASSWORD_ENV_KEYS) {
+    delete input2.env[key];
   }
 }
-function sleep(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
 
 // src/hooks/subagent-fanout-ceiling.ts
-var TASK_TOOL_ID = "task";
+var SUBAGENT_TOOL_ID = "subagent";
 var DEFAULT_SUBAGENT_FANOUT_LIMIT = 8;
 var DEFAULT_FANOUT_WAIT_TIMEOUT_MS = 10 * 60 * 1e3;
-var DEFAULT_PERMIT_TTL_MS = 30 * 60 * 1e3;
+var DEFAULT_ACTIVE_CHILD_TTL_MS = 30 * 60 * 1e3;
+var DEFAULT_PENDING_SLOT_TTL_MS = 2 * 60 * 1e3;
 var FANOUT_LIMIT_ENV = "XEMA_SUBAGENT_FANOUT_LIMIT";
 function resolveSubagentFanoutLimit(env = process.env) {
   const declared = env[FANOUT_LIMIT_ENV];
@@ -20038,7 +19968,7 @@ function resolveSubagentFanoutLimit(env = process.env) {
   const parsed = Number(declared.trim());
   if (!Number.isInteger(parsed)) {
     throw new Error(
-      `${FANOUT_LIMIT_ENV}="${declared}" is not an integer. Expected a whole number of concurrently executing sub-agent tasks between 1 and ${DEFAULT_SUBAGENT_FANOUT_LIMIT}.`
+      `${FANOUT_LIMIT_ENV}="${declared}" is not an integer. Expected a whole number of concurrently running sub-agents between 1 and ${DEFAULT_SUBAGENT_FANOUT_LIMIT}.`
     );
   }
   if (parsed < 1) {
@@ -20056,15 +19986,17 @@ function resolveSubagentFanoutLimit(env = process.env) {
 function createSubagentFanoutCeiling(options) {
   const limit = options.limit;
   const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_FANOUT_WAIT_TIMEOUT_MS;
-  const permitTtlMs = options.permitTtlMs ?? DEFAULT_PERMIT_TTL_MS;
+  const pendingSlotTtlMs = options.pendingSlotTtlMs ?? DEFAULT_PENDING_SLOT_TTL_MS;
+  const activeChildTtlMs = options.activeChildTtlMs ?? DEFAULT_ACTIVE_CHILD_TTL_MS;
   const now = options.now ?? (() => Date.now());
-  const held = /* @__PURE__ */ new Map();
+  const pending = [];
+  const active = /* @__PURE__ */ new Map();
   const waiters = [];
+  const armed = /* @__PURE__ */ new Set();
   let waitedCount = 0;
   let timedOutCount = 0;
-  let sweptCount = 0;
-  let ttlReclaimedCount = 0;
-  const armed = /* @__PURE__ */ new Set();
+  let pendingTtlReclaimedCount = 0;
+  let activeTtlReclaimedCount = 0;
   function arm(fn, ms, keepProcessAlive) {
     const timer = setTimeout(() => {
       armed.delete(timer);
@@ -20079,133 +20011,152 @@ function createSubagentFanoutCeiling(options) {
     clearTimeout(timer);
     armed.delete(timer);
   }
-  function take(callId, sessionId) {
-    const ttlTimer = arm(() => {
-      if (!held.has(callId)) return;
-      ttlReclaimedCount += 1;
-      warn(
-        `fanout-ceiling: permit TTL expired for call=${callId} session=${sessionId} after ${permitTtlMs}ms \u2014 force-releasing. A task held a slot longer than any healthy sub-agent turn; the pool would otherwise have shrunk permanently.`
-      );
-      release(callId, "ttl");
-    }, permitTtlMs, false);
-    held.set(callId, { sessionId, acquiredAt: now(), ttlTimer });
-  }
-  function release(callId, reason) {
-    const permit = held.get(callId);
-    if (permit === void 0) return;
-    disarm(permit.ttlTimer);
-    held.delete(callId);
-    if (reason !== "completed") {
-      debug(
-        `fanout-ceiling: reclaimed call=${callId} via ${reason} (held ${now() - permit.acquiredAt}ms)`
-      );
-    }
+  const occupied = () => pending.length + active.size;
+  function reserve(callId, parentSessionId) {
+    const slot = { callId, parentSessionId, since: now(), timer: void 0 };
+    slot.timer = arm(
+      () => {
+        const index = pending.indexOf(slot);
+        if (index === -1) return;
+        pending.splice(index, 1);
+        pendingTtlReclaimedCount += 1;
+        warn(
+          `fanout-ceiling: reserved slot for call=${callId} session=${parentSessionId} never became a child session within ${pendingSlotTtlMs}ms \u2014 reclaiming (its execute.after was lost; V2 does not guarantee it on abort).`
+        );
+        drain();
+      },
+      pendingSlotTtlMs,
+      false
+    );
+    pending.push(slot);
+  }
+  function activate(childSessionId, parentSessionId) {
+    const timer = arm(
+      () => {
+        if (!active.has(childSessionId)) return;
+        activeTtlReclaimedCount += 1;
+        warn(
+          `fanout-ceiling: child session=${childSessionId} held a slot for ${activeChildTtlMs}ms with no terminal event \u2014 force-releasing so the pool cannot shrink permanently.`
+        );
+        releaseActive(childSessionId, "active-ttl");
+      },
+      activeChildTtlMs,
+      false
+    );
+    active.set(childSessionId, { childSessionId, parentSessionId, since: now(), timer });
+  }
+  function releaseActive(childSessionId, reason) {
+    const child = active.get(childSessionId);
+    if (child === void 0) return;
+    disarm(child.timer);
+    active.delete(childSessionId);
+    debug(
+      `fanout-ceiling: released child=${childSessionId} via ${reason} (held ${now() - child.since}ms, occupied=${occupied()}/${limit})`
+    );
     drain();
   }
   function drain() {
-    while (waiters.length > 0 && held.size < limit) {
+    while (waiters.length > 0 && occupied() < limit) {
       const next = waiters.shift();
       if (next === void 0) return;
       disarm(next.timer);
-      const waitedMs = now() - next.since;
       waitedCount += 1;
-      take(next.callId, next.sessionId);
+      reserve(next.callId, next.parentSessionId);
       info(
-        `fanout-ceiling: admitted call=${next.callId} session=${next.sessionId} after waiting ${waitedMs}ms (limit=${limit}, in-flight=${held.size}, still waiting=${waiters.length})`
+        `fanout-ceiling: admitted call=${next.callId} session=${next.parentSessionId} after waiting ${now() - next.since}ms (limit=${limit}, occupied=${occupied()}, still waiting=${waiters.length})`
       );
       next.grant();
     }
   }
-  async function before(input2) {
-    if (input2.tool !== TASK_TOOL_ID) return;
-    const { callID: callId, sessionID: sessionId } = input2;
-    if (held.size < limit) {
-      take(callId, sessionId);
-      debug(
-        `fanout-ceiling: admitted call=${callId} immediately (in-flight=${held.size}/${limit})`
-      );
+  async function beforeToolCall(input2) {
+    if (input2.tool !== SUBAGENT_TOOL_ID) return;
+    const { id: callId, sessionID: parentSessionId } = input2;
+    if (occupied() < limit) {
+      reserve(callId, parentSessionId);
       return;
     }
     const since = now();
     warn(
-      `fanout-ceiling: sub-agent fan-out at ceiling \u2014 call=${callId} session=${sessionId} is WAITING (limit=${limit}, in-flight=${held.size}, already waiting=${waiters.length}). This is backpressure, not a refusal: the task will start when a slot frees.`
+      `fanout-ceiling: sub-agent fan-out at ceiling \u2014 call=${callId} session=${parentSessionId} is WAITING (limit=${limit}, pending=${pending.length}, active=${active.size}, already waiting=${waiters.length}). Backpressure, not a refusal.`
     );
     await new Promise((resolve) => {
-      const waiter = {
-        callId,
-        sessionId,
-        since,
-        grant: resolve,
-        timer: void 0
-      };
-      waiter.timer = arm(() => {
-        const idx = waiters.indexOf(waiter);
-        if (idx === -1) return;
-        waiters.splice(idx, 1);
-        timedOutCount += 1;
-        warn(
-          `fanout-ceiling: call=${callId} session=${sessionId} waited ${waitTimeoutMs}ms and is being ADMITTED OVER the ceiling (limit=${limit}, in-flight=${held.size}). The pool did not free a slot in that window \u2014 suspect a leaked permit or a stuck sub-agent.`
-        );
-        take(callId, sessionId);
-        resolve();
-      }, waitTimeoutMs, true);
+      const waiter = { callId, parentSessionId, since, grant: resolve, timer: void 0 };
+      waiter.timer = arm(
+        () => {
+          const index = waiters.indexOf(waiter);
+          if (index === -1) return;
+          waiters.splice(index, 1);
+          timedOutCount += 1;
+          warn(
+            `fanout-ceiling: call=${callId} session=${parentSessionId} waited ${waitTimeoutMs}ms and is ADMITTED OVER the ceiling (limit=${limit}, occupied=${occupied()}). Suspect a leaked slot or a stuck sub-agent.`
+          );
+          reserve(callId, parentSessionId);
+          resolve();
+        },
+        waitTimeoutMs,
+        true
+      );
       waiters.push(waiter);
     });
   }
-  function after(input2) {
-    if (input2.tool !== TASK_TOOL_ID) return;
-    release(input2.callID, "completed");
+  function afterToolCall(input2) {
+    if (input2.tool !== SUBAGENT_TOOL_ID) return;
+    const index = pending.findIndex((slot2) => slot2.callId === input2.id);
+    if (index === -1) return;
+    const [slot] = pending.splice(index, 1);
+    disarm(slot?.timer);
+    debug(`fanout-ceiling: call=${input2.id} ended before any child existed \u2014 slot released`);
+    drain();
   }
-  function onSessionIdle(sessionId) {
-    const stale = [];
-    for (const [callId, permit] of held) {
-      if (permit.sessionId === sessionId) stale.push(callId);
+  function onSessionCreated(sessionId, parentId) {
+    if (parentId === void 0 || active.has(sessionId)) return;
+    const index = pending.findIndex((slot) => slot.parentSessionId === parentId);
+    if (index === -1) {
+      debug(`fanout-ceiling: unreserved child=${sessionId} of parent=${parentId} \u2014 counted`);
+    } else {
+      const [slot] = pending.splice(index, 1);
+      disarm(slot?.timer);
     }
-    if (stale.length === 0) return;
-    sweptCount += stale.length;
-    warn(
-      `fanout-ceiling: session=${sessionId} went idle still holding ${stale.length} permit(s) [${stale.join(", ")}] \u2014 reclaiming. These tasks ended without a tool.execute.after, which upstream does not fire on the failure path.`
-    );
-    for (const callId of stale) release(callId, "session-idle");
+    activate(sessionId, parentId);
+  }
+  function onSessionTerminal(sessionId) {
+    releaseActive(sessionId, "terminal");
   }
   function dispose() {
-    const parked = waiters.length;
-    const outstanding = held.size;
     while (waiters.length > 0) {
-      const w = waiters.shift();
-      if (w === void 0) break;
-      disarm(w.timer);
-      w.grant();
-    }
-    for (const permit of held.values()) disarm(permit.ttlTimer);
-    held.clear();
-    if (parked > 0 || outstanding > 0) {
-      info(
-        `fanout-ceiling: disposed \u2014 released ${parked} parked task(s) and disarmed ${outstanding} permit timer(s).`
-      );
+      const waiter = waiters.shift();
+      if (waiter === void 0) break;
+      disarm(waiter.timer);
+      waiter.grant();
     }
+    for (const slot of pending) disarm(slot.timer);
+    pending.length = 0;
+    for (const child of active.values()) disarm(child.timer);
+    active.clear();
   }
   return {
-    before,
-    after,
-    onSessionIdle,
+    beforeToolCall,
+    afterToolCall,
+    onSessionCreated,
+    onSessionTerminal,
     dispose,
     stats: () => ({
       limit,
-      inFlight: held.size,
+      pending: pending.length,
+      active: active.size,
       waiting: waiters.length,
       waitedCount,
       timedOutCount,
-      sweptCount,
-      ttlReclaimedCount,
+      pendingTtlReclaimedCount,
+      activeTtlReclaimedCount,
       armedTimers: armed.size
     })
   };
 }
 
-// src/hooks/system-prompt-overlay.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
-import { join as join4 } from "node:path";
+// src/hooks/system-overlay.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
 
 // src/errors.ts
 var XemaSystemOverlayMissingError = class extends Error {
@@ -20218,7 +20169,7 @@ var XemaSystemOverlayMissingError = class extends Error {
 
 // src/hooks/workspace-listing.ts
 import { readdirSync, statSync } from "node:fs";
-import { join as join3 } from "node:path";
+import { join as join2 } from "node:path";
 var MAX_ENTRIES_PER_DIR = 50;
 var HIDDEN_TOP_LEVEL = /* @__PURE__ */ new Set([".xema", ".opencode"]);
 var SKIP_CHILD_EXPANSION_TOP_LEVEL = /* @__PURE__ */ new Set([
@@ -20238,7 +20189,7 @@ function renderWorkspaceListing(workspaceRoot) {
   const lines = [
     "## Current workspace contents (depth 1)",
     "",
-    "This is a snapshot of `/workspace/` taken at the start of this turn. Use it to orient before reaching for `glob`, `list`, or `read`. Hidden: platform-private slots (`.xema/`, `.opencode/`).",
+    "This is a snapshot of `/workspace/` taken at the start of this turn. Use it to orient before reaching for `glob` or `read`. Hidden: platform-private slots (`.xema/`, `.opencode/`).",
     ""
   ];
   let topLevel;
@@ -20260,13 +20211,13 @@ function renderWorkspaceListing(workspaceRoot) {
 }
 function renderTopLevelEntry(workspaceRoot, entry) {
   const relPath = entry.name;
-  const absPath = join3(workspaceRoot, entry.name);
+  const absPath = join2(workspaceRoot, entry.name);
   if (!entry.isDirectory) {
     return [`- \`/workspace/${relPath}\``];
   }
   if (SKIP_CHILD_EXPANSION_TOP_LEVEL.has(entry.name)) {
     return [
-      `- \`/workspace/${relPath}/\` _(children omitted: known implicit/noisy directory \u2014 use \`glob\`/\`list\` if needed)_`
+      `- \`/workspace/${relPath}/\` _(children omitted: known implicit/noisy directory \u2014 use \`glob\` if needed)_`
     ];
   }
   let children;
@@ -20284,7 +20235,7 @@ function renderTopLevelEntry(workspaceRoot, entry) {
     return `  - \`${child.name}${suffix}\``;
   });
   const overflow = children.length - shown.length;
-  const overflowLine = overflow > 0 ? [`  - _(${overflow} more entr${overflow === 1 ? "y" : "ies"} \u2014 use \`glob\`/\`list\` to enumerate)_`] : [];
+  const overflowLine = overflow > 0 ? [`  - _(${overflow} more entr${overflow === 1 ? "y" : "ies"} \u2014 use \`glob\` to enumerate)_`] : [];
   return [`- \`/workspace/${relPath}/\``, ...childLines, ...overflowLine];
 }
 function readDirSorted(dir) {
@@ -20310,7 +20261,7 @@ function readDirSorted(dir) {
 function resolveIsDirectory(parent, dirent) {
   if (dirent.isSymbolicLink()) {
     try {
-      return statSync(join3(parent, dirent.name)).isDirectory();
+      return statSync(join2(parent, dirent.name)).isDirectory();
     } catch {
       return false;
     }
@@ -20318,114 +20269,155 @@ function resolveIsDirectory(parent, dirent) {
   return dirent.isDirectory();
 }
 
-// src/hooks/system-prompt-overlay.ts
-function buildSystemPromptOverlay(directory) {
-  return async (_input, output2) => {
-    const ctx = readInvocationContextForHook(
-      directory,
-      "experimental.chat.system.transform"
-    );
+// src/hooks/system-overlay.ts
+var XEMA_OVERLAY_METADATA_KEY = "xema.system-overlay";
+function buildSystemOverlayHook(directory) {
+  return (input2) => {
+    const ctx = readInvocationContextForHook(directory, "session.context");
     if (!ctx) {
       return;
     }
-    const overlayPath = join4(directory, ".xema", "system-overlay.md");
-    if (!existsSync3(overlayPath)) {
+    const overlayPath = join3(directory, ".xema", "system-overlay.md");
+    if (!existsSync2(overlayPath)) {
       throw new XemaSystemOverlayMissingError(
-        `Xema session ${ctx.invocation.runId ?? "unknown"} (role=${ctx.invocation.role}, sessionId=${ctx.invocation.sessionId ?? "-"}) is missing /workspace/.xema/system-overlay.md. The platform contract is undefined; refusing to start the chat. Verify the agent-run-context render flow emitted the system-overlay slot.`
-      );
-    }
-    const bytes = readFileSync3(overlayPath, "utf8");
-    if (output2.system.length !== 1) {
-      throw new Error(
-        `experimental.chat.system.transform: expected output.system to contain exactly 1 entry on hook entry, got ${output2.system.length}. Another plugin or an OpenCode change broke the seed-then-extend contract this hook relies on.`
+        `Xema session ${ctx.invocation.runId ?? "unknown"} (role=${ctx.invocation.role}, sessionId=${ctx.invocation.sessionId ?? "-"}) is missing /workspace/.xema/system-overlay.md. The platform contract is undefined; refusing the model request. Verify the agent-run-context render flow emitted the system-overlay slot.`
       );
     }
+    const bytes = readFileSync2(overlayPath, "utf8");
     const listing = renderWorkspaceListing(directory);
-    output2.system[0] = `${output2.system[0]}
+    const part = {
+      type: "text",
+      text: `${bytes}
 
-${bytes}
-
-${listing}`;
+${listing}`,
+      metadata: { [XEMA_OVERLAY_METADATA_KEY]: true }
+    };
+    const existing = input2.system.findIndex(
+      (entry) => entry.metadata?.[XEMA_OVERLAY_METADATA_KEY] === true
+    );
+    if (existing === -1) {
+      input2.system.push(part);
+    } else {
+      input2.system[existing] = part;
+    }
     debug(
-      `experimental.chat.system.transform: concatenated ${bytes.length} overlay bytes + ${listing.length} listing bytes into system[0] (role=${ctx.invocation.role})`
+      `session.context: ${existing === -1 ? "appended" : "replaced"} overlay part (${bytes.length} overlay + ${listing.length} listing bytes, role=${ctx.invocation.role}, opencodeSession=${input2.sessionID})`
     );
   };
 }
 
-// src/index.ts
-var bootCache = /* @__PURE__ */ new Map();
-var XemaPlugin = async (ctx) => {
-  const { directory } = ctx;
-  const cached2 = bootCache.get(directory);
-  if (cached2 !== void 0) {
-    return cached2;
-  }
-  const booting = doBoot(directory);
-  bootCache.set(directory, booting);
+// src/hooks/tool-surface-observation.ts
+import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join as join4 } from "node:path";
+var TOOL_SURFACE_FILE = "opencode-tool-surface.json";
+var DEFAULT_RUNTIME_STATE_DIR = "/run/xema/runtime";
+var RUNTIME_STATE_DIR_ENV = "XEMA_RUNTIME_STATE_DIR";
+function resolveRuntimeStateDir(env = process.env) {
+  const declared = env[RUNTIME_STATE_DIR_ENV];
+  return declared !== void 0 && declared.trim() !== "" ? declared : DEFAULT_RUNTIME_STATE_DIR;
+}
+async function observeToolSurface(options) {
   try {
-    return await booting;
+    const observedAt = (options.now ?? Date.now)();
+    const ids = [...await options.listToolIds()].sort();
+    const doc = { observedAt, tools: ids };
+    mkdirSync(options.stateDir, { recursive: true });
+    const target = join4(options.stateDir, TOOL_SURFACE_FILE);
+    const temp = `${target}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(doc)}
+`, "utf8");
+    renameSync(temp, target);
+    debug(`tool-surface: observed ${ids.length} tool(s) \u2192 ${target}`);
+    return doc;
   } catch (err) {
-    bootCache.delete(directory);
-    throw err;
+    warn(
+      `tool-surface: observation failed (observation only \u2014 no authority is affected): ` + (err instanceof Error ? err.message : String(err))
+    );
+    return void 0;
   }
-};
-async function doBoot(directory) {
-  const contextPath = join5(directory, "context.json");
-  const contextPresentAtBoot = existsSync4(contextPath);
-  info(
-    `boot: directory=${directory} tools=0 (hooks only) context.json=${contextPresentAtBoot ? "present" : "absent"} debug=${isDebug() ? "on" : "off"}`
-  );
-  const fanoutLimit = resolveSubagentFanoutLimit();
-  const fanout = createSubagentFanoutCeiling({ limit: fanoutLimit });
-  const autocommit = buildSessionIdleAutocommit(directory);
+}
+
+// src/plugin-id.ts
+var XEMA_RUNTIME_BRIDGE_PLUGIN_ID = "xema-runtime-bridge";
+
+// src/plugin.ts
+var TOOL_SURFACE_EVENTS = /* @__PURE__ */ new Set([
+  "plugin.updated",
+  "integration.updated",
+  "skill.updated",
+  "agent.updated"
+]);
+async function setup(ctx) {
+  const directory = ctx.location.directory;
+  const limit = resolveSubagentFanoutLimit();
+  const fanout = createSubagentFanoutCeiling({ limit });
+  const turnCompletion = createRootTurnCompletion({
+    resolveParentId: async (sessionId) => {
+      const session = await ctx.session.get({ sessionID: sessionId });
+      return session.parentID !== void 0 && session.parentID.length > 0 ? session.parentID : void 0;
+    }
+  });
+  const stateDir = resolveRuntimeStateDir();
+  const observe = () => observeToolSurface({
+    stateDir,
+    listToolIds: async () => (await ctx.tool.list()).map((tool) => tool.id)
+  });
+  const registrations = [
+    await ctx.session.hook("context", buildSystemOverlayHook(directory)),
+    await ctx.session.hook("compaction", buildCompactionInvariantsHook(directory)),
+    await ctx.tool.hook(
+      "execute.before",
+      (input2) => fanout.beforeToolCall({ tool: input2.tool, sessionID: input2.sessionID, id: input2.id })
+    ),
+    await ctx.tool.hook("execute.after", (input2) => {
+      fanout.afterToolCall({ tool: input2.tool, sessionID: input2.sessionID, id: input2.id });
+    }),
+    await ctx.shell.hook("create.before", scrubShellEnv)
+  ];
+  const abort = new AbortController();
+  const events = (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: abort.signal })) {
+        handleEvent(event);
+      }
+    } catch (err) {
+      if (!abort.signal.aborted) {
+        warn(
+          `event subscription ended unexpectedly: ${err instanceof Error ? err.message : String(err)}. Fan-out children now release only by TTL and turn-completion notices stop until restart.`
+        );
+      }
+    }
+  })();
+  function handleEvent(event) {
+    const type = event?.type;
+    if (typeof type === "string" && TOOL_SURFACE_EVENTS.has(type)) {
+      void observe();
+    }
+    const parsed = parseRuntimeSessionEvent(event);
+    if (parsed === void 0) return;
+    if (parsed.kind === "created") {
+      fanout.onSessionCreated(parsed.sessionId, parsed.parentId);
+      turnCompletion.onSessionCreated(parsed.sessionId, parsed.parentId);
+      return;
+    }
+    fanout.onSessionTerminal(parsed.sessionId);
+    void turnCompletion.onSessionTerminal(parsed.sessionId, parsed.outcome, parsed.executionId);
+  }
+  await observe();
   info(
-    `boot: subagent fan-out ceiling active (limit=${fanoutLimit} concurrent task calls per worker; tighten with XEMA_SUBAGENT_FANOUT_LIMIT)`
+    `setup: ${XEMA_RUNTIME_BRIDGE_PLUGIN_ID} ready (OpenCode ${ctx.app.version}, dir=${directory}, tools=0, sub-agent fan-out limit=${limit}, tool surface \u2192 ${stateDir})`
   );
-  const hooks = {
-    "experimental.chat.system.transform": buildSystemPromptOverlay(directory),
-    // Backpressure on sub-agent fan-out. Upstream awaits this hook immediately
-    // before the tool runs, so parking here parks the `task` call BEFORE the
-    // child session exists — a pool cap that makes the N+1th spawn wait, not a
-    // counter that aborts a run already paid for.
-    "tool.execute.before": async (input2) => {
-      await fanout.before(input2);
-    },
-    "tool.execute.after": (input2) => {
-      fanout.after(input2);
-    },
-    // Shutdown. Disarms the ceiling's timers and lets any parked `task` call
-    // through, so a torn-down worker leaves nothing armed and nothing pending.
-    dispose: async () => {
-      fanout.dispose();
-    },
-    // TWO consumers of `session.idle` now, so the channel fans out. opencode
-    // exposes session lifecycle only as a discriminated event union, not as
-    // dedicated hooks, and `Hooks.event` is a single function — so composition
-    // has to happen here.
-    //
-    // The order matters and the isolation matters more: the fan-out sweep is a
-    // LEAK BACKSTOP, so it must run even if auto-commit fails. Auto-commit
-    // already swallows its own errors by hard invariant, but relying on that
-    // from the outside would make this correct only by someone else's promise.
-    event: async (input2) => {
-      const evt = input2.event;
-      if (evt.type === "session.idle") {
-        const sessionId = evt.properties?.sessionID;
-        if (sessionId) {
-          try {
-            fanout.onSessionIdle(sessionId);
-          } catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            warn(`fanout-ceiling: session-idle sweep failed: ${message}`);
-          }
-        }
-      }
-      await autocommit(input2);
+  return async () => {
+    abort.abort();
+    fanout.dispose();
+    for (const registration of registrations) {
+      await registration.dispose();
     }
+    await events;
   };
-  return hooks;
 }
+var plugin = { id: XEMA_RUNTIME_BRIDGE_PLUGIN_ID, setup };
+var plugin_default = plugin;
 export {
-  XemaPlugin,
-  XemaPlugin as default
+  plugin_default as default
 };