Devflow hands an authorized development goal to a configured local delivery service, which investigates the repository, plans the work and publishes an unmerged PR. The Temporal runtime provides the service, dashboard, CLI and MCP interface. Native macOS execution uses the frozen agent-runtime-kit dependencies and measured command permissions.
The local delivery plugin exposes the service
through one devflow-local-delivery skill. Packaging and normal installation
register entry points; service configuration, authentication and runtime startup
are separate operations.
Normal installation needs Python 3.12+, Git and a POSIX shell. Set
DEVFLOW_PYTHON to choose a supported interpreter; the installation helpers use
only the standard library. Delivery needs an existing configured local service,
an allowlisted repository and the user's linked issue and authority to publish
an unmerged PR. Follow the runtime setup and
desktop/plugin setup for those prerequisites.
Project tools and GitHub authentication retain their own requirements.
Use a trusted release checkout for setup. Set RELEASE_TAG to the
chosen published release. main
and open PRs contain unreleased work.
git clone --branch "$RELEASE_TAG" https://github.com/ebarti/devflow.git
cd devflow
sh scripts/install.shThe normal installer creates or verifies the independently owned checkout at
~/.local/share/devflow/developer-workflow, with its own Git objects and frozen
runtime environment (uv is required). Registrations point into that durable
checkout, so removing the setup checkout or allowing managed worktree cleanup
does not remove the installed code, dependencies, helpers or entry points.
The installer proves the actual imports and installed wheel contents before
exposing the sole devflow-local-delivery service skill
and copies four internal agent definitions as regular files. If a matching
installed local delivery plugin already provides that skill, installation
preserves it without creating a duplicate direct entry. The devflow path
contains script/reference helpers for retained work and has no SKILL.md.
The other direct-agent skills in the source checkout are not globally installed.
Defaults are ~/.agents/skills and $CODEX_HOME (~/.codex when unset).
Use explicit locations for another host configuration:
sh scripts/install.sh /path/to/host/skills /path/to/codex-homeNormal installation does not configure MCP, install metrics
hooks, activate a launchd reconciler or change global model settings. Existing
foreign hooks, host configuration and user data are preserved. Internal agent
copies are tracked by agents/.devflow-agent-manifest.json; installation
refreshes unchanged owned copies and removes obsolete unchanged owned copies.
Modified or custom copies are preserved. --force retains the existing agent
installer's checkout-switch behavior; it does not bypass migration checks or
replace custom files.
Global delivery commands require the explicit operation described in
the launcher installation contract.
scripts/install.sh --delivery-launchers exposes the canonical
devflow-delivery and devflow-delivery-mcp environment and configuration.
It can migrate the recognized historical devflow command into an alias of
devflow-delivery, retaining the old immutable release and guarded rollback.
Normal installation does not migrate a CLI or activate a service.
For a source trial, explicitly select isolated destinations:
sh scripts/install.sh --development /path/to/trial/skills /path/to/trial/codexDEVFLOW_INSTALL_MODE=development provides the same explicit mode for historical
updaters that cannot forward new flags. Development mode preserves source links
and refuses the user's production registration directories. It does not provide
a durable installation proof. Production launcher and supervisor registration
reject temporary/managed source, shared Git objects, indirect environment/import
dependencies, or temporary configuration and persistence roots.
Hosts with additional cleanup roots can supply DEVFLOW_MANAGED_WORKTREE_ROOTS
as a JSON array of absolute paths; the checks resolve configured aliases before
testing every dependency. Production source must use the fixed independently
owned installation root, including when launcher/service registration is invoked
from another checkout.
An interrupted installation retains its journal alongside the durable checkout.
Replay the same setup request to reconcile it, or run sh scripts/install.sh --rollback to restore registrations and retain the unfinished owned checkout.
Rollback never deletes run state, configuration or histories. Existing native
execution grants and acknowledged runtime locations must use the supported
stopped runtime-installation migration; normal setup does not rewrite them.
Foundation-born owners can prepare an independent immutable source generation:
sh scripts/update.sh --prepare "$RELEASE_TAG"
# Use the exact prepared.json path printed by preparation. Preflight reads only.
sh scripts/update.sh --preflight /absolute/generation/prepared.json > request.json
chmod 600 request.json
sh scripts/update.sh --apply "$PWD/request.json"Preparation proves the new source, independent Git storage, frozen environment, imports, bundled CLI and direct controller entries at their final paths. Apply rechecks the captured request under the installation's exclusive lifetime lease, preserves previous source/environment/evidence, journals registration and owner changes, and activates the new generation last. A process still holding the shared lifetime lease prevents the transition. The previous fixed-root entry then refuses operational startup because it no longer owns the installation. Normal updates after generation activation use this explicit protocol.
The supported cohort is a foundation-born complete owner inventory containing empty stores or nonnative deliveries whose authentic closed SDK evidence grants only metadata projection bodies, with settled registered resources. A fake provider can still run accepted-plan prerequisites; every started host-capable activity or child remains unknown without independent body closure. Unknown stores, historical owner populations, native grants, existing native installation acknowledgements, feature cohorts, host checks and diagnostic actors remain typed refusals. A row labelled closed does not establish custody. Original submitted requests, configuration snapshots, authorization, repair budgets, candidates, start journals and histories are not rewritten by source rollover.
An interrupted activation blocks operational starts. Its external
.production-update.json records an independent retained recovery command; use
that exact command even if the caller's checkout/interpreter has disappeared.
sh scripts/update.sh --rollback-generation /absolute/request.json invokes the
same inverse while the caller remains available. Rollback requires unchanged
captured tracking and enrollment state, preserves foreign replacements, and
retains both generations and each inverse object for reconciliation. Newly
admitted or enrolled work must be reconciled before rollback.
After activating a generation, a new service can receive a separate private writer namespace from an authorized configuration template:
sh scripts/update.sh --allocate-namespace /absolute/template-config.jsonThis command allocates a random configuration/state/tracking directory and task
queue, bootstraps its schema through the active SDK under exclusive custody, and
publishes a completed allocation witness. It starts no service or delivery. The
pinned state helper requires the exact active SDK/interpreter before opening a
writable connection to this database. Admission consumers hold fresh_namespace_scope(config) and revalidate
its witness across admission, dispatch and resume. This boundary covers supported
adapters using the allocated unedited configuration and its pinned helper;
arbitrary independently configured legacy writers remain outside that proof.
An existing or shared outbox cannot be declared fresh by setting a flag.
Fresh namespace operations use managed starts through the installed console or service entry. Direct or already-running SDK processes must restart through a managed entry before using the namespace.
Before application imports, the retained bootstrap holds the actual source lifetime lease, verifies the active source manifest and clean Git revision/tree, and checks the pinned interpreter and site registrations. Python ignores ordinary bytecode caches for this path. A read-only per-process descriptor binds startup to the source birth and held lease; API/worker children receive a fresh witness before their imports. Namespace scope checks bind the exact allocated config, state and tracking objects, original config digest, loaded SDK origins and source file identities. A process that imported the SDK outside this qualified path restarts through the installed entry before performing fresh namespace work.
This contract coordinates supported loaders and updaters: generations are retained and never edited by an updater, and an updater needs the exclusive lifetime lease. Checks detect ordinary drift in the SDK, state helpers and installation helpers that the namespace imports. The trusted bootstrap, interpreter/standard library and pinned site remain platform dependencies; advisory locking and checks do not exclude arbitrary same-user transient edits or monkeypatching. Ordinary development and nonnamespace console/service operations retain their existing startup contract. Namespace-bound managed starts require source qualification and never silently fall back when qualification fails.
Between tasks, select a published release and update the durable owner:
sh scripts/update.sh "$RELEASE_TAG"
# For a custom installation, reuse its original locations:
sh scripts/update.sh "$RELEASE_TAG" /path/to/host/skills /path/to/codex-homeThe production updater operates on the durable owner even when invoked from a
disposable setup checkout. It requires the worker and supervisor to be stopped,
fetches the tag, switches to its commit, synchronizes the frozen environment and
reconciles registrations. Source/environment recovery and registration snapshots
remain journaled until verification. Replay an interrupted update or use
sh scripts/update.sh --rollback; failed recovery retains its journal for retry.
Before changing dependencies, the updater verifies an independent complete copy
of the old environment. Rollback exchanges that copy back into place without
network access or dependency resolution. The journal also records a recovery
command using a separately proved base interpreter and retained controller;
use that command if the candidate has broken its own updater script.
Acknowledged native installations require their supported stopped authority
transition before changing source/environment. Existing guards remain enforced.
The ordinary updater currently supports fresh-owner fake-backend source updates.
Native source-successor acknowledgements and authenticated legacy-owner enrollment
remain tracked in #237; those updates
currently refuse. This installation foundation does not complete those transitions.
New durable owners register every configuration loaded by the CLI/API, including
custom state roots, under the same installation lock. Missing databases and
unknown custody refuse an update. A legacy owner has no complete inventory merely
because a directory scan found nothing: it requires an authenticated stopped
cutover before ordinary updates can be enabled. Original native authority and
historical run records are retained throughout that transition.
Production console entries acquire a shared lifetime ownership lease through a
retained stdlib bootstrap before importing the mutable environment or source.
CLI/API/worker processes keep that lease until exit; the updater requires the
exclusive lease. Concurrent configuration readers use a separate short inventory
lock. An interrupted update keeps new operational starts blocked until its
retained recovery command reconciles the source and environment.
The installer prints immutable production command paths beside the runtime.
Global launcher and launchd registrations call those retained bootstraps directly;
they do not execute a mutable console script while uv replaces the environment.
The .venv/bin scripts are internal environment entries. Use the printed commands
or explicitly registered global launchers for production startup.
Use a supported DEVFLOW_PYTHON; a retired historical interpreter need not exist. Tracked source edits stop
an update. No database migration or service activation occurs in this normal
installation path.
Upgrades from previous direct-agent installations retire only unchanged owned
skill pointers and the recognized metrics hook registrations. Guarded installs
must have an owned .devflow-install.json pin whose hashes match the historical
Git inventory, and an unchanged .devflow-hook.py. The published v0.2.2 installer
predates these manifests: that case requires its exact verified historical Git
inventory, owned canonical source and skill symlinks, unchanged current source
files and all of its exact generated telemetry hook registrations. Arbitrary
unrecorded registrations are not migration candidates. The exact historical recipe
must use one consistently serialized canonical absolute interpreter prefix across
all generated events; its hook target, arguments, item fields and groups must
match. Historical installers supported Python 3.12+ and canonicalized the selected
executable without restricting its filename. The retired interpreter is never
executed. Old manifests did not record its value or version, so this recognizes
the generated recipe with a consistent historical interpreter; it cannot cryptographically prove that an unknown old interpreter
value was never edited. Inconsistent prefixes, quoting, arguments, events and
modified owned files still refuse before effects.
The migration atomically exchanges the devflow pointer for script-only
helpers under the skills directory, preserving source files and keeping helper
paths available. Other unchanged owned direct skills are removed from discovery.
Foreign hook entries and metadata remain. A modified, unowned or ambiguous
registration stops installation with its precise path and reason, even with
--force. Restore the recorded bytes/pointer or relocate the conflicting
registration and retry. Do not delete source helpers or user data to resolve a
registration conflict.
Private snapshots live in the owned Codex directory or its nearest owned protected ancestor, outside the OS temporary-directory policy. A group-writable Codex directory uses that ancestor without changing its permissions. Backup/target filesystems and real native exchange are checked before destination effects. Snapshot file bytes, mode and identity come from one opened-file observation; a write during that read refuses capture before installation effects. On preflight or zero-effect capture refusal, destinations are left untouched and the authenticated previous checkout is restored, including updates begun by the historical exec-based updater. After an installer effect, rollback restores only matching recorded object identities; later changed or foreign objects remain, with an actionable path and retained private backup. Destination recovery failure still attempts authenticated source checkout recovery. Recovery continues independent paths after object errors; helper cleanup waits for pointer recovery. All conflicts and the backup remain until the operator recovers them. Successful installation removes its rollback snapshot. Public refusals return status 1; the installer never excludes other writers. Owned destination pointers use native atomic exchange on Linux/macOS before helper cleanup; unsupported hosts refuse without a replacement fallback. Native exchange and capture require the private backup and target on the same filesystem. Forward writes authenticate the displaced object in that backup; retirement and rollback cleanup capture objects before authenticating and deleting them. Concurrent drift refuses installation and retains foreign bytes and the full backup at the reported paths. Upgrades begun by the historical updater also restore its previous detached checkout when it remains clean; newer updater failures restore their previous branch or commit. SQLite, unrelated host files and background services remain outside this operation. Retained work must finish before changing its installed source.
Install the local delivery plugin, connect it
to the configured service and use devflow-local-delivery for an authorized
request, such as fixing the retry bug in a linked repository issue. The service
reports its public policy and owns role selection, planning, implementation,
review and verification. Missing issue or delivery authority requires a blocking
decision. A submission authorizes publication through an unmerged PR;
merge, release and deployment require separate authority.
The GitHub feature delivery model uses the
parent issue as the feature, sub-issues as workstreams, and one stack for complete
incremental chunks. Feature mode coordinates parallel implementation, preserves
ownership and repair accounting across continuations, and supports reviewed plan
corrections within the original authority. Version 2 records keep detailed plans
on the child issues and a compact revision index on the parent. The public
revise_feature_plan operation requests native investigation and review of a
planning defect; it preserves the existing stack and cumulative repair budget.
An explicit merge instruction follows verification. Project updates are handled
by the independent event consumer.
Use the dashboard or the plugin's status/evidence operations to inspect a run. Blocking decisions carry the exact run and candidate identity. A fresh host task may be needed after registration for plugin discovery. The normal installer supplies internal roles rather than independent global role skills.
Historical direct-agent skills, candidate trial tooling and standard-library state/metrics helpers remain in the source tree for existing work and explicit inspection. Their documentation describes those historical interfaces; normal installation does not activate their hooks, collect their metrics or start their reconciler. The work records reference and storage contract describe retained helper storage, separate from the delivery service's runtime configuration.
sh scripts/check-install.sh
python3.12 -B -m unittest discover -s tests -vInstallation checks use isolated temporary skills and Codex-home directories. They cover fresh installation, authentic historical upgrades, replay, refusal and failure rollback through the public installer/updater. Updater tests create tags only in their disposable local Git fixtures, because the public updater requires a release tag fetched from its origin. CI fetches history for these historical fixtures and separately checks the runtime and dashboard. These checks do not perform live installation, model-driven delivery, target-project checks, merges or deployment.
The runtime suite runs in two macOS jobs with two pytest parents per host.
runtime/runtime_ci.py collects the full suite in each parent and assigns whole
modules to four partitions using the measured weights in runtime/ci_timings.json;
new modules are included automatically. Host 0 runs partitions 0 and 2, and host 1
runs partitions 1 and 3. Cases within a module retain their order and run in one
parent. Host 0 completes the Mac source checks before starting its runtime parents.
Each job uploads its test inventory, result and JUnit timings. The required
temporal-runtime-macos check passes only when both Mac jobs and the portable
source job pass, and all four partition reports prove every collected test
finished exactly once at the same Git revision.
Update the timing weights from the uploaded results as the suite grows. From
runtime/, uv run --frozen pytest still runs the complete suite. To run one
partition locally:
uv run --frozen python runtime_ci.py --index 0 --count 4 --revision "$(git rev-parse HEAD)"Keep future tests focused on high-value user, workflow, integrity and security regressions or integration behavior. Do not add small isolated unit tests, implementation-mirror assertions or trivial parameter expansions. Prefer extending an existing meaningful scenario when it covers the risk. See AGENTS.md for the repository contribution rules, including conventional PR titles.
Automatic retries keep the accepted plan and frozen per-issue attempt ceiling. Later cleanup and acknowledged Blocked/claim release can finish after that ceiling is exhausted, but cannot create another attempt. Cleanup maintenance preserves exact recorded resource evidence before updating canonical latest observations; interrupted maintenance reuses and authenticates the immutable archive. If the original finalizer returned no bound receipt, maintenance preserves that absence in the closed result and separately archives authenticated recovery-time observations. Any declared receipt hash remains mandatory. Completed provider journals without the original result binding remain unresolved rather than inferred clean. Ordinary closed unpublished deliveries also support public cleanup after exact accepted implementation custody is proven; cleanup records its own unpublished closure and releases only that run's claim. A passed implementation interrupted at prechecks can then resume those checks without another implementation turn. A provider turn with an unknown outcome can only seed an explicitly authorized new finite iteration from its exact supervisor-recorded partial output, in a fresh session/home; its original verdict stays unknown. A continuation stopped in preflight before its new iteration can reuse that exact unused iteration and existing ceiling with zero added iterations after public cleanup; it must retain the same source, inventory, session absence and unused home. Historical resource observation authenticates membership under the current admitted execution. These continuations require a worker with the corresponding recovery readers, so drain all open native workflows before a supported runtime update.
A closed ordinary implementation may resume with one or two explicitly authorized tracked files when its completed native assessment records blocked findings. The existing stopped-resume path authenticates the original SDK completion, private native receipts, session, retained partial source and exact amended configuration at admission and worker readback. It preserves the blocked result and spends only unused original iterations; every normal gate still applies. See the scope-resume contract.
A separate closed-run browser setup amendment can acknowledge only the reviewed JOBCTRL_E2E_ISOLATED transition from 1 to 0 for the same two selected scenarios. Fresh registration keeps its isolated default. The amendment binds private proposal/configuration bytes, original failed per-case evidence, reviewed owned fixture sources and an immutable acknowledgement, then requires both original cases to pass a fresh native gate. It preserves fake actions/transports, owned profile/data paths, all other recipe settings, normal gates and the original finite repair ceiling. See the browser setup amendment contract.
Private scope/browser amendments also bind the canonical live service scheduling limit independently of their frozen policy. A historical capacity 6 remains recorded as 6; a live limit 2 stays 2 in the private amendment and native supervisor. Original submitted owner provenance, exact compatible owner bytes and repeated readback prevent a caller's private file from raising that limit.
Closed ordinary native deliveries can explicitly bind official pinned Temporal test prerequisites for one unchanged check through stopped_delivery_resume.temporal_test_prerequisites; the Python project/lock, provenance, private tool generation and two supported environment paths are authenticated through worker launch. This setup declaration grants no extra iteration and waives no test or gate. See the runtime contract.