@cluesmith/codev 3.3.2 → 3.3.4

package/scripts/forge/github/pr-create.sh

@@ -0,0 +1,47 @@
+#!/bin/sh
+# Forge concept: pr-create (GitHub via gh CLI)
+# forge-executable: gh
+#
+# Input:  CODEV_PR_TITLE (required)
+#         CODEV_PR_BODY  (required, may be empty)
+#         CODEV_PR_BASE, CODEV_PR_HEAD, CODEV_PR_REPO, CODEV_PR_DRAFT (optional)
+# Output: {"number": <int>, "url": "<web url>"}
+#
+# `gh pr create` prints the new PR's URL on stdout; the number is its last path
+# segment. Anything gh writes that isn't a URL (hints, prompts) is ignored.
+set -e
+
+if [ -z "$CODEV_PR_TITLE" ]; then
+  echo "pr-create: CODEV_PR_TITLE is required" >&2
+  exit 2
+fi
+
+# An empty body is allowed; an *absent* one is not. Without this, forgetting the
+# variable opens a PR with no body at exit 0 — the silent failure #1455 is about.
+if [ -z "${CODEV_PR_BODY+x}" ]; then
+  echo "pr-create: CODEV_PR_BODY is required (set it to \"\" for an empty body)" >&2
+  exit 2
+fi
+
+set -- --title "$CODEV_PR_TITLE" --body "$CODEV_PR_BODY"
+if [ -n "$CODEV_PR_BASE" ]; then set -- "$@" --base "$CODEV_PR_BASE"; fi
+if [ -n "$CODEV_PR_HEAD" ]; then set -- "$@" --head "$CODEV_PR_HEAD"; fi
+if [ -n "$CODEV_PR_REPO" ]; then set -- "$@" --repo "$CODEV_PR_REPO"; fi
+if [ "$CODEV_PR_DRAFT" = "1" ]; then set -- "$@" --draft; fi
+
+url=$(gh pr create "$@" | grep -E '^https?://' | tail -n 1)
+
+if [ -z "$url" ]; then
+  echo "pr-create: gh pr create returned no PR URL" >&2
+  exit 1
+fi
+
+number=${url##*/}
+case "$number" in
+  '' | *[!0-9]*)
+    echo "pr-create: could not parse a PR number from '$url'" >&2
+    exit 1
+    ;;
+esac
+
+printf '{"number":%s,"url":"%s"}\n' "$number" "$url"

package/scripts/forge/github/pr-list.sh

@@ -7,5 +7,9 @@
 # as objects (users carry `login`; teams carry `slug`/`name` and no `login`), so
 # `.login // empty` keeps user reviewers and drops team reviewers — matching the
 # `reviewRequests: string[]` contract in PrListItem (forge-contracts.ts).
-exec gh pr list --json number,title,url,reviewDecision,body,createdAt,author,reviewRequests,isDraft \
-  | jq '[.[] | .reviewRequests = [.reviewRequests[].login // empty]]'
+#
+# Not `gh … | jq`: POSIX sh has no pipefail, so the caller would see jq's exit
+# status and a rate-limited gh would look like a successful empty list (#1645).
+# forge-executable: gh
+out="$(gh pr list --json number,title,url,reviewDecision,body,createdAt,author,reviewRequests,isDraft)" || exit 1
+printf '%s' "$out" | jq '[.[] | .reviewRequests = [.reviewRequests[].login // empty]]'

package/scripts/forge/github/pr-search.sh

@@ -1,5 +1,9 @@
 #!/bin/sh
 # Forge concept: pr-search (GitHub via gh CLI)
 # Input: CODEV_SEARCH_QUERY
-# Output: JSON [{number, headRefName, baseRefName}]
-exec gh pr list --search "$CODEV_SEARCH_QUERY" --json number,headRefName,baseRefName
+# Output: JSON [{number, headRefName, baseRefName, state}]
+# --state all is required so the search includes merged/closed PRs; without it
+# `gh pr list` defaults to --state open and post-merge lookups return nothing (#759).
+# `state` (OPEN/MERGED/CLOSED) lets consumers that only want open PRs filter
+# client-side — the spawn collision guard must ignore merged/closed ones (#1637).
+exec gh pr list --state all --search "$CODEV_SEARCH_QUERY" --json number,headRefName,baseRefName,state

package/scripts/forge/gitlab/issue-search.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-search (GitLab via glab CLI)
+# forge-executable: glab
 #
 # ⚠️ UNVERIFIED — mirrors gitlab/issue-list.sh (raw `glab ... --output json`,
 #    no field normalization) plus a state flag and a `body` field surfaced from

package/scripts/forge/gitlab/issue-view.sh

@@ -1,6 +1,26 @@
 #!/bin/sh
 # Forge concept: issue-view (GitLab via glab CLI)
-# Adds a `url` field mapped from GitLab's `web_url` (the issue's browser page);
-# all other fields glab emits are passed through unchanged. `. + {url: …}` is
-# non-destructive — if `web_url` is absent, `url` is null (optional by contract).
-glab issue view "$CODEV_ISSUE_ID" --output json | jq '. + {url: .web_url}'
+# Maps GitLab's fields into the forge-neutral IssueView shape. `. + {…}` is
+# non-destructive for keys we don't touch; the mapped keys are optional by
+# contract, so a shape mismatch degrades to an omitted line rather than a crash
+# (jq returns null for missing keys, and the guards below tolerate null):
+#   web_url            -> url
+#   author.username    -> author.login
+#   created_at         -> createdAt
+#   assignees[].username -> assignees[].login
+#   labels[]           -> labels[].name  (newer glab emits label objects; older emits strings)
+#   milestone.title    -> milestone.title (null when unset)
+# Best-effort preset (Spec 589): fields GitLab doesn't expose stay absent. The
+# contract's optional fields are added only when present (via `+ {…}` merges) so
+# an absent field is OMITTED, not emitted as null — `author?`/`createdAt?` are not
+# nullable (only `milestone` is). `exec` is dropped: with a pipe it would replace
+# only the glab subshell, not the whole pipeline, so it's misleading here.
+glab issue view "$CODEV_ISSUE_ID" --output json | jq '
+  .
+  + {url: .web_url}
+  + {assignees: [(.assignees // [])[] | {login: .username}]}
+  + {labels: [(.labels // [])[] | if type == "string" then {name: .} else {name: .name} end]}
+  + (if .author.username then {author: {login: .author.username}} else {} end)
+  + (if .created_at then {createdAt: .created_at} else {} end)
+  + (if .milestone then {milestone: {title: .milestone.title}} else {} end)
+'

package/scripts/forge/gitlab/pr-create.sh

@@ -0,0 +1,53 @@
+#!/bin/sh
+# Forge concept: pr-create (GitLab via glab CLI — merge requests)
+# forge-executable: glab
+#
+# Input:  CODEV_PR_TITLE (required)
+#         CODEV_PR_BODY  (required, may be empty)
+#         CODEV_PR_BASE, CODEV_PR_HEAD, CODEV_PR_REPO, CODEV_PR_DRAFT (optional)
+# Output: {"number": <int>, "url": "<web url>"}
+#
+# ⚠️ UNVERIFIED — `glab` is not available in the authoring environment (same
+#    constraint as gitea/issue-search.sh, #920). Written against glab's
+#    documented `mr create` flags; smoke-test before relying on it. Without this
+#    file the gitlab preset would fall through to the GitHub default and shell
+#    out to `gh` — the bug this concept exists to close (#1455).
+#
+# `glab mr create --yes` skips the interactive prompts and prints the new MR's
+# URL; the number (GitLab's `iid`) is its last path segment.
+set -e
+
+if [ -z "$CODEV_PR_TITLE" ]; then
+  echo "pr-create: CODEV_PR_TITLE is required" >&2
+  exit 2
+fi
+
+# An empty body is allowed; an *absent* one is not. Without this, forgetting the
+# variable opens a PR with no body at exit 0 — the silent failure #1455 is about.
+if [ -z "${CODEV_PR_BODY+x}" ]; then
+  echo "pr-create: CODEV_PR_BODY is required (set it to \"\" for an empty body)" >&2
+  exit 2
+fi
+
+set -- --title "$CODEV_PR_TITLE" --description "$CODEV_PR_BODY" --yes
+if [ -n "$CODEV_PR_BASE" ]; then set -- "$@" --target-branch "$CODEV_PR_BASE"; fi
+if [ -n "$CODEV_PR_HEAD" ]; then set -- "$@" --source-branch "$CODEV_PR_HEAD"; fi
+if [ -n "$CODEV_PR_REPO" ]; then set -- "$@" --repo "$CODEV_PR_REPO"; fi
+if [ "$CODEV_PR_DRAFT" = "1" ]; then set -- "$@" --draft; fi
+
+url=$(glab mr create "$@" | grep -E '^https?://' | tail -n 1)
+
+if [ -z "$url" ]; then
+  echo "pr-create: glab mr create returned no MR URL" >&2
+  exit 1
+fi
+
+number=${url##*/}
+case "$number" in
+  '' | *[!0-9]*)
+    echo "pr-create: could not parse an MR number from '$url'" >&2
+    exit 1
+    ;;
+esac
+
+printf '{"number":%s,"url":"%s"}\n' "$number" "$url"

package/scripts/forge/gitlab/pr-search.sh

@@ -1,3 +1,38 @@
 #!/bin/sh
-# Forge concept: pr-search (GitLab via glab CLI)
-exec glab mr list --search "$CODEV_SEARCH_QUERY" --output json
+# Forge concept: pr-search (GitLab via glab CLI — merge requests)
+# Output: JSON [{number, headRefName, baseRefName, state, ...glab fields}]
+#
+# ⚠️ UNVERIFIED — `glab` is not available in the authoring environment (#920);
+#    written against glab's documented `mr list --output json` shape (confirmed
+#    against the field mappings already documented in gitlab/pr-list.sh and
+#    gitlab/pr-exists.sh). Smoke-test before relying on it.
+#
+# --all is required so the search includes merged/closed MRs; without it
+# `glab mr list` defaults to opened only and post-merge lookups return nothing (#759).
+#
+# Maps glab's GitLab-shaped fields into the forge-neutral PrSearchItem contract
+# (forge-contracts.ts); `. + {…}` is non-destructive for keys we don't touch:
+#   iid           -> number        (the MR number glab mr view/merge expects)
+#   source_branch -> headRefName
+#   target_branch -> baseRefName
+# Without this the spawn guard's message reads `PR #undefined` and consult's
+# findPRForIssue can't resolve the MR's base branch on GitLab.
+#
+# glab reports state lowercase (opened/merged/closed/locked); normalize to the
+# GitHub convention (OPEN/MERGED/CLOSED) so consumers filter with one comparison.
+# The spawn collision guard keys off state === "OPEN" to ignore merged MRs (#1637).
+# `locked` (a transient merging state) maps to OPEN too: the guard should err
+# toward the recoverable --force prompt, never silently skip a live collision.
+#
+# Not `glab … | jq`: POSIX sh has no pipefail, so the caller would see jq's exit
+# status and a failed glab would look like a successful empty list (#1645).
+# The capture-then-pipe shape hides `glab` from extractExecutable's first-line
+# heuristic (it lands on the `printf` builtin), so declare the backend explicitly
+# — same as github/pr-list.sh (#1645).
+# forge-executable: glab
+out="$(glab mr list --all --search "$CODEV_SEARCH_QUERY" --output json)" || exit 1
+printf '%s' "$out" | jq 'map(.
+  + {number: .iid}
+  + {headRefName: .source_branch}
+  + {baseRefName: .target_branch}
+  + {state: ((.state // "") | ascii_downcase as $s | if $s == "opened" or $s == "locked" then "OPEN" else ($s | ascii_upcase) end)})'

package/scripts/forge/linear/auth-status.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: auth-status (Linear via GraphQL API)
+# forge-executable: curl
 # Output: exit code (0 = authenticated)
 set -e
 

package/scripts/forge/linear/issue-comment.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-comment (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_ISSUE_ID, CODEV_COMMENT_BODY
 # Output: exit code only
 set -e

package/scripts/forge/linear/issue-list.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-list (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_LINEAR_TEAM (team key, e.g. "ENG")
 # Output: JSON [{number, title, url, labels, createdAt, author, assignees}]
 set -e

package/scripts/forge/linear/issue-search.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: issue-search (Linear via GraphQL API)
+# forge-executable: curl
 #
 # ⚠️ UNVERIFIED — mirrors linear/issue-list.sh with `description` added to the
 #    query (mapped to `body`) and the state filter parameterized. No Linear

package/scripts/forge/linear/issue-view.sh

@@ -1,7 +1,14 @@
 #!/bin/sh
 # Forge concept: issue-view (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_ISSUE_ID (e.g. "ENG-123")
-# Output: JSON {title, body, state, url, comments[]}
+# Output: JSON {title, body, state, url, author, createdAt, assignees, labels, milestone, comments[]}
+#
+# Maps Linear's fields into the forge-neutral IssueView shape. Linear has a
+# single `assignee` (emitted as a one-element `assignees` array) and `project`
+# rather than milestones (mapped into `milestone.title`). These fields are
+# optional by contract, so anything Linear leaves null degrades to an omitted
+# line. Best-effort preset (Spec 589).
 set -e
 
 if [ -z "$LINEAR_API_KEY" ]; then
@@ -18,7 +25,7 @@ curl -sf -X POST https://api.linear.app/graphql \
   -H "Content-Type: application/json" \
   -H "Authorization: $LINEAR_API_KEY" \
   -d "$(jq -n --arg id "$CODEV_ISSUE_ID" '{
-    query: "query($id: String!) { issueVcsByFilter: issues(filter: { identifier: { eq: $id } }) { nodes { title url description state { name } comments { nodes { body createdAt user { displayName } } } } } }",
+    query: "query($id: String!) { issueVcsByFilter: issues(filter: { identifier: { eq: $id } }) { nodes { title url description createdAt state { name } creator { displayName } assignee { displayName } labels { nodes { name } } project { name } comments { nodes { body createdAt user { displayName } } } } } }",
     variables: { id: $id }
   }')" \
   | jq 'if (.data.issueVcsByFilter.nodes | length) == 0 then
@@ -29,6 +36,11 @@ curl -sf -X POST https://api.linear.app/graphql \
       url: .url,
       body: (.description // ""),
       state: .state.name,
+      author: (if .creator then { login: .creator.displayName } else null end),
+      createdAt: .createdAt,
+      assignees: (if .assignee then [{ login: .assignee.displayName }] else [] end),
+      labels: [(.labels.nodes // [])[] | { name: .name }],
+      milestone: (if .project then { title: .project.name } else null end),
       comments: [.comments.nodes[] | {
         body: .body,
         createdAt: .createdAt,

package/scripts/forge/linear/recently-closed.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: recently-closed (Linear via GraphQL API)
+# forge-executable: curl
 # Input: CODEV_LINEAR_TEAM, CODEV_SINCE_DATE (optional, ISO date)
 # Output: JSON [{number, title, url, labels, createdAt, closedAt}]
 set -e

package/scripts/forge/linear/user-identity.sh

@@ -1,5 +1,6 @@
 #!/bin/sh
 # Forge concept: user-identity (Linear via GraphQL API)
+# forge-executable: curl
 # Output: plain text display name
 set -e
 

package/skeleton/.claude/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY.
+description: AI image generation via Gemini with optional async providers. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires the API key for the selected provider.
 ---
 
 # generate-image - AI Image Generation
@@ -22,6 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
+-p, --provider <name>      Provider name (default: gemini)
 ```
 
 ## Aspect ratios
@@ -43,3 +44,40 @@ codev generate-image prompt.txt -o result.png    # Prompt from .txt file
 - Prompt can be a `.txt` file path (auto-detected by extension)
 - Reference images must exist on disk
 - Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable
+
+## Alternative provider: Atlas Cloud
+
+`-p atlas` generates through Atlas Cloud, which serves the same Nano Banana Pro
+model over a submit-then-poll REST API. Useful when a Google AI Studio key is
+not available. Requires `ATLASCLOUD_API_KEY`; the default provider is unchanged.
+
+```bash
+codev generate-image "A sunset over mountains" -p atlas -a 16:9
+```
+
+Measured differences on that path:
+
+- `-a/--aspect` works (`1:1` returns 1024x1024, `16:9` returns 1376x768).
+- `-r/--resolution` has no equivalent field; a note is printed and the model's
+  default resolution comes back.
+- `--ref` is not supported (text-to-image only) and exits with an error rather
+  than silently ignoring the images.
+- The model returns JPEG, so the output file is named after its actual bytes
+  instead of writing JPEG into the default `output.png`.
+
+## MuAPI provider
+
+`-p muapi` uses MuAPI's Nano Banana Pro endpoint with the same aspect-ratio and
+resolution controls. Set `MUAPI_API_KEY` (or `MU_API_KEY`) using the [MuAPI
+access keys page](https://muapi.ai/access-keys). Reference images are uploaded
+to MuAPI and sent to the edit endpoint; returned media is downloaded only over
+HTTPS.
+
+```bash
+codev generate-image "A sunset over mountains" -p muapi -a 16:9
+codev generate-image "Keep the subject, change the lighting" -p muapi --ref subject.png
+```
+
+The provider submits a job, polls the [MuAPI image API](https://muapi.ai/ai-image-api),
+and writes the returned image locally. Polling and individual requests are
+bounded, and the API key is never sent to the returned media host.

package/skeleton/.codex/skills/generate-image/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: generate-image
-description: AI image generation via Gemini. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires GEMINI_API_KEY or GOOGLE_API_KEY.
+description: AI image generation via Gemini with optional async providers. Use when the user wants to generate, create, or make an image, or when you need to create visual assets like logos, diagrams, or illustrations. Requires the API key for the selected provider.
 ---
 
 # generate-image - AI Image Generation
@@ -22,6 +22,7 @@ Note: this is a `codev` subcommand, not standalone.
 -r, --resolution <res>     Resolution: 1K, 2K, 4K (default: 1K)
 -a, --aspect <ratio>       Aspect ratio (default: 1:1)
 --ref <image>              Reference image (repeatable, max 14)
+-p, --provider <name>      Provider name (default: gemini)
 ```
 
 ## Aspect ratios
@@ -43,3 +44,40 @@ codev generate-image prompt.txt -o result.png    # Prompt from .txt file
 - Prompt can be a `.txt` file path (auto-detected by extension)
 - Reference images must exist on disk
 - Requires `GEMINI_API_KEY` or `GOOGLE_API_KEY` environment variable
+
+## Alternative provider: Atlas Cloud
+
+`-p atlas` generates through Atlas Cloud, which serves the same Nano Banana Pro
+model over a submit-then-poll REST API. Useful when a Google AI Studio key is
+not available. Requires `ATLASCLOUD_API_KEY`; the default provider is unchanged.
+
+```bash
+codev generate-image "A sunset over mountains" -p atlas -a 16:9
+```
+
+Measured differences on that path:
+
+- `-a/--aspect` works (`1:1` returns 1024x1024, `16:9` returns 1376x768).
+- `-r/--resolution` has no equivalent field; a note is printed and the model's
+  default resolution comes back.
+- `--ref` is not supported (text-to-image only) and exits with an error rather
+  than silently ignoring the images.
+- The model returns JPEG, so the output file is named after its actual bytes
+  instead of writing JPEG into the default `output.png`.
+
+## MuAPI provider
+
+`-p muapi` uses MuAPI's Nano Banana Pro endpoint with the same aspect-ratio and
+resolution controls. Set `MUAPI_API_KEY` (or `MU_API_KEY`) using the [MuAPI
+access keys page](https://muapi.ai/access-keys). Reference images are uploaded
+to MuAPI and sent to the edit endpoint; returned media is downloaded only over
+HTTPS.
+
+```bash
+codev generate-image "A sunset over mountains" -p muapi -a 16:9
+codev generate-image "Keep the subject, change the lighting" -p muapi --ref subject.png
+```
+
+The provider submits a job, polls the [MuAPI image API](https://muapi.ai/ai-image-api),
+and writes the returned image locally. Polling and individual requests are
+bounded, and the API key is never sent to the returned media host.

package/skeleton/protocols/air/prompts/pr.md

@@ -18,7 +18,8 @@ Open the PR with the review embedded in its body, optionally run CMAP, and notif
 The body must carry `Closes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a partial fix uses `Refs #<N>` or `Part of #<N>` instead. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
-gh pr create --title "[Air #<N>] feat: <brief description>" --body "$(cat <<'EOF'
+export CODEV_PR_TITLE="[Air #<N>] feat: <brief description>"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the feature>
@@ -44,8 +45,12 @@ Closes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 <anything the reviewer should focus on, or "Standard implementation — no special concerns">
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Optional CMAP review
 
 CMAP is your judgement call for AIR. Skip it for simple changes (config, small UI); run it for features touching core logic or several modules:

package/skeleton/protocols/aspir/prompts/review.md

@@ -44,7 +44,8 @@ The review's `## Architecture Updates` and `## Lessons Learned Updates` sections
 The PR body must carry `Closes #<N>` (feature) or `Fixes #<N>` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #<N>` or `Part of #<N>` instead, leaving the issue open for the follow-up.
 
 ```bash
-gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
+export CODEV_PR_TITLE="[Spec {{project_id}}] {{title}}"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 [what was implemented]
 
@@ -63,8 +64,12 @@ codev/specs/{{artifact_name}}.md
 codev/reviews/{{artifact_name}}.md
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Signals
 
 - Review document complete:

package/skeleton/protocols/bugfix/prompts/pr.md

@@ -16,7 +16,8 @@ Open the PR, run CMAP review on it, address feedback, and hand off to the archit
 The PR body must carry `Fixes #<N>` for the driving issue — one per issue if several — so GitHub auto-closes it on merge. **Exception:** a PR that only partially addresses the issue uses `Refs #<N>` or `Part of #<N>` instead, leaving it open for the follow-up. Substitute the real number for `<N>`; leave no `{{...}}` tag or `<N>` placeholder in the committed body.
 
 ```bash
-gh pr create --title "Fix #<N>: <brief description>" --body "$(cat <<'EOF'
+export CODEV_PR_TITLE="Fix #<N>: <brief description>"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 
 <1-2 sentence description of the bug and fix>
@@ -38,8 +39,12 @@ Fixes #<N>  <!-- Substitute <N>; use "Refs #<N>" for a partial fix -->
 - [ ] All tests pass
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Run CMAP review
 
 BUGFIX runs its own 3-way consultation on the PR (porch does not do it for you). Dispatch all three in the background:

package/skeleton/protocols/bugfix/protocol.md

@@ -27,7 +27,8 @@ refactor surrounding code, fix unrelated bugs (file separate issues), or add fea
 [Bugfix #42] Test: regression for unencoded username
 ```
 
-**PR** — open with `gh pr create`, body carrying Summary, Root Cause, Fix and Test Plan plus
+**PR** — open with the `pr-create` forge concept command the PR-phase prompt hands you (`gh
+pr create` on GitHub), body carrying Summary, Root Cause, Fix and Test Plan plus
 `Fixes #<N>` so the issue closes on merge. Run one CMAP pass (Gemini, Codex, Claude), record
 each verdict, and address or rebut every `REQUEST_CHANGES`. Notify the architect with the
 verdicts, then `porch done <id>` and wait.

package/skeleton/protocols/maintain/prompts/review.md

@@ -46,7 +46,8 @@ If the run was not tied to any issue, the `Closes` line can be omitted.
 ```bash
 git push origin HEAD
 
-gh pr create --title "[Maintain] Codebase maintenance run NNNN" --body "$(cat <<'PREOF'
+export CODEV_PR_TITLE="[Maintain] Codebase maintenance run NNNN"
+export CODEV_PR_BODY="$(cat <<'PREOF'
 ## Summary
 
 <2-3 bullet points of what was done>
@@ -67,8 +68,12 @@ Closes #<N>  <!-- Only if this run was triggered by a GitHub issue. Use "Refs #<
 - [x] Documentation links resolve
 PREOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Signals
 
 When PR is created:

package/skeleton/protocols/pir/prompts/review.md

@@ -108,13 +108,16 @@ git push
 PR_TITLE="<concise description of the change>"
 BRANCH="$(git branch --show-current)"
 
-gh pr create \
-  --base main \
-  --head "$BRANCH" \
-  --title "$PR_TITLE" \
-  --body-file codev/reviews/{{artifact_name}}.md
+export CODEV_PR_TITLE="$PR_TITLE"
+export CODEV_PR_BODY="$(cat codev/reviews/{{artifact_name}}.md)"
+export CODEV_PR_BASE=main
+export CODEV_PR_HEAD="$BRANCH"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It prints `{"number": <int>, "url": "<url>"}`. The inputs are **exported** so an inline override that spells `--title "$CODEV_PR_TITLE"` sees them too. The body goes in as an environment variable, not `--body-file` — read the created PR back and confirm the body arrived intact before moving on.
+
 **Verify the PR body contains `Fixes #{{issue.number}}`** (it should — the review file has it at the top). If somehow missing, edit and re-apply:
 
 ```bash
@@ -154,7 +157,7 @@ For any `REQUEST_CHANGES`:
 
 1. Read the finding in full (`codev/projects/{{project_id}}-*/{{project_id}}-<model>.txt`).
 2. **Assess it honestly:**
-   - **Real defect** (correctness / cancellation / security / data-loss): fix it in code, add a regression test that fails without the fix, commit + push (the PR updates automatically — no new `gh pr create`). Then document the finding, your fix, and the pinning test in the review file's **"Things to Look At During PR Review"** section.
+   - **Real defect** (correctness / cancellation / security / data-loss): fix it in code, add a regression test that fails without the fix, commit + push (the PR updates automatically — no second PR). Then document the finding, your fix, and the pinning test in the review file's **"Things to Look At During PR Review"** section.
    - **False positive / out of scope**: write a brief rebuttal in that same section explaining why no change is warranted.
 3. Do **not** re-run `porch done` expecting another consultation pass — `max_iterations: 1` means it will not re-review. Proceed to step 7.
 
@@ -257,7 +260,7 @@ Together with the `--pr` record from step 4a and the `--merged` record from step
   ```
 - Resolve conflicts (do NOT use destructive shortcuts)
 - Force-push with lease: `git push --force-with-lease`
-- Re-run `gh pr create`
+- Re-run the PR creation command from step 4
 
 **If porch's consultation fails (e.g., model unavailable):**
 - `porch done` will report the failure. Inspect `codev/projects/{{project_id}}-*/{{project_id}}-<model>.txt` for the failure details.

package/skeleton/protocols/spir/prompts/review.md

@@ -44,7 +44,8 @@ The review's `## Architecture Updates` and `## Lessons Learned Updates` sections
 The PR body must carry `Closes #<N>` (feature) or `Fixes #<N>` (bug) for the driving issue — one keyword per issue if several — so GitHub auto-closes on merge. **Exception:** a PR that only partially addresses its issue uses `Refs #<N>` or `Part of #<N>` instead, leaving the issue open for the follow-up.
 
 ```bash
-gh pr create --title "[Spec {{project_id}}] {{title}}" --body "$(cat <<'EOF'
+export CODEV_PR_TITLE="[Spec {{project_id}}] {{title}}"
+export CODEV_PR_BODY="$(cat <<'EOF'
 ## Summary
 [what was implemented]
 
@@ -63,8 +64,12 @@ codev/specs/{{artifact_name}}.md
 codev/reviews/{{artifact_name}}.md
 EOF
 )"
+
+{{pr_create_command}}
 ```
 
+The command above is your forge's `pr-create` concept, substituted by porch (`gh pr create` by default). It takes `CODEV_PR_TITLE` / `CODEV_PR_BODY` — optionally `CODEV_PR_BASE`, `CODEV_PR_HEAD`, `CODEV_PR_REPO` — from the environment, which is why they are exported rather than prefixed onto the command line: an inline override that spells `--title "$CODEV_PR_TITLE"` needs them set in the calling shell too. It prints `{"number": <int>, "url": "<url>"}`.
+
 ## Signals
 
 - Review document complete:

package/skeleton/resources/commands/agent-farm.md

@@ -391,11 +391,36 @@ Sends text to a builder's terminal. Useful for:
 
 - **delivered** — the message was written to the recipient's prompt after a clean render-gate pass (an empty, render-verified prompt).
 - **held** — the prompt was not clear, so the message is persisted in Tower's durable mailbox and **delivers automatically** the moment the recipient's prompt is clean (after a submit, on output quiescence, or a poll backstop). The response carries a **why-held reason** and a mailbox id:
-  - `busy` — a draft, menu, dialog, or wrapper screen occupies the prompt;
+  - `busy` — the prompt is occupied. `afx inbox` qualifies it with the gate's own detail:
+    `busy:user-text` (a draft, menu, dialog, or wrapper screen), `busy:recent-input` (the
+    terminal received input within the last fraction of a second — a keystroke, a click, or an
+    ungated `--interrupt`/`--escape` write — so the composer may be changing under the gate; it
+    clears by itself a moment after the input stops), `busy:composer-redraw` (the composer is
+    empty but its rendered region moved a moment ago — a turn-end redraw, a rotating
+    placeholder, a resize; also self-clearing, about a quarter second after it stops moving), or
+    `busy:no-region-end` / `busy:no-composer-marker` (the classifier could not verify the
+    composer at all — the one hold class that does NOT clear on its own);
   - `no-profile` — the target app has no render-gate classifier profile (only `claude`, `codex`, and `agy` are modeled);
   - `no-live-pty` — the recipient agent has no live terminal right now (it delivers when the agent respawns — rows address agents, not PTYs).
 
-A held message is **never force-injected** onto a busy line: a message body is only ever written to a verified-empty prompt, so it cannot fuse with a half-typed draft, and held rows survive Tower restart/shutdown (no shutdown force-flush). See held mail with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`. `--interrupt` is the explicit, deliberate bypass: it interrupts the agent and writes without holding (unchanged semantics).
+**A recipient that is simply TALKING does not hold mail** (Issue #1664). claude and codex accept
+input during a turn and queue it for the next one, so a message written onto their empty composer
+mid-turn is safe and lands as one message when the turn ends — the gate waits only on the
+*composer*, never on the spinner or the streaming transcript above it. Before that, mail queued
+behind whole turns: measured over 24 h, 227 deliveries waited more than 2 s, averaging 54 s and
+peaking at 561 s.
+
+A held message is **never force-injected** onto a busy line: a message body is only ever written to a verified-empty prompt, so it cannot fuse with a draft the gate can see, and held rows survive Tower restart/shutdown (no shutdown force-flush). Two signals make a draft visible (Issue #1473) — the composer classifier reads it off the rendered screen, and every write that reaches the PTY **through Tower** (browser and VS Code keystrokes, the terminal input API, an ungated `--interrupt`/`--escape`) is observed there — whatever survives the terminal-reply filter bumps an input counter the gate folds into its change token, so even a keystroke the app has not echoed yet holds the message, while a chunk that is nothing but a DA/DSR/CPR answer moves nothing. **`afx attach` is the one exception:** it pipes your keystrokes straight to the shellper socket, never through Tower's `PtySession.write()`, so they move no counter — a draft typed under `afx attach` is seen only once the app has echoed it and the classifier can read it off the screen. See held mail with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`. `--interrupt` is the explicit, deliberate bypass: it interrupts the agent and writes without holding (unchanged semantics).
+
+**How a body is typed (Issue #1567):** a frame under 4 lines and at most 256 bytes is one write plus
+Enter, as always. Anything longer is written as **one explicit bracketed paste** (`ESC[200~ … ESC[201~`,
+in ≤512-byte pieces 5 ms apart) with the Enter as a separate write after a short settle. This is the fix
+for the delivery-side head loss where a >1 KB single write was split by the PTY input queue and the
+recipient's paste heuristic discarded the first chunk (only the tail arrived, with `delivered` at the
+sender). While it sits in the composer, claude shows the paste as `[Pasted text #N +M lines]` and codex
+as `[Pasted Content N chars]`; the echo verification behind the `(unverified — …)` suffix accepts a new
+placard as well as the header, so a correct long delivery is reported verified. agy keeps the older
+line-by-line shape (also chunked) because its paste handling has not been measured.
 
 **Examples:**
 
@@ -432,7 +457,7 @@ afx inbox dismiss <id> [options]
 | `ID` | Mailbox row id (pass to `show` / `dismiss`) |
 | `AGE` | How long the message has been held (`5s`, `3m`, `2h`, `1d`) |
 | `REASON` | Why-held: `busy`, `no-profile`, or `no-live-pty`; a trailing `!` marks a row past the escalation age |
-| `FROM → TO` | Sender → recipient agent |
+| `FROM → TO` | Sender → recipient agent. An architect sender carries its name (`architect:main`); the column is sized to its content, so long ids are never truncated |
 | `WORKSPACE` | Owning workspace |
 
 **Options:**