cowork-flow 0.0.19 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {

package/template/.agent/skills/start/SKILL.md

@@ -13,9 +13,10 @@ Before loading state, classify the actual prompt. If it is a bounded delegated t
 
 1. Read `AGENTS.md`.
 2. Read `.cowork-flow/workflow.md`.
-3. Run `.cowork-flow/run resume` or `.\.cowork-flow\run.cmd resume` on Windows.
-4. Read the active task PRD and JSONL indexes only when a task is active.
-5. Read relevant `.cowork-flow/spec/*/index.md` files before code changes.
+3. Read `.cowork-flow/config.yaml` for `codex.post_ack_execution_grace_ms`.
+4. Run `.cowork-flow/run resume` or `.\.cowork-flow\run.cmd resume` on Windows.
+5. Read the active task PRD and JSONL indexes only when a task is active.
+6. Read relevant `.cowork-flow/spec/*/index.md` files before code changes.
 
 Report active task, workflow state, blockers, and the next phase.
 
@@ -51,4 +52,8 @@ Every dispatch prompt starts with:
 Active task: <task-dir>
 ```
 
-After dispatch, use `wait_agent`, review the output, inspect `list_agents`, and `close_agent`.
+Prefer the `COWORK_DISPATCH_V1` envelope for `cowork-*` subagents, then wait for `COWORK_ACK <dispatch_id> <ack_token>` before sending `EXECUTE <dispatch_id>`.
+
+Use per-dispatch post-ACK execution grace after sending `EXECUTE`. The default duration is `300000` ms and can be configured with `codex.post_ack_execution_grace_ms` in `.cowork-flow/config.yaml`. Record `execute_sent_at[dispatch_id]` and compute `deadline[dispatch_id] = execute_sent_at[dispatch_id] + codex.post_ack_execution_grace_ms`; do not use a shared/global deadline across children. After `EXECUTE`, missing output or missing compass/status file is not proof that the child is stuck. Do not close a child only because it is still reading startup rules, AGENTS.md, workflow docs, specs, or task context. If `list_agents` still shows it running, continue waiting through grace. Grace expiration for one `dispatch_id` is a review checkpoint for that child only, not a close trigger and not evidence about other children. If progress, compass, or status files exist, keep waiting. Only close after wrong dispatch evidence, child completion, or user cancellation.
+
+After execution, use `wait_agent`, review the output, inspect `list_agents`, and `close_agent`.

package/template/.codex/hooks/inject-workflow-state.py

@@ -144,6 +144,21 @@ def _get_dispatch_mode(root: Path) -> str:
         return "sub-agent"
 
 
+def _get_post_ack_execution_grace_ms(root: Path) -> int:
+    _load_common(root)
+    try:
+        from common.config import (  # type: ignore[import-not-found]
+            DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS,
+            get_codex_post_ack_execution_grace_ms,
+        )
+    except Exception:
+        return 300000
+    try:
+        return get_codex_post_ack_execution_grace_ms(root)
+    except Exception:
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+
+
 def _get_active_task(root: Path, hook_input: dict[str, Any]) -> tuple[str | None, str, str]:
     _load_common(root)
     try:
@@ -174,6 +189,7 @@ def _build_context(
     source: str,
     breadcrumbs: dict[str, str],
     dispatch_mode: str,
+    post_ack_execution_grace_ms: int,
 ) -> str:
     body = breadcrumbs.get(status) or "Refer to .cowork-flow/workflow.md for the current step."
     if task_path is None:
@@ -184,6 +200,11 @@ def _build_context(
     return "\n\n".join(
         [
             f"<codex-mode>{dispatch_mode}</codex-mode>",
+            (
+                "<codex-runtime>\n"
+                f"post_ack_execution_grace_ms: {post_ack_execution_grace_ms}\n"
+                "</codex-runtime>"
+            ),
             f"<workflow-state>\n{header}\n{body}\n</workflow-state>",
         ]
     )
@@ -202,12 +223,20 @@ def main() -> int:
 
     breadcrumbs = _load_breadcrumbs(root)
     dispatch_mode = _get_dispatch_mode(root)
+    post_ack_execution_grace_ms = _get_post_ack_execution_grace_ms(root)
     task_path, status, source = _get_active_task(root, hook_input)
     if _is_delegated_prompt(hook_input):
         task_path = None
         status = "delegated_subtask"
         source = "prompt"
-    additional_context = _build_context(task_path, status, source, breadcrumbs, dispatch_mode)
+    additional_context = _build_context(
+        task_path,
+        status,
+        source,
+        breadcrumbs,
+        dispatch_mode,
+        post_ack_execution_grace_ms,
+    )
 
     print(
         json.dumps(

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.19
+0.0.20

package/template/.cowork-flow/config.yaml

@@ -24,6 +24,11 @@ max_journal_lines: 2000
 # inline: hint that main session should perform implementation/check directly.
 codex:
   dispatch_mode: "sub-agent"
+  # Grace duration after each subagent ACKs and receives EXECUTE.
+  # This is a per-dispatch duration, not a shared/global deadline.
+  # During this window, missing output or missing compass/status files do not
+  # prove the child is stuck while it loads task context.
+  post_ack_execution_grace_ms: 300000
 
 #-------------------------------------------------------------------------------
 # Task Lifecycle Hooks

package/template/.cowork-flow/scripts/common/config.py

@@ -16,6 +16,7 @@ from .paths import DIR_WORKFLOW, get_repo_root
 DEFAULT_SESSION_COMMIT_MESSAGE = "chore: record journal"
 DEFAULT_MAX_JOURNAL_LINES = 2000
 DEFAULT_CODEX_DISPATCH_MODE = "sub-agent"
+DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS = 300000
 
 CONFIG_FILE = "config.yaml"
 
@@ -139,3 +140,19 @@ def get_codex_dispatch_mode(repo_root: Path | None = None) -> str:
     if mode in {"sub-agent", "inline"}:
         return str(mode)
     return DEFAULT_CODEX_DISPATCH_MODE
+
+
+def get_codex_post_ack_execution_grace_ms(repo_root: Path | None = None) -> int:
+    """Get the post-ACK execution grace duration for Codex subagent dispatch."""
+    config = _load_config(repo_root)
+    codex = config.get("codex")
+    if not isinstance(codex, dict):
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+    value = codex.get("post_ack_execution_grace_ms", DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS)
+    try:
+        parsed = int(value)
+    except (ValueError, TypeError):
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+    if parsed <= 0:
+        return DEFAULT_CODEX_POST_ACK_EXECUTION_GRACE_MS
+    return parsed

package/template/.cowork-flow/scripts/doctor.py

@@ -15,6 +15,10 @@ REQUIRED_START_SNIPPETS = [
     "This skill is for the main session",
     "bounded delegated task should use `entry-boundary`",
     "Main repository changes follow `Plan -> Implement -> Check -> Finish`",
+    "post-ACK execution grace",
+    "codex.post_ack_execution_grace_ms",
+    "execute_sent_at[dispatch_id]",
+    "shared/global deadline",
 ]
 
 REQUIRED_ENTRY_BOUNDARY_SNIPPETS = [
@@ -45,6 +49,12 @@ REQUIRED_WORKFLOW_DISPATCH_SNIPPETS = [
     "COWORK_DISPATCH_V1",
     "COWORK_ACK",
     "followup_task",
+    "post-ACK execution grace",
+    "codex.post_ack_execution_grace_ms",
+    "execute_sent_at[dispatch_id]",
+    "deadline[dispatch_id] = execute_sent_at[dispatch_id] + codex.post_ack_execution_grace_ms",
+    "shared/global deadline",
+    "After `EXECUTE <dispatch_id>`, no reply or no compass/status file while the child loads context is inconclusive.",
     "Formal execution uses `cowork-research`, `cowork-implement`, or `cowork-check`.",
     "Generic `worker` dispatch is best-effort only.",
 ]

package/template/.cowork-flow/workflow.md

@@ -34,7 +34,7 @@ The active task is in planning. Finish prd.md, curate implement.jsonl and check.
 [/workflow-state:planning]
 
 [workflow-state:in_progress]
-The active task is in progress. Main session dispatches cowork-implement work according to the plan, then cowork-check after integration. Every spawn_agent call uses fork_turns="none" and a COWORK_DISPATCH_V1 envelope. Main session waits for COWORK_ACK, sends EXECUTE with followup_task, verifies child output, lists agents, and closes children.
+The active task is in progress. Main session dispatches cowork-implement work according to the plan, then cowork-check after integration. Every spawn_agent call uses fork_turns="none" and a COWORK_DISPATCH_V1 envelope. Main session waits for COWORK_ACK, sends EXECUTE with followup_task, then uses per-dispatch post-ACK execution grace while each child loads context. Main session verifies child output, lists agents, and closes children only after completion or clear failure evidence.
 [/workflow-state:in_progress]
 
 [workflow-state:completed]
@@ -115,7 +115,16 @@ spawn_agent(
 - Use `wait_agent` for `COWORK_ACK <dispatch_id> <ack_token>` before execution.
 - Missing or mismatched `COWORK_ACK` means the task is not dispatched.
 - Only after a matching ACK, send `EXECUTE <dispatch_id>` with `followup_task`.
+- Record `execute_sent_at[dispatch_id]` when `EXECUTE <dispatch_id>` is sent.
+- Compute `deadline[dispatch_id] = execute_sent_at[dispatch_id] + codex.post_ack_execution_grace_ms`; do not use a shared/global deadline across children.
+- After `EXECUTE <dispatch_id>`, no reply or no compass/status file while the child loads context is inconclusive.
+- Use post-ACK execution grace for execution startup before judging execution health. The default is `300000` ms and can be configured with `codex.post_ack_execution_grace_ms` in `.cowork-flow/config.yaml`.
+- Do not call `close_agent` only because the executing child has not produced a compass/status file.
+- If `list_agents` still shows the child running, continue waiting through post-ACK execution grace instead of closing it.
+- Post-ACK execution grace expiration for one `dispatch_id` is a review checkpoint for that child only, not a close trigger and not evidence about other children.
+- If progress, compass, or status files exist, continue waiting and do not close solely because grace expired.
 - If a child reports another `dispatch_id`, close that child and respawn the intended task.
+- An executing child may be closed only after wrong-dispatch evidence, child completion, or user cancellation.
 - 用 `wait_agent` 等待子 agent 返回。
 - 用 `list_agents` 确认没有遗留 running child。
 - 验收子 agent 汇报的文件、命令和结果；不只信“已完成”文本。