Skip to content

docs: define supervised agent-opened session contract - #623

Closed
wibus-wee wants to merge 2 commits into
mainfrom
docs/session-worker-supervision-contract
Closed

wibus-wee wants to merge 2 commits into
mainfrom
docs/session-worker-supervision-contract

Conversation

@wibus-wee

Copy link
Copy Markdown
Member

Related issue

Refs #529

Context: #528, #531, and #569.

Problem / pressure

Agent-opened independent Sessions currently fragment one delegated workflow across ordinary rows, unread states, notifications, and permission routes. The product contract also needs to preserve the containment-only archive/delete behavior established by #569 instead of turning creation provenance into storage ownership.

Summary

  • Add a draft Spec that defines worker-default supervision and explicit handoff in observable, storage-neutral terms.
  • Cover roster/status/results, attention routing, permission escalation, settle, drill-in, archive/delete, phone creation, and existing openedBy* compatibility with acceptance scenarios.
  • Record migration, acknowledgement, active-dismiss, lifecycle fallback, post-create handoff, and later-work routing as human decisions in a proposed Agent Note.
  • Link the owning Session relation Spec to the new contract without describing proposed behavior as implemented.

Visual explanation

Human -> supervisor Session A -> worker B
                              `-> worker C
       -> explicit handoff Session D (independent peer)

supervision: roster + result + attention + acknowledgement
containment: workspace + archive/restore/delete target selection
provenance: opener identity + reverse navigation

Before / after

Before After
Every independent agent-opened Session is presented as a peer, and openedBy* does not distinguish delegated work from handoff. New agent-opened Sessions default to supervised workers; only explicit handoff creates a peer.
Worker unread, completion, and permission attention route directly to each worker. One supervisor route owns aggregate attention while preserving exact per-worker drill-in and acknowledgement.
Archive expectations in #528 conflict with the containment-only lifecycle delivered by #569. Supervision is explicitly non-containment; unresolved attention on supervisor archive/delete requires an approved product choice.

Test plan

  • pnpm run docs check passes with no errors and no protected topics.
  • Direct workspace formatting, lint, i18n, code-collab import, platform-boundary, and public-boundary checks pass.
  • Adapter builds and direct workspace typechecks pass; root wrappers could not invoke missing corepack in this environment.
  • pnpm test:scripts passes 27/27.
  • Workspace tests under Node 26 pass broadly after an explicit local-storage test file; the components suite has two unrelated failures in app-store-review-prompt-hook.test.tsx and tasks-beta-gate.test.tsx (3464 passed, 2 failed). Electron tests were excluded by the repository CI test command.

Context handoff

Instructions for reviewing agents

  • Review focus: Review specs/session-worker-supervision.md for routing and lifecycle consistency with specs/session-relations.md.
  • Decisions to challenge: Challenge the recommended legacy classification, per-worker acknowledgement, terminal-only settle, and supervisor delete precondition.
  • Plausible failures / evidence gaps: No storage shape or migration is proposed, and archive/delete attention fallback remains blocked on human approval.

Authoring context

  • User goal / directives: Define the product contract for agent-opened Sessions as supervised workers unless explicitly handed off.
  • Constraints / non-goals: Documentation only; do not change runtime behavior, storage, or containment lifecycle.
  • Risk-bearing decisions: Attention ownership, mixed-client fallback, acknowledgement scope, and destructive lifecycle preconditions affect compatibility and recovery.
  • Destructive or irreversible behavior: The draft forbids implicit worker cascade and requires approval before supervisor deletion can strand unresolved workers.
  • Deliberately not done or tested: No implementation, migration, translation, or Electron test run is included in this product-contract phase.
  • Unknowns / confidence: The direction is internally coherent, but the explicit decision table must be approved before implementation.

@wibus-wee wibus-wee closed this Sep 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant