crewly 1.20.302 → 1.20.303

package/config/roles/developer/prompt.md

@@ -406,6 +406,13 @@ Default tier: **Fast Path** (greenfield, internal tools, prototypes). Escalate t
 - The Owner is consulted only for goal change, scope change, customer-facing commitment, irreversible expense, or strategic direction.
 
 
+## Long Builds and Background Forks
+
+- Do long multi-step builds (rendering, video, large refactors) in the foreground of your own turn. That is the default.
+- A background subagent or fork can die silently, and then nobody delivers what you promised. If you do use one, keep its description specific, tell the owner only what you can verify, and check on it: look at its output or transcript yourself within a few minutes, and do not end the turn on "it will report back" without a plan for when you look.
+- Crewly tells you when a background task made no progress for about 10 minutes (`[BACKGROUND TASK STALLED]`). When you see it, inspect what it produced and continue the work yourself in the foreground.
+- A promise to the owner ("starting now, will post here") stays yours until the result is posted, whoever does the work.
+
 ## Lazy Behavior Anti-Patterns
 
 You are failing the task if you:

package/config/roles/fullstack-dev/prompt.md

@@ -186,6 +186,13 @@ Default tier: **Fast Path** (greenfield, internal tools, prototypes). Escalate t
 - The Owner is consulted only for goal change, scope change, customer-facing commitment, irreversible expense, or strategic direction.
 
 
+## Long Builds and Background Forks
+
+- Do long multi-step builds (rendering, video, large refactors) in the foreground of your own turn. That is the default.
+- A background subagent or fork can die silently, and then nobody delivers what you promised. If you do use one, keep its description specific, tell the owner only what you can verify, and check on it: look at its output or transcript yourself within a few minutes, and do not end the turn on "it will report back" without a plan for when you look.
+- Crewly tells you when a background task made no progress for about 10 minutes (`[BACKGROUND TASK STALLED]`). When you see it, inspect what it produced and continue the work yourself in the foreground.
+- A promise to the owner ("starting now, will post here") stays yours until the result is posted, whoever does the work.
+
 ## Lazy Behavior Anti-Patterns
 
 You are failing the task if you:

package/config/roles/product-manager/prompt.md

@@ -296,6 +296,13 @@ Default tier: **Standard Path** (customer-facing or coordination work). Drop to
 - The Owner is consulted only for goal change, scope change, customer-facing commitment, irreversible expense, or strategic direction.
 
 
+## Long Builds and Background Forks
+
+- Do long multi-step builds (rendering, video, large refactors) in the foreground of your own turn. That is the default.
+- A background subagent or fork can die silently, and then nobody delivers what you promised. If you do use one, keep its description specific, tell the owner only what you can verify, and check on it: look at its output or transcript yourself within a few minutes, and do not end the turn on "it will report back" without a plan for when you look.
+- Crewly tells you when a background task made no progress for about 10 minutes (`[BACKGROUND TASK STALLED]`). When you see it, inspect what it produced and continue the work yourself in the foreground.
+- A promise to the owner ("starting now, will post here") stays yours until the result is posted, whoever does the work.
+
 ## Lazy Behavior Anti-Patterns
 
 You are failing the task if you:

package/config/skills/orchestrator/usage-categories/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: Usage Categories
+description: Save, list or remove the owner's own categories for usage reports (for example "self-media" and "book"). Categories are optional and only change how reports group tickets; they never alter ticket facts.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+triggers:
+  - usage categories
+  - track time by category
+  - split usage into
+  - count self-media separately
+tags:
+  - usage
+  - categories
+  - report
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 20000
+---
+
+# Usage Categories
+
+The owner decides how usage should be grouped ("how much on self-media vs the book?"). Turn what they say into a category and save it. Nothing is required: with no categories, reports group by team.
+
+## Usage
+
+```bash
+bash execute.sh list
+
+# The description doubles as the keyword list when it is comma separated
+bash execute.sh set --name self-media --description "Xiaohongshu, Substack, LinkedIn, videos"
+
+# Explicit hints: keywords match ticket titles and text; teams / projects match by name
+bash execute.sh set --name book --keywords "chapter,manuscript,Bible study book" --teams "Writers"
+
+bash execute.sh remove --name book
+bash execute.sh clear
+```
+
+## How a ticket gets its category
+
+At report time, in this order:
+
+1. Keywords (case-insensitive), then team and project hints. The best score wins.
+2. If nothing matched and a small model is available, one batched question for the unmatched tickets.
+3. Otherwise `other`.
+
+The result is cached per ticket and category set, and changes the moment a definition changes. Tickets themselves are never modified, so redefining categories re-slices all past usage.
+
+## Etiquette
+
+- Use the owner's own words for names. Do not invent categories they did not ask for.
+- After saving, offer to run `usage-report --by category` so they see the split.
+- `other` is reserved and cannot be defined.

package/config/skills/orchestrator/usage-categories/execute.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# The owner's report categories ("self-media", "book", ...).
+#
+# Usage:
+#   execute.sh list
+#   execute.sh set --name self-media --description "Xiaohongshu, Substack, LinkedIn, videos" \
+#                  [--keywords a,b,c] [--teams "Marketing,Media"] [--projects "Site,Newsletter"]
+#   execute.sh remove --name self-media
+#   execute.sh clear
+#   execute.sh '{"command":"set","name":"book","keywords":["chapter","manuscript"]}'
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+COMMAND=""
+NAME=""
+DESCRIPTION=""
+KEYWORDS=""
+TEAMS=""
+PROJECTS=""
+INPUT_JSON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+elif [[ $# -gt 0 && ${1:0:2} != '--' ]]; then
+  COMMAND="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name)        NAME="$2";        shift 2 ;;
+    --description) DESCRIPTION="$2"; shift 2 ;;
+    --keywords)    KEYWORDS="$2";    shift 2 ;;
+    --teams)       TEAMS="$2";       shift 2 ;;
+    --projects)    PROJECTS="$2";    shift 2 ;;
+    --help|-h)
+      echo "Usage: execute.sh list | set --name N [--description D] [--keywords a,b] [--teams a,b] [--projects a,b] | remove --name N | clear"
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+if [[ -n "$INPUT_JSON" ]]; then
+  [[ -z "$COMMAND" ]]     && COMMAND=$(echo "$INPUT_JSON" | jq -r '.command // empty' 2>/dev/null || true)
+  [[ -z "$NAME" ]]        && NAME=$(echo "$INPUT_JSON" | jq -r '.name // empty' 2>/dev/null || true)
+  [[ -z "$DESCRIPTION" ]] && DESCRIPTION=$(echo "$INPUT_JSON" | jq -r '.description // empty' 2>/dev/null || true)
+  [[ -z "$KEYWORDS" ]]    && KEYWORDS=$(echo "$INPUT_JSON" | jq -r '.keywords // empty | if type == "array" then join(",") else . end' 2>/dev/null || true)
+  [[ -z "$TEAMS" ]]       && TEAMS=$(echo "$INPUT_JSON" | jq -r '.teams // empty | if type == "array" then join(",") else . end' 2>/dev/null || true)
+  [[ -z "$PROJECTS" ]]    && PROJECTS=$(echo "$INPUT_JSON" | jq -r '.projects // empty | if type == "array" then join(",") else . end' 2>/dev/null || true)
+fi
+
+require_param "command (list|set|remove|clear)" "$COMMAND"
+
+case "$COMMAND" in
+  list)
+    api_call GET "/usage-ledger/categories"
+    ;;
+  set)
+    require_param "name" "$NAME"
+    BODY=$(jq -n --arg name "$NAME" --arg description "$DESCRIPTION" --arg keywords "$KEYWORDS" --arg teams "$TEAMS" --arg projects "$PROJECTS" '
+      def list($s): $s | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0));
+      { name: $name }
+      + (if $description != "" then { description: $description } else {} end)
+      + (if $keywords != "" then { keywords: list($keywords) } else {} end)
+      + (if $teams != "" then { teams: list($teams) } else {} end)
+      + (if $projects != "" then { projects: list($projects) } else {} end)')
+    api_call POST "/usage-ledger/categories" "$BODY"
+    ;;
+  remove)
+    require_param "name" "$NAME"
+    api_call DELETE "/usage-ledger/categories/$(jq -rn --arg n "$NAME" '$n|@uri')"
+    ;;
+  clear)
+    api_call PUT "/usage-ledger/categories" '{"categories":[]}'
+    ;;
+  *)
+    error_exit "Unknown command: $COMMAND (use list, set, remove or clear)"
+    ;;
+esac

package/config/skills/orchestrator/usage-categories/execute.test.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Tests for usage-categories — run with: bash execute.test.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0; FAIL=0
+check() { local name="$1"; local got="$2"; local want="$3"; if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/orchestrator/usage-categories" "$TMP/skills/orchestrator/_common"
+cp "$HERE/execute.sh" "$TMP/skills/orchestrator/usage-categories/execute.sh"
+REAL_LIB="$(cd "$HERE/../../_common" && pwd)/lib.sh"
+cat > "$TMP/skills/orchestrator/_common/lib.sh" <<'STUB'
+source "$REAL_LIB"
+api_call() { printf '%s|%s|%s' "$1" "$2" "${3:-}" > "$CALL_LOG"; echo '{"success":true}'; }
+STUB
+export REAL_LIB CALL_LOG="$TMP/call"
+
+run() { CODE=0; OUT=$(env -u CREWLY_SESSION_NAME bash "$TMP/skills/orchestrator/usage-categories/execute.sh" "$@" 2>"$TMP/err") || CODE=$?; }
+
+run list
+check "list" "$(cat "$CALL_LOG")" "GET|/usage-ledger/categories|"
+
+run set --name self-media --description "Xiaohongshu, Substack, LinkedIn" --keywords "videos, shorts" --teams "Marketing"
+LOG=$(cat "$CALL_LOG"); M=${LOG%%|*}; REST=${LOG#*|}; P=${REST%%|*}; B=${REST#*|}
+check "set uses POST" "$M $P" "POST /usage-ledger/categories"
+check "set body" "$(printf '%s' "$B" | jq -c '.')" '{"name":"self-media","description":"Xiaohongshu, Substack, LinkedIn","keywords":["videos","shorts"],"teams":["Marketing"]}'
+
+run '{"command":"set","name":"book","keywords":["chapter","manuscript"]}'
+LOG=$(cat "$CALL_LOG"); B=${LOG#*|*|}
+check "JSON input set body" "$(printf '%s' "$B" | jq -c '.')" '{"name":"book","keywords":["chapter","manuscript"]}'
+
+run remove --name "Bible study"
+check "remove encodes the name" "$(cat "$CALL_LOG")" "DELETE|/usage-ledger/categories/Bible%20study|"
+
+run clear
+check "clear" "$(cat "$CALL_LOG")" 'PUT|/usage-ledger/categories|{"categories":[]}'
+
+run set
+check "set needs a name" "$CODE" "1"
+
+run frobnicate
+check "unknown command" "$CODE" "1"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/orchestrator/usage-report/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: Usage Report
+description: How much owner time, agent time and tokens went into each category, team, project, agent or ticket (for example self-media vs the book). Computed from the immutable ticket ledger; categories are applied at report time.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+triggers:
+  - usage report
+  - how much time did we spend
+  - how many tokens
+  - time and tokens per project
+  - where did the tokens go
+tags:
+  - usage
+  - tokens
+  - time
+  - cost
+  - report
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Usage Report
+
+Answers "how much time and how many tokens went into X?". Every ticket's facts (agent busy time, tokens and estimated cost per model, owner active minutes) are recorded as they happen and never change. This skill adds them up for a window and groups them the way the owner asks.
+
+## Usage
+
+```bash
+# Last 7 days by category (the owner's categories, else by team)
+bash execute.sh --since 7d --by category
+
+# Just the short text to read out or post to Slack
+bash execute.sh --since 30d --by category --text
+
+# Compare two of the owner's categories
+bash execute.sh --since 14d --by category --categories "self-media,book"
+
+# One-off categories (not saved): name:keyword,keyword;name:keyword
+bash execute.sh --since 7d --categories "media:xiaohongshu,substack,linkedin;book:chapter,bible"
+
+# Other groupings
+bash execute.sh --since 7d --by team
+bash execute.sh --since 7d --by project
+bash execute.sh --since 7d --by agent
+bash execute.sh --since 2d --by ticket --limit 10
+```
+
+`--since` takes `24h`, `7d`, `2w` or a date. Figures are summed per UTC hour, so a window edge is accurate to the hour.
+
+## Categories
+
+Categories are never required and never stored on tickets. If the owner has defined categories (see the `usage-categories` skill) the report uses them. If not, tickets are grouped by team (then project). A ticket that matches no category is `other`; usage that happened outside any ticket is `(no ticket)`.
+
+When the owner asks for a new grouping ("how much on self-media vs the book?"), either pass `--categories` for one report or save it with `usage-categories set`.
+
+## Output
+
+Each group has: owner minutes, agent busy minutes, tokens (cost-weighted: cache reads count 0.1x), raw tokens, estimated cost in USD, ticket count and its top 5 tickets. `summary` is a short text suitable for speech or Slack. `notes` lists caveats (for example tickets rebuilt from history are marked inferred).
+
+## Reading the numbers to the owner
+
+- Lead with the summary line, then the two or three biggest groups.
+- Owner minutes are an estimate from message times (messages on one ticket within 10 minutes form one span).
+- Say "about" for cost; it is an API-price estimate, not a bill.

package/config/skills/orchestrator/usage-report/execute.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Usage report: where the owner's time and the agents' tokens went.
+#
+# Usage:
+#   execute.sh [--since 7d] [--until 2026-10-11] [--by category|team|project|agent|ticket]
+#              [--categories "book,self-media" | "media:linkedin,substack;book:chapter"]
+#              [--limit 10] [--text]
+#   execute.sh '{"since":"7d","by":"category"}'
+#
+# --text prints only the short summary (good to read out or post to Slack).
+# Read-only: it changes nothing.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+SINCE=""
+UNTIL=""
+BY=""
+CATEGORIES=""
+LIMIT=""
+TEXT="false"
+INPUT_JSON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since)      SINCE="$2";      shift 2 ;;
+    --until)      UNTIL="$2";      shift 2 ;;
+    --by)         BY="$2";         shift 2 ;;
+    --categories) CATEGORIES="$2"; shift 2 ;;
+    --limit)      LIMIT="$2";      shift 2 ;;
+    --text)       TEXT="true";     shift ;;
+    --help|-h)
+      echo "Usage: execute.sh [--since 7d] [--until DATE] [--by category|team|project|agent|ticket] [--categories NAMES_OR_DEFS] [--limit N] [--text]"
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+if [[ -n "$INPUT_JSON" ]]; then
+  [[ -z "$SINCE" ]]      && SINCE=$(echo "$INPUT_JSON" | jq -r '.since // empty' 2>/dev/null || true)
+  [[ -z "$UNTIL" ]]      && UNTIL=$(echo "$INPUT_JSON" | jq -r '.until // empty' 2>/dev/null || true)
+  [[ -z "$BY" ]]         && BY=$(echo "$INPUT_JSON" | jq -r '.by // empty' 2>/dev/null || true)
+  [[ -z "$CATEGORIES" ]] && CATEGORIES=$(echo "$INPUT_JSON" | jq -r '.categories // empty | if type == "array" then tojson else . end' 2>/dev/null || true)
+  [[ -z "$LIMIT" ]]      && LIMIT=$(echo "$INPUT_JSON" | jq -r '.limit // empty' 2>/dev/null || true)
+  if [[ "$TEXT" != "true" ]]; then TEXT=$(echo "$INPUT_JSON" | jq -r '.text // false' 2>/dev/null || echo false); fi
+fi
+
+QUERY=$(jq -rn \
+  --arg since "${SINCE:-7d}" --arg until "$UNTIL" --arg by "${BY:-category}" \
+  --arg categories "$CATEGORIES" --arg limit "$LIMIT" \
+  '[ "since=" + ($since|@uri), "by=" + ($by|@uri),
+     (if $until != "" then "until=" + ($until|@uri) else empty end),
+     (if $categories != "" then "categories=" + ($categories|@uri) else empty end),
+     (if $limit != "" then "limit=" + ($limit|@uri) else empty end) ] | join("&")')
+
+if ! RESP=$(api_call_full GET "/usage-ledger/report?${QUERY}"); then
+  error_exit "Could not fetch the usage report"
+fi
+
+if [[ "$TEXT" == "true" ]]; then
+  printf '%s' "$RESP" | jq -r '.data.summary // .error // "No report"'
+  exit 0
+fi
+
+# Compact: the full body has every token kind for every group.
+printf '%s' "$RESP" | jq '
+  if .success then
+    { summary: .data.summary,
+      window: .data.window,
+      by: .data.by,
+      categories: .data.categories,
+      totals: { ownerMinutes: .data.totals.ownerMinutes, agentBusyMinutes: .data.totals.agentBusyMinutes,
+                tokens: .data.totals.tokens.budget, rawTokens: .data.totals.tokens.total,
+                costUsd: .data.totals.costUsd, tickets: .data.totals.ticketCount },
+      groups: [ .data.groups[] | { key, ownerMinutes, agentBusyMinutes, tokens: .tokens.budget, rawTokens: .tokens.total,
+                costUsd, tickets: .ticketCount,
+                topTickets: [ .topTickets[] | { ticketId, title, ownerMinutes, agentBusyMinutes, tokens, costUsd } ] } ],
+      notes: .data.notes }
+  else . end'

package/config/skills/orchestrator/usage-report/execute.test.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Tests for usage-report — run with: bash execute.test.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0; FAIL=0
+check() { local name="$1"; local got="$2"; local want="$3"; if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/orchestrator/usage-report" "$TMP/skills/orchestrator/_common"
+cp "$HERE/execute.sh" "$TMP/skills/orchestrator/usage-report/execute.sh"
+REAL_LIB="$(cd "$HERE/../../_common" && pwd)/lib.sh"
+REPORT='{"success":true,"data":{"summary":"Usage, last 7 days: 3 tickets","window":{},"by":"category","categories":null,
+ "totals":{"ownerMinutes":6,"agentBusyMinutes":30,"tokens":{"budget":5000,"total":9000},"costUsd":1.5,"ticketCount":3},
+ "groups":[{"key":"book","ownerMinutes":6,"agentBusyMinutes":30,"tokens":{"budget":5000,"total":9000},"costUsd":1.5,"ticketCount":3,
+   "topTickets":[{"ticketId":"TKT-1","title":"Chapter","ownerMinutes":6,"agentBusyMinutes":30,"tokens":5000,"costUsd":1.5,"inferred":false}]}],"notes":[]}}'
+cat > "$TMP/skills/orchestrator/_common/lib.sh" <<'STUB'
+source "$REAL_LIB"
+api_call() { echo "$1 $2" > "$CALL_LOG"; printf '%s' "$REPORT"; }
+STUB
+export REAL_LIB REPORT CALL_LOG="$TMP/call"
+
+run() { CODE=0; OUT=$(env -u CREWLY_SESSION_NAME bash "$TMP/skills/orchestrator/usage-report/execute.sh" "$@" 2>"$TMP/err") || CODE=$?; }
+
+run
+check "default window and grouping" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=7d&by=category"
+check "compact groups" "$(printf '%s' "$OUT" | jq -c '.groups[0] | [.key, .tokens, .topTickets[0].ticketId]')" '["book",5000,"TKT-1"]'
+check "totals flattened" "$(printf '%s' "$OUT" | jq -c '.totals.tickets')" "3"
+
+run --since 30d --by team --limit 5 --categories "media:linkedin,substack;book"
+check "flags in the query, encoded" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=30d&by=team&categories=media%3Alinkedin%2Csubstack%3Bbook&limit=5"
+
+run '{"since":"2w","by":"project"}'
+check "JSON input" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=2w&by=project"
+
+run --text
+check "--text prints the summary only" "$OUT" "Usage, last 7 days: 3 tickets"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/team-leader/usage-report/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: Usage Report
+description: How much owner time, agent time and tokens went into each category, team, project, agent or ticket (for example self-media vs the book). Computed from the immutable ticket ledger; categories are applied at report time.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+triggers:
+  - usage report
+  - how much time did we spend
+  - how many tokens
+  - time and tokens per project
+  - where did the tokens go
+tags:
+  - usage
+  - tokens
+  - time
+  - cost
+  - report
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Usage Report
+
+Answers "how much time and how many tokens went into X?". Every ticket's facts (agent busy time, tokens and estimated cost per model, owner active minutes) are recorded as they happen and never change. This skill adds them up for a window and groups them the way the owner asks.
+
+## Usage
+
+```bash
+# Last 7 days by category (the owner's categories, else by team)
+bash execute.sh --since 7d --by category
+
+# Just the short text to read out or post to Slack
+bash execute.sh --since 30d --by category --text
+
+# Compare two of the owner's categories
+bash execute.sh --since 14d --by category --categories "self-media,book"
+
+# One-off categories (not saved): name:keyword,keyword;name:keyword
+bash execute.sh --since 7d --categories "media:xiaohongshu,substack,linkedin;book:chapter,bible"
+
+# Other groupings
+bash execute.sh --since 7d --by team
+bash execute.sh --since 7d --by project
+bash execute.sh --since 7d --by agent
+bash execute.sh --since 2d --by ticket --limit 10
+```
+
+`--since` takes `24h`, `7d`, `2w` or a date. Figures are summed per UTC hour, so a window edge is accurate to the hour.
+
+## Categories
+
+Categories are never required and never stored on tickets. If the owner has defined categories (see the `usage-categories` skill) the report uses them. If not, tickets are grouped by team (then project). A ticket that matches no category is `other`; usage that happened outside any ticket is `(no ticket)`.
+
+When the owner asks for a new grouping ("how much on self-media vs the book?"), either pass `--categories` for one report or save it with `usage-categories set`.
+
+## Output
+
+Each group has: owner minutes, agent busy minutes, tokens (cost-weighted: cache reads count 0.1x), raw tokens, estimated cost in USD, ticket count and its top 5 tickets. `summary` is a short text suitable for speech or Slack. `notes` lists caveats (for example tickets rebuilt from history are marked inferred).
+
+## Reading the numbers to the owner
+
+- Lead with the summary line, then the two or three biggest groups.
+- Owner minutes are an estimate from message times (messages on one ticket within 10 minutes form one span).
+- Say "about" for cost; it is an API-price estimate, not a bill.

package/config/skills/team-leader/usage-report/execute.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Usage report: where the owner's time and the agents' tokens went.
+#
+# Usage:
+#   execute.sh [--since 7d] [--until 2026-10-11] [--by category|team|project|agent|ticket]
+#              [--categories "book,self-media" | "media:linkedin,substack;book:chapter"]
+#              [--limit 10] [--text]
+#   execute.sh '{"since":"7d","by":"category"}'
+#
+# --text prints only the short summary (good to read out or post to Slack).
+# Read-only: it changes nothing.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+SINCE=""
+UNTIL=""
+BY=""
+CATEGORIES=""
+LIMIT=""
+TEXT="false"
+INPUT_JSON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since)      SINCE="$2";      shift 2 ;;
+    --until)      UNTIL="$2";      shift 2 ;;
+    --by)         BY="$2";         shift 2 ;;
+    --categories) CATEGORIES="$2"; shift 2 ;;
+    --limit)      LIMIT="$2";      shift 2 ;;
+    --text)       TEXT="true";     shift ;;
+    --help|-h)
+      echo "Usage: execute.sh [--since 7d] [--until DATE] [--by category|team|project|agent|ticket] [--categories NAMES_OR_DEFS] [--limit N] [--text]"
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+if [[ -n "$INPUT_JSON" ]]; then
+  [[ -z "$SINCE" ]]      && SINCE=$(echo "$INPUT_JSON" | jq -r '.since // empty' 2>/dev/null || true)
+  [[ -z "$UNTIL" ]]      && UNTIL=$(echo "$INPUT_JSON" | jq -r '.until // empty' 2>/dev/null || true)
+  [[ -z "$BY" ]]         && BY=$(echo "$INPUT_JSON" | jq -r '.by // empty' 2>/dev/null || true)
+  [[ -z "$CATEGORIES" ]] && CATEGORIES=$(echo "$INPUT_JSON" | jq -r '.categories // empty | if type == "array" then tojson else . end' 2>/dev/null || true)
+  [[ -z "$LIMIT" ]]      && LIMIT=$(echo "$INPUT_JSON" | jq -r '.limit // empty' 2>/dev/null || true)
+  if [[ "$TEXT" != "true" ]]; then TEXT=$(echo "$INPUT_JSON" | jq -r '.text // false' 2>/dev/null || echo false); fi
+fi
+
+QUERY=$(jq -rn \
+  --arg since "${SINCE:-7d}" --arg until "$UNTIL" --arg by "${BY:-category}" \
+  --arg categories "$CATEGORIES" --arg limit "$LIMIT" \
+  '[ "since=" + ($since|@uri), "by=" + ($by|@uri),
+     (if $until != "" then "until=" + ($until|@uri) else empty end),
+     (if $categories != "" then "categories=" + ($categories|@uri) else empty end),
+     (if $limit != "" then "limit=" + ($limit|@uri) else empty end) ] | join("&")')
+
+if ! RESP=$(api_call_full GET "/usage-ledger/report?${QUERY}"); then
+  error_exit "Could not fetch the usage report"
+fi
+
+if [[ "$TEXT" == "true" ]]; then
+  printf '%s' "$RESP" | jq -r '.data.summary // .error // "No report"'
+  exit 0
+fi
+
+# Compact: the full body has every token kind for every group.
+printf '%s' "$RESP" | jq '
+  if .success then
+    { summary: .data.summary,
+      window: .data.window,
+      by: .data.by,
+      categories: .data.categories,
+      totals: { ownerMinutes: .data.totals.ownerMinutes, agentBusyMinutes: .data.totals.agentBusyMinutes,
+                tokens: .data.totals.tokens.budget, rawTokens: .data.totals.tokens.total,
+                costUsd: .data.totals.costUsd, tickets: .data.totals.ticketCount },
+      groups: [ .data.groups[] | { key, ownerMinutes, agentBusyMinutes, tokens: .tokens.budget, rawTokens: .tokens.total,
+                costUsd, tickets: .ticketCount,
+                topTickets: [ .topTickets[] | { ticketId, title, ownerMinutes, agentBusyMinutes, tokens, costUsd } ] } ],
+      notes: .data.notes }
+  else . end'

package/config/skills/team-leader/usage-report/execute.test.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Tests for usage-report — run with: bash execute.test.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0; FAIL=0
+check() { local name="$1"; local got="$2"; local want="$3"; if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/team-leader/usage-report" "$TMP/skills/team-leader/_common"
+cp "$HERE/execute.sh" "$TMP/skills/team-leader/usage-report/execute.sh"
+REAL_LIB="$(cd "$HERE/../../_common" && pwd)/lib.sh"
+REPORT='{"success":true,"data":{"summary":"Usage, last 7 days: 3 tickets","window":{},"by":"category","categories":null,
+ "totals":{"ownerMinutes":6,"agentBusyMinutes":30,"tokens":{"budget":5000,"total":9000},"costUsd":1.5,"ticketCount":3},
+ "groups":[{"key":"book","ownerMinutes":6,"agentBusyMinutes":30,"tokens":{"budget":5000,"total":9000},"costUsd":1.5,"ticketCount":3,
+   "topTickets":[{"ticketId":"TKT-1","title":"Chapter","ownerMinutes":6,"agentBusyMinutes":30,"tokens":5000,"costUsd":1.5,"inferred":false}]}],"notes":[]}}'
+cat > "$TMP/skills/team-leader/_common/lib.sh" <<'STUB'
+source "$REAL_LIB"
+api_call() { echo "$1 $2" > "$CALL_LOG"; printf '%s' "$REPORT"; }
+STUB
+export REAL_LIB REPORT CALL_LOG="$TMP/call"
+
+run() { CODE=0; OUT=$(env -u CREWLY_SESSION_NAME bash "$TMP/skills/team-leader/usage-report/execute.sh" "$@" 2>"$TMP/err") || CODE=$?; }
+
+run
+check "default window and grouping" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=7d&by=category"
+check "compact groups" "$(printf '%s' "$OUT" | jq -c '.groups[0] | [.key, .tokens, .topTickets[0].ticketId]')" '["book",5000,"TKT-1"]'
+check "totals flattened" "$(printf '%s' "$OUT" | jq -c '.totals.tickets')" "3"
+
+run --since 30d --by team --limit 5 --categories "media:linkedin,substack;book"
+check "flags in the query, encoded" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=30d&by=team&categories=media%3Alinkedin%2Csubstack%3Bbook&limit=5"
+
+run '{"since":"2w","by":"project"}'
+check "JSON input" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=2w&by=project"
+
+run --text
+check "--text prints the summary only" "$OUT" "Usage, last 7 days: 3 tickets"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/dist/backend/backend/src/constants.d.ts

@@ -328,6 +328,17 @@ export declare const TURN_STATE_CONSTANTS: {
     readonly HOOK_SILENCE_MS: number;
     /** An open tool call or a running subagent / background task expires after this (ms) */
     readonly OPEN_WORK_MAX_MS: number;
+    /**
+     * A background subagent / fork whose transcript has not grown for this long,
+     * while the agent's own turn is over, is stalled: it stops counting as busy
+     * and the agent is told (ms). Pia's fork died after 2 minutes and the agent
+     * stayed "busy" for the full OPEN_WORK_MAX_MS (2026-10-12).
+     */
+    readonly BACKGROUND_STALL_MS: number;
+    /** Progress probes (a directory read plus a few stats) are reused for this long (ms) */
+    readonly BACKGROUND_PROBE_CACHE_MS: 30000;
+    /** How often the stalled-background watchdog looks (ms) */
+    readonly BACKGROUND_WATCHDOG_INTERVAL_MS: 60000;
     /** After a delivery, wait this long for the runtime to report the turn started (ms) */
     readonly DELIVERY_START_MS: number;
     /** A transcript that says "mid-turn" counts only if it changed within this window (ms) */