@xemahq/opencode-xema-plugin 0.1.3 → 0.1.5

package/src/context.ts

@@ -0,0 +1,154 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── /workspace/context.json reader ──
+// Read once per tool/hook invocation. Surfaces invocation identity (role,
+// surface, runId, sessionId) and the per-invocation `authority` block to
+// the plugin's tools and the system-prompt overlay hook.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+import { warn } from './logger.js';
+
+const ContextJsonSchema = z.object({
+  invocation: z.object({
+    runId: z.string().nullable().optional(),
+    sessionId: z.string().nullable().optional(),
+    attempt: z.number().int().min(1).default(1),
+    role: z.enum([
+      'unit-worker',
+      'coordinator',
+      'gate-reviewer',
+      'clarification-coordinator',
+      'scope-validator',
+      'agent-session',
+      'design-system-builder',
+      'engineer',
+      'generic-agent',
+      'auditor',
+      // Document Buddy: agent collaborates on a single KB document page
+      // by editing a real working file (`/workspace/document/<slug>.<ext>`)
+      // natively; workspace-proxy's document-sync component derives the
+      // reviewable change set from those edits.
+      'document',
+    ]),
+    surface: z
+      .enum(['pipeline-run', 'agent-session', 'design-system-builder', 'gate-review'])
+      .optional(),
+  }),
+  project: z
+    .object({
+      orgId: z.string(),
+      projectId: z.string().nullish(),
+      // Pipeline invocations outside a run (interactive sessions,
+      // brainstorming, gate reviews not tied to a specific branch)
+      // emit `pipelineBranch: null` — distinct from "absent". Accept
+      // both null and undefined here so the context validation survives.
+      pipelineBranch: z.string().nullish(),
+    })
+    .nullish(),
+  authority: z.object({
+    mayWriteWorkspace: z.array(z.string()).default(['/workspace/deliverables']),
+    mayWriteSlugs: z.array(z.string()).default([]),
+    mayWriteKnowledgeBase: z.boolean().default(true),
+    mayEditRepos: z.boolean().default(false),
+    writePolicy: z.enum(['read-only', 'own-pages-only', 'full-write']),
+    /**
+     * Closed list of Xema-namespaced tool names this invocation may call.
+     * Resolved from the `RoleCapabilityProfile` for `invocation.role` by
+     * llm-registry-api's `agent-run-context.service.ts` and written into
+     * context.json verbatim. `session-state.ensureRoleAllowed` checks
+     * every Xema tool call against this list — no fallback to a per-role
+     * registry baked into the plugin.
+     */
+    allowedXemaTools: z.array(z.string()).min(1),
+  }),
+  /**
+   * 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).
+   */
+  git: z
+    .object({
+      autoCommit: z.enum(['enabled', 'disabled']),
+      repoSubPath: z.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: z
+    .object({
+      kind: z.enum(['org_user']),
+      subjectRef: z.string().min(1),
+      displayName: z.string().min(1),
+    })
+    .nullish(),
+});
+
+export type InvocationContext = z.infer<typeof ContextJsonSchema>;
+export type InvocationRole = InvocationContext['invocation']['role'];
+
+/**
+ * Read and validate /workspace/context.json. Returns null if the file is
+ * absent — the plugin then registers no Xema-specific tools (non-Xema
+ * sessions simply pass through). Throws on malformed JSON or schema
+ * violations so programmatic consumers (tests, tools) see the underlying
+ * error; hooks call {@link readInvocationContextForHook} instead to get
+ * a log-and-skip shape.
+ */
+export function readInvocationContext(
+  workspaceDir: string,
+): InvocationContext | null {
+  const path = join(workspaceDir, 'context.json');
+  if (!existsSync(path)) {
+    return null;
+  }
+  const raw = readFileSync(path, 'utf-8');
+  const parsed = JSON.parse(raw) as unknown;
+  return ContextJsonSchema.parse(parsed);
+}
+
+/**
+ * Hook-friendly variant of {@link readInvocationContext}. Silently returns
+ * `null` when `context.json` is absent (expected for non-Xema sessions /
+ * pre-mount calls), and emits a prefixed warn to stderr when the file is
+ * present but malformed — previously these errors propagated into
+ * opencode's hook dispatcher and were swallowed by the runtime, leaving
+ * operators with no signal that the plugin had gone blind mid-session.
+ */
+export function readInvocationContextForHook(
+  workspaceDir: string,
+  hookName: string,
+): InvocationContext | null {
+  const path = join(workspaceDir, 'context.json');
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    const raw = readFileSync(path, 'utf-8');
+    const parsed = JSON.parse(raw) as unknown;
+    return ContextJsonSchema.parse(parsed);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(
+      `hook=${hookName}: failed to read/validate ${path}: ${message}. ` +
+        `Hook will skip this invocation; fix context.json to re-enable plugin behavior.`,
+    );
+    return null;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,24 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Plugin error types ──
+// Typed errors surfaced to the LLM as tool results. Opencode naturally
+// retries tool errors in the same session, so these are our in-session
+// correction signals.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Thrown by the `experimental.chat.system.transform` hook when a Xema
+ * session boots but `/workspace/.xema/system-overlay.md` is missing.
+ *
+ * Fail-closed: the run's platform contract is undefined; we refuse to
+ * start the chat rather than letting the agent operate without the AWP
+ * base layer + deliverable contract + authority guidance the rest of
+ * the platform assumes is in scope.
+ */
+export class XemaSystemOverlayMissingError extends Error {
+  readonly code = 'XEMA_SYSTEM_OVERLAY_MISSING';
+  constructor(message: string) {
+    super(message);
+    this.name = 'XemaSystemOverlayMissingError';
+  }
+}
+

package/src/hooks/session-idle-autocommit.ts

@@ -0,0 +1,411 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── `session.idle` auto-commit hook ──
+//
+// Fires on every opencode `session.idle` event (delivered via the generic
+// `event` hook). For sessions opted into per-turn auto-commit
+// (`context.git.autoCommit === 'enabled'` — the
+// `shared_dev_publish_to_prod` BranchMode default), the hook:
+//
+//   1. Reads context.json for sessionId + actor + repoSubPath.
+//   2. Reads the actor JWT from `$WORKER_ACTOR_JWT_PATH` (default
+//      `/run/xema/actor.jwt`). Missing JWT → log warn + skip (best-effort).
+//   3. Runs `git status --porcelain` against `<workspace>/<repoSubPath>`.
+//      Clean tree → skip (no-op).
+//   4. POSTs `$WORKSPACE_GIT_API_URL/sessions/<sid>/autocommit` with the
+//      actor JWT as `Authorization: Bearer …`. Body:
+//        { turn, actor: { kind, subjectRef, displayName },
+//          committed, sha, pushFailed }
+//      Wire contract: this endpoint records state; the local git ops
+//      (add/commit/push) happen ON the worker — see design note history
+//      that this file replaced. workspace-proxy ships
+//      `/control/git/autocommit` which workspace-git-api will eventually
+//      delegate to; the hook signature is stable across that switch.
+//   5. Translates the response into local actions:
+//        - `committed=true, conflictDetected=false` → log success.
+//        - `committed=true, pushFailed=true` → one retry w/ 5s backoff;
+//          on second failure, log + continue (NEVER block the next turn).
+//        - `conflictDetected=true` → emit `xema.conflict.detected` event
+//          (best-effort; sets a process-local flag readable by other
+//          hooks) so the next user message can surface a "Conflict —
+//          Publish needed" affordance.
+//        - Any HTTP error → log + continue.
+//
+// HARD INVARIANT: this hook MUST NEVER throw out of the opencode
+// dispatcher. Auto-commit is best-effort orientation; failing here would
+// stall every user's next turn. The entire body runs inside a top-level
+// `try { … } catch { warn(...); }` and returns `undefined` on any error.
+//
+// Wire contract (kept in sync with biomes/software-dev/api/workspace-git-api):
+//
+//   POST {WORKSPACE_GIT_API_URL}/sessions/{sessionId}/autocommit
+//   Authorization: Bearer <actor-jwt>
+//   Content-Type: application/json
+//
+//   { "turn": 7,
+//     "actor": { "kind": "org_user", "subjectRef": "user_…",
+//                "displayName": "Alice" },
+//     "committed": true,
+//     "sha": "ab12cd34…",
+//     "pushFailed": false }
+//
+//   →  200 { committed, sha, pushFailed, conflictDetected }
+//
+// See [packages/runtime/opencode-xema-plugin/CHANGELOG] for the broader
+// handoff context. The plaintext design note
+// previously at `hooks/_TODO_session-idle-autocommit.md` was deleted
+// when this file landed.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { readInvocationContextForHook, type InvocationContext } from '../context.js';
+import { warn, info, debug } from '../logger.js';
+import type { OpencodeEvent, OpencodeSessionIdleEvent } from '../opencode-types.js';
+
+const HOOK_NAME = 'session.idle';
+const DEFAULT_JWT_PATH = '/run/xema/actor.jwt';
+const PUSH_RETRY_DELAY_MS = 5_000;
+
+const execFileAsync = promisify(execFile);
+
+interface AutocommitRequestBody {
+  turn: number;
+  actor: {
+    kind: 'org_user';
+    subjectRef: string;
+    displayName: string;
+  };
+  committed: boolean;
+  sha: string | null;
+  pushFailed: boolean;
+}
+
+interface AutocommitResponseBody {
+  committed: boolean;
+  sha: string | null;
+  pushFailed: boolean;
+  conflictDetected: boolean;
+}
+
+/**
+ * Process-local flag set when workspace-git-api last reported
+ * `conflictDetected=true`. Other hooks (e.g. a future chat-message
+ * pre-send hook) can read it via {@link readConflictFlag} to surface a
+ * "Conflict — Publish needed" affordance to the user. Per-session
+ * because a single worker hosts multiple sessions in pool mode.
+ */
+const conflictFlagBySessionId = new Map<string, { at: number; turn: number }>();
+
+export function readConflictFlag(
+  sessionId: string,
+): { at: number; turn: number } | undefined {
+  return conflictFlagBySessionId.get(sessionId);
+}
+
+export function clearConflictFlag(sessionId: string): void {
+  conflictFlagBySessionId.delete(sessionId);
+}
+
+/**
+ * Per-session turn counter. `session.idle` fires once per LLM turn, so
+ * we increment on receipt before performing the autocommit work. This
+ * is the only place inside the worker that sees the boundary
+ * deterministically.
+ */
+const turnCounterBySessionId = new Map<string, number>();
+
+/**
+ * Test-only: reset all in-memory state. Not exported from the package
+ * barrel.
+ */
+export function __resetSessionIdleAutocommitStateForTests(): void {
+  conflictFlagBySessionId.clear();
+  turnCounterBySessionId.clear();
+}
+
+/**
+ * Factory: returns the `event` hook bound to a workspace directory. The
+ * hook itself dispatches on `event.type === 'session.idle'` and ignores
+ * everything else.
+ */
+export function buildSessionIdleAutocommit(
+  workspaceDir: string,
+): (input: { event: OpencodeEvent }) => Promise<void> {
+  return async (input) => {
+    const evt = input.event;
+    if (evt.type !== 'session.idle') {
+      return;
+    }
+    const idleEvent = evt as OpencodeSessionIdleEvent;
+    try {
+      await handleSessionIdle(workspaceDir, idleEvent);
+    } catch (err) {
+      // HARD invariant: never propagate. Auto-commit is best-effort.
+      const message = err instanceof Error ? err.message : String(err);
+      warn(
+        `hook=${HOOK_NAME}: unexpected error swallowed (auto-commit is best-effort): ${message}`,
+      );
+    }
+  };
+}
+
+async function handleSessionIdle(
+  workspaceDir: string,
+  evt: OpencodeSessionIdleEvent,
+): Promise<void> {
+  const sessionId = evt.properties.sessionID;
+  if (!sessionId) {
+    debug(`hook=${HOOK_NAME}: event missing sessionID; skipping`);
+    return;
+  }
+
+  const ctx = readInvocationContextForHook(workspaceDir, HOOK_NAME);
+  if (!ctx) {
+    // Non-Xema session or pre-mount: nothing to commit.
+    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;
+  }
+
+  // ── Why an env var and not the KernelState/etcd service registry ──
+  //
+  // This plugin runs INSIDE the agent-workspace container, which is
+  // deliberately OUTSIDE the etcd service mesh: it holds no registry client,
+  // no etcd credentials, and no service identity of its own — its only
+  // identity is the actor JWT the orchestrator mounts. So `WORKSPACE_GIT_API_URL`
+  // is an ORCHESTRATOR-INJECTED peer URL, not the retired `<SVC>_API_URL`
+  // discovery pattern that first-party in-mesh services must never use. The
+  // orchestrator resolves the peer FROM the registry and injects the resolved
+  // value into the container envelope; this is the only category of code
+  // allowed to read a peer URL from the environment.
+  //
+  // Absent ⇒ SKIP with a warn, never a throw: see this module's HARD
+  // INVARIANT — a `session.idle` hook that throws stalls every user's next
+  // turn. The warn names the operator fix, so the degradation is observable,
+  // not silent.
+  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;
+  }
+
+  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;
+  }
+
+  // TODO(multi-repo): when the workspace can host multiple
+  // checked-out repos (persistent-repos), `git.repoSubPath`
+  // becomes an array and the hook fans out one autocommit per repo. The
+  // workspace-git-api wire shape already keys on `(sessionId,
+  // repoBindingId)` server-side; the per-call body just needs the
+  // repoBindingId added. For now we commit at the single primary
+  // repo (or workspace root if none is configured).
+  const repoSubPath = ctx.git.repoSubPath ?? null;
+  const repoDir = repoSubPath ? join(workspaceDir, repoSubPath) : workspaceDir;
+
+  const dirty = await isGitTreeDirty(repoDir);
+  if (dirty === undefined) {
+    // git status itself failed — log and skip; nothing we can usefully do.
+    return;
+  }
+  if (!dirty) {
+    debug(
+      `hook=${HOOK_NAME}: session=${sessionId} clean tree at ${repoDir}; ` +
+        `skipping auto-commit`,
+    );
+    return;
+  }
+
+  const turn = nextTurn(sessionId);
+  const body: AutocommitRequestBody = {
+    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; // already logged
+  }
+
+  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;
+  }
+
+  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) {
+      warn(
+        `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} push failed twice; ` +
+          `giving up (auto-commit is best-effort). User-driven Publish flow ` +
+          `remains available.`,
+      );
+      return;
+    }
+    if (retry.conflictDetected) {
+      conflictFlagBySessionId.set(sessionId, { at: Date.now(), turn });
+      info(
+        `hook=${HOOK_NAME}: session=${sessionId} turn=${turn} retry surfaced conflict`,
+      );
+      return;
+    }
+    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: string): number {
+  const prev = turnCounterBySessionId.get(sessionId) ?? 0;
+  const next = prev + 1;
+  turnCounterBySessionId.set(sessionId, next);
+  return next;
+}
+
+function readActorJwt(path: string): string | null {
+  try {
+    if (!existsSync(path)) {
+      return null;
+    }
+    const raw = readFileSync(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;
+  }
+}
+
+/**
+ * Returns true iff `git status --porcelain` produces non-empty output.
+ * `undefined` signals "could not determine" (git missing, not-a-repo,
+ * permission error, etc.) — the caller MUST treat this as "skip" rather
+ * than guess.
+ */
+async function isGitTreeDirty(repoDir: string): Promise<boolean | undefined> {
+  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 undefined;
+  }
+}
+
+function buildAutocommitUrl(apiBase: string, sessionId: string): string {
+  const base = apiBase.endsWith('/') ? apiBase.slice(0, -1) : apiBase;
+  return `${base}/sessions/${encodeURIComponent(sessionId)}/autocommit`;
+}
+
+async function postAutocommit(
+  url: string,
+  actorJwt: string,
+  body: AutocommitRequestBody,
+  ctx: InvocationContext,
+): Promise<AutocommitResponseBody | null> {
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${actorJwt}`,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      const text = await safeReadBody(res);
+      warn(
+        `hook=${HOOK_NAME}: POST ${url} responded ${res.status} ${res.statusText} ` +
+          `(role=${ctx.invocation.role}, runId=${ctx.invocation.runId ?? '-'}): ${text}`,
+      );
+      return null;
+    }
+    const parsed = (await res.json()) as AutocommitResponseBody;
+    return parsed;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    warn(`hook=${HOOK_NAME}: POST ${url} failed: ${message}`);
+    return null;
+  }
+}
+
+async function safeReadBody(res: Response): Promise<string> {
+  try {
+    const text = await res.text();
+    return text.length > 512 ? `${text.slice(0, 512)}…` : text;
+  } catch {
+    return '<unreadable body>';
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/hooks/system-prompt-overlay.ts

@@ -0,0 +1,99 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { readInvocationContextForHook } from '../context.js';
+import { XemaSystemOverlayMissingError } from '../errors.js';
+import { debug } from '../logger.js';
+import type {
+  ExperimentalChatSystemTransformInput,
+  ExperimentalChatSystemTransformOutput,
+} from '../opencode-types.js';
+import { renderWorkspaceListing } from './workspace-listing.js';
+
+/**
+ * `experimental.chat.system.transform` hook — concatenates the rendered
+ * Xema platform overlay onto OpenCode's system prompt entry on every
+ * chat call.
+ *
+ * Behavior:
+ *   - **Non-Xema session** (no `context.json` in `directory`) — pass
+ *     through unchanged. The plugin must not affect non-Xema OpenCode
+ *     usage.
+ *   - **Xema session, overlay present** — append the overlay bytes to
+ *     the END of `output.system[0]` (the existing single entry that
+ *     OpenCode seeded with the agent prompt + any user system). The
+ *     overlay is appended as the trailing block so its directives
+ *     remain authoritative on conflict — LLMs treat later system text
+ *     as more recent guidance.
+ *   - **Xema session, overlay missing** — throw
+ *     `XemaSystemOverlayMissingError`. The platform contract is
+ *     undefined; we refuse to start the chat rather than letting an
+ *     agent operate without the AWP base layer + deliverable contract
+ *     + authority guidance the rest of the platform assumes is in
+ *     scope. The agent activity surfaces this as a typed
+ *     `OVERLAY_MISSING` error.
+ *
+ * Why concatenate instead of `output.system.push(bytes)`:
+ *
+ * OpenCode renders each entry of `output.system` as a SEPARATE wire
+ * message with `role: 'system'`. Its post-hook rejoin block in
+ * `session/llm.ts` only collapses entries when `system.length > 2`, so
+ * a single push from us produces `system.length === 2`, which slips
+ * past the rejoin and lands on the wire as two `role: 'system'`
+ * messages. OpenAI and Anthropic accept that shape; some
+ * OpenAI-compatible inference servers (notably stricter Qwen vLLM
+ * deployments) reject it with `400: System message must be at the
+ * beginning.` Concatenating into the existing entry keeps
+ * `system.length === 1` and produces exactly one leading system
+ * message regardless of provider strictness — fixing the symptom at
+ * the only point this plugin owns. (The OpenCode rejoin condition is
+ * a separate upstream bug; this defense is independent of it.)
+ */
+export function buildSystemPromptOverlay(directory: string) {
+  return async (
+    _input: ExperimentalChatSystemTransformInput,
+    output: ExperimentalChatSystemTransformOutput,
+  ): Promise<void> => {
+    const ctx = readInvocationContextForHook(
+      directory,
+      'experimental.chat.system.transform',
+    );
+    if (!ctx) {
+      // Not a Xema session — leave OpenCode's base prompt alone.
+      return;
+    }
+    const overlayPath = join(directory, '.xema', 'system-overlay.md');
+    if (!existsSync(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 = readFileSync(overlayPath, 'utf8');
+    // OpenCode seeds `output.system` with exactly one entry before
+    // calling this hook (see `session/llm.ts` — agent prompt + custom
+    // + user-system are joined into `system[0]`). If that contract
+    // ever changes (e.g. another plugin pushes ahead of us), fail
+    // loudly rather than silently producing multi-system payloads.
+    if (output.system.length !== 1) {
+      throw new Error(
+        `experimental.chat.system.transform: expected output.system to contain exactly 1 entry on hook entry, got ${output.system.length}. ` +
+          `Another plugin or an OpenCode change broke the seed-then-extend contract this hook relies on.`,
+      );
+    }
+    // Render the live depth-1 workspace tree AFTER the static overlay
+    // so the trailing block is the only volatile region of the system
+    // prompt. Everything above it (agent prompt, AWP base, deliverable
+    // contract, authority section) stays prefix-cacheable across
+    // turns; only this listing recomputes when files change. Do NOT
+    // move it earlier — that would invalidate the whole system-prompt
+    // cache on every turn that touches the workspace.
+    const listing = renderWorkspaceListing(directory);
+    output.system[0] = `${output.system[0]}\n\n${bytes}\n\n${listing}`;
+    debug(
+      `experimental.chat.system.transform: concatenated ${bytes.length} overlay bytes + ${listing.length} listing bytes into system[0] (role=${ctx.invocation.role})`,
+    );
+  };
+}