@sabaiway/agent-workflow-kit 1.48.0 → 1.49.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.49.0 — Honesty/robustness bundle: refresh EROFS stated skip · settings integer-overflow parity (AD-056)
+
+A small **honesty/robustness** release (kit MINOR carrying the two bridge PATCH bumps in-tarball —
+codex-cli-bridge 2.7.1 + antigravity-cli-bridge 2.6.1; engine 1.17.0 / memory 2.3.0 unchanged; lineage
+head stays `2.0.0`). Two kit/bridge fixes ship here (a third, repo-only dispatcher fix, rides the same
+commit); all three share one theme: **a blocked environment must produce a STATED degrade, never a
+false red — and a real failure stays loud.**
+
+- **Refresh under a read-only skills dir is a stated skip, not a false failure.** Under the harness
+  session sandbox `~/.claude/skills` is read-only, yet `--refresh-placed` re-syncs even at the current
+  version (repair-on-rerun). That write EROFSed into the generic catch → *"could not refresh — … recover
+  with setup"*, though both versions were already current AND `setup` hits the same read-only dir. It now
+  reports a new **`skipped-readonly`** outcome (exit 0): it names the current version, states the re-sync
+  was skipped/incomplete, and names the read-only cause — never claiming a re-sync ran or file integrity
+  (a partial copy may precede the block). Only a read-only-class write failure at the copy-write boundary,
+  at an equal version, degrades; a read-side / source-side / `linkWrappers` / real-I/O failure, or a
+  version-**behind** refresh, stays a loud *could not refresh* (its recovery pointing at a writable
+  rerun). The opt-in `setup` placement lane keeps its loud failure. Any drift persists until a writable
+  rerun (converge-on-re-run).
+- **Settings integer validation is now shell↔JS exact (Issue-012, Resolved).** The four bridge wrappers'
+  shared `aw_settings_valid` integer arms did `(( 10#$v … ))`, which wraps modulo 2^64 on a 19+ digit
+  string — the shell **accepted** `18446744073709551916` (2^64+300) while the kit's `settingValueValid`
+  (safe-integer) **rejected** it. A shared overflow-safe `aw_int_in_range` helper (byte-identical across
+  all four wrappers) strips leading zeros then rejects on a digit count exceeding the max's — never
+  running arithmetic on a huge string. A leading-zero **in-range** value (e.g. `000…086400`) still
+  passes on both sides; the value is pinned by a new behavioral shell↔JS parity test.
+
 ## 1.48.0 — Family-owned neutral ack store + read-prompt-economy hook lane (AD-055, the CLAUDE-CODE-HARNESS-FRICTION cluster)
 
 A **feature** release (kit-only — engine 1.17.0, memory 2.3.0, bridges 2.7.0/2.6.0 unchanged) that

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.48.0'
+  version: '1.49.0'
 ---
 
 # agent-workflow-kit

package/bridges/antigravity-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: antigravity-cli-bridge
 description: Delegate work to Google's Antigravity CLI (`agy`) — the successor to Gemini CLI — to reach Gemini, Claude, and GPT-OSS models under a Google AI Pro/Ultra subscription from the terminal. Use when the user wants to run a headless `agy` prompt, hand a focused task or second-opinion review to `agy`, install or authenticate Antigravity CLI, check or economise its quota/models, bridge project context into `agy`, set up a second delegated-execution backend beside Codex, or troubleshoot `agy` flags, models, auth, conversations, or its no-JSON headless behaviour.
 metadata:
-  version: '2.6.0'
+  version: '2.6.1'
 ---
 
 # antigravity-cli-bridge

package/bridges/antigravity-cli-bridge/bin/agy-review.sh

@@ -132,12 +132,22 @@ aw_settings_known() {
     *) return 1 ;;
   esac
 }
+aw_int_in_range() {
+  # All-digits $1 vs [min,max] WITHOUT 64-bit wrap (Issue-012): strip leading zeros, then a longer
+  # digit count than max's is unconditionally out of range — never do the arithmetic on a huge string.
+  # A leading-zero in-range value still passes (its stripped count is small); all-zeros collapses to
+  # "0" (below min>=1). Mirrors the JS settingValueValid safe-integer bound, verified by parity test.
+  local n="${1#"${1%%[!0]*}"}" min="$2" max="$3"
+  n="${n:-0}"
+  (( ${#n} > ${#max} )) && return 1
+  (( n >= min && n <= max ))
+}
 aw_settings_valid() {
   local k="$1" v="$2" int_re='^[0-9]+$' dur_re='^[0-9]+(\.[0-9]+)?[smhd]$' zero_re='^0+(\.0+)?[smhd]$'
   case "$k" in
     CODEX_SERVICE_TIER) [[ "$v" == "priority" ]] ;;
-    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 86400 )) ;;
-    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 100000000 )) ;;
+    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 86400 ;;
+    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 100000000 ;;
     AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
     AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
     *) return 1 ;;
@@ -189,6 +199,14 @@ aw_apply_settings() {
       fi
       continue
     fi
+    # Normalize an all-digit (integer) value to DECIMAL before export: a leading-zero value the integer
+    # arms legitimately accept (000…086400 == 86400) would otherwise read as OCTAL in downstream Bash
+    # arithmetic ("value too great for base"). Strip leading zeros, floor "0"; enum/duration (non-digit)
+    # and boolean 0/1 are unaffected.
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+      value="${value#"${value%%[!0]*}"}"
+      value="${value:-0}"
+    fi
     export "$key=$value"
   done
   return 0
@@ -199,7 +217,7 @@ DEFAULT_AGY_REVIEW_MODEL="Gemini 3.1 Pro (High)"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by agy-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="agy"
-AW_BRIDGE_VERSION="2.6.0"
+AW_BRIDGE_VERSION="2.6.1"
 # `-` not `:-` so an EXPLICIT empty AGY_MODEL= survives (drop --model, use settings.json — agy.sh:52).
 AGY_MODEL="${AGY_MODEL-$DEFAULT_AGY_REVIEW_MODEL}"
 # Frontier review models. ANY model is allowed; a sub-frontier one only earns a soft, silenceable warning.

package/bridges/antigravity-cli-bridge/bin/agy-review.test.mjs

@@ -994,8 +994,9 @@ describe('agy-review.sh — settings surface ⟷ manifest (D6, manifest-pinned)'
       assert.ok(arm, `no validation arm for ${s.key}`);
       if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
       if (s.kind === 'integer') {
-        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
-        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+        // Issue-012 refactor: min/max are pinned as the aw_int_in_range helper's positional bounds
+        // (`aw_int_in_range "$v" <min> <max>`) — the overflow-safe range check replaced raw arithmetic.
+        assert.match(arm[1], new RegExp(`aw_int_in_range "\\$v" ${s.min} ${s.max}\\b`), `${s.key}: min/max ${s.min}/${s.max} not pinned as the aw_int_in_range bounds`);
       }
       if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
       if (s.kind === 'duration') {

package/bridges/antigravity-cli-bridge/bin/agy.sh

@@ -99,12 +99,22 @@ aw_settings_known() {
     *) return 1 ;;
   esac
 }
+aw_int_in_range() {
+  # All-digits $1 vs [min,max] WITHOUT 64-bit wrap (Issue-012): strip leading zeros, then a longer
+  # digit count than max's is unconditionally out of range — never do the arithmetic on a huge string.
+  # A leading-zero in-range value still passes (its stripped count is small); all-zeros collapses to
+  # "0" (below min>=1). Mirrors the JS settingValueValid safe-integer bound, verified by parity test.
+  local n="${1#"${1%%[!0]*}"}" min="$2" max="$3"
+  n="${n:-0}"
+  (( ${#n} > ${#max} )) && return 1
+  (( n >= min && n <= max ))
+}
 aw_settings_valid() {
   local k="$1" v="$2" int_re='^[0-9]+$' dur_re='^[0-9]+(\.[0-9]+)?[smhd]$' zero_re='^0+(\.0+)?[smhd]$'
   case "$k" in
     CODEX_SERVICE_TIER) [[ "$v" == "priority" ]] ;;
-    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 86400 )) ;;
-    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 100000000 )) ;;
+    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 86400 ;;
+    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 100000000 ;;
     AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
     AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
     *) return 1 ;;
@@ -156,6 +166,14 @@ aw_apply_settings() {
       fi
       continue
     fi
+    # Normalize an all-digit (integer) value to DECIMAL before export: a leading-zero value the integer
+    # arms legitimately accept (000…086400 == 86400) would otherwise read as OCTAL in downstream Bash
+    # arithmetic ("value too great for base"). Strip leading zeros, floor "0"; enum/duration (non-digit)
+    # and boolean 0/1 are unaffected.
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+      value="${value#"${value%%[!0]*}"}"
+      value="${value:-0}"
+    fi
     export "$key=$value"
   done
   return 0

package/bridges/antigravity-cli-bridge/bin/agy.test.mjs

@@ -443,8 +443,9 @@ describe('agy.sh — settings surface ⟷ manifest (D6, manifest-pinned)', () =>
       assert.ok(arm, `no validation arm for ${s.key}`);
       if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
       if (s.kind === 'integer') {
-        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
-        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+        // Issue-012 refactor: min/max are pinned as the aw_int_in_range helper's positional bounds
+        // (`aw_int_in_range "$v" <min> <max>`) — the overflow-safe range check replaced raw arithmetic.
+        assert.match(arm[1], new RegExp(`aw_int_in_range "\\$v" ${s.min} ${s.max}\\b`), `${s.key}: min/max ${s.min}/${s.max} not pinned as the aw_int_in_range bounds`);
       }
       if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
       if (s.kind === 'duration') {

package/bridges/antigravity-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "antigravity-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "provides": ["review", "probe"],
   "roles": {
     "review": {

package/bridges/codex-cli-bridge/SKILL.md

@@ -2,7 +2,7 @@
 name: codex-cli-bridge
 description: Delegate work to the OpenAI Codex CLI (`codex`) under a ChatGPT subscription — run plan/instruction EXECUTION in a sandboxed workspace, or get a read-only ADVISORY review of a plan or working-tree diff — as a second delegated-execution backend beside Antigravity. Use when the user wants to hand a bounded coding task or plan to `codex exec`, get a second-opinion review from codex, install or authenticate Codex CLI, understand its sandbox/network/approval policy, drive codex efficiently from the main agent (exec vs review, resume, the commit boundary), bridge project context (`AGENTS.md`) into codex, or troubleshoot codex flags, models, auth, or its no-TTY headless behaviour.
 metadata:
-  version: '2.7.0'
+  version: '2.7.1'
 ---
 
 # codex-cli-bridge

package/bridges/codex-cli-bridge/bin/codex-exec.sh

@@ -112,12 +112,22 @@ aw_settings_known() {
     *) return 1 ;;
   esac
 }
+aw_int_in_range() {
+  # All-digits $1 vs [min,max] WITHOUT 64-bit wrap (Issue-012): strip leading zeros, then a longer
+  # digit count than max's is unconditionally out of range — never do the arithmetic on a huge string.
+  # A leading-zero in-range value still passes (its stripped count is small); all-zeros collapses to
+  # "0" (below min>=1). Mirrors the JS settingValueValid safe-integer bound, verified by parity test.
+  local n="${1#"${1%%[!0]*}"}" min="$2" max="$3"
+  n="${n:-0}"
+  (( ${#n} > ${#max} )) && return 1
+  (( n >= min && n <= max ))
+}
 aw_settings_valid() {
   local k="$1" v="$2" int_re='^[0-9]+$' dur_re='^[0-9]+(\.[0-9]+)?[smhd]$' zero_re='^0+(\.0+)?[smhd]$'
   case "$k" in
     CODEX_SERVICE_TIER) [[ "$v" == "priority" ]] ;;
-    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 86400 )) ;;
-    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 100000000 )) ;;
+    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 86400 ;;
+    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 100000000 ;;
     AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
     AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
     *) return 1 ;;
@@ -169,6 +179,14 @@ aw_apply_settings() {
       fi
       continue
     fi
+    # Normalize an all-digit (integer) value to DECIMAL before export: a leading-zero value the integer
+    # arms legitimately accept (000…086400 == 86400) would otherwise read as OCTAL in downstream Bash
+    # arithmetic ("value too great for base"). Strip leading zeros, floor "0"; enum/duration (non-digit)
+    # and boolean 0/1 are unaffected.
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+      value="${value#"${value%%[!0]*}"}"
+      value="${value:-0}"
+    fi
     export "$key=$value"
   done
   return 0

package/bridges/codex-cli-bridge/bin/codex-exec.test.mjs

@@ -1080,8 +1080,9 @@ describe('codex-exec.sh — settings surface ⟷ manifest (D6, manifest-pinned)'
       assert.ok(arm, `no validation arm for ${s.key}`);
       if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
       if (s.kind === 'integer') {
-        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
-        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+        // Issue-012 refactor: min/max are pinned as the aw_int_in_range helper's positional bounds
+        // (`aw_int_in_range "$v" <min> <max>`) — the overflow-safe range check replaced raw arithmetic.
+        assert.match(arm[1], new RegExp(`aw_int_in_range "\\$v" ${s.min} ${s.max}\\b`), `${s.key}: min/max ${s.min}/${s.max} not pinned as the aw_int_in_range bounds`);
       }
       if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
       if (s.kind === 'duration') {

package/bridges/codex-cli-bridge/bin/codex-review.sh

@@ -104,12 +104,22 @@ aw_settings_known() {
     *) return 1 ;;
   esac
 }
+aw_int_in_range() {
+  # All-digits $1 vs [min,max] WITHOUT 64-bit wrap (Issue-012): strip leading zeros, then a longer
+  # digit count than max's is unconditionally out of range — never do the arithmetic on a huge string.
+  # A leading-zero in-range value still passes (its stripped count is small); all-zeros collapses to
+  # "0" (below min>=1). Mirrors the JS settingValueValid safe-integer bound, verified by parity test.
+  local n="${1#"${1%%[!0]*}"}" min="$2" max="$3"
+  n="${n:-0}"
+  (( ${#n} > ${#max} )) && return 1
+  (( n >= min && n <= max ))
+}
 aw_settings_valid() {
   local k="$1" v="$2" int_re='^[0-9]+$' dur_re='^[0-9]+(\.[0-9]+)?[smhd]$' zero_re='^0+(\.0+)?[smhd]$'
   case "$k" in
     CODEX_SERVICE_TIER) [[ "$v" == "priority" ]] ;;
-    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 86400 )) ;;
-    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && (( 10#$v >= 1 && 10#$v <= 100000000 )) ;;
+    CODEX_HARD_TIMEOUT) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 86400 ;;
+    CODEX_REVIEW_MAX_TOTAL_BYTES) [[ "$v" =~ $int_re ]] && aw_int_in_range "$v" 1 100000000 ;;
     AGY_HARD_TIMEOUT) [[ "$v" =~ $dur_re && ! "$v" =~ $zero_re ]] ;;
     AGY_REVIEW_ALLOW_ADDDIR) [[ "$v" == "0" || "$v" == "1" ]] ;;
     *) return 1 ;;
@@ -161,6 +171,14 @@ aw_apply_settings() {
       fi
       continue
     fi
+    # Normalize an all-digit (integer) value to DECIMAL before export: a leading-zero value the integer
+    # arms legitimately accept (000…086400 == 86400) would otherwise read as OCTAL in downstream Bash
+    # arithmetic ("value too great for base"). Strip leading zeros, floor "0"; enum/duration (non-digit)
+    # and boolean 0/1 are unaffected.
+    if [[ "$value" =~ ^[0-9]+$ ]]; then
+      value="${value#"${value%%[!0]*}"}"
+      value="${value:-0}"
+    fi
     export "$key=$value"
   done
   return 0
@@ -172,7 +190,7 @@ DEFAULT_CODEX_EFFORT="xhigh"
 # Review-receipt identity (AD-038). AW_BRIDGE_VERSION mirrors this bridge's SKILL.md/capability.json
 # version (drift-guarded by codex-review.test.mjs against capability.json).
 AW_RECEIPT_BACKEND="codex"
-AW_BRIDGE_VERSION="2.7.0"
+AW_BRIDGE_VERSION="2.7.1"
 CODEX_MODEL="${CODEX_MODEL:-$DEFAULT_CODEX_MODEL}"
 CODEX_EFFORT="${CODEX_EFFORT:-$DEFAULT_CODEX_EFFORT}"
 # Generous hard cap for a slow xhigh review (subscription latency varies).

package/bridges/codex-cli-bridge/bin/codex-review.test.mjs

@@ -1020,8 +1020,9 @@ describe('codex-review.sh — settings surface ⟷ manifest (D6, manifest-pinned
       assert.ok(arm, `no validation arm for ${s.key}`);
       if (s.kind === 'enum') for (const v of s.values) assert.ok(arm[1].includes(`"${v}"`), `${s.key}: enum value '${v}' not pinned`);
       if (s.kind === 'integer') {
-        assert.match(arm[1], new RegExp(`>= ${s.min}\\b`), `${s.key}: min ${s.min} not pinned`);
-        assert.match(arm[1], new RegExp(`<= ${s.max}\\b`), `${s.key}: max ${s.max} not pinned`);
+        // Issue-012 refactor: min/max are pinned as the aw_int_in_range helper's positional bounds
+        // (`aw_int_in_range "$v" <min> <max>`) — the overflow-safe range check replaced raw arithmetic.
+        assert.match(arm[1], new RegExp(`aw_int_in_range "\\$v" ${s.min} ${s.max}\\b`), `${s.key}: min/max ${s.min}/${s.max} not pinned as the aw_int_in_range bounds`);
       }
       if (s.kind === 'boolean') assert.ok(arm[1].includes('"0"') && arm[1].includes('"1"'), `${s.key}: boolean 0/1 not pinned`);
       if (s.kind === 'duration') {

package/bridges/codex-cli-bridge/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "codex-cli-bridge",
   "kind": "execution-backend",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "provides": ["execute", "review"],
   "roles": {
     "execute": {

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.48.0",
+  "version": "1.49.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/setup.md

@@ -11,8 +11,13 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs [<backend>] [--bindir <pa
   runs as its fourth stamp-independent reconcile): refresh every bridge `setup` **already placed**
   from the kit's bundled copies + re-link its wrappers; an absent bridge is a stated skip (**never**
   placed), a placed bridge newer than the bundle is a stated skip naming the kit update (**never**
-  downgraded), and every outcome line is composed by the tool — paste verbatim. Does not combine
-  with `--dry-run`.
+  downgraded), and every outcome line is composed by the tool — paste verbatim. When the skills dir
+  is **read-only this session** and the placed bridge is already at the bundled version, the
+  equal-version re-sync it would run cannot write: that outcome is `skipped-readonly` — a **stated
+  skip** (exit 0, not a failure) naming the current version, the skipped/incomplete re-sync, and the
+  read-only cause; it never claims a re-sync ran, and any local drift persists until a writable rerun.
+  (A version-**behind** refresh blocked by the same read-only dir stays a loud `could not refresh`,
+  its recovery pointing at a writable rerun.) Does not combine with `--dry-run`.
 - `--help`, `-h` — usage.
 
 For each backend it:

package/references/modes/upgrade.md

@@ -31,14 +31,14 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    **Placed-bridge refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.** Run
    `node ${CLAUDE_SKILL_DIR}/tools/setup-backends.mjs --refresh-placed` and **paste its per-bridge
    output lines verbatim** — every outcome line is composed by the tool (*refreshed* / *already
-   current* / *skipped — not placed* / *could not refresh* + its recovery); you compose nothing
-   factual. It is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's
-   bundled copies and re-links its wrappers; an **absent** bridge is a stated skip, **never a first
-   placement** (placement stays the opt-in `${CLAUDE_SKILL_DIR}/references/modes/setup.md` — AD-009/AD-011 honesty intact), and a
-   placed bridge **newer** than the bundled copy is a stated skip naming the kit update (**never a
-   downgrade**). Like the other stamp-independent reconciles it runs on **every** upgrade —
-   including an equal-head one — with no lineage-head bump. A *could not refresh* line is
-   non-fatal: relay it plainly with its recovery and continue the upgrade.
+   current* / *skipped — not placed* / `skipped-readonly` / *could not refresh* + its recovery). It
+   is **refresh-only**: it refreshes a bridge **`setup` already placed** from this kit's bundled copies
+   and re-links its wrappers; an **absent** bridge is a stated skip, **never a first placement**
+   (placement stays the opt-in `${CLAUDE_SKILL_DIR}/references/modes/setup.md` — AD-009/AD-011 honesty intact), a placed bridge
+   **newer** than the bundle is a stated skip naming the kit update (**never a downgrade**), and
+   `skipped-readonly` is an equal-version re-sync a **read-only** skills dir blocked this session (a
+   stated skip, exit 0 — not a failure). Runs on **every** upgrade (equal-head too), no lineage-head
+   bump; a *could not refresh* line is non-fatal — relay it plainly with its recovery.
 
    **Agent-rules lens refresh — stamp-independent, same gate, BEFORE the equal-head short-circuit.**
    Run `node ${CLAUDE_SKILL_DIR}/tools/lens-region.mjs reconcile <project>/docs/ai/agent_rules.md`
@@ -56,7 +56,7 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    **NEVER writes** it (the file lives outside every kit tree — D2), so an unknown/retired key is
    flagged + preserved, never edited. Runs on **every** upgrade; exit 0 covers every outcome.
 4. **Equal-head exit — a real successful-exit report, not a bare stop.** If the stamp **equals** the head, the lineage is up to date — but step 3 (the stamp-independent reconciles) ran first and may have changed things, so this is a proper exit report, not a no-op:
-   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/verification-profile.json` profile was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/autonomy.json` declaration was *seeded* (the sparse defaults-equivalent note) or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/`, found it *already present*, or found an *old ADR layout — migration instructed*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
+   - **Report step 3's outcome in plain language** — for **each** pointer (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); whether the `docs/ai/orchestration.json` config was *seeded* (created from the template), had its onboarding note *refreshed*, was *already current*, or carried a *customized note that was preserved* (a user edit is never clobbered); whether the `docs/ai/gates.json` gate declaration was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/verification-profile.json` profile was *seeded* or was *already present* (preserved byte-for-byte); whether the `docs/ai/autonomy.json` declaration was *seeded* (the sparse defaults-equivalent note) or was *already present* (preserved byte-for-byte); whether the enforcement-script ensure *added* the `archive-decisions` pair to `scripts/`, found it *already present*, or found an *old ADR layout — migration instructed*; the **placed-bridge refresh** outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` / *could not refresh* + recovery); the **agent-rules lens** outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*); the **bridge-settings reconcile** outcome (paste the tool's line verbatim); and, for a hidden deployment, whether the hidden-mode footprint was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
    - **Render the mandatory Recommendations section — on this exit too, BEFORE the footer.** Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; show the raw tool block on request. The section is present-even-when-empty (with everything optimal the body is exactly `no recommendations — flow optimal.`) and VERDICT-FIRST — the composed verdict line renders from the frozen templates `{K} item(s) need attention` / `nothing is broken` / `{N} optional recommendation(s), apply any you want` / `optimality NOT attested — {M} probe check(s) skipped`. Then OFFER the consent-gated applies: the user picks items in plain language; surface each picked item's posture note, get the explicit confirm, then run EXACTLY the rendered one-liners (a HAND-APPLY item is never run by you) — the full lane in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Pinned order on this exit: Recommendations block → optional applies → report footer → the commit ask (the advisor/apply lane never lands after the commit ask).
    - **Live host/session facts are tool-composed only.** Any claim this report makes about the current host or session state — prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts — must trace to **live tool output** from **this session** (the lines you just composed, or a probe you ran this run); a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection. Full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`.

package/tools/doc-parity.mjs

@@ -36,6 +36,7 @@ import {
   VERDICT_SKIPS_TEMPLATE,
   ACKS_FILE,
 } from './recommendations.mjs';
+import { SKIPPED_READONLY } from './setup-backends.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -45,6 +46,7 @@ const AUTONOMY_DOCTOR_DOC = 'references/modes/autonomy-doctor.md';
 const RECOMMENDATIONS_DOC = 'references/modes/recommendations.md';
 const UPGRADE_DOC = 'references/modes/upgrade.md';
 const VELOCITY_DOC = 'references/modes/velocity.md';
+const SETUP_DOC = 'references/modes/setup.md';
 
 // A typed usage failure (exit 2) for the CLI parser — the codebase's typed-error idiom (no classes).
 const usageFail = (message) => Object.assign(new Error(message), { exitCode: 2 });
@@ -99,6 +101,11 @@ export const BINDINGS = Object.freeze([
   // (the incident's "mode-doc apply text stays in lockstep" acceptance as a mechanism, not prose).
   // Bound in BOTH docs that name the path (recommendations.md + velocity.md).
   valueBinding('acks-file', ACKS_FILE, ACKS_FILE, [RECOMMENDATIONS_DOC, VELOCITY_DOC]),
+  // The refresh read-only degrade outcome (REFRESH-EROFS-HONESTY / AD-056): the new skipped-readonly
+  // token must render in BOTH mode contracts that enumerate the placed-bridge refresh outcomes
+  // (setup.md owns --refresh-placed; upgrade.md pastes its lines) — a reworded doc dropping the
+  // outcome fails this pin plus the gate. The token tracks the exported SETUP constant.
+  valueBinding('refresh-skipped-readonly', SKIPPED_READONLY, SKIPPED_READONLY, [SETUP_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/fs-safe.mjs

@@ -17,7 +17,7 @@
 
 import {
   lstatSync, existsSync, mkdirSync, readdirSync, copyFileSync, readlinkSync, symlinkSync,
-  rmSync, unlinkSync,
+  rmSync, unlinkSync, readFileSync,
 } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 
@@ -68,6 +68,27 @@ export const assertContainedRealPath = (root, dest, deps = {}) => {
   rel.split(sep).filter(Boolean).reduce(walk, root);
 };
 
+// Read-only write-boundary tagging (REFRESH-EROFS-HONESTY / AD-056). A DESTINATION-side write failure
+// of the read-only class is TAGGED (err.readonlyWriteBoundary) so the refresh-only driver can classify
+// an equal-version repair-on-rerun that cannot write as a STATED skip — never a false red. The tag is
+// applied ONLY around the three write primitives, so a READ-side failure (bundle read / dir listing)
+// is never absorbed: the degrade classifies at the write boundary, not by a broad err.code sniff over
+// the whole copy. EROFS is destination-side by nature; mkdir/symlink write only the dest; an
+// EACCES/EPERM at copyFile (which also READS the source) is destination-provable ONLY when the source
+// is readable — else it is a source-side read failure that must stay loud.
+const READONLY_WRITE_ERRNOS = new Set(['EROFS', 'EACCES', 'EPERM']);
+export const isReadonlyWriteBoundary = (err) => Boolean(err && err.readonlyWriteBoundary);
+const throwTaggedReadonly = (err, primitive, src, readFile) => {
+  if (err && READONLY_WRITE_ERRNOS.has(err.code)) {
+    let destinationSide = err.code === 'EROFS' || primitive !== 'copyFile';
+    if (!destinationSide) {
+      try { readFile(src); destinationSide = true; } catch { destinationSide = false; }
+    }
+    if (destinationSide) err.readonlyWriteBoundary = true;
+  }
+  throw err;
+};
+
 // Recursive refresh copy. Guards every dest via assertContainedRealPath first, then:
 //   symlink src   → additive: skip if dest exists, else mirror the link target.
 //   directory src → mkdir -p dest, recurse.
@@ -80,20 +101,22 @@ export const copyTreeRefresh = (src, dest, root, deps = {}) => {
   const copyFile = deps.copyFile ?? copyFileSync;
   const readlink = deps.readlink ?? readlinkSync;
   const symlink = deps.symlink ?? symlinkSync;
+  const readFile = deps.readFile ?? readFileSync;
 
   assertContainedRealPath(root, dest, deps);
   const stat = lstat(src);
   if (stat.isSymbolicLink()) {
     if (exists(dest)) return;
-    symlink(readlink(src), dest);
+    const target = readlink(src); // read-side (a readlink failure is never tagged as a write boundary)
+    try { symlink(target, dest); } catch (err) { throwTaggedReadonly(err, 'symlink', src, readFile); }
   } else if (stat.isDirectory()) {
-    mkdir(dest);
+    try { mkdir(dest); } catch (err) { throwTaggedReadonly(err, 'mkdir', src, readFile); }
     for (const entry of readdir(src)) {
       copyTreeRefresh(join(src, entry), join(dest, entry), root, deps);
     }
   } else {
-    mkdir(dirname(dest));
-    copyFile(src, dest);
+    try { mkdir(dirname(dest)); } catch (err) { throwTaggedReadonly(err, 'mkdir', src, readFile); }
+    try { copyFile(src, dest); } catch (err) { throwTaggedReadonly(err, 'copyFile', src, readFile); }
   }
 };
 

package/tools/setup-backends.mjs

@@ -31,7 +31,7 @@ import { join, resolve, relative, dirname, isAbsolute } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import os from 'node:os';
 import { KNOWN_BACKENDS, detectBackend, detectBackends, resolveDir, guideFor, READY } from './detect-backends.mjs';
-import { copyTreeRefresh, linkManaged } from './fs-safe.mjs';
+import { copyTreeRefresh, linkManaged, isReadonlyWriteBoundary } from './fs-safe.mjs';
 import { validateManifest, readAuthoritativeVersion, UNSUPPORTED, INVALID } from './manifest/validate.mjs';
 import { compareSemver } from './semver-lite.mjs';
 
@@ -54,6 +54,12 @@ export const SETUP_STOP = 'SETUP_STOP';
 const stop = (message, fields = {}) =>
   Object.assign(new Error(`[agent-workflow-kit] ${message}`), { name: 'SetupStop', code: SETUP_STOP, ...fields });
 
+// A refresh-only outcome (REFRESH-EROFS-HONESTY / AD-056): an equal-version repair-on-rerun whose
+// write hit a READ-ONLY skills dir. A STATED skip (exit 0), never a false "could not refresh" — the
+// versions are already current and `setup` would hit the same read-only dir. Doc-parity binds this
+// token into references/modes/setup.md + upgrade.md so the mode contracts track the constant.
+export const SKIPPED_READONLY = 'skipped-readonly';
+
 // ── injectable fs ──────────────────────────────────────────────────────────────
 
 const fsDeps = (deps = {}) => ({
@@ -557,13 +563,42 @@ const refreshSkillOnly = (entry, deps = {}) => {
   const fresh = inspectSkillDir(entry, deps);
   if (fresh.action !== 'refresh') return { refreshed: false, drift: null };
   assertNoDowngrade(fresh, deps);
-  const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
-  return { refreshed: true, drift };
+  // D1b: version equality for the read-only degrade is decided from the APPLY-TIME fresh inspection's
+  // fields (never the stale pre-apply plan) — both versions KNOWN and equal; two unknowns are not equal.
+  // assertNoDowngrade just read the bundled manifest, so this read cannot throw here; a versionless
+  // manifest yields null (never "equal" → no false skip).
+  const bundledManifest = readBundledManifest(fresh.bundleDir, deps);
+  const bundledVersion = typeof bundledManifest.version === 'string' ? bundledManifest.version : null;
+  const placedVersion = readPlacedVersionSafe(fresh.skillDir, deps);
+  const currentEqual = bundledVersion !== null && placedVersion === bundledVersion;
+  try {
+    const drift = copyBridgeWithHonesty('refresh', fresh.bundleDir, fresh.skillDir, deps);
+    return { refreshed: true, drift };
+  } catch (err) {
+    // D1/D1a: ONLY a read-only WRITE-boundary failure at an EQUAL version is a repair-on-rerun that
+    // cannot run — a STATED skip, never a false "could not refresh". Every other failure stays loud
+    // (a read-side / source-side / EIO failure, or a version-behind upgrade, re-throws here).
+    if (currentEqual && isReadonlyWriteBoundary(err)) return { refreshed: false, skippedReadonly: true, version: bundledVersion };
+    throw err;
+  }
 };
 
 const NOT_PLACED_LINE = 'skipped — not placed (placement is opt-in: /agent-workflow-kit setup)';
 const stripPrefix = (message) => message.replace('[agent-workflow-kit] ', '');
 
+// The read-only degrade wording (D1). The STATED-skip line: version current + the re-sync
+// skipped/incomplete + the read-only cause + the residual — it never claims a re-sync RAN (that is
+// already-current's line) nor file integrity (a partial copy may have happened before the throw). The
+// FAILED line (a version-behind upgrade blocked by the same read-only dir) stays loud, but its
+// recovery points at a writable rerun — the in-session `setup` would hit the same read-only dir.
+const READONLY_RERUN_HINT = 're-run the refresh from a writable session (e.g. outside the read-only sandbox)';
+const skippedReadonlyLine = (name, version) =>
+  `  ${name}: already current${version ? ` (v${version})` : ''} — the re-sync was skipped/incomplete: ` +
+  `the skills directory is read-only this session (the tree may be PARTIALLY updated). Repair-on-rerun cannot ` +
+  `run here; any remaining drift persists until you ${READONLY_RERUN_HINT}.`;
+const readonlyRefreshFailedLine = (name, message) =>
+  `  ${name}: could not refresh — ${stripPrefix(message)}; the skills directory is read-only this session — ${READONLY_RERUN_HINT}`;
+
 // Refresh every ALREADY-PLACED bridge from the kit's bundled copies and re-link its wrappers (a newer
 // bridge can add one). One reported outcome per backend — never a crash; a per-backend STOP/error
 // becomes a `failed` result. `line` is the tool-composed sentence callers print VERBATIM (the agent
@@ -592,6 +627,11 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
         return { name: plan.name, outcome: 'failed', line: `  ${plan.name}: could not refresh — ${stripPrefix(plan.reason)}; recover with /agent-workflow-kit setup` };
       }
       const refresh = refreshSkillOnly(registryEntry(plan.name), deps);
+      // A read-only skills dir at an EQUAL version is a STATED skip (repair-on-rerun cannot run here) —
+      // never a false "could not refresh" and never a failure exit (D1/AD-056).
+      if (refresh.skippedReadonly) {
+        return { name: plan.name, outcome: SKIPPED_READONLY, line: skippedReadonlyLine(plan.name, refresh.version) };
+      }
       if (!refresh.refreshed) {
         return { name: plan.name, outcome: 'not-placed', line: `  ${plan.name}: ${NOT_PLACED_LINE}` };
       }
@@ -615,6 +655,11 @@ export const refreshPlacedBridges = (deps = {}, names = KNOWN_BACKENDS.map((b) =
       if (err.wouldDowngrade) {
         return { name: canonical, outcome: 'kept-newer', line: `  ${canonical}: skipped — ${stripPrefix(err.message)}` };
       }
+      // A read-only WRITE failure on a version-BEHIND (upgrade) refresh stays a loud failure — but the
+      // in-session "recover with setup" would hit the same read-only dir, so point at a writable rerun.
+      if (isReadonlyWriteBoundary(err)) {
+        return { name: canonical, outcome: 'failed', line: readonlyRefreshFailedLine(canonical, err.message) };
+      }
       return { name: canonical, outcome: 'failed', line: `  ${canonical}: could not refresh — ${stripPrefix(err.message)}; recover with /agent-workflow-kit setup` };
     }
   });