@a5c-ai/krate 5.0.1-staging.f672fe79b

package/src/web-ui.js

@@ -0,0 +1,40 @@
+import { createResource } from './resource-model.js';
+import { toResourceYaml } from './identity-policy.js';
+
+export function createPullRequestReviewModel({ pullRequest, changedFiles = [], pipelineRuns = [] }) {
+  return { layout: 'three-pane-review', panes: ['file-tree', 'diff-and-comments', 'conversation-ci'], keyboardShortcuts: ['j/k file navigation', 'n/p comment navigation', 'a add suggestion', 'm merge'], pullRequest, changedFiles, pipelineRuns, yaml: toResourceYaml(pullRequest) };
+}
+
+export function createFailingRunModel({ pipeline, jobs }) {
+  const failedJobs = jobs.filter((job) => job.status.phase === 'Failed');
+  return { layout: 'live-run-debugger', stream: 'sse', pipeline, failedJobs, actions: ['copy failure', 'find similar runs', 'rerun from step'], similarRunSelector: failedJobs.map((job) => job.metadata.labels).filter(Boolean) };
+}
+
+export function createRunnerPoolEditor(pool) {
+  return { layout: 'split-form-yaml', fields: ['image', 'resources', 'nodeSelector', 'warmReplicas', 'maxReplicas', 'trustTier', 'cache'], resource: pool, yaml: toResourceYaml(pool), saveModes: ['apply', 'copy kubectl', 'open platform-config PR'] };
+}
+
+export function createWebhookInspector({ subscription, deliveries }) {
+  return { layout: 'webhook-inspector', subscription, deliveries, columns: ['phase', 'latency', 'attempts', 'response', 'signature'], actions: ['send test delivery', 'inspect headers/body/response', 'replay'] };
+}
+
+export function createPolicyRolloutModel(policy) {
+  return { layout: 'policy-authoring', modes: ['template', 'CEL/raw'], rollout: ['preview', 'audit', 'enforce'], policy, yaml: toResourceYaml(policy) };
+}
+
+export function createTriageView({ name, namespace = 'krate-org-default', organizationRef = 'default', selector }) {
+  return createResource('View', { name, namespace, labels: { purpose: 'triage' } }, { organizationRef, selector, columns: ['kind', 'repository', 'priority', 'assignee', 'status'], shareable: true }, { saved: true });
+}
+
+export function createDashboard({ repositories, pullRequests, pipelines, runnerPools, webhookDeliveries }) {
+  return {
+    product: 'Krate',
+    principles: ['Kubernetes is the backend', 'CRDs are contracts', 'GitOps transparency'],
+    repositories,
+    pullRequests,
+    pipelines,
+    runnerPools,
+    webhookDeliveries,
+    excellentFlows: ['Open and review a PR', 'Debug a failing run', 'Configure a runner pool', 'Add a webhook and verify it works', 'Write a PR policy with audit-to-enforce rollout', 'Cross-repo triage with saved filters']
+  };
+}

package/tests/agent-approval-controller.test.js

@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAgentApprovalController, createResource } from '../src/index.js';
+
+function makeApproval(name, dispatchRun, action, phase = 'Pending', extra = {}) {
+  const approval = createResource('AgentApproval', { name, namespace: 'krate-org-default' }, {
+    organizationRef: 'default',
+    dispatchRun,
+    action,
+    requestedBy: 'agent-stack-1',
+    ...extra
+  });
+  approval.status = { phase, createdAt: new Date().toISOString(), ...extra.status };
+  return approval;
+}
+
+test('Create approval request returns resource with phase=Pending', () => {
+  const controller = createAgentApprovalController();
+  const result = controller.createApprovalRequest({
+    dispatchRun: 'run-1',
+    action: 'tool-use',
+    requestedBy: 'agent-stack-1',
+    context: 'Needs filesystem write access',
+    namespace: 'krate-org-default',
+    organizationRef: 'default',
+    resources: {}
+  });
+
+  assert.equal(result.error, false, 'Should succeed');
+  assert.equal(result.duplicate, false, 'Should not be a duplicate');
+  assert.ok(result.approval, 'Should return an approval resource');
+  assert.equal(result.approval.kind, 'AgentApproval');
+  assert.equal(result.approval.status.phase, 'Pending');
+  assert.equal(result.approval.spec.action, 'tool-use');
+  assert.equal(result.approval.spec.dispatchRun, 'run-1');
+  assert.equal(result.approval.spec.requestedBy, 'agent-stack-1');
+  assert.ok(result.approval.status.createdAt, 'Should have createdAt timestamp');
+});
+
+test('Record approve sets phase=Approved and decidedBy', () => {
+  const controller = createAgentApprovalController();
+  const existing = makeApproval('approval-1', 'run-1', 'tool-use', 'Pending');
+  const result = controller.recordDecision({
+    approvalName: 'approval-1',
+    decision: 'approve',
+    decidedBy: 'owner',
+    reason: 'Looks safe',
+    resources: { AgentApproval: [existing] }
+  });
+
+  assert.equal(result.error, false, 'Should succeed');
+  assert.equal(result.approval.status.phase, 'Approved');
+  assert.equal(result.approval.status.decidedBy, 'owner');
+  assert.equal(result.approval.status.reason, 'Looks safe');
+  assert.ok(result.approval.status.decidedAt, 'Should have decidedAt timestamp');
+});
+
+test('Record deny sets phase=Denied', () => {
+  const controller = createAgentApprovalController();
+  const existing = makeApproval('approval-2', 'run-1', 'secret-access', 'Pending');
+  const result = controller.recordDecision({
+    approvalName: 'approval-2',
+    decision: 'deny',
+    decidedBy: 'admin',
+    reason: 'Sensitive secrets not allowed',
+    resources: { AgentApproval: [existing] }
+  });
+
+  assert.equal(result.error, false, 'Should succeed');
+  assert.equal(result.approval.status.phase, 'Denied');
+  assert.equal(result.approval.status.decidedBy, 'admin');
+  assert.equal(result.approval.status.reason, 'Sensitive secrets not allowed');
+});
+
+test('isActionApproved returns true after approval', () => {
+  const controller = createAgentApprovalController();
+  const approved = makeApproval('approval-3', 'run-2', 'write-back', 'Approved', { status: { decidedBy: 'owner', decidedAt: new Date().toISOString() } });
+  const result = controller.isActionApproved({
+    dispatchRun: 'run-2',
+    action: 'write-back',
+    resources: { AgentApproval: [approved] }
+  });
+
+  assert.equal(result.approved, true, 'Should be approved');
+  assert.ok(result.approval, 'Should return the approval resource');
+});
+
+test('isActionApproved returns false when still pending', () => {
+  const controller = createAgentApprovalController();
+  const pending = makeApproval('approval-4', 'run-3', 'release', 'Pending');
+  const result = controller.isActionApproved({
+    dispatchRun: 'run-3',
+    action: 'release',
+    resources: { AgentApproval: [pending] }
+  });
+
+  assert.equal(result.approved, false, 'Should not be approved');
+  assert.equal(result.reason, 'Approval is still pending');
+});
+
+test('Duplicate pending request returns existing approval', () => {
+  const controller = createAgentApprovalController();
+  const existing = makeApproval('approval-5', 'run-4', 'tool-use', 'Pending');
+  const result = controller.createApprovalRequest({
+    dispatchRun: 'run-4',
+    action: 'tool-use',
+    requestedBy: 'agent-stack-1',
+    resources: { AgentApproval: [existing] }
+  });
+
+  assert.equal(result.error, false, 'Should succeed');
+  assert.equal(result.duplicate, true, 'Should be flagged as duplicate');
+  assert.equal(result.approval.metadata.name, 'approval-5', 'Should return the existing approval');
+});
+
+test('Invalid action type returns error', () => {
+  const controller = createAgentApprovalController();
+  const result = controller.createApprovalRequest({
+    dispatchRun: 'run-5',
+    action: 'invalid-action',
+    requestedBy: 'agent-stack-1',
+    resources: {}
+  });
+
+  assert.equal(result.error, true, 'Should fail');
+  assert.equal(result.reason, 'invalid-action');
+  assert.ok(result.message.includes('invalid-action'), 'Message should mention the invalid action');
+});
+
+test('Already decided approval returns error on re-decide', () => {
+  const controller = createAgentApprovalController();
+  const decided = makeApproval('approval-6', 'run-6', 'escalation', 'Approved', { status: { decidedBy: 'admin', decidedAt: new Date().toISOString() } });
+  const result = controller.recordDecision({
+    approvalName: 'approval-6',
+    decision: 'deny',
+    decidedBy: 'other-admin',
+    resources: { AgentApproval: [decided] }
+  });
+
+  assert.equal(result.error, true, 'Should fail');
+  assert.equal(result.reason, 'already-decided');
+  assert.ok(result.message.includes('already been decided'), 'Message should indicate already decided');
+});
+
+test('listPendingApprovals filters by org and pending status', () => {
+  const controller = createAgentApprovalController();
+  const pending1 = makeApproval('p1', 'run-7', 'tool-use', 'Pending');
+  const pending2 = makeApproval('p2', 'run-8', 'release', 'Pending');
+  const approved = makeApproval('p3', 'run-9', 'write-back', 'Approved');
+
+  const result = controller.listPendingApprovals({
+    organizationRef: 'default',
+    resources: { AgentApproval: [pending1, pending2, approved] }
+  });
+
+  assert.equal(result.length, 2, 'Should return only pending approvals');
+  assert.ok(result.every(a => a.status.phase === 'Pending'), 'All should be Pending');
+});
+
+test('listApprovalsForRun filters by dispatch run', () => {
+  const controller = createAgentApprovalController();
+  const a1 = makeApproval('r1', 'run-10', 'tool-use', 'Pending');
+  const a2 = makeApproval('r2', 'run-10', 'secret-access', 'Approved');
+  const a3 = makeApproval('r3', 'run-11', 'release', 'Pending');
+
+  const result = controller.listApprovalsForRun({
+    dispatchRun: 'run-10',
+    resources: { AgentApproval: [a1, a2, a3] }
+  });
+
+  assert.equal(result.length, 2, 'Should return approvals for run-10 only');
+  assert.ok(result.every(a => a.spec.dispatchRun === 'run-10'), 'All should belong to run-10');
+});

package/tests/agent-context-bundles.test.js

@@ -0,0 +1,278 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { assembleContextBundle, createRedactionManifest } from '../src/agent-context-bundles.js';
+import { createResource } from '../src/resource-model.js';
+
+function makeStack(name, promptOverrides = {}, extraSpec = {}) {
+  return createResource('AgentStack', { name }, {
+    organizationRef: 'default',
+    baseAgent: 'claude-code',
+    adapter: 'babysitter',
+    runtimeIdentity: { serviceAccountRef: 'sa-agent' },
+    prompt: {
+      system: promptOverrides.system || '',
+      developer: promptOverrides.developer || '',
+      task: promptOverrides.task || '',
+    },
+    ...extraSpec
+  });
+}
+
+function makeSkill(name, promptFragment) {
+  return createResource('AgentSkill', { name }, {
+    organizationRef: 'default',
+    format: 'markdown',
+    sourceRef: `skills/${name}`,
+    promptFragment
+  });
+}
+
+function makeContextLabel(name, promptFragment) {
+  return createResource('AgentContextLabel', { name }, {
+    organizationRef: 'default',
+    promptFragment,
+    allowedSources: ['manual']
+  });
+}
+
+describe('agent context bundles', () => {
+  it('basic assembly with system/developer/task prompt', () => {
+    const stack = makeStack('test-stack', {
+      system: 'You are a security reviewer.',
+      developer: 'Focus on OWASP top 10.',
+      task: 'Review the authentication module.'
+    });
+    const bundle = assembleContextBundle({ stack, repository: 'my-repo', ref: 'refs/heads/main' });
+
+    assert.equal(bundle.kind, 'AgentContextBundle');
+    assert.equal(bundle.apiVersion, 'krate.a5c.ai/v1alpha1');
+    assert.ok(bundle.metadata.name.startsWith('bundle-'));
+    assert.equal(bundle.spec.organizationRef, 'default');
+    assert.equal(bundle.spec.dispatchRun, '');
+    assert.ok(typeof bundle.spec.digest === 'string' && bundle.spec.digest.length === 64);
+
+    // Prompt layers present
+    const layers = bundle.spec.promptLayers;
+    assert.equal(layers[0].role, 'system');
+    assert.equal(layers[1].role, 'developer');
+    assert.equal(layers[2].role, 'task');
+    assert.ok(layers[0].sizeBytes > 0);
+    assert.ok(layers[1].sizeBytes > 0);
+    assert.ok(layers[2].sizeBytes > 0);
+
+    // _content present (in-memory, not persisted)
+    assert.equal(bundle._content.system, 'You are a security reviewer.');
+    assert.equal(bundle._content.developer, 'Focus on OWASP top 10.');
+    assert.equal(bundle._content.task, 'Review the authentication module.');
+  });
+
+  it('redaction catches API_KEY=xxx patterns', () => {
+    const stack = makeStack('test-stack', {
+      system: 'config: API_KEY=sk_live_abc123xyz',
+      developer: '',
+      task: ''
+    });
+    const bundle = assembleContextBundle({ stack });
+    assert.ok(bundle._content.system.includes('[REDACTED:secret-key]'));
+    assert.ok(!bundle._content.system.includes('sk_live_abc123xyz'));
+    assert.ok(bundle.spec.redactions.total > 0);
+    assert.ok(bundle.spec.redactions.byKind['secret-key'] > 0);
+  });
+
+  it('redaction catches provider tokens (sk-xxx)', () => {
+    const stack = makeStack('test-stack', {
+      system: '',
+      developer: 'Use key: sk-abcdefghijklmnopqrstuvwxyz1234567890',
+      task: ''
+    });
+    const bundle = assembleContextBundle({ stack });
+    assert.ok(bundle._content.developer.includes('[REDACTED:provider-token]'));
+    assert.ok(!bundle._content.developer.includes('sk-abcdefghijklmnopqrstuvwxyz1234567890'));
+    assert.ok(bundle.spec.redactions.byKind['provider-token'] > 0);
+  });
+
+  it('redaction catches Bearer tokens', () => {
+    const stack = makeStack('test-stack', {
+      system: 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.test',
+      developer: '',
+      task: ''
+    });
+    const bundle = assembleContextBundle({ stack });
+    assert.ok(bundle._content.system.includes('[REDACTED:bearer-token]'));
+    assert.ok(!bundle._content.system.includes('eyJhbGciOiJIUzI1NiJ9'));
+    assert.ok(bundle.spec.redactions.byKind['bearer-token'] > 0);
+  });
+
+  it('redaction catches private keys', () => {
+    const privateKey = '-----BEGIN RSA PRIVATE KEY-----\nMIIBogIBAAJBALRpYJk...\n-----END RSA PRIVATE KEY-----';
+    const stack = makeStack('test-stack', {
+      system: `Here is a key: ${privateKey}`,
+      developer: '',
+      task: ''
+    });
+    const bundle = assembleContextBundle({ stack });
+    assert.ok(bundle._content.system.includes('[REDACTED:private-key]'));
+    assert.ok(!bundle._content.system.includes('MIIBogIBAAJBALRpYJk'));
+    assert.ok(bundle.spec.redactions.byKind['private-key'] > 0);
+  });
+
+  it('size truncation at 750 KiB', () => {
+    // Create a bundle that exceeds 750 KiB via many source attachments.
+    // Each source is truncated to 64 KiB per-layer, so we need enough sources
+    // to exceed 750 KiB total. 750/64 ~= 12, so 13 sources at 64 KiB each should exceed.
+    // Use content with spaces to avoid base64-credential pattern matching.
+    const chunk = 'the quick brown fox jumps.\n';
+    const bigContent = chunk.repeat(Math.ceil((64 * 1024) / chunk.length)).slice(0, 64 * 1024);
+    const stack = makeStack('test-stack', {
+      system: 'small system prompt',
+      developer: '',
+      task: ''
+    });
+    const sourceRefs = [];
+    for (let i = 0; i < 15; i++) {
+      sourceRefs.push({ kind: 'file', ref: `big-file-${i}.txt`, content: bigContent });
+    }
+    const bundle = assembleContextBundle({ stack, sourceRefs });
+
+    assert.equal(bundle.spec.limits.truncated, true);
+    assert.equal(bundle.spec.limits.maxBytes, 750 * 1024);
+
+    // Verify total content is at or near the limit
+    const allContentLen = bundle._content.system.length +
+      bundle._content.developer.length +
+      bundle._content.task.length +
+      bundle._content.sources.reduce((s, src) => s + src.content.length, 0);
+    assert.ok(allContentLen <= 750 * 1024 + 100, `total size ${allContentLen} should be near 750KiB limit`);
+  });
+
+  it('digest is deterministic (same input produces same digest)', () => {
+    const stack = makeStack('test-stack', {
+      system: 'Deterministic test system prompt.',
+      developer: 'Deterministic test developer prompt.',
+      task: 'Deterministic test task prompt.'
+    });
+    const sourceRefs = [{ kind: 'pr-body', ref: '#42', content: 'PR description here' }];
+
+    const bundle1 = assembleContextBundle({ stack, sourceRefs });
+    const bundle2 = assembleContextBundle({ stack, sourceRefs });
+
+    assert.equal(bundle1.spec.digest, bundle2.spec.digest);
+    assert.ok(typeof bundle1.spec.digest === 'string' && bundle1.spec.digest.length === 64);
+  });
+
+  it('redaction manifest has counts only (no leaked values)', () => {
+    const stack = makeStack('test-stack', {
+      system: 'SECRET_KEY = "my-super-secret-value123" and PASSWORD=hunter2',
+      developer: '',
+      task: ''
+    });
+    const bundle = assembleContextBundle({ stack });
+    const manifest = bundle.spec.redactions;
+
+    assert.ok(typeof manifest.total === 'number' && manifest.total >= 2);
+    assert.ok(typeof manifest.byKind === 'object');
+    // Ensure the manifest only has counts, no string values that could leak secrets
+    for (const [kind, count] of Object.entries(manifest.byKind)) {
+      assert.ok(typeof kind === 'string');
+      assert.ok(typeof count === 'number');
+    }
+    // Verify no secret values in the serialized manifest
+    const serialized = JSON.stringify(manifest);
+    assert.ok(!serialized.includes('my-super-secret-value123'));
+    assert.ok(!serialized.includes('hunter2'));
+  });
+
+  it('empty inputs handled gracefully', () => {
+    const stack = makeStack('test-stack', { system: '', developer: '', task: '' });
+    const bundle = assembleContextBundle({ stack });
+
+    assert.equal(bundle.kind, 'AgentContextBundle');
+    assert.ok(typeof bundle.spec.digest === 'string' && bundle.spec.digest.length === 64);
+    assert.equal(bundle.spec.promptLayers.length, 3);
+    assert.equal(bundle.spec.promptLayers[0].sizeBytes, 0);
+    assert.equal(bundle.spec.promptLayers[1].sizeBytes, 0);
+    assert.equal(bundle.spec.promptLayers[2].sizeBytes, 0);
+    assert.equal(bundle.spec.redactions.total, 0);
+    assert.equal(bundle.spec.limits.truncated, false);
+    assert.deepEqual(bundle.spec.sources, []);
+    assert.equal(bundle._content.system, '');
+    assert.equal(bundle._content.developer, '');
+    assert.equal(bundle._content.task, '');
+  });
+
+  it('assembles skill and label fragments from resources', () => {
+    const stack = makeStack('test-stack', {
+      system: 'System prompt',
+      developer: '',
+      task: ''
+    }, { skillRefs: ['skill-review', 'skill-test'] });
+    const resources = {
+      AgentSkill: [
+        makeSkill('skill-review', 'Review all changed files for security issues.'),
+        makeSkill('skill-test', 'Run unit tests before proceeding.'),
+        makeSkill('skill-unused', 'This should not appear.')
+      ],
+      AgentContextLabel: [
+        makeContextLabel('label-prod', 'This is a production environment.')
+      ]
+    };
+    const bundle = assembleContextBundle({
+      stack,
+      contextLabels: ['label-prod'],
+      resources
+    });
+
+    // Should have system + developer + task + 2 skills + 1 label = 6 layers
+    assert.equal(bundle.spec.promptLayers.length, 6);
+    assert.equal(bundle.spec.promptLayers[3].role, 'skill:skill-review');
+    assert.equal(bundle.spec.promptLayers[4].role, 'skill:skill-test');
+    assert.equal(bundle.spec.promptLayers[5].role, 'label:label-prod');
+    assert.ok(bundle._content.skillFragments.length === 2);
+    assert.ok(bundle._content.labelFragments.length === 1);
+  });
+
+  it('createRedactionManifest returns correct structure', () => {
+    const manifest = createRedactionManifest({ 'secret-key': 3, 'provider-token': 1, 'bearer-token': 2 });
+    assert.equal(manifest.total, 6);
+    assert.deepEqual(manifest.byKind, { 'secret-key': 3, 'provider-token': 1, 'bearer-token': 2 });
+  });
+
+  it('createRedactionManifest with empty counts', () => {
+    const manifest = createRedactionManifest({});
+    assert.equal(manifest.total, 0);
+    assert.deepEqual(manifest.byKind, {});
+  });
+
+  it('source refs are limited to MAX_ATTACHMENTS (32)', () => {
+    const stack = makeStack('test-stack', { system: '', developer: '', task: '' });
+    const sourceRefs = [];
+    for (let i = 0; i < 40; i++) {
+      sourceRefs.push({ kind: 'file', ref: `file-${i}.txt`, content: `content ${i}` });
+    }
+    const bundle = assembleContextBundle({ stack, sourceRefs });
+    assert.ok(bundle.spec.sources.length <= 32, 'should cap at 32 sources');
+    assert.ok(bundle._content.sources.length <= 32);
+  });
+
+  it('prompt layers are truncated to 64 KiB each', () => {
+    const oversized = 'a'.repeat(80 * 1024); // 80 KiB
+    const stack = makeStack('test-stack', {
+      system: oversized,
+      developer: '',
+      task: ''
+    });
+    const bundle = assembleContextBundle({ stack });
+    assert.ok(bundle._content.system.length <= 64 * 1024, 'system prompt should be truncated to 64 KiB');
+  });
+
+  it('redaction in source content', () => {
+    const stack = makeStack('test-stack', { system: '', developer: '', task: '' });
+    const sourceRefs = [
+      { kind: 'pipeline-log', ref: 'run-123', content: 'Error: API_KEY=leaked_value_here failed auth' }
+    ];
+    const bundle = assembleContextBundle({ stack, sourceRefs });
+    assert.ok(bundle._content.sources[0].content.includes('[REDACTED:secret-key]'));
+    assert.ok(!bundle._content.sources[0].content.includes('leaked_value_here'));
+    assert.ok(bundle.spec.redactions.total > 0);
+  });
+});

package/tests/agent-dispatch-controller.test.js

@@ -0,0 +1,176 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAgentDispatchController, createAgentMuxClient, createResource } from '../src/index.js';
+
+function makeStack(name, spec = {}) {
+  return createResource('AgentStack', { name, namespace: 'krate-org-default' }, {
+    organizationRef: 'default',
+    baseAgent: 'claude-code',
+    adapter: 'anthropic',
+    runtimeIdentity: { serviceAccountRef: 'sa-default' },
+    ...spec
+  });
+}
+
+function makeServiceAccount(name) {
+  return createResource('AgentServiceAccount', { name, namespace: 'krate-org-default' }, {
+    organizationRef: 'default',
+    namespace: 'krate-org-default',
+    serviceAccountName: name
+  });
+}
+
+function makeRoleBinding(name, subject) {
+  return createResource('AgentRoleBinding', { name, namespace: 'krate-org-default' }, {
+    organizationRef: 'default',
+    subject,
+    roleRef: 'agent-developer',
+    scope: 'namespace'
+  });
+}
+
+function makeSecretGrant(name, subject, purpose) {
+  return createResource('AgentSecretGrant', { name, namespace: 'krate-org-default' }, {
+    organizationRef: 'default',
+    subject,
+    secretRef: 'secret-' + purpose,
+    purpose
+  });
+}
+
+function buildValidResources(stackName) {
+  return {
+    AgentStack: [makeStack(stackName)],
+    AgentServiceAccount: [makeServiceAccount('sa-default')],
+    AgentRoleBinding: [makeRoleBinding('rb-1', 'sa-default')],
+    AgentSecretGrant: [makeSecretGrant('sg-model', 'sa-default', 'model-provider')]
+  };
+}
+
+test('Successful dispatch with Agent Mux available', async () => {
+  // Use a mock mux client that returns a session without making real HTTP calls
+  const muxClient = {
+    role: 'agent-mux-client',
+    isAvailable() { return true; },
+    async launchSession() { return { runId: `amux-${Date.now()}`, sessionId: `session-${Date.now()}` }; },
+  };
+  const resources = buildValidResources('dispatch-stack');
+  const controller = createAgentDispatchController({ agentMuxClient: muxClient });
+
+  const result = await controller.createManualDispatch({
+    repository: 'test-repo',
+    ref: 'main',
+    agentStack: 'dispatch-stack',
+    actor: 'test-user',
+    namespace: 'krate-org-default',
+    organizationRef: 'default',
+    resources
+  });
+
+  assert.equal(result.error, false, 'Dispatch should succeed');
+  assert.ok(result.run, 'Result should include run resource');
+  assert.ok(result.attempt, 'Result should include attempt resource');
+  assert.ok(result.contextBundle, 'Result should include contextBundle resource');
+  assert.ok(result.permissionSnapshot, 'Result should include permissionSnapshot');
+  assert.equal(result.run.kind, 'AgentDispatchRun');
+  assert.equal(result.attempt.kind, 'AgentDispatchAttempt');
+  assert.equal(result.run.status.phase, 'Running', 'Run phase should be Running when mux is available');
+  assert.ok(result.attempt.status.agentMuxRunId, 'Attempt should have agentMuxRunId');
+  assert.ok(result.attempt.status.agentMuxSessionId, 'Attempt should have agentMuxSessionId');
+  assert.ok(result.attempt.status.startedAt, 'Attempt should have startedAt timestamp');
+});
+
+test('Dispatch with Agent Mux unavailable', async () => {
+  const muxClient = createAgentMuxClient({ gateway: '', enabled: false });
+  const resources = buildValidResources('dispatch-stack');
+  const controller = createAgentDispatchController({ agentMuxClient: muxClient });
+
+  const result = await controller.createManualDispatch({
+    repository: 'test-repo',
+    ref: 'main',
+    agentStack: 'dispatch-stack',
+    actor: 'test-user',
+    namespace: 'krate-org-default',
+    organizationRef: 'default',
+    resources
+  });
+
+  assert.equal(result.error, false, 'Dispatch should still succeed (queued)');
+  assert.equal(result.run.status.phase, 'Queued', 'Run phase should be Queued when mux is unavailable');
+  assert.ok(result.run.status.conditions, 'Run should have conditions');
+  const muxCondition = result.run.status.conditions.find(c => c.type === 'AgentMuxBound');
+  assert.ok(muxCondition, 'Should have AgentMuxBound condition');
+  assert.equal(muxCondition.status, 'False', 'AgentMuxBound should be False');
+  assert.equal(muxCondition.reason, 'Unavailable');
+});
+
+test('Dispatch denied by permission review', async () => {
+  const resources = {
+    AgentStack: [makeStack('denied-stack', { runtimeIdentity: { serviceAccountRef: 'sa-missing' } })],
+    // No service account, no role binding, no secret grant — permission review will deny
+  };
+  const controller = createAgentDispatchController();
+
+  const result = await controller.createManualDispatch({
+    repository: 'test-repo',
+    ref: 'main',
+    agentStack: 'denied-stack',
+    actor: 'test-user',
+    namespace: 'krate-org-default',
+    organizationRef: 'default',
+    resources
+  });
+
+  assert.equal(result.error, true, 'Dispatch should be denied');
+  assert.equal(result.reason, 'permission-denied', 'Reason should be permission-denied');
+  assert.ok(result.review, 'Result should include the review details');
+  assert.equal(result.review.decision, 'denied');
+});
+
+test('Stack not found', async () => {
+  const resources = buildValidResources('existing-stack');
+  const controller = createAgentDispatchController();
+
+  const result = await controller.createManualDispatch({
+    repository: 'test-repo',
+    ref: 'main',
+    agentStack: 'nonexistent-stack',
+    actor: 'test-user',
+    namespace: 'krate-org-default',
+    organizationRef: 'default',
+    resources
+  });
+
+  assert.equal(result.error, true, 'Dispatch should fail');
+  assert.equal(result.reason, 'stack-not-found', 'Reason should be stack-not-found');
+  assert.ok(result.message.includes('nonexistent-stack'), 'Message should name the missing stack');
+});
+
+test('Context bundle referenced correctly', async () => {
+  const muxClient = createAgentMuxClient({ gateway: '', enabled: false });
+  const resources = buildValidResources('ref-stack');
+  const controller = createAgentDispatchController({ agentMuxClient: muxClient });
+
+  const result = await controller.createManualDispatch({
+    repository: 'test-repo',
+    ref: 'main',
+    agentStack: 'ref-stack',
+    actor: 'test-user',
+    namespace: 'krate-org-default',
+    organizationRef: 'default',
+    resources
+  });
+
+  assert.equal(result.error, false, 'Dispatch should succeed');
+  assert.ok(result.contextBundle.spec.digest, 'Context bundle should have a digest');
+  assert.equal(
+    result.attempt.spec.contextBundleDigest,
+    result.contextBundle.spec.digest,
+    'Attempt contextBundleDigest should match context bundle digest'
+  );
+  assert.equal(
+    result.run.spec.contextBundleRef,
+    result.contextBundle.metadata.name,
+    'Run contextBundleRef should match context bundle name'
+  );
+});