Phase 1: Noetica workstation install and OS-native service model

[mdheller]

Scope

Initialize Phase 1 for making Noetica installable and runnable on macOS and Linux without coupling service supervision to Homebrew.

Corrected operating assumptions

• Homebrew is an installer/distribution path for the Mac workstation and developer bootstrapping.
• Homebrew must not be treated as the canonical service supervisor.
• Noetica should provide its own CLI entrypoint and lifecycle commands, similar in spirit to Codex / Claude Code style foreground operation.
• Long-running service mode must use OS-native supervision:
  • macOS: launchctl / LaunchAgent plist
  • Linux / SourceOS: systemd --user, systemd unit, or Quadlet where containerized
• Agent Machine remains the local runtime substrate for local providers/workers, but Phase 1 should not require live Agent Machine provider activation.
• AgentTerm is not on the critical path for Phase 1.
• Prophet Mesh in GCP is deferred until after Noetica install/provider abstraction works against external test providers such as GPT/Claude.

Phase 1 target

brew install SourceOS-Linux/tap/noetica should install a coherent Noetica workstation package that can be run in foreground or registered with OS-native service control.

Initial commands should include:

noetica version
noetica doctor
noetica configure
noetica start
noetica open
noetica smoke
noetica service install
noetica service start
noetica service status
noetica service stop
noetica service uninstall

noetica service ... must call through to the platform-native service adapter, not Homebrew services.

Required implementation plan

1. Add a Phase 1 install architecture document in docs/architecture/noetica-workstation-install-phase-1.md.
2. Add a small CLI wrapper or launcher contract for Noetica lifecycle commands.
3. Add macOS LaunchAgent template generation.
4. Add Linux systemd user unit template generation.
5. Add config path discipline:
   • macOS/Linux user config: ~/.config/sourceos/noetica/config.json
   • user state/logs under SourceOS-aligned user-state paths.
6. Add provider config for external test providers first:
   • OpenAI-compatible route
   • Anthropic/Claude route
   • placeholder SourceOS route
   • placeholder Agent Machine route
7. Add noetica doctor checks:
   • Node runtime present
   • Noetica build present
   • config present/valid
   • external provider key present or explicitly absent
   • Agent Machine installed or absent
   • SourceOS route configured/unconfigured
8. Add noetica smoke using external provider or dry-run mode.
9. Add Homebrew formula only after lifecycle contract is explicit.

Acceptance criteria

• Homebrew installs Noetica files and the noetica CLI.
• Running noetica start starts Noetica in foreground without service registration.
• Running noetica service install writes the correct OS-native service definition.
• Running noetica service start/status/stop uses launchctl on macOS and systemctl --user or SourceOS-compatible control on Linux.
• Noetica works with external GPT/Claude test providers before Prophet Mesh exists.
• Noetica does not require AgentTerm.
• Noetica detects Agent Machine but does not fail if Agent Machine is bootstrap-only.
• Prophet Mesh remains Phase 5 / later-provider work, not Phase 1.

Non-goals

• Do not use brew services as the canonical service abstraction.
• Do not require Prophet Mesh for first install.
• Do not require live Agent Machine provider activation for Phase 1.
• Do not include AgentTerm in the default install path.
• Do not add unrestricted memory persistence or policy bypasses.

[mdheller]

Phase 1 closeout — workstation install path

Phase 1 implementation packet is complete and ready for ordered review/merge.

Delivered PR stack

1. Document Phase 1 workstation install contract #21 — Phase 1 workstation install contract
2. Add Phase 1 Noetica CLI lifecycle wrapper #22 — CLI lifecycle wrapper
3. Add Phase 1 config and provider model #23 — SourceOS-aligned config/provider model
4. Implement Phase 1 provider smoke checks #24 — explicit provider smoke checks
5. Harden Phase 1 foreground start and open commands #25 — foreground start/open hardening
6. Add Phase 1 OS-native service adapters #26 — OS-native service adapters
7. Add Phase 1 release artifact layout #27 — release artifact layout
8. Add Noetica Homebrew formula SourceOS-Linux/homebrew-tap#3 — Noetica Homebrew formula

Merge order

Merge Noetica PRs in order:

#21 → #22 → #23 → #24 → #25 → #26 → #27

Then merge SourceOS-Linux/homebrew-tap#3.

The tap formula currently tracks the Noetica source branch for bootstrap. Once #27 is merged and an artifact is published, update the formula to use the release artifact URL and SHA-256 from the Noetica release receipt.

Acceptance status

Satisfied by the stack:

• noetica CLI surface exists.
• noetica version reports package metadata.
• noetica configure writes ~/.config/sourceos/noetica/config.json with env-var secret references only.
• noetica doctor and noetica doctor --json report config/provider/runtime readiness.
• noetica smoke --dry-run is non-networked and non-fatal.
• noetica smoke --provider <id> supports OpenAI-compatible and Anthropic routes and fails closed for disabled/deferred/missing-key states.
• noetica start runs foreground mode and uses configured/default host/port.
• noetica open opens the configured/default local URL.
• noetica service ... uses LaunchAgent/launchctl on macOS and systemd --user on Linux.
• Homebrew formula exposes noetica and does not introduce brew services as canonical supervision.
• Release artifact script emits tarball, SHA-256 record, and receipt.
• Prophet Mesh remains deferred.
• AgentTerm is not required.
• Agent Machine remains optional/detected only.

Remaining before Phase 2

• Let CI run across all stacked PRs.
• Merge in order.
• Publish the Noetica release artifact from Add Phase 1 release artifact layout #27.
• Update tap formula from source-branch bootstrap to release-artifact URL + SHA-256.
• Perform a Mac local install test:
  • brew install SourceOS-Linux/tap/noetica
  • noetica version
  • noetica configure
  • noetica doctor --json
  • noetica smoke --dry-run
  • noetica start
  • noetica service install/status/uninstall
• Perform Linux/SourceOS equivalent install/runtime test.

Phase 2 readiness gate

Phase 2 should not begin until the merged Phase 1 surface can be installed on the Mac workstation and can run through the CLI/config/doctor/smoke/start path without manual repo-local assumptions.

Recommended Phase 2 scope: SourceOS route integration and Agent Machine local-readiness handshake, while still using external providers as working test routes and keeping Prophet Mesh deferred until the hosted-provider phase.

[mdheller]

Phase 1 merge status update

Merged:

• Document Phase 1 workstation install contract #21 — Phase 1 workstation install contract

Stopped before #22 because the remaining stack became non-mergeable after #21 was squash-merged into main.

This is expected for a stacked branch series when the base branch advances by squash commit rather than preserving the original parent chain. Do not force-merge #22–#27 as-is.

Recommended repair path:

1. Restack Add Phase 1 Noetica CLI lifecycle wrapper #22–Add Phase 1 release artifact layout #27 onto the new main, preserving their content and ordering; or
2. Collapse Add Phase 1 Noetica CLI lifecycle wrapper #22–Add Phase 1 release artifact layout #27 into one fresh phase-1-noetica-integration branch from current main, then run the full validate workflow once.

I recommend option 2 because Phase 1 is now a coherent install surface and the remaining PRs are tightly coupled. After the integration PR lands, merge the tap formula PR SourceOS-Linux/homebrew-tap#3, updating it if necessary to point at the merged Noetica surface or published release artifact.

Phase 2 should not begin until the repaired Phase 1 implementation PR has green CI on current main.