@xemahq/agent-session-runtime 0.11.1 → 0.11.2

package/src/lib/composer.ts

@@ -1,1315 +0,0 @@
-import { createHash } from 'node:crypto';
-
-import {
-  LogicalWorkspaceSlot,
-  LogicalMountPlanEntrySchema,
-  WorkspaceMountMode,
-  type LogicalMountPlanEntry,
-  type WorkspaceMountPlan,
-} from '@xemahq/kernel-contracts/agent-workspace';
-import {
-  RuntimePlacementAssessment,
-  UnsupportedRuntimePlacementError,
-  WorkerRuntimeKind,
-  type RuntimeLayoutAdapter,
-  type UnsupportedPlacement,
-} from '@xemahq/kernel-contracts/worker-runtime';
-import {
-  BriefcaseReferenceKind,
-  type AgentRunRole,
-  type Briefcase,
-  type BriefcaseReference,
-  type BriefcaseUpload,
-  type CompiledWorkingFile,
-  type MountSource,
-  type RenderedAgentRunContextParams,
-} from '@xemahq/kernel-contracts/workflow';
-
-import { UnknownSlotError } from './errors';
-import type {
-  ComposeWorkspaceImageRequest,
-  WorkspaceImageComposer,
-} from './types';
-
-// ═══════════════════════════════════════════════════════════════════════════
-// ── WorkspaceImageComposer ──
-//
-// Turns a (manifest, bindInputs, agentContext) tuple into a typed
-// WorkspaceMountPlan. The plan is what the workspace-proxy
-// `/workspace/mounts/apply` handler resolves into bytes-on-disk.
-//
-// The composer auto-emits five platform-rendered slots from the agent
-// block (agents-md, context-json, agent-bundles per delegated subagent,
-// skill-bundles per skill, instructions). User-data slots are emitted
-// from the manifest's mounts block + agentContext refs.
-//
-// Resolution of WHICH agents/skills/instructions to mount happens
-// upstream in llm-registry-api (via the resolvers calling
-// `agent-run-context/render` and the per-resource bundle endpoints).
-// The composer only enumerates which `MountSource` discriminators to
-// emit; the resolver fetches the bytes at apply time.
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Resolved agent metadata the caller passed in via `agentContext`.
- * Keys are arbitrary; the composer recognizes a closed set of common
- * keys to drive the platform-rendered slot emission and falls back to
- * the manifest's declared agent block for everything else.
- */
-interface AgentContextShape {
-  readonly delegatedSubAgents?: readonly string[];
-  readonly skills?: readonly string[];
-  readonly instructions?: readonly string[];
-  readonly runtimeConfig?: Readonly<Record<string, unknown>>;
-  readonly mcpConfig?: Readonly<Record<string, unknown>>;
-  readonly inputsJsonBase64?: string;
-  readonly kbSpaceIds?: readonly string[];
-  /**
-   * Per-space page selections — emitted as `kb-pages` MountSource
-   * entries under `references/kb/<spaceId>/<pageSlug>.md`. Used by the
-   * runtime KB-mount feature on Interactive Sessions / Design System Builder
-   * (the user picks individual pages from a space to attach to a live
-   * session). Empty `pageSlugs` selections are dropped by the composer
-   * — fail-fast on an empty selection happens in the resolver.
-   */
-  readonly kbPageMounts?: ReadonlyArray<{
-    readonly spaceId: string;
-    readonly pageSlugs: readonly string[];
-  }>;
-  readonly externalProjectIds?: readonly string[];
-  readonly repoRef?: string;
-  readonly repoRevision?: string;
-  readonly deliverableSpecRef?: string;
-  readonly deliverablesRef?: string | readonly string[];
-  readonly sessionId?: string;
-  /**
-   * Per-job hand-off: artifact-store versions emitted by upstream jobs
-   * (typically `xema/http@v1` with `outputMode: artifact` or any
-   * `xema/emit-artifact@v1` step) that this agent should see as
-   * concrete files inside `/workspace/<slot>/<fileName>`. The agent
-   * reads them via its tool surface — they do NOT travel through
-   * `agent-run-context.workflowInputs.*` or the system prompt.
-   *
-   * Each entry specifies which workspace slot to mount into; the
-   * manifest MUST enable that slot or the composer fails fast at
-   * `extractInputArtifactSources`.
-   */
-  readonly inputArtifacts?: ReadonlyArray<InputArtifactRef>;
-}
-
-/**
- * Wire shape for `agentContext.inputArtifacts[]`. Workflow authors
- * populate these by referencing upstream outputs:
- *
- * ```yaml
- * inputArtifacts:
- *   - artifactId: ${{ needs.fetch.outputs.artifactId }}
- *     version:    ${{ needs.fetch.outputs.version }}
- *     fileName:   page.html
- *     payloadField: body
- * ```
- *
- * `slot` defaults to `inputs` — the canonical workspace slot for "data
- * the workflow is feeding into this agent."
- */
-export interface InputArtifactRef {
-  readonly artifactId: string;
-  readonly version: number;
-  readonly fileName: string;
-  readonly slot?: string;
-  readonly payloadField?: string;
-  readonly contentType?: string;
-}
-
-export interface ExplicitlyUnsupportedOptionalEntry {
-  readonly mountKey: string;
-  readonly slot: LogicalWorkspaceSlot;
-  readonly placement: UnsupportedPlacement;
-}
-
-export interface RuntimeAssessedWorkspaceMountPlan extends WorkspaceMountPlan {
-  readonly runtimeKind: WorkerRuntimeKind;
-  readonly runtimeLayoutRevision: string;
-  readonly runtimeLayoutProfileRef: string;
-  readonly staticDependencyClosureHash: string;
-  readonly unsupportedOptionalEntries: readonly ExplicitlyUnsupportedOptionalEntry[];
-}
-
-export class DefaultWorkspaceImageComposer implements WorkspaceImageComposer {
-  public constructor(
-    private readonly runtimeLayout: RuntimeLayoutAdapter,
-    private readonly optionalMountKeys: ReadonlySet<string> = new Set(),
-  ) {}
-
-  async compose(
-    req: ComposeWorkspaceImageRequest,
-  ): Promise<RuntimeAssessedWorkspaceMountPlan> {
-    // Exactly-one-of invariant: the doc on `ComposeWorkspaceImageRequest`
-    // promises `workflowRun` xor `interactive`. Enforce it here so
-    // `deriveApplyId` can never collapse two unrelated requests onto a
-    // shared `applyId` (which would let workspace-proxy dedup
-    // unrelated mounts). No silent fallback per the engineering
-    // constitution.
-    const hasWorkflow = req.workflowRun !== undefined;
-    const hasInteractive = req.interactive !== undefined;
-    if (hasWorkflow === hasInteractive) {
-      throw new Error(
-        `ComposeWorkspaceImageRequest must declare exactly one of \`workflowRun\` or \`interactive\` (got workflowRun=${hasWorkflow}, interactive=${hasInteractive}).`,
-      );
-    }
-    const ctx = req.agentContext as AgentContextShape;
-    // Surface discriminator. The xor-checked `workflowRun` / `interactive`
-    // fields above ARE the kernel surface signal; we project them onto a
-    // boolean here for the gates further down. Workflow content
-    // (deliverable specs, input artifacts, deliverables) must never leak
-    // into a session surface — fail-fast per CLAUDE.md.
-    const isWorkflowSurface = hasWorkflow;
-    if (!isWorkflowSurface) {
-      // Hard-assert: a session must not be built with any workflow-only
-      // payload. This catches the "wrong agentContext fed into the session
-      // bootstrap" class of misuse before it materialises on disk.
-      if (ctx.inputArtifacts !== undefined && ctx.inputArtifacts.length > 0) {
-        throw new Error(
-          'WorkspaceImageComposer: agent-session surface received non-empty `agentContext.inputArtifacts` — input artifacts are a workflow-only concept. Drop the field or switch to a workflow surface.',
-        );
-      }
-      if (
-        ctx.deliverableSpecRef !== undefined ||
-        ctx.deliverablesRef !== undefined ||
-        req.agentOverrides?.deliverableSpecRef !== undefined ||
-        req.manifest.agent.deliverableSpecRef !== undefined
-      ) {
-        throw new Error(
-          'WorkspaceImageComposer: agent-session surface received a deliverable-spec / deliverables reference — deliverables are a workflow-only concept. Drop `deliverableSpecRef` / `deliverablesRef` for session calls, or switch to a workflow surface.',
-        );
-      }
-    }
-    // Role is caller-supplied. The silent `?? manifest.agent.role`
-    // fallback was removed as part of the unified-role refactor — every
-    // caller (worker activity, agent-session bootstrap, future
-    // entry points) MUST set `agentOverrides.role` explicitly. This
-    // prevents the class of bugs where a manifest declared the wrong
-    // role and the runtime silently propagated it to the wrong template.
-    if (req.agentOverrides?.role === undefined) {
-      throw new Error(
-        'ComposeWorkspaceImageRequest.agentOverrides.role is required — pass `manifest.agent.role` explicitly so the renderer can validate role-vs-surface up front.',
-      );
-    }
-    const role: AgentRunRole = req.agentOverrides.role;
-    const deliverableSpecRef =
-      req.agentOverrides?.deliverableSpecRef ??
-      req.manifest.agent.deliverableSpecRef ??
-      ctx.deliverableSpecRef;
-
-    assertNoSecretOrBindingMaterial(req);
-    const entries: LogicalMountPlanEntry[] = [];
-
-    // ── Platform-rendered single-file slots ───────────────────────────
-    // The three rendered-* sources (agents-md, context-json, system-overlay)
-    // all dispatch to llm-registry's `agent-run-context/render`, which
-    // returns `{agentsMd, contextJson, systemOverlay}` in a single
-    // response. Building them from one shared param object guarantees
-    // they hash to the same workspace-proxy cache key — so one
-    // mount-apply triggers exactly one upstream render call (instead of
-    // three) and the three slots are guaranteed to come from the same
-    // render snapshot. Diverging the params is a silent perf+consistency
-    // bug; do not do it.
-    // Workflow-only: `context.json.workflowInputs.*` is the workflow
-    // engine's `with:` block projection. Sessions have no such concept;
-    // surfacing it would be a lie. The hard-assert above ensures no
-    // workflow-only fields slip through; we still drop the projection
-    // here as a defence-in-depth.
-    const workflowInputs = isWorkflowSurface
-      ? pickWorkflowInputs(req.agentContext)
-      : null;
-    const renderedMounts = buildRenderedMounts(
-      req.manifest.mounts,
-      req.manifest.slug,
-      req.manifest.version,
-    );
-    const renderedInputArtifacts = buildRenderedInputArtifacts(
-      ctx.inputArtifacts,
-    );
-    const renderedWorkingFiles = buildRenderedWorkingFiles(
-      req.manifest.workingFiles,
-    );
-    const renderedSourceParams: RenderedAgentRunContextParams = {
-      orgId: req.orgId,
-      projectId: req.projectId,
-      agentSlug: req.manifest.agent.slug,
-      stageKey: req.manifest.agent.stageKey,
-      role,
-      ...(deliverableSpecRef === undefined ? {} : { deliverableSpecRef }),
-      ...(req.workflowRun?.runId === undefined
-        ? {}
-        : { runId: req.workflowRun.runId }),
-      ...(req.workflowRun?.jobRunId === undefined
-        ? {}
-        : { jobRunId: req.workflowRun.jobRunId }),
-      ...(req.interactive?.sessionId === undefined
-        ? {}
-        : { sessionId: req.interactive.sessionId }),
-      ...(workflowInputs === null ? {} : { workflowInputs }),
-      ...(renderedMounts.length === 0 ? {} : { mounts: renderedMounts }),
-      ...(renderedInputArtifacts.length === 0
-        ? {}
-        : { inputArtifacts: renderedInputArtifacts }),
-      ...(renderedWorkingFiles.length === 0
-        ? {}
-        : { workingFiles: renderedWorkingFiles }),
-    };
-
-    entries.push(
-      buildEntry({
-        slot: LogicalWorkspaceSlot.AgentContext,
-        relPath: '',
-        mode: WorkspaceMountMode.ReadOnly,
-        mountKey: 'agents-md',
-        source: { kind: 'rendered-agents-md', ...renderedSourceParams },
-      }),
-    );
-
-    if (ctx.runtimeConfig !== undefined) {
-      assertRuntimeConfigExcludesImageOwnedContent(ctx.runtimeConfig);
-      entries.push(
-        buildCanonicalConfigEntry(
-          LogicalWorkspaceSlot.RuntimeConfig,
-          'runtime-config',
-          'runtime-config.json',
-          ctx.runtimeConfig,
-        ),
-      );
-    }
-    if (ctx.mcpConfig !== undefined) {
-      entries.push(
-        buildCanonicalConfigEntry(
-          LogicalWorkspaceSlot.McpConfig,
-          'mcp-config',
-          'mcp-config.json',
-          ctx.mcpConfig,
-        ),
-      );
-    }
-
-    entries.push(
-      buildEntry({
-        slot: LogicalWorkspaceSlot.AgentContext,
-        relPath: '',
-        mode: WorkspaceMountMode.ReadOnly,
-        mountKey: 'context-json',
-        source: { kind: 'rendered-context-json', ...renderedSourceParams },
-      }),
-    );
-
-    entries.push(
-      buildEntry({
-        slot: LogicalWorkspaceSlot.SystemOverlay,
-        relPath: '',
-        mode: WorkspaceMountMode.ReadOnly,
-        mountKey: 'system-overlay',
-        source: { kind: 'rendered-system-overlay', ...renderedSourceParams },
-      }),
-    );
-
-    // ── /workspace/tmp (scratch space) ──
-    // Always-on, read-write, tarball-persisted. Empty seed so the
-    // directory exists from session start; agents drop scratch files in
-    // and snapshots carry them across retries automatically.
-    entries.push(
-      buildEntry({
-        slot: LogicalWorkspaceSlot.Temporary,
-        relPath: '.keep',
-        mode: WorkspaceMountMode.ReadWrite,
-        mountKey: 'tmp:seed',
-        source: {
-          kind: 'static-literal',
-          pathWithinWorkspace: '.keep',
-          bytes: '',
-        },
-      }),
-    );
-
-    // ── Agent definitions (primary + delegated subagents) ─────────────
-    // The logical plan is the sole static closure authority on both
-    // workflow and interactive surfaces. Runtime-specific writers may render
-    // these differently, but no second control bundle may reconstruct them.
-    entries.push(
-      buildEntry({
-        slot: LogicalWorkspaceSlot.AgentDefinitions,
-        relPath: `${req.manifest.agent.slug}.md`,
-        mode: WorkspaceMountMode.ReadOnly,
-        mountKey: `agent-bundle:${req.manifest.agent.slug}`,
-        source: {
-          kind: 'agent-kernel',
-          orgId: req.orgId,
-          agentSlug: req.manifest.agent.slug,
-          stageKey: req.manifest.agent.stageKey,
-          agentMode: 'primary',
-        },
-      }),
-    );
-    for (const sub of dedupe(ctx.delegatedSubAgents ?? [])) {
-      if (sub === req.manifest.agent.slug) {
-        continue;
-      }
-      entries.push(
-        buildEntry({
-          slot: LogicalWorkspaceSlot.AgentDefinitions,
-          relPath: `${sub}.md`,
-          mode: WorkspaceMountMode.ReadOnly,
-          mountKey: `agent-bundle:${sub}`,
-          source: {
-            kind: 'agent-kernel',
-            orgId: req.orgId,
-            agentSlug: sub,
-            stageKey: req.manifest.agent.stageKey,
-            agentMode: 'subagent',
-          },
-        }),
-      );
-    }
-
-    // ── Skill bundles + /skill launch commands ────────────────────────
-    // Each skill is a multi-file BUNDLE (SKILL.md + bundled resources).
-    // The entry's relPath is the skill DIRECTORY; the `skill-bundle`
-    // resolver yields one file per bundle member, so the writer composes
-    // `<skill-bundles slot>/<skillKey>/<resolver relPath>`.
-    //
-    // Alongside each bundle we emit one logical invocation intent, rendered
-    // as a command file. A runtime whose adapter consumed the intent NATIVELY
-    // (no command file) was the reason this used to branch on runtimeKind; no
-    // such runtime ships, and the kernel placement kind that expressed it is
-    // gone, so every skill gets a rendered command.
-    //
-    // Kernel-shipped System skills are PREPENDED to whatever skills the
-    // caller already named in `agentContext.skills` (per the skill
-    // composition rules — `SkillSpace.System`
-    // skills are auto-injected into every agent's mounted bundle).
-    // `dedupe` collapses any overlap so a caller that re-mentions a
-    // System skill in `agentContext.skills` does not double-mount it.
-    for (const skillKey of dedupe([
-      ...(req.systemSkillSlugs ?? []),
-      ...(ctx.skills ?? []),
-    ])) {
-      entries.push(
-        buildEntry({
-          slot: LogicalWorkspaceSlot.SkillBundles,
-          relPath: skillKey,
-          mode: WorkspaceMountMode.ReadOnly,
-          mountKey: `skill-bundle:${skillKey}`,
-          source: {
-            kind: 'skill-bundle',
-            skillKey,
-          },
-        }),
-      );
-      const commandRelPath = `${skillKey}.md`;
-      entries.push(
-        buildEntry({
-          slot: LogicalWorkspaceSlot.SkillCommands,
-          relPath: commandRelPath,
-          mode: WorkspaceMountMode.ReadOnly,
-          mountKey: `skill-command:${skillKey}`,
-          source: {
-            kind: 'static-literal',
-            pathWithinWorkspace: commandRelPath,
-            bytes: Buffer.from(renderSkillCommand(skillKey), 'utf8').toString(
-              'base64',
-            ),
-          },
-        }),
-      );
-    }
-
-    // ── Instruction sections ──────────────────────────────────────────
-    for (const sectionKey of dedupe(ctx.instructions ?? [])) {
-      entries.push(
-        buildEntry({
-          slot: LogicalWorkspaceSlot.Instructions,
-          relPath: `${sectionKey}.md`,
-          mode: WorkspaceMountMode.ReadOnly,
-          mountKey: `instruction:${sectionKey}`,
-          source: {
-            kind: 'instruction-section',
-            orgId: req.orgId,
-            sectionKey,
-            agentSlug: req.manifest.agent.slug,
-            stageKey: req.manifest.agent.stageKey,
-          },
-        }),
-      );
-    }
-
-    // ── Input artifacts (workflow-step output → file in workspace) ──
-    // Walks `agentContext.inputArtifacts[]` and lands each artifact
-    // version as a single file under its target slot. Slot defaults to
-    // `inputs`. The slot MUST be enabled in the manifest — otherwise
-    // the workspace-proxy authority guard would reject any tool read on
-    // the resulting path, and the workflow author wants a hard signal
-    // not a silent skip.
-    //
-    // Workflow-surface only: the hard-assert at the top of compose()
-    // guarantees `ctx.inputArtifacts` is empty on session surfaces, so
-    // this loop is effectively a no-op there.
-    const enabledSlots = new Set(
-      Object.entries(req.manifest.mounts)
-        .filter(([, decl]) => decl.enabled)
-        .map(([slotKey]) => slotKey),
-    );
-    for (const ia of ctx.inputArtifacts ?? []) {
-      const slotKey = ia.slot ?? 'inputs';
-      if (!enabledSlots.has(slotKey)) {
-        throw new Error(
-          `WorkspaceImageComposer: agentContext.inputArtifacts targets slot '${slotKey}' but the manifest '${req.manifest.slug}@${req.manifest.version}' does not enable it. ` +
-            `Enable the slot in the agent manifest or change the inputArtifact's 'slot' to one of: [${[...enabledSlots].join(', ') || '(none)'}].`,
-        );
-      }
-      const slotDef = requireLogicalSlot(
-        slotKey,
-        'inputArtifacts',
-        req.manifest.slug,
-        req.manifest.version,
-      );
-      const fileName = ia.fileName.trim();
-      if (
-        fileName.length === 0 ||
-        fileName.includes('..') ||
-        fileName.startsWith('/')
-      ) {
-        throw new Error(
-          `WorkspaceImageComposer: inputArtifact fileName '${ia.fileName}' is invalid — must be a non-empty relative path without '..' segments.`,
-        );
-      }
-      entries.push(
-        buildEntry({
-          slot: slotDef.slot,
-          relPath: fileName,
-          mode: WorkspaceMountMode.ReadOnly,
-          mountKey: `input-artifact:${ia.artifactId}:v${ia.version}:${fileName}`,
-          source: {
-            kind: 'artifact-version',
-            artifactId: ia.artifactId,
-            version: ia.version,
-            fileName,
-            ...(ia.payloadField !== undefined && {
-              payloadField: ia.payloadField,
-            }),
-            ...(ia.contentType !== undefined && {
-              contentType: ia.contentType,
-            }),
-          },
-        }),
-      );
-    }
-
-    // ── User-data mounts (manifest-declared) ──────────────────────────
-    for (const [slotKey, decl] of Object.entries(req.manifest.mounts)) {
-      if (!decl.enabled) continue;
-      const slotDef = requireLogicalSlot(
-        slotKey,
-        'manifest.mounts',
-        req.manifest.slug,
-        req.manifest.version,
-      );
-      const mode = decl.mode ?? slotDef.defaultMode;
-      const mountMode =
-        mode === 'read-write'
-          ? WorkspaceMountMode.ReadWrite
-          : WorkspaceMountMode.ReadOnly;
-      const sources = extractMountSourcesForSlot(
-        slotKey,
-        decl,
-        ctx,
-        deliverableSpecRef,
-        req.briefcase,
-        isWorkflowSurface,
-      );
-      for (const { source, relPath, mountKey } of sources) {
-        entries.push(
-          buildEntry({
-            slot: slotDef.slot,
-            relPath,
-            mode: mountMode,
-            mountKey,
-            source,
-          }),
-        );
-      }
-    }
-
-    // ── Manifest seed files (inline literal or resolved template) ─────
-    if (
-      req.manifest.requiredTemplateNames.length > 0 &&
-      req.templateResolver === undefined
-    ) {
-      throw new Error(
-        `WorkspaceImageComposer: manifest '${req.manifest.slug}@${req.manifest.version}' references templates ` +
-          `[${req.manifest.requiredTemplateNames.join(', ')}] but no templateResolver was supplied.`,
-      );
-    }
-    for (const sf of req.manifest.seedFiles) {
-      const slotDef = requireLogicalSlot(
-        sf.slot,
-        'manifest.seedFiles',
-        req.manifest.slug,
-        req.manifest.version,
-      );
-      let bytesBase64: string;
-      if (sf.source.kind === 'inline') {
-        bytesBase64 = sf.source.bytesBase64;
-      } else {
-        const rendered = await req.templateResolver!.resolve(
-          sf.source.name,
-          sf.source.vars,
-        );
-        bytesBase64 = Buffer.from(rendered, 'utf8').toString('base64');
-      }
-      // `entry.relPath` is the file's location within the slot — used by
-      // the plan validator to dedup target paths AND by the writer as the
-      // file's final position. `source.pathWithinWorkspace` is identity
-      // metadata only (audit/telemetry), redundantly carrying the same
-      // value. The static-literal resolver yields `sub.relPath: ''` so
-      // the writer composes `<slot>/<entry.relPath>/<''>` → `<slot>/<entry.relPath>`,
-      // which is exactly what we want.
-      entries.push(
-        buildEntry({
-          slot: slotDef.slot,
-          relPath: sf.relPath,
-          mode: WorkspaceMountMode.ReadOnly,
-          mountKey: `seed:${sf.slot}:${sf.relPath}`,
-          source: {
-            kind: 'static-literal',
-            pathWithinWorkspace: sf.relPath,
-            bytes: bytesBase64,
-          },
-        }),
-      );
-    }
-
-    return finalizeLogicalPlan(
-      req,
-      entries,
-      this.runtimeLayout,
-      this.optionalMountKeys,
-    );
-  }
-}
-
-/**
- * Stable apply-id — feeds the workspace-proxy lease key.
- *
- * Includes manifest slug + version + a content hash of the manifest's
- * mount-affecting blocks (`agent`, `mounts`, `seedFiles`,
- * `requiredTemplateNames`, `extends`). The content hash defends against
- * the failure mode where a manifest is mutated in place without bumping
- * `version` — without it, workspace-proxy would serve stale mounts from
- * a cached lease keyed only on the unchanged version. The bind inputs
- * hash + scopeId ensure cross-run / cross-input isolation.
- *
- * Hash is base16; collision probability is negligible at the per-lease
- * scale we operate at.
- */
-function deriveApplyId(req: ComposeWorkspaceImageRequest): string {
-  // Exactly one of the two is set — enforced at the top of compose().
-  const scopeId = req.workflowRun
-    ? `wf:${req.workflowRun.runId}:${req.workflowRun.jobRunId}`
-    : `is:${req.interactive!.sessionId}:${req.interactive!.turnGen ?? 0}`;
-  const inputsHash = createHash('sha256')
-    .update(JSON.stringify(stableSort(req.agentContext)))
-    .digest('hex')
-    .slice(0, 16);
-  const manifestContentHash = deriveManifestContentHash(req.manifest);
-  const components = [
-    req.orgId,
-    req.projectId,
-    req.manifest.slug,
-    req.manifest.version,
-    manifestContentHash,
-    req.manifest.agent.slug,
-    req.agentOverrides?.role ?? req.manifest.agent.role,
-    inputsHash,
-    scopeId,
-  ];
-  return createHash('sha256').update(components.join(':')).digest('hex');
-}
-
-function finalizeLogicalPlan(
-  req: ComposeWorkspaceImageRequest,
-  entries: readonly LogicalMountPlanEntry[],
-  runtimeLayout: RuntimeLayoutAdapter,
-  optionalMountKeys: ReadonlySet<string>,
-): RuntimeAssessedWorkspaceMountPlan {
-  return compileLogicalWorkspacePlan({
-    applySeed: deriveApplyId(req),
-    entries,
-    runtimeLayout,
-    optionalMountKeys,
-  });
-}
-
-export interface CompileLogicalWorkspacePlanInput {
-  readonly applySeed: string;
-  readonly entries: readonly LogicalMountPlanEntry[];
-  readonly runtimeLayout: RuntimeLayoutAdapter;
-  readonly optionalMountKeys?: ReadonlySet<string>;
-}
-
-export function compileLogicalWorkspacePlan(
-  input: CompileLogicalWorkspacePlanInput,
-): RuntimeAssessedWorkspaceMountPlan {
-  const { applySeed, entries, runtimeLayout } = input;
-  const optionalMountKeys = input.optionalMountKeys ?? new Set<string>();
-  const ordered = [...entries].sort(compareLogicalEntries);
-  const seenMountKeys = new Set<string>();
-  const supported: LogicalMountPlanEntry[] = [];
-  const unsupportedOptionalEntries: ExplicitlyUnsupportedOptionalEntry[] = [];
-
-  for (const entry of ordered) {
-    assertNoSecretOrBindingMaterial(entry.source);
-    LogicalMountPlanEntrySchema.parse(entry);
-    if (seenMountKeys.has(entry.mountKey)) {
-      throw new Error(`DUPLICATE_LOGICAL_MOUNT_KEY:${entry.mountKey}`);
-    }
-    seenMountKeys.add(entry.mountKey);
-    const placement = runtimeLayout.assess(entry);
-    if (placement.assessment === RuntimePlacementAssessment.Unsupported) {
-      if (!optionalMountKeys.has(entry.mountKey)) {
-        throw new UnsupportedRuntimePlacementError(placement);
-      }
-      unsupportedOptionalEntries.push({
-        mountKey: entry.mountKey,
-        slot: entry.slot,
-        placement,
-      });
-      continue;
-    }
-    supported.push(entry);
-  }
-
-  const closure = {
-    schemaVersion: 1,
-    runtimeKind: runtimeLayout.runtimeKind,
-    runtimeLayoutRevision: runtimeLayout.revision,
-    runtimeLayoutProfileRef: runtimeLayout.profileRef,
-    entries: supported,
-    unsupportedOptionalEntries,
-  } as const;
-  const staticDependencyClosureHash = createHash('sha256')
-    .update(JSON.stringify(stableSort(closure)))
-    .digest('hex');
-  const applyId = createHash('sha256')
-    .update(`${applySeed}:${staticDependencyClosureHash}`)
-    .digest('hex');
-  return {
-    applyId,
-    entries: supported,
-    runtimeKind: runtimeLayout.runtimeKind,
-    runtimeLayoutRevision: runtimeLayout.revision,
-    runtimeLayoutProfileRef: runtimeLayout.profileRef,
-    staticDependencyClosureHash,
-    unsupportedOptionalEntries,
-  };
-}
-
-function compareLogicalEntries(
-  left: LogicalMountPlanEntry,
-  right: LogicalMountPlanEntry,
-): number {
-  const leftKey = `${left.slot}\u0000${left.relPath}\u0000${left.mountKey}`;
-  const rightKey = `${right.slot}\u0000${right.relPath}\u0000${right.mountKey}`;
-  return leftKey === rightKey ? 0 : leftKey < rightKey ? -1 : 1;
-}
-
-const FORBIDDEN_MATERIAL_KEY =
-  /(?:secret|password|accessToken|refreshToken|credentialLease|runtimeBinding|sessionBinding)/i;
-
-function assertNoSecretOrBindingMaterial(value: unknown, path = 'input'): void {
-  if (value === null || typeof value !== 'object') {
-    return;
-  }
-  if (Array.isArray(value)) {
-    value.forEach((member, index) =>
-      assertNoSecretOrBindingMaterial(member, `${path}[${index}]`),
-    );
-    return;
-  }
-  for (const [key, member] of Object.entries(
-    value as Readonly<Record<string, unknown>>,
-  )) {
-    if (FORBIDDEN_MATERIAL_KEY.test(key) && member !== undefined) {
-      throw new Error(`FORBIDDEN_RUNTIME_MATERIAL:${path}.${key}`);
-    }
-    assertNoSecretOrBindingMaterial(member, `${path}.${key}`);
-  }
-}
-
-/**
- * Hash the manifest fields that drive mount composition. A change to
- * any of these fields produces a different `applyId`, forcing
- * workspace-proxy to allocate a fresh lease and re-resolve mounts. Any
- * non-mount field (`description`, `metadata.author`, …) is excluded so
- * cosmetic edits don't churn the lease.
- */
-function deriveManifestContentHash(
-  manifest: ComposeWorkspaceImageRequest['manifest'],
-): string {
-  // `extends` is already flattened into `agent`/`mounts`/`seedFiles`/`env`
-  // by the DSL compiler, so hashing those four fields captures the
-  // effective workspace shape after inheritance.
-  const projection = {
-    agent: manifest.agent,
-    mounts: manifest.mounts,
-    seedFiles: manifest.seedFiles,
-    env: manifest.env,
-    requiredTemplateNames: manifest.requiredTemplateNames,
-  };
-  return createHash('sha256')
-    .update(JSON.stringify(stableSort(projection)))
-    .digest('hex')
-    .slice(0, 16);
-}
-
-function stableSort(value: unknown): unknown {
-  if (value === null || typeof value !== 'object') return value;
-  if (Array.isArray(value)) return value.map(stableSort);
-  const obj = value as Record<string, unknown>;
-  const sorted: Record<string, unknown> = {};
-  for (const key of Object.keys(obj).sort()) {
-    sorted[key] = stableSort(obj[key]);
-  }
-  return sorted;
-}
-
-function dedupe<T>(items: readonly T[]): readonly T[] {
-  return Array.from(new Set(items));
-}
-
-/**
- * The OpenCode command-file body for a `/skill` launch command. Typing
- * `/<skillKey>` in a session expands to this prompt — load the skill,
- * then act on whatever the user passed as arguments.
- */
-function renderSkillCommand(skillKey: string): string {
-  return [
-    '---',
-    `description: Load and apply the ${skillKey} skill`,
-    '---',
-    `Load and apply the \`${skillKey}\` skill, then act on the request: $ARGUMENTS`,
-    '',
-  ].join('\n');
-}
-
-function buildEntry(args: {
-  slot: LogicalWorkspaceSlot;
-  relPath: string;
-  mode: WorkspaceMountMode;
-  mountKey: string;
-  source: MountSource;
-}): LogicalMountPlanEntry {
-  return {
-    mountKey: args.mountKey,
-    slot: args.slot,
-    relPath: args.relPath,
-    mode: args.mode,
-    source: args.source,
-  };
-}
-
-function buildCanonicalConfigEntry(
-  slot: LogicalWorkspaceSlot.RuntimeConfig | LogicalWorkspaceSlot.McpConfig,
-  mountKey: string,
-  sourceName: string,
-  value: Readonly<Record<string, unknown>>,
-): LogicalMountPlanEntry {
-  assertNoSecretOrBindingMaterial(value, mountKey);
-  return buildEntry({
-    slot,
-    relPath: '',
-    mode: WorkspaceMountMode.ReadOnly,
-    mountKey,
-    source: {
-      kind: 'static-literal',
-      pathWithinWorkspace: sourceName,
-      bytes: Buffer.from(JSON.stringify(stableSort(value)), 'utf8').toString(
-        'base64',
-      ),
-    },
-  });
-}
-
-function assertRuntimeConfigExcludesImageOwnedContent(
-  config: Readonly<Record<string, unknown>>,
-): void {
-  for (const key of ['plugins', 'tools']) {
-    if (config[key] !== undefined) {
-      throw new Error(`RUNTIME_IMAGE_OWNED_CONTENT:${key}`);
-    }
-  }
-}
-
-interface ExtractedMountSource {
-  readonly source: MountSource;
-  readonly relPath: string;
-  readonly mountKey: string;
-}
-
-/**
- * Translate a manifest mount declaration + agentContext into one or
- * more concrete MountSources. Closed switch on slot key — adding a
- * new user-data slot requires extending here.
- */
-function extractMountSourcesForSlot(
-  slotKey: string,
-  _decl: { readonly config: Readonly<Record<string, unknown>> },
-  ctx: AgentContextShape,
-  deliverableSpecRef: string | undefined,
-  briefcase: Briefcase | undefined,
-  isWorkflowSurface: boolean,
-): readonly ExtractedMountSource[] {
-  switch (slotKey) {
-    case 'inputs':
-      // Workflow-only slot. The inputs slot carries the rendered
-      // inputs.json blob serialized from workflow `with:` inputs;
-      // sessions have no such concept — the hard-assert at the top of
-      // compose() ensures workflow-only payloads never reach a session,
-      // and this guard makes the rule explicit at the source-extractor
-      // boundary too.
-      if (!isWorkflowSurface) return [];
-      if (!ctx.inputsJsonBase64) return [];
-      return [
-        {
-          source: {
-            kind: 'static-literal',
-            pathWithinWorkspace: 'inputs.json',
-            bytes: ctx.inputsJsonBase64,
-          },
-          relPath: 'inputs.json',
-          mountKey: 'inputs:json',
-        },
-      ];
-    case 'uploads':
-      return extractBriefcaseUploadMounts(briefcase?.uploads);
-    case 'references': {
-      const out: ExtractedMountSource[] = [];
-      for (const spaceId of dedupe(ctx.kbSpaceIds ?? [])) {
-        out.push({
-          source: { kind: 'kb-space', spaceId },
-          relPath: `kb/${spaceId}`,
-          mountKey: `references:kb:${spaceId}`,
-        });
-      }
-      for (const mount of ctx.kbPageMounts ?? []) {
-        const pageSlugs = dedupe(mount.pageSlugs);
-        if (pageSlugs.length === 0) continue;
-        out.push({
-          source: { kind: 'kb-pages', spaceId: mount.spaceId, pageSlugs },
-          relPath: `kb/${mount.spaceId}`,
-          // Mount-key disambiguates from the kb-space entry on the same
-          // space when both coexist — e.g. user mounted the whole space
-          // and later pinned additional specific pages. Slot promote
-          // does an atomic `rm -rf` + rename so the two entries' files
-          // coexist under `references/kb/<spaceId>/` after apply.
-          mountKey: `references:kb-pages:${mount.spaceId}`,
-        });
-      }
-      for (const projectId of dedupe(ctx.externalProjectIds ?? [])) {
-        out.push({
-          source: { kind: 'scm-repo', repoRef: projectId, ref: 'HEAD' },
-          relPath: `external-projects/${projectId}`,
-          mountKey: `references:project:${projectId}`,
-        });
-      }
-      for (const entry of extractBriefcaseReferenceMounts(
-        briefcase?.references,
-      )) {
-        out.push(entry);
-      }
-      return out;
-    }
-    case 'repos':
-      if (!ctx.repoRef) return [];
-      return [
-        {
-          source: {
-            kind: 'scm-repo',
-            repoRef: ctx.repoRef,
-            ref: ctx.repoRevision ?? 'HEAD',
-          },
-          relPath: ctx.repoRef,
-          mountKey: `repo:${ctx.repoRef}`,
-        },
-      ];
-    case 'deliverable-specs':
-      // Workflow-only slot. Sessions never harvest deliverables, so a
-      // spec mount would be dead weight at best, misleading at worst.
-      // The compose()-level hard-assert ensures `deliverableSpecRef` is
-      // undefined on session surfaces, but we mirror the gate here so
-      // the slot-extractor switch is the single readable place that
-      // documents which slots are workflow-only.
-      if (!isWorkflowSurface) return [];
-      if (!deliverableSpecRef) return [];
-      return [
-        {
-          source: {
-            kind: 'deliverable-specs',
-            contractKey: deliverableSpecRef,
-          },
-          relPath: deliverableSpecRef,
-          mountKey: `deliverable-specs:${deliverableSpecRef}`,
-        },
-      ];
-    case 'deliverables': {
-      // Workflow-only slot — same rationale as `deliverable-specs`.
-      if (!isWorkflowSurface) return [];
-      const refs = ctx.deliverablesRef
-        ? Array.isArray(ctx.deliverablesRef)
-          ? ctx.deliverablesRef
-          : [ctx.deliverablesRef]
-        : [];
-      return refs.map((contractKey) => ({
-        source: { kind: 'deliverables', contractKey },
-        relPath: contractKey,
-        mountKey: `deliverables:${contractKey}`,
-      }));
-    }
-    case 'attachments':
-      if (!ctx.sessionId) return [];
-      return [
-        {
-          source: { kind: 'session-attachment', sessionId: ctx.sessionId },
-          relPath: '',
-          mountKey: `attachments:${ctx.sessionId}`,
-        },
-      ];
-    default:
-      return [];
-  }
-}
-
-/**
- * Project `briefcase.uploads[]` onto `artifact-version` MountSources
- * under the `uploads` AWP slot. Each upload becomes one file at
- * `/workspace/uploads/<filename>`. Empty filenames or paths containing
- * traversal segments fail fast — the dispatch endpoint already
- * validates these but we re-check at compose time so an in-memory
- * mutation can never write outside the slot.
- */
-function extractBriefcaseUploadMounts(
-  uploads: readonly BriefcaseUpload[] | undefined,
-): readonly ExtractedMountSource[] {
-  if (!uploads || uploads.length === 0) return [];
-  return uploads.map((u) => {
-    const fileName = u.filename.trim();
-    if (
-      fileName.length === 0 ||
-      fileName.includes('..') ||
-      fileName.startsWith('/')
-    ) {
-      throw new Error(
-        `WorkspaceImageComposer: briefcase upload filename '${u.filename}' is invalid — must be a non-empty relative path without '..' segments.`,
-      );
-    }
-    return {
-      source: {
-        kind: 'artifact-version',
-        artifactId: u.artifact.artifactId,
-        version: u.artifact.version,
-        fileName,
-        ...(u.contentType !== null ? { contentType: u.contentType } : {}),
-      },
-      relPath: fileName,
-      mountKey: `briefcase-upload:${u.artifact.artifactId}:v${u.artifact.version}`,
-    } satisfies ExtractedMountSource;
-  });
-}
-
-/**
- * Project `briefcase.references[]` onto MountSources under the
- * `references` AWP slot. Each reference kind maps to the
- * already-supported MountSource kind:
- *
- *   - `kb_page`      → `kb-pages` (single page, ref is `<spaceId>/<slug>`)
- *   - `kb_space`     → `kb-space` (whole space, ref is `<spaceId>`)
- *   - `artifact`     → `artifact-version` (ref is `<artifactId>@<version>`)
- *   - `scm_repo`     → `scm-repo` (ref is `<repoRef>@<gitRef>` or `<repoRef>`)
- *   - `external_url` → skipped (no on-disk file; surfaces via
- *     context.json only — agents see it under workflowInputs)
- */
-function extractBriefcaseReferenceMounts(
-  references: readonly BriefcaseReference[] | undefined,
-): readonly ExtractedMountSource[] {
-  if (!references || references.length === 0) return [];
-  const out: ExtractedMountSource[] = [];
-  for (const ref of references) {
-    const entry = briefcaseReferenceToMount(ref);
-    if (entry !== null) out.push(entry);
-  }
-  return out;
-}
-
-function briefcaseReferenceToMount(
-  ref: BriefcaseReference,
-): ExtractedMountSource | null {
-  switch (ref.kind) {
-    case BriefcaseReferenceKind.KB_SPACE:
-      return {
-        source: { kind: 'kb-space', spaceId: ref.ref },
-        relPath: `kb/${ref.ref}`,
-        mountKey: `briefcase-reference:kb-space:${ref.ref}`,
-      };
-    case BriefcaseReferenceKind.KB_PAGE: {
-      // ref shape: `<spaceId>/<pageSlug>` (matches the canonical
-      // /kb/spaces/:slug/pages/:pageSlug route used elsewhere).
-      const sep = ref.ref.indexOf('/');
-      if (sep <= 0 || sep === ref.ref.length - 1) {
-        throw new Error(
-          `briefcase reference kind=kb_page must encode ref as '<spaceId>/<pageSlug>' (got '${ref.ref}').`,
-        );
-      }
-      const spaceId = ref.ref.slice(0, sep);
-      const pageSlug = ref.ref.slice(sep + 1);
-      return {
-        source: { kind: 'kb-pages', spaceId, pageSlugs: [pageSlug] },
-        relPath: `kb/${spaceId}`,
-        mountKey: `briefcase-reference:kb-page:${spaceId}:${pageSlug}`,
-      };
-    }
-    case BriefcaseReferenceKind.ARTIFACT: {
-      // ref shape: `<artifactId>@<version>` (integer version, matches
-      // the artifact-store address scheme).
-      const at = ref.ref.lastIndexOf('@');
-      if (at <= 0) {
-        throw new Error(
-          `briefcase reference kind=artifact must encode ref as '<artifactId>@<version>' (got '${ref.ref}').`,
-        );
-      }
-      const artifactId = ref.ref.slice(0, at);
-      const version = Number.parseInt(ref.ref.slice(at + 1), 10);
-      if (!Number.isInteger(version) || version < 1) {
-        throw new Error(
-          `briefcase reference kind=artifact has invalid version in '${ref.ref}' — must be a positive integer.`,
-        );
-      }
-      const trimmedTitle = ref.title?.trim() ?? '';
-      const fileName =
-        trimmedTitle.length > 0 ? trimmedTitle : `${artifactId}-v${version}`;
-      return {
-        source: {
-          kind: 'artifact-version',
-          artifactId,
-          version,
-          fileName,
-        },
-        relPath: fileName,
-        mountKey: `briefcase-reference:artifact:${artifactId}:v${version}`,
-      };
-    }
-    case BriefcaseReferenceKind.SCM_REPO: {
-      // ref shape: `<repoRef>` or `<repoRef>@<gitRef>`. The repoRef is
-      // opaque to the composer; the SCM resolver decodes it.
-      const at = ref.ref.indexOf('@');
-      const repoRef = at < 0 ? ref.ref : ref.ref.slice(0, at);
-      const gitRef = at < 0 ? 'HEAD' : ref.ref.slice(at + 1);
-      return {
-        source: { kind: 'scm-repo', repoRef, ref: gitRef },
-        relPath: `scm/${repoRef}`,
-        mountKey: `briefcase-reference:scm:${repoRef}:${gitRef}`,
-      };
-    }
-    case BriefcaseReferenceKind.EXTERNAL_URL:
-      // No on-disk mount — the URL surfaces via context.json's
-      // workflowInputs projection. Audit trail logs the ref.
-      return null;
-    default:
-      throw new Error(
-        `Unhandled briefcase reference kind '${(ref as { kind: string }).kind}'.`,
-      );
-  }
-}
-
-interface ManifestLogicalSlot {
-  readonly slot: LogicalWorkspaceSlot;
-  readonly defaultMode: 'read-only' | 'read-write';
-}
-
-const MANIFEST_LOGICAL_SLOTS: Readonly<Record<string, ManifestLogicalSlot>> =
-  Object.freeze({
-    inputs: { slot: LogicalWorkspaceSlot.Inputs, defaultMode: 'read-only' },
-    tmp: { slot: LogicalWorkspaceSlot.Temporary, defaultMode: 'read-write' },
-    deliverables: {
-      slot: LogicalWorkspaceSlot.Deliverables,
-      defaultMode: 'read-write',
-    },
-    'deliverable-specs': {
-      slot: LogicalWorkspaceSlot.DeliverableSpecs,
-      defaultMode: 'read-only',
-    },
-    references: {
-      slot: LogicalWorkspaceSlot.References,
-      defaultMode: 'read-only',
-    },
-    repos: {
-      slot: LogicalWorkspaceSlot.Repositories,
-      defaultMode: 'read-write',
-    },
-    uploads: {
-      slot: LogicalWorkspaceSlot.Uploads,
-      defaultMode: 'read-only',
-    },
-  });
-
-function requireLogicalSlot(
-  key: string,
-  source:
-    | 'manifest.mounts'
-    | 'manifest.seedFiles'
-    | 'rendered.mounts'
-    | 'inputArtifacts',
-  manifestSlug: string,
-  manifestVersion: string,
-): ManifestLogicalSlot {
-  const slot = MANIFEST_LOGICAL_SLOTS[key];
-  if (!slot) {
-    throw new UnknownSlotError(key, source, manifestSlug, manifestVersion);
-  }
-  return slot;
-}
-
-/**
- * Drop the keys the composer itself consumes (subagents, skills, mount
- * routing hints, etc.) so the remainder is what the caller passed as
- * actual workflow inputs (e.g. the user's request text). Returns null
- * when nothing remains so the rendered-context-json source can omit the
- * field entirely instead of carrying an empty object.
- */
-function pickWorkflowInputs(
-  agentContext: Readonly<Record<string, unknown>>,
-): Readonly<Record<string, unknown>> | null {
-  const COMPOSER_RESERVED = new Set<string>([
-    'delegatedSubAgents',
-    'skills',
-    'instructions',
-    'runtimeConfig',
-    'mcpConfig',
-    'inputsJsonBase64',
-    'kbSpaceIds',
-    'kbPageMounts',
-    'externalProjectIds',
-    'repoRef',
-    'repoRevision',
-    'deliverableSpecRef',
-    'deliverablesRef',
-    'sessionId',
-    'inputArtifacts',
-  ]);
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(agentContext)) {
-    if (COMPOSER_RESERVED.has(k)) continue;
-    if (v === undefined) continue;
-    out[k] = v;
-  }
-  return Object.keys(out).length === 0 ? null : out;
-}
-
-/**
- * Project the manifest's mount declarations into the wire shape the
- * llm-registry renderer consumes — `{ mount: '/workspace/<slot>', mode }`.
- * The renderer derives `context.json.authority.mayWriteWorkspace[]` from
- * this list; the system overlay surfaces it to the agent as the
- * authoritative writable-paths declaration. Disabled mounts are dropped.
- *
- * Unknown slot keys throw `UnknownSlotError` — same fail-fast contract
- * as the user-data loop, so a manifest typo or stale slot name
- * surfaces at the first compose call instead of materializing an
- * incomplete `mayWriteWorkspace[]`.
- */
-/**
- * Project the workflow-supplied input artifacts into the renderer
- * wire shape: an absolute workspace path the agent reads from, plus the
- * artifact lineage for traceability. The renderer surfaces these in
- * AGENTS.md (`# Inputs`) and `context.json.workflow.inputArtifacts[]`,
- * so the agent doesn't have to ls slot directories to discover them.
- */
-function buildRenderedInputArtifacts(
-  inputArtifacts: readonly InputArtifactRef[] | undefined,
-): ReadonlyArray<{
-  readonly path: string;
-  readonly contentType?: string;
-  readonly sourceArtifactId: string;
-  readonly sourceVersion: number;
-}> {
-  if (!inputArtifacts || inputArtifacts.length === 0) return [];
-  const out: Array<{
-    path: string;
-    contentType?: string;
-    sourceArtifactId: string;
-    sourceVersion: number;
-  }> = [];
-  for (const ia of inputArtifacts) {
-    const slotKey = ia.slot ?? 'inputs';
-    const slotDef = MANIFEST_LOGICAL_SLOTS[slotKey];
-    if (!slotDef) continue;
-    out.push({
-      path: `${slotDef.slot}/${ia.fileName}`,
-      ...(ia.contentType !== undefined && { contentType: ia.contentType }),
-      sourceArtifactId: ia.artifactId,
-      sourceVersion: ia.version,
-    });
-  }
-  return out;
-}
-
-/**
- * Project compiled working-file bindings onto the render-request wire shape
- * so llm-registry can surface them on `context.json.workingFiles`.
- */
-function buildRenderedWorkingFiles(
-  workingFiles: readonly CompiledWorkingFile[] | undefined,
-): ReadonlyArray<{
-  readonly slug: string;
-  readonly path: string;
-  readonly format: 'markdown' | 'html' | 'json' | 'yaml' | 'text';
-  readonly syncDirection: 'down-only' | 'up-only' | 'bidirectional';
-  readonly sourceKind: string;
-  readonly sourceRef: Readonly<Record<string, string>>;
-}> {
-  if (!workingFiles || workingFiles.length === 0) return [];
-  return workingFiles.map((wf) => {
-    if (
-      wf.path.startsWith('/') ||
-      /(^|\/)\.opencode(\/|$)/.test(wf.path)
-    ) {
-      throw new Error(`NON_LOGICAL_WORKING_FILE_PATH:${wf.slug}:${wf.path}`);
-    }
-    return {
-      slug: wf.slug,
-      path: wf.path,
-      format: wf.format,
-      syncDirection: wf.syncDirection,
-      sourceKind: wf.sourceKind,
-      sourceRef: wf.sourceRef,
-    };
-  });
-}
-
-function buildRenderedMounts(
-  mounts: Readonly<
-    Record<string, { enabled: boolean; mode?: 'read-only' | 'read-write' }>
-  >,
-  manifestSlug: string,
-  manifestVersion: string,
-): ReadonlyArray<{ mount: string; mode: 'read-only' | 'read-write' }> {
-  const out: { mount: string; mode: 'read-only' | 'read-write' }[] = [];
-  for (const [slotKey, decl] of Object.entries(mounts)) {
-    if (!decl.enabled) continue;
-    const slotDef = requireLogicalSlot(
-      slotKey,
-      'rendered.mounts',
-      manifestSlug,
-      manifestVersion,
-    );
-    const mode = decl.mode ?? slotDef.defaultMode;
-    out.push({ mount: slotDef.slot, mode });
-  }
-  return out;
-}