<!-- task=m-iop-agent-cli-runtime/13_standalone_host_foundation plan=0 tag=API -->

# 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_config_fixtures` → `15+13,14_cli_command_tree` → `16+13,14,15_cli_binary_contract`: consume this host and close the command surface.
- `17+13_project_log_records` → `18+13,17_project_log_journal` → `19+13,17,18_project_log_sink`: consume lifecycle events through an interface and close durable presentation logs.
- `20+13_local_control`: consumes host snapshots/commands and owns the socket boundary.
- `21+13,14,20_client_process_manager`: consumes the host, user-local config fixture, and local-control operation seam.
- `22+16,19,20,21_logged_smoke`: validates the integrated product externally.
- `23+16,19,20,21,22_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:

```text
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

```bash
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.

```go
// 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

```bash
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

```bash
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

```bash
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`.
