fix: gate focus auto-start on task dependencies (#3045)
This commit is contained in:
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user