kandev/docs/plans/executor-host-gh-bridge/task-02-runtime-propagation.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
02-runtime-propagation	Complete runtime propagation	complete	2	01-host-cli-route	plan.md	REQ-INTEGRATIONS-GITHUB-AUTHENTICATION-002	AC-INTEGRATIONS-GITHUB-AUTHENTICATION-002.2 AC-INTEGRATIONS-GITHUB-AUTHENTICATION-002.3 AC-INTEGRATIONS-GITHUB-AUTHENTICATION-002.4 AC-INTEGRATIONS-GITHUB-AUTHENTICATION-002.5 AC-INTEGRATIONS-GITHUB-AUTHENTICATION-002.6 AC-INTEGRATIONS-GITHUB-AUTHENTICATION-002.7	../../specs/integrations/system-design/github-authentication-02.md

Task 02: Complete runtime propagation

Summary

Carry the bridge through each local launch path and the final child environment. Prove that a reused executor or late profile token cannot defeat credential precedence. Compose indexed Git definitions at the strict source-aware boundary and replace stale generated entries at the agentctl configure/start boundary.

In scope

• Cover full launch and configureResumeGitHubCredentials through the shared credential route.
• Extend prepared-workspace configuration with the resolved executor identity and repository set before agent start.
• Reuse preparation's resolved repositories instead of repeating materialization or remote reconciliation.
• Replace obsolete generated entries when the host, token, or policy changes on resume or prepared start.
• Preserve environment delivery errors instead of reporting successful bridge activation after failed delivery.
• Exercise lifecycle profile merges and CollectAgentEnvWithError using the supplied multi-entry host environment.
• Cover the same effective Git environment for agent processes and existing task shell/process consumers.
• Treat complete lifecycle snapshots and request-only configure calls as separate environment contracts.
• Remove obsolete marker-owned entries when a later preparation has no bridge, while preserving user entries.

Out of scope

No new UI, snapshot schema, remote credential forwarding, or unrelated generic environment refactor.

Acceptance

1. Launch, resume, and prepared start each pass with current eligibility and no duplicate indexed entries.
2. Late profile tokens remain the effective credential, and managed broker failure never invokes the host helper.
3. Real Git succeeds through the final environment without Git file changes, including a login shell that replaces PATH.

TDD cases

Add the plan's launch/resume/prepared-workspace and child-environment tests before changing each path. Use a spy host CLI to assert invocation counts and credential source without exposing real secrets. Test logout between preparations, executor-to-managed transition, a newly explicit token, and failed environment delivery. Test the bridge with a successful user helper, a failed managed helper, and a token supplied by a late profile merge. For a failed explicit token, assert that no stored-login retry occurs. Test HOME and GH_CONFIG_DIR overrides so probe/helper account selection stays consistent.

For process-level evidence, use real Git in an isolated home with a fake CLI. Pass inherited and task blocks through the actual agentctl environment collector. Assert unchanged hooks and notes, one generated helper, and no changed Git configuration files. Use an executable path with spaces and a login shell that replaces PATH. Keep platform-specific shell tests explicitly gated, while portable policy and composition tests run everywhere.

Verification

From the repository root:

(cd apps/backend && go test -tags fts5 ./internal/orchestrator/executor -run 'TestExecutorHostGHBridge|TestConfigureGitHubCredentialBroker|TestConfigureGitCredentialBroker' -count=1)
(cd apps/backend && go test -tags fts5 ./internal/agent/runtime/lifecycle -run 'TestBuildEnvForExecutionHostGHBridge|TestMergeEnvFillMissing' -count=1)
(cd apps/backend && go test -tags fts5 ./internal/agentctl/server/config -run 'TestCollectAgentEnv.*(HostGHBridge|GitConfig)' -count=1)
(cd apps/backend && go test -tags fts5 ./internal/agentctl/server/process -run 'Test.*(HostGHBridge|GitEnv)' -count=1)
git diff --check

Files likely touched

• apps/backend/internal/orchestrator/executor/executor_execute.go
• apps/backend/internal/orchestrator/executor/executor_resume.go
• apps/backend/internal/orchestrator/executor/executor_host_gh_bridge_test.go
• apps/backend/internal/agent/runtime/lifecycle/manager_launch_test.go
• apps/backend/internal/agent/runtime/lifecycle/profile_env.go
• apps/backend/internal/agentctl/server/config/config.go
• apps/backend/internal/agentctl/server/config/config_test.go
• apps/backend/internal/agentctl/server/process/workspace_git_env_test.go

Only change runtime composition where the failing boundary tests require it. Read apps/backend/internal/agentctl/AGENTS.md before agentctl implementation.

Dependencies

Task 01.

Risks

Early request maps do not contain every eventual profile variable. Prepared-workspace starts can bypass the full credential route or retain an old generated environment.

Parallelism

sequential

Inputs

• Authentication criteria 002.2 through 002.7 and the design's runtime propagation section.
• configureExistingWorkspace, configureResumeGitHubCredentials, and buildEnvForExecution.
• profile_env.go, CollectAgentEnvWithError, and nearby indexed Git configuration regressions.

Results

• Carried the effective bridge environment through initial launch, resume, and prepared-workspace agent starts.
• Composed agent-profile, executor-profile, managed-runtime, and repository Git blocks at strict resolution, then sent the resulting lifecycle snapshot through agentctl's normal overlay mode. The indexed merge recognizes an already-forwarded snapshot and does not append inherited entries twice.
• Refreshed agent and executor profile credential-store values before the host probe, preserved request precedence, replaced stale marker-owned entries, and returned environment delivery errors.
• The process manager tests verify request-only overlay reconfiguration, complete replacement for callers that own the full indexed block, and invalid-config atomicity. The overlay path preserves user hooks/notes and removes generated helpers when the next request supplies none. Agent, tracker, one-shot, shell, and task processes use the resulting canonical environment.
• TestComposeExecutionRuntimeEnvironmentRemovesObsoleteManagedCredentials verifies lifecycle composition also removes stale ordinary broker variables before forwarding a request-only reconfiguration.
• The lifecycle test verifies that a prepared execution with an existing runtime snapshot sends one composed indexed block through normal Configure. The Kubernetes restart path uses the same overlay contract, and lifecycle spills the environment once.
• TestBuildEnvForExecutionHostGHBridge_ComposesStrictProfileBlocks verifies the production strict resolver composes agent-profile, executor-profile, and managed indexed Git definitions while retaining the supplied entries.
• TestLaunchPreparedSessionProbesEffectiveProfileCredentialStore verifies both profile-directory mismatch directions through the production prepared-session route.
• (cd apps/backend && go test -tags fts5 ./internal/orchestrator/executor -run 'TestExecutorHostGHBridge|TestConfigureGitHubCredentialBroker|TestConfigureGitCredentialBroker' -count=1) passed.
• (cd apps/backend && go test -tags fts5 ./internal/agent/runtime/lifecycle -run 'TestBuildEnvForExecutionHostGHBridge|TestMergeEnvFillMissing' -count=1) passed.
• (cd apps/backend && go test -tags fts5 ./internal/agentctl/server/config -run 'TestCollectAgentEnv.*(HostGHBridge|GitConfig)' -count=1) passed.
• (cd apps/backend && go test -tags fts5 ./internal/agentctl/server/process -run 'Test.*(HostGHBridge|GitEnv)' -count=1) passed.
• The final affected-package run passed with -count=1 for the executor, lifecycle, agentctl client/API/config/process, backendapp, environment, and gitconfigenv packages.
• make -C apps/backend lint passed with zero issues on the final tree.
• make -C apps/backend build passed.
• git diff --check passed.