crewly 1.20.295 → 1.20.297

package/config/skills/_common/lib.sh

@@ -222,6 +222,12 @@ api_call() {
   local url="${CREWLY_API_URL}/api${endpoint}"
   _prune_skill_output
   local args=(-s -w '\n%{http_code}' -X "$method")
+  # Optional ceiling on the whole request (seconds). A caller that can tell
+  # "the server is slow" from "it failed" (poll-tasks' claim) sets it; curl
+  # then exits 28 instead of hanging until the skill runner kills the call.
+  if [ -n "${CREWLY_API_MAX_TIME:-}" ]; then
+    args+=(--max-time "$CREWLY_API_MAX_TIME")
+  fi
   # A raw file upload (app-data --upload): CREWLY_API_UPLOAD_FILE is sent as the
   # body, byte for byte, with CREWLY_API_UPLOAD_TYPE as its Content-Type and the
   # URI-encoded CREWLY_API_UPLOAD_NAME as X-File-Name. Everything else is JSON.

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/complete-task/SKILL.md

@@ -60,9 +60,11 @@ On success the skill prints **one JSON line** that always names the `workItemId`
 Resolution order:
 
 1. `workItemId`, if you pass it — always wins.
-2. Otherwise, a lookup of the WorkItem currently `running` against your
+2. Otherwise, ONLY when you named no task (no `workItemId`, no `taskId`): a lookup of the WorkItem currently `running` against your
    `sessionName` (`GET /api/task-pool/items?status=running&target=<session>`).
-3. If neither resolves, the skill exits non-zero with an error naming the
+3. If you passed `taskId` without `workItemId`, the skill
+   refuses (non-zero exit): it never substitutes your running item for an id you named.
+4. If nothing resolves, the skill exits non-zero with an error naming the
    session it searched. It never reports success without completing something.
 
 Pass `workItemId` whenever you know it — the lookup in step 2 depends on the

package/config/skills/agent/core/complete-task/execute.sh

@@ -124,6 +124,13 @@ fi
 #
 # WORK_ITEM_ID was read from the input up top alongside the other params,
 # so the identifier is known before any of the legacy path handling runs.
+# A `taskId` names a specific task: never swap it for whatever happens to be
+# running (#1134 - a complete-task naming one item closed the agent's active,
+# unfinished one). The legacy `absoluteTaskPath` is only logging context and
+# keeps its documented pool lookup.
+if [ -z "$WORK_ITEM_ID" ] && [ -n "$TASK_ID" ]; then
+  error_exit "Nothing was completed: you passed taskId '${TASK_ID}' but no 'workItemId', and this skill does not guess which WorkItem you meant. Pass 'workItemId' (find it with GET /api/task-pool/items?target=${SESSION_NAME}) and call again."
+fi
 if [ -z "$WORK_ITEM_ID" ]; then
   POOL_RESP=$(api_call_full GET "/task-pool/items?status=running&target=${SESSION_NAME}" 2>/dev/null || echo '{}')
   WORK_ITEM_ID=$(echo "$POOL_RESP" | jq -r '.workItems[0].id // .data[0].id // empty' 2>/dev/null || true)

package/config/skills/agent/core/complete-task/explicit-id.test.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Tests for complete-task never swapping a named id for the running item (#1134) — run with: bash explicit-id.test.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  if [ "$2" = "$3" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $1"; echo "  want: $3"; echo "  got:  $2"; fi
+}
+
+PORT=18854
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+: > "$STUB_LOG"
+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'])
+class H(BaseHTTPRequestHandler):
+    def reply(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 note(self):
+        open(LOG, 'a').write(self.command + ' ' + self.path + '\n')
+    def do_GET(self):
+        self.note()
+        return self.reply(200, {'workItems': [{'id': 'wi-running'}]})
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); self.rfile.read(n)
+        self.note()
+        return self.reply(200, {'success': True})
+    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
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' 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
+
+run() { CREWLY_SESSION_NAME=dev-1 CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$1" 2>&1; echo "exit=$?"; }
+
+: > "$STUB_LOG"
+OUT=$(run '{"taskId":"wi-other","sessionName":"dev-1","summary":"done"}')
+check "taskId without workItemId: refused" "$(printf '%s' "$OUT" | grep -c 'exit=1')" "1"
+check "taskId without workItemId: names the problem" "$(printf '%s' "$OUT" | grep -c "does not guess")" "1"
+check "taskId without workItemId: nothing sent" "$(grep -vc heartbeat "$STUB_LOG")" "0"
+
+: > "$STUB_LOG"
+run '{"workItemId":"wi-given","sessionName":"dev-1","summary":"done"}' >/dev/null
+check "explicit workItemId: completes exactly that one" "$(grep -v heartbeat "$STUB_LOG")" "POST /api/task-pool/complete/wi-given"
+
+: > "$STUB_LOG"
+run '{"sessionName":"dev-1","summary":"done"}' >/dev/null
+check "no id at all: running-item lookup still works" "$(tail -1 "$STUB_LOG")" "POST /api/task-pool/complete/wi-running"
+
+echo "complete-task: $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/config/skills/agent/core/poll-tasks/execute.sh

@@ -19,6 +19,8 @@
 # Returns:
 #   On claim: { success: true, claimed: true, workItem: {...}, claim: {...} }
 #   No match: { success: true, claimed: false, available: 0, message: "..." }
+#   Pending:  { success: true, claimed: false, claimPending: true, message: "..." } — the claim timed
+#             out and may still land; do not retry, check get-my-tasks later
 #   Error:    { error: "..." } on stderr, exit 1
 # =============================================================================
 set -euo pipefail
@@ -168,8 +170,18 @@ else
     }')
 fi
 
-CLAIM_RESPONSE=$(api_call POST "/task-pool/claim" "$CLAIM_BODY" 2>&1) || {
+# The claim is a write the server may apply long after this call gives up
+# (a slow pool-file rewrite queues behind other writes, crewly#1108). Bound
+# the wait and report "pending" instead of failing: a failure invites a blind
+# retry, which queues yet another write.
+CLAIM_RESPONSE=$(CREWLY_API_MAX_TIME="${POLL_TASKS_CLAIM_MAX_TIME:-90}" api_call POST "/task-pool/claim" "$CLAIM_BODY" 2>&1) || {
   CLAIM_ERROR="$CLAIM_RESPONSE"
+  # Timed out (curl 28), no HTTP answer (status 0 / 000) or a gateway timeout:
+  # the claim may still land. Do not retry; look at get-my-tasks later.
+  if printf '%s' "$CLAIM_ERROR" | grep -Eq 'exit code 28|"status":(0|000|408|502|503|504)[,}]'; then
+    jq -n '{success: true, claimed: false, claimPending: true, message: "Claim pending: the server has not answered yet and may still apply it. Do NOT retry the claim; check get-my-tasks in a minute to see whether the work item is yours."}'
+    exit 0
+  fi
   # 404 = no available items (race condition — someone else claimed it)
   if printf '%s' "$CLAIM_ERROR" | grep -q '"status":404'; then
     jq -n '{success: true, claimed: false, available: 0, message: "No work items available (claimed by another agent)"}'

package/config/skills/agent/core/poll-tasks/execute.test.sh

@@ -297,6 +297,43 @@ assert_json_field "fifo body has no workItemId" "$FIFO_BODY" ".workItemId" "null
 assert_json_field "fifo body types[0]" "$FIFO_BODY" ".filters.types[0]" "delegate"
 assert_json_field "fifo body types[1]" "$FIFO_BODY" ".filters.types[1]" "project_task"
 
+# ---------------------------------------------------------------------------
+# Test 9: a claim that times out is reported as pending, not as a failure
+# (crewly#1108). Runs the real execute.sh against a stub curl: GETs answer
+# with one queued item, the claim POST "times out" (curl exit 28).
+# ---------------------------------------------------------------------------
+echo "Test 9: claim timeout is reported as claimPending"
+
+STUB_DIR=$(mktemp -d)
+cat > "$STUB_DIR/curl" <<'STUB'
+#!/bin/bash
+method=GET
+for a in "$@"; do
+  if [ "$prev" = "-X" ]; then method="$a"; fi
+  prev="$a"
+done
+if [ "$method" = "POST" ]; then
+  [ "$STUB_MODE" = "http504" ] && { printf '{"error":"gateway"}\n504'; exit 0; }
+  [ "$STUB_MODE" = "http500" ] && { printf '{"error":"boom"}\n500'; exit 0; }
+  exit 28
+fi
+printf '{"success":true,"count":1,"data":[{"id":"wi-1","title":"t","description":"d"}]}\n200'
+STUB
+chmod +x "$STUB_DIR/curl"
+
+OUTPUT=$(PATH="$STUB_DIR:$PATH" STUB_MODE=timeout CREWLY_SESSION_NAME=agent-1 bash "$SCRIPT_DIR/execute.sh" '{"sessionName":"agent-1"}' </dev/null 2>/dev/null) && EXIT_CODE=$? || EXIT_CODE=$?
+assert_eq "timeout exits 0" "0" "$EXIT_CODE"
+assert_json_field "timeout: claimPending" "$OUTPUT" ".claimPending" "true"
+assert_json_field "timeout: claimed false" "$OUTPUT" ".claimed" "false"
+assert_contains "timeout: tells the agent not to retry" "Do NOT retry" "$OUTPUT"
+
+OUTPUT=$(PATH="$STUB_DIR:$PATH" STUB_MODE=http504 CREWLY_SESSION_NAME=agent-1 bash "$SCRIPT_DIR/execute.sh" '{"sessionName":"agent-1"}' </dev/null 2>/dev/null) && EXIT_CODE=$? || EXIT_CODE=$?
+assert_json_field "504: claimPending" "$OUTPUT" ".claimPending" "true"
+
+OUTPUT=$(PATH="$STUB_DIR:$PATH" STUB_MODE=http500 CREWLY_SESSION_NAME=agent-1 bash "$SCRIPT_DIR/execute.sh" '{"sessionName":"agent-1"}' </dev/null 2>&1) && EXIT_CODE=$? || EXIT_CODE=$?
+assert_eq "a real 500 is still an error" "1" "$EXIT_CODE"
+rm -rf "$STUB_DIR"
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------