crewly 1.20.296 → 1.20.298

package/config/roles/developer/prompt.md

@@ -63,7 +63,7 @@ git worktree add /tmp/crewly-worktrees/{{SESSION_NAME}}-<task-slug> -b <feat-bra
 cd /tmp/crewly-worktrees/{{SESSION_NAME}}-<task-slug>
 ```
 
-Why: Crewly is a multi-agent system, and the main repo's working tree may be in any state (rebase pending, conflict markers, another agent's WIP). A private worktree is your *own* clean copy off the latest origin/main; you can build, test, and commit there without colliding. When you're done, push your branch and open a PR — the worktree gets cleaned up after merge.
+Why: Crewly is a multi-agent system, and the main repo's working tree may be in any state (rebase pending, conflict markers, another agent's WIP). A private worktree is your *own* clean copy off the latest origin/main; you can build, test, and commit there without colliding. When you're done, push your branch and open a PR — once the change has landed on `origin/main` (any git host, squash merges included) the Crewly janitor removes the worktree for you. If you already know it is merged and nobody needs it, run `git worktree remove <path>` yourself and keep the branch.
 
 This pattern *is* the dogfood — it's a KR4 template candidate, treat it as default for any code-touching task.
 

package/config/skills/agent/core/app-data/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: App Data
 description: Read and write the data of a Crewly App you published (the same collections the app's page sees through crewly.db) — list, get, set, update, add, delete. Use it to fill an app with content, act on what the owner entered, or answer an [APP CHANGES] message.
-version: 1.5.0
+version: 1.6.0
 category: productivity
 skillType: claude-skill
 assignableRoles:
@@ -44,6 +44,7 @@ bash execute.sh --app 28au74d9cj --set meta settings --data '{"title":"Weekly sh
 bash execute.sh --app 28au74d9cj --update items 1kx2-ab --data '{"done":true}' --if-rev 3
 bash execute.sh --app 28au74d9cj --add items --data '{"name":"eggs","done":false}'
 bash execute.sh --app 28au74d9cj --delete items 1kx2-ab
+bash execute.sh --app 28au74d9cj --get-field items 1kx2-ab --field /photo --out ./photo.png --decode   # full value of a cut field
 bash execute.sh --app 28au74d9cj --request-access --reason "write the morning briefing"   # ask the owner, see "Collaborators"
 bash execute.sh --app 28au74d9cj --collaborators                                          # who the owner let in
 bash execute.sh --app 28au74d9cj --owner                                                  # who the app's comments go to
@@ -200,3 +201,14 @@ write private information there.
 
 Collection names: `[A-Za-z0-9_-]{1,64}`. Doc ids: `[A-Za-z0-9_.:-]{1,128}`.
 Documents are JSON objects up to 256 KB.
+
+## Long values (over 65,536 characters)
+
+`--get` and `--list` cut any string over 65,536 characters (a base64 photo, a
+long document) so it cannot flood your terminal. A cut is never silent: the
+answer carries `truncated: [{"field":"/photo","chars":123456}]` (in a list,
+each entry also has the doc `id`). Do not parse a flagged value as if it were
+whole. Fetch it with `--get-field <collection> <docId> --field <pointer> --out
+<file>`: the full value goes to a file inside your project (nothing is printed
+but `{file, bytes}`). Add `--decode` for base64 / data-URL values to get the
+real binary (the image itself).

package/config/skills/agent/core/app-data/execute.sh

@@ -15,6 +15,7 @@ print_usage() {
 Usage:
   bash execute.sh --app <appId> --list <collection> [--limit 100] [--after <docId>]
   bash execute.sh --app <appId> --get <collection> <docId>
+  bash execute.sh --app <appId> --get-field <collection> <docId> --field </json/pointer> --out <file> [--decode]
   bash execute.sh --app <appId> --set <collection> <docId> --data '{"done":true}'
   bash execute.sh --app <appId> --update <collection> <docId> --data '{"done":true}' [--if-rev 4]
   bash execute.sh --app <appId> --add <collection> --data '{"name":"milk"}'
@@ -32,6 +33,10 @@ Options:
   --if-rev     Only update when the doc is still at this rev (409 conflict otherwise)
   --limit      Page size for --list (1-500, default 100)
   --after      Continue a --list after this doc id (the previous page's "next")
+  --get-field  Save the FULL value of one field to a file (reads cut strings over 65,536 characters and list them in "truncated"); prints only {file, bytes}
+  --field      JSON pointer into the doc's data, as listed in "truncated" (e.g. /photo, /items/0/image)
+  --out        File to write for --get-field: inside your project directory, not an existing symlink
+  --decode     With --get-field: base64-decode the value (a data:...;base64, prefix is dropped) so a photo is written as the real image
   --upload     Put a file (an image for a post) into the app and print its url; works for the owner's agents and for collaborators. Regular, non-symlink file inside your project directory, up to 10 MB (the app's own limit may be smaller)
   --name       File name to show for --upload (default: the file's name)
   --request-access  Ask the owner to let your team (default) or only you work in an app another team published; a card goes to the owner, nothing is granted until they tap Allow
@@ -51,10 +56,20 @@ fail_from() {
   exit 1
 }
 
+# Run one API call. stdout (the whole response body, however many lines it
+# spans) is kept apart from stderr (the missing-session warning, or the JSON
+# error object api_call prints on failure) so neither pollutes the other.
 call() {
-  local out
-  out=$(api_call "$@" 2>&1) || { fail_from "$(printf '%s\n' "$out" | tail -n 1)"; }
-  printf '%s\n' "$out" | tail -n 1
+  local out err errfile rc=0
+  errfile=$(mktemp "${TMPDIR:-/tmp}/app-data-err.XXXXXX") || errfile=/dev/null
+  out=$(api_call "$@" 2>"$errfile") || rc=$?
+  err=$(cat "$errfile" 2>/dev/null || true)
+  [ "$errfile" = /dev/null ] || rm -f "$errfile"
+  if [ "$rc" -ne 0 ]; then
+    # The error object is the last non-empty stderr line (warnings come first).
+    fail_from "$(printf '%s\n' "$err" | awk 'NF{l=$0} END{print l}')"
+  fi
+  printf '%s\n' "$out"
 }
 
 uri() { jq -rn --arg v "$1" '$v|@uri'; }
@@ -107,13 +122,35 @@ content_type_for() {
   esac
 }
 
-APP=""; OP=""; UPLOAD=""; NAME=""; COLL=""; DOC=""; DATA=""; IF_REV=""; LIMIT=""; AFTER=""; SCOPE=""; REASON=""; SET_OWNER=""; WHO=""
+# --out for --get-field: a new regular file inside the project directory
+# (CREWLY_PROJECT_PATH, else the working directory), never under Crewly's home,
+# never through a symlink. Prints the absolute target path.
+resolve_out_path() {
+  local given="$1" dir base project real_dir
+  dir="$(dirname "$given")"; base="$(basename "$given")"
+  [ -d "$dir" ] || error_exit "the directory of --out does not exist: $dir"
+  real_dir="$(cd "$dir" && pwd -P)"
+  project="$(cd "${CREWLY_PROJECT_PATH:-$PWD}" && pwd -P)" || error_exit "cannot resolve the project directory"
+  case "$real_dir/" in "$project"/*) ;; *) error_exit "--out must be inside your project directory ($project)" ;; esac
+  case "$real_dir/" in "${CREWLY_HOME:-$HOME/.crewly}"/*|"$HOME/.crewly"/*) error_exit "--out is inside Crewly's home directory" ;; esac
+  [ ! -L "$real_dir/$base" ] || error_exit "--out is a symbolic link; pass a real file path"
+  [ ! -d "$real_dir/$base" ] || error_exit "--out is a directory"
+  printf '%s/%s' "$real_dir" "$base"
+}
+
+APP=""; OP=""; UPLOAD=""; NAME=""; COLL=""; DOC=""; DATA=""; IF_REV=""; LIMIT=""; AFTER=""; SCOPE=""; REASON=""; SET_OWNER=""; WHO=""; FIELD=""; OUT_FILE=""; DECODE=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --app)    [ $# -ge 2 ] || error_exit "--app requires a value"; APP="$2"; shift 2 ;;
     --list|--add)
       [ $# -ge 2 ] || error_exit "$1 requires a collection"
       OP="${1#--}"; COLL="$2"; shift 2 ;;
+    --get-field)
+      [ $# -ge 3 ] || error_exit "--get-field requires a collection and a doc id"
+      OP="get-field"; COLL="$2"; DOC="$3"; shift 3 ;;
+    --field)     [ $# -ge 2 ] || error_exit "--field requires a JSON pointer"; FIELD="$2"; shift 2 ;;
+    --out)       [ $# -ge 2 ] || error_exit "--out requires a file path";   OUT_FILE="$2"; shift 2 ;;
+    --decode)    DECODE=1; shift ;;
     --get|--set|--update|--delete)
       [ $# -ge 3 ] || error_exit "$1 requires a collection and a doc id"
       OP="${1#--}"; COLL="$2"; DOC="$3"; shift 3 ;;
@@ -191,11 +228,28 @@ case "$OP" in
     [ -n "$LIMIT" ] && Q="limit=$(uri "$LIMIT")"
     [ -n "$AFTER" ] && Q="${Q:+$Q&}after=$(uri "$AFTER")"
     RESPONSE=$(call GET "${BASE}${Q:+?$Q}") || { printf '%s\n' "$RESPONSE"; exit 1; }
-    printf '%s' "$RESPONSE" | jq -c '{success: true, docs: [.data.docs[]? | {id, data, rev, updatedAt, updatedBy: (.updatedBy.kind // null)} + (if .updatedBy.kind == "agent" then {by: .updatedBy.id} else {} end)], next: .data.next}'
+    printf '%s' "$RESPONSE" | jq -c '{success: true, docs: [.data.docs[]? | {id, data, rev, updatedAt, updatedBy: (.updatedBy.kind // null)} + (if .updatedBy.kind == "agent" then {by: .updatedBy.id} else {} end)], next: .data.next} + (if .data.truncated then {truncated: .data.truncated, truncatedHint: .data.truncatedHint} else {} end)'
+    ;;
+  get-field)
+    [ -n "$FIELD" ] || error_exit "--field is required for --get-field (a JSON pointer such as /photo)"
+    [ -n "$OUT_FILE" ] || error_exit "--out is required for --get-field"
+    TARGET="$(resolve_out_path "$OUT_FILE")" || exit 1
+    RESPONSE=$(CREWLY_SKILL_FULL_OUTPUT=1 call GET "${BASE}/$(uri "$DOC")/field?path=$(uri "$FIELD")") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    printf '%s' "$RESPONSE" | jq -e '.data.type == "string"' >/dev/null 2>&1 || error_exit "that field is not a string; read it with --get"
+    TMP_OUT="$(mktemp "${TARGET}.XXXXXX")" || error_exit "cannot write next to $OUT_FILE"
+    printf '%s' "$RESPONSE" | jq -j '.data.value' > "$TMP_OUT"
+    if [ -n "$DECODE" ]; then
+      sed -E '1s#^data:[^,]*;base64,##' "$TMP_OUT" | tr -d '\n\r ' > "${TMP_OUT}.b64"
+      { base64 -d < "${TMP_OUT}.b64" > "${TMP_OUT}.bin" 2>/dev/null || base64 -D < "${TMP_OUT}.b64" > "${TMP_OUT}.bin" 2>/dev/null; } \
+        || { rm -f "$TMP_OUT" "${TMP_OUT}.b64" "${TMP_OUT}.bin"; error_exit "the value is not valid base64"; }
+      mv "${TMP_OUT}.bin" "$TMP_OUT"; rm -f "${TMP_OUT}.b64"
+    fi
+    mv "$TMP_OUT" "$TARGET"
+    jq -cn --arg f "$TARGET" --argjson b "$(wc -c < "$TARGET" | tr -d ' ')" --argjson c "$(printf '%s' "$RESPONSE" | jq '.data.chars')" '{success: true, file: $f, bytes: $b, chars: $c}'
     ;;
   get)
     RESPONSE=$(call GET "${BASE}/$(uri "$DOC")") || { printf '%s\n' "$RESPONSE"; exit 1; }
-    printf '%s' "$RESPONSE" | jq -c '{success: true, id: .data.id, data: .data.data, rev: .data.rev, updatedAt: .data.updatedAt}'
+    printf '%s' "$RESPONSE" | jq -c '{success: true, id: .data.id, data: .data.data, rev: .data.rev, updatedAt: .data.updatedAt} + (if .data.truncated then {truncated: .data.truncated, truncatedHint: .data.truncatedHint} else {} end)'
     ;;
   set)
     need_data

package/config/skills/agent/core/app-data/execute.test.sh

@@ -24,6 +24,18 @@ class H(BaseHTTPRequestHandler):
         def send(code, obj):
             self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
             self.wfile.write(json.dumps(obj).encode())
+        if self.path.endswith('/pretty'):
+            self.send_response(200); self.send_header('Content-Type', 'application/json'); self.end_headers()
+            return self.wfile.write(json.dumps({'success': True, 'data': {'id': 'pretty', 'data': {'text': 'line1\nline2'}, 'rev': 3, 'updatedAt': 't'}}, indent=2).encode())
+        if '/field' in self.path:
+            from urllib.parse import urlparse, parse_qs
+            q = parse_qs(urlparse(self.path).query).get('path', [''])[0]
+            if q == '/photo':
+                return send(200, {'success': True, 'data': {'field': q, 'type': 'string', 'chars': 38, 'value': 'data:image/png;base64,aGVsbG8gd29ybGQ='}})
+            if q == '/n':
+                return send(200, {'success': True, 'data': {'field': q, 'type': 'number', 'value': 1}})
+        if self.path.endswith('/trunc'):
+            return send(200, {'success': True, 'data': {'id': 'trunc', 'data': {'photo': 'xx'}, 'rev': 1, 'updatedAt': 't', 'truncated': [{'field': '/photo', 'chars': 70000}], 'truncatedHint': 'cut'}})
         if self.path.endswith('/missing'):
             return send(404, {'success': False, 'error': 'not_found', 'message': 'Document not found.', 'hint': 'No such app, document or version for this account.'})
         if self.path.endswith('/collaborators') and method == 'GET':
@@ -89,6 +101,15 @@ check "list: path" "$(jq -r .path "$STUB_LOG")" "/api/apps/$A/data/items?limit=5
 OUT=$(run --app $A --get items milk)
 check "get" "$OUT" '{"success":true,"id":"milk","data":{"name":"milk","done":false},"rev":2,"updatedAt":"t"}'
 
+# A multi-line (pretty-printed) response body must survive whole (#1122).
+OUT=$(run --app $A --get items pretty)
+check "get: multi-line body kept whole" "$OUT" '{"success":true,"id":"pretty","data":{"text":"line1\nline2"},"rev":3,"updatedAt":"t"}'
+# The missing-session warning goes to stderr and must not break the JSON (#1122).
+OUT=$(env "${ENVS[@]}" CREWLY_SESSION_NAME= bash "$EXEC" --app $A --get items pretty 2>/dev/null)
+check "get: stderr warning does not pollute stdout" "$(printf '%s' "$OUT" | jq -r .id)" "pretty"
+OUT=$(env "${ENVS[@]}" CREWLY_SESSION_NAME= bash "$EXEC" --app $A --get items missing 2>/dev/null; true)
+check "error with warning: reason still parsed" "$(printf '%s' "$OUT" | jq -r .reason)" "not_found"
+
 OUT=$(run --app $A --get items missing; true)
 check "get missing → not_found" "$(printf '%s' "$OUT" | jq -c '{success, status, reason}')" '{"success":false,"status":404,"reason":"not_found"}'
 
@@ -195,5 +216,26 @@ check "upload: 2xx without a url fails, not success with nulls" "$(printf '%s' "
 OUT=$(run_err --app $A --upload || true)
 check "upload needs a path" "$(printf '%s' "$OUT" | grep -c 'requires a file path')" "1"
 
+# --get / --list carry the truncation flag through (#1145).
+OUT=$(run --app $A --get items trunc)
+check "get: truncation flag passed through" "$(printf '%s' "$OUT" | jq -c '.truncated')" '[{"field":"/photo","chars":70000}]'
+
+# --get-field --out writes the full value to a file and prints no content (#1145).
+OUT=$(run --app $A --get-field items milk --field /photo --out "$WORK/proj/photo.txt")
+check "get-field: path" "$(jq -r .path "$STUB_LOG")" "/api/apps/$A/data/items/milk/field?path=%2Fphoto"
+check "get-field: file holds the raw value" "$(cat "$WORK/proj/photo.txt")" 'data:image/png;base64,aGVsbG8gd29ybGQ='
+check "get-field: prints a receipt, not the value" "$(printf '%s' "$OUT" | jq -c '{success, bytes, chars}')" '{"success":true,"bytes":38,"chars":38}'
+run --app $A --get-field items milk --field /photo --out "$WORK/proj/photo.bin" --decode >/dev/null
+check "get-field --decode: data URL decoded to bytes" "$(cat "$WORK/proj/photo.bin")" 'hello world'
+OUT=$(run_err --app $A --get-field items milk --field /photo --out "$WORK/outside-photo.txt" || true)
+check "get-field: --out outside the project refused" "$(printf '%s' "$OUT" | grep -c 'inside your project')" "1"
+ln -s "$WORK/outside.json" "$WORK/proj/out-link.txt"
+OUT=$(run_err --app $A --get-field items milk --field /photo --out "$WORK/proj/out-link.txt" || true)
+check "get-field: symlink --out refused" "$(printf '%s' "$OUT" | grep -c 'symbolic link')" "1"
+OUT=$(run_err --app $A --get-field items milk --field /n --out "$WORK/proj/n.txt" || true)
+check "get-field: non-string field refused" "$(printf '%s' "$OUT" | grep -c 'not a string')" "1"
+OUT=$(run_err --app $A --get-field items milk --out "$WORK/proj/x.txt" || true)
+check "get-field: --field required" "$(printf '%s' "$OUT" | grep -c -- '--field is required')" "1"
+
 echo "app-data: $PASS passed, $FAIL failed"
 [ "$FAIL" -eq 0 ]

package/config/skills/agent/core/docs-comment/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: Docs Comment
-description: Handle feedback left as comments in a Google Doc — list comments and replies, reply, resolve, or add a comment (via the Google Workspace grant held by Crewly Cloud). Writes as the owner's Google account — say what you posted.
-version: 1.0.0
+description: Handle feedback left as comments in a Google Doc — list comments and replies; reply, resolve and add are queued for the owner's OK and posted as a batch only after they reply 「发 C<n>」 (via the Google Workspace grant held by Crewly Cloud).
+version: 1.1.0
 category: productivity
 skillType: claude-skill
 assignableRoles:
@@ -41,6 +41,9 @@ bash execute.sh reply   --doc 1AbC… --comment AAAB… --text "Updated the intr
 bash execute.sh resolve --doc 1AbC… --comment AAAB… --text "Done in v2."
 bash execute.sh resolve --doc 1AbC… --comment AAAB…
 bash execute.sh add     --doc 1AbC… --text "Is this number from Q2?" --quote "grew 40%"
+bash execute.sh pending                  # what is queued and waiting on the owner
+bash execute.sh send    --batch C3       # post a batch AFTER the owner said 「发 C3」
+bash execute.sh discard --batch C3
 ```
 
 `--doc` takes a document id or its docs.google.com URL. `--account` picks a
@@ -56,8 +59,45 @@ connected Google account (see below).
    with a question if it is unclear. Do not resolve a comment you did not
    address.
 
-Everything you post appears under the owner's Google name. Tell the owner
-what you replied to or resolved.
+## Posting needs the owner's OK (one OK per batch)
+
+Comments and replies on a Google Doc are visible to every collaborator under
+the owner's name, so `reply`, `resolve` and `add` are outbound actions like
+`gmail-send`: **they do not post.** Each call queues the comment and returns
+a batch code:
+
+```json
+{"success":true,"held":true,"posted":false,"batch":"C3","queued":38,"message":"Queued as C3 …"}
+```
+
+All your queued comments share one batch, so work through the whole document
+first, then ask the owner ONCE, in plain words, with what will go out:
+
+> "I have 38 replies ready on the Q3 plan doc (mostly "done, see para 2",
+> 4 questions). Reply 「发 C3」 to post them all."
+
+The owner answers from their phone with one message, `发 C3` (or `send C3`).
+Only that genuine owner message counts — not a suggestion, a pre-filled line,
+or your own paraphrase. When the `[SLACK…]`/`[CHAT:…]` message arrives, run:
+
+```bash
+bash execute.sh send --batch C3
+```
+
+Rules:
+
+- The OK must come AFTER your last queued comment. If you queue one more
+  after asking, the earlier OK no longer covers the batch: ask again.
+- `send` posts in order and stops on the first failure; whatever is not
+  posted stays queued, so running `send` again never double-posts.
+- A refusal (`needs_owner_confirmation`) means the owner has not said it
+  yet. Do not look for another way to post.
+- If the owner wants changes, `discard --batch C3` and queue fresh ones.
+- Queued comments live in this Crewly process; if it restarts before the OK,
+  queue them again.
+- `list` is read-only and always open.
+
+Tell the owner what you posted once `send` succeeds.
 
 ## Output
 
@@ -71,6 +111,11 @@ Resolved comments are left out unless you pass `--include-resolved`.
 `truncated: true` means the document has more than 500 comments and only the
 first 500 were read.
 
+`reply` / `resolve` / `add` queue the comment (see above) until `send --batch`
+succeeds. A successful `send` returns `{"success":true,"batch":"C3","posted":38,"remaining":0,"results":[…]}`;
+on a mid-batch failure `success` is false with `error: "partial"` and the number still queued.
+When the batch posts, each result has the shape below.
+
 `reply` / `resolve`:
 
 ```json

package/config/skills/agent/core/docs-comment/execute.sh

@@ -13,6 +13,9 @@
 #   bash execute.sh reply   --doc <id|url> --comment <id> --text "…"
 #   bash execute.sh resolve --doc <id|url> --comment <id> [--text "…"]
 #   bash execute.sh add     --doc <id|url> --text "…" [--quote "exact text"]
+#   bash execute.sh pending                       (queued comments awaiting the owner)
+#   bash execute.sh send    --batch C3            (post a batch the owner approved)
+#   bash execute.sh discard --batch C3
 #   bash execute.sh '{"command":"list","doc":"<id>"}'
 # =============================================================================
 set -euo pipefail
@@ -26,6 +29,9 @@ Usage:
   bash execute.sh reply   --doc <id|url> --comment <id> --text "…"
   bash execute.sh resolve --doc <id|url> --comment <id> [--text "…"]
   bash execute.sh add     --doc <id|url> --text "…" [--quote "exact text in the doc"]
+  bash execute.sh pending
+  bash execute.sh send    --batch C3
+  bash execute.sh discard --batch C3
   bash execute.sh '{"command":"reply","doc":"<id>","comment":"<id>","text":"…"}'
 
 Options:
@@ -35,6 +41,10 @@ Options:
   --quote             Exact document text the new comment is about (add only;
                       Google Docs may still show it as an unanchored comment)
   --include-resolved  list: include resolved comments too
+  --batch             send / discard: the batch code a reply / resolve / add returned (e.g. C3)
+
+reply, resolve and add do NOT post: they queue the comment for the owner and
+return a batch code. After the owner answers 「发 <code>」, run send --batch.
   --account           Which connected Google account to act as (default: your primary)
   --help | -h         Show this help
 EOF_USAGE
@@ -66,7 +76,7 @@ elif [[ $# -gt 0 && ${1:0:1} != '-' ]]; then
   COMMAND="$1"
   shift
 fi
-DOC=""; COMMENT=""; TEXT=""; TEXT_SET=0; QUOTE=""; INCLUDE_RESOLVED=0; ACCOUNT=""
+DOC=""; COMMENT=""; TEXT=""; TEXT_SET=0; QUOTE=""; INCLUDE_RESOLVED=0; ACCOUNT=""; BATCH=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --doc|--id)         [ $# -ge 2 ] || error_exit "$1 requires a value";        DOC="$2";     shift 2 ;;
@@ -75,6 +85,7 @@ while [[ $# -gt 0 ]]; do
     --quote)            [ $# -ge 2 ] || error_exit "--quote requires a value";   QUOTE="$2";   shift 2 ;;
     --include-resolved) INCLUDE_RESOLVED=1; shift ;;
     --account)          [ $# -ge 2 ] || error_exit "--account requires a value"; ACCOUNT="$2"; shift 2 ;;
+    --batch)            [ $# -ge 2 ] || error_exit "--batch requires a value";   BATCH="$2";   shift 2 ;;
     --help|-h)          print_usage; exit 0 ;;
     *) error_exit "Unknown option: $1" ;;
   esac
@@ -88,13 +99,35 @@ if [ -n "$INPUT_JSON" ]; then
   [ -z "$QUOTE" ]   && QUOTE=$(printf '%s' "$INPUT" | jq -r '.quote // empty')
   [ "$INCLUDE_RESOLVED" -eq 0 ] && [ "$(printf '%s' "$INPUT" | jq -r '.includeResolved // false')" = "true" ] && INCLUDE_RESOLVED=1
   [ -z "$ACCOUNT" ] && ACCOUNT=$(printf '%s' "$INPUT" | jq -r '.account // empty')
+  [ -z "$BATCH" ]   && BATCH=$(printf '%s' "$INPUT" | jq -r '.batch // empty')
 fi
 # Route the call at one connected Google account; unset means the default.
 [ -n "$ACCOUNT" ] && export CREWLY_GOOGLE_ACCOUNT="$ACCOUNT"
 # Accept a full docs.google.com URL too.
 DOC=$(printf '%s' "$DOC" | sed -E 's#.*/document/d/([^/?]+).*#\1#')
 
-[ -n "$COMMAND" ] || error_exit "a command is required: list, reply, resolve or add (see --help)"
+[ -n "$COMMAND" ] || error_exit "a command is required: list, reply, resolve, add, pending, send or discard (see --help)"
+BATCHES="/google/doc-comment-batches"
+# Comment writes are outbound: an agent's are queued, not posted (HTTP 202).
+# Print the queue answer instead of a post result.
+held_or() {
+  if printf '%s' "$1" | jq -e '.data.held == true' >/dev/null 2>&1; then
+    printf '%s' "$1" | jq -c '{success: true, held: true, posted: false, batch: .data.batch, queued: .data.queued, message: .data.message}'
+    return 0
+  fi
+  return 1
+}
+case "$COMMAND" in
+  pending)
+    RESPONSE=$(call GET "$BATCHES") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), batches: [.data.batches[] | {batch: .code, agent: .agentSession, queued: (.items | length), items: [.items[] | {action, docId, commentId, text, quote}]}]}'
+    exit 0 ;;
+  send|discard)
+    require_param "batch (--batch)" "$BATCH"
+    RESPONSE=$(call POST "${BATCHES}/$(uri "$BATCH")/${COMMAND}" '{}') || { printf '%s\n' "$RESPONSE"; exit 1; }
+    printf '%s' "$RESPONSE" | jq -c '{success: (.success // false)} + .data'
+    exit 0 ;;
+esac
 require_param "doc (--doc)" "$DOC"
 BASE="/google/docs/$(uri "$DOC")/comments"
 
@@ -111,18 +144,21 @@ case "$COMMAND" in
     require_param "text (--text)" "$TEXT"
     BODY=$(jq -cn --arg text "$TEXT" '{text: $text}')
     RESPONSE=$(call POST "${BASE}/$(uri "$COMMENT")/replies" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    held_or "$RESPONSE" && exit 0
     printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), action: "reply", docId: .data.docId, commentId: .data.commentId, replyId: .data.id, content: .data.content}'
     ;;
   resolve)
     require_param "comment (--comment)" "$COMMENT"
     BODY=$(jq -cn --arg text "$TEXT" 'if $text != "" then {text: $text} else {} end')
     RESPONSE=$(call POST "${BASE}/$(uri "$COMMENT")/resolve" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    held_or "$RESPONSE" && exit 0
     printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), action: "resolve", docId: .data.docId, commentId: .data.commentId, replyId: .data.id, content: (.data.content // ""), resolved: true}'
     ;;
   add)
     require_param "text (--text)" "$TEXT"
     BODY=$(jq -cn --arg text "$TEXT" --arg quote "$QUOTE" '{text: $text} + (if $quote != "" then {quote: $quote} else {} end)')
     RESPONSE=$(call POST "${BASE}" "$BODY") || { printf '%s\n' "$RESPONSE"; exit 1; }
+    held_or "$RESPONSE" && exit 0
     printf '%s' "$RESPONSE" | jq -c '{success: (.success // false), action: "add", docId: .data.docId, commentId: .data.id, content: .data.content} + (if .data.quote then {quote: .data.quote} else {} end)'
     ;;
   *)

package/config/skills/agent/core/docs-comment/execute.test.sh

@@ -30,6 +30,14 @@ class H(BaseHTTPRequestHandler):
             return self._send(403, {'success': False, 'error': 'reauth_required',
                                     'message': 'Replying to or adding comments on this document needs Google Drive edit access, which this Google account has not granted yet.',
                                     'hint': 'Ask the owner to reconnect Google Drive: run the google-connect skill with --product drive.'})
+        if '/docs/held/' in self.path:
+            return self._send(202, {'success': True, 'data': {'held': True, 'batch': 'C3', 'queued': 2, 'message': 'Queued as C3'}})
+        if self.path.startswith('/api/google/doc-comment-batches'):
+            if method == 'GET':
+                return self._send(200, {'success': True, 'data': {'batches': [{'code': 'C3', 'agentSession': 'ella', 'items': [{'action': 'reply', 'docId': 'd1', 'commentId': 'c1', 'text': 'Fixed'}]}]}})
+            if '/C9/' in self.path:
+                return self._send(403, {'success': False, 'error': 'needs_owner_confirmation', 'message': 'The owner has not confirmed batch C9'})
+            return self._send(200, {'success': True, 'data': {'batch': 'C3', 'posted': 2, 'remaining': 0}})
         if method == 'GET':
             return self._send(200, {'success': True, 'data': {'docId': 'd1', 'comments': [COMMENT], 'truncated': False}})
         if self.path.endswith('/replies'):
@@ -93,6 +101,26 @@ check "reauth: exit code" "$CODE" "1"
 check "reauth: reason" "$(printf '%s' "$OUT" | jq -r '.reason')" "reauth_required"
 check "reauth: hint names the one-tap path" "$(printf '%s' "$OUT" | jq -r '.hint' | grep -c 'google-connect skill with --product drive')" "1"
 
+# a held comment is reported as queued, never as posted
+for ACT in "reply --doc held --comment c1 --text x" "resolve --doc held --comment c1" "add --doc held --text x"; do
+  OUT=$(run $ACT)
+  check "held (${ACT%% *}): output" "$OUT" '{"success":true,"held":true,"posted":false,"batch":"C3","queued":2,"message":"Queued as C3"}'
+done
+
+# pending / send / discard
+OUT=$(run pending)
+check "pending: request" "$(req)" 'GET /api/google/doc-comment-batches null'
+check "pending: output" "$OUT" '{"success":true,"batches":[{"batch":"C3","agent":"ella","queued":1,"items":[{"action":"reply","docId":"d1","commentId":"c1","text":"Fixed","quote":null}]}]}'
+OUT=$(run send --batch C3)
+check "send: request" "$(req)" 'POST /api/google/doc-comment-batches/C3/send {}'
+check "send: output" "$OUT" '{"success":true,"batch":"C3","posted":2,"remaining":0}'
+run discard --batch C3 >/dev/null
+check "discard: request" "$(req)" 'POST /api/google/doc-comment-batches/C3/discard {}'
+OUT=$(run send --batch C9); CODE=$?
+check "send refused: exit code" "$CODE" "1"
+check "send refused: reason" "$(printf '%s' "$OUT" | jq -r '.reason')" "needs_owner_confirmation"
+check "send needs --batch" "$(run_err send | grep -c 'batch')" "1"
+
 # argument validation (no request sent)
 check "no command" "$(run_err --doc d1 | grep -c 'command is required')" "1"
 check "unknown command" "$(run_err delete --doc d1 | grep -c 'Unknown command')" "1"

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

@@ -829,6 +829,13 @@ export declare const BROWSER_BRIDGE_CONSTANTS: {
     readonly WS_PATH: "/ws/browser";
     /** Default timeout for commands sent to Chrome Extension (ms) */
     readonly COMMAND_TIMEOUT_MS: 30000;
+    /**
+     * Timeout for screenshot / full-page-screenshot (ms). Capturing a heavy
+     * page (Slack web, long feeds) and relaying a multi-MB base64 image takes
+     * well beyond the 30 s default; the shorter limit made them look like a
+     * missing browser (crewly#1080).
+     */
+    readonly SCREENSHOT_TIMEOUT_MS: 90000;
     /**
      * Per-tab dispatch (1 agent : 1 tab) — see
      * `.crewly/specs/crewly-in-chrome-per-tab-fix-2026-04-25.md`.
@@ -2821,6 +2828,26 @@ export declare const WORKTREE_JANITOR_CONSTANTS: {
     readonly LOW_DISK_REPORT_ITEMS: 5;
     /** Timeout of one `du -sk` size probe (ms). */
     readonly DU_TIMEOUT_MS: 60000;
+    /** Runaway-file watcher (crewly#1078): how often agent scratch dirs and worktrees are scanned (1 minute). */
+    readonly RUNAWAY_CHECK_INTERVAL_MS: number;
+    /** A file this big in an agent dir is reported to the owner (5 GB); if it is also still growing, its writer is stopped. */
+    readonly RUNAWAY_FILE_BYTES: number;
+    /** A file that grew by this much per minute between two scans is a runaway whatever its size (1 GB/min). */
+    readonly RUNAWAY_GROWTH_BYTES_PER_MIN: number;
+    /** Files smaller than this are never tracked between scans (cheap pre-filter, 256 MB). */
+    readonly RUNAWAY_TRACK_MIN_BYTES: number;
+    /** Bytes of a stopped runaway file kept (the head, so the agent can see what it was writing, 1 MB). */
+    readonly RUNAWAY_KEEP_HEAD_BYTES: number;
+    /** How deep under each watched dir files are looked for. */
+    readonly RUNAWAY_SCAN_DEPTH: 8;
+    /** Cap on directory entries visited per scan. */
+    readonly RUNAWAY_SCAN_MAX_ENTRIES: 200000;
+    /** Wait after SIGTERM before SIGKILL for the writer (ms). */
+    readonly RUNAWAY_KILL_GRACE_MS: 3000;
+    /** Timeout of the `lsof` that finds a file's writers (ms). */
+    readonly RUNAWAY_LSOF_TIMEOUT_MS: 10000;
+    /** One line added to every agent's start prompt. */
+    readonly PROMPT_HINT: "Disk hygiene: never let a command or script write an unbounded file. When you redirect or concatenate output (`> file`, `>> file`, `cat a b > all.md`), cap it (`| head -c 50M`, `| head -n 100000`) and never build a file from its own output. A file in your scratch dir or worktree that grows past a few GB is stopped by Crewly and the owner is alerted.";
     /** State file under CREWLY_HOME remembering when the owner was last told about low disk. */
     readonly STATE_FILENAME: "disk-janitor-state.json";
     /**
@@ -2844,6 +2871,27 @@ export declare const WORKTREE_JANITOR_CONSTANTS: {
      * instead of 24 h). `worktree-agent-` is Claude Code's automatic subagent branch.
      */
     readonly AGENT_BRANCH_PREFIXES: readonly string[];
+    /**
+     * Untracked paths under a directory with one of these names (or a `*.log`
+     * file) are regenerable output and do not make a worktree "dirty". Nested
+     * packages often do not ignore their own `node_modules` / `.next`, so
+     * `git status` lists them as untracked.
+     */
+    readonly REGENERABLE_DIRS: readonly string[];
+    /** File suffixes treated as regenerable output (logs). */
+    readonly REGENERABLE_FILE_SUFFIXES: readonly string[];
+    /** Directories deleted from kept (dirty / not-merged) worktrees under low disk — reinstalled by `npm install` / rebuilt by `next build`. */
+    readonly RECLAIM_DIRS: readonly string[];
+    /** A kept worktree must be idle this long before its regenerable dirs are reclaimed under low disk (24 hours). */
+    readonly RECLAIM_MIN_IDLE_MS: number;
+    /** How deep under a worktree reclaimable dirs are searched for (root = 0; `web/node_modules` = 1). */
+    readonly RECLAIM_SEARCH_DEPTH: 3;
+    /** Work completion (task done / verified) schedules one tidy pass after this quiet period (2 minutes); bursts share it. */
+    readonly COMPLETION_TIDY_DELAY_MS: number;
+    /** Idle needed by a completion-triggered pass: the agent said it is finished, so far less than the periodic threshold (10 minutes). */
+    readonly COMPLETION_MIN_IDLE_MS: number;
+    /** Commits of the default branch searched for a squash-merge patch-equivalent of a branch. */
+    readonly SQUASH_SEARCH_MAX_COMMITS: 300;
     /** Branches that are never deleted, whatever the verdict. */
     readonly PROTECTED_BRANCHES: readonly string[];
     /** Timeout of one local git command (ms). */