ctrld/tasks/plan.md

Plan: provisioning failure codes (issue #586)

Spec: SPEC.md. Baseline: ac0e6aed on v1.0. Branches: issue-586 (off v1.0), issue-586-master (off master). Two MRs, both referencing #586; the v1.0 MR carries Closes #586.

Shared contract (fixed here so parallel tasks cannot diverge)

Code	Stage	Exit
API_UNREACHABLE	bootstrap	30
API_REJECTED	bootstrap	31
API_DEVICE_INVALID	bootstrap	32
LISTENER_BIND_FAILED	listener	41
LISTENER_CONFIGURED_ADDR_UNAVAILABLE	listener	42
SERVICE_INSTALL_FAILED	service	51
SERVICE_START_FAILED	service	52
SERVICE_SELFCHECK_FAILED	service	53

• Result file: provision_result.json in the ctrld home dir (same resolution as the persisted internal log: absHomeDir on v1.0, the userHomeDir-based equivalent on master). Atomic write (temp + rename in the same dir). Cleared when provisioning succeeds.
• Result schema (version 1): version, timestamp (RFC3339, UTC), stage, code, exit_code, message, optional detail.attempts[] of {addr, proto, os_error}; attempts capped at 12 entries, every string capped at 256 chars.
• Identifier line, exact format (greppable, token-free by construction): provisioning failed: stage=<stage> code=<CODE> (exit <N>).
• Redaction: results are built through a constructor that takes the secrets in scope (cd UID, provision token) and strips them from every field. Messages come from our own summaries plus OS error strings, never raw config or API bodies.
• Exit seam: provisionExit = os.Exit package var so tests can stub process exit. Emission helper failProvision(...) writes the file, logs the identifier line, calls the notify func, then exits with the stage code. Nonzero exit is preserved everywhere the daemon exits nonzero today; the deliberate clean return on permanent API rejection stays a clean return (result file only).

Dependency graph

A1 (contract module + doc, v1.0)          D1 (master port)
  ├─► B1 daemon emissions (cli.go)          depends on: contract table
  ├─► B2 start-side (commands.go+service.go)  (from A1) + C1 verified
  └─► B3 postinstall (scripts, tests)          implementation as reference
        └─► C1 v1.0 checkpoint ────────────► D1 ─► E1 final checkpoint

Group A — serial, runs inline (1 task)

A1. Contract foundation on issue-586

Create branch issue-586 from v1.0. New files: cmd/cli/provision_result.go, cmd/cli/provision_result_test.go, docs/provisioning-failure-codes.md.

Module contents: stage type + the 8 code constants + exit-code map; ProvisionResult struct per schema; bounded/redacting constructor; atomic writeProvisionResult / readProvisionResult / clearProvisionResult; identifier-line formatter; provisionExit seam; failProvision helper. Doc: full table — code, stage, exit, failure scenario, next safe troubleshooting action / evidence request.

Tests (RED first): every code maps to exactly one stage and one in-range exit code (30–39/40–49/50–59); no collision with 0–3 (ctrld status) or 126 (pin); file round-trip; atomic overwrite; clear; redaction (a result built from inputs containing a fake token and cd UID serializes without them); attempts/string caps enforced; identifier line matches the exact format.

Acceptance: go build ./... and go test ./cmd/cli/ green; doc rows exactly match the constants.

Group B — parallel Workflow fan-out, one subagent per task, worktree isolation, branched from issue-586 after A1

B1. Daemon emissions in cli.go

• Bootstrap branches in run() (cli.go:339-372):
  • permanent rejection (permanentAPIRejection): write API_REJECTED result (HTTP status + our own summary, no raw API body), keep the existing clean return and its comment.
  • invalid device (controld.InvalidConfigCode): write API_DEVICE_INVALID before uninstallInvalidCdUID.
  • fatal fetch: write API_UNREACHABLE, replace cdLogger.Fatal() with error log + identifier line + failProvision exit 30 (still nonzero for the service manager).
• Listener (tryUpdateListenerConfig, tryUpdateListenerConfigIntercept):
  • record every failed bind attempt {addr, proto, os_error} — capture UDP and TCP errors separately in tryListen (keep errors.Join for control flow), cap per contract.
  • exhaustion fatal (cli.go:1639) and converged-random fatal (cli.go:1720) → LISTENER_BIND_FAILED exit 41 with attempts.
  • no-fallback-allowed fatal (cli.go:1652) and intercept-mode fatals (cli.go:1452,1467) → LISTENER_CONFIGURED_ADDR_UNAVAILABLE exit 42 (fallback-exhausted intercept fatal stays LISTENER_BIND_FAILED).
  • all fatals keep calling the notify func first; final message includes the code string.
• Clear the result file at the point provisioning is known good (after updateListenerConfig succeeds in run()).

Tests (RED first): occupy a UDP+TCP port, drive the listener path to exhaustion with the exit seam stubbed, assert the result file has LISTENER_BIND_FAILED, the attempted address, both protocols' os_error (address already in use class); pure mapping test API error → code (permanent 4xx → API_REJECTED, 40402 → API_DEVICE_INVALID, network error → API_UNREACHABLE) following cli_preflight_test.go patterns.

Acceptance: only cmd/cli/cli.go + new/extended tests touched; go build ./... && go test ./cmd/cli/ green.

B2. ctrld start reporting in commands.go + service.go

• Add doTasksE (returns failed task name + error; doTasks keeps its signature and delegates).
• Fresh-install path (commands.go:618): failed Install task → SERVICE_INSTALL_FAILED (write result, print identifier line, exit 51); failed Start task → SERVICE_START_FAILED (exit 52). This fixes the current fall-through that exits 0 on install failure.
• Existing-service path (commands.go:528-543): failure → 52 with the same reporting (replaces bare os.Exit(1)).
• Self-check failure branch (commands.go:627-664): keep the log drain and uninstall(p, s); then read the daemon's result file — if present and stamped after this start attempt began, report its stage/code/exit (daemon identity wins: e.g. LISTENER_BIND_FAILED); otherwise write and report SERVICE_SELFCHECK_FAILED exit 53. Extract this into a testable helper (fabricated result files + stubbed exit seam).
• On successful start (self-check ok), clear any stale result file.

Tests (RED first): doTasksE failure attribution; helper precedence (fresh daemon result wins; stale/missing falls back to 53); exit-code selection per failed task.

Acceptance: only cmd/cli/commands.go, cmd/cli/service.go + tests touched; build and package tests green.

B3. postinstall MDM surface

• scripts/pkg/postinstall: capture ctrld start output to a mktemp file (chmod 600) instead of /dev/null; keep the plist check as the success gate; on failure, grep -m1 '^provisioning failed: ' from the capture into the install log together with the exit code; delete the capture file always; never echo any other output line (token safety preserved by extracting only the fixed-format line).
• Shell test test-scripts/darwin/test-postinstall-provision-failure.sh (matching existing script conventions): stub $CTRLD that prints a fake token plus a valid identifier line and exits 41; assert the logged output contains stage/code/exit and not the token; assert success path unchanged. Runs without root.
• Update docs/macos-pkg-mdm.md where it documents the discard behavior/failure triage, and add the failure-code doc link.

Acceptance: shell test passes locally (sh test-scripts/darwin/...); only scripts/pkg/postinstall, test-scripts/darwin/, docs/ touched.

Checkpoint C1 — serial, after Group B merges

Merge order: B1, B2, B3 into issue-586. Then: go build ./..., go vet ./..., go test ./cmd/cli/... (and full ./...), run the B3 shell test, verify doc table == constants, and verify each spec acceptance criterion has an implementation + test. Fix-forward any merge fallout before Group D starts.

Group D — serial (1 task, own worktree off master)

D1. Master port on issue-586-master

Create git worktree with branch issue-586-master from origin/master/master. Port with the v1.0 implementation as reference, adapted to master's structure (zap-shaped logging idiom, no commands.go):

• cmd/cli/provision_result.go + tests: identical contract table.
• Bootstrap: run() branches at master cli.go:340-374 (same permanent-rejection clean return, invalid-device, fatal fetch).
• Listener: tryUpdateListenerConfig fatals at master cli.go:1657/1667/1719; intercept variant at cli.go:1487/1502; per-attempt capture (bind errors currently logged at Debug, cli.go:1665).
• Start side: commands_service_start.go — both doTasks call sites, self-check default: arm (os.Exit(1) ~line 370), same fall-through audit, same precedence logic; doTasksE in service.go.
• docs/provisioning-failure-codes.md: same table (omit pkg/postinstall-specific notes; master has no scripts/pkg).
• No postinstall work on master.

Tests mirrored from v1.0 where the structure allows.

Acceptance: in the master worktree, go build ./..., go test ./cmd/cli/... green; constants table semantically identical to issue-586.

Checkpoint E1 — serial, final

• Cross-branch contract equality: compare code constants, exit codes, identifier-line format, result schema between the two branches.
• Full test suites on both branches.
• Both branches committed (per-task Conventional Commits); no pushes, no MRs yet — /draft-review is the next pipeline step.

Execution notes

• Each parallel group runs as one Workflow fan-out, one subagent per task, isolation: 'worktree' so parallel edits never conflict; serial tasks (A1, C1, D1, E1) run inline (D1 manages its own master-based worktree).
• Every subagent follows RED → GREEN → regression → build and commits in its worktree; the orchestrator merges in dependency order and runs the full suite before the next group.
• Subagent prompts are self-contained: they carry the contract table and file anchors from this plan, not references to SPEC.md (worktree copies may not include untracked files).