@defend-tech/opencode-optima 0.1.61 → 0.1.63

package/Agents_Common.md

@@ -19,7 +19,7 @@
 - ClickUp delivery types are `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, and `Respuesta del formulario` unless converted or linked.
 - WPM estimates `Story Points` during `plan` and re-estimates on material plan changes.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima-provided fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and code instead of personal names.
-- ClickUp status actions: `backlog` ignore, `plan` plan plus remove the PM assignee before assigning `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. After validation, Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
+- ClickUp status actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy, `in progress` execute, `validation` Tech Lead + Validator/QA gates, and parent post-approval merge automation. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, or partial-phase stops. Validator/QA may merge validated subtasks into the parent branch without CTO/PO approval; parent human `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code. `completed`/`Closed` ignore unless reopened.
 - One shared-worktree `implementation` task may be active; ClickUp-first delivery should use task-specific worktrees/branches.
 - Agent messages must start with `[Agent Message] From: <agent_name> To: <agent_name>`.
 - Clarifications, blockers, dependencies, and reviews go through PMA.

package/Agents_Common.prompt.md

@@ -21,7 +21,7 @@
 - ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted or linked.
 - WPM estimates `Story Points` during `plan` and re-estimates on material plan changes.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
-- ClickUp-first statuses: `backlog` ignore, `plan` plan plus remove the PM assignee before assigning `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
+- ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy, `in progress` execute, `validation` Tech Lead + Validator/QA gates, and parent post-approval merge automation. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, or partial-phase stops. Validator/QA may merge validated subtasks into the parent branch without CTO/PO approval; parent human `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code. `completed`/`Closed` ignore unless reopened.
 - Signed agent-to-agent messages must start exactly: `[Agent Message] From: <agent_name> To: <agent_name>`.
 - Direct all clarifications, blockers, and specialist questions through PMA unless explicitly in a direct discussion-capable role.
 - Read relevant docs/tasks fully when they govern the current work. Prefer targeted CodeMap navigation before broad source search.

package/assets/agents/workflow_product_manager.md

@@ -15,7 +15,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - `workflow_product_manager` owns delivery ops: ClickUp status, routing/handoffs, decomposition, validation gates, Git worktree/branch/PR flow, evidence, and closure.
 - `product_manager` remains compatibility/product/planning PMA for requirements, SCRs, product truth, rough pre-estimation, and default/legacy orchestration when ClickUp-first is not opted in. Do not remove, shadow, or break `product_manager`.
 - ClickUp Docs/tasks are source of truth for intent, state, comments, assignment, validation, and closure. Use the ClickUp skill plus ClickUp MCP/tools for every read/write/comment/field/status/assignment/dashboard action.
-- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If a task is PM-assigned, do not stop until you have posted a human-visible ClickUp task comment, removed yourself, and assigned `CTO` plus `PO` or the next owner.
+- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If a task is PM-assigned, do not stop until you have posted a human-visible ClickUp task comment, removed yourself, and assigned the next non-human owner; assign `CTO`/`PO` only under the explicit human approval allowlist.
 - OpenCode session output is not visible to humans unless you post it to ClickUp. Before any stop, blocker, error, clarification, missing tool, or handoff pause, post a task comment. If ClickUp writes are unavailable, record the blocker/manual-sync payload in task/evidence and still report that blocker before stopping.
 - Keep raw logs in evidence; ClickUp gets summaries, paths/links, or excerpts only.
 
@@ -33,18 +33,19 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 
 - Register only when Optima opt-in ClickUp webhook mode is configured and active/valid.
 - Webhook wakeup requires signed `X-Signature` HMAC SHA-256 verification, duplicate suppression, PM assignment/non-terminal status checks, and comment mention gating for `@Defend Tech Product Manager`.
-- If ClickUp `agent_metadata` lacks a session id, Optima creates a session and writes `ses_...`; if a stored session is missing in OpenCode, Optima logs locally and comments on ClickUp with host, datetime, and missing id instead of replacing it.
+- Webhook routing is successful only after the worktree is OpenChamber-visible, an OpenCode `workflow_product_manager` session exists in that exact worktree directory, and prompt delivery/admission is verified. Worktree visibility alone is a launch failure, not successful routing.
 - Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`. Ignore unless converted/linked to delivery: `Idea`, legacy `Backlog`, `Hito`, `Nota de reunión`, `Respuesta del formulario`. Treat `Backlog` task type as `Idea`, not `backlog` status.
 - Branch-safe slugs: `Tarea` -> `tarea`, `Bug` -> `bug`, `Doc` -> `doc`, `PoC` -> `poc`. Unknown task type: pause and ask PMA/PO for clarification.
 
 ## Status Actions
 
 - Human registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in the task worktree, use the Optima-provided Human Role Fallback Registry and configured ClickUp IDs instead of blocking solely on the missing repo-local file.
+- Human approval allowlist: never assign `CTO`/`PO` except for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign them for generic handoff, routine validation, cleanup, subtasks, or partial-phase stops.
 - `backlog`: ignore until prioritized.
-- `plan`: clarify AC/SCR/test strategy with Validator/QA; decompose; create/update Definition; estimate Story Points; remove PM assignee first; assign `CTO` + `PO` or next owner; target zero PM-assigned tasks.
-- `in progress`: execute through the assigned delivery agent or workflow runner.
-- `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks. Validator/QA may merge validated subtasks into parent branch without `CTO`/`PO`; validated parents stay in `validation`, assigned to `CTO`/`PO`, ready for approval.
-- `merge`: only after `CTO`/`PO` move parent from `validation` to `merge`; Validator/QA then merges parent PR into `dev`. Conflicts or merge failures return the affected item to `in progress`.
+- `plan`: clarify AC/SCR/test strategy with Validator/QA; decompose; create/update Definition; estimate Story Points; remove PM assignee first; assign the next delivery owner. Assign `CTO`/`PO` only for parent tasks with clear questions already posted in ClickUp comments; subtasks are planned and executed end-to-end without CTO/PO assignment.
+- `in progress`: execute through the assigned delivery agent or workflow runner. Escalate to `CTO`/`PO` only when genuinely blocked by missing credentials, permissions, external tools, or access; do not stop with phase language such as "I reached phase 1".
+- `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks. Validator/QA may merge validated subtasks into parent branch without `CTO`/`PO`; validated parent tasks may assign `CTO`/`PO` only when a functional preview URL is provided.
+- `merge`: parent-only post-approval automation after a human comments `Approved`; remove human assignees, assign yourself or the merge owner, merge parent PR into `dev`, clean workspaces/worktrees/branches, push to `dev`, and ensure the dev environment contains the code. Conflicts or merge failures return the affected item to `in progress`.
 - `completed` / `Closed`: no execution unless explicitly reopened.
 
 ## Git, Worktree, PR
@@ -58,18 +59,18 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - Unrelated active tasks in `.optima/tasks/current.md` must not block planning; move to/create the correct task worktree instead.
 - Parent setup pulls remote once; after parent branch creation, subtasks can trust the parent local branch without continuous remote polling.
 - Branches: parent `<clickup-task-type>/<parent-task-id>`; subtask `<clickup-task-type>/<parent-task-id>-subtask-<subtask-id>`; pending planned subtasks `<clickup-task-type>/<parent-task-id>-pending-<title-slug>`; PoC always `poc/<clickup-task-id>` and remains there unless productized later.
-- PR targets/start points: subtask -> parent branch and starts from the parent branch; if parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first; parent -> `dev` only after Tech Lead + Validator/QA pass and `CTO`/`PO` move to `merge`; release -> `dev` to `main` only after explicit approval.
+- PR targets/start points: subtask -> parent branch and starts from the parent branch; if parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first; parent -> `dev` only after Tech Lead + Validator/QA pass and a parent-validation human `Approved` comment triggers merge automation; release -> `dev` to `main` only after explicit approval.
 - Preserve user work and unrelated dirty files. Stop and ask if unexpected changes appear.
 
 ## Operating Style
 
 - Orchestrate; do not silently implement specialist work yourself.
 - Delegate through ClickUp task/subtask assignment or task-specific specialist sessions with ClickUp context, AC, evidence, sync duties, branch target, Story Points, Definition link, final Documentation needs, and validation requirements.
-- Never abandon a PM-assigned task: keep working until unblocked and handed off, or post the stop/blocker/clarification/error as a ClickUp comment, remove Workflow/Product Manager, and assign `CTO` plus `PO` or next owner.
+- Never abandon a PM-assigned task: keep working until unblocked and handed off, or post the stop/blocker/clarification/error as a ClickUp comment, remove Workflow/Product Manager, and assign the next delivery owner; assign `CTO`/`PO` only under the human approval allowlist.
 - On pickup, rewrite the ClickUp task description with the complete current description of what must be done; do not rely on status comments.
 - At plan completion, rewrite the ClickUp task description again with the complete final plan/Definition, distinct from the plan comment.
 - Estimate Story Points during `plan`, write them to ClickUp `Story Points`, and re-estimate when material plan changes alter scope/risk.
-- Before assigning `CTO`/`PO` or any next owner, remove the PM assignee and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued.
+- Before assigning any next owner, remove the PM assignee and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued; when the next owner is `CTO`/`PO`, verify the allowlist condition and comment evidence first.
 - Final handoffs must include Summary, Work Performed, AC Coverage, Documentation Impact, Open Risks, Recommended Next Step, verification results, and commit/PR status.
 
 <include:plugin:Agents_Common.md>

package/dist/index.js

@@ -8621,13 +8621,6 @@ var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
 var CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS = 8e3;
 var CLICKUP_WEBHOOK_SIGNAL_STATE = Symbol.for("opencode-optima.clickup-webhook.signal-state");
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
-var objectIdentityMap = /* @__PURE__ */ new WeakMap();
-var objectIdentitySequence = 0;
-function objectIdentity(value) {
-  if (!value || typeof value !== "object" && typeof value !== "function") return String(value ?? "");
-  if (!objectIdentityMap.has(value)) objectIdentityMap.set(value, `obj_${++objectIdentitySequence}`);
-  return objectIdentityMap.get(value);
-}
 function isRootDirectory(candidate) {
   const resolved = path5.resolve(candidate);
   return resolved === path5.parse(resolved).root;
@@ -8753,7 +8746,6 @@ function hasActionableClickUpRoute(result = {}) {
   if (!result.sessionId) return false;
   if (result.action === "message_delivery_failed" || result.action === "error") return false;
   if (result.deliveryVerification?.ok === false) return false;
-  if (result.deliveryVerification?.method === "prompt_admission") return false;
   return true;
 }
 function determineClickUpMergeAuthority({ isSubtask = false, clickupStatus = "", validationPassed = false, mergeFailed = false, finalApprovalRoles = CLICKUP_FINAL_APPROVER_ROLES, humansRegistry } = {}) {
@@ -8845,9 +8837,9 @@ var CLICKUP_REQUIRED_SUMMARY_SECTIONS = [
 ];
 var CLICKUP_RAW_LOG_SECTION_NAMES = /* @__PURE__ */ new Set(["Raw Logs", "Logs", "Full Logs", "Command Output", "Transcript"]);
 var CLICKUP_TRANSITIONS = /* @__PURE__ */ new Map([
-  ["plan->in progress", { status: "in progress", assignFinalApprovers: true, comment: "Plan complete; assigning CTO+PO for visibility and moving to implementation." }],
+  ["plan->in progress", { status: "in progress", comment: "Plan complete; moving to implementation without generic CTO/PO assignment." }],
   ["in progress->validation", { status: "validation", comment: "Implementation complete; ready for validation." }],
-  ["validation->merge", { status: "merge", assignFinalApprovers: true, comment: "Validation passed; parent task is ready for CTO+PO merge approval." }],
+  ["validation->merge", { status: "merge", assignFinalApprovers: true, parentOnlyFinalApproval: true, comment: "Parent validation passed with a functional preview URL; ready for CTO/PO approval flow." }],
   ["validation->in progress", { status: "in progress", comment: "Validation failed; returning to implementation." }],
   ["merge->completed", { status: "completed", comment: "Merge complete; closing delivery task." }],
   ["completed->in progress", { status: "in progress", comment: "Task reopened; returning to implementation." }],
@@ -9586,11 +9578,14 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
   const key = `${from}->${to}`;
   const rule = CLICKUP_TRANSITIONS.get(key);
   if (!rule) return { ok: false, dryRun: true, message: `Transition not allowed: ${key}` };
-  const assignsFinalApprovers = rule.assignFinalApprovers === true;
-  const requiresPlanCompletionContract = from === "plan" && assignsFinalApprovers;
+  const assignsFinalApprovers = rule.assignFinalApprovers === true && !(rule.parentOnlyFinalApproval && isSubtask);
+  const requiresPlanCompletionContract = from === "plan" && to === "in progress";
   const definitionContent = compactMarkdownValue(definition);
   const description = compactMarkdownValue(planDescription);
   const validationErrors = [];
+  if (rule.parentOnlyFinalApproval && isSubtask) {
+    validationErrors.push("Subtasks must not use the parent final-approval transition; merge validated subtasks directly into the parent branch/workspace.");
+  }
   if (assignsFinalApprovers && !isRealClickUpAssigneeId(productManagerAssignee) && requireProductManagerAssignee !== false) {
     validationErrors.push("productManagerAssignee must be the configured ClickUp PM assignee ID before assigning final approvers.");
   }
@@ -9599,10 +9594,10 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
   }
   if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
-  const finalApprovers = rule.assignFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
+  const finalApprovers = assignsFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
   const explicitRemovals = (removeAssignees || []).filter(Boolean);
   const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
-  const removalTargets = rule.assignFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
+  const removalTargets = assignsFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
   const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))].filter((assignee) => !removalTargets.includes(assignee));
   const authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
   const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
@@ -9617,7 +9612,7 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
       assignment_delta: {
         add: assigned,
         remove: removalTargets,
-        objective: rule.assignFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
+        objective: assignsFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
       },
       comment: rule.comment,
       description,
@@ -10075,11 +10070,17 @@ function createTestClickUpApiClient(config) {
     __metadata: metadata
   };
 }
-function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
-  const webhook = response?.webhook || response?.data || response || {};
+function clickUpWebhookRemoteInactiveReason(webhook = {}) {
   const healthStatus = String(webhook.health?.status || webhook.health_status || "").trim().toLowerCase();
   const status = String(webhook.status || webhook.state || "").trim().toLowerCase();
-  const active = webhook.active !== false && !["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status) && !["failed", "failing", "unhealthy", "error", "errored", "suspended", "paused"].includes(healthStatus);
+  if (["suspended", "paused", "failed", "failing", "unhealthy", "error", "errored"].includes(healthStatus)) return `remote_health_${healthStatus}`;
+  if (["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status)) return `remote_status_${status}`;
+  if (webhook.active === false) return "remote_inactive";
+  return "";
+}
+function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
+  const webhook = response?.webhook || response?.data || response || {};
+  const active = !clickUpWebhookRemoteInactiveReason(webhook);
   return sanitizeClickUpWebhookState({
     active,
     webhookId: webhook.id || webhook.webhook_id || webhook.webhookId,
@@ -10105,20 +10106,44 @@ function clickUpWebhookLocationCompatible(webhook = {}, config = {}) {
   }
   return true;
 }
+function clickUpWebhookEventsCompatible(webhook = {}, config = {}) {
+  if (!Array.isArray(webhook.events) || webhook.events.length === 0) return false;
+  const actualEvents = new Set(webhook.events);
+  return [...new Set(config?.webhook?.events || [])].every((event) => actualEvents.has(event));
+}
+function clickUpWebhookRemoteCompatibilityReason(webhook = {}, config = {}) {
+  if (!clickUpWebhookLocationCompatible(webhook, config)) return "remote_location_mismatch";
+  if (!clickUpWebhookEventsCompatible(webhook, config)) return "remote_events_mismatch";
+  return "";
+}
+function isClickUpWebhookRemoteSelfHealableReason(reason = "") {
+  const normalized = String(reason || "");
+  return normalized === "remote_inactive" || normalized.startsWith("remote_health_") || normalized.startsWith("remote_status_");
+}
 async function findReusableClickUpWebhook(config, clickupClient = null, existingState = null) {
   if (!clickupClient?.listWebhooks) return null;
   const listed = await clickupClient.listWebhooks({ teamId: config.teamId });
-  let secretlessMatch = null;
+  let incompatibleMatch = null;
   for (const webhook of clickUpWebhookListItems(listed)) {
     const remote = normalizeClickUpWebhookApiResponse(webhook, config);
     if (remote.publicUrl !== config.webhook.publicUrl) continue;
-    if (!clickUpWebhookLocationCompatible(webhook, config)) continue;
+    const compatibilityReason = clickUpWebhookRemoteCompatibilityReason(webhook, config);
+    if (compatibilityReason) {
+      if (compatibilityReason === "remote_events_mismatch" && remote.webhookId && !incompatibleMatch) incompatibleMatch = { ...remote, active: false, reason: compatibilityReason };
+      continue;
+    }
     const existingSecret = existingState?.webhookId === remote.webhookId ? existingState.secret : "";
     const reusable = remote.secret ? remote : { ...remote, secret: existingSecret };
     if (isClickUpWebhookStateActive(reusable, config)) return reusable;
-    if (remote.webhookId && !secretlessMatch) secretlessMatch = { ...remote, active: false, reason: "remote_secret_unavailable" };
+    if (remote.webhookId && !incompatibleMatch) {
+      incompatibleMatch = {
+        ...remote,
+        active: false,
+        reason: remote.active === false ? clickUpWebhookRemoteInactiveReason(webhook) || "remote_inactive" : "remote_secret_unavailable"
+      };
+    }
   }
-  return secretlessMatch;
+  return incompatibleMatch;
 }
 async function validateClickUpWebhookState(state, config, clickupClient = null, { allowRemoteUnhealthyLocalRecovery = false } = {}) {
   if (!isClickUpWebhookStateActive(state, config)) return { valid: false, reason: "state_incomplete" };
@@ -10133,7 +10158,7 @@ async function validateClickUpWebhookState(state, config, clickupClient = null,
     }
     const localStateValidation = await validateClickUpWebhookState(state, config, null);
     if (allowRemoteUnhealthyLocalRecovery && localStateValidation.valid && remote.webhookId === state.webhookId) {
-      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && [...new Set(config.webhook.events || [])].every((event) => new Set(remote.events || []).has(event));
+      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && !clickUpWebhookRemoteCompatibilityReason(match, config);
       if (remoteConfigMatches) {
         return {
           ...localStateValidation,
@@ -10158,12 +10183,18 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
   const { config } = validation;
   const existing = existingState ? sanitizeClickUpWebhookState(existingState, config) : readClickUpWebhookState(worktree, config);
   const existingValidation = await validateClickUpWebhookState(existing, config, clickupClient, { allowRemoteUnhealthyLocalRecovery: true });
-  if (existingValidation.valid) {
+  const canReplaceUnhealthyExisting = existingValidation.mode === "local_state_remote_unhealthy" && existingValidation.remote?.webhookId && clickupClient?.deleteWebhook && clickupClient?.createWebhook;
+  if (existingValidation.valid && !canReplaceUnhealthyExisting) {
     const state = writeClickUpWebhookState(worktree, { ...existingValidation.state, recentEventKeys: existing.recentEventKeys || [] }, config);
     clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: existingValidation.mode });
     return { active: true, valid: true, mode: existingValidation.mode, limitation: existingValidation.limitation, state };
   }
-  const reusableRemote = await findReusableClickUpWebhook(config, clickupClient, existing);
+  const reusableRemote = canReplaceUnhealthyExisting ? {
+    ...existingValidation.remote,
+    active: false,
+    secret: existingValidation.remote.secret || existing.secret,
+    reason: clickUpWebhookRemoteInactiveReason(existingValidation.remote) || existingValidation.reason || "remote_unhealthy_self_heal"
+  } : await findReusableClickUpWebhook(config, clickupClient, existing);
   if (reusableRemote) {
     if (isClickUpWebhookStateActive(reusableRemote, config)) {
       const state = writeClickUpWebhookState(worktree, { ...reusableRemote, recentEventKeys: existing.recentEventKeys || [] }, config);
@@ -10171,10 +10202,31 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
       clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: mode2 });
       return { active: true, valid: true, mode: mode2, state };
     }
-    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
-    return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    if (reusableRemote.active === false && reusableRemote.reason !== "remote_secret_unavailable") {
+      if (!isClickUpWebhookRemoteSelfHealableReason(reusableRemote.reason)) {
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_incompatible" });
+        return { active: false, valid: false, reason: reusableRemote.reason || "remote_incompatible", state: existing, remote: reusableRemote };
+      }
+      if (clickupClient?.deleteWebhook && clickupClient?.createWebhook) {
+        const deleteResult = await deleteClickUpWebhookBestEffort({ webhookId: reusableRemote.webhookId, clickupClient, worktree, reason: reusableRemote.reason || "remote_unhealthy_self_heal" });
+        if (deleteResult.ok) {
+          if (existing.webhookId === reusableRemote.webhookId) markClickUpWebhookInactive(worktree, existing, config);
+        } else {
+          const reason = deleteResult.reason || "remote_unhealthy_delete_failed";
+          clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+          return { active: false, valid: false, reason, state: existing, remote: reusableRemote, deleteResult };
+        }
+      } else {
+        const reason = clickupClient?.deleteWebhook ? "remote_unhealthy_create_unavailable" : "remote_unhealthy_delete_unavailable";
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+        return { active: false, valid: false, reason, state: existing, remote: reusableRemote };
+      }
+    } else {
+      clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
+      return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    }
   }
-  if (existing.webhookId && clickupClient?.deleteWebhook) {
+  if (existing.webhookId && existing.webhookId !== reusableRemote?.webhookId && clickupClient?.deleteWebhook) {
     await deleteClickUpWebhookBestEffort({ webhookId: existing.webhookId, clickupClient, worktree, reason: existingValidation.reason || "startup_self_heal" });
     markClickUpWebhookInactive(worktree, existing, config);
   }
@@ -10502,12 +10554,16 @@ function clearClickUpPendingSessionMetadata(metadata, metadataKey) {
   delete cursor[parts[parts.length - 1]];
   return JSON.stringify(sortJsonValue(root), null, 2);
 }
-async function openCodeSessionExists(client, sessionId) {
+function withOptionalDirectoryQuery(payload, directory) {
+  if (!directory) return payload;
+  return { ...payload, query: { ...payload.query || {}, directory } };
+}
+async function openCodeSessionExists(client, sessionId, { directory = "" } = {}) {
   const getAttempts = [
-    { path: { id: sessionId } },
-    { path: { sessionID: sessionId } },
-    { sessionID: sessionId },
-    { id: sessionId }
+    withOptionalDirectoryQuery({ path: { id: sessionId } }, directory),
+    withOptionalDirectoryQuery({ path: { sessionID: sessionId } }, directory),
+    directory ? { sessionID: sessionId, directory } : { sessionID: sessionId },
+    directory ? { id: sessionId, directory } : { id: sessionId }
   ];
   if (typeof client?.session?.get === "function") {
     for (const attempt of getAttempts) {
@@ -10519,10 +10575,10 @@ async function openCodeSessionExists(client, sessionId) {
     }
   }
   const messageAttempts = [
-    { path: { id: sessionId }, query: { limit: 1 } },
-    { path: { sessionID: sessionId }, query: { limit: 1 } },
-    { sessionID: sessionId, limit: 1 },
-    { id: sessionId, limit: 1 }
+    { path: { id: sessionId }, query: { limit: 1, ...directory ? { directory } : {} } },
+    { path: { sessionID: sessionId }, query: { limit: 1, ...directory ? { directory } : {} } },
+    directory ? { sessionID: sessionId, directory, limit: 1 } : { sessionID: sessionId, limit: 1 },
+    directory ? { id: sessionId, directory, limit: 1 } : { id: sessionId, limit: 1 }
   ];
   if (typeof client?.session?.messages === "function") {
     for (const attempt of messageAttempts) {
@@ -10926,6 +10982,17 @@ async function verifyOpenCodeSessionEventDelivery(client, { sessionId, directory
   }
   return { ok: false, reason: lastError };
 }
+async function postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason, source } = {}) {
+  if (typeof clickupClient?.postTaskComment !== "function") return { ok: false, skipped: true, reason: "post_comment_unavailable" };
+  try {
+    await clickupClient.postTaskComment({ taskId, comment: `Optima launch failure: ${reason || "launch_failed"}. Worktree visibility alone is not successful routing; Optima requires an OpenCode session plus verified prompt admission/delivery.` });
+    appendClickUpWebhookLocalLog(worktree, { type: "launch_failure_comment_posted", taskId, reason, source });
+    return { ok: true };
+  } catch (error) {
+    appendClickUpWebhookLocalLog(worktree, { type: "launch_failure_comment_failed", taskId, reason, source, message: error.message });
+    return { ok: false, error: error.message };
+  }
+}
 async function applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason, source, tagName = CLICKUP_BLOCKER_TAG_NAME } = {}) {
   if (typeof clickupClient?.addTaskTag !== "function") {
     appendClickUpWebhookLocalLog(worktree, { type: "blocker_tag_unavailable", taskId, reason, source, tagName });
@@ -10955,7 +11022,17 @@ function openCodeBlockingPromptVerification(result, sessionId) {
 }
 async function deliverClickUpSessionEventWithVerification({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, sessionId, agent, text, directory, opencodeBaseUrl, directPrompt = false, acceptPromptAdmission = false, eventMarkers = [], verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery, applyBlockerOnFailure = true } = {}) {
   const beforeMessages = await readOpenCodeSessionMessages(openCodeClient, { sessionId, directory, limit: 50 }).catch(() => null);
-  const sendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: directPrompt, allowDirectFallback: directPrompt });
+  let sendResult;
+  try {
+    sendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: directPrompt, allowDirectFallback: directPrompt });
+  } catch (error) {
+    const reason2 = error.message || "message_delivery_failed";
+    appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason: reason2, fallbackAttempted: false });
+    if (!applyBlockerOnFailure) return { ok: false, action: "message_delivery_failed", reason: reason2, taskId, sessionId, fallbackAttempted: false };
+    const blocker2 = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: reason2, source: "delivery_send_failed" });
+    const launchFailureComment2 = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: reason2, source: "delivery_send_failed" });
+    return { ok: false, action: "message_delivery_failed", reason: reason2, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2, launchFailureComment: launchFailureComment2 };
+  }
   let blockingPromptVerification = null;
   let admissionVerification = null;
   try {
@@ -10965,7 +11042,8 @@ async function deliverClickUpSessionEventWithVerification({ openCodeClient, send
     appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason: error.message, fallbackAttempted: false });
     if (!applyBlockerOnFailure) return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false };
     const blocker2 = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: error.message, source: "delivery_admission_failed" });
-    return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2 };
+    const launchFailureComment2 = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: error.message, source: "delivery_admission_failed" });
+    return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2, launchFailureComment: launchFailureComment2 };
   }
   if (blockingPromptVerification) return { ok: true, verification: blockingPromptVerification, admissionVerification: null, fallback: false };
   if (admissionVerification && acceptPromptAdmission) {
@@ -10980,7 +11058,8 @@ async function deliverClickUpSessionEventWithVerification({ openCodeClient, send
   appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason, fallbackAttempted: false, httpFallbackDisabled: Boolean(opencodeBaseUrl) });
   if (!applyBlockerOnFailure) return { ok: false, action: "message_delivery_failed", reason, taskId, sessionId, fallbackAttempted: false };
   const blocker = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason, source: "delivery_verification_failed" });
-  return { ok: false, action: "message_delivery_failed", reason, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker };
+  const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason, source: "delivery_verification_failed" });
+  return { ok: false, action: "message_delivery_failed", reason, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker, launchFailureComment };
 }
 async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, staleSessionId, sessionTitle, taskRoute, metadataWithRouting, config, prompt, eventMarkers = [], deliveryEvidencePath, evidencePath, eventKey, createSession, verifySessionEventDelivery } = {}) {
   appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_started", taskId, staleSessionId, worktree: taskRoute?.worktree });
@@ -10990,12 +11069,14 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   } catch (error) {
     appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_create_failed", taskId, staleSessionId, message: error.message });
     const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
-    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
+    const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
+    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, launchFailureComment, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
   }
   if (!String(replacementSessionId || "").startsWith("ses_")) {
     appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_create_invalid", taskId, staleSessionId, replacementSessionId });
     const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
-    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
+    const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
+    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, launchFailureComment, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
   }
   const replacementDelivery = await deliverClickUpSessionEventWithVerification({
     openCodeClient,
@@ -11017,7 +11098,8 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   if (!replacementDelivery.ok) {
     appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_delivery_failed", taskId, staleSessionId, replacementSessionId, reason: replacementDelivery.reason });
     const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: replacementDelivery.reason || "replacement_delivery_failed", source: "pm_session_recovery" });
-    return { ...replacementDelivery, sessionId: staleSessionId, replacementSessionId, replacementAttempted: true, blockerTag, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
+    const launchFailureComment = replacementDelivery.launchFailureComment || await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: replacementDelivery.reason || "replacement_delivery_failed", source: "pm_session_recovery" });
+    return { ...replacementDelivery, sessionId: staleSessionId, replacementSessionId, replacementAttempted: true, blockerTag, launchFailureComment, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
   }
   const replacementMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(metadataWithRouting, config.routing.metadataKey, replacementSessionId), config.routing.metadataKey);
   await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: replacementMetadata });
@@ -11301,8 +11383,26 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
-      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: taskRoute.worktree, agent: config.routing.targetAgent });
-      if (!String(pendingSessionId || "").startsWith("ses_")) return { ok: false, action: "error", reason: "session_create_failed", taskId };
+      try {
+        pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: taskRoute.worktree, agent: config.routing.targetAgent });
+      } catch (error) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pm_session_create_failed", taskId, worktree: taskRoute.worktree, message: error.message });
+        const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        return finish({ ok: false, action: "error", reason: "session_create_failed", taskId, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, blockerTag, launchFailureComment });
+      }
+      if (!String(pendingSessionId || "").startsWith("ses_")) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pm_session_create_invalid", taskId, worktree: taskRoute.worktree, sessionId: pendingSessionId || null });
+        const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        return finish({ ok: false, action: "error", reason: "session_create_failed", taskId, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, blockerTag, launchFailureComment });
+      }
+      if (!await sessionExists(openCodeClient, pendingSessionId, { directory: taskRoute.worktree })) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pm_session_create_directory_unverified", taskId, worktree: taskRoute.worktree, sessionId: pendingSessionId });
+        const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "session_directory_unverified", source: "route_create_session" });
+        const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "session_directory_unverified", source: "route_create_session" });
+        return finish({ ok: false, action: "error", reason: "session_directory_unverified", taskId, sessionId: pendingSessionId, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, blockerTag, launchFailureComment });
+      }
       if (saveState) {
         saveState({
           ...state,
@@ -11318,7 +11418,20 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
       throw error;
     }
     const delivery = await deliverClickUpSessionEventWithVerification({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, sessionId: pendingSessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl, directPrompt: config.opencode?.promptDelivery === "http", acceptPromptAdmission: config.opencode?.acceptPromptAdmission === true, eventMarkers: [taskId, eventType], verifySessionEventDelivery });
-    if (!delivery.ok) return finish({ ...delivery, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path });
+    if (!delivery.ok) {
+      const failedMetadata = clearClickUpPendingSessionMetadata(metadataWithRouting, config.routing.metadataKey);
+      let pendingCleared = false;
+      try {
+        await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: failedMetadata });
+        pendingCleared = true;
+      } catch (error) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pending_session_clear_failed", taskId, sessionId: pendingSessionId, message: error.message });
+      }
+      const { [taskId]: _failedPending, ...remainingPending2 } = stateToPersist.pendingSessions || {};
+      stateToPersist = { ...stateToPersist, pendingSessions: remainingPending2 };
+      appendClickUpWebhookLocalLog(worktree, { type: "pending_session_delivery_failed", taskId, sessionId: pendingSessionId, reason: delivery.reason || "message_delivery_failed", pendingCleared });
+      return finish({ ...delivery, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, pendingCleared });
+    }
     const nextMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(pendingMetadata, config.routing.metadataKey, pendingSessionId), config.routing.metadataKey);
     await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
     const { [taskId]: _completedPending, ...remainingPending } = stateToPersist.pendingSessions || {};
@@ -11326,7 +11439,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     return finish({ ok: true, action: "created_session", taskId, sessionId: pendingSessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryAdmission: delivery.admissionVerification, deliveryFallback: delivery.fallback, deliveryAttempts: delivery.fallback ? 2 : 1 });
   }
   const sessionId = String(existingSessionId);
-  if (await sessionExists(openCodeClient, sessionId)) {
+  if (await sessionExists(openCodeClient, sessionId, { directory: taskRoute.worktree })) {
     if (typeof clickupClient?.updateTaskMetadata === "function") await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: metadataWithRouting });
     const delivery = await deliverClickUpSessionEventWithVerification({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, sessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl, directPrompt: config.opencode?.promptDelivery === "http", acceptPromptAdmission: config.opencode?.acceptPromptAdmission === true, eventMarkers: [taskId, eventType], verifySessionEventDelivery, applyBlockerOnFailure: false });
     if (!delivery.ok) {
@@ -11454,6 +11567,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
         routed.undelivered += 1;
         appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: result?.action || "error", sessionId: routeSummary.sessionId, reason: result.reason || "startup_reconciliation_route_failed" });
         if (!result.blockerTag) await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: result.reason || "startup_reconciliation_route_failed", source: "startup_reconciliation_task" });
+        if (!result.launchFailureComment) await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: result.reason || "startup_reconciliation_route_failed", source: "startup_reconciliation_task" });
       } else {
         routed.undelivered += 1;
         appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: routeSummary.action, sessionId: routeSummary.sessionId, reason: "route_not_actionable" });
@@ -11561,14 +11675,13 @@ function clickUpListenerKey(config) {
 }
 function clickUpListenerFingerprint({ config, state, worktree, clickupClient, openCodeClient } = {}) {
   return JSON.stringify({
+    teamId: config?.teamId || "",
     publicUrl: config?.webhook?.publicUrl || "",
     path: clickUpWebhookExpectedPath(config),
-    worktree: path5.resolve(worktree || process.cwd()),
+    location: config?.webhook?.location || {},
     webhookId: state?.webhookId || "",
     secret: state?.secret || "",
-    events: config?.webhook?.events || [],
-    clickupClient: objectIdentity(clickupClient),
-    openCodeClient: objectIdentity(openCodeClient)
+    events: config?.webhook?.events || []
   });
 }
 function startClickUpWebhookListener({ config, state, worktree, clickupClient, openCodeClient, listenerRegistry = activeClickUpWebhookListeners } = {}) {

package/dist/sanitize_cli.js

@@ -8628,13 +8628,6 @@ var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
 var CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS = 8e3;
 var CLICKUP_WEBHOOK_SIGNAL_STATE = Symbol.for("opencode-optima.clickup-webhook.signal-state");
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
-var objectIdentityMap = /* @__PURE__ */ new WeakMap();
-var objectIdentitySequence = 0;
-function objectIdentity(value) {
-  if (!value || typeof value !== "object" && typeof value !== "function") return String(value ?? "");
-  if (!objectIdentityMap.has(value)) objectIdentityMap.set(value, `obj_${++objectIdentitySequence}`);
-  return objectIdentityMap.get(value);
-}
 function isRootDirectory(candidate) {
   const resolved = path5.resolve(candidate);
   return resolved === path5.parse(resolved).root;
@@ -8760,7 +8753,6 @@ function hasActionableClickUpRoute(result = {}) {
   if (!result.sessionId) return false;
   if (result.action === "message_delivery_failed" || result.action === "error") return false;
   if (result.deliveryVerification?.ok === false) return false;
-  if (result.deliveryVerification?.method === "prompt_admission") return false;
   return true;
 }
 function determineClickUpMergeAuthority({ isSubtask = false, clickupStatus = "", validationPassed = false, mergeFailed = false, finalApprovalRoles = CLICKUP_FINAL_APPROVER_ROLES, humansRegistry } = {}) {
@@ -8852,9 +8844,9 @@ var CLICKUP_REQUIRED_SUMMARY_SECTIONS = [
 ];
 var CLICKUP_RAW_LOG_SECTION_NAMES = /* @__PURE__ */ new Set(["Raw Logs", "Logs", "Full Logs", "Command Output", "Transcript"]);
 var CLICKUP_TRANSITIONS = /* @__PURE__ */ new Map([
-  ["plan->in progress", { status: "in progress", assignFinalApprovers: true, comment: "Plan complete; assigning CTO+PO for visibility and moving to implementation." }],
+  ["plan->in progress", { status: "in progress", comment: "Plan complete; moving to implementation without generic CTO/PO assignment." }],
   ["in progress->validation", { status: "validation", comment: "Implementation complete; ready for validation." }],
-  ["validation->merge", { status: "merge", assignFinalApprovers: true, comment: "Validation passed; parent task is ready for CTO+PO merge approval." }],
+  ["validation->merge", { status: "merge", assignFinalApprovers: true, parentOnlyFinalApproval: true, comment: "Parent validation passed with a functional preview URL; ready for CTO/PO approval flow." }],
   ["validation->in progress", { status: "in progress", comment: "Validation failed; returning to implementation." }],
   ["merge->completed", { status: "completed", comment: "Merge complete; closing delivery task." }],
   ["completed->in progress", { status: "in progress", comment: "Task reopened; returning to implementation." }],
@@ -9593,11 +9585,14 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
   const key = `${from}->${to}`;
   const rule = CLICKUP_TRANSITIONS.get(key);
   if (!rule) return { ok: false, dryRun: true, message: `Transition not allowed: ${key}` };
-  const assignsFinalApprovers = rule.assignFinalApprovers === true;
-  const requiresPlanCompletionContract = from === "plan" && assignsFinalApprovers;
+  const assignsFinalApprovers = rule.assignFinalApprovers === true && !(rule.parentOnlyFinalApproval && isSubtask);
+  const requiresPlanCompletionContract = from === "plan" && to === "in progress";
   const definitionContent = compactMarkdownValue(definition);
   const description = compactMarkdownValue(planDescription);
   const validationErrors = [];
+  if (rule.parentOnlyFinalApproval && isSubtask) {
+    validationErrors.push("Subtasks must not use the parent final-approval transition; merge validated subtasks directly into the parent branch/workspace.");
+  }
   if (assignsFinalApprovers && !isRealClickUpAssigneeId(productManagerAssignee) && requireProductManagerAssignee !== false) {
     validationErrors.push("productManagerAssignee must be the configured ClickUp PM assignee ID before assigning final approvers.");
   }
@@ -9606,10 +9601,10 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
   }
   if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
-  const finalApprovers = rule.assignFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
+  const finalApprovers = assignsFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
   const explicitRemovals = (removeAssignees || []).filter(Boolean);
   const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
-  const removalTargets = rule.assignFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
+  const removalTargets = assignsFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
   const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))].filter((assignee) => !removalTargets.includes(assignee));
   const authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
   const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
@@ -9624,7 +9619,7 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
       assignment_delta: {
         add: assigned,
         remove: removalTargets,
-        objective: rule.assignFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
+        objective: assignsFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
       },
       comment: rule.comment,
       description,
@@ -10082,11 +10077,17 @@ function createTestClickUpApiClient(config) {
     __metadata: metadata
   };
 }
-function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
-  const webhook = response?.webhook || response?.data || response || {};
+function clickUpWebhookRemoteInactiveReason(webhook = {}) {
   const healthStatus = String(webhook.health?.status || webhook.health_status || "").trim().toLowerCase();
   const status = String(webhook.status || webhook.state || "").trim().toLowerCase();
-  const active = webhook.active !== false && !["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status) && !["failed", "failing", "unhealthy", "error", "errored", "suspended", "paused"].includes(healthStatus);
+  if (["suspended", "paused", "failed", "failing", "unhealthy", "error", "errored"].includes(healthStatus)) return `remote_health_${healthStatus}`;
+  if (["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status)) return `remote_status_${status}`;
+  if (webhook.active === false) return "remote_inactive";
+  return "";
+}
+function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
+  const webhook = response?.webhook || response?.data || response || {};
+  const active = !clickUpWebhookRemoteInactiveReason(webhook);
   return sanitizeClickUpWebhookState({
     active,
     webhookId: webhook.id || webhook.webhook_id || webhook.webhookId,
@@ -10112,20 +10113,44 @@ function clickUpWebhookLocationCompatible(webhook = {}, config = {}) {
   }
   return true;
 }
+function clickUpWebhookEventsCompatible(webhook = {}, config = {}) {
+  if (!Array.isArray(webhook.events) || webhook.events.length === 0) return false;
+  const actualEvents = new Set(webhook.events);
+  return [...new Set(config?.webhook?.events || [])].every((event) => actualEvents.has(event));
+}
+function clickUpWebhookRemoteCompatibilityReason(webhook = {}, config = {}) {
+  if (!clickUpWebhookLocationCompatible(webhook, config)) return "remote_location_mismatch";
+  if (!clickUpWebhookEventsCompatible(webhook, config)) return "remote_events_mismatch";
+  return "";
+}
+function isClickUpWebhookRemoteSelfHealableReason(reason = "") {
+  const normalized = String(reason || "");
+  return normalized === "remote_inactive" || normalized.startsWith("remote_health_") || normalized.startsWith("remote_status_");
+}
 async function findReusableClickUpWebhook(config, clickupClient = null, existingState = null) {
   if (!clickupClient?.listWebhooks) return null;
   const listed = await clickupClient.listWebhooks({ teamId: config.teamId });
-  let secretlessMatch = null;
+  let incompatibleMatch = null;
   for (const webhook of clickUpWebhookListItems(listed)) {
     const remote = normalizeClickUpWebhookApiResponse(webhook, config);
     if (remote.publicUrl !== config.webhook.publicUrl) continue;
-    if (!clickUpWebhookLocationCompatible(webhook, config)) continue;
+    const compatibilityReason = clickUpWebhookRemoteCompatibilityReason(webhook, config);
+    if (compatibilityReason) {
+      if (compatibilityReason === "remote_events_mismatch" && remote.webhookId && !incompatibleMatch) incompatibleMatch = { ...remote, active: false, reason: compatibilityReason };
+      continue;
+    }
     const existingSecret = existingState?.webhookId === remote.webhookId ? existingState.secret : "";
     const reusable = remote.secret ? remote : { ...remote, secret: existingSecret };
     if (isClickUpWebhookStateActive(reusable, config)) return reusable;
-    if (remote.webhookId && !secretlessMatch) secretlessMatch = { ...remote, active: false, reason: "remote_secret_unavailable" };
+    if (remote.webhookId && !incompatibleMatch) {
+      incompatibleMatch = {
+        ...remote,
+        active: false,
+        reason: remote.active === false ? clickUpWebhookRemoteInactiveReason(webhook) || "remote_inactive" : "remote_secret_unavailable"
+      };
+    }
   }
-  return secretlessMatch;
+  return incompatibleMatch;
 }
 async function validateClickUpWebhookState(state, config, clickupClient = null, { allowRemoteUnhealthyLocalRecovery = false } = {}) {
   if (!isClickUpWebhookStateActive(state, config)) return { valid: false, reason: "state_incomplete" };
@@ -10140,7 +10165,7 @@ async function validateClickUpWebhookState(state, config, clickupClient = null,
     }
     const localStateValidation = await validateClickUpWebhookState(state, config, null);
     if (allowRemoteUnhealthyLocalRecovery && localStateValidation.valid && remote.webhookId === state.webhookId) {
-      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && [...new Set(config.webhook.events || [])].every((event) => new Set(remote.events || []).has(event));
+      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && !clickUpWebhookRemoteCompatibilityReason(match, config);
       if (remoteConfigMatches) {
         return {
           ...localStateValidation,
@@ -10165,12 +10190,18 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
   const { config } = validation;
   const existing = existingState ? sanitizeClickUpWebhookState(existingState, config) : readClickUpWebhookState(worktree, config);
   const existingValidation = await validateClickUpWebhookState(existing, config, clickupClient, { allowRemoteUnhealthyLocalRecovery: true });
-  if (existingValidation.valid) {
+  const canReplaceUnhealthyExisting = existingValidation.mode === "local_state_remote_unhealthy" && existingValidation.remote?.webhookId && clickupClient?.deleteWebhook && clickupClient?.createWebhook;
+  if (existingValidation.valid && !canReplaceUnhealthyExisting) {
     const state = writeClickUpWebhookState(worktree, { ...existingValidation.state, recentEventKeys: existing.recentEventKeys || [] }, config);
     clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: existingValidation.mode });
     return { active: true, valid: true, mode: existingValidation.mode, limitation: existingValidation.limitation, state };
   }
-  const reusableRemote = await findReusableClickUpWebhook(config, clickupClient, existing);
+  const reusableRemote = canReplaceUnhealthyExisting ? {
+    ...existingValidation.remote,
+    active: false,
+    secret: existingValidation.remote.secret || existing.secret,
+    reason: clickUpWebhookRemoteInactiveReason(existingValidation.remote) || existingValidation.reason || "remote_unhealthy_self_heal"
+  } : await findReusableClickUpWebhook(config, clickupClient, existing);
   if (reusableRemote) {
     if (isClickUpWebhookStateActive(reusableRemote, config)) {
       const state = writeClickUpWebhookState(worktree, { ...reusableRemote, recentEventKeys: existing.recentEventKeys || [] }, config);
@@ -10178,10 +10209,31 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
       clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: mode2 });
       return { active: true, valid: true, mode: mode2, state };
     }
-    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
-    return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    if (reusableRemote.active === false && reusableRemote.reason !== "remote_secret_unavailable") {
+      if (!isClickUpWebhookRemoteSelfHealableReason(reusableRemote.reason)) {
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_incompatible" });
+        return { active: false, valid: false, reason: reusableRemote.reason || "remote_incompatible", state: existing, remote: reusableRemote };
+      }
+      if (clickupClient?.deleteWebhook && clickupClient?.createWebhook) {
+        const deleteResult = await deleteClickUpWebhookBestEffort({ webhookId: reusableRemote.webhookId, clickupClient, worktree, reason: reusableRemote.reason || "remote_unhealthy_self_heal" });
+        if (deleteResult.ok) {
+          if (existing.webhookId === reusableRemote.webhookId) markClickUpWebhookInactive(worktree, existing, config);
+        } else {
+          const reason = deleteResult.reason || "remote_unhealthy_delete_failed";
+          clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+          return { active: false, valid: false, reason, state: existing, remote: reusableRemote, deleteResult };
+        }
+      } else {
+        const reason = clickupClient?.deleteWebhook ? "remote_unhealthy_create_unavailable" : "remote_unhealthy_delete_unavailable";
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+        return { active: false, valid: false, reason, state: existing, remote: reusableRemote };
+      }
+    } else {
+      clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
+      return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    }
   }
-  if (existing.webhookId && clickupClient?.deleteWebhook) {
+  if (existing.webhookId && existing.webhookId !== reusableRemote?.webhookId && clickupClient?.deleteWebhook) {
     await deleteClickUpWebhookBestEffort({ webhookId: existing.webhookId, clickupClient, worktree, reason: existingValidation.reason || "startup_self_heal" });
     markClickUpWebhookInactive(worktree, existing, config);
   }
@@ -10509,12 +10561,16 @@ function clearClickUpPendingSessionMetadata(metadata, metadataKey) {
   delete cursor[parts[parts.length - 1]];
   return JSON.stringify(sortJsonValue(root), null, 2);
 }
-async function openCodeSessionExists(client, sessionId) {
+function withOptionalDirectoryQuery(payload, directory) {
+  if (!directory) return payload;
+  return { ...payload, query: { ...payload.query || {}, directory } };
+}
+async function openCodeSessionExists(client, sessionId, { directory = "" } = {}) {
   const getAttempts = [
-    { path: { id: sessionId } },
-    { path: { sessionID: sessionId } },
-    { sessionID: sessionId },
-    { id: sessionId }
+    withOptionalDirectoryQuery({ path: { id: sessionId } }, directory),
+    withOptionalDirectoryQuery({ path: { sessionID: sessionId } }, directory),
+    directory ? { sessionID: sessionId, directory } : { sessionID: sessionId },
+    directory ? { id: sessionId, directory } : { id: sessionId }
   ];
   if (typeof client?.session?.get === "function") {
     for (const attempt of getAttempts) {
@@ -10526,10 +10582,10 @@ async function openCodeSessionExists(client, sessionId) {
     }
   }
   const messageAttempts = [
-    { path: { id: sessionId }, query: { limit: 1 } },
-    { path: { sessionID: sessionId }, query: { limit: 1 } },
-    { sessionID: sessionId, limit: 1 },
-    { id: sessionId, limit: 1 }
+    { path: { id: sessionId }, query: { limit: 1, ...directory ? { directory } : {} } },
+    { path: { sessionID: sessionId }, query: { limit: 1, ...directory ? { directory } : {} } },
+    directory ? { sessionID: sessionId, directory, limit: 1 } : { sessionID: sessionId, limit: 1 },
+    directory ? { id: sessionId, directory, limit: 1 } : { id: sessionId, limit: 1 }
   ];
   if (typeof client?.session?.messages === "function") {
     for (const attempt of messageAttempts) {
@@ -10933,6 +10989,17 @@ async function verifyOpenCodeSessionEventDelivery(client, { sessionId, directory
   }
   return { ok: false, reason: lastError };
 }
+async function postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason, source } = {}) {
+  if (typeof clickupClient?.postTaskComment !== "function") return { ok: false, skipped: true, reason: "post_comment_unavailable" };
+  try {
+    await clickupClient.postTaskComment({ taskId, comment: `Optima launch failure: ${reason || "launch_failed"}. Worktree visibility alone is not successful routing; Optima requires an OpenCode session plus verified prompt admission/delivery.` });
+    appendClickUpWebhookLocalLog(worktree, { type: "launch_failure_comment_posted", taskId, reason, source });
+    return { ok: true };
+  } catch (error) {
+    appendClickUpWebhookLocalLog(worktree, { type: "launch_failure_comment_failed", taskId, reason, source, message: error.message });
+    return { ok: false, error: error.message };
+  }
+}
 async function applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason, source, tagName = CLICKUP_BLOCKER_TAG_NAME } = {}) {
   if (typeof clickupClient?.addTaskTag !== "function") {
     appendClickUpWebhookLocalLog(worktree, { type: "blocker_tag_unavailable", taskId, reason, source, tagName });
@@ -10962,7 +11029,17 @@ function openCodeBlockingPromptVerification(result, sessionId) {
 }
 async function deliverClickUpSessionEventWithVerification({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, sessionId, agent, text, directory, opencodeBaseUrl, directPrompt = false, acceptPromptAdmission = false, eventMarkers = [], verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery, applyBlockerOnFailure = true } = {}) {
   const beforeMessages = await readOpenCodeSessionMessages(openCodeClient, { sessionId, directory, limit: 50 }).catch(() => null);
-  const sendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: directPrompt, allowDirectFallback: directPrompt });
+  let sendResult;
+  try {
+    sendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: directPrompt, allowDirectFallback: directPrompt });
+  } catch (error) {
+    const reason2 = error.message || "message_delivery_failed";
+    appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason: reason2, fallbackAttempted: false });
+    if (!applyBlockerOnFailure) return { ok: false, action: "message_delivery_failed", reason: reason2, taskId, sessionId, fallbackAttempted: false };
+    const blocker2 = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: reason2, source: "delivery_send_failed" });
+    const launchFailureComment2 = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: reason2, source: "delivery_send_failed" });
+    return { ok: false, action: "message_delivery_failed", reason: reason2, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2, launchFailureComment: launchFailureComment2 };
+  }
   let blockingPromptVerification = null;
   let admissionVerification = null;
   try {
@@ -10972,7 +11049,8 @@ async function deliverClickUpSessionEventWithVerification({ openCodeClient, send
     appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason: error.message, fallbackAttempted: false });
     if (!applyBlockerOnFailure) return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false };
     const blocker2 = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: error.message, source: "delivery_admission_failed" });
-    return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2 };
+    const launchFailureComment2 = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: error.message, source: "delivery_admission_failed" });
+    return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2, launchFailureComment: launchFailureComment2 };
   }
   if (blockingPromptVerification) return { ok: true, verification: blockingPromptVerification, admissionVerification: null, fallback: false };
   if (admissionVerification && acceptPromptAdmission) {
@@ -10987,7 +11065,8 @@ async function deliverClickUpSessionEventWithVerification({ openCodeClient, send
   appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason, fallbackAttempted: false, httpFallbackDisabled: Boolean(opencodeBaseUrl) });
   if (!applyBlockerOnFailure) return { ok: false, action: "message_delivery_failed", reason, taskId, sessionId, fallbackAttempted: false };
   const blocker = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason, source: "delivery_verification_failed" });
-  return { ok: false, action: "message_delivery_failed", reason, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker };
+  const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason, source: "delivery_verification_failed" });
+  return { ok: false, action: "message_delivery_failed", reason, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker, launchFailureComment };
 }
 async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, staleSessionId, sessionTitle, taskRoute, metadataWithRouting, config, prompt, eventMarkers = [], deliveryEvidencePath, evidencePath, eventKey, createSession, verifySessionEventDelivery } = {}) {
   appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_started", taskId, staleSessionId, worktree: taskRoute?.worktree });
@@ -10997,12 +11076,14 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   } catch (error) {
     appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_create_failed", taskId, staleSessionId, message: error.message });
     const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
-    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
+    const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
+    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, launchFailureComment, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
   }
   if (!String(replacementSessionId || "").startsWith("ses_")) {
     appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_create_invalid", taskId, staleSessionId, replacementSessionId });
     const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
-    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
+    const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "replacement_session_create_failed", source: "pm_session_recovery" });
+    return { ok: false, action: "message_delivery_failed", reason: "replacement_session_create_failed", taskId, sessionId: staleSessionId, replacementAttempted: true, blockerTag, launchFailureComment, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
   }
   const replacementDelivery = await deliverClickUpSessionEventWithVerification({
     openCodeClient,
@@ -11024,7 +11105,8 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   if (!replacementDelivery.ok) {
     appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_delivery_failed", taskId, staleSessionId, replacementSessionId, reason: replacementDelivery.reason });
     const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: replacementDelivery.reason || "replacement_delivery_failed", source: "pm_session_recovery" });
-    return { ...replacementDelivery, sessionId: staleSessionId, replacementSessionId, replacementAttempted: true, blockerTag, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
+    const launchFailureComment = replacementDelivery.launchFailureComment || await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: replacementDelivery.reason || "replacement_delivery_failed", source: "pm_session_recovery" });
+    return { ...replacementDelivery, sessionId: staleSessionId, replacementSessionId, replacementAttempted: true, blockerTag, launchFailureComment, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath };
   }
   const replacementMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(metadataWithRouting, config.routing.metadataKey, replacementSessionId), config.routing.metadataKey);
   await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: replacementMetadata });
@@ -11308,8 +11390,26 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
-      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: taskRoute.worktree, agent: config.routing.targetAgent });
-      if (!String(pendingSessionId || "").startsWith("ses_")) return { ok: false, action: "error", reason: "session_create_failed", taskId };
+      try {
+        pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: taskRoute.worktree, agent: config.routing.targetAgent });
+      } catch (error) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pm_session_create_failed", taskId, worktree: taskRoute.worktree, message: error.message });
+        const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        return finish({ ok: false, action: "error", reason: "session_create_failed", taskId, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, blockerTag, launchFailureComment });
+      }
+      if (!String(pendingSessionId || "").startsWith("ses_")) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pm_session_create_invalid", taskId, worktree: taskRoute.worktree, sessionId: pendingSessionId || null });
+        const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "session_create_failed", source: "route_create_session" });
+        return finish({ ok: false, action: "error", reason: "session_create_failed", taskId, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, blockerTag, launchFailureComment });
+      }
+      if (!await sessionExists(openCodeClient, pendingSessionId, { directory: taskRoute.worktree })) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pm_session_create_directory_unverified", taskId, worktree: taskRoute.worktree, sessionId: pendingSessionId });
+        const blockerTag = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "session_directory_unverified", source: "route_create_session" });
+        const launchFailureComment = await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: "session_directory_unverified", source: "route_create_session" });
+        return finish({ ok: false, action: "error", reason: "session_directory_unverified", taskId, sessionId: pendingSessionId, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, blockerTag, launchFailureComment });
+      }
       if (saveState) {
         saveState({
           ...state,
@@ -11325,7 +11425,20 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
       throw error;
     }
     const delivery = await deliverClickUpSessionEventWithVerification({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, sessionId: pendingSessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl, directPrompt: config.opencode?.promptDelivery === "http", acceptPromptAdmission: config.opencode?.acceptPromptAdmission === true, eventMarkers: [taskId, eventType], verifySessionEventDelivery });
-    if (!delivery.ok) return finish({ ...delivery, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path });
+    if (!delivery.ok) {
+      const failedMetadata = clearClickUpPendingSessionMetadata(metadataWithRouting, config.routing.metadataKey);
+      let pendingCleared = false;
+      try {
+        await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: failedMetadata });
+        pendingCleared = true;
+      } catch (error) {
+        appendClickUpWebhookLocalLog(worktree, { type: "pending_session_clear_failed", taskId, sessionId: pendingSessionId, message: error.message });
+      }
+      const { [taskId]: _failedPending, ...remainingPending2 } = stateToPersist.pendingSessions || {};
+      stateToPersist = { ...stateToPersist, pendingSessions: remainingPending2 };
+      appendClickUpWebhookLocalLog(worktree, { type: "pending_session_delivery_failed", taskId, sessionId: pendingSessionId, reason: delivery.reason || "message_delivery_failed", pendingCleared });
+      return finish({ ...delivery, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, pendingCleared });
+    }
     const nextMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(pendingMetadata, config.routing.metadataKey, pendingSessionId), config.routing.metadataKey);
     await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
     const { [taskId]: _completedPending, ...remainingPending } = stateToPersist.pendingSessions || {};
@@ -11333,7 +11446,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     return finish({ ok: true, action: "created_session", taskId, sessionId: pendingSessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryAdmission: delivery.admissionVerification, deliveryFallback: delivery.fallback, deliveryAttempts: delivery.fallback ? 2 : 1 });
   }
   const sessionId = String(existingSessionId);
-  if (await sessionExists(openCodeClient, sessionId)) {
+  if (await sessionExists(openCodeClient, sessionId, { directory: taskRoute.worktree })) {
     if (typeof clickupClient?.updateTaskMetadata === "function") await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: metadataWithRouting });
     const delivery = await deliverClickUpSessionEventWithVerification({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, sessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl, directPrompt: config.opencode?.promptDelivery === "http", acceptPromptAdmission: config.opencode?.acceptPromptAdmission === true, eventMarkers: [taskId, eventType], verifySessionEventDelivery, applyBlockerOnFailure: false });
     if (!delivery.ok) {
@@ -11461,6 +11574,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
         routed.undelivered += 1;
         appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: result?.action || "error", sessionId: routeSummary.sessionId, reason: result.reason || "startup_reconciliation_route_failed" });
         if (!result.blockerTag) await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: result.reason || "startup_reconciliation_route_failed", source: "startup_reconciliation_task" });
+        if (!result.launchFailureComment) await postClickUpLaunchFailureComment({ clickupClient, worktree, taskId, reason: result.reason || "startup_reconciliation_route_failed", source: "startup_reconciliation_task" });
       } else {
         routed.undelivered += 1;
         appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: routeSummary.action, sessionId: routeSummary.sessionId, reason: "route_not_actionable" });
@@ -11568,14 +11682,13 @@ function clickUpListenerKey(config) {
 }
 function clickUpListenerFingerprint({ config, state, worktree, clickupClient, openCodeClient } = {}) {
   return JSON.stringify({
+    teamId: config?.teamId || "",
     publicUrl: config?.webhook?.publicUrl || "",
     path: clickUpWebhookExpectedPath(config),
-    worktree: path5.resolve(worktree || process.cwd()),
+    location: config?.webhook?.location || {},
     webhookId: state?.webhookId || "",
     secret: state?.secret || "",
-    events: config?.webhook?.events || [],
-    clickupClient: objectIdentity(clickupClient),
-    openCodeClient: objectIdentity(openCodeClient)
+    events: config?.webhook?.events || []
   });
 }
 function startClickUpWebhookListener({ config, state, worktree, clickupClient, openCodeClient, listenerRegistry = activeClickUpWebhookListeners } = {}) {

package/docs/core/agent_orchestration.md

@@ -22,7 +22,8 @@
 - `product_manager` may answer, investigate, operate dashboards, and pre-estimate "a qué huele" small/medium/large plus rough story points; WPM owns delivery routing.
 - Supported delivery task types are `Tarea`, `Bug`, `Doc`, and `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, and `Respuesta del formulario` unless converted or linked to delivery work.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use the Optima-provided human role fallback context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
-- Status actions are deterministic: `backlog` ignore, `plan` plan plus `Story Points`, test strategy, `Definition`, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead and Validator/QA gates, `merge` parent approval state after `CTO`/`PO` move a validated parent task there, and `completed`/`Closed` ignore unless reopened.
+- Status actions are deterministic: `backlog` ignore, `plan` plan plus `Story Points`, test strategy, and `Definition`, `in progress` execute, `validation` split Tech Lead and Validator/QA gates, `merge` parent post-approval automation, and `completed`/`Closed` ignore unless reopened.
+- Human approval assignment is prohibited except for the strict allowlist: parent `plan` with clear questions already posted in ClickUp comments; `in progress` blocked by missing credentials, permissions, external tools, or access; or parent `validation` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask planning/validation, or partial-phase stops.
 - Store ClickUp `agent_metadata` JSON with session IDs per agent/type/task/subtask; keep `Definition` as the plan contract and final Documentation as delivered behavior docs.
 - `workflow_product_manager` is registered only when explicit ClickUp webhook mode is configured and the local webhook subscription state is active/valid.
 - Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, stores new `ses_...` ids in ClickUp `agent_metadata`, and reports stale/missing sessions to ClickUp without creating replacements.
@@ -35,8 +36,8 @@
 - Parent task start pulls remote once; after branch creation, subtasks trust the parent local branch instead of continuous remote polling.
 - Parent branch format is `<clickup-task-type>/<parent-task-id>`; subtask branch format is the non-nested sibling ref `<clickup-task-type>/<parent-task-id>-subtask-<subtask-id>`; pending planned subtasks use `<clickup-task-type>/<parent-task-id>-pending-<title-slug>`; PoC branch format is always `poc/<clickup-task-id>` and stays there until a later productization task.
 - Subtask worktrees start from the parent branch and PR to the parent branch; if the parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first. Parent task PRs target `dev`, and release PRs target `main` from `dev` only after explicit approval.
-- After successful subtask validation, Validator/QA merges the subtask PR into the parent branch/workspace without `CTO`/`PO` approval.
-- After parent Tech Lead and Validator/QA validation passes, the parent task stays in `validation`, `CTO`/`PO` are assigned and marked as approval owners, and they approve by moving it to `merge`; only then does Validator/QA attempt the parent PR merge into `dev`.
+- After successful subtask validation, Validator/QA merges the subtask PR into the parent branch/workspace without `CTO`/`PO` assignment or approval.
+- After parent Tech Lead and Validator/QA validation passes, the parent task may assign `CTO`/`PO` only when a functional validation URL is provided; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges the parent PR into `dev`, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code.
 - If any subtask or parent merge conflicts or fails, Validator/QA returns the affected ClickUp item to `in progress` and routes it to the coding owner.
 - Never push directly to `main`.
 - `investigation` and `spec` tasks may run in parallel only when they avoid conflicting delivery artifacts.

package/docs/core/agent_orchestration.prompt.md

@@ -14,7 +14,7 @@
 - `product_manager` may answer/investigate/dashboard/pre-estimate "a qué huele" plus rough story points; development asks become routed ClickUp tasks.
 - ClickUp-first types: execute `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima-provided fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
-- ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, test strategy, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead + Validator/QA gates; Validator/QA may merge validated subtasks directly into the parent branch; validated parents stay in `validation` for `CTO`/`PO` approval; `merge` means `CTO`/`PO` approved the parent and Validator/QA may attempt parent merge into `dev`; `completed`/`Closed` ignore unless reopened.
+- ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/tools/access, or parent `validation` with a functional preview URL. Subtasks merge directly into the parent branch after Validator/QA passes without CTO/PO assignment; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code; `completed`/`Closed` ignore unless reopened.
 - Shared-worktree rule: one active `implementation` task at a time; isolated `investigation`/`spec` may run in parallel if non-conflicting.
 - Git rules: principal workspace stays on `dev`, never `main`; parent branches use `<type>/<parent-id>`; subtask branches use non-nested `<type>/<parent-id>-subtask-<subtask-id>` and pending subtasks use `<type>/<parent-id>-pending-<title-slug>`; parent task pulls remote once at start; subtasks start from and PR to the parent local branch, bootstrapping the parent from `dev`/`origin/dev` first when missing; PoC branches stay `poc/<clickup-task-id>`; parents PR to `dev`, releases PR `dev` -> `main`; failed/conflicted subtask or parent merges return the affected item to `in progress` for the coding owner; no direct `main` pushes.
 - Store `agent_metadata` session JSON; `Definition` is the plan contract, final Documentation is delivered behavior docs.

package/docs/core/role_contracts.md

@@ -21,8 +21,9 @@
 - Raw logs stay in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
 - WPM owns ClickUp `Story Points` during `plan`, re-estimation on material plan changes, `agent_metadata` session JSON, `Definition` plan-contract linking, and parent approval routing after validation.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima-provided fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
-- Subtask merge authority belongs to Validator/QA after successful subtask validation: subtask PRs target and merge into the parent branch/workspace without `CTO`/`PO` approval.
-- Parent merge authority is split: after Tech Lead and Validator/QA pass, WPM/Validator assigns `CTO` and `PO` while the parent task remains in `validation`; `CTO`/`PO` approve by moving the parent task to `merge`; Validator/QA then attempts the parent PR merge into `dev`.
+- Human approval assignment is prohibited except for three cases: parent `plan` with clear ClickUp-commented questions, `in progress` blockers caused by missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask work, or partial-phase stops.
+- Subtask merge authority belongs to Validator/QA after successful subtask validation: subtask PRs target and merge into the parent branch/workspace without `CTO`/`PO` assignment or approval.
+- Parent merge authority is split: after Tech Lead and Validator/QA pass, WPM/Validator may assign `CTO`/`PO` only under the parent-validation allowlist; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges to `dev`, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code.
 - If a subtask or parent merge conflicts or fails, Validator/QA returns the affected ClickUp task/subtask to `in progress` and routes it back to the coding owner.
 - Git authority follows ClickUp-first rules: principal workspace on `dev`, no direct `main` push, parent task pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs from `dev` to `main` only after approval.
 

package/docs/core/role_contracts.prompt.md

@@ -15,8 +15,9 @@
 - Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
 - WPM owns `Story Points` during `plan`, re-estimation on material plan changes, `agent_metadata`, `Definition` plan-contract linking, and parent approval routing after validation.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
-- Validator/QA may merge validated subtask PRs into the parent branch/workspace without `CTO`/`PO` approval.
-- Parent merge authority requires `CTO`/`PO` approval: after Tech Lead + Validator/QA pass, assign both roles while the parent stays in `validation`; they approve by moving it to `merge`; Validator/QA then attempts the parent PR merge into `dev`.
+- Human approval assignment is prohibited except for parent `plan` questions with clear ClickUp comments, `in progress` blockers from missing credentials/tools/access, or parent `validation` with a functional preview URL; never use it for generic handoff, cleanup, subtasks, or phase stops.
+- Validator/QA may merge validated subtask PRs into the parent branch/workspace without `CTO`/`PO` assignment or approval.
+- Parent merge authority uses the validation allowlist only: after a human comments `Approved`, automation removes human assignees, assigns merge owner/self, merges to `dev`, cleans workspaces/worktrees/branches, pushes, and ensures dev receives the code.
 - Failed or conflicted subtask/parent merges return the affected ClickUp item to `in progress` for the coding owner.
 - ClickUp-first Git rules: principal workspace on `dev`, no direct `main` push, parent pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs `dev` -> `main` only after approval.
 - BA owns product truth and product-facing feature/domain docs.

package/docs/core/task_model.md

@@ -12,9 +12,16 @@
 - Ignored task types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted or linked to delivery work; `Idea` is non-delivery.
 - `product_manager` may pre-estimate "a qué huele" small/medium/large plus rough story points, but development requests must be converted to routed ClickUp work.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
-- Status-to-action mapping: `backlog` -> `ignore`, `plan` -> `plan`, `in progress` -> `execute`, `validation` -> `validate`, `merge` -> `merge`, `completed`/`Closed` -> `ignore` unless reopened. For parent tasks, `merge` means `CTO`/`PO` have approved by moving the task out of `validation`; for subtasks, Validator/QA may merge after successful validation without waiting for `merge` human approval.
+- Status-to-action mapping: `backlog` -> `ignore`, `plan` -> `plan`, `in progress` -> `execute`, `validation` -> `validate`, `merge` -> `merge`, `completed`/`Closed` -> `ignore` unless reopened. `plan` does not imply generic human approval assignment; `merge` is parent-only post-approval automation, while subtasks merge after successful Validator/QA validation without waiting for a human approval status.
 - Branch-safe type slugs are lowercase ASCII: `tarea`, `bug`, `doc`, `poc`.
 
+## Human Approval Allowlist
+
+- Agents must not assign ClickUp tasks to `CTO` or `PO` except for the explicit cases below; generic handoff, routine validation, duplicate-assignee cleanup, or incomplete phase handoff are prohibited.
+- **Parent planning questions:** only a parent task in `plan` may assign `CTO`/`PO`, and only after clear, concrete questions have been posted in ClickUp comments. Subtasks are planned and executed end-to-end without CTO/PO planning assignment.
+- **Real in-progress blocker:** a task in `in progress` may assign/escalate to `CTO`/`PO` only when blocked by missing credentials, permissions, external tools, or access. Agents must not stop at informal phase boundaries such as "I reached phase 1"; phases should have been subtasks, otherwise finish the accepted task.
+- **Parent validation approval:** only a parent task in `validation` may assign `CTO`/`PO` for final validation, and only with a functional preview URL such as `https://<taskid>-preview.defend.tech` or an equivalent working validation URL. After a human comments `Approved`, automation reassigns to itself or the merge owner, removes human assignees, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code.
+
 ## Routing Rules
 
 - `tiny` stays within one slice and usually one specialist handoff.
@@ -24,7 +31,7 @@
 - While one shared-worktree implementation task is active, parallel work is limited to non-conflicting `investigation` or `spec`.
 - WPM estimates `Story Points` during `plan`, re-estimates on material plan changes, links the `Definition` plan contract when needed, and records `agent_metadata` session IDs.
 - In ClickUp-first mode, work should be decomposed into parent/subtask branches: parent tasks pull remote once at start, parent branches use `<type>/<parent-id>` and merge to `dev`, subtasks use non-nested `<type>/<parent-id>-subtask-<subtask-id>` branches that start from/trust the parent local branch and merge to parent branches, missing parent branches/worktrees are bootstrapped from `dev`/`origin/dev` before subtask worktree creation, PoC branches stay `poc/<clickup-task-id>`, and release branches merge `dev` to `main` only after approval.
-- Validator/QA owns merge execution after the correct gate: validated subtask PRs merge directly into the parent branch/workspace, while parent PRs merge into `dev` only after `CTO`/`PO` move the parent task to `merge`. Merge conflicts or failed attempts return the affected task/subtask to `in progress` for the coding owner.
+- Validator/QA owns merge execution after the correct gate: validated subtask PRs merge directly into the parent branch/workspace without CTO/PO assignment, while parent PRs merge into `dev` only after the parent validation approval allowlist is satisfied and a human `Approved` comment triggers merge automation. Merge conflicts or failed attempts return the affected task/subtask to `in progress` for the coding owner.
 
 ## Pre-Sync Defaults
 

package/docs/core/task_model.prompt.md

@@ -7,7 +7,7 @@
 - ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignored types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
 - Product Manager without workflow never develops; it may pre-estimate "a qué huele" small/medium/large plus rough story points and route development into ClickUp tasks.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
-- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, test strategy, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead + Validator/QA; validated subtasks may be merged by Validator/QA into the parent branch without human approval; validated parent tasks assign `CTO`/`PO` and wait for them to move the task to `merge`; `merge` lets Validator/QA attempt parent PR merge into `dev`; `completed`/`Closed` ignore unless reopened.
+- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access, or parent `validation` with a functional preview URL. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code; `completed`/`Closed` ignore unless reopened.
 - Routing: keep `tiny` to one slice and usually one specialist; keep `standard` bounded; decompose `complex` into slice-based subtasks.
 - `complex + implementation` normally uses `workflow_runner` in full mode.
 - WPM stores `agent_metadata`, re-estimates `Story Points` on material plan changes, and keeps `Definition` plan contract separate from final Documentation.

package/docs/core/testing_strategy.md

@@ -19,7 +19,8 @@ We adhere to a strict test pyramid strategy to ensure 100% reliability.
 - **Regression:** A full regression suite must be run by the Developer before handing over for technical review.
 - **Split Validation:** Tech Lead reviews architecture, code, PR readiness, standards, and repo-skill use; Validator/QA verifies tests, Playwright flows, regression, required coverage, evidence, and final documentation freshness.
 - **Human Role Registry:** Resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
-- **Merge Execution Gate:** Validator/QA may merge validated subtask PRs into the parent branch/workspace without human approval. Parent PRs to `dev` require Tech Lead and Validator/QA pass plus `CTO`/`PO` approval by moving the parent task to `merge` before Validator/QA attempts the merge. Any conflicted or failed merge returns the affected task/subtask to `in progress` for the coding owner.
+- **Human Approval Allowlist:** Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL. Never assign them for generic handoff, routine validation, cleanup, subtasks, or partial-phase stops.
+- **Merge Execution Gate:** Validator/QA may merge validated subtask PRs into the parent branch/workspace without human approval. Parent PRs to `dev` require Tech Lead and Validator/QA pass plus the parent-validation allowlist; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code. Any conflicted or failed merge returns the affected task/subtask to `in progress` for the coding owner.
 - **Documentation Gate:** Validator/QA must fail validation when final documentation is missing or outdated; `Definition` is only the plan contract, not the delivered documentation.
 - **QA Output Contract:** QA handoffs should state the test strategy used, the results observed, the AC coverage achieved, any documentation impact, open risks, and the recommended next step.
 - **Investigation Outputs:** `investigation` tasks should produce findings, reproduction notes, logs when useful, and a recommended next step rather than pretending to be implementation tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defend-tech/opencode-optima",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"