@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/ci-orchestration-spec.md

@@ -0,0 +1,140 @@
+# Agent CI orchestration spec
+
+## Purpose
+
+CI is one source of agent work in the broader Krate agent orchestration model. Failed checks, pipeline events, flaky-test clusters, release gates, and artifact reviews should select a configured `AgentStack` and create an `AgentDispatchRun` that appears beside normal `Pipeline` and `Job` records.
+
+The canonical stack/resource model lives in [Agent stack management spec](./agent-stack-management-spec.md). This document defines the CI-specific trigger, context, runner, and acceptance requirements.
+
+## Primary CI use cases
+
+### Failed PR check diagnosis
+
+1. A `Pipeline` or `Job` fails for a PR.
+2. Krate extracts the failed job, step, log window, failure signature, artifacts, changed files, branch, commit SHA, and related PR discussion.
+3. The PR check panel offers `Diagnose with agent`.
+4. A trigger rule or manual action selects an `AgentStack` such as `claude-code-ci-diagnoser`.
+5. The agent receives a bounded context bundle with logs, artifacts, diff context, repo policy, and requested output format.
+6. The agent returns a diagnosis, likely fix paths, subagent findings, and optional patch artifact.
+
+### Failed PR check repair
+
+1. A maintainer chooses `Attempt repair` from a failed check or comments `@agent fix failing check`.
+2. Krate creates an `AgentDispatchRun` linked to the failed `Pipeline`, `Job`, PR, and commit SHA.
+3. The run is scheduled on a runner pool compatible with the PR trust tier.
+4. The selected stack may invoke subagents such as diagnoser, test-fixer, reviewer, or validator.
+5. The agent produces a patch artifact, branch proposal, suggested diff, or PR update request.
+6. Krate requires approval before pushing commits, updating the PR, submitting a review, or rerunning privileged workflows.
+
+### Flaky test triage
+
+1. Krate groups recent failures by `failure.signature`, job metadata, test names, and affected paths.
+2. A scheduled or manual trigger runs a triage stack against failed and passing runs.
+3. The agent summarizes suspected flake source, affected tests, owners, confidence, and recommended next actions.
+4. Krate writes findings to an issue/work item/saved triage view only when policy allows.
+
+### Release gate review
+
+1. Develop, staging, main, or tag publish workflows produce chart, image, UI, package-validation, checksum artifacts, and branch deployments where configured.
+2. A release-review stack inspects artifact completeness, checksum consistency, package/chart/image version alignment, release note gaps, and deployment policy.
+3. The agent cannot publish directly; it produces a release-readiness report unless a privileged approval path is configured.
+
+## CI signals agents need
+
+Agents should not scrape CI pages. Krate should pass structured context from its own resources and artifacts.
+
+Required context bundle fields:
+
+- `repository`: name, default branch, clone URL, visibility, trust tier;
+- `ref`: branch, commit SHA, PR head/base, fork status;
+- `source`: failed check, manual, PR comment, issue comment, label, scheduled scan, webhook;
+- `actor`: user, bot, team, permission decision;
+- `pullRequest`: title, body, labels, changed files, review state, mergeability;
+- `pipeline`: workflow name, run ID, status, conclusion, check name, URL;
+- `job`: job ID, step name, exit code, runner pool, image, duration;
+- `logs`: bounded log excerpts with redaction status;
+- `artifacts`: artifact names, types, URLs, digests, retention;
+- `failure`: signature, stack trace, test names, file paths, similar runs;
+- `stack`: selected `AgentStack`, tool profile, MCP servers, skills, subagents, approval mode;
+- `policy`: allowed tools, write-back mode, approval mode, network/secret restrictions;
+- `identity`: runtime ServiceAccount, runner ServiceAccount, native roles, Secret grants, and ConfigMap grants;
+- `contextLabels`: selected prompt fragments and provenance.
+
+## CI trigger contracts
+
+### Failed check trigger
+
+- Input: `Pipeline` or `Job` status transitions to failed.
+- Match keys: repository, PR, workflow, job, step, branch, path filters, failure signature.
+- Dedupe key: repository + PR/check source + commit SHA + job + step + failure signature + rule.
+- Default action: create a diagnosis suggestion; auto-run only if repository policy enables it.
+- Required context: failed log excerpt, job metadata, changed files, artifacts, similar failures.
+
+### Check rerun trigger
+
+- Input: rerun requested by human, rule, or approved agent output.
+- Match keys: previous dispatch run, target pipeline/job/step, actor, approval record.
+- Dedupe key: original run + approved artifact digest + target check.
+- Default action: create a new `Pipeline` resource or external workflow rerun and link it back to the agent dispatch.
+
+### Release trigger
+
+- Input: tag push, main publish workflow, or release-candidate schedule.
+- Match keys: version, chart package, npm artifact, image tag, checksum artifact, release branch.
+- Dedupe key: version + commit SHA + artifact digest set.
+- Default action: produce a release-readiness report and approval item for privileged publishing gaps.
+
+### Flaky triage trigger
+
+- Input: scheduled scan or repeated failure signature threshold.
+- Match keys: failure signature, job name, test name, branch, path, owner, time window.
+- Dedupe key: signature + query digest + result set digest.
+- Default action: summarize, create/update work item, and optionally dispatch repair after approval.
+
+## Runner and execution requirements
+
+- Agent dispatch attempts must schedule through `RunnerPool` policy or an explicitly configured external Agent Mux gateway.
+- Fork PRs and untrusted refs must use untrusted pools and receive no privileged secrets.
+- Trusted agents may receive scoped secrets only through runner policy and only for approved task kinds.
+- Runner pods must use a policy-selected Kubernetes ServiceAccount, and untrusted/forked refs must not receive privileged ServiceAccounts.
+- CI-triggered agents must validate `AgentSecretGrant`, `AgentConfigGrant`, and native RBAC before launch.
+- Tool, MCP, skill, and model-provider Secret/ConfigMap requirements must be shown in the run context snapshot.
+- Agent workspaces must be isolated per dispatch attempt and bound to repository/ref/pipeline identity.
+- Long-running sessions must publish queue, start, heartbeat, token/cost, subagent, artifact, approval, and terminal events.
+- Cancelling an `AgentDispatchRun` must cancel the active Agent Mux run/session and mark the current attempt cancelled.
+- Rerun-from-step or rerun-after-fix must create new `Pipeline` resources or external workflow attempts and link them to the agent dispatch.
+
+## Approval and write-back requirements
+
+- Diagnosis summaries can be posted automatically only when repository policy allows bot comments.
+- Pushing commits, updating PR branches, opening PRs, approving reviews, rerunning privileged workflows, publishing release artifacts, or accessing privileged MCP/tool/secret/network capabilities must require explicit approval unless a repository admin configures a narrower exception.
+- Every write-back records actor, approving user, trigger rule, agent stack snapshot, dispatch attempt, context bundle digest, prompt hash, artifact digest, and target object.
+- Approval UI must show assembled prompt, context labels, stack/tools/MCP/skills/subagents, runner pool, runtime ServiceAccount, runner ServiceAccount, requested Secret/ConfigMap access, requested action, and target branch/PR/check.
+
+## Chat and run view requirements
+
+The run detail page should feel like a CI check page plus an Agent Mux transcript.
+
+Recommended layout:
+
+- Header: repository, source object, task kind, status, agent stack, runner pool, runtime ServiceAccount, runner ServiceAccount, linked check, branch/SHA, approval state.
+- Left panel: PR/check context, failed step, changed files, labels, context labels, logs, artifacts.
+- Center panel: Agent Mux transcript and live event stream.
+- Right panel: attempts, queue timing, runner pod/job, ServiceAccounts, native RBAC, tools/actions, MCP servers, skills, Secret/ConfigMap grants, subagents, approvals, artifacts, write-back controls.
+- Footer/composer: continuation prompt, attach more context, approve/reject action, cancel/retry/resume/fork when supported.
+
+## Observability requirements
+
+- Metrics: queued dispatches, wait latency, duration, cancellation count, approval wait time, token/cost estimate, subagent count, write-back count, failed dispatches, dedupe drops.
+- Events: trigger matched, dispatch skipped, context assembled, approval requested, run queued, run started, subagent started/completed, artifact produced, write-back requested, write-back completed.
+- Logs: Agent Mux gateway calls, runner scheduling decisions, ServiceAccount selection, RBAC admission decisions, Secret/ConfigMap grant decisions, context redaction decisions, webhook/CI event correlation IDs, MCP health checks.
+
+## Acceptance criteria
+
+- A failed PR check can create a linked agent diagnosis run with bounded logs, artifact references, and selected `AgentStack` snapshot.
+- A maintainer can dispatch an agent from a PR comment or label and see resolved prompt/context/tools/subagents before privileged work starts.
+- Fork PR agent runs are forced onto untrusted runner pools, unprivileged ServiceAccounts, and cannot receive privileged secrets.
+- A repair attempt can produce a patch artifact without automatically pushing it.
+- A human approval can convert an approved patch artifact into a branch update, PR comment, review, or workflow rerun.
+- Agent run detail streams transcript/events and links back to source PR, check, pipeline, job, workspace, session, and artifacts.
+- Repeated CI failures are deduped by source object, commit SHA, failed job/step, failure signature, context digest, and rule.

package/docs/agents/context-assembly-spec.md

@@ -0,0 +1,219 @@
+# Agent context assembly and prompt safety spec
+
+## Purpose
+
+Agent dispatch is only safe if Krate can explain exactly what context entered the prompt and launch options. This document defines how to assemble `AgentContextBundle` resources from repository pages, CI events, issues, PRs, artifacts, context labels, skills, tools, and user prompts.
+
+It is grounded in the current Krate UI structure: repository routes already provide Code, Issues, Pull Requests, Runs, Hooks, and Settings surfaces, and `ui-shell.jsx` exposes YAML plan panels for advanced resource visibility.
+
+## Context assembly principles
+
+- Context is a durable resource, not a transient UI string.
+- Every prompt fragment must have provenance.
+- Context labels are reviewed prompt fragments, not hidden commands.
+- Secret values are never included in prompt, preview, transcript, artifact, or audit records.
+- Redaction happens before the bundle is snapshotted.
+- Retries should use the original context snapshot unless the user explicitly refreshes it.
+- Prompt preview must show all included sources, labels, skills, and attachments before dispatch.
+
+## `AgentContextBundle` schema
+
+Important fields:
+
+```yaml
+spec:
+  dispatchRun: adr-01hx
+  sourceRefs:
+    repository: krate
+    pullRequest: krate/42
+    pipeline: pipeline-01hx
+    job: job-01hx-test
+    issue: krate/91
+    path: docs/agents
+  prompt:
+    user: string
+    renderedSystemDigest: sha256:...
+    renderedDeveloperDigest: sha256:...
+    renderedTaskDigest: sha256:...
+  contextLabels:
+    - name: ci-failure-summary
+      generation: 4
+      digest: sha256:...
+  sources:
+    - kind: repository-file
+      ref: refs/heads/staging
+      path: docs/agents/README.md
+      digest: sha256:...
+    - kind: pipeline-log
+      name: job-01hx-test
+      redactionStatus: redacted
+  attachments:
+    - kind: log-excerpt
+      artifactRef: artifact-01hx-log
+      digest: sha256:...
+  redactions:
+    - kind: secret-pattern
+      count: 3
+      replacement: "[REDACTED:secret]"
+  limits:
+    maxBytes: 750000
+    truncated: false
+status:
+  phase: Ready
+  digest: sha256:...
+  conditions: []
+```
+
+## Context sources by route
+
+| Route/surface | Default context | Optional context |
+| --- | --- | --- |
+| `/orgs/[org]/repositories/[repo]/code` | repo, branch/ref, selected path, file metadata, repository instructions | selected file contents, recent commits, workspace state |
+| `/orgs/[org]/repositories/[repo]/issues` | issue title/body/labels/comments, context labels, linked workspace/session/runs | child issues, related PRs, artifacts |
+| `/orgs/[org]/repositories/[repo]/pull-requests` | PR title/body, source/target branch, changed files, checks, review state | diff hunks, comments, previous agent artifacts |
+| `/orgs/[org]/repositories/[repo]/runs` | pipeline/job status, failed step, runner pool, logs, artifacts | similar failures, rerun history, cache metadata |
+| `/orgs/[org]/repositories/[repo]/hooks` | webhook delivery, headers metadata, event type, matched rule | replay history, dedupe/coalescing records |
+| `/agents/rules` dry-run | sample event, matched rule, rendered prompt, permission review | fixture payloads, expected dedupe key |
+| `/agents/runs/[run]` continuation | previous context digest, transcript summary, current artifacts | new user-provided context, selected files/logs |
+
+## Prompt layers
+
+Krate should render prompt layers separately:
+
+1. stack system prompt;
+2. stack developer prompt;
+3. skill prompt fragments;
+4. context label prompt fragments;
+5. trigger prompt template;
+6. user task prompt;
+7. bounded source summaries and attachments.
+
+Each layer gets a digest and provenance entry. The UI can show rendered text where safe, but large attachments should show summaries and digests.
+
+## Redaction policy
+
+Redaction happens in this order:
+
+1. explicit Secret/ConfigMap deny list from permission review;
+2. known secret key names and token patterns;
+3. provider credentials and OAuth tokens;
+4. private keys and kubeconfigs;
+5. webhook signatures and auth headers;
+6. repository policy-defined patterns;
+7. user-specified redaction patterns.
+
+Redaction output records counts and categories, not raw values.
+
+## Size and truncation policy
+
+Default limits:
+
+- prompt text: 64 KiB;
+- log excerpts: 256 KiB per job;
+- diff context: 256 KiB;
+- total bundle: 750 KiB for standard dispatch;
+- max attachment count: 32.
+
+When truncation happens:
+
+- mark `limits.truncated=true`;
+- include what was omitted and why;
+- prefer keeping first actionable error, changed-file summary, and source breadcrumbs;
+- allow user to attach more context explicitly from the run detail page.
+
+## Context label safety
+
+`AgentContextLabel` must include:
+
+- reviewed prompt fragment;
+- allowed source types;
+- owner/reviewer metadata;
+- generation and digest;
+- allowed stacks or repositories;
+- unsafe phrase/pattern validation status.
+
+Labels cannot:
+
+- reference Secret values;
+- grant tools or permissions;
+- change approval mode;
+- override runner pool or ServiceAccount;
+- hide prompt text from preview.
+
+## Context bundle lifecycle
+
+1. User or trigger proposes context.
+2. Context assembler resolves sources and permissions.
+3. Redactor removes sensitive values.
+4. Bundle digest is computed.
+5. Permission review digest is attached.
+6. Bundle is snapshotted before dispatch attempt creation.
+7. Retry uses the same bundle unless user selects refresh.
+8. Refreshed context creates a new digest and attempt reason.
+
+## UI requirements
+
+The dispatch composer and run detail page must show:
+
+- source refs and route origin;
+- selected stack and prompt layers;
+- context labels and generation/digest;
+- attachments and truncation state;
+- redaction summary;
+- permission review summary;
+- final context digest.
+
+Denied or warning states:
+
+- source unavailable;
+- attachment too large;
+- redaction failed;
+- context label drifted;
+- selected label not allowed for route/source;
+- prompt template field missing;
+- refreshed context differs from original run.
+
+## Controller responsibilities
+
+Future file:
+
+- `src/agent-context-bundles.js`
+
+Responsibilities:
+
+- collect sources from Krate resources;
+- render prompt layers;
+- redact sensitive values;
+- produce digest and manifest;
+- write `AgentContextBundle` metadata and object storage attachments;
+- expose preview for UI without launching an agent.
+
+## Acceptance criteria
+
+- A dispatch can be recreated from context bundle metadata without secret values.
+- Prompt preview shows every injected context label and skill fragment.
+- A missing or drifted context label blocks dispatch or retry according to policy.
+- Large logs are truncated with visible explanation.
+- Redaction failures fail closed.
+- Context bundle digest appears on dispatch run, attempt, approval, artifacts, and audit events.
+
+## Company brain memory sources
+
+`AgentContextBundle` must support company brain memory as a dedicated source family. Memory sources include Atlas-style graph YAML records, Markdown records with YAML frontmatter, free-form Markdown grep excerpts, ontology reports, and generated indexes tied to a Git commit.
+
+Required memory fields inside a bundle:
+
+```yaml
+memory:
+  repositoryRef: org-company-brain
+  requestedRef: main
+  resolvedCommit: abcdef1234567890
+  snapshotRef: memory-snapshot-01hx
+  queryManifestDigest: sha256:...
+  ontologyDigest: sha256:...
+  indexDigest: sha256:...
+  selectedRecordsDigest: sha256:...
+  selectedExcerptsDigest: sha256:...
+```
+
+A retry uses the original memory snapshot unless the user explicitly refreshes memory. A dispatch may also specify `refAt` to run with memory from a prior timestamp; Krate resolves that timestamp to the latest approved commit at or before it and records both the historical commit and the current commit for diff warnings.

package/docs/agents/controller-reconciliation-spec.md

@@ -0,0 +1,255 @@
+# Agent controller reconciliation spec
+
+## Purpose
+
+This document defines the controller loops needed for agent orchestration. It is grounded in the current Krate implementation:
+
+- `src/api-controller.js` is an HTTP/application facade and should not own long-running reconciliation loops.
+- `src/kubernetes-controller.js` already models list/get/apply/delete/watch over Kubernetes-style resources.
+- `src/controller-ui.js` converts controller snapshots into UI-friendly view models.
+- `apps/web/app/api/watch/[[...resource]]/route.js` streams org-scoped Krate live events as SSE.
+
+Agent implementation should add focused controllers and keep UI/API handlers thin.
+
+## Controller architecture
+
+| Controller | Watches | Writes | Purpose |
+| --- | --- | --- | --- |
+| `agent-stack-controller` | stack/tool/MCP/skill/subagent/context/rbac/grant resources | stack status, capability requirements | Validate stack readiness. |
+| `agent-rbac-controller` | users, teams, RepositoryPermission, AgentServiceAccount, AgentRoleBinding, native RBAC | native ServiceAccounts/Roles/RoleBindings, status | Sync Kubernetes identity/RBAC intent. |
+| `agent-secret-config-controller` | Secret, ConfigMap, grants, capabilities | grant status, requirement status | Validate secret/config access and drift. |
+| `agent-trigger-controller` | WebhookDelivery, Pipeline, Job, Issue, PullRequest, AgentTriggerRule | AgentTriggerExecution, AgentDispatchRun | Match events and create runs. |
+| `agent-dispatch-controller` | AgentDispatchRun, AgentDispatchAttempt | attempts, sessions, artifacts, approvals, status | Launch/reconcile Agent Mux runs. |
+| `agent-workspace-controller` | AgentWorkspacePolicy, AgentWorkspace, work-item links | workspace status, links | Manage worktrees/runtime state. |
+| `agent-approval-controller` | AgentApproval, artifacts, write-back requests | approval status, repository/PR/check writes | Gate privileged actions. |
+| `agent-ui-projection-controller` | all agent resources | controller-ui model additions | Build efficient route view models. |
+
+## Shared reconciliation rules
+
+- Reconcile by desired resource state and observed external state, not by UI events.
+- Use `metadata.generation` and `status.observedGeneration` to avoid stale status updates.
+- Every external side effect needs an idempotency key.
+- Controllers must tolerate restart, duplicate events, partial Agent Mux outages, and Kubernetes watch reconnects.
+- Conditions should explain every blocked UI action.
+- Secret values must never be copied into status, audit events, logs, or prompt previews.
+
+## Idempotency keys
+
+| Side effect | Key |
+| --- | --- |
+| Trigger execution | source event UID + rule generation + dedupe key |
+| Dispatch run creation | trigger execution UID or manual dispatch request UID |
+| Attempt creation | dispatch run UID + attempt number + reason |
+| Agent Mux launch | attempt UID + stack snapshot digest + context digest |
+| Workspace provision | workspace policy + repo + ref + work item + attempt UID |
+| Approval request | attempt UID + action type + target + artifact digest |
+| Write-back | approval UID + artifact digest + target object |
+| Native RBAC sync | AgentRoleBinding UID + roleRef + subject + scope |
+| Secret/config grant review | grant UID + target metadata version + subject |
+
+## `agent-stack-controller`
+
+Inputs:
+
+- `AgentStack`, `AgentToolProfile`, `AgentMcpServer`, `AgentSkill`, `AgentSubagent`, `AgentContextLabel`.
+- `AgentServiceAccount`, `AgentRoleBinding`, `AgentSecretGrant`, `AgentConfigGrant`.
+- Agent Mux capability manifests.
+
+Reconcile steps:
+
+1. Load stack and referenced config resources.
+2. Query Agent Mux capabilities for adapter/model/session/tool support.
+3. Compute `AgentCapabilityRequirement` for tools, MCP, skills, subagents, model provider, and runtime.
+4. Call permission review for ServiceAccount/RBAC/Secret/Config access.
+5. Probe MCP health where required.
+6. Set readiness conditions and warnings.
+7. Emit UI projection hints for stack builder.
+
+Outputs:
+
+- `AgentStack.status.conditions`.
+- `AgentCapabilityRequirement` records.
+- Audit events for readiness transitions when they affect dispatch admission.
+
+## `agent-rbac-controller`
+
+Inputs:
+
+- `User`, `Team`, `IdentityMapping`, `RepositoryPermission`.
+- `AgentServiceAccount`, `AgentRoleBinding`.
+- Native Kubernetes `ServiceAccount`, `Role`, `ClusterRole`, `RoleBinding`, `ClusterRoleBinding`.
+
+Reconcile steps:
+
+1. Resolve Krate subject into Kubernetes user/group/ServiceAccount.
+2. Determine whether Krate owns or imports the native object.
+3. Run bind/escalate checks for requested role changes.
+4. Apply or update owned native RBAC objects.
+5. Detect drift and set conditions.
+6. Notify stack controller when dependent identity or roles changed.
+
+Failure handling:
+
+- Missing subject: `SubjectsResolved=False`.
+- Escalation denied: `EscalationAdmitted=False` and no native apply.
+- Drift on owned privileged role: block dependent dispatches until resolved.
+
+## `agent-secret-config-controller`
+
+Inputs:
+
+- Native `Secret` and `ConfigMap` metadata.
+- `AgentSecretGrant`, `AgentConfigGrant`.
+- `AgentCapabilityRequirement`.
+- `AgentDispatchAttempt` for active snapshots.
+
+Reconcile steps:
+
+1. Check target Secret/ConfigMap existence and requested key names.
+2. Check native RBAC visibility for metadata and apply policy for sensitive ConfigMap keys.
+3. Match grants to capability requirements.
+4. Mark stale grants when target metadata version changes.
+5. Update affected stack readiness and active dispatch warnings.
+
+Failure handling:
+
+- Secret value unavailable to controller: acceptable; values are not required for metadata validation.
+- Secret missing: block new dispatch and mark active snapshots stale.
+- Key removed: block retry/resume and show affected consumers.
+
+## `agent-trigger-controller`
+
+Inputs:
+
+- `WebhookDelivery`, `Pipeline`, `Job`, `Issue`, `PullRequest`, labels, comments, schedules, manual dispatch requests.
+- `AgentTriggerRule`.
+
+Reconcile steps:
+
+1. Normalize event into a trigger payload.
+2. Persist `AgentTriggerExecution` before dispatch.
+3. Evaluate lifecycle, matcher, actor, repository/ref trust, dedupe, and concurrency.
+4. Build context bundle plan and run permission review.
+5. Create `AgentDispatchRun` when admitted.
+6. Mark execution as created, coalesced, rejected, or waiting for approval.
+
+Outputs:
+
+- `AgentTriggerExecution`.
+- `AgentDispatchRun` and initial source breadcrumbs.
+
+## `agent-dispatch-controller`
+
+Inputs:
+
+- `AgentDispatchRun`, `AgentDispatchAttempt`, `AgentContextBundle`, permission snapshots.
+- Agent Mux gateway/client.
+
+Reconcile steps:
+
+1. Create initial or retry attempt.
+2. Materialize immutable stack/context/permission snapshots.
+3. Select runner/external gateway and workspace.
+4. Launch Agent Mux run/session with admitted tools, secrets, configs, and runtime identity references.
+5. Persist Agent Mux run/session IDs.
+6. Reconcile event stream into status, artifact, approval, cost, and subagent records.
+7. Transition run to terminal state or waiting state.
+
+Failure handling:
+
+- Agent Mux unavailable: retry with backoff while attempt remains queued/starting.
+- Session binding pending: set `AgentMuxSessionBound=False` with pending reason.
+- Adapter rejects launch options: fail attempt and keep permission snapshot for diagnosis.
+
+## `agent-workspace-controller`
+
+Inputs:
+
+- `AgentWorkspacePolicy`, `AgentWorkspace`, `WorkItemWorkspaceLink`, dispatch attempts.
+
+Reconcile steps:
+
+1. Decide workspace mode from policy and trust tier.
+2. Provision/link worktree when needed.
+3. Record branch, head, dirty state, ahead/behind, runtime URLs, and missing path state.
+4. Handle pin, archive, cleanup, recover, notes, and rebase actions.
+5. Link workspace to issue/PR/run/session.
+
+## `agent-approval-controller`
+
+Inputs:
+
+- `AgentApproval`, write-back requests, artifacts, dispatch attempts.
+
+Reconcile steps:
+
+1. Validate approver identity and native RBAC.
+2. Validate approval still matches current artifact digest and target object.
+3. Apply approved action idempotently.
+4. Write audit event and update approval/run status.
+
+## UI projection integration
+
+`src/controller-ui.js` should add an `agents` view model with:
+
+- stack readiness counters;
+- active dispatches and pending approvals;
+- missing permission warnings;
+- repository-scoped agent affordances for code/issues/PRs/runs/settings;
+- watch resource names for `LiveWatchPanel`.
+
+The existing app can initially expose agent resources through advanced resource tables, then add typed pages once controllers exist.
+
+## Memory controller responsibilities
+
+The memory controller reconciles the company brain control plane:
+
+- watches `AgentMemoryRepository`, validates reachability, default branch, layout, and index freshness;
+- watches `AgentMemorySource`, computes allowed path/kind scopes, and projects missing grants into `AgentCapabilityRequirement`;
+- resolves current, explicit, snapshot-tag, and `refAt` memory refs for dispatch admission;
+- creates `AgentMemorySnapshot` and `AgentMemoryQuery` records during context assembly;
+- validates `AgentMemoryUpdate` patches, opens review branches/PRs when allowed, and records approval/merge status;
+- updates `AgentMemoryOntology` status from parser, graph, frontmatter, edge, owner, and secret-scan validators;
+- preserves historical snapshots even when memory sources or repositories are later disabled.
+
+## Org-scoped controller reconciliation
+
+Every controller reconciliation starts by resolving `organizationRef` and namespace. Controllers may cache cluster-wide watches, but each side effect must be namespaced to the owning org. Agent, memory, runner, trigger, deployment, repository, and secret/config controllers reject cross-org references unless an explicit sharing policy exists.
+
+The memory controller also reconciles `AgentRunMemoryImport` records by reading admitted `.a5c` run/session/journal metadata, redacting it, normalizing it into the org memory repository, and linking imported records to the source `AgentDispatchRun` or Babysitter run ID.
+
+## Org admission and memory import reconciler pseudocode
+
+Org admission should run as a shared preflight:
+
+```text
+resolveOrg(resource)
+assertNamespaceMatchesOrg(resource.namespace, org.namespace)
+assertOrgLabels(resource.metadata.labels, org)
+for ref in resource.spec.refs:
+  assertSameOrg(ref, org) or assertSharingPolicy(ref, org)
+assertKubernetesRbac(actor, org.namespace, verb, resource)
+assertKratePermission(actor, org, action)
+emitAuditPreflight(actor, org, resource, action)
+```
+
+`AgentRunMemoryImport` reconciliation:
+
+```text
+resolve import org and source run
+verify source repository/session/run belongs to org
+collect admitted MEMORY.md, session, journal, task, artifact metadata
+compute source digests
+redact secrets and unsafe prompt instructions
+normalize to Markdown/YAML memory files
+validate ontology/frontmatter/edges/owners
+open or update memory repo PR
+wait for approval/merge
+record resulting memory commit and indexes
+```
+
+The reconciler must be idempotent by source digest, target path, and import generation.
+
+## Sequence spec reference
+
+The detailed org-memory sequences are defined in [Org memory controller sequence spec](./org-memory-controller-sequence-spec.md). Controller implementation should keep that document as the source of truth for ordering, idempotency keys, status conditions, and cross-org denial behavior.