feat(agents): annotate actual allocated task work

[decode2]

Linked issue

Refs #1702. Explicit recorded work metadata, not completion of owner-only decisions.

PR type

• New feature (type:feature)

Summary

• Accept an optional work descriptor on subagent_run, validated before preparation, consent or allocation.
• Annotate only the actual allocated owned task ID in the existing curated state, without TaskRecord fields, another registry, child prompt injection or inheritance.
• Retain launched tasks when optional publication fails, and pin the captured owner after append so reentrant session changes cannot clobber new-owner notes.

Changes

Surface	Change
lib/orchestrator-work.ts	Root-only bounded task annotations and separate launch descriptors
lib/orchestrator-state.ts	PublishedWork type and captured-owner post-append guard
extensions/gentle-agents.ts	Real allocation callback, optional work argument and honest local-publication status
tests/orchestrator-work.test.ts, tests/gentle-agents.test.ts	Exact allocated IDs, pre-effect validation, failure/capacity, replacement and reentrant owner coverage
docs/gentle-agents-activity.md, odd/tasks/work-discovery.md	Usage, limitations and work-unit evidence

Test plan

• Public-tool RED: missing publication status and invalid metadata reached preparation, two intended failures.
• Reentrancy RED: missing expected exception; GREEN preserves valid new-owner notes and rejects old publication.
• Writer seven-file affected suite: 231 passed, zero failures.
• Type ratchet: 186 recorded diagnostics, no regressions (not clean compilation).
• Runtime check: eight generated modules unchanged; whitespace check passed.
• Fresh independent seven-file fixed-candidate verification: 231 passed, zero failed/skipped; source files and Git index unchanged.
• Shellcheck and skill-load testing: N/A, no scripts or skills changed.

Contributor checklist

• Nonclosing approved issue reference for partial coordination work.
• Exactly one type:feature label requested on create; verify target readback.
• Tests and behavior docs included.
• Authorized conventional work-unit commit completed.
• No AI attribution or Co-Authored-By trailers.

Chain context

Field	Value
Strategy	Sequential stacked feature-parent PRs
Position	2, explicit allocated-task annotation
Base	feat/work-classification, PR #1779 (bc7624a2)
Depends on	#1779
Follow-up	Bounded published-work search and public SDK integration
Review budget	232 additions + deletions / 400
Starts at	Validated session work publication
Ends with	Optional classification on actual newly allocated owned task IDs
Rollback	Remove explicit task-annotation argument/callback/decoder extension and tests/docs; session work remains

main
 └── #1779: classified publication
      └── 📍 this PR: actual owned task annotation
           └── next: bounded search / related-work matches
                └── next: public SDK acceptance

recorded means local curated persistence, not guaranteed peer advertisement. Publication unavailability is not launch failure; do not relaunch an allocated task. Historical annotations are not proof of current ownership, and later search must join current published active catalog IDs. Capacity failures never prune owner-declared notes.

Out of scope: automatic classification/inheritance, continuation annotation, search/filter wiring, helper capture, real child SDK execution, owner decisions, dependency execution and runtime activation. Allocation tests mock the production runner; existing SDK consultation regression does not prove OS child launch. Reentrancy is a controlled lifecycle regression, not a claimed natural SDK race.

Native assessment: medium risk, under budget, outcome unknown. The initial small/fallback profile requested separate verification; after the tracker write the runtime profile is large. No native approval/consumption or main merge is claimed.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 9be55bc7-c95b-4518-b1ab-2714f45b69e4

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}