row 238: stack-release's sso-config first step carries --instance NAME on a named instance (#1744)

Lands Launchpad's round 3 candidate, manifest 1bf831f3 (4c90099ea on launchpad/row238-r4, base
c515273db), approved by Webby (29956, rev 2717). Three paths: scripts/stack-release.sh, packages/cli/tests/
stack-release.test.mjs and docs/TOOLS.md. It is row 200's follow-up N1. Round 3 only merges docs/TOOLS.md
onto the row 240 landing: the landed blob plus the one hunk at :599. The 3-path patch-id, b9d0bb0ee3c7,
is the same in all three rounds, and stack-release.sh stays 100755.

Evidence: Launchpad's slot run on round 2, 2afbfbb01: stack-release.test.mjs 196/0 (sage-1794). Sage's
combined gate with row 228 on c515273db plus both rows' paths (07:11:30Z to 07:23:34Z): packages/seat 165 pass, 0 fail; packages/cli 640 pass, 0 fail; all ten scripts/test-*.sh 585 pass, 0 fail (out/, run.log). Row 238's mutant, the sso-config first step dropping --instance NAME, was killed (2 fails), survived: none, and stack-release.sh was restored to its blob.
`queue review verify-commit 238` matches the manifest on all 3 paths. Round 1's N1 stays on the #1744
carry list.

docs/TOOLS.md

@@ -599,7 +599,8 @@ error. Before anything stops, a run whose Console flags hold `--sso` refuses
 `sso-target` for a target Console without it, `sso-config` when the target's own
 `checkConsole` refuses the config's `console` key (or there is none, in which
 case, from another copy, it names the first step: activate the target without
-`--sso`, then write `console.sso`), and `sso-slot` for each provider's slot file
+`--sso`, then write `console.sso`; on a named instance both commands carry
+`--instance NAME`), and `sso-slot` for each provider's slot file
 that is missing, a symlink, not a regular file, not owned by this uid, has group
 or other bits, resolves inside the repository or the copies, or is empty. It
 uses `lstat`, `stat` and `realpath` on the slot and never reads it. `--plan`

packages/cli/tests/stack-release.test.mjs

@@ -1683,6 +1683,14 @@ test('T57 row 200: activate --sso, its refusals before any stop, and the rollbac
   assert.ok(stepText(a).includes(`Z drop --sso; ${B}'s Console does not support it, so the Console flags come from ${set}/${show}\n`));
   await noLeak(a);
  });
+ await t.test('row 238 (#1744): on a named instance the sso-config first step names --instance NAME in both commands',async(t)=>{
+  const e=await mk(t),a=await named(e,'alpha');await seed(a);
+  assert.equal(JSON.parse(readFileSync(a.cfg,'utf8')).console,undefined);
+  await refused(a,['activate',C1,'acme','--sso'],'sso-config',`${C1}'s Console would refuse its --sso start: there is no console.sso in the system config; activate ${C1} --instance alpha without --sso first, then write console.sso, then run activate ${C1} --instance alpha --sso`);
+  const out=await planOnly(a,3,'activate',C1,'acme','--sso');
+  assert.ok(out.includes(`refuses sso-config: ${C1}'s Console would refuse its --sso start: there is no console.sso in the system config; activate ${C1} --instance alpha without --sso first, then write console.sso, then run activate ${C1} --instance alpha --sso`),out.join('\n'));
+  await noLeak(a);
+ });
 });
 
 // --- rehearse (D2, row 163; the brief's "Stack rehearsal on a scratch root") ---

scripts/stack-release.sh

@@ -929,12 +929,13 @@ sso_checks() {
     sso_supported || { check_refuse sso-target "$TO's Console does not support --sso"; return 0; }
     local cfg="${MOSAIC_CONFIG:-$HOME/.config/mosaic-dev/config.json}" out id slot path why
     # N4 (webby-0019, sage-1403): a pre-phase-1 loader refuses a console key, so with the key not yet
-    # written and the stack on another copy, the first step is the re-pin without --sso.
-    local first=""
+    # written and the stack on another copy, the first step is the re-pin without --sso. On a named
+    # instance both commands carry --instance NAME (row 238).
+    local first="" inst="${INSTANCE_FLAGS[*]:+ ${INSTANCE_FLAGS[*]}}"
     if ! out="$(node -e "$SSO_JS" -- "$COPIES/$TO" "$cfg" 2>&1)"; then
         out="${out%%$'\n'*}"
         [ "$out" != "there is no console.sso in the system config" ] || [ "$P_COPY" = "$TO" ] ||
-            first="; activate $TO without --sso first, then write console.sso, then run activate $TO --sso"
+            first="; activate $TO$inst without --sso first, then write console.sso, then run activate $TO$inst --sso"
         check_refuse sso-config "$TO's Console would refuse its --sso start: $out$first"
         return 0
     fi