mishkan-harness 0.2.6 → 0.2.7

package/payload/mishkan/agents/joab.md

@@ -62,7 +62,9 @@ finding:
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 ---
 

package/payload/mishkan/agents/joah.md

@@ -51,7 +51,9 @@ You document the specific project: its decisions, its operations, its history.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 MADR for ADRs. Keep a Changelog. Diátaxis quadrant.
 

package/payload/mishkan/agents/maaseiah.md

@@ -49,7 +49,9 @@ You collect and assemble. You do not decide and you do not produce work.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 No `/plan` (collect-only role).
 

package/payload/mishkan/agents/meremoth.md

@@ -54,7 +54,9 @@ You work the delivery layer: CI/CD, build, release automation.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 No `:latest`. SOPS for secrets.
 

package/payload/mishkan/agents/meshullam.md

@@ -56,7 +56,9 @@ change, the alternatives, what is affected, the rollback path.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 No `:latest`. All resources tagged. SOPS for secrets.
 

package/payload/mishkan/agents/nathan.md

@@ -59,7 +59,9 @@ approval needed. Capture the outcome as an ADR (MADR) for Sefer to publish.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Approval gate via `/plan`.
 

package/payload/mishkan/agents/nehemiah.md

@@ -81,7 +81,9 @@ stop, surface it, and wait.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Approval gate on consequential decisions via `/plan`.
 

package/payload/mishkan/agents/obed.md

@@ -48,7 +48,9 @@ prepared, optimised, delivered.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Core Web Vitals budgets (LCP < 2.5s, INP < 200ms, CLS < 0.1).
 

package/payload/mishkan/agents/oholiab.md

@@ -56,7 +56,9 @@ Plan before a **design-system or state-management architectural change**.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 pnpm only. WCAG 2.2 AA. Core Web Vitals budgets. TanStack Query/Router.
 

package/payload/mishkan/agents/palal.md

@@ -52,7 +52,9 @@ You work at the structural intersection: OS, virtualisation, networking.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Two root causes on non-trivial failures (e.g. an incident is often applicative + network).
 

package/payload/mishkan/agents/phinehas.md

@@ -61,7 +61,9 @@ constraint, the threat it addresses, which teams it binds, and the cost.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Two root causes on non-trivial failures. Approval gate via `/plan`.
 

package/payload/mishkan/agents/rehum.md

@@ -50,7 +50,9 @@ You watch for risk and advise. Reliability, SLOs, capacity, infra security postu
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 ---
 

package/payload/mishkan/agents/salma.md

@@ -58,7 +58,9 @@ Plan before any **state-management architectural change**.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 pnpm only. WCAG 2.2 AA. Core Web Vitals budgets.
 

package/payload/mishkan/agents/seraiah.md

@@ -61,7 +61,9 @@ engineering identity, conventions that span every project.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Diátaxis quadrant declared.
 

package/payload/mishkan/agents/shallum.md

@@ -57,7 +57,9 @@ data-safety implications, the rollback path, and what depends on the schema.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 ---
 

package/payload/mishkan/agents/shaphan.md

@@ -54,7 +54,9 @@ sources: [...]
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 ---
 

package/payload/mishkan/agents/shemaiah.md

@@ -46,6 +46,9 @@ verdict: resolved|partial|blocked
 confidence: high|medium|low
 gaps: [...]            # unanswered sub-questions
 curated_library_agreement: agrees|conflicts|not_covered
+curated_promotion_candidate: null | {name,url,problem_class,team,source_tier,why}
+                       # D-016: non-null ONLY when resolved + confidence≥medium +
+                       # not_covered + cross-project reuse. Nominates, never writes.
 ```
 
 ## Skills (invoke on demand)
@@ -57,7 +60,9 @@ curated_library_agreement: agrees|conflicts|not_covered
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 ---
 

package/payload/mishkan/agents/shevna.md

@@ -47,7 +47,9 @@ You embed with the teams and document what they produce.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 Diátaxis quadrant declared.
 

package/payload/mishkan/agents/uriah.md

@@ -59,7 +59,9 @@ finding:
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 No `/plan` (evaluate against known rules).
 

package/payload/mishkan/agents/zaccur.md

@@ -46,7 +46,9 @@ You keep the record and assemble Migdal's milestone report.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 No `/plan` (collect-only role).
 

package/payload/mishkan/agents/zadok.md

@@ -58,7 +58,9 @@ guarantees to be fixed, and what they bind.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 ---
 

package/payload/mishkan/agents/zerubbabel.md

@@ -57,7 +57,9 @@ why this shape, what consumes it, what is out of scope.
 
 Stateful operations hard stop. Sequence before implementation. Diagnose
 before fix. Durable solutions only. No scope expansion. No fabricated
-facts. English for all output.
+facts. Surface an unknown you cannot resolve up to the main session rather
+than guessing — a subagent cannot delegate onward (its Task tool is inert).
+English for all output.
 
 OpenAPI 3.1 contract before any endpoint. Approval gate via `/plan`.
 

package/payload/mishkan/cognee/.env.example

@@ -136,6 +136,17 @@ COGNEE_PORT=7777
 # Cognee 1.x defaults multi-user access control ON, whose handler is incompatible
 # with neo4j. Single-user self-host → disable it:
 ENABLE_BACKEND_ACCESS_CONTROL=false
+# ⚠️ ISOLATION (verified, cognee v1.1.0 + issue #2855/#1023): with access control
+# OFF on a Neo4j backend, cognee's `datasets=` filter is ADVISORY ONLY — silently
+# ignored; search runs the WHOLE graph. So projects sharing one Neo4j work store
+# are MUTUALLY VISIBLE (a query scoped to one project can return another's data).
+# RESOLUTION — ADR D-012: each project gets its OWN per-project work store
+# (embedded Ladybug container + volume, mishkan-work-<slug>), provisioned by
+# ensure-work-store.sh; isolation is by topology, not datasets=. This .env config
+# (GRAPH_DATABASE_PROVIDER=neo4j below) is the LEGACY shared work box; the
+# per-project stores override the graph provider to ladybug via
+# docker-compose.work.yml. While any project still uses the shared box, treat it
+# as a SINGLE TRUST DOMAIN: no secrets, no PII, opt-in + scrubbed ingest only.
 
 # Secured default user — OVERRIDE Cognee's built-in default_user@example.com + default
 # password. Even with access control off, set these so the well-known defaults don't work.

package/payload/mishkan/cognee/Dockerfile

@@ -31,6 +31,26 @@ WORKDIR /app
 RUN git clone https://github.com/topoteretes/cognee.git . \
  && git checkout "$COGNEE_MCP_REF"
 WORKDIR /app/cognee-mcp
+
+# MISHKAN overlay patch 1/2 — align cognee CORE to the pinned wrapper ref.
+# cognee-mcp pins the core LOOSELY against PyPI (>=1.0.0,<2.0.0), so uv sync
+# would install a different core version than the checked-out wrapper. That skew
+# is what makes the recall patch below collide with the core's own user= pass
+# ("authorized_search() got multiple values for keyword argument 'user'"). This
+# rewrites the core dep to a `@ file:///app` direct reference so uv builds the
+# core from the same checkout. Idempotent + fail-loud. Must run before uv sync.
+COPY --chown=cognee:cognee patches/cognee-mcp-core-align.py /app/_mishkan_core_align.py
+RUN python /app/_mishkan_core_align.py
+
+# MISHKAN overlay patch 2/2 — cognee-mcp recall()/search() omit `user=` (upstream
+# cognee issue #2855, unfixed through v1.1.2), which breaks the read/search path
+# with "'NoneType' object has no attribute 'id'". Apply to the checked-out
+# source before uv sync. Idempotent + fail-loud: the build fails if the anchor
+# call-sites move on a COGNEE_MCP_REF bump, so we never ship a silently-unpatched
+# (still-broken) image. Drop this COPY/RUN once a fixed cognee-mcp ref is pinned.
+COPY --chown=cognee:cognee patches/cognee-mcp-recall-user.py /app/_mishkan_patch.py
+RUN python /app/_mishkan_patch.py
+
 RUN uv sync --all-extras
 
 # Pre-create the persisted-storage root owned by cognee (uid 10001). A named

package/payload/mishkan/cognee/README.md

@@ -9,6 +9,17 @@ graph persistence is deferred until it's up.
 New to Cognee setup? Run the **cognee-quickstart** skill first — it walks the
 Python env, provider keys, and backend choices.
 
+> ⚠️ **Project isolation.** Per **ADR D-012**, each project gets its **own**
+> physically-separate work store — a lightweight cognee-mcp container with an
+> embedded **Ladybug** graph + its own volume (`mishkan-work-<slug>`, own port),
+> provisioned by `ensure-work-store.sh` at `/mishkan-init`. Isolation is by
+> topology, **not** cognee's `datasets=` filter: with
+> `ENABLE_BACKEND_ACCESS_CONTROL=false` (required on Neo4j) that filter is
+> advisory-only and does **not** isolate (cognee v1.1.0 / issue #1023).
+> **Legacy / transition:** the old shared `:7777` Neo4j work box holds all
+> projects in one graph — treat it as a single trust domain (no secrets/PII,
+> scrubbed opt-in ingest) until each project is migrated to its own store.
+
 ## Bring it up
 
 ```bash
@@ -34,28 +45,37 @@ nc -z localhost 7730 && echo "cognee-mcp (curated) up on :7730"
 ~/.claude/mishkan/scripts/seed-curated-library.sh   # targets mishkan-curated-mcp
 ```
 
-## Two stores (decision D-007)
+## Three stores (decisions D-007 + D-012)
 
 | Store | Containers | Port | Holds | MCP alias |
 |---|---|---|---|---|
-| **work** | `mishkan-cognee-*` | 7777 | per-project knowledge + `<client>_memory` | `cognee` (read+write) |
+| **per-project work** | `mishkan-work-<slug>` | own port | this project's knowledge — embedded **Ladybug**, physically isolated per project (D-012) | `cognee` (read+write) |
+| **session memory** | `mishkan-cognee-*` | 7777 | `claude_code_memory` only — shared per-client session memory (the kept Neo4j box) | `cognee-memory` (read+write) |
 | **curated** | `mishkan-curated-*` | 7730 | the cross-project reference library only | `cognee-curated` (read) |
 
-The curated library is **physically isolated** in its own Neo4j so project data
-(which can contain PII) never mixes with it. The curated box reuses the shared
-Ollama and the shared Postgres *server* (own database `curated_db`). The
-per-client memory dataset (e.g. `claude_code_memory`) is part of the **work**
-store and must not be pruned.
+**Per-project work (D-012):** each project gets its own isolated work store —
+a cognee-mcp container with an embedded Ladybug graph + its own volume, on its
+own port, provisioned by `ensure-work-store.sh` at `/mishkan-init`. Isolation is
+by topology (container + volume), **not** the `datasets=` filter (which is
+advisory-only on Neo4j with access control off — cognee v1.1.0 / issue #1023).
+
+**Session memory:** `claude_code_memory` is per-client session memory — one
+continuous thing across all your work, not re-derivable — so it stays in the one
+shared box (`:7777`, the `cognee-memory` alias) and is never pruned. `CACHING=false`
++ `COGNEE_MCP_AGENT_SCOPED=false` on the per-project stores keep both memory layers
+out of them, so memory cannot fragment.
+
+**Curated** is physically isolated in its own Neo4j so project data (which can
+contain PII) never mixes with the cross-project reference. It reuses the shared
+Ollama and Postgres *server* (own database `curated_db`).
 
 ## How agents reach it
 
-Claude Code connects via the project's `.mcp.json` (seeded by `/mishkan-init`
-from `~/.claude/mishkan/templates/mcp.json`), which declares **both** stores:
-`cognee` → work (`http://localhost:7777/mcp`) and `cognee-curated` → curated
-(`http://localhost:7730/mcp`). A **zero-container stdio alternative** is included
-in that template (`_stdio_alternative`): it launches `cognee-mcp` directly via
-`uv --directory <path-to-cognee-mcp> run cognee-mcp` with `LLM_API_KEY` — no
-container, no port. Use whichever fits.
+Claude Code connects via the project's `.mcp.json` (rendered by `/mishkan-init`
+from `~/.claude/mishkan/templates/mcp.json`), which declares **three** doorways:
+`cognee` → this project's own work store (its own port), `cognee-memory` →
+`http://localhost:7777/mcp` (shared session memory), `cognee-curated` →
+`http://localhost:7730/mcp` (shared reference).
 
 ## Transports (per cognee docs)
 

package/payload/mishkan/cognee/docker-compose.curated.yml

@@ -32,11 +32,26 @@ services:
     volumes:
       - curated_neo4j_data:/data
     healthcheck:
-      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:7474 >/dev/null 2>&1 || exit 1"]
+      # Conditional TCP probe WITH internal retries. Each invocation tries to open
+      # :7474 up to 3 times with a 2s gap and exits 0 on the first connect — so a
+      # momentary blip during the slow Neo4j+APOC cold-start does not register as a
+      # failure. bash /dev/tcp, NOT a wget HTTP GET (which takes 5-10s on a loaded
+      # Neo4j and blew the old timeout, false-flagging a healthy box and cascading to
+      # curated-mcp). The for-loop IS the retry; `&& exit 0` is the conditional
+      # success; `exit 1` fires only if all 3 attempts in the window fail.
+      test: ["CMD", "bash", "-c", "for i in 1 2 3; do (exec 3<>/dev/tcp/127.0.0.1/7474) 2>/dev/null && exit 0; [ \"$$i\" = 3 ] || sleep 2; done; exit 1"]
       interval: 15s
-      timeout: 5s
+      timeout: 10s
       retries: 5
-      start_period: 30s
+      # 240s: observed cold-start was 174s under full-stack I/O contention — right
+      # against the old 180s grace, so `compose up` declared the dependency failed
+      # ~4s before the health flip. 240s clears the observed worst case with margin;
+      # a too-long start_period only delays the first probe, never slows a healthy box.
+      start_period: 240s
+      # start_interval (Docker 25+): during start_period, probe every 5s instead of
+      # the 15s steady-state interval, so a healthy flip is detected within ~5s of
+      # the port binding — this removes the race, not just the larger grace.
+      start_interval: 5s
     networks:
       - shared
     security_opt:
@@ -59,11 +74,23 @@ services:
     ports:
       - "127.0.0.1:${CURATED_MCP_PORT:-7730}:7777"
     healthcheck:
-      test: ["CMD-SHELL", "python3 -c \"import socket; socket.create_connection(('127.0.0.1',7777),2).close()\" || exit 1"]
+      # Conditional probe WITH internal retries: connect up to 3 times (1s apart, no
+      # trailing sleep), exit 0 on the first success — absorbs a transient blip
+      # without flagging a failure. `$$i` is escaped so compose passes a literal $i
+      # through to the shell.
+      test: ["CMD-SHELL", "for i in 1 2 3; do python3 -c \"import socket; socket.create_connection(('127.0.0.1',7777),2).close()\" 2>/dev/null && exit 0; [ \"$$i\" = 3 ] || sleep 1; done; exit 1"]
       interval: 15s
-      timeout: 5s
+      timeout: 10s
       retries: 10
-      start_period: 90s
+      # 300s: cognee-mcp cold-start is slow (~4-5min — cognee lib import + graph
+      # init + ollama embedding warmup + DB migrations before it binds :7777). The
+      # old 90s grace flagged a still-booting container unhealthy on every cold
+      # start. A generous start_period only delays the first probe; it never slows
+      # a healthy container. Matches the shared :7777 box (base compose) at 300s.
+      start_period: 300s
+      # start_interval (Docker 25+): probe every 5s during start_period so the health
+      # flip is caught within ~5s of :7777 binding, not up to 15s later.
+      start_interval: 5s
     networks:
       - shared
     security_opt:

package/payload/mishkan/cognee/docker-compose.selfhosted.yml

@@ -52,17 +52,43 @@ services:
       NEO4J_PLUGINS: '["apoc"]'
       NEO4J_dbms_security_procedures_unrestricted: "apoc.*"
       NEO4J_dbms_security_procedures_allowlist: "apoc.*"
+      # Explicit heap + pagecache. Left unset, Neo4j auto-sizes conservatively
+      # against the cgroup limit and can GC-pause under a bulk cognify (APOC
+      # label/edge writes across many docs at once), making bolt briefly
+      # unresponsive -> the client sees "ServiceUnavailable ... Timed out" mid-
+      # ingest. Sized for the 4g limit below: heap initial==max (no resize pause)
+      # 1g + pagecache 1g leaves ~2g for off-heap + OS. Tune up for larger graphs.
+      NEO4J_server_memory_heap_initial__size: "1g"
+      NEO4J_server_memory_heap_max__size: "1g"
+      NEO4J_server_memory_pagecache_size: "1g"
     ports:
       - "127.0.0.1:${NEO4J_HTTP_PORT:-7716}:7474"   # Neo4j Browser
       - "127.0.0.1:${NEO4J_BOLT_PORT:-7709}:7687"   # bolt
     volumes:
       - neo4j_data:/data
     healthcheck:
-      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:7474 >/dev/null 2>&1 || exit 1"]
+      # Conditional TCP probe WITH internal retries. Each invocation tries to open
+      # :7474 up to 3 times with a 2s gap and exits 0 on the first connect — so a
+      # momentary blip during the slow Neo4j+APOC cold-start does not register as a
+      # failure. bash /dev/tcp, NOT a wget HTTP GET (the GET takes 5-10s on a loaded
+      # Neo4j and blew the old timeout, false-flagging a healthy box and cascading to
+      # cognee-mcp via depends_on). The for-loop IS the retry; `&& exit 0` is the
+      # conditional success; `exit 1` fires only if all 3 attempts in the window fail.
+      test: ["CMD", "bash", "-c", "for i in 1 2 3; do (exec 3<>/dev/tcp/127.0.0.1/7474) 2>/dev/null && exit 0; [ \"$$i\" = 3 ] || sleep 2; done; exit 1"]
       interval: 15s
-      timeout: 5s
+      timeout: 10s
       retries: 5
-      start_period: 30s
+      # 240s: observed cold-start was 174s under full-stack I/O contention (ollama +
+      # pg + both neo4j warming in parallel) — right against the old 180s grace, so
+      # `compose up` gave up ~4s before the health flip and declared the dependency
+      # failed. 240s clears the observed worst case with margin; a too-long
+      # start_period only delays the first probe, it never slows a healthy container.
+      start_period: 240s
+      # start_interval (Docker 25+): during start_period, probe every 5s instead of
+      # the 15s steady-state interval, so a healthy flip is detected within ~5s of
+      # the port binding. THIS removes the race (compose up giving up just before a
+      # 15s-cadence probe would fire) — the larger grace alone only narrowed it.
+      start_interval: 5s
     networks:
       - cognee_net
     security_opt:
@@ -70,8 +96,12 @@ services:
     deploy:
       resources:
         limits:
-          cpus: "1.5"
-          memory: 2g
+          # Raised 2g -> 4g (+cpus 1.5 -> 2.0): 2g was too tight for Neo4j+APOC
+          # under bulk cognify — heap+pagecache+off-heap collided with the cap and
+          # stalled the bolt server. 4g gives the configured 1g heap + 1g pagecache
+          # real headroom; the extra core shortens GC pauses.
+          cpus: "2.0"
+          memory: 4g
 
   postgres:
     image: pgvector/pgvector:pg16