@openduo/duoduo 0.2.12 → 0.3.1

package/bootstrap/config/stdio.md

@@ -17,7 +17,16 @@
 #    Example:
 #    prompt_mode: append
 #
-# 3) Claude Agent SDK-aligned options (optional)
+# 3) time_gap_minutes (optional, number)
+#    Minutes of inactivity before injecting a time-context hint into the
+#    next user turn. Helps the agent sense elapsed time after idle gaps.
+#    Set to 0 to disable. Instance Descriptors override Kind Descriptors.
+#    Default: 60 (1 hour).
+#
+#    Example:
+#    time_gap_minutes: 30
+#
+# 4) Claude Agent SDK-aligned options (optional)
 #    These keys map directly to SDK query() options and may also be set on
 #    Instance Descriptors. Instance values override Kind values.
 #    Runtime defaults still apply underneath: ALADUO disables

package/bootstrap/subconscious/cadence-executor/CLAUDE.md

@@ -2,7 +2,7 @@
 schedule:
   enabled: true
   cooldown_ticks: 0
-  max_duration_ms: 300000
+  max_duration_ms: 120000
 ---
 
 # Cadence Executor
@@ -45,6 +45,9 @@ check the item off anyway.
 
 ## Guardrails
 
-- Queue empty? Do nothing. Don't look for work that isn't there.
+- Queue empty AND no pending inbox items? Return immediately with
+  exactly: `Queue empty. No pending work.`
+  Do NOT scan the system, check jobs, or investigate anything.
+  Just return the message.
 - Something fails? Leave it unchecked. Note the error. Move on.
 - At most 5 items per tick. Don't overrun my time budget.

package/bootstrap/subconscious/memory-weaver/.claude/agents/entity-crystallizer.md

@@ -70,7 +70,15 @@ secondary type in the entity body.
    If the orchestrator passed a gap list (missing files listed in
    `meta-memory-state.json` but absent from disk), note those for creation.
 
-3. **Scan recent fragments** (last 3-5 days in `fragments/`).
+   **Batch limit**: Process at most 20 gaps per tick. Prioritize the
+   most recently modified files on disk (`ls -t`). Leave remaining
+   gaps for the next tick — they will still be detected as gaps.
+   This prevents timeout when hundreds of files need indexing.
+
+3. **Scan recent fragments** — only read fragment date-directories
+   from the last 3 days (`ls -t memory/fragments/ | head -3`).
+   Within each directory, sort files by mtime and read newest first.
+   Stop when you have enough signal (typically 10-20 fragments).
    Look for mentions of:
    - **People**: names, pronouns ("he", "she", "they"), roles ("the user",
      "the admin"), identifying behavior patterns

package/bootstrap/subconscious/memory-weaver/.claude/agents/spine-scanner.md

@@ -18,8 +18,28 @@ You will receive:
 ## How to Scan
 
 1. Read `meta-memory-state.json` to find `last_tick` and `last_processed_fragments`.
-2. List event partitions in the events directory (sorted by date).
-3. Read recent partitions — start from the date of `last_tick`, scan forward.
+2. **Derive the time window.** Extract the date and hour from `last_tick`
+   (e.g. `2026-03-16T08:…` → date `2026-03-16`, hour prefix `"08"`).
+   You only need partition files from that date onward.
+3. List event partitions in the events directory. **Only open files
+   whose filename is >= the `last_tick` date.** Skip everything older.
+
+   **Large file strategy**: Spine partition files are 10-30MB JSONL.
+   Do NOT use `Read` on them — it will fail (256KB limit).
+   Do NOT use the `Grep` tool either — it also has a 256KB output cap
+   and cannot stream large result sets. Use `Bash` with shell `grep`
+   and `tail` instead, which have no size limit:
+
+   ```bash
+   # Only scan lines AFTER last_tick — use the hour prefix to narrow
+   grep '"ts":"2026-03-16T08' /path/to/events/2026-03-16.jsonl \
+     | grep -E '"type":"(channel\.message|agent\.result|agent\.error|job\.(spawn|complete|fail)|route\.deliver)"' \
+     | tail -200
+   ```
+
+   If `last_tick` was yesterday, scan yesterday's file (from the hour
+   onward) AND today's file. Never scan files from before `last_tick`.
+
 4. Focus on these event types:
    - `channel.message` — what people said
    - `agent.result` — what the agent did
@@ -51,7 +71,8 @@ If you found something worth recording, write ONE fragment file:
 ```markdown
 # Fragment: <short title>
 
-**Timestamp**: <ISO timestamp>
+**Timestamp**: <ISO timestamp of the source event>
+**Source**: <source.kind>/<source.name or channel_id> (e.g. channel/feishu, meta/subconscious:sentinel)
 
 ## Observation
 
@@ -66,6 +87,11 @@ If you found something worth recording, write ONE fragment file:
 - `<topic-or-entity-name>` — <brief connection>
 ```
 
+The **Source** line captures WHERE the signal came from. This lets
+downstream agents (entity-crystallizer, intuition-updater) distinguish
+e.g. a user conversation from a background job failure without
+re-reading the Spine.
+
 If nothing interesting happened, return exactly:
 `No new signals.`
 

package/bootstrap/subconscious/memory-weaver/CLAUDE.md

@@ -32,7 +32,7 @@ task. I decide what to run each tick, dispatch work, and maintain state.
 
 ### Parallelism & Dependencies
 
-```
+```text
 spine-scanner ───────┐
                      ├──▶ (both complete) ──▶ intuition-updater
 entity-crystallizer ─┘
@@ -40,7 +40,7 @@ entity-crystallizer ─┘
 
 - `spine-scanner` and `entity-crystallizer` are **independent** —
   they read different inputs and write different outputs.
-  **Always dispatch them in parallel** (send both Task calls in
+  **Always dispatch them in parallel** (send both Agent calls in
   a single response) to cut wall-clock time in half.
 - `intuition-updater` depends on the outputs of the other two.
   Dispatch it **only after** both have returned.
@@ -69,32 +69,44 @@ entity-crystallizer ─┘
      - `total_ticks - last_intuition_tick >= 4`
      - entity-crystallizer is running this tick (chain after it)
 
-4. **Phase 1 — parallel dispatch.** Send Task calls for
-   `spine-scanner` and `entity-crystallizer` (if due) together
-   in a single message. Pass each:
-
-   spine-scanner:
-   - Events directory path (from Runtime Context)
-   - `memory/state/meta-memory-state.json` path
-   - `memory/fragments/` path
-
-   entity-crystallizer:
-   - `memory/index.md` path
-   - `memory/entities/` path
-   - `memory/topics/` path
-   - `memory/fragments/` path
-   - Any index gaps found in step 2 (unlisted files, missing files)
-
-5. **Phase 2 — sequential follow-up.** After Phase 1 completes,
-   if `intuition-updater` is due, dispatch it now. Pass it:
-   - `memory/CLAUDE.md` path
-   - `memory/index.md` path
-   - `memory/entities/` path
-   - `memory/topics/` path
-
-6. **If nothing needs to run** (rare):
+4. **Dispatch using agent names.** Use the Agent tool with the `name`
+   parameter to invoke pre-defined agents. Pass each its context:
+
+   Phase 1 — parallel dispatch (send both in a single response):
+
+   ```text
+   Agent(name: "spine-scanner", prompt: "<events dir> <state path> <fragments dir>")
+   Agent(name: "entity-crystallizer", prompt: "<index> <entities> <topics> <fragments> <gaps>")
+   ```
+
+   Phase 2 — sequential follow-up (after Phase 1 completes):
+
+   ```text
+   Agent(name: "intuition-updater", prompt: "<CLAUDE.md> <index> <entities> <topics>")
+   ```
+
+   **CRITICAL**: Always pass the `name` parameter. Without it,
+   subagents will lack Bash, Grep, and other tools declared in their
+   agent definition files under `.claude/agents/`.
+
+5. **If nothing needs to run** (rare):
    Return `No significant cognitive delta.`
 
+### Avoiding Timeout
+
+This partition has a 10-minute budget. Most failures come from
+subagents reading too much data. Guard against this:
+
+- **spine-scanner**: Spine partition files are 10-30MB JSONL.
+  Never use `Read` (256KB cap). Use `Bash` with shell `grep` and
+  `tail` to extract only signal events within the time window.
+- **entity-crystallizer**: Process at most 20 gaps per tick.
+  Leave remaining gaps for the next tick.
+- **intuition-updater**: Only read `CLAUDE.md` + index + a handful
+  of changed entities. Never re-read all entities from scratch.
+- If Phase 1 takes > 5 minutes, **skip Phase 2** this tick.
+  The intuition-updater will catch up next time.
+
 ## After Dispatch: Update State
 
 After subagents complete, update `memory/state/meta-memory-state.json`:

package/bootstrap/var/DUODUO.md

@@ -15,4 +15,5 @@ Look for `DUODUO.md` in subdirectories to learn how each part works.
 - `registry/` — runtime status snapshots
 - `outbox/` — pending egress messages
 - `ingress/` — raw channel inputs before normalization
+- `telemetry/` — structured runtime latency samples for offline aggregation
 - `usage/` — per-session drain usage records (token counts, cost, tool calls)

package/bootstrap/var/telemetry/DUODUO.md

@@ -0,0 +1,61 @@
+# Telemetry — Structured Runtime Samples
+
+This directory contains append-only JSONL telemetry files for low-level runtime timings.
+
+These records are separate from `usage/`:
+
+- `usage/` is scoped to one `drainMailboxOnce()` execution and focuses on per-session work.
+- `telemetry/` is for cross-cutting transport and gateway timings that do not fit cleanly into a single drain record.
+
+## Layout
+
+Files are partitioned by UTC day:
+
+```text
+telemetry/
+  2026-03-14.jsonl
+  2026-03-15.jsonl
+```
+
+## Record Format
+
+Each line is one JSON object. The current metric records look like:
+
+```jsonc
+{
+  "kind": "metric",
+  "metric": "ingress_snapshot_ms",
+  "value": 4.2,
+  "ts": 1773475200000,
+  "eventId": "evt_123",
+  "sessionKey": "stdio:alice",
+  "sourceKind": "stdio"
+}
+```
+
+Current metric names:
+
+- `ingress_snapshot_ms` — gateway snapshot persistence latency
+- `replay_scan_ms` — unread outbox scan latency during pull/replay
+- `cursor_load_ms` — delivery cursor read latency
+- `cursor_store_ms` — delivery cursor write latency
+
+Extra fields may vary by metric. They are for debugging context and may grow over time.
+
+## Reporting
+
+Use the report helper to aggregate recent samples:
+
+```bash
+pnpm run telemetry:report -- --since 30m
+```
+
+Bare numeric values are treated as minutes, so `--since 90` means the last 90 minutes.
+
+The report prints `count`, `avg`, `p50`, `p95`, and `max` for each known metric.
+
+## Guarantees
+
+- **Append-only**: telemetry files are never rewritten in place.
+- **Best-effort**: failed telemetry writes never block the main runtime path.
+- **Low ceremony**: records are plain JSONL so they are easy to inspect with shell tools.

package/bootstrap/var/usage/DUODUO.md

@@ -1,7 +1,7 @@
 # Usage — Drain Execution Records
 
 This directory contains per-session usage ledgers.
-Each file tracks token counts, cost, and tool call metrics across every `drainMailboxOnce()` invocation.
+Each file tracks token counts, cost, tool call metrics, and runner-side local performance snapshots across every `drainMailboxOnce()` invocation.
 
 ## Layout
 
@@ -37,11 +37,36 @@ Each line is a JSON `DrainRecord`:
     "output_tokens": 410,
     "cache_read_input_tokens": 1200,
     "cache_creation_input_tokens": 0
+  },
+  "perf": {
+    "mailbox_merge_ms": 6.1,
+    "mailbox_parse_ms": 1.8,
+    "session_snapshot_ms": 2.2,
+    "session_state_ms": 0.9,
+    "outbox_lookup_ms": 0.4,
+    "event_read_ms": 1.6,
+    "effective_config_ms": 0.7,
+    "outbox_emit_ms": 4.3,
+    "session_upsert_ms": 1.5,
+    "mailbox_finalize_ms": 1.1,
+    "sdk_ttft_ms_total": 842,
+    "sdk_ttft_samples": 1
   }
 }
 ```
 
 `usage` is absent when the drain was cancelled before the SDK returned a result.
+`perf` is optional and records best-effort local timings for the runner-side stages observed during that drain.
+
+## Summary Semantics
+
+`usage.get` returns both per-record detail and an aggregated summary.
+
+- `usage` fields are summed across records in the summary.
+- `perf` fields are also summed across records in the summary.
+- `sdk_ttft_ms_total / sdk_ttft_samples` are emitted separately so callers can compute average TTFT without losing sample count.
+
+These timings are scoped to one `drainMailboxOnce()` execution. Transport-side or consumer-side costs such as ingress snapshots, replay scans, websocket delivery, and CLI rendering are not part of this ledger yet.
 
 ## Querying via RPC