/learning-window

name: learning-window
description: Persist collection evidence and plan unread room windows separately from learned facts.

Learning window state

This optional workflow component owns learning collection checkpoints, not a resident gateway event cursor, task inbox, or transport lifecycle. It starts no resident daemon. Network reads delegate adapter-supplied capabilities and the existing cloud auth/HTTP owner. Core services do not depend on it.

The dispatcher supplies current joined membership for every configured scope. `scripts/window_state.py:plan_windows` returns each scope's earliest unread timestamp, including the immutable bootstrap timestamp for a newly joined room or newly configured scope. Never initialize a new room from another room's or scope's current timestamp.

After a trusted bounded collector returns a scope-qualified receipt, the dispatcher calls `record_collection` with the dedicated private state directory. The writer locks and validates state, atomically persists the complete receipt, then records collection progress only for rooms with covered available history. Failures and exhausted page budgets leave unread rooms at their prior position. The receipt's overall success flag cannot override a failed room. The persisted receipt contains unlearned events and must survive until its consumer commits them to a durable facts store.

Collection is not learning. This writer never advances a learned-facts cursor or claims dossiers changed. A recency-only update does not consume facts. Consumer acknowledgment and receipt retention need their own tested contract before unattended operation; never prune unlearned receipts to make a size gate pass.

`scripts/collection_pass.py:collect_pass` accepts an explicit configured scope list and injected membership/collector capabilities. It validates exact membership and window binding, persists partial receipts, and admits a consumer only when every configured scope has covered available history. It does not invoke a consumer or acknowledge facts. The optional dispatcher delegates to this contract. Direct model-authored receipt files are not trusted collector evidence. Same-user filesystem access can bypass any optional writer; do not claim this is all-provider authorization or mandatory protection of a legacy cursor.

`command_collection.py:collect_commands` invokes adapter-injected argument vectors for each configured hostname scope with strict `rooms` and bounded `history` commands. Credential/environment resolution belongs to those adapters. Partial strict failures are persisted with unread coverage; command timeouts and scope mismatches prevent consumer admission. No network command was exercised by its offline tests; adapter deployment and scheduled live runs need separate evidence. Scope exceptions retain their type and a fixed `error_stages` label for membership read/validation, history read, window order/validation or receipt persistence. Labels contain no exception text, command output or credentials; a history-read label alone does not distinguish network failure from command-output validation.

`launch.sh manifest directory log` detaches `dispatch_collection.py` with explicit manifest config, a dedicated private collection state directory and a caller resolved log path. It delegates interpreter selection to the repository Python resolver. A launch receipt means dispatcher requested, not consumer completion. The locked dispatcher performs collection before invoking the configured consumer argument vector and supplies every retained digest-verified bundle. No fact acknowledgment or receipt deletion is implemented; consumer exit stays unverified. Scope keys must match the canonical collector gateway hostname, not a Matrix homeserver alias. Private dispatcher wiring belongs to the caller's adapter.

Consumers run in their own process group. Before final readback and lock release, the dispatcher kills remaining group members and reaps its direct child, including on timeout, normal exit, and SIGTERM/SIGINT cancellation. A child deliberately escaping the group is outside this guarantee; this is not a sandbox.

The consumer is a detached session with no task inbox: its child environment sets `SUTANDO_CORE_SESSION=0` and removes any inherited `SUTANDO_INSTANCE_ID`. The core Stop hook recognizes that explicit non-core role without relying on a fresh core heartbeat. Other environment and hook settings are preserved. This role declaration is queue ownership, not an authorization or tool boundary. The Stop hook is Claude-specific and is not installed as Codex enforcement. A detached Codex exec adapter must explicitly configure its working directory, receipt/checker access and private output write permission; no resident core launcher or implicit Codex sandbox grant is supplied.

`receipt_status.py` emits canonical collection summaries from digest-verified bundles, including exact UTC timestamps and each scope's visible population. The dispatcher persists these summaries before attempting the consumer. They remain collection evidence when a consumer fails, exits or writes only recency. Optional `--claims` compares structured collection claims with that evidence; it does not validate arbitrary consumer prose or acknowledge learned facts.

An adapter can opt into proposal retention by adding `proposal_stores` to the manifest's `config`: a mapping from permitted person keys to observed durable store IDs. The adapter supplies this inventory, not the consumer. Without it, consumer invocation is unchanged. This mapping does not grant document-writing authority or establish that a proposed interpretation is true.

For an enabled job, the dispatcher persists a fresh UUID output path before attempting the consumer. Its machine-readable return contract lists permitted person keys and retained receipt digests. The consumer writes exactly `{"schema": 1, "proposals": [...]}` to that path. Each proposal contains only `person_key`, `scope`,