# Shell Entrypoint Cutover

Shell entrypoints may remain as stable operator, CI, bootstrap, and severe
recovery interfaces. New canonical governance/runtime logic, validation
orchestration, testing/proof orchestration, service status lookup, service
restart/recovery sequencing, and notification delivery claims must live in
Runtime Core or another typed Runtime-owned service and be exposed through
Runtime CLI or Runtime API methods.

## Canonical Ownership Rule

Runtime functionality and daemons are Node/TypeScript-owned by default. Shell is
allowed only for:

- human convenience commands that call a Runtime/Node method;
- bootstrap/startup wrappers that establish the Runtime process boundary;
- severe recovery when the Runtime/Node path is the failed component;
- tiny process facades where the real behavior remains in Runtime/Node;
- local inspection utilities such as `rg`, `sed`, `tail`, `ls`, and `git`.

Shell must not own business logic, service truth, notification truth, liveness
truth, validation/testing orchestration, state transformation, journal
consumption, daemon behavior, or restart/recovery policy when a Runtime/Node
service can own it. If shell remains on one of those surfaces, it is
compatibility-only and must be listed in the shell-entrypoints registry with
the reason, authority boundary, and migration target.

In local/dev fail-fast proof mode, an approved replacement retires the old
technology immediately. For example, when Node/TypeScript replaces a
shell-owned supervisor, validation, testing, or state-transformation surface,
the old shell entrypoints must be removed or marked retired rather than kept as
compatibility wrappers. Stale callers should fail loudly, repo-owned references
should be fixed immediately, and failure evidence should be recorded in the
active chunk. Compatibility may remain only for severe recovery, human
bootstrap/process startup, or an explicitly time-boxed migration proof with a
removal condition.

## Preferred Pattern

- Runtime Core owns typed parsing, classification, validation, rendering, and
  scheduling semantics.
- Runtime/API methods own validation, testing, browser proof, service actions,
  status lookup, and notification evidence. Human shell or `yarn` commands may
  invoke those methods, but must not duplicate the behavior or bypass journal,
  service-status, Socket.IO invalidation, or Runtime Executor notification
  paths.
- Daemons and long-running service controllers must be implemented in
  Node/TypeScript Runtime-owned modules unless they are explicitly classified as
  bootstrap or severe-recovery shell compatibility.
- Codex and new automation should use `node ai/runtime/dist/cli.js request`
  and `node ai/runtime/dist/cli.js batch` for normal Runtime API reads.
- `node ai/runtime/dist/cli.js snapshot --tier fast` is the default compact
  status query.
- `node ai/runtime/dist/cli.js validate --tier fast|chunk|full` is the
  canonical tiered validation entrypoint for Runtime Core-owned checks.
- `node ai/runtime/dist/cli.js testing frontend-specs --include <spec>` and
  `node ai/runtime/dist/cli.js testing backend-specs --include <spec>` are the
  canonical targeted workspace spec entrypoints. They may invoke workspace test
  runners internally as low-level primitives, but callers must use the Runtime
  wrapper so test intent, status, output tails, and Runtime State Journal
  evidence are recorded consistently.
- `node ai/runtime/dist/cli.js testing runtime-action-panel-browser-smoke` is
  the canonical browser proof entrypoint for Runtime Action Panel live behavior.
- `node ai/runtime/dist/cli.js shell-entrypoints` reports the registry-backed
  shell classification and must show zero unclassified shell scripts.
- Shell wrappers for migrated read-only behavior should be thin facades around
  Runtime CLI or Runtime API only when the migration decision explicitly keeps
  a human/CI facade.
- Shell wrappers for migrated side-effect procedures must be thin facades
  around Blueprint Runtime Executor methods and must fail closed if the Runtime
  API daemon is unavailable, unless fail-fast replacement mode has retired the
  wrapper entirely.
- Thin facades should fail closed when Runtime Core cannot render or validate
  the requested behavior.
- Wrappers may keep textual formatting for operator compatibility, but should
  not duplicate registry parsing or policy logic.

## Compatibility-Only Shell Internals

These remain shell-owned until a focused migration replaces their side effects
with equally guarded runtime adapters:

- `ai/tools/approved-action-dispatcher/dispatch.sh` for approved execution.
- `ai/tools/operator-daemon/run-once.sh` and registered daemon actions for
  trusted local execution.
- `ai/tools/runtime-supervisor/README.md` documents the retired shell
  supervisor and the typed Runtime/Node supervisor CLI. The old
  `ai/tools/runtime-supervisor/*.sh` entrypoints are retired and must not be
  recreated as compatibility wrappers.
- `ai/tools/telegram/` for live Telegram transport.
- `ai/tools/runtime-scorecard/scorecard.mjs` for broad legacy JSON/KV
  compatibility and shell/process probes.
- `ai/runtime/start-daemon.sh`, `ai/runtime/stop-daemon.sh`, and
  `ai/runtime/status.sh` for bootstrap and recovery.
- `ai/runtime/request.sh` for deprecated compatibility-only local Unix socket
  access.

## Converted Facades

- `ai/chunks/transition.sh` is a Runtime Executor facade for
  `runtime.executor.transition`.
- `ai/tools/operator-questions/ask.sh` is a Runtime Executor facade for
  `runtime.executor.createQuestion`.
- `ai/tools/telegram/send-run-summary.mjs` is a Runtime Executor facade for
  `runtime.executor.runSummary`.
- `ai/tools/telegram/send-message.mjs` is a Runtime Executor facade for
  `runtime.executor.enqueueTelegram`.
- `ai/tools/operator-notifications/post-run-recommendation.sh` is a Runtime
  Executor facade for run-summary/close-approval policy.
- `ai/governance/validators/validate-run-paths.sh` is a Runtime CLI facade.
- `ai/tools/operator-notifications/render-event.mjs` is a Runtime Core CLI
  facade and no longer carries a YAML parsing fallback.

## Guardrails

Do not introduce new shell-only implementations for behavior already owned by
Runtime Core. Prefer adding a Runtime Core method and a thin human convenience
facade.

Do not call shell scripts or workspace `yarn` commands directly to restart
services, run canonical validation/proof, run targeted workspace specs, look up
dashboard truth, or send operator notifications when a Runtime/API method exists
or should exist. Direct shell or direct `yarn` is allowed only for documented
bootstrap, severe recovery, human convenience, or process facade cases that
cannot use Runtime because Runtime is the failed component. Such exceptions must
be registry-classified and must record why the Runtime path was unavailable.

Do not expose arbitrary shell execution through Runtime API. Authority-state
mutation remains behind lifecycle transition tooling, approved-action
dispatcher, trusted operator daemon, or runtime supervisor boundaries.