Metadata

name: fable-run
description: Launch, manage, and verify live applications across CLI binaries, web servers, TUIs, Electron apps, and background daemons with readiness probes and clean teardown. Use when starting development servers, executing live smoke tests, testing interactive CLI binaries, or driving runtime smoke verification — even if the user does not explicitly say "fable-run" (e.g. "start the dev server", "launch the app", "test the running CLI", "smoke test the web app"). Do NOT use for static analysis or unit testing without a running process (use fable-verify).
version: 1.3.0
pack: system
inputs: ["app_target"]
requires: ["built_artifact"]
produces: ["runtime_evidence","smoke_proof"]
gates: ["process_clean_exit","status_200"]
fallback: fable-recover
mutatesWorkspace: false
parallelSafe: false
neural_links: {"precursors":["fable-dataviz","fable-execute"],"continuations":["fable-verify","fable-release"],"lateral_peers":["fable-verify"],"recovery":"fable-recover"}

Fable Run

Execute the real artifact in a bounded environment and collect runtime evidence without confusing "process started" with "application works."

Mission

Runtime work needs lifecycle ownership: exact command/artifact, working directory, environment, ports, readiness criteria, output bounds, timeout, and cleanup.

A server PID, HTTP 200 from the wrong process, or CLI exit 0 that never exercised the feature is not sufficient proof.

Activate When

a server/service must run to verify behavior;
a built/published CLI or executable needs a smoke test;
browser/runtime integration requires a live process;
a runtime path differs materially from unit-test/source execution;
verification needs empirical entrypoint/lifecycle evidence.

Do Not Activate When

unit/integration tests can prove behavior without a persistent live process (fable-verify);
code still needs implementation (fable-execute);
repeated runtime failure/staleness needs diagnosis (fable-recover);
launching the process would cause an unauthorized/destructive external side effect.

Runtime Classification

Target	Important controls
one-shot CLI	cwd/env/args, exit, stdout/stderr, side effects
HTTP server	port ownership, readiness, health vs feature probe, cleanup
worker/daemon	startup readiness, queue/input fixture, termination
browser app	server URL, browser readiness, console/network errors
packaged binary	exact artifact/version/path, clean environment
multi-service	dependency startup order, ports, teardown, correlation

Protocol

Stage 1 — Identify the exact artifact

Record:

command/binary path;
version/hash/build if relevant;
cwd;
required environment/config;
expected process type;
safe input/probe;
destructive/external side effects to avoid.

Do not assume foo on PATH is the artifact just built—resolve it when identity matters.

Stage 2 — Establish resource ownership

Before launch determine:

requested/available port;
whether an existing process owns it;
temp directories/files;
child-process behavior;
timeout/budget;
cleanup method.

Never kill an unrelated process merely to acquire a preferred port.

Stage 3 — Launch with bounded observation

Capture PID/process handle, stdout/stderr, startup errors, and timestamps. Use output/timeout limits so a noisy/hung service cannot consume unbounded resources.

Stage 4 — Distinguish startup from readiness

A successful spawn only means the OS accepted the process.

Readiness may require:

port accepting connections;
health endpoint with expected payload;
dependency initialization complete;
CLI command reaches expected branch;
browser page loads without fatal console/runtime errors.

Use a bounded readiness loop with backoff rather than a fixed arbitrary sleep when possible.

Stage 5 — Probe the behavior that matters

Health 200 proves health only. If the changed feature is /checkout, probe the smallest safe checkout behavior/contract rather than concluding from /healthz alone.

Record request/input and relevant response/side effect.

Stage 6 — Detect wrong/stale process

If output contradicts source/build expectations, check:

resolved executable/import path;
process start time;
port owner PID;
build/artifact hash;
cwd/env;
old server still running.

Route repeated ambiguity to recovery before changing product logic.

Stage 7 — Terminate cleanly

Stop only processes/resources owned by this run. Wait for clean exit where feasible, escalate termination only within the owned process tree, and remove temporary resources.

Stage 8 — Record runtime evidence narrowly

State what the run proves: entrypoint launches, endpoint behavior observed, shutdown clean, etc. Hand broader correctness to fable-verify.

Decision Rules

Port conflict with unknown process → choose another safe port or inspect owner; do not indiscriminately kill it.
Spawn success without readiness → keep waiting/probing within budget, not PASS.
Health success without changed-feature probe → only health claim passes.
Fixed sleep for readiness is weaker than bounded condition polling; prefer observable readiness.
Runtime output unchanged after source change → prove artifact/process identity before another code mutation.
One-shot CLI that intentionally exits nonzero can still be a valid tested error path; compare exit/output to expected contract rather than requiring 0 universally.
External production-like side effect requires explicit safe scope/authorization; prefer local fixture/sandbox when available.
Background processes must have ownership and cleanup even if the test itself fails.

Invariants

Exact runtime artifact/process identity is knowable when used as evidence.
No unrelated process is killed.
Spawn, readiness, behavior, and shutdown are separate claims.
Runtime probes are bounded by time/output/resources.
Owned background resources are cleaned on success and failure.
Evidence does not claim more than the actual probe exercised.

Failure Taxonomy

Spawn failure

Executable missing, permission/config/startup error. Inspect command/artifact/env before retry.

Readiness failure

Process alive but service never becomes usable. Capture startup logs/dependencies and diagnose.

Wrong-process evidence

Port/path points to an older/unrelated process. Resolve identity, do not mutate product.

Feature probe failure

Runtime is ready but target behavior is wrong. Return to verify/execute/recover based on clarity.

Hang/leak

Process or child does not terminate. Inspect lifecycle/cleanup; force only owned tree within bounds.

Environmental mismatch

Behavior depends on cwd/env/OS/runtime version. Record and reconcile rather than treating as product fact universally.

Anti-Patterns

sleep 5 && curl /healthz as universal runtime proof;
assuming PID created means ready;
using 200 from health endpoint to prove unrelated feature;
killing whatever owns port 3000;
leaving server running after failure;
testing a PATH-installed old binary instead of candidate artifact;
ignoring stderr because process stayed alive;
unbounded log capture or polling;
performing real destructive transactions for a smoke test without need.

Runtime Packet

Artifact/command/version:
CWD/env/config:
Owned resources/PID/port:
Readiness condition/result:
Behavior probe/result:
Stdout/stderr highlights:
Artifact/process identity checks:
Termination/cleanup:
What this proves:
What remains for verify:

Completion Criteria

Runtime execution completes when:

exact candidate process/artifact was launched under known context;
readiness was observed, not assumed;
relevant behavior was probed or evidence scope is explicitly limited;
stale/wrong process ambiguity is resolved;
owned processes/resources are cleaned;
evidence is handed to verification without overclaiming.

Progressive Resources

Deep guide: references/process-lifecycle-and-readiness.md
Existing protocol: references/runtime-process-management.md
Example: examples/live-server-smoke-check.md

fable-run

安装