server-deploy/docs/superpowers/plans/2026-09-25-operation-state.md

Operation State Implementation Plan

For agentic workers: Use superpowers:executing-plans with test-driven-development. No production access or automatic commits.

Goal: Persist operation identity and status under an exclusive OS lock, refusing duplicate execution and ambiguous state.

Architecture: An internal state package acquires a nonblocking per-directory host lock and returns a session. Every mutation saves a complete bounded snapshot using write/sync/rename; the session becomes unusable on persistence errors. The directory must be a pre-existing trusted local directory, not a network share.

Tech Stack: Go standard library, Linux flock / Windows LockFileEx, os.Root.

Spec: docs/2026-09-25-complete-optimization-proposal.md sections 7, 8, 12, 14.

Constraints

• Current directory and codex/new-deployment-architecture branch; preserve prior edits.
• No CLI write endpoint or Docker/application operation is enabled by this package.
• No automatic deletion of lock files, stale-task replay or corrupted-state reset.
• Lock-file inode must remain stable; close releases the OS lock.
• Metadata integrity is not authorization, and terminal success must be verified by the future executor.
• Linux is the production target; Windows provides development tests. Power-loss durability on Windows is not claimed.

Task 1: Exclusive host sessions

Files: internal/state/store.go, lock_linux.go, lock_windows.go, lock_unsupported.go, store_test.go.

Interface: Acquire(directory, hostID string) (*Session, error); Session.Close() error.

• Write tests: second session returns ErrBusy, closed session rejects use, independent directories do not block each other, invalid IDs fail, killed child releases OS lock.
• Run go test ./internal/state; observe missing implementation failure.
• Implement nonblocking OS lock with private regular file inside os.Root; refuse unsupported systems and symlink state files.
• Run tests using real temp directories and subprocesses, not mocked locks.

second, err := Acquire(dir, "host-one")
if second != nil || !errors.Is(err, ErrBusy) { t.Fatal("host lock bypassed") }

Task 2: Persistent idempotency and state transitions

Files: internal/state/operation.go, snapshot.go, operation_test.go.

Interfaces: Begin(id, planHash string) (Operation, bool, error); Get(id string) (Operation, error); Advance(id string, revision uint64, next Status) (Operation, error).

• Tests: duplicate ID/hash returns original with created=false; same ID/different hash conflicts; reopened state persists; unrelated new operation blocked by unresolved prior operation; stale revision and running-to-running rejected; terminal results immutable.
• Tests: corrupt/truncated/oversized/host-mismatched snapshots rejected; write failure poisons session and never returns success; surviving running state is not silently reset.
• Implement canonical checksummed snapshot, bounded read, unique temporary file, file sync, atomic rename and Linux directory sync. Any persistence failure requires closing/reopening and checking the actual state.
• Run full tests and real killed-child recovery test. Abrupt process death is not a power-loss durability test.

again, created, err := session.Begin("op-one", hash)
if err != nil || created || again.Revision != 1 { t.Fatal("duplicate submission changed state") }

Task 3: Verification and documentation

• Run gofmt, go test ./... -count=1, go vet ./..., native CLI smoke tests and Linux cross-build including state tests.
• Independent read-only code review; repair actionable findings with regression tests.
• Update docs/implementation-status.md and internal/state/README.md with lifecycle, trusted-root requirements, residual risks, and remaining systemd/executor work.

Additional evidence: Ubuntu WSL full suite and go test -race ./internal/state passed. Windows symlink tests skipped for unavailable privilege; both passed on Linux. Regression tests cover missing initialized snapshots and 113,357-record capacity boundary.