feat: Task ID semantics and lifecycle integrity (#3404, #3405)

[garnetlyx]

Summary

Implements GitHub issues #3404 (Task ID semantics) and #3405 (Task lifecycle integrity).

Changes

#3404: Task ID Semantics

1. New utility (src/shared/id-types.ts): Added detectIdType() to identify ID types (background/task/session/unknown) and formatIdTypeError() for type-aware error messages.
2. Type-aware errors (background_output): Now distinguishes session vs task vs background IDs and suggests the correct tool.
3. Consistent metadata: Updated all 4 tool surfaces (delegate-task, call-omo-agent, sync-task, background-task) to use unified <task_metadata> format.

#3405: Task Lifecycle Integrity

4. BlockedBy guard (task-update): Prevents marking a task completed if it has unresolved blockedBy dependencies.
5. Near-duplicate detection (task-create): Warns (doesn't block) when creating a task with the same subject in the same session.

Verification

• 478 tests pass, 0 fail
• 47 files across 4 test suites
• All new behaviors have test coverage
• No breaking changes to existing tests

---

Summary by cubic

Adds type-aware Task ID handling and enforces dependency rules to prevent ID mix-ups and premature completion. Implements #3404 (Task ID semantics) and #3405 (Task lifecycle integrity).

• New Features

  • Shared utils: detectIdType() and formatIdTypeError() classify IDs (bg_, T-, ses_/ses-) and return helpful hints.
  • background_output: type-aware errors; suggests session_read for ses_*/ses-* and task_update/task_get for T-...; generic not found for bg_.../unknown.
  • Unified <task_metadata>: emitted only when session_id is resolved; includes session_id and background_task_id. call-omo-agent and delegate-task updated; sync-task adds task_id for foreground tasks.
  • task_update: blocks completed if any blockedBy tasks are not completed or deleted; guard applies even when adding blockers in the same request; invalid IDs count as unresolved.
  • task_create: warns on near-duplicate subjects within the same session (task still created).

• Migration

  • If you parse <task_metadata>, read background_task_id for background jobs; the block may be omitted until session_id is known. Do not rely on task_id in that block.

^{Written for commit dddfc6c. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

3 issues found across 16 files

Confidence score: 2/5

• I’m scoring this as high risk because there are two high-severity, high-confidence issues (7/10, confidence 9/10) with concrete user and security impact in src/tools/task/task-update.ts.
• src/tools/task/task-update.ts uses untrusted blockedBy values in join(...) before strict ID validation, which can allow path traversal reads outside the task directory and should be treated as merge-blocking until fixed.
• src/tools/task/task-update.ts can incorrectly allow status="completed" when addBlockedBy is included in the same update, since blocker checks run before merging new blockers; src/shared/id-types.ts also misses hyphenated session IDs like ses-main, causing incorrect not-found handling.
• Pay close attention to src/tools/task/task-update.ts, src/shared/id-types.ts - path traversal/input validation and completion-guard ordering are the main risks, plus session ID format parsing.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/tools/task/task-update.ts">

<violation number="1" location="src/tools/task/task-update.ts:107">
P1: Completion can be bypassed when `status="completed"` is combined with `addBlockedBy` in the same update, because the guard checks blockers before the new ones are merged.</violation>

<violation number="2" location="src/tools/task/task-update.ts:111">
P1: Validate `blockedBy` IDs before building file paths; the new guard currently uses untrusted strings in `join(...)`, enabling path traversal reads outside the task directory.</violation>
</file>

<file name="src/shared/id-types.ts">

<violation number="1" location="src/shared/id-types.ts:6">
P2: Recognize the hyphenated session IDs used elsewhere in the repo; `ses-main` and similar values currently fall through to the generic not-found message.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Recognize the hyphenated session IDs used elsewhere in the repo; ses-main and similar values currently fall through to the generic not-found message.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/shared/id-types.ts, line 6:

<comment>Recognize the hyphenated session IDs used elsewhere in the repo; `ses-main` and similar values currently fall through to the generic not-found message.</comment>

<file context>
@@ -0,0 +1,22 @@
+export function detectIdType(id: string): IdType {
+  if (id.startsWith("bg_")) return "background"
+  if (id.startsWith("T-")) return "task"
+  if (id.startsWith("ses_")) return "session"
+  return "unknown"
+}
</file context>

[garnetlyx]

I have read the CLA Document and I hereby sign the CLA