Skip to content

feat(agent-org): enforce Coordinator-only Task graphs and atomic activation #704

Description

@ShiboSheng

Stack position

This PR enables direct work activation only after the lifecycle and Root-send foundations exist. It does not enable Member conversation; that remains gated until PR 4.

Problem / Motivation

The current Task model allows Worker self-create and Manager administration of direct-report Tasks. Idle activation is not one atomic Root-owned transaction, Task terminal semantics are incomplete, and callbacks/recovery do not yet share the same generation fence. This conflicts with the final authority rule: Coordinator writes the global Task graph; Workers only execute their assigned Task.

Goal

When Coordinator decides a user message requires work, create the Task graph directly—without Proposal or confirmation—and atomically activate an Idle Team. Make Task authority deterministic at Store/Tool/Prompt/registry boundaries and make Completed/Failed/Cancelled terminal states irreversible and auditable.

Required scope

  • Add a Root-current-Turn-only IMMEDIATE batch transaction as the sole Idle → Working activation writer.
  • In one commit, validate authoritative message/Turn; advance Team state, activation_generation, and work_revision; clear old completion intent; mark the Turn activation; and insert Task graph, dependencies, history, and assignment outbox.
  • Persist the activation receipt on Turn Intent and immutable Task source fields (source_turn_intent_id, originating_message_id).
  • In Working, Coordinator graph expansion increments only work_revision, not activation_generation.
  • Remove Worker self-create and Manager direct-report administration from registry, Prompt, Tool execution, Store field gates, debug helpers, and tests.
  • Enforce a typed actor/field matrix: Coordinator administers pending graph; Task owner advances only its bound lifecycle/output; System uses only narrow receipt/generation-backed Archive/Recovery operations.
  • Require every new Task to start pending. Coordinator cannot impersonate owner lifecycle/output; Worker cannot mix graph-admin fields into lifecycle updates.
  • Represent in-progress goal/owner/dependency changes as cancel + replacement pending Task; do not add superseded.
  • Carry and recheck generation through Wake enqueue, Scheduler claim, Recovery reserve/refund/callback, and work finalization.
  • Treat paused-yield as a lifecycle handoff, not a normal Task finalizer; Resume creates at most one valid continuation for the new authorization generation.
  • Default to dependency/queue scheduling; parallel work requires explicit Coordinator override.
  • Add complete Completed/Failed/Cancelled result/reason semantics and append-only audit annotations. Remove status=deleted; physical rows disappear only through Archived Team destructive delete.
  • Freeze all terminal Task core fields; Failed/Cancelled do not satisfy dependencies.

Locked invariants

  • Coordinator is the only global Task graph writer. Hierarchy does not grant Manager Task authority.
  • Worker can advance only its currently assigned Task lifecycle/output.
  • Idle activation and first Task graph are all-or-nothing and exactly-once per authoritative Root Turn.
  • Terminal Tasks never reopen; no superseded state exists.
  • Failed/Cancelled cannot unlock downstream Tasks.
  • Every Wake/Recovery/callback revalidates status, owner, receipt, generation, and lease at the owning boundary.
  • No Proposal, confirmation card, second model classifier, or frontend activation command is introduced.

Acceptance criteria

  • Failure before any activation commit point leaves Team Idle with no Task, outbox, or partial receipt.
  • Replaying the same Root Turn/batch creates one generation and one Task graph.
  • Two Root Turns racing from Idle produce one activation; the other follows Working expansion without a second generation bump.
  • Working expansion preserves validity of existing Worker callbacks and queues new work by default.
  • Worker/Manager cannot obtain Task admin tools; directly constructed/debug tools are also rejected with zero side effects.
  • New Tasks cannot start in_progress/completed; Completed requires output and Failed/Cancelled require reason.
  • Mixed legal Worker lifecycle plus illegal graph fields fails atomically.
  • Coordinator cannot write owner lifecycle/output while pretending to be the Worker.
  • A stale Worker completion after cancel/reassignment is a no-op.
  • Paused activation writes nothing; explicit Resume followed by a new Root Turn is required.
  • Pause-fenced callbacks have zero work side effects and each receipt yields at most one legal continuation.
  • Crash after commit or first Wake failure recovers the same Tasks/outbox without reinterpreting the message.
  • Archive wins races with activation, Wake, Recovery, and callbacks.
  • Old-generation callbacks are diagnostic-only.
  • Every terminal core-field patch is rejected; audit annotations remain append-only.
  • Failed/Cancelled upstream Tasks do not unlock dependents.
  • Recovery reserve/refund is idempotent for the same token and generation.

Verification

  • Rust Store/transaction/actor-field/race/generation/terminal-state tests.
  • Real registry and Tool-to-Task production integration, including debug bypass attempts.
  • SQLite concurrency and fault-injection around the activation commit.
  • Crash/restart/Recovery E2E using the authoritative Root Turn.
  • Frontend tests for Paused activation rejection and Task history/result/reason display.
  • TypeScript typecheck and focused UI tests.
  • Architecture audit across Task ownership, FSM, wire schema, persistence, initialization parity, and dead legacy authority paths.
  • Performance guard for Wake, recovery reservations, FIFO scheduling, and bounded retries.

Out of scope

  • Direct or Group Member conversation and read-only tool policy (PR 4).
  • Complete UI, 13 locales, rendered release E2E, and final performance measurements (PR 5).
  • Proposal/confirmation/work-request lifecycle.
  • Worker-created Tasks, Manager-to-report Task creation, superseded, or reopening terminal Tasks.
  • Unrelated changes to ordinary SDE Agent tools or scheduling.

Effort and budget

  • Label: Effort: High
  • P50 range: 3,600–4,600 review lines; planning point: 4,600
  • P90 cap: 6,200 review lines
  • Expected substantive files: 25–34
  • At 70% of P50, review the diff and risks. Above 1.25× P50, explain new entry points/test surface; at 1.5×, stop and re-spike before expanding scope.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions