fix: gate focus auto-start on task dependencies (#3045)

This commit is contained in:
Carlos Florêncio
2026-08-26 07:11:38 +00:00
committed by GitHub
parent 2db9af2a3d
commit 32b81c2f2d
6 changed files with 429 additions and 20 deletions
@@ -0,0 +1,82 @@
---
created: 2026-08-25
status: done
requirements:
- REQ-TASKS-TASK-DEPENDENCIES-001
system_design:
- ../../specs/tasks/system-design/task-dependencies.md
legacy_specs: []
---
# Implementation Plan: Focus Auto-Start Dependency Gate
## Overview
Repair the `session.ensure` focus path so every `LaunchSession` request marked
as an automatic start observes the existing task-dependency gate. Add the
regression test first, then extend `launchStart`'s existing downgrade-to-prepare
condition without changing manual starts or dependency-resolution behavior.
## Scope
### In scope
- Gate `LaunchSession` requests with `IntentStart` and `AutoStart: true` on
unresolved task dependencies.
- Fail closed when the dependency gate cannot be read.
- Preserve the workspace-only `CREATED` session used to inspect a blocked task.
- Preserve normal automatic starts after dependencies resolve.
### Out of scope
- Manual Start agent actions and direct manual `StartTask` calls.
- Existing dependency-resolution, deferred-launch, and WIP-promotion behavior.
- Frontend changes, API changes, persistence changes, and browser E2E coverage.
## Technical approach
Add the dependency predicate to the existing auto-start downgrade in
`apps/backend/internal/orchestrator/session_launch.go`. The request remains an
automatic request while `launchPrepare` runs, which suppresses passthrough
prepare upgrades and prevents a bounce back into `launchStart`.
Add focused table-driven coverage in a new orchestrator test file. Use a
minimal configurable `TaskDependencyReader` fake and the established launch
counter/service wiring to prove blocked and read-error requests prepare only,
while an unblocked request reaches the agent launch path.
## Tests
- `AC-TASKS-TASK-DEPENDENCIES-001.1`: `TestLaunchSession_AutoStartDependencyGate`
covers an unresolved dependency, a resolved dependency, and a dependency-read
error at the `LaunchSession` boundary.
- The blocked and read-error cases assert a `CREATED` workspace-only session,
no agent launch, and no transition to `SCHEDULING` or `IN_PROGRESS`.
- The unblocked case asserts the normal launch path still reaches a running
agent session.
## Work orders
- [x] [Task 01: Gate focus-induced auto-start](task-01-gate-focus-autostart.md)
## Verification results
- Focused regression passed:
`go test -tags fts5 ./internal/orchestrator -run '^TestLaunchSession_AutoStartDependencyGate$' -count=1`.
- Focused race regression passed:
`go test -race -tags fts5 ./internal/orchestrator -run '^TestLaunchSession_AutoStartDependencyGate$' -count=1`.
- `make -C apps/backend lint` passed with zero issues.
- `gofmt -l` reported no changes for the modified Go files.
- `make -C apps/backend test` passed for `internal/orchestrator` and the other
packages reached before two unrelated environment-sensitive packages failed.
`internal/common/config` and `internal/launcher` selected the existing
`/root/.kandev/config.yaml` instead of each test's temporary home.
## Risks
- The downgrade must retain `AutoStart: true`; clearing it would allow a
passthrough prepare to upgrade back into an agent start.
- The dependency reader is optional in some test/service constructions, so the
nil-reader behavior must remain unchanged.
- Broad backend validation can expose unrelated repository failures; targeted
orchestrator evidence remains the regression proof.
@@ -0,0 +1,122 @@
---
id: "01-gate-focus-autostart"
title: "Gate focus-induced auto-start"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-TASKS-TASK-DEPENDENCIES-001
acceptance_criteria:
- AC-TASKS-TASK-DEPENDENCIES-001.1
system_design:
- ../../specs/tasks/system-design/task-dependencies.md
---
# Task 01: Gate Focus-Induced Auto-Start
## Summary
Make `launchStart` apply the task dependency gate to automatic starts before it
can call `startTask`. Blocked and unreadable dependency state downgrade to the
existing workspace-only prepare flow, while an unblocked task still starts.
## In scope
- Add focused `LaunchSession` regression coverage for blocked, unblocked, and
dependency-read-error cases.
- Extend `launchStart`'s `req.AutoStart` downgrade condition with
`dependencyBlocksAutoStart(ctx, req.TaskID, "session.launch")`.
- Preserve the request fields needed by `launchPrepare` and its passthrough
recursion guard.
## Out of scope
- Gating manual starts where `AutoStart` is false.
- Changing `autoStartTaskForStep`, dependency resolution, WIP admission, or the
frontend `session.ensure` message.
- Adding a browser test for a backend launch-admission regression.
## Acceptance
- A blocked automatic `IntentStart` creates only a `CREATED` workspace session,
never launches the agent, and never moves the task to `SCHEDULING` or
`IN_PROGRESS`.
- A dependency-read error has the same fail-closed prepare-only result.
- An unblocked automatic `IntentStart` follows the existing normal start path.
## TDD sequence
1. Add `TestLaunchSession_AutoStartDependencyGate` with a nearby
`@covers AC-TASKS-TASK-DEPENDENCIES-001.1` annotation and three cases:
unresolved, resolved, and read error.
2. Run only that test. Confirm the unresolved and read-error cases fail because
an agent starts or the task leaves `CREATED`; confirm the resolved positive
control reaches the existing launch path.
3. Add the minimum dependency predicate to `launchStart`'s current automatic
downgrade condition.
4. Rerun the focused test and keep all three cases green. Refactor only the test
setup if needed for clarity, then rerun it after the final production edit.
## Verification
```bash
cd apps/backend
go test -tags fts5 ./internal/orchestrator -run '^TestLaunchSession_AutoStartDependencyGate$' -count=1
cd ../..
make -C apps/backend test
make -C apps/backend lint
gofmt -l apps/backend/internal/orchestrator/session_launch.go apps/backend/internal/orchestrator/session_launch_dependency_test.go
git diff --cached --name-only | grep '\.go$' | xargs -r gofmt -l
```
If either formatting command reports a file, run `gofmt -w` on that exact file,
restage it, and repeat both checks before committing.
## Files likely touched
- `apps/backend/internal/orchestrator/session_launch.go`
- `apps/backend/internal/orchestrator/session_launch_dependency_test.go`
## Dependencies
None.
## Risks
- A test that observes only a session row could miss an agent launch; assert
both persisted state and the launch counter.
- The resolved positive control must use the same harness so a no-op setup
cannot make every case appear gated.
## Parallelism
`sequential`
## Inputs
- `REQ-TASKS-TASK-DEPENDENCIES-001` and
`AC-TASKS-TASK-DEPENDENCIES-001.1`.
- `docs/specs/tasks/system-design/task-dependencies.md`, especially automated
launch guards and fail-closed behavior.
- `apps/backend/internal/orchestrator/session_launch.go` and existing
orchestrator dependency/launch test helpers.
## Results
Implemented the dependency gate in `launchStart` and added
`TestLaunchSession_AutoStartDependencyGate`. The regression covers unresolved
dependencies, resolved dependencies, and dependency-read errors at the
`LaunchSession` boundary. Blocked and unreadable dependency state now keeps the
request on the workspace-only `CREATED` path; resolved state still launches.
Validation:
- Focused test passed.
- Focused race test passed.
- Backend lint passed with zero issues.
- `gofmt -l` reported no changes.
- The full backend target reached and passed `internal/orchestrator`, but the
target returned failure because unrelated config-discovery tests in
`internal/common/config` and `internal/launcher` read the existing
`/root/.kandev/config.yaml` instead of their temporary homes.
@@ -101,7 +101,7 @@ parallel ones. The reuse is part of the contract because the guarantees below
|---|---|
| `task_blockers` table + BFS cycle detection (`office/dashboard.AddTaskBlocker`) | The dependency edge store and cycle validator, promoted from Office-only to a core task relationship. |
| Deferred launch intent (`tasks.metadata.deferred_launch`, claimed atomically) | Storage and idempotent consumption of "start automatically when unblocked". |
| The single auto-start chokepoint (`orchestrator.autoStartTaskForStep`) | Where the dependency gate lives and where dependency-triggered launches enter, so the existing auto-start claim guard prevents double launches. |
| Automated launch guards (`orchestrator.autoStartTaskForStep` and `orchestrator.launchStart`) | `autoStartTaskForStep` gates workflow, queue, watcher, and dependency-resolution starts before claims. `launchStart` gates `LaunchSession` auto-starts, including `session.ensure`, and downgrades blocked requests to workspace-only prepare. |
| WIP admission and queue promotion ([`tasks/wip-limit-pull-system`](wip-limit-pull-system.md)) | Decides whether an unblocked, auto-start-intent task launches now or on promotion. |
Two existing behaviors are intentionally *not* changed:
@@ -419,8 +419,9 @@ Edges and blocking:
Gating:
- **GIVEN** B depends on an unfinished A and B's workflow step has
`on_enter: auto_start_agent`, **WHEN** B is moved into that step, **THEN** no
session is created and the skip is logged.
`on_enter: auto_start_agent`, **WHEN** B is moved into that step or its task
view sends `session.ensure`, **THEN** no agent starts. The move creates no
session; focus may create only a workspace-ready `CREATED` session.
- **GIVEN** B depends on an unfinished A and B is queued for a WIP-limited
auto-start step, **WHEN** capacity opens and B is promoted, **THEN** B is
admitted, its queued badge clears, and no session is created.
@@ -576,4 +577,4 @@ MCP:
## Implementation plan
See [`../../plans/task-dependencies/plan.md`](../../../plans/task-dependencies/plan.md).
See [`../../plans/task-dependencies/plan.md`](../../../plans/task-dependencies/plan.md).