@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/core/harnesses/shared/hooks/policies/stop-check.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
+_DOFLOW_SRC=${0//\\//}; case $_DOFLOW_SRC in */*) _DOFLOW_POLDIR=${_DOFLOW_SRC%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # stop-check.sh — Canonical Policy Library: Stop hook
 #
 # Two responsibilities:
@@ -24,14 +26,8 @@
 #
 # Canonical Policy Script Contract (design.md §4):
 #   env    DOFLOW_PROJECT_DIR, DOFLOW_AGENT (both optional here)
-#   stdin  a Stop-shaped JSON payload. session_id and transcript path field
-#          names both vary by harness (transcript_path vs. Antigravity's
-#          camelCase transcriptPath) — this script reads the union of known
-#          field names rather than assuming one, since a native front door
-#          (Claude/Codex/Kiro) execs this script directly with no payload
-#          translation of its own.
-#   exit   0 = allow the stop, non-zero = deny (block the stop) with the
-#          reason on stderr.
+#   stdin  envelope v1 from a native front door via the shared lifecycle bridge.
+#   exit   exit 2 + doflow_decide deny = deny; other faults per IC-011.
 #
 # Depends on lib.sh (require_jq, json_field, ensure_session_dir,
 # run_with_timeout) being discoverable next to this script when it runs — see
@@ -48,18 +44,49 @@
 
 set -euo pipefail
 # shellcheck source=lib.sh
-source "$(dirname "$0")/lib.sh"
-require_jq
-
+source "$_DOFLOW_POLDIR/lib.sh"
 INPUT=$(cat)
-SESSION_ID=$(json_field "$INPUT" ".session_id")
+# Decision records stay off every stream unless a bridge supplied the fd.
+POLICY_DIR=$_DOFLOW_POLDIR
+if [ -f "$POLICY_DIR/contract.sh" ]; then
+  # shellcheck source=contract.sh
+  source "$POLICY_DIR/contract.sh"
+  doflow_decision_init stop-check 1
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure stop-check contract-missing ) >/dev/null 2>&1 || true
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  doflow_decide error dependency-missing:jq
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure stop-check dependency-missing:jq ) >/dev/null 2>&1 || true
+fi
+require_jq
+SESSION_ID="" ENVELOPE_CLASS=missing
+{ IFS= read -r -d '' ENVELOPE_CLASS; IFS= read -r -d '' SESSION_ID; } < <(
+  printf '%s' "$INPUT" | jq -j 'if ((. | type) != "object") or ((.doflow_event | type) != "object") or ((.doflow_event | has("version")) | not) then "missing" elif ((.doflow_event.version | type) == "number") and .doflow_event.version == 1 then "v1" else "unsupported" end, "\u0000", (.session_id // "" | if type == "string" then rtrimstr("\n") else tojson end), "\u0000"' 2>/dev/null
+) || true
+ENVELOPE_CLASS=${ENVELOPE_CLASS:-missing}
+if [ ! -f "$POLICY_DIR/contract.sh" ]; then ENVELOPE_CLASS=missing; fi
+if [ "$ENVELOPE_CLASS" = unsupported ] || [ "$ENVELOPE_CLASS" = missing ]; then
+  code=envelope-version
+  [ "$ENVELOPE_CLASS" = missing ] && code=envelope-missing
+  [ -f "$POLICY_DIR/contract.sh" ] || code=contract-missing
+  doflow_decide unsupported "$code"
+  if [ -f "$POLICY_DIR/contract.sh" ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure stop-check "$code" ) >/dev/null 2>&1 || true
+  fi
+  exit 0
+fi
 
 TRANSCRIPT_PATH=$(json_field "$INPUT" ".transcript_path")
 [ -z "$TRANSCRIPT_PATH" ] && TRANSCRIPT_PATH=$(json_field "$INPUT" ".transcriptPath")
 
 # ── 1. Lint dispatch (only when we have a session-scoped edited-files queue) ──
 
-if [ -n "$SESSION_ID" ]; then
+# With no config home (SESSION_DIR empty) there is no queue to read; the stub check below still runs.
+if [ -n "$SESSION_ID" ] && [ -n "$SESSION_DIR" ]; then
   SESSION_PATH=$(ensure_session_dir "$SESSION_ID")
   EDITED_FILES="$SESSION_PATH/edited-files.txt"
   PROC_FILE="$SESSION_PATH/edited-files.txt.proc"
@@ -79,12 +106,14 @@ if [ -n "$SESSION_ID" ]; then
     # The resolver for the leak-scan verb. Absent install -> the scan is
     # skipped, like every other tool below: this hook has never required
     # anything to be present.
+    # HOME may be unset (an absolute XDG_CONFIG_HOME alone gives a config home): its candidates drop out.
     DOFLOW_RUN=""
+    claude_dir="${CLAUDE_CONFIG_DIR:-${HOME:+$HOME/.claude}}"
     for candidate in \
-      "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/scripts/doflow/bin/doflow-run" \
-      "$HOME/.doflow/scripts/doflow/bin/doflow-run"
+      "${claude_dir:+$claude_dir/scripts/doflow/bin/doflow-run}" \
+      "${HOME:+$HOME/.doflow/scripts/doflow/bin/doflow-run}"
     do
-      [ -x "$candidate" ] && { DOFLOW_RUN="$candidate"; break; }
+      [ -n "$candidate" ] && [ -x "$candidate" ] && { DOFLOW_RUN="$candidate"; break; }
     done
 
     while IFS= read -r path; do
@@ -107,7 +136,7 @@ if [ -n "$SESSION_ID" ]; then
     # before the {} reply is invalid hook output)
     if [ ${#py_files[@]} -gt 0 ]; then
       if command -v ruff &>/dev/null; then
-        nohup ruff format "${py_files[@]}" </dev/null >/dev/null 2>&1 &
+        nohup ruff format "${py_files[@]}" </dev/null >/dev/null 2>&1 3>&- 5>&- &
         run_with_timeout 2 -- ruff check "${py_files[@]}" >&2 || true
       fi
     fi
@@ -115,7 +144,7 @@ if [ -n "$SESSION_ID" ]; then
     # JS/TS: async fix only (eslint --fix rarely needs the caller's immediate attention)
     if [ ${#js_files[@]} -gt 0 ]; then
       if command -v eslint &>/dev/null; then
-        nohup eslint --fix "${js_files[@]}" </dev/null >/dev/null 2>&1 &
+        nohup eslint --fix "${js_files[@]}" </dev/null >/dev/null 2>&1 3>&- 5>&- &
       fi
     fi
 
@@ -129,7 +158,7 @@ if [ -n "$SESSION_ID" ]; then
     # Java: async spotlessApply (slow — only if gradlew exists in cwd)
     if [ "$java_has_files" = "true" ]; then
       if [ -x "./gradlew" ]; then
-        nohup ./gradlew spotlessApply </dev/null >/dev/null 2>&1 &
+        nohup ./gradlew spotlessApply </dev/null >/dev/null 2>&1 3>&- 5>&- &
       fi
     fi
 
@@ -143,6 +172,7 @@ if [ -n "$SESSION_ID" ]; then
       if [ -n "$DOFLOW_RUN" ]; then
         leak_out="$(run_with_timeout 2 -- "$DOFLOW_RUN" leak-scan "${leak_args[@]}" 2>/dev/null || true)"
         if [ -n "$leak_out" ] && printf '%s' "$leak_out" | grep -q ':[0-9]'; then
+          doflow_decide advisory internal-identifiers-found
           printf 'doflow: internal identifiers found in shipped files (warning, not a block):\n%s\n' \
             "$leak_out" >&2
         fi
@@ -161,9 +191,10 @@ fi
 
 # The payload's own last_assistant_message is the response being stopped on. A present key
 # (even null or empty) is authoritative: the transcript is only read when the key is absent.
-# jq filter for the transcript fallback: one JSON object per line, assistant text from three
+# jq filter for the transcript fallback: one JSON object per line, assistant text from four
 # shapes — Claude Code (.message with text blocks), Codex rollout (response_item .payload with
-# output_text blocks) and the flat {role,content} line. A partial or foreign line yields "".
+# output_text blocks), Copilot CLI events.jsonl (type assistant.message, .data.content a string) and
+# the flat {role,content} line. A partial or foreign line yields "".
 read -r -d '' LAST_ASSISTANT_JQ <<'JQ' || true
 def text: if type == "string" then .
   elif type == "array" then [ .[]? | objects | select(.type == "text" or .type == "output_text") | .text | strings ] | join("\n")
@@ -171,6 +202,7 @@ def text: if type == "string" then .
 [ inputs | fromjson? | objects
   | if ((.message | objects | .role) // null) == "assistant" then .message.content
     elif .type == "response_item" and ((.payload | objects | .role) // null) == "assistant" then .payload.content
+    elif .type == "assistant.message" then .data.content
     elif .role == "assistant" then .content
     else empty end
   | text | select(length > 0) ] | last // ""
@@ -248,16 +280,22 @@ if grep -qiE -- "$STUB_PATTERN" <<<"$STUB_TEXT" 2>/dev/null; then
   # Block a given message once: the continuation that follows is judged on new text, and a
   # harness with no stop_hook_active would otherwise be blocked on this one forever. State is
   # per session, or per transcript when the harness sends no session_id; any failure here
-  # leaves the block in force only for this call.
+  # leaves the block in force only for this call. With no config home there is no state store, so
+  # this policy cannot remember a block and allows the stop.
+  [ -n "$SESSION_DIR" ] || exit 0
   GUARD_KEY="$SESSION_ID"
   [ -z "$GUARD_KEY" ] && GUARD_KEY="t$(printf '%s' "$TRANSCRIPT_PATH" | cksum | cut -d' ' -f1)"
-  GUARD_FILE="$(ensure_session_dir "$GUARD_KEY" 2>/dev/null)/stop-last-blocked" || GUARD_FILE=""
+  GUARD_FILE=""
+  if [ -n "$SESSION_DIR" ]; then
+    GUARD_FILE="$(ensure_session_dir "$GUARD_KEY" 2>/dev/null)/stop-last-blocked" || GUARD_FILE=""
+  fi
   MESSAGE_SUM=$(printf '%s' "$LAST_ASSISTANT_CONTENT" | cksum 2>/dev/null) || MESSAGE_SUM=""
   if [ -n "$MESSAGE_SUM" ] && [ -n "$GUARD_FILE" ] && [ "$(cat "$GUARD_FILE" 2>/dev/null)" = "$MESSAGE_SUM" ]; then
     exit 0
   fi
   [ -n "$MESSAGE_SUM" ] && [ -n "$GUARD_FILE" ] && { printf '%s\n' "$MESSAGE_SUM" > "$GUARD_FILE"; } 2>/dev/null || true
   echo "[stop-check] The last response contains an unfinished-work marker (TODO/FIXME/stub comment or a not-implemented raise/throw)." >&2
+  doflow_decide deny unfinished-work
   exit 2
 fi
 

package/core/harnesses/shared/hooks/policies/subagent-audit.sh

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
+case "${OSTYPE:-}" in msys*|cygwin*|win32*) if command -v jq >/dev/null 2>&1; then jq() { command jq -b "$@"; }; fi ;; esac # native jq.exe ends lines with CRLF unless -b
+_DOFLOW_SRC=${0//\\//}; case $_DOFLOW_SRC in */*) _DOFLOW_POLDIR=${_DOFLOW_SRC%/*} ;; *) _DOFLOW_POLDIR=. ;; esac
 # subagent-audit.sh — Canonical Policy Library: SubagentStart + SubagentStop hook
 # (pure observability, no deny path)
 #
 # 022-hooks-remaining-duplication: claude and codex's copies were byte-identical — moved here as
-# the single canonical copy. Gemini has no SubagentStart/SubagentStop-equivalent event.
+# the single canonical copy.
 #
 # Appends {timestamp, session_id, event, agent_type, agent_id} to a session-scoped audit log.
 # Today there is zero record of which of the installed agents/ specialists actually run, how often, or
@@ -18,14 +20,45 @@
 
 set -euo pipefail
 # shellcheck source=lib.sh
-source "$(dirname "$0")/lib.sh"
-require_jq
-
+source "$_DOFLOW_POLDIR/lib.sh"
 INPUT=$(cat)
-SESSION_ID=$(json_field "$INPUT" ".session_id")
+POLICY_DIR=$_DOFLOW_POLDIR
+if [ -f "$POLICY_DIR/contract.sh" ]; then
+  # shellcheck source=contract.sh
+  source "$POLICY_DIR/contract.sh"
+  doflow_decision_init subagent-audit 1
+else
+  doflow_decision_init() { :; }
+  doflow_decide() { :; }
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure subagent-audit contract-missing ) >/dev/null 2>&1 || true
+  exit 0
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  doflow_decide error dependency-missing:jq
+  ( . "$POLICY_DIR/capture-failure.sh"; doflow_capture_failure subagent-audit dependency-missing:jq ) >/dev/null 2>&1 || true
+fi
+require_jq
+SESSION_ID="" ENVELOPE_CLASS=missing
+{ IFS= read -r -d '' ENVELOPE_CLASS; IFS= read -r -d '' SESSION_ID; } < <(
+  printf '%s' "$INPUT" | jq -j 'if ((. | type) != "object") or ((.doflow_event | type) != "object") or ((.doflow_event | has("version")) | not) then "missing" elif ((.doflow_event.version | type) == "number") and .doflow_event.version == 1 then "v1" else "unsupported" end, "\u0000", (.session_id // "" | if type == "string" then rtrimstr("\n") else tojson end), "\u0000"' 2>/dev/null
+) || true
+ENVELOPE_CLASS=${ENVELOPE_CLASS:-missing}
+if [ ! -f "$POLICY_DIR/contract.sh" ]; then ENVELOPE_CLASS=missing; fi
+if [ "$ENVELOPE_CLASS" = unsupported ] || [ "$ENVELOPE_CLASS" = missing ]; then
+  code=envelope-version
+  [ "$ENVELOPE_CLASS" = missing ] && code=envelope-missing
+  [ -f "$POLICY_DIR/contract.sh" ] || code=contract-missing
+  doflow_decide unsupported "$code"
+  if [ -f "$POLICY_DIR/contract.sh" ]; then
+    ( . "$_DOFLOW_POLDIR/capture-failure.sh"; doflow_capture_failure subagent-audit "$code" ) >/dev/null 2>&1 || true
+  fi
+  exit 0
+fi
 
 # Guard: if we can't determine the session, nothing to do
 [[ -z "$SESSION_ID" ]] && exit 0
+# No config home (lib.sh leaves the state paths empty): no session store to write (086 IC-010).
+[[ -n "$SESSION_DIR" ]] || exit 0
 
 EVENT=$(json_field "$INPUT" ".hook_event_name")
 AGENT_TYPE=$(json_field "$INPUT" ".agent_type")
@@ -41,6 +74,6 @@ jq -nc \
   --arg agent_type "$AGENT_TYPE" \
   --arg agent_id "$AGENT_ID" \
   '{timestamp: $ts, session_id: $session, event: $event, agent_type: $agent_type, agent_id: $agent_id}' \
-  >> "$SESSION_PATH/subagent-audit.log" 2>/dev/null || true
+  >> "$SESSION_PATH/subagent-audit.log" 2>/dev/null || doflow_decide error audit-write-failed
 
 exit 0

package/core/harnesses/shared/hooks/policies/summary-store.sh

@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+# summary-store.sh — Canonical Policy Library: scoped compact summaries, grants and the legacy
+# adopter (feature 078, IC-010, IC-011 store write, IC-012, IC-014; DEC-003, DEC-012, DEC-014).
+#
+# Layout under STATE_DIR (lib.sh: <config home>/doflow/session-env; empty with no config home, and
+# then there is no store: peeks find nothing, writes, claims and adopts return 1):
+#   summaries/<worktreeKey>/<run>/<lineage>/summary.md            one pending summary per scope
+#   summaries/<worktreeKey>/<run>/<lineage>/.summary.XXXXXX       write temporary
+#   summaries/<worktreeKey>/<run>/<lineage>/.claimed.<unitId>     claim temporary
+#   grants/<run>/<lineage>/<summaryId>.md                         grant addressed to a recipient
+#   grants/<run>/<lineage>/.claimed.<unitId>.<summaryId>          claim temporary
+# worktreeKey is cwd_hash of the identity worktree (DEC-027), so the caller must have sourced
+# lib.sh, which defines cwd_hash, STATE_DIR and PROJECTS_DIR.
+#
+# Sourcing this file defines functions only: no option, no variable, no trap, no output. bash 3.2
+# safe and safe under the caller's `set -euo pipefail`. Peek functions always return 0; write,
+# claim and adopt return 0 when they did their work and 1 otherwise, so call them from `if` or
+# with `||`. Results are DF_SUMMARY_* and DF_GRANT_* variables. A claimed file is left in place for
+# the caller to pass to emission.jq (--rawfile summary or grant) and to remove after rendering.
+
+# The id pattern of IC-007 (DEC-024) and the summary id pattern of IC-010.
+_doflow_ss_id_ok() { [[ ${1:-} =~ ^[A-Za-z0-9][A-Za-z0-9_-]{0,55}$ ]]; }
+_doflow_ss_summary_id_ok() { [[ ${1:-} =~ ^s-[0-9]{8}T[0-9]{6}Z-[A-Za-z0-9]{6}$ ]]; }
+# A unit id (L.<run>.<lineage>.<attempt> or a harness session id) is one path segment.
+_doflow_ss_unit_ok() { [[ ${1:-} =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ ]]; }
+
+# _doflow_ss_root: _DF_SS_ROOT = lib.sh's STATE_DIR; returns 1 when it is empty (no config home).
+_doflow_ss_root() {
+  _DF_SS_ROOT="${STATE_DIR:-}"
+  [ -n "$_DF_SS_ROOT" ]
+}
+
+# _doflow_ss_key <dir>: _DF_SS_KEY = cwd_hash <dir>, remembered for the last directory asked.
+_doflow_ss_key() {
+  if [ -n "${_DF_SS_KEY_FOR:-}" ] && [ "$_DF_SS_KEY_FOR" = "$1" ] && [ -n "${_DF_SS_KEY:-}" ]; then
+    return 0
+  fi
+  _DF_SS_KEY=""
+  _DF_SS_KEY_FOR=""
+  [ -n "$1" ] || return 1
+  declare -F cwd_hash >/dev/null 2>&1 || return 1
+  _DF_SS_KEY=$(cwd_hash "$1" 2>/dev/null) || _DF_SS_KEY=""
+  [[ $_DF_SS_KEY =~ ^[0-9a-f]{16}$ ]] || { _DF_SS_KEY=""; return 1; }
+  _DF_SS_KEY_FOR=$1
+  return 0
+}
+
+# doflow_summary_scope <worktree> <run> <lineage>
+# DF_SUMMARY_SCOPE = summaries/<worktreeKey>/<run>/<lineage>, or empty (return 1) when run or
+# lineage is not an id, or the lineage is `solo`, which has no scope directory.
+doflow_summary_scope() {
+  DF_SUMMARY_SCOPE=""
+  _doflow_ss_id_ok "${2:-}" && _doflow_ss_id_ok "${3:-}" && [ "$3" != solo ] || return 1
+  _doflow_ss_key "${1:-}" || return 1
+  _doflow_ss_root || return 1
+  DF_SUMMARY_SCOPE="$_DF_SS_ROOT/summaries/$_DF_SS_KEY/$2/$3"
+  return 0
+}
+
+# _doflow_ss_head <file>: reads the frontmatter the way emission.jq's parse_record does (\r removed,
+# fields between the first two `---` lines, first match wins, leading spaces of a value dropped),
+# never more than 65536 bytes. Sets _DF_SS_SESSION, _DF_SS_SID, and for the grant header
+# _DF_SS_FROM (from_lineage), _DF_SS_AT (compacted_at) and _DF_SS_BRANCH (branch).
+_doflow_ss_head() {
+  local LC_ALL=C line="" left=65536 fences=0 key value seen=" "
+  _DF_SS_SESSION=""
+  _DF_SS_SID=""
+  _DF_SS_FROM=""
+  _DF_SS_AT=""
+  _DF_SS_BRANCH=""
+  {
+    while [ "$left" -gt 0 ] && [ "$fences" -lt 2 ]; do
+      IFS= read -r -n "$left" line || [ -n "$line" ] || break
+      left=$((left - ${#line} - 1))
+      line=${line//$'\r'/}
+      if [ "$line" = "---" ]; then
+        fences=$((fences + 1))
+      elif [ "$fences" = 1 ] && [[ $line == ?*:* ]]; then
+        key=${line%%:*}
+        value=${line#*:}
+        while [ "${value# }" != "$value" ]; do value=${value# }; done
+        # The first match of a key wins: a wanted key is recorded in $seen once it is read.
+        case "$key" in
+          session_id | summary_id | from_lineage | compacted_at | branch)
+            case "$seen" in *" $key "*) key="" ;; esac ;;
+          *) key="" ;;
+        esac
+        case "$key" in
+          session_id) _DF_SS_SESSION=$value ;;
+          summary_id) _DF_SS_SID=$value ;;
+          from_lineage) _DF_SS_FROM=$value ;;
+          compacted_at) _DF_SS_AT=$value ;;
+          branch) _DF_SS_BRANCH=$value ;;
+        esac
+        [ -z "$key" ] || seen="$seen$key "
+      fi
+      line=""
+    done
+  } 2>/dev/null <"$1" || true
+  return 0
+}
+
+# _doflow_ss_body_bytes <file>: _DF_SS_BODY = the UTF-8 byte length of the record body exactly as
+# parse_record yields it (\r removed, from the first non-empty line after the second `---`,
+# trailing newlines dropped). The caller has bounded the file's size.
+_doflow_ss_body_bytes() {
+  local LC_ALL=C line="" fences=0 started=0 gap=0
+  _DF_SS_BODY=0
+  {
+    while IFS= read -r line || [ -n "$line" ]; do
+      line=${line//$'\r'/}
+      if [ "$fences" -lt 2 ]; then
+        [ "$line" != "---" ] || fences=$((fences + 1))
+      elif [ -z "$line" ]; then
+        [ "$started" = 0 ] || gap=$((gap + 1))
+      elif [ "$started" = 0 ]; then
+        started=1
+        _DF_SS_BODY=${#line}
+      else
+        _DF_SS_BODY=$((_DF_SS_BODY + gap + 1 + ${#line}))
+        gap=0
+      fi
+      line=""
+    done
+  } 2>/dev/null <"$1" || true
+  return 0
+}
+
+# _doflow_ss_size <file>: _DF_SS_SIZE = the file's size in bytes, or empty.
+_doflow_ss_size() {
+  _DF_SS_SIZE=$(wc -c 2>/dev/null <"$1") || _DF_SS_SIZE=""
+  _DF_SS_SIZE=${_DF_SS_SIZE//[!0-9]/}
+  return 0
+}
+
+# doflow_summary_write <worktree> <run> <lineage> <attempt> <compacted_at> <session_id> <trigger>
+#                      <branch> <role> <body>
+# IC-011 step 3: mkdir -p the scope, mktemp .summary.XXXXXX in it, write the IC-010 record, mv it to
+# summary.md (a newer compaction replaces the pending one). compacted_at is UTC ISO-8601 to the
+# second (YYYY-MM-DDTHH:MM:SSZ). Sets DF_SUMMARY_ID and DF_SUMMARY_PATH. Returns 1 with nothing left
+# behind on an invalid argument, an empty body or a failed step.
+doflow_summary_write() {
+  local worktree="${1:-}" run="${2:-}" lineage="${3:-}" attempt="${4:-}" at="${5:-}"
+  local session="${6:-}" trigger="${7:-}" branch="${8:-}" role="${9:-}" body="${10:-}"
+  local tmp="" stamp suffix nl=$'\n' cr=$'\r'
+  DF_SUMMARY_ID=""
+  DF_SUMMARY_PATH=""
+  [ -n "$body" ] || return 1
+  [[ $at =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$ ]] || return 1
+  [ -z "$attempt" ] || [[ $attempt =~ ^[1-9][0-9]{0,3}$ ]] || return 1
+  doflow_summary_scope "$worktree" "$run" "$lineage" || return 1
+  # A frontmatter value is one line: an embedded line break would forge a key.
+  session=${session//[$nl$cr]/ }; trigger=${trigger//[$nl$cr]/ }; branch=${branch//[$nl$cr]/ }
+  role=${role//[$nl$cr]/ }; worktree=${worktree//[$nl$cr]/ }
+  mkdir -p "$DF_SUMMARY_SCOPE" 2>/dev/null || return 1
+  tmp=$(mktemp "$DF_SUMMARY_SCOPE/.summary.XXXXXX" 2>/dev/null) || return 1
+  suffix=${tmp##*.summary.}
+  stamp=${at//[-:]/}
+  DF_SUMMARY_ID="s-$stamp-$suffix"
+  if ! _doflow_ss_summary_id_ok "$DF_SUMMARY_ID" \
+    || ! printf -- '---\ncompacted_at: %s\nsession_id: %s\ntrigger: %s\nbranch: %s\nrole: %s\nsummary_id: %s\nrun: %s\nlineage: %s\nattempt:%s\nworktree: %s\n---\n\n%s\n' \
+      "$at" "${session:-unknown}" "${trigger:-unknown}" "${branch:-unknown}" "${role:-main}" \
+      "$DF_SUMMARY_ID" "$run" "$lineage" "${attempt:+ $attempt}" "$worktree" "$body" >"$tmp" 2>/dev/null \
+    || ! mv -f "$tmp" "$DF_SUMMARY_SCOPE/summary.md" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null || true
+    DF_SUMMARY_ID=""
+    return 1
+  fi
+  DF_SUMMARY_PATH="$DF_SUMMARY_SCOPE/summary.md"
+  return 0
+}
+
+# doflow_summary_peek <worktree> <run> <lineage> <session_id>
+# IC-012 owner steps 1 and 2, for the state vector: DF_SUMMARY_OWN is `none` (no regular,
+# non-symlink summary.md in the scope), `own-write` (its frontmatter session_id is this session's)
+# or `pending`; DF_SUMMARY_FILE is its path and DF_SUMMARY_SID its frontmatter summary_id (possibly
+# empty) when not `none`. Always returns 0.
+doflow_summary_peek() {
+  local f
+  DF_SUMMARY_OWN=none
+  DF_SUMMARY_FILE=""
+  DF_SUMMARY_SID=""
+  doflow_summary_scope "${1:-}" "${2:-}" "${3:-}" || return 0
+  f="$DF_SUMMARY_SCOPE/summary.md"
+  [ -f "$f" ] && [ ! -L "$f" ] || return 0
+  _doflow_ss_head "$f"
+  DF_SUMMARY_FILE=$f
+  DF_SUMMARY_SID=$_DF_SS_SID
+  if [ -n "${4:-}" ] && [ "$_DF_SS_SESSION" = "$4" ]; then DF_SUMMARY_OWN=own-write; else DF_SUMMARY_OWN=pending; fi
+  return 0
+}
+
+# doflow_summary_claim <worktree> <run> <lineage> <unit_id> <session_id>
+# IC-012 owner steps 1 to 3: peek, then rename summary.md to .claimed.<unitId>; a summary written
+# after the rename is a new summary.md and survives. The claimed copy is cut to its first 65536
+# bytes. Sets DF_SUMMARY_OWN (as peek, `none` after a lost rename), DF_SUMMARY_CLAIMED (the claimed
+# path, for --rawfile summary) and DF_SUMMARY_BYTES (its full size before the cut, for
+# plan.summaryBytes). Returns 0 when this caller claimed it; the caller removes the claimed file.
+doflow_summary_claim() {
+  local unit="${4:-}" claimed
+  DF_SUMMARY_CLAIMED=""
+  DF_SUMMARY_BYTES=0
+  doflow_summary_peek "${1:-}" "${2:-}" "${3:-}" "${5:-}"
+  [ "$DF_SUMMARY_OWN" = pending ] || return 1
+  _doflow_ss_unit_ok "$unit" || return 1
+  claimed="$DF_SUMMARY_SCOPE/.claimed.$unit"
+  if ! mv "$DF_SUMMARY_FILE" "$claimed" 2>/dev/null; then
+    DF_SUMMARY_OWN=none
+    return 1
+  fi
+  _doflow_ss_size "$claimed"
+  DF_SUMMARY_BYTES=${_DF_SS_SIZE:-0}
+  if [ "$DF_SUMMARY_BYTES" -gt 65536 ]; then
+    # The cut copy is private to this user, as the record it replaces (L1-11).
+    if ! { (umask 077; head -c 65536 "$claimed" >"$claimed.read") 2>/dev/null && mv -f "$claimed.read" "$claimed" 2>/dev/null; }; then
+      rm -f "$claimed" "$claimed.read" 2>/dev/null || true
+      return 1
+    fi
+  fi
+  DF_SUMMARY_CLAIMED=$claimed
+  return 0
+}
+
+# _doflow_ss_known <value>: _DF_SS_KNOWN = emission.jq's `known`: `]` removed, then empty when it
+# is "unknown".
+_doflow_ss_known() {
+  _DF_SS_KNOWN=${1//]/}
+  [ "$_DF_SS_KNOWN" != unknown ] || _DF_SS_KNOWN=""
+  return 0
+}
+
+# doflow_grant_peek <run> <lineage> <max_bytes>
+# IC-012 grant steps 1 and 2: the oldest grants/<run>/<lineage>/<summaryId>.md by name among regular,
+# non-symlink files whose name matches the summary id pattern. DF_GRANT is `none`, `fits` or `over`.
+# It fits exactly when emission.jq would render it whole: the UTF-8 bytes of render_grant's segment
+# "[Granted summary from lineage <from_lineage><header_tail>]\n<body>" are at most max_bytes, so a
+# body that fits under a header that does not is `over` and is never claimed. DF_GRANT_FILE,
+# DF_GRANT_ID and DF_GRANT_BYTES (the body's bytes, for the pointer; empty when the file is too large
+# to be worth reading) describe it. Always returns 0.
+doflow_grant_peek() {
+  local LC_ALL=C run="${1:-}" lineage="${2:-}" max="${3:-}" dir f name header tail=""
+  DF_GRANT=none
+  DF_GRANT_FILE=""
+  DF_GRANT_ID=""
+  DF_GRANT_BYTES=""
+  _doflow_ss_id_ok "$run" && _doflow_ss_id_ok "$lineage" || return 0
+  [[ $max =~ ^[1-9][0-9]{0,9}$ ]] || return 0
+  _doflow_ss_root || return 0
+  dir="$_DF_SS_ROOT/grants/$run/$lineage"
+  [ -d "$dir" ] && [ ! -L "$dir" ] || return 0
+  # Glob expansion is sorted (C collation here), and summary ids sort by time.
+  for f in "$dir"/s-*.md; do
+    name=${f##*/}
+    name=${name%.md}
+    _doflow_ss_summary_id_ok "$name" || continue
+    [ -f "$f" ] && [ ! -L "$f" ] || continue
+    DF_GRANT_FILE=$f
+    DF_GRANT_ID=$name
+    break
+  done
+  [ -n "$DF_GRANT_FILE" ] || return 0
+  _doflow_ss_size "$DF_GRANT_FILE"
+  # A frontmatter needs far less than 65536 bytes: anything larger than that plus the budget is over.
+  if [ -n "$_DF_SS_SIZE" ] && [ "$_DF_SS_SIZE" -le $((max + 65536)) ]; then
+    _doflow_ss_body_bytes "$DF_GRANT_FILE"
+    DF_GRANT_BYTES=$_DF_SS_BODY
+    # render_grant's header, from the same bounded head pass parse_record's fields come from.
+    _doflow_ss_head "$DF_GRANT_FILE"
+    _doflow_ss_known "$_DF_SS_AT"
+    [ -z "$_DF_SS_KNOWN" ] || tail=", compacted $_DF_SS_KNOWN"
+    _doflow_ss_known "$_DF_SS_BRANCH"
+    [ -z "$_DF_SS_KNOWN" ] || tail="$tail on branch $_DF_SS_KNOWN"
+    header="[Granted summary from lineage $_DF_SS_FROM$tail]"
+    if [ $((${#header} + 1 + DF_GRANT_BYTES)) -le "$max" ]; then DF_GRANT=fits; else DF_GRANT=over; fi
+  else
+    DF_GRANT=over
+  fi
+  return 0
+}
+
+# doflow_grant_claim <run> <lineage> <unit_id> <max_bytes>
+# IC-012 grant step 3: peek; when the oldest grant fits, rename it to
+# .claimed.<unitId>.<summaryId> and set DF_GRANT_CLAIMED (for --rawfile grant); the caller removes
+# it after rendering. An `over` grant stays in place (DF_GRANT_FILE renders the pointer). One grant
+# per event. Returns 0 only when this caller claimed a grant.
+doflow_grant_claim() {
+  local unit="${3:-}" claimed
+  DF_GRANT_CLAIMED=""
+  doflow_grant_peek "${1:-}" "${2:-}" "${4:-}"
+  [ "$DF_GRANT" = fits ] || return 1
+  _doflow_ss_unit_ok "$unit" || return 1
+  claimed="${DF_GRANT_FILE%/*}/.claimed.$unit.$DF_GRANT_ID"
+  if ! mv "$DF_GRANT_FILE" "$claimed" 2>/dev/null; then
+    DF_GRANT=none
+    return 1
+  fi
+  DF_GRANT_CLAIMED=$claimed
+  return 0
+}
+
+# doflow_summary_adopt_legacy <cwd> <worktree> [check]
+# IC-014, on action `adopt` only: the pre-078 project summary under projects/<cwd_hash cwd>/, a
+# regular file and not a symlink, moves once into summaries/<worktreeKey>/local/main/summary.md
+# with its frontmatter kept. When a summary is already pending there it is newer by construction
+# and the old file is removed instead. The legacy file is first renamed to <old>.adopting.<pid>, so
+# only one adopter proceeds (a lost rename means another adopter won and returns 0, DEC-043); then
+# a hard link that refuses to replace, and the .adopting file is unlinked last, so a summary written
+# meanwhile is never overwritten. Without hard links, `mv -n` is the fallback, taken only when the
+# target is absent and verified afterwards. Nothing writes the old path. Returns 0 when a legacy
+# file was adopted or retired, or another adopter took it. With a third argument `check` it only tests that the
+# legacy file exists and changes nothing (doflow_summary_legacy_present). This function is the one
+# place that names the legacy file (G38.4).
+doflow_summary_adopt_legacy() {
+  local cwd="${1:-}" worktree="${2:-}" projects old new taken
+  [ -n "$cwd" ] || return 1
+  [ -n "$worktree" ] || worktree=$cwd
+  _doflow_ss_key "$cwd" || return 1
+  _doflow_ss_root || return 1
+  projects="${PROJECTS_DIR:-$_DF_SS_ROOT/projects}"
+  old="$projects/$_DF_SS_KEY/last-compact-summary.md"
+  [ -f "$old" ] && [ ! -L "$old" ] || return 1
+  [ "${3:-}" != check ] || return 0
+  doflow_summary_scope "$worktree" local main || return 1
+  new="$DF_SUMMARY_SCOPE/summary.md"
+  mkdir -p "$DF_SUMMARY_SCOPE" 2>/dev/null || return 1
+  taken="$old.adopting.$$"
+  mv "$old" "$taken" 2>/dev/null || return 0
+  # A link that refuses to replace; it fails when a summary is pending, which retires the legacy one.
+  if ! ln "$taken" "$new" 2>/dev/null && [ ! -e "$new" ] && [ ! -L "$new" ]; then
+    # No hard links on this filesystem: a rename that refuses to replace, then a check that $new is
+    # the adopted file (mv -n leaves the source in place when the target appeared meanwhile).
+    # The old path is never written again, so a failed rename leaves the .adopting file in place.
+    mv -n "$taken" "$new" 2>/dev/null || true
+    if [ -e "$taken" ] && [ ! -e "$new" ] && [ ! -L "$new" ]; then return 1; fi
+  fi
+  rm -f "$taken" 2>/dev/null || true
+  return 0
+}
+
+# doflow_summary_legacy_present <cwd>
+# Returns 0 when the pre-078 project summary under projects/<cwd_hash cwd>/ exists as a regular file
+# and not a symlink, and 1 otherwise. Runs adopt_legacy's check mode in a subshell, so it sets no
+# variable, prints nothing and changes nothing.
+doflow_summary_legacy_present() {
+  [ -n "${1:-}" ] || return 1
+  (doflow_summary_adopt_legacy "$1" "" check)
+}