stack/agents/darkwing/work/queue-180/BUILD.md

Row 180: activation ids and plan-mode refusals

Brief: "# Brief: activation ids and plan-mode refusals (row A)" in docs/plans/2026-10-20_stack-release-after-window.md (blob aafa471ae, c7f3beb17). Gitea #1678, Vikunja P19 391, plus N1 and N2 from Dewey's row 176 review. Owner Darkwing, reviewer Dewey, gate owner Sage.

Files

File	What
build.patch	the change, git diff 7f519242e over the five paths below
candidate-manifest.sha256	one line per changed path

• Base: 7f519242e for round 2 (sage-1171). Round 1 was built on c7f3beb17. No commit in c7f3beb17..7f519242e touches the five paths, and the patch is byte for byte the same on either base. At 03:29Z, refactor was c7421cabd, and the two commits after 7f519242e touch only plans and SESSIONS.
• Changed: scripts/stack-release.sh, scripts/webui-service.sh, packages/cli/tests/stack-release.test.mjs, packages/webui/tests/service.test.mjs, docs/TOOLS.md. These are the brief's touched files, with nothing else.
• Digests and patch-id: see "Candidate" at the end.

Item 1: activation ids within one second (P19 391)

next_activation() takes the UTC second once and tries the base id <second>-<TO:0:12>, then -1 through -9. A name is free when none of these exist:

• $STATE/stack-rollback/<id>
• $DATA/backups/stack/<id>
• $DATA/bus.post-attempt-<second><suffix>

It sets ACT and POST from the same suffix. With all ten taken it refuses capture-failed ("every activation id for X is taken; nothing was stopped") and clears ACT and POST first, so the refused log line has activation null. new_activation() calls it and sets RS, and do_adopt calls it in place of its own date line. All three callers run after lock(): activate and rollback reach it only past the --plan exit, and adopt and pm-on lock first.

Why a suffix and not milliseconds. The brief allowed either. With milliseconds, the brief's pinned-clock test can't produce two runs in one stamp, and the shape of every id would change. With the suffix, the base form is still a whole id, and lexical order is still time order: X < X-1 < ... < X-9 < the next second. Sage approved it (sage-1155).

A side effect: the base code took POST from a second date call, which could land in the next second from ACT. POST now uses ACT's second.

--restore (:78) now takes ^[0-9]{8}T[0-9]{6}Z-[0-9a-f]{12}(-[1-9])?$.

Check (b): everything that builds or parses an activation id (sage-1155)

git grep over the tree outside v1/, agents/ and docs/plans for stack-active, stack-activation-log, stack-rollback, backups/stack and post-attempt finds three files: scripts/stack-release.sh, its test and docs/TOOLS.md. Line numbers are at the candidate.

Hit	What it does with the id	Result
stack-release.sh:50 log_line	writes ACT into each log line	fine, writes only
:100-110 read_pointer	checks typeof p.activation==="string", sets P_ACT	fine; P_ACT is read nowhere else
:116 write_pointer	writes ACT	fine
:128 interrupted()	keys open runs on the exact activation string	fine; a suffixed id is a distinct key
:331 backup_store, :355 restore_store	take the backup dir path, never parse it	fine
:78 --restore regex	parsed the old form only	changed, takes both
:827, :883 do_rollback --restore path	builds $DATA/backups/stack/$RESTORE	fine, a name only
test :378 T1	^\d{8}T\d{6}Z-<B12>$ on an adopt id	fine, one run, no collision
test :558 T13	post-attempt name \d{8}T\d{6}Z	fine, one run
test :678 T24	capture-failed message with the base id	fine, the base form is still first
test :274 posts()	startsWith('bus.post-attempt-')	fine
test :950 T34	notEqual between two runs' ids	now always true, which is what the test wanted
TOOLS.md :382-433	the pointer, rollback sets, backups, post-attempt and --restore	updated

Unrelated hits I checked: packages/cli/tests/notifier.test.mjs:255, a torn-files regex. scripts/release.sh and packages/runs write their own activation-log.jsonl for the other release system.

Item 2: plan-mode refusals in console_for_target (N1)

• parse_opts no longer checks the tester port inline. After the loop it checks the port unless PLAN=1. An empty --tester-port "" is still usage, through a new [ -n "$2" ].
• In console_for_target, an invalid port calls usage outside --plan, as before. Under --plan it goes through check_refuse tester-port-invalid. tester-port-target goes through check_refuse in both modes. Outside --plan, check_refuse is refuse, so the output is unchanged.

Deviation from the brief (sage-1155)

The brief says the bad port "gives the same reason text usage gives today". Usage has no reason line. It prints the usage block and exits 4. Sage ruled that this was a brief error and that I should use a reason line:

• main Console port 7332: --tester-port 80 is not a whole port from 1024 to 65535 other than 7332
• otherwise: ... other than 7332 and the Console's --port N

Without --plan the output is still the usage block and exit 4, byte for byte. Sage won't re-pin the brief for this.

Item 3: webui-service tester port length (N2)

tester_port_ok checks ${#TESTER_PORT} -le 5 on the value as written, before it strips zeros. That's the count serve uses (webui cli.mjs:30, /^\d{1,5}$/) and the one valid_tester_port in stack-release.sh uses. 007333 now refuses with exit 4, and 07333 still renders.

Tests

• T43 (stack-release.test.mjs), item 1. A date stand-in on PATH pins every call to one second, except calls with %s (the gate's start marks), which go to /usr/bin/date. Pinning those too would make two gates' journal windows overlap.
  • Activate C1 with --pm-after-harness, then pm-on on the same copy. The ids are id and id-1, with matching log lines, two rollback sets and a SHA256SUMS in each.
  • Two migrate-and-restore rounds. Round 1 restores an old-form id and round 2 a suffixed one. Each prints its own post-attempt path. At the end there are two posts, two backups and four rollback sets.
  • Ten names taken: eight rollback sets, one backup and one post-attempt store. The run refuses capture-failed with no start or stop and an unchanged fingerprint. Its log line has activation null.
  • --restore with -0, -10, -a, - or a 13th hex character appended is usage (exit 4). The base form, -1 and -9 are not.
• T44, item 2.
  • --plan --tester-port P with --pm-after-harness on a business file that sets harness. P is 80 and the Console's port, against a pointer with --port, then 80 and 7332 against one without. Each case lists exactly the tester-port-invalid line and the pm-after-harness-set line, exits 3 and leaves stderr empty. The same flags without --plan give exit 4, empty stdout and stderr equal to --help's. Nothing starts or stops, and the log doesn't grow.
  • Activate A, whose Console lacks --tester-port, with --plan. It lists tester-port-target and unknown-kind-for-target and exits 3. Without --plan it refuses tester-port-target with today's message and one log line.
• Round 2 added two subtests for Dewey's round 1 (#1678 comment 29352).
  • C1, in T43: "adopt takes the next free id too". The clock is pinned, there's no pointer, and stack-rollback/<id> already exists for the copy adopt will take. Adopt exits 0, and both the pointer's activation and the one log line are <id>-1.
  • C2, in T44: "without --plan a bad port is usage before any pointer read". With no pointer, activate C1 acme --tester-port 80 exits 4, with empty stdout, stderr equal to --help's, no log line and no start or stop. Without the post-loop check (:85), pointer_for_business refuses no-pointer first, with exit 3 and a log line.
• service.test.mjs, item 3: "tester service counts the digits as written before it strips leading zeros".

Runs

All runs used the worktree ~/darkwing-scratch/r180/wt at base c7f3beb17, with node_modules linked. Totals come from the ℹ summary lines.

Run 1, slot 02:40:51.625Z to 02:44:44.402Z (sage-1155):

Run	Result	End
stack-release.test.mjs whole	106 pass, 0 fail	02:44:22.823Z
service.test.mjs whole	28 pass, 0 fail	02:44:25.286Z
m1 no suffix (for s in "")	killed, T43: second run refuses capture-failed	02:44:31.894Z
m1b old --restore regex	killed, T43: suffixed --restore is usage	02:44:39.467Z
m2 invalid port ends --plan (usage)	killed, T44: exit 4, expected 3	02:44:41.429Z
m2b refuse tester-port-target	killed, T44: stderr not empty under --plan	02:44:44.247Z
m3 length line removed in webui-service.sh	killed: 007333 exit 0, expected 4	02:44:44.402Z

Defect found during the build

After run 1, while writing this packet, I found that the ten-names refusal wrote the -9 id, which belongs to another run, into its refused line. lock() refuses interrupted-run before this point (:562), so the line couldn't close an open run, but a refusal record named a run that wasn't its own. The fix clears ACT and POST before that refusal. The ten-names subtest in T43 tests it, and Sage agreed with the fix (sage-1159). Run 2 covers the fix and adds two mutants, on the backups/stack check and the post-attempt check. Those prove the brief's "chosen while holding the lock, against both stack-rollback/ and backups/stack/", which run 1 didn't cover.

Run 2, slot 02:47:46.563Z to 02:51:59.884Z (sage-1159):

Run	Result	End
stack-release.test.mjs whole	107 pass, 0 fail (run 1 plus the ten-names subtest)	02:51:22.962Z
m1 no suffix	killed, T43: second run refuses capture-failed	02:51:29.999Z
m1c ACT="" POST="" removed	killed: activation ...-9, expected null	02:51:39.603Z
m1d no backups/stack check	killed: the run took the -8 name and captured	02:51:49.775Z
m1e no post-attempt check	killed: the run took the -9 name and captured	02:51:59.883Z

service.test.mjs and scripts/webui-service.sh didn't change after run 1. Each mutant edited the worktree file after a backup checked by sha256, and the script put the file back and checked the sha again.

No other test file runs the changed code. packages/webui/tests/pinned-copy.test.mjs and packages/cli/tests/stack-copy.test.mjs run webui-service.sh copy, which doesn't reach tester_port_ok. No test pins a sha256 of either script. Sage's gate runs the suites.

Round 2, slot 03:24:32.105Z to 03:28:20.029Z (sage-1171), worktree on 7f519242e:

Run	Result	End
stack-release.test.mjs whole	109 pass, 0 fail (run 2 plus C1 and C2)	03:28:05.528Z
X2 adopt's own date line back in place of next_activation	killed, C1: activation <id>, expected <id>-1	03:28:16.516Z
X1 post-loop port check (:85) removed	killed, C2: exit 3 no-pointer, expected 4	03:28:20.029Z

Dewey said nothing else needed re-running. service.test.mjs and both scripts are unchanged since run 2.

Dewey's N1 is a note only and isn't changed in this round. Under --plan, a hard refusal before console_for_target, such as no-pointer, ends the run before the port is checked, so tester-port-invalid isn't on that plan.

Candidate

Round 2:

• candidate-manifest.sha256 digest c743480eb1e92ee1e1c4365d715543466f58c712a73c8cc39d6147600c1b2c06.
• build.patch sha256 109b774d43573cabb8044dac4907bdc8fb19295cedd2f7f46f8a9980154f3c45, git patch-id --stable 31b1d502444eb4b6589662e6b917600a40030b2f. 161 insertions, 10 deletions, five files. It applies to c7421cabd (git apply --check).
• Only the test file changed from round 1. Round 1 was manifest digest 26ea8e88d23a and patch-id 30a272d49b79.

Path	sha256
docs/TOOLS.md	3468a2d2eeeb0175dc37499e89e609144ff3a07bb275fea64b82bbdbd64e4de5
packages/cli/tests/stack-release.test.mjs	09c6cdd7568cd6769d9a39c7f5655df1850b1de7e01712fac0bad84ff2b692d5
packages/webui/tests/service.test.mjs	1fca5facd9be5014803cef88a4f79d51c7b67920bdf001a1909daa2a1339fa03
scripts/stack-release.sh	f225cfdf5d2ba3f828b45c8af3c0da7f7f9d8722daa6890c374e4253f3ee37a7
scripts/webui-service.sh	0636852303b73aa9ad4761679bb7c7bda4eca3e4ff56d5f67d2cb1d1adc75b80

The patch adds no em dash. BUILD.md and the TOOLS.md lines pass tools/unslop-hook/unslop-check.js.