@xemahq/opencode-xema-plugin 0.1.4 → 0.1.5

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})`,
+    );
+  };
+}

package/src/hooks/workspace-listing.ts

@@ -0,0 +1,175 @@
+import { readdirSync, statSync, type Dirent } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Renders the actual depth-1 contents of `/workspace` as a Markdown
+ * tree, grouped by AWP top-level slot. Appended to the system prompt
+ * by the chat-system-transform hook so the LLM sees the real layout —
+ * actual filenames, repo slugs, prior-turn deliverables — without
+ * having to spend a tool call on `glob` or `list`.
+ *
+ * Design constraints:
+ *
+ *   - **Read-only, side-effect free.** Pure fs reads. No caching state,
+ *     no writes, no network.
+ *   - **Hides platform-private slots.** `.xema/` is platform-private —
+ *     the LLM has no business reading or grep'ing it (its contents are
+ *     already in the system prompt overlay). `.opencode/` is OpenCode
+ *     runtime state (agent + skill bundles, plugin tree, snapshot
+ *     metadata) — also hidden because operating on it is never the
+ *     user's intent.
+ *   - **Bounded output.** Each directory's listing is capped at
+ *     {@link MAX_ENTRIES_PER_DIR}; overflow is summarised as
+ *     `(N more entries — use \`glob\`/\`list\` to enumerate)` so the
+ *     system prompt never balloons under sessions that accumulate
+ *     hundreds of files in `deliverables/`.
+ *   - **Stable ordering.** Entries are sorted alphabetically with
+ *     directories first, so identical filesystem state produces
+ *     identical bytes and the trailing prompt-cache window stays warm
+ *     turn-to-turn when nothing changed.
+ *   - **Cache positioning.** This block goes at the very END of the
+ *     system prompt because it is the most volatile part. Anthropic +
+ *     OpenAI prefix-cache the system prompt; everything ABOVE this
+ *     block stays cached, only this trailing block recomputes.
+ */
+export const MAX_ENTRIES_PER_DIR = 50;
+
+/**
+ * Top-level entries hidden from the listing. Keep tight: anything not
+ * in this set is rendered. The check matches on the immediate child
+ * name under `/workspace/`.
+ */
+const HIDDEN_TOP_LEVEL: ReadonlySet<string> = new Set(['.xema', '.opencode']);
+
+/**
+ * Top-level directories whose child entries are intentionally not expanded.
+ *
+ * These locations are usually implicit/noisy (dependency caches, VCS internals,
+ * virtual environments) and rarely useful in the prompt body. We still show the
+ * top-level path so the model can request targeted tooling if needed.
+ */
+const SKIP_CHILD_EXPANSION_TOP_LEVEL: ReadonlySet<string> = new Set([
+  '.git',
+  'node_modules',
+  '.venv',
+  'venv',
+  '__pycache__',
+  '.mypy_cache',
+  '.pytest_cache',
+  '.ruff_cache',
+  '.tox',
+  '.nox',
+  '.eggs',
+]);
+
+interface ListedEntry {
+  readonly name: string;
+  readonly isDirectory: boolean;
+}
+
+export function renderWorkspaceListing(workspaceRoot: string): string {
+  const lines: string[] = [
+    '## 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/`).',
+    '',
+  ];
+
+  let topLevel: ListedEntry[];
+  try {
+    topLevel = readDirSorted(workspaceRoot);
+  } catch (err) {
+    // The hook is best-effort orientation. If the workspace can't be
+    // listed (extremely unusual — the workspace must exist for the
+    // session to have started), surface it inline rather than failing
+    // the whole chat call. The static overlay above this block already
+    // tells the LLM the canonical layout.
+    lines.push(`_Listing unavailable: ${(err as Error).message}_`);
+    return lines.join('\n');
+  }
+
+  const visible = topLevel.filter((entry) => !HIDDEN_TOP_LEVEL.has(entry.name));
+  if (visible.length === 0) {
+    lines.push('_(workspace is empty)_');
+    return lines.join('\n');
+  }
+
+  for (const entry of visible) {
+    lines.push(...renderTopLevelEntry(workspaceRoot, entry));
+  }
+
+  return lines.join('\n');
+}
+
+function renderTopLevelEntry(workspaceRoot: string, entry: ListedEntry): string[] {
+  const relPath = entry.name;
+  const absPath = join(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 — use \`glob\`/\`list\` if needed)_`,
+    ];
+  }
+
+  let children: ListedEntry[];
+  try {
+    children = readDirSorted(absPath);
+  } catch (err) {
+    return [`- \`/workspace/${relPath}/\` _(unreadable: ${(err as Error).message})_`];
+  }
+  if (children.length === 0) {
+    return [`- \`/workspace/${relPath}/\` _(empty)_`];
+  }
+
+  const shown = children.slice(0, MAX_ENTRIES_PER_DIR);
+  const childLines = shown.map((child) => {
+    const suffix = child.isDirectory ? '/' : '';
+    return `  - \`${child.name}${suffix}\``;
+  });
+  const overflow = children.length - shown.length;
+  const overflowLine =
+    overflow > 0
+      ? [`  - _(${overflow} more entr${overflow === 1 ? 'y' : 'ies'} — use \`glob\`/\`list\` to enumerate)_`]
+      : [];
+
+  return [`- \`/workspace/${relPath}/\``, ...childLines, ...overflowLine];
+}
+
+/**
+ * `readdirSync` with deterministic ordering: directories first, then
+ * files, each group sorted by name (case-sensitive — workspace paths
+ * are case-sensitive on the worker filesystem). Symlinks resolve to
+ * their target's type via `statSync` so a symlinked dir lists like a
+ * dir, not a file.
+ */
+function readDirSorted(dir: string): ListedEntry[] {
+  const dirents: Dirent[] = readdirSync(dir, { withFileTypes: true });
+  const entries: ListedEntry[] = dirents.map((d) => ({
+    name: d.name,
+    isDirectory: resolveIsDirectory(dir, d),
+  }));
+  entries.sort((a, b) => {
+    if (a.isDirectory !== b.isDirectory) {
+      return a.isDirectory ? -1 : 1;
+    }
+    if (a.name < b.name) {return -1;}
+    if (a.name > b.name) {return 1;}
+    return 0;
+  });
+  return entries;
+}
+
+function resolveIsDirectory(parent: string, dirent: Dirent): boolean {
+  if (dirent.isSymbolicLink()) {
+    try {
+      return statSync(join(parent, dirent.name)).isDirectory();
+    } catch {
+      // Broken symlink: classify as file so we surface its presence
+      // without crashing the listing.
+      return false;
+    }
+  }
+  return dirent.isDirectory();
+}