[Sprint] sprint-loop-45

[scealiontach]

Sprint Plan: 2026-06-01 Sprint Loop 45

Sprint Goal

Close three high-priority shell-scripts regressions that can cause packaged installs to miss documented commands, Kubernetes helper commands to run against the wrong namespace, and daml-export to terminate or duplicate background builds. The sprint is intentionally limited to the three eligible Backlog issues returned by Linear for the verified Surinis shell-scripts project; each issue has a clear failure mode, focused implementation surface, and regression-test path.

Selected Issues

SUR-3351: Bug: Kubernetes pod helpers drop -n on per-pod commands

Description summary: against-each-pod and pod-console accept -n NAMESPACE and use it for the initial pod listing, but later per-pod commands omit the namespace. against-each-pod drops -n from kubectl get pod "$pod" -o json and the requested pod command, while pod-console builds tmux payloads that run kubectl $COMMAND pod/$pod ... without -n. The issue calls out existing tests/against-each-pod.bats coverage as incomplete because it only checks the listing call.

Rationale: This is a correctness bug with user-visible risk: the helpers can list pods from one namespace and then inspect or operate on same-named pods from another namespace. It is also relatively small and testable with the existing kubectl/tmux stubs.

Definition of Done:

• bash/against-each-pod builds namespace args when -n is supplied and passes them to every per-pod k8s::ctl get pod and command invocation.
• bash/pod-console includes the namespace in each generated kubectl send-keys payload when -n is supplied.
• Existing behavior without -n remains unchanged and does not emit namespace flags.
• tests/against-each-pod.bats asserts every recorded kubectl call includes -n my-ns when the option is provided.
• tests/pod-console.bats covers the namespace-bearing send-keys payload without weakening the existing quoting regression.
• Verification artifacts such as KUBECTL_ARGV_LOG snippets are posted to Linear if retained, not committed under .claude/sprints/, .claude/runs/, or .claude/plans/.
• tests/bats/bin/bats tests/against-each-pod.bats tests/pod-console.bats passes.

Dependencies / ordering: Do first. It is the smallest runtime fix and establishes the namespace argument pattern to preserve while running the rest of the sprint tests.

SUR-3353: Bug: bin package omits standalone executable commands

Description summary: The bin tarball recipe only selects no-extension files containing the string includer, so executable standalone commands without @include support are silently left out. The issue identifies bash/mddoc and bash/semver as executable command scripts missing from dist/bin-*.tar.gz, and notes README.md documents bash/mddoc <file> as a usable command.

Rationale: This packaging bug affects all users installing from the bin tarball and is reviewable if handled with an explicit command-selection rule plus a tarball regression. It pairs well with SUR-3351 because both protect command availability and behavior for installed scripts.

Definition of Done:

• Makefile no longer relies on grep -q "includer" as the only selector for bin-package commands.
• Standalone executable no-extension commands such as mddoc and semver are included in the bin tarball.
• Commands that use @include are still packed through bash/pack-script; standalone executable commands are copied or otherwise packaged without requiring fake includer references.
• The packaging rule avoids accidentally including library files, fixtures, directories, or non-executable files.
• Regression coverage builds or inspects the bin package and asserts bin/mddoc and bin/semver are present.
• Existing pack-script behavior and tests remain intact.
• make package and the targeted packaging regression pass.

Dependencies / ordering: Do after SUR-3351 and before SUR-3352. The Makefile change is broad enough to verify independently before moving to the more stateful daml-export process-control fix.

SUR-3352: Bug: daml-export can kill in-flight builds on normal exit

Description summary: daml-export starts build "$OUTPUT_DIR" & jobs, tracks PIDs in RUNNING_PROCS, and installs an EXIT trap that kills all tracked jobs. There is no final wait after the main and post-loop scheduling, so a normal successful exit can kill still-running builds. The post-loop find "$TARGET_DIR" -name export.good pass can also start duplicate builds for an output directory whose first build is still running.

Rationale: This is the riskiest selected issue because it changes background-process lifecycle behavior, but it fixes data loss and wasted CPU in long-running exports. Keeping it last lets earlier, smaller fixes land with green tests before focused process-control work.

Definition of Done:

• bash/daml-export distinguishes normal completion from signal or failure cleanup so successful exits wait for remaining builds instead of killing them.
• Final waiting propagates at least one build failure to the script exit status.
• The post-loop verify_and_build path does not start a duplicate build for an output directory that already has a running build.
• PID tracking is pruned consistently without losing still-running child processes.
• Regression coverage uses a slow stub daml build to prove successful runs wait for completion and do not kill in-flight jobs.
• Duplicate-build coverage proves the same output directory is not scheduled twice while its first build is running.
• Slow-stub logs or process traces are posted to Linear if retained, not committed under .claude/sprints/, .claude/runs/, or .claude/plans/.

Dependencies / ordering: Do last. It touches async behavior in bash/daml-export and should be verified after the packaging and Kubernetes changes are already stable.

Risks + Mitigations

• Namespace arguments can be inserted in the wrong position for kubectl subcommands; build an argv array and assert exact logged command lines in bats.
• pod-console already has quoting-sensitive send-keys coverage; extend the existing payload inspection instead of replacing it.
• against-each-pod currently invokes jq after the kubectl stub; keep tests focused on logged kubectl argv and avoid adding a real jq dependency.
• Packaging every no-extension file could include non-command helpers or directories; filter on regular executable files and preserve the library *.sh exclusion.
• Running pack-script against standalone commands could fail or alter scripts unnecessarily; only use pack-script for commands that actually include the includer mechanism.
• make package may leave dist/ state that affects follow-up assertions; run from a clean dist or have the test isolate package output.
• daml-export background waits can hang if the regression stub or PID pruning is wrong; keep slow stubs short and add bounded test timeouts where the bats suite already supports them.
• Propagating build failures could alter existing successful-run behavior; add explicit tests for success and failure paths before changing trap cleanup.
• Duplicate-build detection needs a stable key for output directories; track output directories alongside PIDs instead of inferring from process state alone.
• Verification artifacts requested by Linear must not be committed under .claude/sprints/, .claude/runs/, or .claude/plans/; post or discard generated logs before final diff review.

Out of Scope

• Selecting or modifying issues outside Linear status Backlog at planning time.
• Changing Linear labels, priorities, project membership, assignments, or cycles.
• Reworking the broader Kubernetes helper API beyond preserving namespace flags for the listed commands.
• Redesigning the full package layout or release process beyond including standalone executable commands in the bin tarball.
• Rewriting daml-export export-range generation, archive correction, or Daml source rewriting beyond the background-build lifecycle bug.
• Committing local verification transcripts, generated tar listings, or slow-stub logs under .claude/.

Linear Evidence

• Linear team verified: Surinis
• Linear project used: shell-scripts
• Query/filter used: team Surinis, project shell-scripts, state exactly Backlog, archived excluded; full descriptions and comments read for every Backlog issue returned; manual label, blockedBy, sub-issue, and open-PR overlap filters applied. Open PR file list was [], so Dependency Filter B was a no-op.
• Approx count of Backlog issues reviewed: 3
• Approx count of manual-labelled Backlog issues skipped: 0
• Issues skipped due to unmerged blockers: 0 []
• Issues skipped due to open-PR file overlap: 0 []

Sub-issue Status

No selected or skipped candidate issue had sub-issues in Linear.

Parent Issue	Sub-issue	Sub-issue Status	Eligible?
SUR-3351	None	N/A	Yes
SUR-3352	None	N/A	Yes
SUR-3353	None	N/A	Yes

Linear State Transitions

Issue ID	Previous State	New State
SUR-3351	Backlog	Todo
SUR-3352	Backlog	Todo
SUR-3353	Backlog	Todo