@a5c-ai/krate 5.0.1-staging.00fa5317c

package/src/agent-approval-controller.js

@@ -0,0 +1,170 @@
+import { createResource, clone } from './resource-model.js';
+
+export const AGENT_APPROVAL_CONTROLLER_BOUNDARY = {
+  role: 'agent-approval-controller',
+  scope: 'Human gate lifecycle for agent tool-use, secret-access, write-back, release, and escalation actions',
+  owns: ['approval creation', 'decision recording', 'approval lookup', 'duplicate detection'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'agent execution', 'UI rendering']
+};
+
+const VALID_ACTIONS = new Set(['tool-use', 'secret-access', 'write-back', 'release', 'escalation']);
+
+export function createAgentApprovalController() {
+  return {
+    role: 'agent-approval-controller',
+
+    createApprovalRequest({ dispatchRun, action, requestedBy, context, namespace = 'default', organizationRef = 'default', resources = {} }) {
+      if (!action || !VALID_ACTIONS.has(action)) {
+        return { error: true, reason: 'invalid-action', message: `Invalid action type: ${action}. Must be one of: ${[...VALID_ACTIONS].join(', ')}` };
+      }
+      if (!dispatchRun) {
+        return { error: true, reason: 'missing-dispatch-run', message: 'dispatchRun is required' };
+      }
+      if (!requestedBy) {
+        return { error: true, reason: 'missing-requested-by', message: 'requestedBy is required' };
+      }
+
+      // Check for duplicate pending approval
+      const existing = (resources.AgentApproval || []).find(
+        (a) => a.spec?.dispatchRun === dispatchRun && a.spec?.action === action && (!a.status?.phase || a.status.phase === 'Pending')
+      );
+      if (existing) {
+        return { error: false, approval: clone(existing), duplicate: true };
+      }
+
+      const now = new Date().toISOString();
+      const approvalName = `approval-${dispatchRun}-${action}-${Date.now()}`;
+
+      const approval = createResource('AgentApproval', { name: approvalName, namespace }, {
+        organizationRef,
+        dispatchRun,
+        action,
+        requestedBy,
+        description: context || `Agent requests permission to perform: ${action}`,
+        requestedAt: now
+      });
+      approval.status = { phase: 'Pending', createdAt: now };
+
+      return { error: false, approval, duplicate: false };
+    },
+
+    recordDecision({ approvalName, decision, decidedBy, reason, namespace = 'default', organizationRef = 'default', resources = {} }) {
+      if (!approvalName) {
+        return { error: true, reason: 'missing-approval-name', message: 'approvalName is required' };
+      }
+      if (!decision || (decision !== 'approve' && decision !== 'deny')) {
+        return { error: true, reason: 'invalid-decision', message: `Invalid decision: ${decision}. Must be 'approve' or 'deny'` };
+      }
+      if (!decidedBy) {
+        return { error: true, reason: 'missing-decided-by', message: 'decidedBy is required' };
+      }
+
+      const approvals = resources.AgentApproval || [];
+      const approval = approvals.find((a) => a.metadata?.name === approvalName);
+      if (!approval) {
+        return { error: true, reason: 'not-found', message: `AgentApproval not found: ${approvalName}` };
+      }
+
+      if (approval.status?.phase && approval.status.phase !== 'Pending') {
+        return { error: true, reason: 'already-decided', message: `AgentApproval ${approvalName} has already been decided: ${approval.status.phase}` };
+      }
+
+      const now = new Date().toISOString();
+      const phase = decision === 'approve' ? 'Approved' : 'Denied';
+
+      const updated = clone(approval);
+      updated.status = {
+        ...updated.status,
+        phase,
+        decidedBy,
+        decidedAt: now,
+        reason: reason || undefined
+      };
+
+      return { error: false, approval: updated };
+    },
+
+    isActionApproved({ dispatchRun, action, resources = {} }) {
+      const approvals = resources.AgentApproval || [];
+      const match = approvals.find(
+        (a) => a.spec?.dispatchRun === dispatchRun && a.spec?.action === action
+      );
+
+      if (!match) {
+        return { approved: false, approval: null, reason: 'No approval request found' };
+      }
+
+      if (match.status?.phase === 'Approved') {
+        return { approved: true, approval: clone(match), reason: match.status.reason || 'Approved' };
+      }
+
+      if (match.status?.phase === 'Denied') {
+        return { approved: false, approval: clone(match), reason: match.status.reason || 'Denied' };
+      }
+
+      return { approved: false, approval: clone(match), reason: 'Approval is still pending' };
+    },
+
+    listPendingApprovals({ organizationRef, resources = {} }) {
+      const approvals = resources.AgentApproval || [];
+      return approvals.filter((a) => {
+        const matchesOrg = !organizationRef || a.spec?.organizationRef === organizationRef;
+        const isPending = !a.status?.phase || a.status.phase === 'Pending';
+        return matchesOrg && isPending;
+      }).map(clone);
+    },
+
+    listApprovalsForRun({ dispatchRun, resources = {} }) {
+      const approvals = resources.AgentApproval || [];
+      return approvals.filter((a) => a.spec?.dispatchRun === dispatchRun).map(clone);
+    },
+
+    // -----------------------------------------------------------------------
+    // B1: Persistence
+    // -----------------------------------------------------------------------
+
+    async persistApproval({ approval, applyResource }) {
+      if (!approval) {
+        return { error: true, reason: 'missing-approval', message: 'approval is required' };
+      }
+      if (typeof applyResource !== 'function') {
+        return { error: true, reason: 'missing-apply-resource', message: 'applyResource function is required' };
+      }
+      try {
+        const applyResult = await applyResource(approval);
+        return { error: false, approval, applyResult };
+      } catch (err) {
+        return { error: true, reason: 'persist-failed', message: err?.message || 'applyResource failed' };
+      }
+    },
+
+    // -----------------------------------------------------------------------
+    // B1: Enforcement gate
+    // -----------------------------------------------------------------------
+
+    enforceApproval({ dispatchRun, action, resources = {} }) {
+      const approvals = resources.AgentApproval || [];
+      const match = approvals.find(
+        (a) => a.spec?.dispatchRun === dispatchRun && a.spec?.action === action
+      );
+
+      if (!match) {
+        return { allowed: false, reason: 'no-approval-found', message: `No approval found for dispatchRun=${dispatchRun} action=${action}`, approval: null };
+      }
+
+      const phase = match.status?.phase;
+
+      if (phase === 'Approved') {
+        return { allowed: true, approval: clone(match), reason: 'approved' };
+      }
+
+      if (phase === 'Denied') {
+        return { allowed: false, reason: 'approval-denied', message: `Approval for dispatchRun=${dispatchRun} action=${action} was denied`, approval: clone(match) };
+      }
+
+      // Pending or unknown
+      return { allowed: false, reason: 'approval-pending', message: `Approval for dispatchRun=${dispatchRun} action=${action} is still pending`, approval: clone(match) };
+    }
+  };
+}

package/src/agent-context-bundles.js

@@ -0,0 +1,242 @@
+import { createHash } from 'node:crypto';
+import { createResource, clone } from './resource-model.js';
+
+export const AGENT_CONTEXT_BUNDLES_BOUNDARY = {
+  role: 'agent-context-bundles',
+  scope: 'Context assembly, redaction, and digest computation for agent dispatch',
+  owns: ['prompt layer collection', 'redaction patterns', 'size enforcement', 'digest computation'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['secret values', 'runtime execution', 'Agent Mux sessions']
+};
+
+const PROMPT_LAYER_MAX = 64 * 1024;  // 64 KiB
+const BUNDLE_MAX = 750 * 1024;       // 750 KiB
+const MAX_ATTACHMENTS = 32;
+
+// Redaction patterns (ordered by priority)
+const REDACTION_PATTERNS = [
+  { kind: 'secret-key', pattern: /(?:API_KEY|API_SECRET|SECRET_KEY|ACCESS_KEY|PRIVATE_KEY|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)\s*[=:]\s*['"]?([^\s'"}{,\]]+)/gi },
+  { kind: 'provider-token', pattern: /\b(sk-[a-zA-Z0-9]{20,}|ghp_[a-zA-Z0-9]{36,}|gho_[a-zA-Z0-9]{36,}|glpat-[a-zA-Z0-9\-_]{20,}|xoxb-[a-zA-Z0-9\-]+|xoxp-[a-zA-Z0-9\-]+)\b/g },
+  { kind: 'bearer-token', pattern: /Bearer\s+[a-zA-Z0-9\-._~+\/]+=*/gi },
+  { kind: 'private-key', pattern: /-----BEGIN\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+|EC\s+|DSA\s+|OPENSSH\s+)?PRIVATE\s+KEY-----/g },
+  { kind: 'base64-credential', pattern: /\b[A-Za-z0-9+\/]{40,}={0,2}\b/g },
+];
+
+function sha256(data) {
+  return createHash('sha256').update(data).digest('hex');
+}
+
+function truncateToLimit(text, limit) {
+  if (typeof text !== 'string') return '';
+  if (text.length <= limit) return text;
+  return text.slice(0, limit);
+}
+
+function applyRedactions(text) {
+  if (typeof text !== 'string' || text.length === 0) return { text, counts: {} };
+  const counts = {};
+  let redacted = text;
+  for (const { kind, pattern } of REDACTION_PATTERNS) {
+    const fresh = new RegExp(pattern.source, pattern.flags);
+    const before = redacted;
+    redacted = redacted.replace(fresh, (match) => {
+      counts[kind] = (counts[kind] || 0) + 1;
+      return `[REDACTED:${kind}]`;
+    });
+  }
+  return { text: redacted, counts };
+}
+
+function mergeRedactionCounts(target, source) {
+  for (const [kind, count] of Object.entries(source)) {
+    target[kind] = (target[kind] || 0) + count;
+  }
+}
+
+export function createRedactionManifest(redactionCounts) {
+  const total = Object.values(redactionCounts).reduce((sum, n) => sum + n, 0);
+  return { total, byKind: clone(redactionCounts) };
+}
+
+export function assembleContextBundle({ stack, repository, ref, sourceRefs = [], contextLabels = [], redactionPolicy, resources = {} }) {
+  const namespace = stack?.metadata?.namespace || 'default';
+  const organizationRef = stack?.spec?.organizationRef || 'default';
+  const allRedactionCounts = {};
+
+  // Step 1 — Collect prompt layers
+  const rawSystem = stack?.spec?.prompt?.system || '';
+  const rawDeveloper = stack?.spec?.prompt?.developer || '';
+  const rawTask = stack?.spec?.prompt?.task || '';
+
+  // Collect skill fragments
+  const skillFragments = [];
+  const skillRefs = stack?.spec?.skillRefs || [];
+  const agentSkills = resources.AgentSkill || [];
+  for (const skillRef of skillRefs) {
+    const skill = agentSkills.find((s) => s.metadata?.name === skillRef);
+    if (skill?.spec?.promptFragment) {
+      skillFragments.push({ name: skillRef, content: skill.spec.promptFragment });
+    }
+  }
+
+  // Collect label fragments
+  const labelFragments = [];
+  const agentContextLabels = resources.AgentContextLabel || [];
+  for (const labelRef of contextLabels) {
+    const label = agentContextLabels.find((l) => l.metadata?.name === labelRef);
+    if (label?.spec?.promptFragment) {
+      labelFragments.push({ name: labelRef, content: label.spec.promptFragment });
+    }
+  }
+
+  // Step 2 — Truncate each layer and compute digests
+  const system = truncateToLimit(rawSystem, PROMPT_LAYER_MAX);
+  const developer = truncateToLimit(rawDeveloper, PROMPT_LAYER_MAX);
+  const task = truncateToLimit(rawTask, PROMPT_LAYER_MAX);
+
+  // Apply redaction to prompt layers
+  const systemRedacted = applyRedactions(system);
+  mergeRedactionCounts(allRedactionCounts, systemRedacted.counts);
+  const developerRedacted = applyRedactions(developer);
+  mergeRedactionCounts(allRedactionCounts, developerRedacted.counts);
+  const taskRedacted = applyRedactions(task);
+  mergeRedactionCounts(allRedactionCounts, taskRedacted.counts);
+
+  const systemDigest = sha256(systemRedacted.text);
+  const developerDigest = sha256(developerRedacted.text);
+  const taskDigest = sha256(taskRedacted.text);
+
+  const skillLayerDigests = [];
+  const redactedSkillFragments = [];
+  for (const frag of skillFragments) {
+    const truncated = truncateToLimit(frag.content, PROMPT_LAYER_MAX);
+    const redacted = applyRedactions(truncated);
+    mergeRedactionCounts(allRedactionCounts, redacted.counts);
+    const digest = sha256(redacted.text);
+    skillLayerDigests.push({ role: `skill:${frag.name}`, digest, sizeBytes: redacted.text.length });
+    redactedSkillFragments.push({ name: frag.name, content: redacted.text });
+  }
+
+  const labelLayerDigests = [];
+  const redactedLabelFragments = [];
+  for (const frag of labelFragments) {
+    const truncated = truncateToLimit(frag.content, PROMPT_LAYER_MAX);
+    const redacted = applyRedactions(truncated);
+    mergeRedactionCounts(allRedactionCounts, redacted.counts);
+    const digest = sha256(redacted.text);
+    labelLayerDigests.push({ role: `label:${frag.name}`, digest, sizeBytes: redacted.text.length });
+    redactedLabelFragments.push({ name: frag.name, content: redacted.text });
+  }
+
+  // Step 3 — Collect sources from sourceRefs
+  const sources = [];
+  const limitedSourceRefs = sourceRefs.slice(0, MAX_ATTACHMENTS);
+  for (const srcRef of limitedSourceRefs) {
+    const content = truncateToLimit(srcRef.content || '', PROMPT_LAYER_MAX);
+    const redacted = applyRedactions(content);
+    mergeRedactionCounts(allRedactionCounts, redacted.counts);
+    sources.push({
+      kind: srcRef.kind || 'unknown',
+      ref: srcRef.ref || '',
+      content: redacted.text,
+      digest: sha256(redacted.text)
+    });
+  }
+
+  // Step 5 — Enforce total size
+  let wasTruncated = false;
+  const TRUNC_MARKER = '[...truncated at 750KiB limit]';
+  const TRUNC_MARKER_LEN = TRUNC_MARKER.length;
+
+  const computeTotalSize = () =>
+    systemRedacted.text.length + developerRedacted.text.length + taskRedacted.text.length +
+    redactedSkillFragments.reduce((s, f) => s + f.content.length, 0) +
+    redactedLabelFragments.reduce((s, f) => s + f.content.length, 0) +
+    sources.reduce((s, src) => s + src.content.length, 0);
+
+  let totalSize = computeTotalSize();
+
+  if (totalSize > BUNDLE_MAX) {
+    wasTruncated = true;
+    // Build a list of truncatable items (sources first, then labels, then skills)
+    // sorted by descending size so we cut the largest first
+    const truncatableItems = [
+      ...sources.map((s, i) => ({ type: 'source', index: i })),
+      ...redactedLabelFragments.map((f, i) => ({ type: 'label', index: i })),
+      ...redactedSkillFragments.map((f, i) => ({ type: 'skill', index: i }))
+    ];
+
+    const getContent = (t) => {
+      if (t.type === 'source') return sources[t.index].content;
+      if (t.type === 'label') return redactedLabelFragments[t.index].content;
+      return redactedSkillFragments[t.index].content;
+    };
+
+    truncatableItems.sort((a, b) => getContent(b).length - getContent(a).length);
+
+    for (const target of truncatableItems) {
+      totalSize = computeTotalSize();
+      if (totalSize <= BUNDLE_MAX) break;
+
+      const currentContent = getContent(target);
+      const excess = totalSize - BUNDLE_MAX;
+      // We need to remove at least `excess` bytes, but also account for the marker we add
+      const cutAmount = excess + TRUNC_MARKER_LEN;
+      const newLen = Math.max(0, currentContent.length - cutAmount);
+      const truncatedContent = currentContent.slice(0, newLen) + TRUNC_MARKER;
+
+      if (target.type === 'source') {
+        sources[target.index].content = truncatedContent;
+        sources[target.index].digest = sha256(truncatedContent);
+      } else if (target.type === 'label') {
+        redactedLabelFragments[target.index].content = truncatedContent;
+        labelLayerDigests[target.index].digest = sha256(truncatedContent);
+        labelLayerDigests[target.index].sizeBytes = truncatedContent.length;
+      } else if (target.type === 'skill') {
+        redactedSkillFragments[target.index].content = truncatedContent;
+        skillLayerDigests[target.index].digest = sha256(truncatedContent);
+        skillLayerDigests[target.index].sizeBytes = truncatedContent.length;
+      }
+    }
+  }
+
+  // Step 6 — Compute bundle digest
+  const promptLayers = [
+    { role: 'system', digest: systemDigest, sizeBytes: systemRedacted.text.length },
+    { role: 'developer', digest: developerDigest, sizeBytes: developerRedacted.text.length },
+    { role: 'task', digest: taskDigest, sizeBytes: taskRedacted.text.length },
+    ...skillLayerDigests,
+    ...labelLayerDigests,
+  ];
+
+  const digestPayload = JSON.stringify({
+    promptLayers,
+    sources: sources.map((s) => ({ kind: s.kind, ref: s.ref, digest: s.digest }))
+  });
+  const digest = sha256(digestPayload);
+
+  const redactionManifest = createRedactionManifest(allRedactionCounts);
+
+  // Step 7 — Build the resource
+  const resource = createResource('AgentContextBundle', { name: `bundle-${digest.slice(0, 12)}`, namespace }, {
+    organizationRef,
+    dispatchRun: '',
+    digest,
+    sources: limitedSourceRefs.map((s) => ({ kind: s.kind || 'unknown', ref: s.ref || '' })),
+    promptLayers,
+    redactions: redactionManifest,
+    limits: { maxBytes: BUNDLE_MAX, truncated: wasTruncated },
+  });
+
+  // Store actual text content in _content (in-memory only, not part of resource spec)
+  resource._content = {
+    system: systemRedacted.text,
+    developer: developerRedacted.text,
+    task: taskRedacted.text,
+    skillFragments: redactedSkillFragments,
+    labelFragments: redactedLabelFragments,
+    sources
+  };
+
+  return resource;
+}

package/src/agent-dispatch-controller.js

@@ -0,0 +1,209 @@
+import { createPermissionReviewer } from './agent-permission-review.js';
+import { createAgentStackController } from './agent-stack-controller.js';
+import { assembleContextBundle } from './agent-context-bundles.js';
+import { createResource, clone } from './resource-model.js';
+import { createAgentMuxClient } from './agent-mux-client.js';
+import { createAgentMemoryController } from './agent-memory-controller.js';
+import { createAgentApprovalController } from './agent-approval-controller.js';
+import { createAgentWorkspaceController } from './agent-workspace-controller.js';
+
+export const AGENT_DISPATCH_CONTROLLER_BOUNDARY = {
+  role: 'agent-dispatch-controller',
+  scope: 'Manual dispatch orchestration with permission gating, context assembly, and workspace provisioning',
+  owns: ['dispatch creation', 'attempt lifecycle', 'Agent Mux session binding', 'workspace provisioning'],
+  delegatesTo: ['agent-permission-review', 'agent-stack-controller', 'agent-context-bundles', 'agent-mux-client', 'agent-memory-controller', 'agent-approval-controller', 'agent-workspace-controller'],
+  mustNotOwn: ['secret values', 'UI rendering']
+};
+
+export function createAgentDispatchController(options = {}) {
+  const permissionReviewer = options.permissionReviewer || createPermissionReviewer();
+  const stackController = options.stackController || createAgentStackController();
+  const agentMuxClient = options.agentMuxClient || createAgentMuxClient();
+  const memoryController = options.memoryController || createAgentMemoryController();
+  const approvalController = options.approvalController || createAgentApprovalController();
+  const workspaceController = options.workspaceController || createAgentWorkspaceController();
+
+  return {
+    role: 'agent-dispatch-controller',
+
+    async createManualDispatch({ repository, ref, sourceRefs = [], agentStack, taskKind, actor, namespace = 'default', organizationRef = 'default', resources = {} }) {
+      // 1. Find stack
+      const stack = (resources.AgentStack || []).find(s => s.metadata?.name === agentStack);
+      if (!stack) return { error: true, reason: 'stack-not-found', message: `AgentStack '${agentStack}' not found` };
+
+      // 2. Permission review
+      const review = permissionReviewer.reviewPermissions({ repository, ref, actor, agentStack, resources });
+      if (review.decision === 'denied') {
+        return { error: true, reason: 'permission-denied', message: 'Dispatch denied by permission review', review };
+      }
+      const permissionSnapshot = permissionReviewer.createPermissionSnapshot(review);
+
+      // 3. Memory snapshot — create if any AgentMemoryRepository exists in resources
+      let memorySnapshot = null;
+      const memoryRepos = resources.AgentMemoryRepository || [];
+      if (memoryRepos.length > 0) {
+        const memRepo = memoryRepos[0];
+        const timeTravel = memoryController.resolveTimeTravel({ mode: 'current', commits: [] });
+        memorySnapshot = memoryController.createMemorySnapshot({
+          memoryRepository: memRepo.metadata.name,
+          requestedRef: ref,
+          resolvedCommit: timeTravel.resolvedCommit || ref,
+          queryManifest: {},
+          selectedRecords: [],
+          selectedDocuments: [],
+          ontologyDigest: '',
+          namespace,
+          organizationRef,
+        });
+      }
+
+      // 4. Approval gate — if review requires approval, create approval and return early
+      if (review.decision === 'requires-approval') {
+        const now = new Date().toISOString();
+        const runName = `dispatch-${Date.now()}`;
+
+        const run = createResource('AgentDispatchRun', { name: runName, namespace }, {
+          organizationRef,
+          repository,
+          sourceRefs: clone(sourceRefs),
+          agentStack,
+          taskKind: taskKind || 'diagnostic',
+          contextBundleRef: null,
+        });
+        run.status = { phase: 'AwaitingApproval', queuedAt: now };
+        if (memorySnapshot) {
+          run.spec.memorySnapshotRef = memorySnapshot.metadata.name;
+        }
+
+        const approvalResult = approvalController.createApprovalRequest({
+          dispatchRun: runName,
+          action: 'secret-access',
+          requestedBy: actor,
+          context: `Dispatch requires approval for agent stack: ${agentStack}`,
+          namespace,
+          organizationRef,
+          resources,
+        });
+
+        return {
+          error: false,
+          run,
+          approval: approvalResult.error ? null : approvalResult.approval,
+          awaitingApproval: true,
+          memorySnapshot,
+          permissionSnapshot,
+          review,
+        };
+      }
+
+      // 5. Workspace provisioning — reuse or create
+      let workspaceResult = null;
+      let mountSpec = null;
+      const branch = ref || 'main';
+
+      const reusable = workspaceController.findReusableWorkspace({
+        organizationRef, repository, branch, resources,
+      });
+
+      if (reusable) {
+        const claimResult = workspaceController.claimWorkspace({
+          name: reusable.metadata.name,
+          runRef: `dispatch-pending`,
+          resources,
+        });
+        if (!claimResult.error) {
+          workspaceResult = { workspace: claimResult.workspace, reused: true };
+          const mount = workspaceController.getMountSpec({ workspace: claimResult.workspace });
+          if (!mount.error) mountSpec = { volume: mount.volume, volumeMount: mount.volumeMount };
+        }
+      }
+
+      if (!workspaceResult) {
+        const createResult = workspaceController.createWorkspace({
+          organizationRef, repository, branch, namespace,
+          volumeSpec: {},
+        });
+        if (!createResult.error) {
+          workspaceResult = { workspace: createResult.workspace, pvcManifest: createResult.pvcManifest, reused: false };
+          const mount = workspaceController.getMountSpec({ workspace: createResult.workspace });
+          if (!mount.error) mountSpec = { volume: mount.volume, volumeMount: mount.volumeMount };
+        }
+      }
+
+      // 6. Assemble context bundle
+      const contextBundle = assembleContextBundle({ stack, repository, ref, sourceRefs, contextLabels: [], resources });
+
+      // 7. Create resources
+      const now = new Date().toISOString();
+      const runName = `dispatch-${Date.now()}`;
+
+      const run = createResource('AgentDispatchRun', { name: runName, namespace }, {
+        organizationRef,
+        repository,
+        sourceRefs: clone(sourceRefs),
+        agentStack,
+        taskKind: taskKind || 'diagnostic',
+        contextBundleRef: contextBundle.metadata.name,
+      });
+      run.status = { phase: 'Pending', queuedAt: now };
+      if (memorySnapshot) {
+        run.spec.memorySnapshotRef = memorySnapshot.metadata.name;
+      }
+      if (workspaceResult) {
+        run.spec.workspaceRef = workspaceResult.workspace.metadata.name;
+      }
+      if (mountSpec) {
+        run.spec.mountSpec = mountSpec;
+      }
+
+      // Update workspace runRef to actual dispatch name
+      if (workspaceResult) {
+        workspaceResult.workspace.status.runRef = runName;
+      }
+
+      const attempt = createResource('AgentDispatchAttempt', { name: `${runName}-attempt-1`, namespace }, {
+        organizationRef,
+        agentDispatchRun: runName,
+        attemptReason: 'initial',
+        agentStackSnapshot: clone(stack.spec),
+        contextBundleDigest: contextBundle.spec.digest,
+      });
+      attempt.status = { permissionSnapshot, queueEnteredAt: now };
+
+      // 7. Try Agent Mux launch
+      let transcript = null;
+      if (agentMuxClient.isAvailable()) {
+        try {
+          const session = await agentMuxClient.launchSession({ stack, contextBundle, permissionSnapshot });
+          if (session && session.runId) {
+            attempt.status.agentMuxRunId = session.runId;
+            attempt.status.agentMuxSessionId = session.sessionId;
+            run.status.phase = 'Running';
+            attempt.status.startedAt = now;
+
+            // 8. After successful launch — start SSE subscription + create initial transcript
+            const collectedEvents = [];
+            const subscription = agentMuxClient.subscribeToEvents(session.runId, (event) => {
+              collectedEvents.push(event);
+            });
+            run.status.sseSubscription = { runId: session.runId, active: true };
+
+            transcript = agentMuxClient.reconcileTranscript(session.sessionId, collectedEvents, { namespace, organizationRef });
+            run.status.transcriptRef = transcript.metadata.name;
+          } else {
+            run.status.phase = 'Queued';
+            run.status.conditions = [{ type: 'AgentMuxBound', status: 'False', reason: 'LaunchFailed', message: 'Agent Mux launch returned no session' }];
+          }
+        } catch {
+          run.status.phase = 'Queued';
+          run.status.conditions = [{ type: 'AgentMuxBound', status: 'False', reason: 'LaunchFailed' }];
+        }
+      } else {
+        run.status.phase = 'Queued';
+        run.status.conditions = [{ type: 'AgentMuxBound', status: 'False', reason: 'Unavailable', message: 'Agent Mux gateway not configured' }];
+      }
+
+      return { error: false, run, attempt, contextBundle, permissionSnapshot, memorySnapshot, transcript, workspace: workspaceResult, mountSpec };
+    }
+  };
+}