feat(sandbox): scoped agents provisioned by the checkpoint cycle

Completes the role model on the sandbox side, and closes the third failure of
the 2026-07/08 sessions: a refresh wiped hand-granted rights and nothing
recorded them, so the sandbox silently lost capabilities nobody had written down.

- Provisioned `ai_agent_sandbox_read` (36 rights) and
  `ai_agent_sandbox_sandbox_write` (44 rights) from test/scopes.ts.
  Verified functionally on the live sandbox: the reader reads and gets
  403 on invoice creation; the writer creates a draft and gets 403 on DELETE.
- checkpoint-provision.sh now re-creates both scoped agents after every
  refresh, so their rights come from code rather than from someone's memory.
  Failure to provision a scope warns instead of aborting the whole checkpoint.
- checkpoint-relink-env.sh points the write skill at the scoped writer key,
  falling back to the legacy single-user key so an older checkout still works.
  The write skill now operates as ai_agent_sandbox_sandbox_write (id 6).

Smoke-tested end to end after the credential swap: the promote pipeline
rehearses on the sandbox under the scoped writer, and `apply` still refuses
without a recorded human gate.

The redundant `ai_agent_prod_prod_write` login is documented as deliberate:
renaming a provisioned production credential means creating a second privileged
user and repointing the promote flow — churn for cosmetics.

Left behind in the sandbox: draft invoice id=19, a scope probe. It cannot be
deleted (no scope grants DELETE, which is the point) and the next refresh
reclaims it.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01VRShc4QhLLU73FLHx9vskh

.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-provision.sh

@@ -19,5 +19,18 @@ command -v deno >/dev/null || { echo "checkpoint-provision: deno not found (http
 echo ">>> launching provisionSandbox.ts — complete the admin login in the browser (use PROD admin creds)"
 ( cd "${ROOT}/test" && deno run --allow-all provisionSandbox.ts )
 
+# Scoped agents (test/scopes.ts). A refresh wipes every user, so they are
+# re-created here rather than granted by hand — the 2026-07 failure where a
+# refresh silently dropped hand-granted rights and nothing recorded it.
+if [[ -f "${ROOT}/test/provisionAiUser.ts" ]]; then
+  for scope in read sandbox-write; do
+    echo ">>> provisioning scoped sandbox agent: ${scope}"
+    ( cd "${ROOT}/test" \
+      && DOLIBARR_ADDRESS="${DOLIBARR_SANDBOX_URL:-https://erp-sandbox.arcodange.lab}" \
+         deno run --allow-all provisionAiUser.ts --scope "${scope}" --env sandbox ) \
+      || echo "   WARN: scoped provisioning failed for '${scope}' — check test/scopes.ts" >&2
+  done
+fi
+
 echo ">>> provisioning finished; relinking the write skill .env"
 exec "${SCRIPT_DIR}/checkpoint-relink-env.sh"

.claude/skills/dolibarr-sandbox-checkpoint/scripts/checkpoint-relink-env.sh

@@ -7,7 +7,11 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT="${ARCO_ROOT:-$(cd "${SCRIPT_DIR}/../../../.." && pwd)}"
 SB_URL="${DOLIBARR_SANDBOX_URL:-https://erp-sandbox.arcodange.lab}"
-KEY="${ROOT}/test/.ai_agent_sandbox.key"
+# Prefer the SCOPED writer (test/scopes.ts, `sandbox-write`); fall back to the
+# legacy single-user key so an older checkout keeps working. The scoped user is
+# what a refresh re-provisions, which is why it wins.
+KEY="${ROOT}/test/.ai_agent_sandbox_sandbox_write.key"
+[[ -s "${KEY}" ]] || KEY="${ROOT}/test/.ai_agent_sandbox.key"
 ENV="${ROOT}/.claude/skills/dolibarr-sandbox-write/.env"
 DOLW="${ROOT}/.claude/skills/dolibarr-sandbox-write/scripts/dol-write.sh"
 

test/scopes.ts

@@ -160,7 +160,14 @@ export const SCOPES: Readonly<Record<string, Scope>> = {
 
 export type ScopeName = keyof typeof SCOPES;
 
-/** Conventional login for a given scope + environment. One user per pair. */
+/**
+ * Conventional login for a given scope + environment. One user per pair.
+ *
+ * The scope name is kept verbatim, so `prod-write` on production reads
+ * `ai_agent_prod_prod_write`. Redundant, deliberately left alone: renaming a
+ * provisioned production credential means creating a second privileged user and
+ * repointing the promote flow — churn for cosmetics. Don't "fix" it.
+ */
 export function loginFor(scope: string, env: "sandbox" | "production"): string {
   return env === "sandbox" ? `ai_agent_sandbox_${scope.replace(/-/g, "_")}`
                            : `ai_agent_prod_${scope.replace(/-/g, "_")}`;