# Installed AWC coordination

## Authority and package ownership

The canonical AWC sources in this checkout are `packages/core` (`@fyso/agent-work-context` 0.1.1) and `packages/cli` (`@fyso/awc` 0.1.2). The root remains `@fyso/objective-guard` (0.1.2). AWC coordinates the installed `awareness` and `oguard` executables via PATH; each engine retains its own authority and version. Awareness Framework 0.5.0 and Objective Guard 0.1.2 are the local validation targets.

The earlier package boundary was recovered from the historical Objective Guard checkout at commit `a5b55e299f87b4cbf0b36c095d469bbddde78546`. Only the coordinator package boundary was brought forward; the historical checkout's divergent commits and vendored engine trees were preserved. The installed CLI no longer relies on that checkout. The corrected core replaces development-only paths and legacy-global-board reads with runtime CLI adapters.

## Lifecycle

AWC binds context, task, repository/worktree, branch, objective, round and contract hash. It reads Awareness through `awareness status --context-scope worktree`. Session isolation remains controlled by Awareness's existing session environment. Repository labels such as `fyso-dev/objective-guard` are not mistaken for absolute filesystem paths.

- `start` attaches only to a matching active round; bootstrap/successor definitions are sent to the guard. Repeated checks and obligations are preserved.
- An unrelated active context is rejected. A blocked context may be explicitly superseded under a new identity after the guard's clean-tree requirement is met; the previous context is journaled.
- `pause` and `resume` synchronize Awareness state. Pausing AWC does not change the guard's edit authorization. Closed contexts stay terminal.
- `close` invokes installed `oguard round-end --mode final --json`, requires `pass` and verifies that the guard lifecycle is closed before marking Awareness done.
- A partial Awareness transition leaves `recovery-required` with a pending state. Repair the executable and retry that same command. Do not delete the context to conceal partial state.
- `status`, `check` and `handoff` report coherence. `check` exits nonzero on mismatches. A terminal, consistently closed context is valid.

Local `.awc/` state is excluded from Git. Transactions use an exclusive lock and append-only journal. Locks are never reclaimed solely by age; after a crash, inspect the PID before manually removing a stale lock. Coordination does not validate strategic usefulness or establish independent outcome labels.

## Build and installation

```bash
npm run package:awc -- /tmp/awc-pack
npm install -g /tmp/awc-pack/fyso-awc-0.1.2.tgz
awc --version
awc status --json
```

The packer bundles the exact core dependency through an offline staging directory. The installed tarball needs no sibling monorepo directories. Install the engine CLIs independently into the same chosen npm prefix. Local tarball installation is not npm registry publication.

When consolidating existing global installations, inspect `type -a awc awareness oguard` and package versions first. Retain one authoritative prefix; back up prior packages and owned hook configurations before removing duplicate installations. Do not remove unrelated packages or user hooks.

## Hooks

`oguard-hooks install --harness all` installs one owned pre-edit gate, post-edit observer and prompt hook per harness, preserving other integrations. It migrates the known earlier `.codex/hooks/awc-prompt.sh` and `.claude/hooks/awareness-prompt.sh` registrations. When a Codex legacy wrapper supplied Awareness itself, the installer replaces that behavior with a dedicated Awareness user-prompt hook.

An independent Awareness prompt disables duplicate Awareness reads in the guard prompt. AWC guidance is included when its executable is on PATH, without an additional `awc status` process on every prompt. The Codex gate has no `Edit|Write` matcher, so it can inspect Codex patch payloads; Claude retains that matcher. The Claude pre-edit gate is installed even when it was previously missing.

## Verification and limits

`npm run test:awc` packs and installs the CLI into a temporary prefix and exercises real engine CLIs in temporary external Git repositories with private Awareness homes and guard inventories. It covers full lifecycle, successor rounds, reference mismatch, failing verification, recovery and worktree routing. These tests explicitly skip when the engine executables are absent; a skipped run is not installation evidence. `test/prompt-context.test.mjs` verifies idempotent migration and preservation of unrelated hooks.

Run the full suite, documentation guard and normal round-end dogfooding after changes. A passing integration test demonstrates these declared paths, not universal crash recovery, every shell environment or the statistical utility of Objective Guard.