kandev/docs/plans/task-terminal-git-environment/plan.md

spec, created, status

spec	created	status
docs/specs/integrations/github-authentication.md	2026-07-28	completed

Implementation Plan: Managed Task Terminal Git Environment

Overview

Extend the existing managed GitHub credential contract from agent subprocesses to every authorised task execution surface: local/worktree terminals, remote terminal shells, passthrough-agent PTYs, legacy agentctl shells, and task-scoped command processes. Reuse the current per-execution environment and ownership guards; do not persist, log, or expose the broker contract to the browser.

Backend

Capture and provide the effective execution environment

Files:

• apps/backend/internal/agent/runtime/lifecycle/types.go
• apps/backend/internal/agent/runtime/lifecycle/manager_launch.go
• apps/backend/internal/agent/runtime/lifecycle/manager_execution.go
• apps/backend/internal/agent/runtime/lifecycle/manager_passthrough.go
• apps/backend/internal/gateway/websocket/terminal_handler.go

Changes:

• Keep the already-resolved per-execution environment in memory on AgentExecution, using a defensive copy and clearing it when the execution is removed.
• Provide the effective environment only to lifecycle-owned, already-authorized terminal/process launch paths; preserve explicit terminal/process overrides as the highest precedence.
• Use it for local/worktree user-shell terminals and passthrough-agent PTYs, including their managed GIT_CONFIG_* block and shim-first PATH.
• Preserve executor inheritance: environments without a broker contract retain their current host/executor behavior and receive no Kandev shim.

Make agentctl shell and command launch surfaces inherit instance environment

Files:

• apps/backend/internal/agentctl/server/process/manager.go
• apps/backend/internal/agentctl/server/process/runner.go
• apps/backend/internal/agentctl/server/process/interactive_shells.go

Changes:

• Merge the instance AgentEnv into the legacy /shell/start shell, per-terminal agentctl shells, and StartProcess command launches before their explicit call-site environment.
• Retain the existing indexed-Git configuration exactly as one ordered block; do not reconstruct or log its individual credential values.
• Make process start fail before spawning when effective-environment preparation cannot satisfy the managed contract, without ambient Git/gh fallback.

Public documentation

Files:

• docs/public/executors.md
• docs/public/developer-tools.md

Changes:

• Document that a terminal opened in a managed task receives the same task-scoped Git/gh routing as its agent, while executor-inheritance mode leaves credentials to the executor.
• State that an already-open terminal keeps its launch environment; open a new terminal after a session resume or credential-policy change.

Frontend

No UI or browser protocol changes are required. Existing terminal ownership checks and terminal routes remain the boundary; the backend supplies the process environment after authorization.

Tests

• What: a local/worktree terminal and a passthrough-agent PTY inherit a managed broker contract, Git helper configuration, and shim-first PATH; executor-inheritance terminals do not gain that shim. Files: apps/backend/internal/agent/runtime/lifecycle/manager_launch_test.go, apps/backend/internal/agent/runtime/lifecycle/manager_passthrough_test.go, and apps/backend/internal/gateway/websocket/terminal_handler_test.go. How: focused Go tests with a synthetic non-secret broker contract and captured PTY start environment; assert authorization fails before environment retrieval.
• What: legacy agentctl shells, per-terminal agentctl shells, and task-scoped command starts inherit AgentEnv, while explicit call-site values override inherited ones. Files: apps/backend/internal/agentctl/server/process/runner_shells_test.go and apps/backend/internal/agentctl/server/process/runner_test.go. How: table-driven environment merge tests and a real short-lived child process that reports only non-secret marker variables.
• What: public documentation remains valid. Files: docs/public/executors.md, docs/public/developer-tools.md. How: node --test scripts/validate-public-docs.test.mjs and node scripts/validate-public-docs.mjs.

E2E Tests

No new Playwright test is planned. The terminal UI and WebSocket contract are unchanged; focused backend tests exercise the authorization boundary and the actual process environments without putting a broker contract into an E2E fixture or browser-visible output.

Implementation Waves

Wave 1:

• Task 01: Runtime terminal environment propagation

Wave 2:

• Task 02: Agentctl shell and process inheritance

Wave 3:

• Task 03: Document and verify terminal Git routing

Execute sequentially in the primary conversation. No task is delegated unless the user explicitly authorizes delegation after choosing the implementation model.

Risks and non-goals

• Broker leases and indexed Git configuration are sensitive runtime data. They must remain in-memory and must not enter terminal metadata, logs, errors, frontend payloads, or command arguments.
• A terminal already owns host-level execution authority for local/worktree tasks; this change aligns its credential behavior with the task agent and is not a sandbox boundary.
• This plan does not grant terminal access across task-environment ownership boundaries, change credential policy selection, persist terminal environments, or support arbitrary host shells.

Open Questions

None.