crewly 1.20.450 → 1.20.452

package/config/skills/agent/checkup-report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Check-up Report
-description: The intake and report steps of the small-business check-up as one Crewly App. Copies the bundled App page (five intake questions, the report with the top 3 breaks and what an agent could do, a 7-day daily summary) into the project for publish-app, turns checkup-analyse's breaks.json into the App's report document (with the number the owner asked to see first), and writes daily-summary documents for app-data.
-version: 1.0.0
+description: The intake and report steps of the small-business check-up as one Crewly App. Copies the bundled App page (five intake questions, the report with the top 3 breaks and what an agent could do, a 7-day daily summary) into the project for publish-app, turns checkup-analyse's breaks.json into the App's report document (with the number the owner asked to see first), writes daily-summary documents for app-data, and keeps a per-step time log (--log-step) the report shows.
+version: 1.1.0
 category: productivity
 skillType: claude-skill
 assignableRoles:
@@ -12,6 +12,7 @@ triggers:
   - publish the check-up
   - intake questions
   - daily check-up summary
+  - log a check-up step
 tags:
   - check-up
   - small-business
@@ -84,10 +85,26 @@ bash app-data --app <appId> --set daily 2026-10-27 --data-file ./checkup-data/da
 Say what changed and what was done, in the owner's language, under 300
 characters. Seven entries, then stop unless the owner asks for more.
 
-## Time log
+The free **Small Business Check-up** team template (`small-business-checkup`)
+runs these steps with a Checkup Lead, a Data Analyst and an optional Reviewer
+who checks `report-doc.json` before it is published; remove the Reviewer from
+the team to skip that step.
 
-Record the start and end of each step (intake, connect, analyse, report) in
-your work notes; the check-up is measured by how long it really takes.
+## Time log — how long the check-up really took
+
+Mark the start and end of every step; the report shows the minutes per step
+and the total, and the owner sees them under "How long it took".
+
+```bash
+bash execute.sh --log-step intake --start --out ./checkup-data     # steps: intake, connect, analyse, report, daily
+bash execute.sh --log-step intake --end --out ./checkup-data
+```
+
+`--out` is the same directory as the report; the log is `timelog.json` there
+and `--breaks` folds it in as `timing` (closed steps with minutes, the total,
+and any step still open). A second `--start` on an open step restarts it;
+`--end` with no open entry fails (exit 2) so a forgotten start is noticed.
+`--at <iso>` back-fills a time you know. One `daily` entry per day is fine.
 
 ## Report back
 

package/config/skills/agent/checkup-report/app/index.html

@@ -68,6 +68,7 @@
     <div id="notes-wrap" class="hidden"><h2>Could not check</h2><ul class="plain" id="notes" data-crewly-id="notes"></ul></div>
     <h2>Files</h2>
     <ul class="plain" id="files" data-crewly-id="files"></ul>
+    <div id="timing-wrap" class="hidden"><h2>How long it took</h2><ul class="plain" id="timing" data-crewly-id="timing"></ul></div>
     <h2>Assumptions</h2>
     <ul class="plain" id="assumptions" data-crewly-id="assumptions"></ul>
     <button class="secondary" id="ask" data-crewly-id="ask">Ask about this report</button>
@@ -193,6 +194,15 @@
     (r.files || []).forEach(function (f) { files.appendChild(el('li', null, f.file + ' — ' + f.source + ' ' + f.kind + ', ' + f.rows + ' rows')); });
     var as = $('assumptions'); as.replaceChildren();
     Object.keys(r.assumptions || {}).forEach(function (k) { as.appendChild(el('li', null, k + ': ' + r.assumptions[k])); });
+    var timing = $('timing'); timing.replaceChildren();
+    var t = r.timing;
+    if (t && t.steps && t.steps.length) {
+      t.steps.forEach(function (s) {
+        timing.appendChild(el('li', null, s.step + ': ' + (s.endedAt ? s.minutes + ' min' : 'still running')));
+      });
+      timing.appendChild(el('li', 'note', 'Total ' + t.totalMinutes + ' min of agent time' + (t.open && t.open.length ? ' so far' : '')));
+    }
+    $('timing-wrap').classList.toggle('hidden', !(t && t.steps && t.steps.length));
   }
   $('ask').onclick = function () {
     crewly.notify('The owner opened the check-up report and tapped "Ask about this report". Reply in their DM with a one-line offer to walk through the top 3.').then(function () {

package/config/skills/agent/checkup-report/execute.sh

@@ -9,6 +9,8 @@
 #   bash execute.sh --app-dir ./checkup-app                                        # copy the App page
 #   bash execute.sh --breaks …/analysis/breaks.json --business "Oak Pottery" --intake ./intake.json --out ./checkup-data
 #   bash execute.sh --daily "Replied to 3 open inquiries; 1 booked." --out ./checkup-data
+#   bash execute.sh --log-step intake --start --out ./checkup-data     # per-step time log (timelog.json)
+#   bash execute.sh '{"logStep":"intake","mark":"end","out":"./checkup-data"}'
 #   bash execute.sh '{"breaks":"…/breaks.json","business":"Oak Pottery","out":"./checkup-data"}'
 #
 # Output: one JSON line with the files written and the exact next command
@@ -23,13 +25,15 @@ command -v node >/dev/null 2>&1 || { printf '{"success":false,"error":"node is r
 ARGS=()
 if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
   command -v jq >/dev/null 2>&1 || { printf '{"success":false,"error":"jq is required to read JSON input"}\n'; exit 1; }
-  for key in appDir breaks business intake examples out daily date; do
+  for key in appDir breaks business intake examples out daily date logStep at; do
     v=$(printf '%s' "$1" | jq -r --arg k "$key" '.[$k] // empty')
     if [ -n "$v" ]; then
-      case "$key" in appDir) flag=--app-dir ;; *) flag="--$key" ;; esac
+      case "$key" in appDir) flag=--app-dir ;; logStep) flag=--log-step ;; *) flag="--$key" ;; esac
       ARGS+=("$flag" "$v")
     fi
   done
+  mark=$(printf '%s' "$1" | jq -r '.mark // empty')
+  case "$mark" in start|end) ARGS+=("--$mark") ;; esac
   shift
 fi
 ARGS+=("$@")

package/config/skills/agent/checkup-report/execute.test.sh

@@ -133,5 +133,42 @@ bash "$EXEC" --daily "   " --out "$T/x" >/dev/null 2>&1; check "empty daily exit
 bash "$EXEC" --breaks "$T/an/breaks.json" --examples lots --out "$T/x" >/dev/null 2>&1; check "bad examples exits 1" "$?" "1"
 bash "$EXEC" --bogus >/dev/null 2>&1; check "unknown flag exits 1" "$?" "1"
 
+# 9. --log-step: per-step time log
+check "page has a timing block" "$(grep -c 'data-crewly-id="timing"' "$PAGE")" "1"
+bash "$EXEC" --log-step intake --start --at 2026-10-26T09:00:00Z --out "$T/tl" >/dev/null; check "log start exits 0" "$?" "0"
+check "timelog written" "$([ -f "$T/tl/timelog.json" ] && echo yes || echo no)" "yes"
+check "open entry" "$(jq -c '.steps[0] | {step, endedAt, minutes}' "$T/tl/timelog.json")" '{"step":"intake","endedAt":null,"minutes":null}'
+LOUT="$(bash "$EXEC" --log-step intake --end --at 2026-10-26T09:12:30Z --out "$T/tl")"
+check "log end exits 0" "$?" "0"
+check "minutes = 12.5" "$(jq -r '.steps[0].minutes' "$T/tl/timelog.json")" "12.5"
+check "end output carries the entry" "$(printf '%s' "$LOUT" | jq -r '.entry.endedAt')" "2026-10-26T09:12:30.000Z"
+check "end output totals" "$(printf '%s' "$LOUT" | jq -c '.timing | {totalMinutes, open}')" '{"totalMinutes":12.5,"open":[]}'
+bash "$EXEC" --log-step connect --start --at 2026-10-26T09:13:00Z --out "$T/tl" >/dev/null
+bash "$EXEC" --log-step connect --start --at 2026-10-26T09:14:00Z --out "$T/tl" >/dev/null
+check "restart replaces the open start" "$(jq -r '[.steps[] | select(.step=="connect")] | length, .[0].startedAt' "$T/tl/timelog.json" | tr '\n' ' ')" "1 2026-10-26T09:14:00.000Z "
+bash "$EXEC" --log-step connect --end --at 2026-10-26T10:14:00Z --out "$T/tl" >/dev/null
+bash "$EXEC" --log-step analyse --start --at 2026-10-26T10:15:00Z --out "$T/tl" >/dev/null
+bash "$EXEC" --log-step analyse --end --at 2026-10-26T10:21:00Z --out "$T/tl" >/dev/null
+bash "$EXEC" --log-step report --start --at 2026-10-26T10:22:00Z --out "$T/tl" >/dev/null
+JLOG="$(bash "$EXEC" "{\"logStep\":\"report\",\"mark\":\"end\",\"at\":\"2026-10-26T10:30:00Z\",\"out\":\"$T/tl\"}")"
+check "json input logs a step" "$(printf '%s' "$JLOG" | jq -r '.entry.minutes')" "8"
+check "four closed steps" "$(jq -r '[.steps[] | select(.endedAt)] | length' "$T/tl/timelog.json")" "4"
+check "same step twice keeps both" "$(bash "$EXEC" --log-step daily --start --at 2026-10-27T09:00:00Z --out "$T/tl" >/dev/null; bash "$EXEC" --log-step daily --end --at 2026-10-27T09:03:00Z --out "$T/tl" >/dev/null; bash "$EXEC" --log-step daily --start --at 2026-10-28T09:00:00Z --out "$T/tl" >/dev/null; jq -r '[.steps[] | select(.step=="daily")] | length' "$T/tl/timelog.json")" "2"
+bash "$EXEC" --breaks "$T/an/breaks.json" --business "Oak Pottery" --out "$T/tl" >/dev/null
+check "report folds the time log in" "$(jq -c '.timing | {totalMinutes, open, n: (.steps|length)}' "$T/tl/report-doc.json")" '{"totalMinutes":89.5,"open":["daily"],"n":6}'
+check "timing steps carry minutes" "$(jq -r '.timing.steps[1] | "\(.step) \(.minutes)"' "$T/tl/report-doc.json")" "connect 60"
+check "no time log → no timing" "$(jq -r 'has("timing")' "$D")" "false"
+bash "$EXEC" --log-step cook --start --out "$T/tl" >/dev/null 2>&1; check "unknown step exits 1" "$?" "1"
+bash "$EXEC" --log-step analyse --end --out "$T/tl" >/dev/null 2>&1; check "end without start exits 2" "$?" "2"
+bash "$EXEC" --log-step intake --out "$T/tl" >/dev/null 2>&1; check "log-step without --start/--end exits 1" "$?" "1"
+bash "$EXEC" --start --out "$T/tl" >/dev/null 2>&1; check "--start without --log-step exits 1" "$?" "1"
+bash "$EXEC" --log-step intake --start >/dev/null 2>&1; check "log-step without --out exits 1" "$?" "1"
+bash "$EXEC" --log-step intake --start --at yesterday --out "$T/tl" >/dev/null 2>&1; check "bad --at exits 1" "$?" "1"
+bash "$EXEC" --log-step intake --start --at 2026-10-26T09:00:00Z --out "$T/tl2" >/dev/null
+bash "$EXEC" --log-step intake --end --at 2026-10-26T08:00:00Z --out "$T/tl2" >/dev/null 2>&1; check "end before start exits 1" "$?" "1"
+printf '{"nope":1}' > "$T/tl3.json"; mkdir -p "$T/tl3"; cp "$T/tl3.json" "$T/tl3/timelog.json"
+bash "$EXEC" --log-step intake --start --out "$T/tl3" >/dev/null 2>&1; check "broken timelog exits 2" "$?" "2"
+bash "$EXEC" --breaks "$T/an/breaks.json" --out "$T/tl3" >/dev/null 2>&1; check "report with broken timelog exits 2" "$?" "2"
+
 echo "checkup-report: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]

package/config/skills/agent/checkup-report/report.mjs

@@ -10,6 +10,8 @@
 //   node report.mjs --app-dir ./checkup-app                       # copy the App page to publish
 //   node report.mjs --breaks …/breaks.json --business "Oak Pottery" [--intake answers.json] --out ./checkup-data
 //   node report.mjs --daily "Replied to 3 open inquiries; 1 booked." [--date 2026-10-27] --out ./checkup-data
+//   node report.mjs --log-step intake --start --out ./checkup-data          # per-step time log → timelog.json
+//   node report.mjs --log-step intake --end --out ./checkup-data
 // =============================================================================
 import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync, readdirSync, statSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
@@ -20,6 +22,9 @@ const APP_SRC = join(HERE, 'app');
 const DEFAULT_EXAMPLES = 3;
 /** Crewly App documents are capped at 256 KB; stay well under it. */
 const MAX_DOC_BYTES = 200 * 1024;
+/** The check-up's steps, in order; the time log accepts no other name. */
+export const STEPS = ['intake', 'connect', 'analyse', 'report', 'daily'];
+const TIMELOG_FILE = 'timelog.json';
 
 /** The "which number first" choices offered by the intake form, with how each is read off the breaks. */
 const FIRST_NUMBER_RULES = [
@@ -60,7 +65,8 @@ function examplesFor(b, limit) {
 /**
  * Build the report document the App renders from checkup-analyse output.
  * Items are summarised into a few examples per break so the document stays small
- * and no full list of people lands in the App's data.
+ * and no full list of people lands in the App's data. `opts.timelog` (from
+ * `readTimelog`) adds a `timing` block with minutes per step.
  */
 export function buildReportDoc(breaks, opts = {}) {
   const by = Object.fromEntries(breaks.breaks.map((b) => [b.type, b]));
@@ -91,9 +97,58 @@ export function buildReportDoc(breaks, opts = {}) {
     if (rule) doc.firstNumber = { asked: want, key: rule.key, label: rule.label, value: rule.value(by) };
     else doc.notes = [...doc.notes, `The owner asked to see "${want}" first; no break maps to it, so the top 3 lead.`];
   }
+  // How long the check-up took, when the agent logged its steps (`--log-step`).
+  if (opts.timelog && opts.timelog.steps.length) doc.timing = summariseTimelog(opts.timelog);
   return doc;
 }
 
+/** Read `<dir>/timelog.json`; an absent file is an empty log, a broken one throws. */
+export function readTimelog(dir) {
+  const file = join(dir, TIMELOG_FILE);
+  if (!existsSync(file)) return { steps: [] };
+  const raw = JSON.parse(readFileSync(file, 'utf8'));
+  if (!raw || !Array.isArray(raw.steps)) throw new Error(`${file}: not a time log ({ steps: [] })`);
+  return raw;
+}
+
+/**
+ * Record the start or end of a check-up step in the time log.
+ *
+ * `--start` opens an entry (a second start on a still-open step restarts it);
+ * `--end` closes the latest open entry of that step and fills in `minutes`.
+ * `at` overrides the clock (ISO timestamp) for back-filling and tests.
+ *
+ * @returns the updated log and the entry touched
+ * @throws when the step is unknown, `--end` finds no open entry, or `at` is not a date
+ */
+export function logStep(log, step, mark, at) {
+  if (!STEPS.includes(step)) throw new Error(`unknown step "${step}"; use one of ${STEPS.join(', ')}`);
+  const when = at ? new Date(at) : new Date();
+  if (Number.isNaN(when.getTime())) throw new Error(`--at must be an ISO timestamp, got "${at}"`);
+  const iso = when.toISOString();
+  const open = [...log.steps].reverse().find((s) => s.step === step && !s.endedAt);
+  let entry;
+  if (mark === 'start') {
+    if (open) { open.startedAt = iso; entry = open; }
+    else { entry = { step, startedAt: iso, endedAt: null, minutes: null }; log.steps.push(entry); }
+  } else {
+    if (!open) throw new Error(`no open "${step}" entry to end; run --log-step ${step} --start first`);
+    if (when.getTime() < new Date(open.startedAt).getTime()) throw new Error(`end (${iso}) is before start (${open.startedAt})`);
+    open.endedAt = iso;
+    open.minutes = Math.round((when.getTime() - new Date(open.startedAt).getTime()) / 6000) / 10;
+    entry = open;
+  }
+  return { log, entry };
+}
+
+/** Fold a time log into the shape the report document carries: closed steps with minutes, plus the total. */
+export function summariseTimelog(log) {
+  const steps = log.steps.map((s) => ({ step: s.step, startedAt: s.startedAt, endedAt: s.endedAt, minutes: s.minutes }));
+  const closed = steps.filter((s) => s.endedAt);
+  const totalMinutes = Math.round(closed.reduce((a, s) => a + (s.minutes || 0), 0) * 10) / 10;
+  return { steps, totalMinutes, open: steps.filter((s) => !s.endedAt).map((s) => s.step) };
+}
+
 /** Read intake answers from a plain document or from app-data's `{ success, data }` output. */
 function readIntake(path) {
   const raw = JSON.parse(readFileSync(path, 'utf8'));
@@ -119,7 +174,7 @@ function out(obj, code) {
 }
 
 function usage() {
-  out({ success: false, error: 'usage: report.mjs --app-dir <dir> | --breaks <breaks.json> [--business <name>] [--intake <answers.json>] [--examples N] --out <dir> | --daily "<summary>" [--date YYYY-MM-DD] --out <dir>' }, 1);
+  out({ success: false, error: 'usage: report.mjs --app-dir <dir> | --breaks <breaks.json> [--business <name>] [--intake <answers.json>] [--examples N] --out <dir> | --daily "<summary>" [--date YYYY-MM-DD] --out <dir> | --log-step <intake|connect|analyse|report|daily> --start|--end [--at <iso>] --out <dir>' }, 1);
 }
 
 function main(argv) {
@@ -135,14 +190,39 @@ function main(argv) {
     else if (a === '--out') o.out = next();
     else if (a === '--daily') o.daily = next();
     else if (a === '--date') o.date = next();
+    else if (a === '--log-step') o.logStep = next();
+    else if (a === '--start') o.mark = 'start';
+    else if (a === '--end') o.mark = 'end';
+    else if (a === '--at') o.at = next();
     else usage();
   }
-  if (!o.appDir && !o.breaks && !o.daily) usage();
-  if ((o.breaks || o.daily) && !o.out) usage();
+  if (!o.appDir && !o.breaks && !o.daily && !o.logStep) usage();
+  if ((o.breaks || o.daily || o.logStep) && !o.out) usage();
+  if (o.logStep && !o.mark) usage();
+  if (o.mark && !o.logStep) usage();
   if (o.date && !/^\d{4}-\d{2}-\d{2}$/.test(o.date)) out({ success: false, error: `--date must be YYYY-MM-DD, got "${o.date}"` }, 1);
   if (!Number.isFinite(o.examples) || o.examples < 0) out({ success: false, error: '--examples needs a number >= 0' }, 1);
 
   const result = { success: true };
+  if (o.logStep) {
+    let log;
+    try {
+      log = readTimelog(o.out);
+    } catch (e) {
+      out({ success: false, error: e.message }, 2);
+    }
+    let entry;
+    try {
+      ({ entry } = logStep(log, o.logStep, o.mark, o.at));
+    } catch (e) {
+      out({ success: false, error: e.message }, o.mark === 'end' && /no open/.test(e.message) ? 2 : 1);
+    }
+    mkdirSync(o.out, { recursive: true });
+    writeFileSync(join(o.out, TIMELOG_FILE), JSON.stringify(log, null, 2));
+    result.timelog = resolve(join(o.out, TIMELOG_FILE));
+    result.entry = entry;
+    result.timing = summariseTimelog(log);
+  }
   if (o.appDir) {
     result.appDir = resolve(o.appDir);
     result.copied = copyApp(o.appDir);
@@ -166,7 +246,13 @@ function main(argv) {
         out({ success: false, error: `${o.intake}: ${e.message}` }, 2);
       }
     }
-    const doc = buildReportDoc(breaks, { business: o.business, intake, examples: o.examples });
+    let timelog = null;
+    try {
+      timelog = readTimelog(o.out);
+    } catch (e) {
+      out({ success: false, error: e.message }, 2);
+    }
+    const doc = buildReportDoc(breaks, { business: o.business, intake, examples: o.examples, timelog });
     const json = JSON.stringify(doc, null, 2);
     if (Buffer.byteLength(json) > MAX_DOC_BYTES) out({ success: false, error: `report document is ${Buffer.byteLength(json)} bytes; lower --examples` }, 2);
     mkdirSync(o.out, { recursive: true });
@@ -175,6 +261,7 @@ function main(argv) {
     result.top3 = doc.top3;
     result.totals = doc.totals;
     result.firstNumber = doc.firstNumber || null;
+    result.timing = doc.timing || null;
     result.next = `app-data --app <appId> --set report current --data-file ${join(o.out, 'report-doc.json')}`;
   }
   if (o.daily) {

package/config/skills/agent/spawn-subagent/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: Spawn Sub-agent
+description: Run one short-lived helper for a bounded task (a large read, a parallel search, a scoped fix) and get its report back. Works on every runtime - Claude Code, Codex, Gemini, crewly-agent - because the helper runs in Crewly's own in-process runtime, not yours. The helper cannot message, delegate or schedule; it reads and edits under one directory and reports once. Treat the result as evidence, not as done work.
+natural_language_description: Hand a bounded task to a short-lived helper and read its report.
+version: 1.0.0
+category: task-management
+skillType: claude-skill
+assignableRoles:
+  - developer
+  - qa
+  - tpm
+  - designer
+  - frontend-developer
+  - backend-developer
+  - fullstack-dev
+  - qa-engineer
+  - product-manager
+  - architect
+  - generalist
+  - researcher
+  - team-leader
+triggers:
+  - spawn sub-agent
+  - spawn subagent
+  - run a helper
+  - delegate to helper
+  - parallel research
+tags:
+  - subagent
+  - delegation
+  - in-process
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 660000
+---
+
+# Spawn Sub-agent
+
+Runs one short-lived helper for a single bounded task and returns its report.
+The helper is a Crewly in-process worker (crewly#1317): it gets read tools
+(`read_file`, `glob`, `grep`, `git_status`, `git_diff`, `web_search`),
+write tools under its directory unless `--read-only`, and `report_to_parent`.
+It cannot message anyone, delegate, schedule, touch tickets, or spawn helpers
+of its own. The call blocks until the helper reports or its budget runs out.
+
+Use it for work that is bounded and self-contained and that nobody needs to
+own, review or hear about: reading a large tree for one question, three
+searches in parallel, a scoped fix with a clear acceptance line. Do not use
+it for work a teammate should own (that is a ticket) or for anything that
+needs to talk to the owner.
+
+## Parameters
+
+| Flag | JSON Field | Required | Description |
+|------|-----------|----------|-------------|
+| `--task` / `-t` | `task` | Yes | The task, in full, with the acceptance line. Max 12,000 chars: summarise context, do not paste it |
+| `--cwd` / `-C` | `cwd` | No | Absolute directory the helper works in and may write under. Default `$CREWLY_PROJECT_PATH`, else `$PWD` |
+| `--read-only` | `readOnly` | No | No shell and no file writes |
+| `--max-steps` | `maxSteps` | No | Model steps granted (default 30, cap 60) |
+| `--model` / `-m` | `model` | No | `provider/modelId`; default is the model Crewly's fallback settings name for in-process agents |
+| `--task-file` | - | No | Read the task from a file instead of the flag |
+
+## Examples
+
+```bash
+# A read-only question about the codebase
+bash config/skills/agent/spawn-subagent/execute.sh --read-only \
+  --task "Where is the retry delay for Slack posts set? Report file and line, and the default value."
+
+# A scoped fix in a worktree
+bash config/skills/agent/spawn-subagent/execute.sh --cwd /abs/path/to/worktree \
+  --task "Rename helper foo() to bar() in src/x.ts and its test; run 'npx tsc --noEmit -p backend'. Report what changed and the tsc result."
+
+# Three helpers in parallel from a shell
+for q in "auth" "billing" "slack"; do
+  bash config/skills/agent/spawn-subagent/execute.sh --read-only --task "List every file under src that handles $q, one line each" > "/tmp/sub-$q.json" &
+done; wait
+```
+
+## Output
+
+JSON. `success` is true only when the helper did work and stopped on its
+own. `stoppedReason` is one of `done`, `did_nothing`, `steps_exhausted`,
+`incomplete`, `timeout`, `error`. `summary` is its report (capped at 6,000
+chars), `toolCalls` / `toolNames` what it did, `filesChanged` what it
+wrote, `usage` its tokens (booked under `sessionName`, `<you>/sub-<n>`).
+
+```json
+{"success":true,"stoppedReason":"done","summary":"...","toolCalls":4,"toolNames":["grep","read_file"],"filesChanged":[],"usage":{"input":1200,"output":300,"cachedInput":0},"steps":5,"sessionName":"crewly-dev-1/sub-1","durationMs":18000,"model":"deepseek/deepseek-chat"}
+```
+
+A refusal is an error with a `code`: `nested` (a helper cannot spawn),
+`too_many` (3 already running for you), `task_too_long`, `cwd_invalid`,
+`model_invalid`, `parent_required` (no agent session in this shell).
+
+## Reading the result
+
+`toolCalls: 0` means the helper did nothing, whatever `summary` says. Check
+`filesChanged` against what you asked for. The report is a claim from a
+model with less context than you: verify anything you will act on, and
+never relay it to the owner as your own finding without reading the files it
+names.

package/config/skills/agent/spawn-subagent/execute.sh

@@ -0,0 +1,114 @@
+#!/bin/bash
+# Run one short-lived in-process helper for a bounded task (crewly#1317).
+# Thin wrapper over POST /api/subagents; the backend starts the worker,
+# waits for its one report and shuts it down. Blocks until then.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+# Wall-clock budget the backend gives a helper (600 s) plus a margin: the
+# reply arrives only when the helper is done.
+SUBAGENT_CURL_MAX_TIME="${CREWLY_SUBAGENT_MAX_TIME:-660}"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh --task "..." [--cwd /abs/dir] [--read-only] [--max-steps N] [--model provider/id]
+  bash execute.sh --task-file /path/to/task.md [...]
+  bash execute.sh '{"task":"...","cwd":"/abs/dir","readOnly":true}'
+
+Options:
+  --task      | -t   The task, in full, with its acceptance line (max 12,000 chars)
+  --task-file        Read the task from a file
+  --cwd       | -C   Absolute directory the helper works in (default $CREWLY_PROJECT_PATH, else $PWD)
+  --read-only        No shell and no file writes
+  --max-steps        Model steps granted (default 30, cap 60)
+  --model     | -m   provider/modelId (default: the fallback settings' in-process model)
+  --json      | -j   Raw JSON payload (same as the legacy positional form)
+  --help      | -h   Show this help
+EOF_USAGE
+}
+
+INPUT_JSON=""
+TASK=""
+TASK_FILE=""
+CWD_ARG=""
+READ_ONLY="false"
+MAX_STEPS=""
+MODEL=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --task|-t) TASK="${2:-}"; shift 2 ;;
+    --task-file) TASK_FILE="${2:-}"; shift 2 ;;
+    --cwd|-C) CWD_ARG="${2:-}"; shift 2 ;;
+    --read-only) READ_ONLY="true"; shift ;;
+    --max-steps) MAX_STEPS="${2:-}"; shift 2 ;;
+    --model|-m) MODEL="${2:-}"; shift 2 ;;
+    --json|-j) INPUT_JSON="${2:-}"; shift 2 ;;
+    --help|-h) print_usage; exit 0 ;;
+    --) shift; break ;;
+    *)
+      if [[ -z "$INPUT_JSON" && ${1:0:1} == '{' ]]; then
+        INPUT_JSON="$1"; shift
+      else
+        unknown_arg_exit "$1"
+      fi
+      ;;
+  esac
+done
+
+if [ -z "$INPUT_JSON" ] && [ -z "$TASK" ] && [ -z "$TASK_FILE" ] && [ ! -t 0 ]; then
+  STDIN_DATA="$(cat)"
+  if [[ ${STDIN_DATA:0:1} == '{' ]]; then
+    INPUT_JSON="$STDIN_DATA"
+  fi
+fi
+
+if [ -n "$INPUT_JSON" ]; then
+  INPUT=$(read_json_input "$INPUT_JSON")
+  [ -z "$TASK" ] && TASK=$(printf '%s' "$INPUT" | jq -r '.task // empty')
+  [ -z "$CWD_ARG" ] && CWD_ARG=$(printf '%s' "$INPUT" | jq -r '.cwd // empty')
+  [ "$READ_ONLY" = "false" ] && READ_ONLY=$(printf '%s' "$INPUT" | jq -r 'if .readOnly == true then "true" else "false" end')
+  [ -z "$MAX_STEPS" ] && MAX_STEPS=$(printf '%s' "$INPUT" | jq -r '.maxSteps // empty')
+  [ -z "$MODEL" ] && MODEL=$(printf '%s' "$INPUT" | jq -r '.model // empty')
+fi
+
+if [ -n "$TASK_FILE" ]; then
+  [ -f "$TASK_FILE" ] || error_exit "task file not found: $TASK_FILE"
+  TASK="$(cat "$TASK_FILE")"
+fi
+
+require_param "task (--task)" "$TASK"
+
+if [ -z "$CWD_ARG" ]; then
+  CWD_ARG="${CREWLY_PROJECT_PATH:-$PWD}"
+fi
+case "$CWD_ARG" in
+  /*) ;;
+  *) error_exit "cwd must be an absolute path, got: $CWD_ARG" ;;
+esac
+[ -d "$CWD_ARG" ] || error_exit "cwd is not a directory: $CWD_ARG"
+
+if [ -n "$MAX_STEPS" ] && ! [[ "$MAX_STEPS" =~ ^[0-9]+$ ]]; then
+  error_exit "--max-steps must be a whole number, got: $MAX_STEPS"
+fi
+
+BODY=$(jq -nc \
+  --arg task "$TASK" \
+  --arg cwd "$CWD_ARG" \
+  --argjson readOnly "$READ_ONLY" \
+  --arg maxSteps "$MAX_STEPS" \
+  --arg model "$MODEL" \
+  '{task: $task, cwd: $cwd, readOnly: $readOnly}
+   + (if $maxSteps != "" then {maxSteps: ($maxSteps | tonumber)} else {} end)
+   + (if $model != "" then {model: $model} else {} end)')
+
+# The backend wraps the outcome in {success, data}; the agent wants the outcome.
+OUT=$(CREWLY_API_MAX_TIME="$SUBAGENT_CURL_MAX_TIME" api_call POST "/subagents" "$BODY")
+printf '%s' "$OUT" | jq -c '.data // .'

package/config/skills/agent/spawn-subagent/execute.test.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+# Tests for spawn-subagent — run with: bash execute.test.sh
+# Python HTTP stub as the backend; asserts the request the skill sends and
+# the JSON it prints. Separate HOME / CREWLY_HOME. Exit 0 on pass.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+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
+}
+
+PORT=18851
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+OUTCOME = {'success': True, 'stoppedReason': 'done', 'summary': 'retry delay at src/slack.ts:42 = 2000',
+           'toolCalls': 2, 'toolNames': ['grep', 'read_file'], 'filesChanged': [],
+           'usage': {'input': 100, 'output': 20, 'cachedInput': 0}, 'steps': 3,
+           'sessionName': 'dev-ella/sub-1', 'durationMs': 1500, 'model': 'deepseek/deepseek-chat'}
+class H(BaseHTTPRequestHandler):
+    def _send(self, code, obj):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(obj).encode())
+    def do_GET(self): self._send(200, {'success': True})
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); body = self.rfile.read(n).decode() if n else ''
+        data = json.loads(body) if body else None
+        with open(LOG, 'a') as f:
+            f.write(json.dumps({'method': 'POST', 'path': self.path, 'body': data,
+                                'session': self.headers.get('X-Agent-Session')}) + '\n')
+        if self.path != '/api/subagents':
+            return self._send(200, {'success': True})
+        task = (data or {}).get('task', '')
+        if task.startswith('NESTED'):
+            return self._send(400, {'success': False, 'code': 'nested', 'error': 'A sub-agent cannot spawn sub-agents.'})
+        if task.startswith('TIMEOUT'):
+            out = dict(OUTCOME); out.update({'success': False, 'stoppedReason': 'timeout', 'toolCalls': 0, 'error': 'sub-agent exceeded 600000 ms'})
+            return self._send(200, {'success': True, 'data': out})
+        self._send(200, {'success': True, 'data': OUTCOME})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+WORK="$(mktemp -d)"; mkdir -p "$WORK/home/.crewly" "$WORK/repo"
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -rf "$STUB_LOG" "$WORK"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+ENVS=(CREWLY_API_URL="http://127.0.0.1:${PORT}" CREWLY_SESSION_NAME=dev-ella HOME="$WORK/home" CREWLY_HOME="$WORK/home/.crewly" CREWLY_PROJECT_PATH="$WORK/repo")
+# stdin closed: the skill reads JSON from a pipe when no task is given, and a
+# test runner's stdin is a pipe that never ends.
+run() { : > "$STUB_LOG"; env "${ENVS[@]}" bash "$EXEC" "$@" 2>/dev/null </dev/null; }
+run_err() { : > "$STUB_LOG"; env "${ENVS[@]}" bash "$EXEC" "$@" 2>&1 >/dev/null </dev/null; }
+# The skill library's start-of-skill heartbeat is not part of what we test.
+reqs() { jq -c 'select(.path != "/api/heartbeat") | {path, session, body}' "$STUB_LOG" | paste -sd'|' -; }
+
+# 1. Minimal call: task only; cwd defaults to CREWLY_PROJECT_PATH; readOnly false; no optionals.
+OUT=$(run --task "Where is the retry delay set?")
+check "minimal: request" "$(reqs)" "{\"path\":\"/api/subagents\",\"session\":\"dev-ella\",\"body\":{\"task\":\"Where is the retry delay set?\",\"cwd\":\"$WORK/repo\",\"readOnly\":false}}"
+check "minimal: prints the outcome unwrapped" "$(printf '%s' "$OUT" | jq -c '{success, stoppedReason, toolCalls, sessionName}')" '{"success":true,"stoppedReason":"done","toolCalls":2,"sessionName":"dev-ella/sub-1"}'
+
+# 2. Every flag.
+OUT=$(run --task "Fix it" --cwd "$WORK/repo" --read-only --max-steps 12 --model deepseek/deepseek-chat)
+check "all flags" "$(jq -c 'select(.path == "/api/subagents") | .body' "$STUB_LOG")" "{\"task\":\"Fix it\",\"cwd\":\"$WORK/repo\",\"readOnly\":true,\"maxSteps\":12,\"model\":\"deepseek/deepseek-chat\"}"
+
+# 3. Legacy JSON form.
+OUT=$(run "{\"task\":\"From JSON\",\"cwd\":\"$WORK/repo\",\"readOnly\":true,\"maxSteps\":5}")
+check "json form" "$(jq -c 'select(.path == "/api/subagents") | .body' "$STUB_LOG")" "{\"task\":\"From JSON\",\"cwd\":\"$WORK/repo\",\"readOnly\":true,\"maxSteps\":5}"
+
+# 4. Task from a file keeps quotes and newlines.
+printf 'Line one with "quotes"\nLine two\n' > "$WORK/task.md"
+run --task-file "$WORK/task.md" >/dev/null
+check "task file" "$(jq -r 'select(.path == "/api/subagents") | .body.task' "$STUB_LOG")" "$(printf 'Line one with "quotes"\nLine two\n')"
+
+# 5. cwd falls back to PWD when CREWLY_PROJECT_PATH is unset.
+: > "$STUB_LOG"
+(cd "$WORK/repo" && env CREWLY_API_URL="http://127.0.0.1:${PORT}" CREWLY_SESSION_NAME=dev-ella HOME="$WORK/home" CREWLY_HOME="$WORK/home/.crewly" bash "$EXEC" --task "pwd default" >/dev/null 2>&1 </dev/null)
+check "cwd defaults to PWD" "$(jq -r 'select(.path == "/api/subagents") | .body.cwd' "$STUB_LOG")" "$WORK/repo"
+
+# 6. Refusals before any request.
+OUT=$(run_err --cwd "$WORK/repo" || true)
+check "task required" "$(printf '%s' "$OUT" | grep -c 'Missing required parameter: task')" "1"
+check "task required: nothing sent" "$(reqs)" ""
+OUT=$(run_err --task x --cwd relative/dir || true)
+check "cwd must be absolute" "$(printf '%s' "$OUT" | grep -c 'must be an absolute path')" "1"
+OUT=$(run_err --task x --cwd "$WORK/missing" || true)
+check "cwd must exist" "$(printf '%s' "$OUT" | grep -c 'not a directory')" "1"
+OUT=$(run_err --task x --max-steps many || true)
+check "max-steps numeric" "$(printf '%s' "$OUT" | grep -c 'whole number')" "1"
+OUT=$(run_err --task x --bogus || true)
+check "unknown flag" "$(printf '%s' "$OUT" | grep -c 'Unknown argument: --bogus')" "1"
+
+# 7. A backend refusal is an error with its code; exit non-zero.
+OUT=$(run_err --task "NESTED please" || true)
+check "backend refusal surfaces the code" "$(printf '%s' "$OUT" | jq -r 'select(.error == true) | .details.code' 2>/dev/null | head -1)" "nested"
+set +e; run --task "NESTED please" >/dev/null 2>&1; RC=$?; set -e
+check "backend refusal exits 1" "$RC" "1"
+
+# 8. A child that timed out is still a 200 outcome with success:false.
+OUT=$(run --task "TIMEOUT me")
+check "timeout outcome passes through" "$(printf '%s' "$OUT" | jq -c '{success, stoppedReason, error}')" '{"success":false,"stoppedReason":"timeout","error":"sub-agent exceeded 600000 ms"}'
+
+# 9. --help prints usage and sends nothing.
+OUT=$(run --help)
+check "help" "$(printf '%s' "$OUT" | grep -c -- '--read-only')" "2"
+check "help sends nothing" "$(reqs)" ""
+
+echo "spawn-subagent: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]