Skip to content

feat: add an /ops lane for local runtime operations and previews #437

Description

@SUaDtL

Problem

codeArbiter requires every intent to enter through a command, but no command owns reversible local runtime operations such as starting a development stack, checking readiness, tailing logs, or opening a browser preview.

Observed friction in HomeCadence:

  1. The user asked whether the existing web app could be stood up for a preview.
  2. $ca-btw could inspect and answer, but its read-only gate correctly prohibited starting processes.
  3. The follow-up stand up the local app was off-channel. The redirect catalog had no accurate route; the closest available option was a logged $ca-override.
  4. The user then tried $ca-dev, but maintainer dev mode is correctly reserved for editing codeArbiter itself and requires CODEARBITER_DEV=1 plus audit logging.

A routine, reversible local preview should not require a governance bypass or misuse maintainer mode.

Proposal

Add an operational lane, tentatively /ops ($ca-ops on Codex), for running and observing existing project tooling without authoring source changes.

Representative intents:

  • stand up the local app
  • run the dev server
  • start/restart/stop the API and worker
  • open the local preview
  • show service status
  • tail the runtime logs

The lane should discover commands from project context (package.json, runbooks, Compose manifests, etc.), execute only local/reversible operations, keep durable runtime receipts, and remain distinct from feature/fix/chore implementation.

Suggested boundaries

  • MAY start, stop, restart, inspect, and health-check local processes and containers.
  • MAY open a local browser preview after readiness succeeds.
  • MUST track exact owned PIDs/containers and log locations so cleanup is narrowly scoped.
  • MUST NOT edit source, commit, push, deploy, or mutate task/decision ledgers.
  • MUST NOT expose environment values or credentials in output or logs.
  • MUST NOT perform destructive cleanup such as volume deletion, database reset, or broad process termination without an explicit destructive-action confirmation.
  • Database migrations and seed operations are durable mutations: surface them as an explicit sub-step with their own confirmation/risk classification rather than silently folding them into start.
  • $ca-btw remains read-only; $ca-dev remains codeArbiter-maintainer-only; ordinary local runtime work no longer needs $ca-override.

Acceptance criteria

  • Off-channel runtime phrases route to /ops instead of /feature, /btw, /dev, or /override.
  • /ops start [target], /ops status, /ops logs [target], /ops open, and /ops stop [target] have documented semantics.
  • Start reports concrete readiness evidence: command, PID/container identity, bound address/port, health result, and log location.
  • A partial startup reports which services are healthy and which failed, with actionable diagnostics.
  • Stop touches only resources started or explicitly targeted by the lane.
  • Runtime state is transient/gitignored and recoverable across interrupted sessions.
  • Host mappings are defined for Claude Code, Codex, and Pi.
  • The command catalog and redirect logic include the operational lane.

Why this belongs in core

This is not HomeCadence-specific. Any governed repository with a dev server, Docker Compose stack, preview environment, local worker, or test harness has the same gap between read-only Q&A and source-changing implementation. An explicit operational lane reduces bypass pressure while preserving codeArbiter's routing and safety model.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions