iop/agent-task/m-iop-agent-cli-runtime/13_standalone_host_foundation/PLAN-cloud-G09.md

Standalone iop-agent Host Foundation

For the Implementing Agent

Filling implementation-owned sections in CODE_REVIEW-cloud-G09.md is mandatory. Run every verification command, paste actual notes/output, leave the active pair in place, and report ready for review. Finalization belongs only to the code-review skill. If blocked, record the exact blocker, attempted commands/output, and resume condition in implementation-owned evidence fields; do not ask the user, call user-input tools, create stop files, classify next state, archive logs, or write complete.log.

Background

The shared Go runtime packages exist, but there is no standalone application host that composes them into one device-local process. This foundation establishes an application-owned lifecycle and dependency boundary that later CLI, log, local-control, and client-process packets can implement independently.

Analysis

Files Read

• agent-ops/rules/project/rules.md
• agent-ops/rules/project/domain/platform-common/rules.md
• agent-ops/rules/project/domain/testing/rules.md
• agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md
• agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md
• agent-contract/inner/agent-runtime.md
• agent-contract/inner/iop-agent-cli-runtime.md
• packages/go/agentconfig/runtime_config.go
• packages/go/agentconfig/watcher.go
• packages/go/agentstate/store.go
• packages/go/agenttask/ports.go
• packages/go/agenttask/types.go
• packages/go/agenttask/manager.go
• packages/go/agentconfig/runtime_config_test.go
• apps/node/cmd/node/main.go
• apps/node/cmd/node/main_test.go
• Makefile
• go.mod

SDD Criteria

The approved SDD is agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md. This packet is a compatibility-preserving prerequisite rather than a check-on-pass Roadmap task. It prepares the host seams required by S10 (cli-surface), S11 (local-control), S12 (project-logs), and S15 (client-process-manager) without claiming their Evidence Map rows. The checklist therefore requires a lifecycle-only host with deterministic unit evidence and no provider, socket, process, or logging implementation.

Verification Context

No external verification handoff was supplied. Repository-native sources are agent-test/local/rules.md, agent-test/local/profiles/platform-common-smoke.md, and agent-test/local/profiles/testing-smoke.md; Go is available at /config/.local/bin/go as go1.26.2 linux/arm64 for a module declaring Go 1.24. Use fresh focused tests, a package race run, go vet, and git diff --check; cached test output is not acceptable. No external runner is needed.

Test Coverage Gaps

• No apps/agent package or host lifecycle test exists.
• Existing agenttask.Manager tests prove shared state transitions but not standalone ownership, startup rollback, or reverse shutdown ordering.
• No current test proves that application adapters remain outside packages/go/**.

Symbol References

None. This packet adds application-owned symbols and does not rename or remove an existing symbol.

Split Judgment

• 13_standalone_host_foundation: stable lifecycle/DI contract; PASS requires only ordered start, rollback, reverse stop, and context cancellation tests.
• 14+13_cli_surface: consumes this host and owns the command surface.
• 15+13_project_logs: consumes lifecycle events through an interface and owns durable presentation logs.
• 16+13_local_control: consumes host snapshots/commands and owns the socket boundary.
• 17+13,16_client_process_manager: consumes the host and local-control operation seam.
• 18+14,15,16,17_logged_smoke: validates the integrated product externally.
• 19+14,15,16,17,18_parity_cutover: performs final behavior disposition and production-route cutover.

This task is dependency-free. The later predecessor references are currently missing because their active complete.log files do not yet exist.

Scope Rationale

Do not add CLI commands, concrete provider adapters, socket transport, project-log serialization, subprocess ownership, or parity migration here. Do not change shared agenttask, agentstate, or agentworkspace semantics. The new agent domain rule is project-local; central agent-ops/rules/common/** remains untouched.

Final Routing

• evaluation_mode: first-pass
• finalizer: finalize-task-policy.sh pair
• build: closure complete, grade G09, route cloud, basis grade-boundary, filename PLAN-cloud-G09.md
• review: closure complete, grade G09, route cloud, basis official-review, filename CODE_REVIEW-cloud-G09.md
• large_indivisible_context: false
• positive loop risks: new application/domain bootstrap, multi-component lifecycle ordering (count 2)
• recovery signals: review rework 0, evidence-integrity failure false
• capability-gap evidence: none; G09 grade boundary selected

Implementation Checklist

• Bootstrap the project-only agent domain rule and map apps/agent/** before adding application code.
• Implement and test the standalone host lifecycle and dependency ports without duplicating shared runtime behavior.
• Add and test bootstrap composition with deterministic startup rollback and reverse shutdown.
• Run fresh focused, race, vet, formatting, and diff verification.
• Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

[API-1] Bootstrap the Agent Application Domain

Problem

agent-ops/rules/project/rules.md:69-87 has no mapping for the planned apps/agent/** application, so implementation would enter a new domain without a checked project rule.

Solution

Create the empty apps/agent directory, then use the routed domain-rule creation workflow to add a project-only rule before any Go source. Update only the project mapping:

Before (agent-ops/rules/project/rules.md:73-80)
apps/node/**, apps/edge/**, apps/control-plane/**, apps/client/**, packages/**

After
apps/agent/** -> agent-ops/rules/project/domain/agent/rules.md

The rule must define standalone daemon ownership, application-vs-common package boundaries, config/state locality, same-user control assumptions, test expectations, and explicit prohibitions against duplicating agenttask or provider runtime logic.

Modified Files and Checklist

• agent-ops/rules/project/domain/agent/rules.md — add the project-only domain rule.
• agent-ops/rules/project/rules.md — register apps/agent/** and document the new application root.

Test Strategy

No code test is needed. Verify the mapping is unique and every referenced rule path exists.

Verification

test -f agent-ops/rules/project/domain/agent/rules.md
test "$(rg -n 'apps/agent/\\*\\*' agent-ops/rules/project/rules.md | wc -l | tr -d ' ')" = 1

Expected: both commands exit 0.

[API-2] Add the Host Lifecycle Boundary

Problem

packages/go/agenttask/ports.go:19-25,40-349 exposes the host-neutral manager and its explicit execution ports, but no application owner coordinates those dependencies.

Solution

Add an application-owned host package. Define small Component and runtime-control ports, a Host that starts components in declared order, cancels the run context on failure, rolls back only started components, and stops in reverse order. Preserve error identity with joined errors and make repeated stop safe.

// apps/agent/internal/host/host.go
package host

type Component interface {
    Start(context.Context) error
    Stop(context.Context) error
}

Do not wrap or reimplement agenttask.Manager; the future bootstrap adapter supplies it as a component.

Modified Files and Checklist

• apps/agent/internal/host/host.go — implement lifecycle ownership.
• apps/agent/internal/host/ports.go — define narrow application-facing runtime/status ports.
• apps/agent/internal/host/host_test.go — cover order, rollback, cancellation, repeated stop, and error retention.

Test Strategy

Write table-driven tests TestHostStartStopOrdering, TestHostStartRollback, and TestHostStopIsIdempotent with deterministic fake components and an ordered trace.

Verification

go test -count=1 ./apps/agent/internal/host
go test -count=1 -race ./apps/agent/internal/host

Expected: both commands pass with no race.

[API-3] Add Bootstrap Composition

Problem

apps/node/cmd/node/main.go:1 demonstrates an application entry point, but the standalone host has no constructor that validates dependencies and exposes one run/close boundary.

Solution

Add a bootstrap module that accepts explicit application dependencies, rejects nil/duplicate component names, builds the host, and exposes deterministic Run/Close behavior. Keep construction side-effect free; starting providers, sockets, and client processes belongs to later packets.

Modified Files and Checklist

• apps/agent/internal/bootstrap/module.go — validate and compose host dependencies.
• apps/agent/internal/bootstrap/module_test.go — verify validation, lifecycle delegation, and startup failure cleanup.

Test Strategy

Write TestNewModuleRejectsInvalidDependencies, TestModuleRunDelegatesLifecycle, and TestModuleStartupFailureRollsBack.

Verification

go test -count=1 ./apps/agent/internal/bootstrap

Expected: package passes.

Dependencies and Execution Order

1. Complete API-1 before adding any apps/agent Go source.
2. Complete API-2 before API-3.
3. Run all final verification after the domain mapping and both packages exist.

Modified Files Summary

File	Item
agent-ops/rules/project/domain/agent/rules.md	API-1
agent-ops/rules/project/rules.md	API-1
apps/agent/internal/host/host.go	API-2
apps/agent/internal/host/ports.go	API-2
apps/agent/internal/host/host_test.go	API-2
apps/agent/internal/bootstrap/module.go	API-3
apps/agent/internal/bootstrap/module_test.go	API-3

Final Verification

gofmt -w apps/agent/internal/host/*.go apps/agent/internal/bootstrap/*.go
go test -count=1 ./apps/agent/internal/host ./apps/agent/internal/bootstrap
go test -count=1 -race ./apps/agent/internal/host ./apps/agent/internal/bootstrap
go vet ./apps/agent/internal/host ./apps/agent/internal/bootstrap
git diff --check

Expected: all commands pass; no shared runtime package is modified. After completing all code changes, fill implementation-owned sections in CODE_REVIEW-*-G??.md.