Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement

Phase 3 of design #3352 (unknown means stop — one strict argument contract for the repo's operator scripts). Design doc: files/designs/code-operator-argument-contract.md in the keep-the-four-repos-healthy goal workspace.

Gated on Phases 1–2 of #3352 (Phase 1 = #3264 + #3252, #3287, #3281, #3278, #3296, #3297; Phase 2 = #3333, #3330, #3295, #3312) — do not start the inventory until they land.

Scope

Closing inventory audit + contract statement:

Inventory every remaining hand-rolled argv parser in bin/, pm-stack/*/scripts/, pkgs/*/deploy*.mjs, pkgs/*/install*.mjs, infra/*/worker/deploy.mjs, nixos/services/*/worker/deploy.mjs, and the Go tools under pkgs/mcpx/tools/ — every process.argv / args.includes( / argv.indexOf( consumer not covered by Phases 1–2.
Disposition each, in the closing evidence on this issue: (a) covered by Phases 1–2; (b) strict — fix it under this design before closing, or file it as a named follow-up issue; (c) deliberately lenient — named, with its reason (documented pass-through of trailing arguments; interactive surfaces).
Named starting candidates (disposition, do not pre-judge): pm-stack/aggregator/scripts/compact-usage-snapshots.ts (validates its --months value, membership-parses unknowns), bin/provider-catalog-sync.mjs, pm-stack/aggregator/scripts/collect-fleet-feed.ts, bin/record.mjs, pm-stack/aggregator/scripts/confirm-charges-surfaced.ts.
Explicit dispositions required: the pkgs/id REPL parsers (id(repl): find/search/show/peek parsers silently swallow unknown and mistyped flags — a typo'd flag vanishes and its value becomes a query #2274 — interactive, its hard-error-vs-warn pin is its own; expected disposition is deliberately-local, recorded with the reason); pkarr-worker RETENTION_SECONDS (pkarr-worker(retention): RETENTION_SECONDS is parsed with a bare Number() and no guard — '0'/'7d'/' ' schedule the deletion alarm at/before now (or NaN), so stored packets vanish right after a 204, and '1e9' never expires #3261 — an env value, expected to belong to Design: env numbers are arguments — one strict parse for boot-time configuration #2835's env contract / Phase 3 of #2835 — closing inventory audit for the env-number contract + contract docs #2837's audit; confirm and record, do not adopt).
Check callers (systemd units, timers, docs, wrapper scripts) of every parser newly made strict in this phase for arguments that were previously ignored — a caller that relied on an ignored argument gets its call fixed and named in the evidence.
Write the contract where operator tools are documented (script header-comment conventions / contributing docs — name the exact places in the evidence), and post the closing evidence on design issue Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352.

Acceptance criteria

A complete inventory table (parser file → disposition a/b/c with reason or follow-up issue link) is posted on this issue; the grep basis for completeness is stated.
Every (b) parser is either fixed under this design (PR linked) or filed as a named follow-up issue linked from the table.
id(repl): find/search/show/peek parsers silently swallow unknown and mistyped flags — a typo'd flag vanishes and its value becomes a query #2274 and pkarr-worker(retention): RETENTION_SECONDS is parsed with a bare Number() and no guard — '0'/'7d'/' ' schedule the deletion alarm at/before now (or NaN), so stored packets vanish right after a 204, and '1e9' never expires #3261 carry explicit recorded dispositions as above.
The contract statement is written into the named documentation places (paths in the evidence).
Closing evidence is posted on Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352.

Phase 3 of design #3352, filed this pass. Gated on Phases 1-2 (Phase 1 = #3264 + #3252, #3287, #3281, #3278, #3296, #3297; Phase 2 = #3333, #3330, #3295, #3312) and labelled status/blocked accordingly. Triage packet enqueued → pilot task 5061 (queue=repo-health-code-pilot, status=queued, verified by dedupe re-read). Triage: confirm scope per #3352, record the gating, enqueue the implementation follow-up once the gating clears — do not start the inventory early.

Triage (queue task 5061, lane F, 2026-11-01T05:41Z): scope confirmed against design #3352 and the design doc (files/designs/code-operator-argument-contract.md, present in the goal workspace). This phase is a closing audit only — no implementation in the triage task, and the inventory must not start until Phases 1–2 land.

Gating check — NOT cleared (fresh gh states, 2026-11-01T05:37–05:41Z):

Phase 1: pkarr-worker(deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu or --deploy-version=<id> performs a real deploy of HEAD #3264 OPEN, pkarr-worker(deploy): --dry-run is ignored on the --deploy-version path — a rollback preview creates a real 100% deployment #3252 OPEN, github-backup(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real deploy (upload + secret reset) #3287 CLOSED, id-mail(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu enters the real deploy sequence and force-deletes the retired 'id-mail' Worker #3281 OPEN, opencode-claimant(install): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real install, and a typo'd --stor writes the real OpenChamber store #3278 OPEN, proxy-supervise: unrecognized arguments are silently ignored — a typo'd --dry-rnu starts/rolls real proxies, and a typo'd --statuz reconciles instead of reporting status #3296 CLOSED, sync-models: unrecognized arguments are silently ignored — a typo'd --dry-rnu rewrites the live OpenCode config in place (and reloads opencode) #3297 OPEN (4 of 7 open)
Phase 2: aggregator(charges-producer): a trailing or flag-like --start/--end/--out value is silently replaced by the defaults — the producer overwrites the live candidates file for the wrong period and exits 0 #3333 OPEN, aggregator(backfill): trailing --dir crashes with a raw TypeError, and a flag-like value (--dir --print) silently writes the rebuilt history into a directory named '--print' #3330 CLOSED, aggregator(snapshots): append-usage-snapshots --by with no value silently discards every derived record — exit 0, 'no records derived' #3295 OPEN, mcpx(docs-history): a value-taking flag as the last argument panics — stamp/check arg loops index rest[i] after i++ with no bounds check #3312 OPEN (3 of 4 open)

Because the gating has not cleared, the implementation follow-up packet is NOT enqueued yet (the packet conditions it on the gating clearing). Task 5061 is parked with the resume condition: all Phase 1 and Phase 2 issues above closed → enqueue the implementation follow-up packet (or split) carrying this issue's acceptance criteria intact → work the closing inventory (surfaces: bin/, pm-stack/*/scripts/, pkgs/*/deploy*.mjs, pkgs/*/install*.mjs, infra/*/worker/deploy.mjs, nixos/services/*/worker/deploy.mjs, pkgs/mcpx/tools/; explicit dispositions owed for #2274 and #3261; caller checks for newly-strict parsers; contract statement into the operator-tool docs; closing evidence also posted on #3352). Verification for the follow-up: repo test suites via CI per fleet policy; no builds on the sandbox.

Correction (lane F): the gating table in my triage comment above listed #3287, #3296, and #3330 as CLOSED. A fresh direct API check (2026-11-01T06:14Z) shows all three are OPEN — in fact all 11 gating issues are currently OPEN (Phase 1: #3264 #3252 #3287 #3281 #3278 #3296 #3297; Phase 2: #3333 #3330 #3295 #3312). The wrong states came from corrupted chunked tool output during my shift. The triage conclusion is unchanged and stronger: gating NOT cleared, inventory not started, follow-up packet not enqueued, task 5061 parked until every Phase 1 + Phase 2 issue closes.

🤖 Agent note · picked up

Agent: queue worker (repo-worker-code), Lane A shift
Session / ID: cron repo-queue-worker-shift; queue task 5061
Found via: queue claim (resume of parked triage)
Task: Phase 3 (audit) of Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352 — revalidate the 11 Phase 1/2 gate issues fresh.
Links: Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353, Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352

🤖 Agent note · parked

Agent: queue worker (repo-worker-code), Lane A shift
Session / ID: cron repo-queue-worker-shift; queue task 5061
Reason: Gate unchanged on fresh check: 9 of 11 Phase 1/2 gate issues still OPEN (pkarr-worker(deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu or --deploy-version=<id> performs a real deploy of HEAD #3264, pkarr-worker(deploy): --dry-run is ignored on the --deploy-version path — a rollback preview creates a real 100% deployment #3252, github-backup(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real deploy (upload + secret reset) #3287, opencode-claimant(install): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real install, and a typo'd --stor writes the real OpenChamber store #3278, proxy-supervise: unrecognized arguments are silently ignored — a typo'd --dry-rnu starts/rolls real proxies, and a typo'd --statuz reconciles instead of reporting status #3296, sync-models: unrecognized arguments are silently ignored — a typo'd --dry-rnu rewrites the live OpenCode config in place (and reloads opencode) #3297, aggregator(charges-producer): a trailing or flag-like --start/--end/--out value is silently replaced by the defaults — the producer overwrites the live candidates file for the wrong period and exits 0 #3333, aggregator(backfill): trailing --dir crashes with a raw TypeError, and a flag-like value (--dir --print) silently writes the rebuilt history into a directory named '--print' #3330, mcpx(docs-history): a value-taking flag as the last argument panics — stamp/check arg loops index rest[i] after i++ with no bounds check #3312); only id-mail(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu enters the real deploy sequence and force-deletes the retired 'id-mail' Worker #3281 and aggregator(snapshots): append-usage-snapshots --by with no value silently discards every derived record — exit 0, 'no records derived' #3295 closed.
Resume condition: All 11 gate issues CLOSED; then post the triage verdict and enqueue the Phase 3 implementation follow-up.
Links: Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353, Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352

agent-note:v1

state: picked-up
agent: repo-worker-code (OpenChamber scheduled lane)
session: ses_e5e63de7762ffeTdiKRyeQb1wZ; task 5061
task: triage Phase 3 only; do not start inventory or enqueue implementation before all Phase 1/2 issues close.
next: freshly verify Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353/Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352 and all 11 gate issues, then park if the gate remains open.
links: Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353 · Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352

agent-note:v1

state: blocked
agent: repo-worker-code (OpenChamber scheduled lane)
session: ses_e5e63de7762ffeTdiKRyeQb1wZ; task 5061
verdict: Phase 3 scope remains as specified, but the gate is unmet: 9/11 Phase 1/2 issues are OPEN (pkarr-worker(deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu or --deploy-version=<id> performs a real deploy of HEAD #3264, pkarr-worker(deploy): --dry-run is ignored on the --deploy-version path — a rollback preview creates a real 100% deployment #3252, github-backup(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real deploy (upload + secret reset) #3287, opencode-claimant(install): unrecognized arguments are silently ignored — a typo'd --dry-rnu performs a real install, and a typo'd --stor writes the real OpenChamber store #3278, proxy-supervise: unrecognized arguments are silently ignored — a typo'd --dry-rnu starts/rolls real proxies, and a typo'd --statuz reconciles instead of reporting status #3296, sync-models: unrecognized arguments are silently ignored — a typo'd --dry-rnu rewrites the live OpenCode config in place (and reloads opencode) #3297, aggregator(charges-producer): a trailing or flag-like --start/--end/--out value is silently replaced by the defaults — the producer overwrites the live candidates file for the wrong period and exits 0 #3333, aggregator(backfill): trailing --dir crashes with a raw TypeError, and a flag-like value (--dir --print) silently writes the rebuilt history into a directory named '--print' #3330, mcpx(docs-history): a value-taking flag as the last argument panics — stamp/check arg loops index rest[i] after i++ with no bounds check #3312); id-mail(worker deploy): unrecognized arguments are silently ignored — a typo'd --dry-rnu enters the real deploy sequence and force-deletes the retired 'id-mail' Worker #3281 and aggregator(snapshots): append-usage-snapshots --by with no value silently discards every derived record — exit 0, 'no records derived' #3295 are CLOSED. Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352 and Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353 remain OPEN.
action: no inventory started and no implementation follow-up enqueued. Keep Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353 status/blocked until all 11 gate issues close; then revalidate and enqueue the follow-up.
links: Design: unknown means stop — one strict argument contract for the repo's operator scripts #3352

agent-note:v1
state: reviewed (coverage loop-back)
Coverage pass 2026-11-03, loop-back review: this issue was re-reviewed (drift / overlap / already-handled / stale / blockers / ordering) so every open issue in the four repos is reviewed and in the system. Verdict: still live; in the system as task 5061 (triage, blocked, priority 30) in repo-health-code-pilot. Labels audited and synced. If it is already handled at current main, its triage closes it with evidence; if oversized, the triage files the split; blockers belong on this issue.
Found via: coverage loop-back 2026-11-03

Navigation Menu

Repository navigation

Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353

Scope

Acceptance criteria

34 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Phase 3 (audit) of #3352 — closing argv-parser inventory + argument contract statement #3353

Description

Scope

Acceptance criteria

Activity

dezren39 commented on Nov 1, 2026

dezren39 commented on Nov 1, 2026

dezren39 commented on Nov 1, 2026

34 remaining items

dezren39 commented on Nov 2, 2026

dezren39 commented on Nov 2, 2026

dezren39 commented on Nov 2, 2026

dezren39 commented on Nov 2, 2026

developing-today commented on Nov 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions