fix: preserve blocked Kanban cards from auto-decomposition

.gitignore

@@ -122,6 +122,8 @@ models-dev-upstream/
 .codex/
 .cursor/
 .gemini/
+# Generated local Kanban worker Git-identity guard.
+.hermes-hooks/
 .zed/
 .mcp.json
 opencode.json

agent/anthropic_adapter.py

@@ -926,13 +926,17 @@ def _read_claude_code_credentials_from_keychain() -> Optional[Dict[str, Any]]:
         logger.debug("Keychain: no entry found for 'Claude Code-credentials'")
         return None
 
-    raw = result.stdout.strip()
+    raw = result.stdout
+    if not isinstance(raw, str):
+        logger.debug("Keychain: credentials payload was non-text (%s)", type(raw).__name__)
+        return None
+    raw = raw.strip()
     if not raw:
         return None
 
     try:
         data = json.loads(raw)
-    except json.JSONDecodeError:
+    except (json.JSONDecodeError, TypeError):
         logger.debug("Keychain: credentials payload is not valid JSON")
         return None
 

agent/prompt_builder.py

@@ -216,12 +216,19 @@ def _strip_yaml_frontmatter(content: str) -> str:
     "files outside it unless the task explicitly asks.\n"
     "3. **Heartbeat on long operations.** Call `kanban_heartbeat(note=...)` "
     "every few minutes during long subprocesses (training, encoding, crawling). "
-    "Skip heartbeats for short tasks. **If your task may run longer than 1 hour, "
-    "you MUST call `kanban_heartbeat` at least once an hour** — the dispatcher "
-    "reclaims tasks running past `kanban.dispatch_stale_timeout_seconds` "
-    "(default 4 hours) when no heartbeat has arrived in the last hour. A "
-    "reclaim re-queues the task as `ready` without penalty (no failure counter "
-    "tick), but you lose your current run's progress.\n"
+    "Skip heartbeats for short tasks. Heartbeat cadence has TWO distinct windows:\n"
+    "   - **Initial window (no heartbeat yet on this run):** you have up to "
+    "`kanban.dispatch_stale_timeout_seconds` (default 4 hours) before the "
+    "stale-claim reaper reclaims the task — but send your first heartbeat as "
+    "soon as the work is meaningfully underway, not at the last minute.\n"
+    "   - **Steady state (after your first heartbeat on this run):** you MUST "
+    "call `kanban_heartbeat` at least every `kanban.stuck_after_seconds_default` "
+    "(default 15 min). A worker that has heartbeated at least once but then goes "
+    "silent for >`kanban.stuck_after_seconds_default` is killed and re-queued "
+    "without a failure penalty, but progress since the last heartbeat is lost. "
+    "If your task legitimately needs longer between heartbeats (e.g. a training "
+    "epoch), set `metadata.stuck_after_seconds` on the task or mark it "
+    "`metadata.no_heartbeat_required=true` to opt out of stuck detection.\n"
     "4. **Block on genuine ambiguity.** If you need a human decision you cannot "
     "infer (missing credentials, UX choice, paywalled source, peer output you "
     "need first), call `kanban_block(reason=\"...\")` and stop. Don't guess. "
@@ -233,13 +240,17 @@ def _strip_yaml_frontmatter(content: str) -> str:
     "workers read both via their own `kanban_show`. Never put secrets / "
     "tokens / raw PII in either field — run rows are durable forever. "
     "Exception: if your output is a code change that needs human review "
-    "before counting as merged/done (most coding tasks), drop the "
-    "structured metadata (changed_files / tests_run / diff_path) into a "
+    "before counting as merged/done (most coding tasks), open a PR, drop "
+    "the structured metadata (changed_files / tests_run / pr_url) into a "
     "`kanban_comment` first, then end with "
-    "`kanban_block(reason=\"review-required: <one-line summary>\")` so a "
-    "reviewer can approve+unblock or request changes. Reviewing-then-"
-    "completing is more honest than auto-completing work that still needs "
-    "eyes on it.\n"
+    "`kanban_review(reason=\"PR <url>, AC: <one-line>\")`. That hands "
+    "the card to the `sdlc-review` auto-reviewer, which runs mechanical "
+    "checks and on a clean pass promotes to `human_review` for Sahil to "
+    "merge and approve (the auto-reviewer does NOT merge — Sahil merges "
+    "every PR himself). The old `kanban_block(reason=\"review-required: "
+    "...\")` pattern is forbidden — use `kanban_review` for PR handoffs and "
+    "reserve `kanban_block` for genuine blockers (missing creds, paywalled "
+    "source, needs-smoke-test, etc.).\n"
     "6. **If follow-up work appears, create it; don't do it.** Use "
     "`kanban_create(title=..., assignee=<right-profile>, parents=[your-task-id])` "
     "to spawn a child task for the appropriate specialist profile instead of "

cli.py

@@ -16020,7 +16020,7 @@ def _block(reason: str) -> None:
             except Exception:
                 pass
 
-    _run_loop(
+    loop_result = _run_loop(
         task_id=task_id,
         goal_text=goal_text,
         run_turn=_run_turn,
@@ -16030,6 +16030,61 @@ def _block(reason: str) -> None:
         first_response=first_response or "",
         log=lambda m: logger.info("%s", m),
     )
+    if not isinstance(loop_result, dict):
+        return
+    if loop_result.get("outcome") != "finalization_recovery":
+        return
+
+    recovery_contract = str(loop_result.get("recovery_contract") or "").strip()
+    recovery_reason = str(loop_result.get("reason") or "").strip()
+    run_id_raw = (_os.environ.get("HERMES_KANBAN_RUN_ID") or "").strip()
+    expected_run_id = int(run_id_raw) if run_id_raw.isdigit() else None
+    c = _kb.connect()
+    try:
+        saved = _kb.record_finalization_recovery(
+            c,
+            task_id,
+            reason=recovery_reason,
+            contract=recovery_contract,
+            expected_run_id=expected_run_id,
+        )
+        if saved:
+            logger.info(
+                "kanban goal loop: recorded finalization recovery contract for "
+                "task %s (run_id=%s)",
+                task_id,
+                expected_run_id,
+            )
+            return
+        task_after = _kb.get_task(c, task_id)
+        if task_after is not None and task_after.status in {
+            "done",
+            "blocked",
+            "review",
+            "human_review",
+            "triage",
+            "todo",
+            "scheduled",
+        }:
+            logger.info(
+                "kanban goal loop: finalization recovery contract became a "
+                "no-op for task %s (already in %s)",
+                task_id,
+                task_after.status,
+            )
+        else:
+            logger.info(
+                "kanban goal loop: skipped finalization recovery contract for "
+                "task %s due to ownership/state drift (status=%s, run_id=%s)",
+                task_id,
+                task_after.status if task_after is not None else None,
+                expected_run_id,
+            )
+    finally:
+        try:
+            c.close()
+        except Exception:
+            pass
 
 
 def main(