Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
9df387e
Add Docker-backed application runtime
kfiramar Jul 10, 2026
876dda8
Prefer dev for pull request bases
kfiramar Jul 10, 2026
9ba7711
fix: serialize startup and guard bulk actions
kfiramar Jul 10, 2026
0c5e8c7
Consolidate PR preview controller ownership
kfiramar Jul 10, 2026
ba5e8e8
Remove obsolete planning selection state and dead compatibility code
kfiramar Jul 10, 2026
6b5d749
Harden multi-target action selection and execution
kfiramar Jul 10, 2026
9e79778
Remove plan-agent workflow compatibility hub
kfiramar Jul 10, 2026
e546a81
Deeply harden runtime state and lifecycle ownership
kfiramar Jul 11, 2026
03e9146
Restore legacy pointer migration into scoped state registry
kfiramar Jul 11, 2026
ce242f3
Make resume fallback tests PID-independent
kfiramar Jul 11, 2026
72cec8a
Prevent missing-interpreter startup failures
kfiramar Jul 11, 2026
cd20552
Reconcile same-head previews and honor readiness
kfiramar Jul 11, 2026
4071b18
fix review findings in runtime lifecycle hardening
kfiramar Jul 11, 2026
6913f7d
fix config-only service target resolution
kfiramar Jul 11, 2026
7d80787
fix Docker runtime review findings
kfiramar Jul 11, 2026
cd08020
fix linked worktree action targeting
kfiramar Jul 11, 2026
728cb44
preserve aggregate untested test scope
kfiramar Jul 11, 2026
593e35a
fix second-round Docker runtime review findings
kfiramar Jul 11, 2026
7095217
keep untested runner within architecture budget
kfiramar Jul 11, 2026
ce794fa
fix scoped lifecycle and state review findings
kfiramar Jul 11, 2026
5883f63
fix review edge cases in test targeting and menu cleanup
kfiramar Jul 11, 2026
8e3b134
fix final Docker runtime review edge cases
kfiramar Jul 11, 2026
489c3c8
Merge PR #336: consolidate preview controller ownership
kfiramar Jul 11, 2026
b4b24e7
Merge PR #337: harden action and workflow execution
kfiramar Jul 11, 2026
45b3100
reconcile runtime refactor and harden deleted-file shipping
kfiramar Jul 11, 2026
2a793d1
Merge PR #341: harden runtime state and lifecycle ownership
kfiramar Jul 11, 2026
fb34adc
reconcile Docker runtime with consolidated lifecycle
kfiramar Jul 11, 2026
aa1e72d
Merge PR #335: add Docker-backed application runtime
kfiramar Jul 11, 2026
98ca67d
enable contributor CI and guidance for dev
kfiramar Jul 11, 2026
d23a38c
tolerate transient empty GitHub check rollups
kfiramar Jul 11, 2026
50c688c
allow full CI three minutes to finish
kfiramar Jul 11, 2026
7194164
Consolidate open PRs and harden runtime lifecycle ownership
kfiramar Jul 12, 2026
2796a6e
Merge consolidated envctl hardening into dev (#342)
kfiramar Jul 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
name: Tests

# Runs the canonical contributor validation lane on every PR targeting `main`.
# Runs the canonical contributor validation lane on every PR targeting `dev` or `main`.
# The lane matches `docs/developer/contributing.md`:
#
# uv run --extra dev pytest -q
Expand All @@ -9,12 +9,12 @@ name: Tests
#
# `pull_request` already fires on PR open, reopen, and every push to the head
# branch (the `synchronize` event), so a separate `push` trigger would just
# double the runs. Post-merge work on `main` is handled by `release.yml`.
# double the runs. Release publishing from `main` is handled explicitly by `release.yml`.
#
# Jobs run in parallel:
# - pytest: the slow lane
# - package: python -m build + release shipability gate
# - lint: ruff (non-blocking until main is green)
# - lint: ruff (non-blocking until the lint baseline is green)
#
# All three restore uv's cache through GitHub's official cache action keyed by
# uv.lock so dependency installs reuse already-downloaded wheels without relying
Expand All @@ -31,6 +31,7 @@ name: Tests
on:
pull_request:
branches:
- dev
- main

permissions:
Expand Down
6 changes: 3 additions & 3 deletions contracts/python_runtime_gap_report.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
{
"version": 1,
"generated_at": "2026-07-06T17:49:55+00:00",
"matrix_generated_at": "2026-07-06T17:49:55+00:00",
"matrix_sha256": "19b3bb085a8392aa9e6f99856983555c06da3606d5e81a6d1f2be7d20022899d",
"generated_at": "2026-07-10T21:33:31+00:00",
"matrix_generated_at": "2026-07-10T21:30:49+00:00",
"matrix_sha256": "6ecf2e6088f7d7a8926cc75e72d4376423b3a171c47406c9f995a5c368e48027",
"summary": {
"feature_count": 59,
"gap_count": 0,
Expand Down
7 changes: 5 additions & 2 deletions contracts/runtime_feature_matrix.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"version": 1,
"generated_at": "2026-07-06T17:49:55+00:00",
"generated_at": "2026-07-10T21:30:49+00:00",
"inventory_sources": {
"python_supported_commands": [
"blast-all",
Expand Down Expand Up @@ -327,6 +327,7 @@
"--deps",
"--deps-parallel",
"--deps-sequential",
"--docker",
"--doctor",
"--entire-system",
"--failed",
Expand Down Expand Up @@ -419,6 +420,7 @@
"python_source_of_truth": [
"python/envctl_engine/runtime/engine_runtime.py",
"python/envctl_engine/runtime/engine_runtime_lifecycle_support.py",
"python/envctl_engine/runtime/lifecycle_full_cleanup.py",
"python/envctl_engine/runtime/lifecycle_blast_support.py",
"python/envctl_engine/runtime/lifecycle_blast_ports.py",
"python/envctl_engine/runtime/lifecycle_blast_processes.py",
Expand Down Expand Up @@ -1311,7 +1313,8 @@
"shell_source_of_truth": [],
"python_source_of_truth": [
"python/envctl_engine/runtime/engine_runtime.py",
"python/envctl_engine/runtime/lifecycle_cleanup_orchestrator.py"
"python/envctl_engine/runtime/lifecycle_cleanup_orchestrator.py",
"python/envctl_engine/runtime/lifecycle_full_cleanup.py"
],
"evidence_tests": [
"tests/python/runtime/test_lifecycle_parity_stop_health.py"
Expand Down
4 changes: 2 additions & 2 deletions docs/developer/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This repository is Python-first at runtime. Most behavior changes therefore need
- did the change accidentally break the supported Python runtime contract?

## Workflow
1. Create a branch from `main`.
1. Create a branch from `dev`.
2. Keep changes scoped to one objective.
3. Install the CLI in editable mode:

Expand All @@ -35,7 +35,7 @@ uv run --extra dev python scripts/release_shipability_gate.py --repo . --check-t
6. Use narrower `unittest` targets only for focused local iteration; they are no longer the authoritative release-readiness lane.

7. Use conventional commits (`type(scope): subject`).
8. Open a PR with:
8. Open a PR targeting `dev` with:
- `Summary`
- `Validation`
- `Impact`
Expand Down
40 changes: 39 additions & 1 deletion docs/reference/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,11 +253,16 @@ envctl pr-preview-controller --command start --pr-number 287
Behavior:

- starts or reconciles a preview when the configured label is added
- treats an explicit `--command start` as a forced reconciliation: an existing
same-head runtime is stopped before the import/start path runs again, so
changed CI environment or secret inputs cannot be hidden by Git identity
- redeploys labeled PRs when GitHub sends a new-commit event
- loads a tracked `.envctl` from the exact PR head when present; otherwise it
falls back to the controller-generated configuration
- publishes explicitly listed `ENVCTL_PREVIEW_PUBLIC_SERVICES` on deterministic
TLS hosts and projects matching HTTP/WebSocket source URLs into launch env
- rejects a routed service whose JSON health response explicitly reports
`"ready": false`, even when the endpoint itself returns HTTP 2xx
- creates `ENVCTL_PREVIEW_GENERATED_SECRETS` ephemerally for each preview start,
so shared service credentials do not need to be stored in GitHub
- also redeploys during scheduled reconciliation if the saved preview head is stale
Expand All @@ -271,6 +276,22 @@ Behavior:
- records GitHub deployments and marks them inactive when previews stop
- is intended for trusted CI runners with `gh`, `git`, Docker, and envctl available

Integration ownership:

- envctl is the canonical owner of preview event parsing, branch-to-PR
matching, worktree lifecycle, runtime cleanup, comments, and deployments;
consuming repositories should invoke the installed command instead of
vendoring a controller copy
- the caller workflow should forward `pull_request_target`, feature-branch
`push`, `schedule`, and `workflow_dispatch` events through
`GITHUB_EVENT_NAME` and `GITHUB_EVENT_PATH`
- feature-branch `push` events are restricted to open same-repository PRs with
the configured preview label; deleted branches, tags, forks, and unmatched
branches are ignored
- install or select the desired envctl revision before invoking the command;
this keeps controller rollout/version policy in CI while behavior and tests
remain centralized in envctl


## Runtime Resolution Events

Expand All @@ -291,6 +312,10 @@ High-value command families:
- `plan`
- `import`
- `test`

When `envctl pr` or `envctl ship` opens a pull request without an explicit
`ENVCTL_PR_BASE`, it selects the first branch that exists in this order:
`dev`, `main`, then `master`. Both remote branches and local refs are checked.
- `logs`
- `health`
- `errors`
Expand Down Expand Up @@ -388,6 +413,14 @@ envctl kill --backend --headless # alias for stop --backend
envctl kill-all --headless # alias for stop-all
```

Plain dependency cleanup is intentionally storage-preserving: `stop --dependencies`
and plain `stop-all` release saved dependency records and scoped port locks, but
leave envctl-managed Docker dependency stacks and their storage available for a
later start to reuse. Use `stop-all --remove-volumes` to remove supported managed
containers and volumes, or `blast-all` for aggressive ecosystem cleanup.
Explicit `--main` and `--trees` cleanup is mode-scoped: it never stops or retires
the other mode's saved runtime.

For AI plan-agent launches, `--entire-system` starts configured or autodetected local app services. In a repo/worktree
with no explicit backend, frontend, or additional-service configuration and no supported autodetectable app layout,
envctl reports that no local app system is configured and continues without app services; the AI session still launches.
Expand Down Expand Up @@ -522,6 +555,11 @@ Commit defaults:
- write one complete next commit message in `.envctl-commit-message.md` rather than multiple fragmented summaries only when using the fallback ledger
- envctl-local control artifacts (`.envctl*`, `.codegraph/`, `.serena/project.local.yml`, `MAIN_TASK.md`, `OLD_TASK_*.md`, `trees/`) stay local; if a broad `git add .` stages them, `envctl commit` unstages those protected paths before committing normal changes

PR defaults:

- `envctl pr` and `envctl ship` target `dev` when that remote branch exists, otherwise `main`, otherwise `master`; use `--pr-base <branch>` to override the selection explicitly
- an existing open PR for the current head branch is rediscovered before creation, so rerunning the command reports or updates the same PR instead of opening a duplicate

Optional plan-agent launch config for `--plan` and `--import`:

`envctl ship` is the preferred AI handoff command. From inside the current
Expand All @@ -534,7 +572,7 @@ If GitHub has attached the pushed head commit but still has no target test check
`no_checks_reported` immediately instead of waiting for the full timeout. The command returns the structured JSON result by default including
the PR URL, `pr_created`, `operation_statuses`, `checks_state`, `passed_checks`,
`failing_checks`, `pending_checks`, and `checks_error`. `--json` remains accepted as a compatibility no-op;
use `--human` only when compact terminal output is preferred. The check wait timeout defaults to 2 minutes; pending
use `--human` only when compact terminal output is preferred. The check wait timeout defaults to 3 minutes; pending
checks after that window are reported as `checks_pending_timeout` without failing the handoff command, while actual failed
checks still return a non-zero exit. The timeout can be tuned with
`ENVCTL_SHIP_CHECK_TIMEOUT_SECONDS` and
Expand Down
66 changes: 66 additions & 0 deletions docs/reference/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,6 +139,13 @@ Only simple `${VAR}` placeholders are supported. Shell-style defaults, command s

Frontend launch-env sections may use `ENVCTL_SOURCE_SUPABASE_URL` and `ENVCTL_SOURCE_SUPABASE_ANON_KEY`. They cannot reference `ENVCTL_SOURCE_SUPABASE_SERVICE_ROLE_KEY`; envctl rejects that mapping before launching the frontend process.

Every launched service also receives `ENVCTL_PYTHON_EXECUTABLE`, the absolute
interpreter path running envctl. Repository-owned shell launchers can use this
as a bootstrap interpreter on minimal hosts where a `python` command alias is
not installed. Applications should still create and execute their own project
environment rather than importing application dependencies from envctl's
environment.

## Managed Supabase Ports

Managed Supabase exposes two distinct local resources:
Expand Down Expand Up @@ -371,6 +378,65 @@ The wizard saves accepted backend/frontend test suggestions to `ENVCTL_BACKEND_T
| `ENVCTL_WORKTREE_CGC_DATABASE` | `kuzudb` | Backend passed as `--database <value>` to `cgc context create` for generated worktree contexts. |

## Execution Policy

### Docker application runtime

`envctl ... --docker` preserves normal project selection, port allocation, dependency startup,
service ordering, state, dashboard, logs, health, restart, and stop behavior, but launches every
selected app service in a managed container instead of as a host process. Managed dependencies such
as Postgres, Redis, Supabase, and n8n continue to use their existing Docker adapters.

Settings resolve service-specific keys before global fallbacks. Additional service names are
uppercased and non-alphanumeric characters become underscores, so `voice-runtime` accepts the
standard `ENVCTL_SERVICE_VOICE_RUNTIME_*` prefix (and the shorter `ENVCTL_VOICE_RUNTIME_*` alias).

| Variable | Default | Purpose |
| --- | --- | --- |
| `ENVCTL_<SERVICE>_DOCKER_IMAGE` / `ENVCTL_DOCKER_IMAGE` | unset | Existing image to run. Without a Dockerfile setting, no build runs. |
| `ENVCTL_<SERVICE>_DOCKERFILE` / `ENVCTL_DOCKERFILE` | discovered | Dockerfile to build; discovery checks the service directory and then project root. |
| `ENVCTL_<SERVICE>_DOCKER_CONTEXT` / `ENVCTL_DOCKER_CONTEXT` | Dockerfile directory | Build context relative to the project root. |
| `ENVCTL_<SERVICE>_DOCKER_TARGET` / `ENVCTL_DOCKER_TARGET` | unset | Optional multi-stage build target. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_ARGS` / `ENVCTL_DOCKER_BUILD_ARGS` | public frontend env keys | Comma-separated build-arg names or `NAME=value` entries. Named values come from the service env and are not placed on the Docker command line. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND` / `ENVCTL_DOCKER_COMMAND` | image command | Explicit command executed inside the container. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND_MODE` / `ENVCTL_DOCKER_COMMAND_MODE` | `image` | `image` keeps the image CMD/ENTRYPOINT; `service` translates and runs envctl's normal service command. |
| `ENVCTL_<SERVICE>_DOCKER_WORKDIR` / `ENVCTL_DOCKER_WORKDIR` | image default | Container working directory. |
| `ENVCTL_<SERVICE>_DOCKER_PORT` / `ENVCTL_DOCKER_PORT` | single exposed image port or allocated host port | Container-side listener port. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_POLICY` / `ENVCTL_DOCKER_BUILD_POLICY` | `cached` | `cached`, `missing`, or `never`. |
| `ENVCTL_DOCKER_BUILD_TIMEOUT_SECONDS` | `900` | Image build timeout. |
| `ENVCTL_DOCKER_RUN_TIMEOUT_SECONDS` | `120` | Container creation timeout. |

The default `cached` policy invokes `docker build` with BuildKit enabled on every start. Docker
evaluates the context and reuses unchanged layers, while changed source cannot accidentally reuse a
stale whole image. Generated tags are stable for one checkout/worktree, preventing parallel trees
from racing on one tag. Use `missing` for immutable/prebuilt local tags and `never` when image
lifecycle is owned outside envctl.

Containers publish only to `127.0.0.1`, carry `io.envctl.*` ownership labels, and persist their ID,
name, and image in runtime state. Internal URLs and host settings pointing at `localhost` map to
`host.docker.internal`; browser-facing `VITE_*`, `NEXT_PUBLIC_*`, `PUBLIC_*`, CORS, and frontend URL
values remain host-facing. Service env passes through a short-lived mode-`0600` file and is not
rendered into Docker command diagnostics. Normal logs are snapshotted from Docker on demand;
`logs --follow` creates followers only for that command and tears them down on exit, so application
runtime state does not depend on long-lived host helper processes.

```dotenv
ENVCTL_BACKEND_DOCKER_IMAGE=acme/api-dev:latest
ENVCTL_BACKEND_DOCKER_COMMAND=uvicorn app.main:app --host 0.0.0.0 --port 8000
ENVCTL_BACKEND_DOCKER_PORT=8000

ENVCTL_FRONTEND_DOCKERFILE=frontend/Dockerfile
ENVCTL_FRONTEND_DOCKER_CONTEXT=frontend
ENVCTL_FRONTEND_DOCKER_PORT=5173
```

```bash
envctl start --trees --entire-system --docker --headless
envctl health --json
envctl logs --project feature-a-1 --service backend
envctl restart --project feature-a-1 --service backend --docker --headless
envctl stop --project feature-a-1 --entire-system
```

| Variable | Default | Purpose |
| --- | --- | --- |
| `ENVCTL_SERVICE_ATTACH_PARALLEL` | `true` | Run backend+frontend service attach in parallel when both are selected. |
Expand Down
14 changes: 12 additions & 2 deletions docs/reference/important-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ pass `--interactive` only when you want prompts.
| `--frontend` | Runtime scope: run or stop frontend app services only. |
| `--fullstack` | Runtime scope: run or stop backend and frontend app services. |
| `--both` | Alias for `--fullstack`. |
| `--dependencies` | Runtime scope: run or stop dependencies only (DB/Redis/etc.), without app services. |
| `--dependencies` | Runtime scope: run dependencies only, or detach their saved records/port locks on stop without removing reusable managed Docker stacks. |
| `--deps` | Alias for `--dependencies`. |
| `--entire-system` | Runtime scope: run or stop dependencies plus backend and frontend services. |
| `--entire-system` | Runtime scope: run dependencies plus app services; on stop, terminate app services and detach dependency records/locks while keeping managed Docker stacks reusable. |
| `--only-frontend` | Startup/plan modifier: launch only the frontend app service; skip backend, managed dependencies, and dependency prep. |
| `--only-backend` | Startup/plan modifier: launch only the backend app service; skip frontend, managed dependencies, and dependency prep. |
| `--no-deps` | Startup/plan modifier: skip managed dependencies and plan-agent dependency prep. |
Expand Down Expand Up @@ -89,12 +89,22 @@ Plan-agent handoff note: if `--plan --tmux/--omx --headless` starts the implemen
| `--parallel-trees` | Enable parallel tree startup workers. |
| `--parallel-trees-max <n>` | Max parallel tree startup workers. |
| `--service-parallel` / `--service-sequential` | Run backend+frontend startup attach in parallel or sequential mode (default: parallel). |
| `--docker` | Build or reuse images and run backend, frontend, and additional app services as managed Docker containers. |
| `--parallel` / `--sequential` | For `envctl test`, run backend/frontend test suites in parallel or sequential mode (default: parallel for multiple suites, with sequential fallback). Legacy aliases: `--test-parallel` / `--test-sequential`. |
| `--test-parallel-max <n>` | Cap concurrent test suites in parallel mode and pytest-xdist workers when pytest-xdist is explicitly enabled (default suite cap: CPU-aware, max `4`; default pytest workers: current free CPU cores). |
| `--clear-port-state` | Clear saved port reservations/state. |
| `--force` | Free configured ports if needed. |
| `ENVCTL_DOCKER_PREWARM=0\|1` | Enable/disable one-shot Docker daemon prewarm before requirements startup (default: `1`). |
| `ENVCTL_DOCKER_PREWARM_TIMEOUT_SECONDS=<n>` | Timeout for Docker prewarm command (default: `10`). |
| `ENVCTL_<SERVICE>_DOCKER_IMAGE=<image>` | Use an existing image for one app service. `ENVCTL_DOCKER_IMAGE` is the global fallback. |
| `ENVCTL_<SERVICE>_DOCKERFILE=<path>` | Build an app service image from a Dockerfile. `ENVCTL_DOCKERFILE` is the global fallback. |
| `ENVCTL_<SERVICE>_DOCKER_CONTEXT=<path>` | Override the Docker build context; defaults to the Dockerfile directory. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_ARGS=<names>` | Add comma-separated Docker build-arg names (or `NAME=value` entries); public frontend env keys are passed automatically. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND=<command>` | Override the image command inside the container. |
| `ENVCTL_<SERVICE>_DOCKER_COMMAND_MODE=image\|service` | Keep image CMD/ENTRYPOINT (default) or run envctl's normal service command. |
| `ENVCTL_<SERVICE>_DOCKER_PORT=<port>` | Override the container-side port while preserving envctl's allocated host port. |
| `ENVCTL_<SERVICE>_DOCKER_WORKDIR=<path>` | Override the image working directory for the service command. |
| `ENVCTL_<SERVICE>_DOCKER_BUILD_POLICY=cached\|missing\|never` | `cached` (default) reuses Docker layers; `missing` builds only when absent; `never` requires an existing image. |
| `ENVCTL_REQUIREMENTS_PORT_MISMATCH_POLICY=adopt_existing\|recreate` | On existing container port mismatch, adopt existing mapping (default) or force recreate. |

## Logs and Debugging
Expand Down
Loading
Loading