fix(hooks): surface unreadable active task records (#544)

[izumi0uu]

Summary

Fix the workflow-state hook so an existing active task with an unreadable task record is not reported as no_task.

When the session pointer resolves to a task directory whose task.json is missing, malformed, not an object, or has no usable status, the hook now emits Task: <task> (task_error). This preserves the task identity and gives the model a diagnostic state instead of encouraging duplicate task creation.

The behavior is synchronized across the shared template, Claude hook, and Codex hook. The runtime contract now documents task_error as a reachable pseudo-status.

Closes #544

Testing

• Core test suite: 344 passed, 1 skipped
• CLI test suite: 1,674 passed
• TypeScript typecheck
• ESLint
• Python basedpyright: 0 errors (existing unused-import warnings only)
• Python syntax compilation
• GitNexus change detection: low risk
• git diff --check

Scope

• Hooks and CLI regression tests
• Backend / Lambda
• Frontend
• Infrastructure
• Database migration

Regression Coverage

• Malformed JSON
• Missing or unusable status
• Non-object JSON task records
• Ensures the result does not contain Status: no_task

Summary by CodeRabbit

• Bug Fixes

  • Workflow-state reporting now distinguishes task-record errors from sessions without an active task.
  • Displays a diagnostic task_error status when task details are missing, unreadable, malformed, non-object, or incomplete.
  • Preserves the task directory name in error breadcrumbs and provides guidance to repair the existing task record without creating a replacement.

• Tests

  • Added regression coverage for invalid task records and repair guidance in workflow messages.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: ab0cf8c5-cb56-4cb7-8feb-f5d30bc13be4

📥 Commits

Reviewing files that changed from the base of the PR and between fd25b40 and a93ff5c.

📒 Files selected for processing (4)

• marketplace
• packages/cli/src/templates/trellis/workflow.md
• packages/cli/test/regression.test.ts
• packages/cli/test/templates/trellis.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/cli/test/regression.test.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The workflow-state hooks now distinguish invalid task records from absent active-task pointers. They return task_error with the task directory name, document the behavior, add repair guidance, and test malformed, statusless, and non-object records. The marketplace submodule reference also changed.

Changes

Workflow-state task errors

Layer / File(s)	Summary
Task-record error handling .claude/hooks/inject-workflow-state.py, .codex/hooks/inject-workflow-state.py, packages/cli/src/templates/shared-hooks/inject-workflow-state.py, .trellis/spec/cli/backend/workflow-state-contract.md	The hook copies return task_error when task.json is missing, unreadable, malformed, non-object, or lacks a valid status. The contract documents the status and preserves the task directory name.
Task-error workflow guidance packages/cli/src/templates/trellis/workflow.md	The workflow template directs repair of the existing task.json and prohibits creating or activating another task.
Task-error regression coverage packages/cli/test/regression.test.ts, packages/cli/test/templates/trellis.test.ts	Tests cover malformed, statusless, and non-object task records. They verify task_error routing and repair guidance.
Marketplace submodule reference marketplace	The marketplace submodule pointer changes to commit 7310a50c138b19244bef4fb1489cf45266a13c99.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to a93ff

This change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant WorkflowStateHook
  participant TaskRecord
  participant WorkflowTemplate
  WorkflowStateHook->>TaskRecord: Read task.json
  TaskRecord-->>WorkflowStateHook: Return invalid or unusable record
  WorkflowStateHook->>WorkflowTemplate: Select task_error breadcrumb
  WorkflowTemplate-->>WorkflowStateHook: Provide repair guidance

Loading

Suggested reviewers: taosu0216

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The hooks distinguish unreadable task records, but the bundled workflow template does not ship the required diagnostic task_error block.	Add the task_error block to the bundled workflow template and update the byte-identical marketplace mirror in the companion change.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: surfacing unreadable active task records in hooks.
Out of Scope Changes check	✅ Passed	The changes remain within the linked issue scope by updating hook behavior, contracts, templates, tests, and synchronized mirrors.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[taosu0216]

Reviewed — the fix is right and I want to merge it, with one gap worth closing first.

The fix

Distinguishing "the record cannot be read" from "there is no task" is the correct call, and the failure mode it prevents is the expensive one: the model was being told no_task and would go create a duplicate task on top of a real one it simply could not read. The three hook copies (.claude/, .codex/, packages/cli/src/templates/shared-hooks/) are byte-identical, so the dogfood copies will not drift.

It also does not make the hook noisier — UserPromptSubmit already runs every turn, so this relabels an existing per-turn line rather than adding a new trigger.

The gap

The PR adds the task_error status but not a [workflow-state:task_error] block in packages/cli/src/templates/trellis/workflow.md. I verified the template has no such block today, and build_breadcrumb falls back to the generic "Refer to workflow.md for current step." line when a tag is missing.

So after merging, a user with a corrupt task.json sees:

Task: <id> (task_error)
Refer to workflow.md for current step.

The header — the part that stops the duplicate-task behaviour — works. But the diagnostic body your description promises never appears; the specific wording in the test (Repair the active task record before continuing.) comes from a workflow.md the test writes itself, so it does not demonstrate what ships.

The fallback is deliberate design (the docstring is explicit that workflow.md is the only source of truth and a missing tag should degrade visibly rather than be masked), so this is incomplete rather than broken.

Could you add the [workflow-state:task_error] block to the bundled template, telling the user their active-task record is unreadable and how to repair it? A few lines. Note the marketplace mirror is byte-compared against the bundled template by test/templates/trellis.test.ts, so marketplace/workflows/native/workflow.md needs the same edit in a companion PR against mindfold-ai/marketplace.

Ping when that is in and I will merge.

[taosu0216]

Checking back on this one — I think my earlier request may have read as already satisfied, so to be concrete about what is still missing.

The [workflow-state:task_error] blocks in this PR are in packages/cli/test/regression.test.ts, where the tests write their own workflow.md fixture. The shipped template, packages/cli/src/templates/trellis/workflow.md, still has no task_error block — I checked against the current branch head (fd25b407).

So the tests demonstrate the hook renders the block correctly if one exists, but no such block ships. A real user with a corrupt task.json gets the header (Task: <id> (task_error)) and then the generic Refer to workflow.md for current step. fallback.

What is needed is a [workflow-state:task_error] block in the bundled template itself, saying the active-task record could not be read and how to repair it. Then the marketplace mirror needs the same edit in a companion PR against mindfold-ai/marketplace, because test/templates/trellis.test.ts compares marketplace/workflows/native/workflow.md byte-for-byte against the bundled template and will fail otherwise.

The rest of the PR is good and I want it in — the hook change is correct, the three copies are byte-identical, and stopping the duplicate-task behaviour is the valuable part. This is the last piece.

[izumi0uu]

Thanks, I forgot to follow up. I’ve added the missing shipped [workflow-state:task_error] block.

It now tells the agent to repair the existing active task record and explicitly prevents creating or activating another task. I also updated the workflow status map/table and added a template-level regression assertion, so this behavior is now verified against the bundled workflow rather than only a test fixture.

The native marketplace mirror is byte-identical and is available in the companion PR:
mindfold-ai/marketplace#15

Local verification:

• Core: 344 passed, 1 skipped
• CLI: 1693 passed
• Bundled/marketplace workflow parity confirmed