AgentFlow is an extensible AI agent orchestration platform. Its first planned use case is investigating CI/CD failures, while keeping the platform independent of Git providers, programming languages, and LLM providers.
This repository implements Foundation, the Laravel Control Plane, the Python Runtime, and queued execution integration: two applications, public health routes, isolated database roles, a Redis worker, a code-managed workflow catalog, authenticated APIs, and a deterministic LangGraph workflow backed by runtime-owned PostgreSQL persistence. Laravel creates runs, queues UUID-only jobs after commit, and workers call the runtime over authenticated internal HTTP, persist diagnoses/events, and reconcile uncertain outcomes. Python executions can also be requested directly on the internal network. External providers, agents, LLM calls, webhooks, and UI are not implemented.
flowchart LR
Client -->|127.0.0.1:8080| API[Laravel control plane]
Worker -->|internal HTTP| Runtime[Python execution plane]
API --> Public[(PostgreSQL: public)]
Worker[Laravel worker] --> Public
API --> Redis[(Redis queues)]
Redis --> Worker
Runtime --> Private[(PostgreSQL: agent_runtime)]
Laravel owns the public API, authorization, workflow management, execution lifecycle, persistence, and queues. Python owns orchestration and future agents, tools, and model integrations. Both schemas live in one PostgreSQL instance; each application receives a restricted role. Redis belongs to Laravel.
The Laravel worker calls Python through internal HTTP. The
public APP_API_TOKEN and internal AGENT_RUNTIME_TOKEN are independent.
APP_API_TOKEN protects /api/v1/* with static Bearer authentication. The
runtime token protects /v1/executions and /v1/executions/{execution_id}. Both health
endpoints are intentionally unauthenticated and
return exactly {"status":"ok"}.
See the foundation architecture decision. The Control Plane decision and API contract describe persistence, idempotency, and state transitions. The Python Runtime decision and API contract describe synchronous execution, fixture inputs, runtime migrations, and reservation semantics. Executed Task 03 checks are recorded in the Runtime validation report. The queued integration decision and Task 04 validation report cover dispatch, retries, reconciliation, and the real Redis/worker E2E. The recovery hardening decision describes the follow-up audit corrections.
- Docker Engine or Docker Desktop with a working daemon and Compose v2.20+
(including
up --wait). Run commands from the repository root. - Internet access for initial image/package downloads.
- Python 3.12+ to generate local configuration or run Python locally.
- For host-side PHP tests: PHP 8.4, Composer 2.8+, and PostgreSQL/Redis PHP extensions, in addition to Laravel/PHPUnit's standard PHP extensions.
The containers provide PHP 8.4, Laravel 12, Python 3.12, FastAPI, LangGraph, PostgreSQL 17, and Redis 7.4. No Node, frontend build, or LLM key is required.
Generate a local development .env from the documented root template:
python3 infrastructure/docker/generate-local-env.pyThe script uses Python's cryptographically secure secrets module. It generates
a 32-byte Laravel application key and separate random values for both tokens,
the administrator password, both database-role passwords, and Redis. It creates
.env with mode 0600, prints no secret values, and refuses to overwrite an
existing file. Review .env locally; do not commit it or paste its contents into
logs. .env files are excluded from Git and Docker build contexts.
For manual setup, copy .env.example to .env, restrict permissions with
chmod 600 .env, and replace every empty secret. Generate each token/password
with a separate python3 -c 'import secrets; print(secrets.token_hex(32))' call.
Generate APP_KEY with
php -r 'echo "base64:".base64_encode(random_bytes(32)).PHP_EOL;'.
These commands print values for you to copy privately; the helper above avoids
printing them. Do not reuse the public token for the internal service.
Important settings:
| Variables | Purpose |
|---|---|
APP_KEY, APP_ENV, APP_DEBUG, APP_URL, APP_PORT |
Laravel configuration and loopback host port; debug defaults to false |
APP_API_TOKEN |
Static Bearer credential for /api/v1/* |
AGENT_RUNTIME_TOKEN, AGENT_RUNTIME_URL |
Internal execution API credential and worker HTTP destination |
AGENT_RUNTIME_CONNECT_TIMEOUT, AGENT_RUNTIME_HTTP_TIMEOUT |
Connection/response timeouts in seconds, default 2/10 |
AGENTFLOW_JOB_TIMEOUT, REDIS_QUEUE_RETRY_AFTER |
Job timeout/Redis visibility interval, default 60/90 seconds |
AGENTFLOW_RETRY_DELAY_FIRST, AGENTFLOW_RETRY_DELAY_SECOND |
Progressive retry delays, default 10/30 seconds; maximum three job attempts |
AGENTFLOW_RECONCILE_AFTER |
Stale running threshold, default 300 seconds |
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD |
Database name and bootstrap administrator; administrator credentials go only to PostgreSQL |
DB_USERNAME, DB_PASSWORD |
Laravel role with access to public |
AGENT_RUNTIME_DB_USERNAME, AGENT_RUNTIME_DB_PASSWORD |
Python role with access to agent_runtime |
REDIS_PASSWORD, REDIS_DB, REDIS_CACHE_DB, REDIS_QUEUE |
Redis authentication, logical databases, and queue |
QUEUE_CONNECTION, CACHE_STORE, SESSION_DRIVER |
Redis queues and file-based cache/sessions; no supporting SQL tables needed |
Compose derives both applications' database names from POSTGRES_DB. Keep
the internal hostnames, ports, and runtime schema at their template defaults
for this topology. Database role names must be distinct lowercase identifiers
of at most 63 characters. The API and worker receive the runtime token for
outbound HTTP; Python never receives the public token or Laravel's
database credentials. Do not use unredacted docker compose config output in
shared logs; use --quiet to validate without printing secrets.
docker compose config --quiet
docker compose build
docker compose up -d --wait --wait-timeout 120
docker compose ps
docker compose logs --tail=100 api worker agent-runtime postgres redisStartup waits for meaningful PostgreSQL/Redis health checks; no startup sleeps
or automatic migrations run. PostgreSQL readiness authenticates with both
application roles and checks schema grants. Redis readiness requires an
authenticated PING. The worker check verifies a queue worker process and
Redis connectivity. The application checks verify HTTP liveness; they do not
promise that future workflows are ready or that jobs are being processed.
Only Laravel is published, at 127.0.0.1:8080. Python, PostgreSQL, and Redis have
no host-published ports and use an internal Compose network. The API joins that
network plus a normal public bridge for host port publishing. Only the API
has outbound connectivity through this additional bridge. Application
processes run as UID 10001. PostgreSQL and Redis use their official images'
privilege-dropping entrypoints. The PHP development server and images containing
test dependencies are intended for local development, not production serving.
The API builds agentflow-api:local once; the worker reuses that local image
without building or pulling it. Build the API image before starting only the
worker.
After code or dependency changes, rebuild the application images and recreate the affected services:
docker compose up -d --build --wait --wait-timeout 120
docker compose stop
docker compose downstop and down preserve the named PostgreSQL and Redis volumes. Redis uses
AOF persistence. Do not add --volumes when you need to preserve local data.
Application filesystem caches are disposable; workflow runs and events are
persistent PostgreSQL records.
After rebuilding the PHP image, explicitly apply the additive migrations with the restricted Laravel database role, then register the code-managed catalog:
docker compose exec -T api php artisan migrate --force
docker compose exec -T api php artisan db:seed --class=WorkflowCatalogSeeder --forceStartup never runs migrations or seeders. The seeder can be rerun and retains
the catalog workflow UUID while restoring pipeline-investigation, version
1.0.0, enabled. Review migrations before applying them to an existing database;
do not use migrate:fresh, db:wipe, or volume deletion.
All v1 endpoints require Authorization: Bearer <APP_API_TOKEN>. Supply the
credential privately in your HTTP client; do not paste real tokens into shared
commands or logs. Responses use API Resources with a data envelope.
| Method | Endpoint | Behavior |
|---|---|---|
| GET | /api/v1/workflows |
Enabled catalog entries ordered by slug |
| POST | /api/v1/workflow-runs |
Create or reuse a run; HTTP 202 |
| GET | /api/v1/workflow-runs/{id} |
Status, input, output/error, attempts and timestamps |
| GET | /api/v1/workflow-runs/{id}/events |
Chronological events, 100 per page; ?page=2 for the next page |
POST body:
{"workflow":"pipeline-investigation","input":{"fixture":"phpunit-failure"}}input must be a JSON object; nested arrays/objects are supported and strings
retain whitespace and empty values. PostgreSQL JSONB cannot store null
characters, and nonfinite numbers are rejected. Optional Idempotency-Key
accepts 1–255 visible ASCII characters without spaces. The key is global across
workflows. Reordered object keys reuse the same run, while a different workflow,
catalog version, or input returns 409. Without a key, every POST creates a run.
Replays return the existing run's current status with HTTP 202 and no new event.
Invalid credentials return 401, validation failures 422, missing runs 404;
errors consistently contain message and validation failures also errors.
The workflow-specific fixture contract is checked asynchronously by Python.
A structurally valid object with an unknown fixture creates a run which later
fails with INVALID_INPUT; the public creation endpoint still returns 202.
Apply the additive Laravel migration after building the new PHP image, then recreate API/worker so long-lived workers load the new code:
docker compose build api
docker compose run --rm --no-deps -T api php artisan migrate --force
docker compose up -d --no-deps --wait --wait-timeout 120 api workerThe Task 04 migration adds private workflow name/version snapshots, an outbound
request marker, next-attempt time, and safe retry diagnostics to workflow_runs.
It does not change public statuses, Python tables, or database grants. Existing
runs are backfilled from the current catalog; their original historical version
cannot be reconstructed if that catalog changed before this migration.
The winning creation transaction registers dispatch after the outermost commit.
Idempotent public replays do not enqueue another job. Jobs always use Redis and
carry only the run UUID; the worker reloads the row, claims pending → running
atomically, and uses that UUID unchanged as Python's execution_id. A session
advisory lock coordinates workers/reconciliation for that run. SQL transactions
are short and do not span HTTP calls.
Jobs have at most three deliveries/processing attempts, with delays of 10 then
30 seconds by default. attempts counts processing starts; a normal execution
has one. Runtime identity/input remain stable across retries. HTTP automatic
retries and redirects are disabled. The configuration must satisfy:
0 < connect_timeout <= http_timeout
job_timeout > 3 * http_timeout + 5
redis_retry_after > job_timeout + http_timeout + 5
The client checks these bounds before HTTP. Defaults 2/10/60/90 satisfy them.
Up to three HTTP calls can occur in an attempt (lookup, POST, recovery lookup).
The extra Redis margin also allows a final GET during the failed-job callback.
The worker's stop grace period is 90 seconds.
Docker restarts an unexpectedly exited worker with restart: unless-stopped.
This includes Laravel's process exit on a hard job timeout. A stopped worker is
not restarted until the operator starts it; Docker health alone is a liveness
check, so use a real queued fixture to verify processing.
Before POST, Laravel durably records that the request may have been sent.
Timeout, connection loss, 429, malformed replies, and retryable 5xx trigger a
GET lookup. Completed results are reused; failed results are terminal; running
results defer processing. An unknown/unavailable outcome never authorizes a new
POST. Only a validated EXECUTION_NOT_FOUND response permits another POST with
the same UUID. Exhaustion produces RETRY_EXHAUSTED, with a safe cause such as
RECOVERY_INCONCLUSIVE. No timeout cancels or proves termination of Python.
Local lifecycle events and imported Python step events are persisted with the
terminal transition in a transaction. Python event UUID uniqueness prevents
duplicate imports. A normal execution has run.created, run.started, six
step events, and run.completed. Inspect the final diagnosis through the
existing public run and events GET endpoints.
To recover stale pending/running runs manually:
docker compose exec -T api php artisan agentflow:reconcile-runs
docker compose exec -T api php artisan agentflow:reconcile-runs --run=<run-uuid>The command visits all eligible runs using UUID keyset pagination in batches of
100 and the same per-run lock. It performs GET only and recovers completed/failed
outcomes. An active or unknown remote state is never reexecuted. Only a validated
EXECUTION_NOT_FOUND permits publishing another UUID-only job, within the existing
three-attempt budget. A private dispatch_requested_at marker throttles repeat
publication for AGENTFLOW_RECONCILE_AFTER seconds. Publication happens after
releasing the lock so a fast worker can acquire it. No scheduler is installed
automatically; run the command periodically through your deployment scheduler.
Recovery has no leases, fencing, outbox, or resume protocol. An interrupted
Python execution may remain running. Laravel can fail explicitly after retry
exhaustion while Python later completes; terminal Laravel failures are not
automatically reopened. Pending runs left by a commit-to-publication crash can
be recovered by the command. A detected publication error returns a safe HTTP
503 and leaves the run pending with QUEUE_UNAVAILABLE in its private diagnostic
and run.dispatch_deferred in its timeline. Reuse the public idempotency key
after a 503; a replay returns the same run. Recovery records run.dispatch_requested.
This is periodic repair, not a transactional outbox or exactly-once delivery.
Runtime request bytes are capped before JSON parsing, including bodies without
Content-Length (AGENT_RUNTIME_MAX_REQUEST_BYTES, default 1 MiB). Oversize
requests return safe HTTP 413 / INVALID_INPUT. Laravel's runtime client streams
responses with a hard byte cap (AGENT_RUNTIME_MAX_RESPONSE_BYTES, default
1 MiB) and an absolute HTTP deadline. It rejects compressed responses and closes
oversize streams before decoding JSON. The public Laravel API retains its
existing PHP request limit (8 MiB by default).
Rebuild/recreate the runtime after code or dependency changes, then explicitly apply its additive migrations using the restricted runtime role:
docker compose build agent-runtime
docker compose up -d --no-deps --wait --wait-timeout 120 agent-runtime
docker compose exec -T agent-runtime python -m agent_runtime.migrateThe migration command creates only agent_runtime.schema_migrations and
agent_runtime.executions; it never changes Laravel tables, schemas, or grants.
Startup does not apply migrations. Before migration, /health still reports
process liveness while execution requests return a generic internal error.
The runtime has no published host port. Call http://agent-runtime:8000 from
the internal Docker network, using Authorization: Bearer <AGENT_RUNTIME_TOKEN>
for both execution endpoints. Keep the actual token private in your HTTP client.
| Method | Endpoint | Behavior |
|---|---|---|
| GET | /health |
Public liveness; exactly {"status":"ok"} |
| POST | /v1/executions |
Synchronous execution; 201 for a new result, 200 for a completed replay |
| GET | /v1/executions/{execution_id} |
Persisted execution, result/error, step events, and timestamps |
POST body:
{
"execution_id": "79d4428a-68a1-41dc-a168-02072cce968b",
"workflow": {"name": "pipeline-investigation", "version": "1.0.0"},
"input": {"fixture": "phpunit-failure"}
}Supported fixtures are phpunit-failure, dependency-failure, and
successful-pipeline. Each supplies bounded synthetic evidence. The successful
pipeline returns successful_pipeline with no remediation actions. There are
no external network/model calls. Evidence describes fixture observations only.
Diagnosing a failing pipeline is a completed execution; runtime failed means
the workflow itself could not produce a diagnosis.
The execution UUID is the durable idempotency key. Equal workflow identity and
input reuse completed results after restart. A different request returns 409
EXECUTION_CONFLICT; an equal running request returns 409
EXECUTION_IN_PROGRESS. Failed executions return the persisted failure with
HTTP 500 EXECUTION_FAILED and are never automatically reexecuted. GET returns
200 for any existing status, including failed/running. Events are stored as
JSONB in the execution row. Crash recovery, leases, retries, and automatic
takeover are outside Task 03; an interrupted process may leave a running row.
Validation failures return 422 INVALID_INPUT; unknown workflow/version returns
404 WORKFLOW_NOT_FOUND. Errors use {"error":{"code":"...","message":"..."}};
failed POST responses also include the persisted execution. See ADR 0003 for
the full contract, including missing executions and internal failures.
curl --fail http://127.0.0.1:8080/api/health
docker compose exec -T api php -r 'echo file_get_contents("http://agent-runtime:8000/health"), PHP_EOL;'
docker compose exec -T worker php /usr/local/bin/worker-healthcheck.phpUse your configured APP_PORT instead of 8080 if changed. The second command
tests Python from another service on the internal Docker network.
docker compose exec -T api php vendor/bin/phpunit
docker compose exec -T agent-runtime python -m pytest
docker compose exec -T postgres sh -c 'psql -X -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"' < tests/e2e/database-isolation.sql
sh tests/e2e/validate.shThe integration script validates Compose, builds images, waits for healthy services, checks API health through its published host port and inside the container, checks runtime health, runs PHPUnit/Pytest, tests role isolation, and checks the worker. It leaves containers running. The isolation test creates probe tables inside a transaction, checks own-schema writes and denied cross-schema reads/writes/DDL, then rolls everything back.
Authentication, validation, normalization and enum tests need no database.
Database integration tests are skipped unless AGENTFLOW_TEST_DATABASE names
an explicitly provisioned PostgreSQL database ending in _test. They never
substitute SQLite or reset the application database. To provision a dedicated
test database once using the existing Foundation roles and schema isolation:
docker compose exec -T postgres sh -c 'createdb -U "$POSTGRES_USER" agentflow_control_plane_test'
docker compose exec -T -e POSTGRES_DB=agentflow_control_plane_test postgres sh /docker-entrypoint-initdb.d/10-init.sh
docker compose exec -T -e AGENTFLOW_TEST_DATABASE=agentflow_control_plane_test api php vendor/bin/phpunit --fail-on-skippedThe provisioning command reapplies the same configured role names/passwords
and schema grants to the test database. If the database already exists, skip
createdb; inspect its state rather than dropping it. Tests run additive
migrations on this database and roll back fixtures. Concurrency tests commit
UUID-scoped fixtures, coordinate two separate HTTP-kernel processes at their
database INSERTs, and remove only those fixtures. They require proc_open.
The test role must be able to see its own sessions in pg_stat_activity (the
PostgreSQL default). No Redis or Python service is used by these Laravel tests.
Provision a separate Python test database once, then opt in explicitly:
docker compose exec -T postgres sh -c 'createdb -U "$POSTGRES_USER" agentflow_runtime_test'
docker compose exec -T -e POSTGRES_DB=agentflow_runtime_test postgres sh /docker-entrypoint-initdb.d/10-init.sh
docker compose exec -T -e AGENT_RUNTIME_TEST_DATABASE=agentflow_runtime_test agent-runtime python -m pytest -q -W errorIf the database already exists, skip createdb. Python tests require a database
name ending in _test, apply runtime migrations with the runtime role, and
remove only UUID-scoped rows belonging to each test. They never reset schemas
or delete volumes. Without AGENT_RUNTIME_TEST_DATABASE, database tests are
reported as skipped; an opted-in connection failure fails the suite. The restart
test starts two successive local Uvicorn processes inside the test container.
Pytest's container cache directory is writable by UID 10001.
To include both applications' database tests in the full stack validation:
AGENTFLOW_TEST_DATABASE=agentflow_control_plane_test AGENT_RUNTIME_TEST_DATABASE=agentflow_runtime_test sh tests/e2e/validate.shFor the real Laravel → Redis → worker → Python E2E, provision a third dedicated database once with both existing application roles/schemas:
docker compose exec -T postgres sh -c 'createdb -U "$POSTGRES_USER" agentflow_integration_test'
docker compose exec -T -e POSTGRES_DB=agentflow_integration_test postgres sh /docker-entrypoint-initdb.d/10-init.sh
python3 tests/e2e/execution.pySkip createdb if the database exists. The E2E requires current built images and
healthy base services. It explicitly applies additive migrations/catalog setup
only to agentflow_integration_test, then starts three temporary test services
without published ports, using a UUID-scoped Redis queue. Before starting its
worker it asserts that an idempotent public replay leaves exactly one queued
job. It also creates a committed pending run without publication and verifies
that reconciliation queues it once. All three fixture scenarios must complete
through the real HTTP/queue path.
Only test-owned runs/executions, that unique queue, and those temporary containers
are cleaned; existing services, databases, and volumes are retained. No Laravel
code directly accesses Python tables. Override AGENTFLOW_E2E_DATABASE only with
another explicitly provisioned database ending in _test.
To exercise automatic worker restart and recovery after a lost successful response, use the same isolated E2E with an explicit fault opt-in:
AGENTFLOW_E2E_CRASH_WORKER=1 python3 tests/e2e/execution.pyOnly the test worker is killed, after Python responds successfully and before Laravel persists/acknowledges the result. Docker must restart it, Redis must redeliver the reserved job, and the worker must recover by GET with exactly one runtime POST. The test uses 1/2/15/25-second connect/HTTP/job/Redis timeouts to keep redelivery short while preserving the production timeout inequalities.
To include this E2E in the full validation script:
AGENTFLOW_TEST_DATABASE=agentflow_control_plane_test AGENT_RUNTIME_TEST_DATABASE=agentflow_runtime_test AGENTFLOW_E2E_DATABASE=agentflow_integration_test sh tests/e2e/validate.shFor host execution, set the same variable and configure the DB_* connection
for your dedicated PostgreSQL server; the test harness overrides only the
database name. No administrator credentials are needed by PHPUnit.
Host-side tests, when the required dependencies are installed:
cd apps/api
composer install
composer test
cd ../..
python3.12 -m venv apps/agent-runtime/.venv
apps/agent-runtime/.venv/bin/python -m pip install './apps/agent-runtime[test]'
apps/agent-runtime/.venv/bin/python -m pytest apps/agent-runtime/testsThe health tests require neither a database nor Redis. Laravel receives real
configuration from Compose rather than an image-baked .env. The optional
apps/api/.env.example documents Laravel-native variables for host execution;
copying it is unnecessary for the health test. Avoid creating a second .env
unless you need to run Artisan locally.
PHP dependencies are locked in apps/api/composer.lock. Python's direct and
test dependencies are pinned in pyproject.toml; a fully resolved Python
transitive lock is not included. Image tags deliberately follow the selected
runtime release lines rather than immutable digests.
See the original Foundation validation report
for its historical environment limitations. The PHP Docker image build and all
47 Laravel tests against a dedicated PostgreSQL database passed on 2026-11-04;
details are recorded in
the Control Plane validation report.
On an empty postgres-data volume, the official image creates the database
and runs 10-init.sh. The script creates two application roles and the runtime
schema, removes broad public privileges, grants each role access only to its
own schema, and sets each role's database-specific search path. The administrator
owns both schemas; application roles cannot create schemas, administer roles,
or obtain the other application's grants. No application tables are created.
On an existing volume, PostgreSQL skips initialization scripts. Changing
passwords or names in .env therefore does not update database roles. Scripts
also do not automatically resume after a partially failed first initialization.
Inspect the logs and existing database before taking action.
For an existing Foundation database, after reviewing/backing up its state, you can deliberately reapply application-role provisioning:
docker compose up -d postgres
docker compose exec -T postgres sh /docker-entrypoint-initdb.d/10-init.shThis is repeatable for the same role names and retains tables/data, but it updates application passwords, restores schema ownership/ACLs and default privileges, and removes direct cross-schema table/sequence grants. It rejects application roles with existing role memberships. It does not rotate the bootstrap administrator password, rename old roles, or repair arbitrary legacy ownership/function grants. Keep role names stable and review legacy databases separately. Changing the administrator password requires an explicit PostgreSQL administrative operation, not just an environment edit. Recreate services after changing environment values:
docker compose up -d --force-recreate --wait --wait-timeout 120- Docker socket permission denied: confirm Docker is running and your shell is authorized to use its daemon. The validation script cannot run without it.
- API is healthy but its host port is unreachable: verify with
docker compose port api 8000; expect127.0.0.1:8080(or yourAPP_PORT). The API must join bothinternaland the normalpublicbridge, since a container attached only to an internal network may have no published binding. After applying the Compose fix, rundocker compose up -d --force-recreate --no-deps --wait apiand retrycurl --fail http://127.0.0.1:8080/api/health. - Package/image downloads fail: check DNS, registry/PyPI/Packagist access, and proxies. Do not disable TLS verification to work around download failures.
- Composer cannot create
/app/vendorduring image build: the API Dockerfile must assign/appitself toagentflowbefore running Composer; ownership of copied files alone is insufficient. Rebuild the API and worker withdocker compose build apiafter applying the fix. - Build export fails with
agentflow-api:local: already exists: only the API service should define the shared PHP image build. The worker reuses its image; inheriting the build in both services can cause concurrent exports to the same tag. Apply the Compose fix and rerundocker compose build. - Compose reports a missing variable: generate
.envor fill the named value. An existing.envis preserved by the generator; it is not repaired automatically. The API entrypoint rejects equal public and internal tokens. - PostgreSQL stays unhealthy: inspect its logs and verify role passwords, schema grants, and persistent-volume history. Follow the existing-volume instructions; do not delete data to conceal an initialization failure.
- Worker fails with missing tables: keep
QUEUE_CONNECTION=redis,QUEUE_FAILED_DRIVER=null,CACHE_STORE=file, andSESSION_DRIVER=file. There are deliberately no users, sessions, cache, or queue-job migrations. - Python is unreachable from the host: use the internal health command above; Python's port is intentionally not published.
- Edits do not appear in containers: source is copied at build time; rebuild images. No host source bind mount hides installed dependencies.
After a normal Git checkout, check local secret exclusion with
git check-ignore .env and inspect git diff --cached before committing.
Never force-add secrets or generated dependency/build directories.
Queued Laravel-to-runtime execution is implemented. External pipeline providers, LLMs, advanced crash recovery, webhooks, and UI remain outside the current scope.