docs: propose credential lifecycle and GitHub App access

rfcs/0027/baseline-and-proposal.dot

@@ -0,0 +1,50 @@
+digraph BaselineAndProposal {
+  graph [rankdir=TB, bgcolor="white", pad="0.18", nodesep="0.36", ranksep="0.32", splines=polyline, fontname="Arial", fontsize=12];
+  node [shape=box, style="rounded,filled", fontname="Arial", fontsize=13, fontcolor="#24323B", color="#82949D", penwidth=1.1, margin="0.16,0.12"];
+  edge [fontname="Arial", fontsize=10, fontcolor="#425963", color="#6B818A", penwidth=1.2, arrowsize=0.7];
+
+  subgraph cluster_current_credentials {
+    label="EXISTING / Provider-managed model token, dedicated Codex\nThe separate Agent messaging gateway receives neither value.";
+    labelloc=t; labeljust=l; style=rounded; color="#BDCBD1"; fontcolor="#425963"; margin=16;
+    issue [label="ServiceAccountDriver\nIssue model token", fillcolor="#EFF3F6"];
+    compute [label="API-side Compute\nStore credential", fillcolor="#EFF3F6"];
+    secret [label="Account Secret\nToken + workspace ID", fillcolor="#EFF3F6"];
+    codex [label="Dedicated Codex\nReceive token +\nworkspace ID", fillcolor="#EFF3F6"];
+    { rank=same; issue; compute; secret; codex; }
+    issue -> compute -> secret -> codex;
+  }
+
+  subgraph cluster_proposed_credentials {
+    label="ADDITION / Proposed managed GitHub profile\nCurrent OCC authority is required for every GitHub dispatch; the existing model-credential path remains.";
+    labelloc=t; labeljust=l; style=rounded; color="#9FBFB6"; fontcolor="#355F54"; margin=16;
+    agent [label="Agent execution\nNo GitHub token", fillcolor="#E9F3F1", color="#578D82"];
+    connector [label="Trusted connector\nVerify execution + Work", fillcolor="#E9F3F1", color="#578D82"];
+    broker [label="CredentialGatewayDriver\n(proposed)\nBroker + mediator", fillcolor="#E9F3F1", color="#578D82"];
+    github [label="GitHub\nScoped request", fillcolor="#E9F3F1", color="#578D82"];
+    { rank=same; agent; connector; broker; github; }
+    agent -> connector -> broker -> github;
+  }
+
+  subgraph cluster_current_cutover {
+    label="EXISTING / Ordinary Kubernetes reconciliation: source call order\nActivation and a Recreate gateway rollout do not establish the full observed-stop contract below.";
+    labelloc=t; labeljust=l; style=rounded; color="#BDCBD1"; fontcolor="#425963"; margin=16;
+    select [label="Commit successor\nas active revision", fillcolor="#EFF3F6"];
+    activate [label="Request successor\nactivation", fillcolor="#EFF3F6"];
+    retire [label="Request predecessor\nretirement", fillcolor="#EFF3F6"];
+    { rank=same; select; activate; retire; }
+    select -> activate -> retire;
+  }
+
+  subgraph cluster_required_cutover {
+    label="REQUIRED / RFC 0027 activation order, specified by RFC 0037\nObserved predecessor termination gates successor execution and shared writes; serving has an availability gap.";
+    labelloc=t; labeljust=l; style=rounded; color="#A9BCD0"; fontcolor="#426381"; margin=16;
+    prepare [label="Isolated candidate\nExecution disabled", fillcolor="#EAF1F8", color="#6489B0"];
+    stop [label="Observe predecessor\nHarness + writers stopped\nResolve uncertain creates", fillcolor="#EAF1F8", color="#6489B0"];
+    permit [label="Select successor\nPermit execution", fillcolor="#EAF1F8", color="#6489B0"];
+    route [label="Enable routing\nafter readiness", fillcolor="#EAF1F8", color="#6489B0"];
+    { rank=same; prepare; stop; permit; route; }
+    prepare -> stop -> permit -> route;
+  }
+
+  issue -> agent -> select -> prepare [style=invis];
+}

rfcs/0027/runtime-access-overview.dot

@@ -0,0 +1,12 @@
+digraph RuntimeAccessOverview {
+  graph [rankdir=LR, bgcolor="white", pad="0.18", nodesep="0.28", ranksep="0.38", splines=spline, fontname="Arial", fontsize=11];
+  node [shape=box, style="rounded,filled", fontname="Arial", fontsize=12, fontcolor="#24323B", color="#82949D", penwidth=1.1, margin="0.16,0.12"];
+  edge [fontname="Arial", fontsize=10, fontcolor="#425963", color="#6B818A", penwidth=1.2, arrowsize=0.7];
+
+  reads [label="A: Managed reads\nMetadata, clone, fetch\nMinimal internal Work + operations", fillcolor="#E9F3F1", color="#578D82"];
+  publish [label="B: Coding + publication\nHuman Approve and publish\nExact candidate + separate effects", fillcolor="#EAF1F8", color="#6489B0"];
+  lifecycle [label="C: Broader durable Work + children\nStop task / Stop Agent / Start Agent\nQualify broader lifecycle behavior", fillcolor="#F7EDEE", color="#B7858B"];
+
+  reads -> publish;
+  publish -> lifecycle;
+}

rfcs/0027/runtime-access-overview.md

@@ -0,0 +1,53 @@
+# Enterprise runtime and access: RFC series
+
+This informational guide connects four **draft** proposals under accepted [RFC 0027](../0027-openclaw-enterprise.md). Each draft owns its requirements; this guide adds no authority, resource, or acceptance decision.
+
+## Four owners
+
+| Proposal | Owns |
+| --- | --- |
+| [0036: work authority](https://github.com/openclaw/rfcs/pull/70) | Service-owned logical work, immutable scope and selected duration policy, child admission, and delivery authority. |
+| [0035: identity and enforcement](https://github.com/openclaw/rfcs/pull/69) | Authenticated identity, execution assignment, bounded enforcement leases, and withdrawal. |
+| [0034: credentials and GitHub](https://github.com/openclaw/rfcs/pull/68) | Credential issuance, protected custody, mediated use, and cleanup. |
+| [0037: runtime and delivery](https://github.com/openclaw/rfcs/pull/71) | Stop/resume, bounded drain, writer exclusion, completed-state recovery, and completed-result delivery. |
+
+## Changes from the merged implementation
+
+The comparison below is anchored to merged source `3eeacb8`. The named profiles have different credential and runtime boundaries.
+
+| Boundary | Existing implementation | Addition or required change |
+| --- | --- | --- |
+| Identity and configuration | An [Agent-associated ServicePrincipal and revision selections](https://github.com/openclaw/openclaw-enterprise/blob/3eeacb85d9e8e087bc3e74d792778e4ef3123412/packages/contracts/src/index.ts#L309) for Provider and ServiceAccount. | 0035 binds authenticated execution to work authority. 0034 adds the proposed `repositoryAccess` selection and `credential_gateway` capability. |
+| Credentials | [Provider-managed model tokens](https://github.com/openclaw/openclaw-enterprise/blob/3eeacb85d9e8e087bc3e74d792778e4ef3123412/docs/reference/service-accounts.md#L85) reach dedicated Codex through Compute's account Secret. Ordinary [SecretDriver bindings](https://github.com/openclaw/openclaw-enterprise/blob/3eeacb85d9e8e087bc3e74d792778e4ef3123412/docs/flows/secret-storage-and-delivery.md#L113) reach the consuming gateway environment. | 0034 adds mediated GitHub access with protected tokens and current OCC authority per dispatch. Existing model and ServiceAccount credential paths remain. |
+| Replacement | The [ordinary Kubernetes controller](https://github.com/openclaw/openclaw-enterprise/blob/3eeacb85d9e8e087bc3e74d792778e4ef3123412/apps/controller/src/worker.ts#L987) selects and requests successor activation before requesting predecessor retirement. | 0037 requires observed predecessor termination before successor execution or shared writes, preserving RFC 0027's order and accepting an availability gap. |
+
+![Existing dedicated-Codex credential delivery and ordinary Kubernetes call order, compared with additive GitHub mediation and the required observed-stop handoff.](baseline-and-proposal.png)
+
+The messaging gateway remains Agent-owned, provisioned by Compute, and separate from the proposed credential gateway. In dedicated Codex, it receives neither managed account token nor workspace ID. Current [activation](https://github.com/openclaw/openclaw-enterprise/blob/3eeacb85d9e8e087bc3e74d792778e4ef3123412/apps/controller/src/drivers/compute/kubernetes/index.ts#L1647) and [retirement](https://github.com/openclaw/openclaw-enterprise/blob/3eeacb85d9e8e087bc3e74d792778e4ef3123412/apps/controller/src/drivers/compute/kubernetes/index.ts#L1817) calls do not establish the full observed-stop contract; their order alone does not prove concurrent writers.
+
+## Delivery stages
+
+![Stage A delivers managed reads, clone and fetch with minimal internal work authority. Stage B adds coding and explicit human Approve and publish. Stage C adds broader durable work and children plus Stop task, Stop Agent and Start Agent.](runtime-access-overview.png)
+
+| Stage | User-visible behavior | Required boundary |
+| --- | --- | --- |
+| **A: read** | Managed repository metadata, clone, and fetch. | Current authorization for each dispatch, protected credentials, and minimal internal Work and operation records. A standalone root Work may qualify first; same-scope subordinate helpers join only after their attribution and cancellation are qualified. |
+| **B: code and publish** | Coding plus explicit human **Approve and publish** for an exact frozen candidate. | Any configured, authorized human may approve, including the requester. The Agent cannot approve its own candidate; absent approval policy denies publication. |
+| **C: durable work and controls** | Broader durable Work and children, **Stop task**, **Stop Agent**, and **Start Agent**. | Qualify the broader work and lifecycle contracts; this stage does not add advanced scheduling or a task-database design. |
+
+Later publication modes may require an independent human **or** use an explicitly scoped automatic authorization policy. These are alternative modes, both bound to the exact candidate and current policy; automatic authorization does not also require per-operation human approval. Missing policy never selects a fallback. See [repository configuration](../0034/repository-configuration.md).
+
+## One operation
+
+1. **Admit.** OCC checks the requester's invocation permission and the service's own access separately. Minimal internal records bind root Work, immutable scope, selected duration policy, execution, and operation identity. Execution defaults to uncapped unless admission selects a finite limit; missing policy is not an uncapped selection. Qualified helpers remain subordinate to the same root's scope and cancellation. Broader durable-child behavior is later scope (0035/0036).
+2. **Dispatch and renew.** The trusted connector proves its identity and execution/Work binding. The proposed `CredentialGatewayDriver`, selected by the Installation, obtains online OCC authority for every GitHub dispatch and keeps tokens outside Agent execution (0034). It is separate from the Agent messaging gateway; broker and mediator may share a trusted service. Each enforcement lease and operation deadline is finite. Renewal respects every configured Work, attempt, and ancestor limit; certificate or token rotation extends none of them. Stage B also records approval and push/PR effects separately.
+3. **Stop or complete.** A completed model turn does not close logical Work. Cancellation and security revocation withdraw affected authority from the first supported profile. Stage C adds the broader user controls, bounded graceful drain, and separately admitted delivery of an already completed result to its exact audience; cancellation or security revocation also withdraws affected delivery (0036/0037).
+4. **Replace and clean up.** Changed permissions require a fresh isolation boundary; the selected Kubernetes/gVisor profile uses a fresh Pod and sandbox. Compute proves predecessor termination before shared writable replacement. When separately selected, recovery restores supported completed state; active-session migration and replay remain later scope (0037). Closed Work and uncertain effects cannot be revived or replayed. Credential cleanup survives Work closure and Agent deletion under retained platform authority (0034).
+
+## Acceptance boundary
+
+RFC 0027's accepted baseline denies operations when authorization is unavailable. The first GitHub profile retains that behavior, including reads and credential maintenance; previously fetched local files are a separate boundary. The broader authority drafts retain an optional **explicit amendment** for separately selected, qualified reads under existing unexpired enforcement leases, with all required local evidence intact. Writes, authority renewal, admission, and new assignment still require current authority. That amendment remains unaccepted and is not an initial GitHub release gate.
+
+Review shared contracts together and accept RFCs separately under the [repository lifecycle](../../README.md#rfc-lifecycle). Stages A and B need the relevant minimal identity, Work, operation, cancellation, and credential contracts; they do not wait for all of Stage C. Selecting SPIFFE for a connector does not select it for every Agent.
+
+Acceptance does not qualify a production runtime. Each owner retains its mechanism and integration gates, including protected Work attribution, measured withdrawal, recovery compatibility, and mediated provider access. Initial profiles name the helper/child and recovery subset they support. Component checks and explicitly substituted external interfaces support bounded source evidence; runtime and provider claims require the corresponding live evidence.