@gotcos/glasses-server 6.44.4 → 6.44.6

package/CHANGELOG.md

@@ -1,3 +1,61 @@
+## 6.44.6
+
+What /qa found in 6.44.5 before anyone installed it.
+
+- `GET /api/context/learning/review`: the strict To review set (the bridge's
+  `learning-to-review`, the same set the status block counts) as event rows,
+  one page of up to 200. 6.44.5's list approximated it with a kind filter and
+  showed "50 of 837" beside a chip that said 121.
+- Every user value now rides as one argv token (`--q=...`, `--id=...`,
+  `--entity=...`), so a search term or entity name that begins with `-` can no
+  longer be read by the bridge's argument parser as a flag.
+- An older COS bridge prints its unknown-command answer to stdout; the server
+  probed only stderr, so every learning route on such a bridge answered 503
+  instead of `cos_pipeline_not_configured`. Both are probed now.
+- A `found: false` entity answer is a 404 with a class Control can name,
+  `index_missing` or `entity_not_found`, never a 503; the null-normalizer
+  fallback says `record_not_found`.
+- `/api/context/status` answers `Cache-Control: private, no-store` like the
+  eight routes that shipped with it; it carries private counts.
+- Every learning and graph route logs the bridge failure it used to swallow,
+  and the search shape passes the bridge's own `scope` through.
+- On the COS side (same night): a JSON error exits 0 so it is parsed rather
+  than rejected, the bot-memory reach is bounded at 2.5 s so a wedged Qdrant
+  cannot blank the file stores, and entity descriptions cap at 12.
+
+## 6.44.5
+
+Recent learning and the knowledge graph, read-only, for COS Control.
+
+- `GET /api/context/status` also carries `learning` and `graph` blocks. They come
+  from a second bridge call (`context-learning-graph-status`, 1.5 s budget) made
+  alongside the existing one with `Promise.allSettled`, so a bridge that predates
+  the command, times out, or answers `{ error }` leaves `memory` and `threads`
+  exactly as they were and the two blocks absent. Nothing an existing client
+  reads has changed; a client that wants the blocks checks for them.
+- Seven read routes: `GET /api/context/learning` (cursor-paged events with a
+  per-store coverage map), `GET /api/context/learning/status`,
+  `GET /api/context/learning/:id`, `GET /api/context/graph/status`,
+  `GET /api/context/graph/search`, `GET /api/context/graph/entity`,
+  `GET /api/context/graph/passages`, and one `POST /api/context/graph/index`
+  that answers 202 and only asks the bridge to start a detached index build
+  (`graph-index-build --reason control`). The HTTP handler never runs
+  `--build-index`, `--apply-curation`, `--process-queue` or `graph-sync`; a
+  source test pins that. Every route sits behind the API token like the rest of
+  `/api`, answers `Cache-Control: private, no-store`, and 503s with the bridge
+  state when no pipeline is configured.
+- Bodies are allowlisted before they leave: counts pass only as integers, event
+  ids must match `evt_` plus sixteen hex characters, unknown fields and local
+  paths never pass, and an `{ error }` from the bridge becomes a status (404 for
+  `*_not_found`, 400 for `invalid_*`, 503 otherwise) rather than a 200. Found
+  while writing the tests: the passages shape always carries an `error` key,
+  `null` on success, and the first draft read the key alone as a failure.
+- Caps are the bridge's, restated at the edge: 50 events per page, 30 search
+  hits, 5 passages, a 200-character entity id, 160-character query.
+- Older servers 404 these paths, which is how a client tells 6.44.5 apart from
+  what it had. A second Mac still on 6.44.2 picks up 6.44.3 and 6.44.4 with this
+  install; nothing in those two needs a step in between.
+
 ## 6.44.4
 
 Stage, a finish line, and no dispatch without one.

package/README.md

@@ -419,6 +419,16 @@ complete setup. The file tier is read from the code path taken only when no
 bridge is configured, so adding it cannot change the behaviour of an install that
 already has one.
 
+Since 6.44.5 the bridge tier also serves recent learning and the knowledge graph,
+read-only: `/api/context/learning` (events, cursor-paged, with a per-store
+coverage map), `/api/context/learning/status`, `/api/context/learning/:id`, and
+`/api/context/graph/{status,search,entity,passages}`, plus `POST
+/api/context/graph/index`, which only asks the pipeline to start a detached index
+build and answers 202. Nothing in the file tier can answer these, so they return
+503 `cos_pipeline_not_configured` there; older servers 404 them, which is how a client
+tells the versions apart. `/api/context/status` carries `learning` and `graph`
+blocks when the bridge can produce them and omits them otherwise.
+
 The API is read-only in both tiers. Standalone installs with neither a bridge nor
 a notes folder report the feature as unavailable without affecting messages,
 meetings, transcription, or agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.44.4",
+  "version": "6.44.6",
   "description": "COS Glasses \u2014 self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/lib/cos-context-browser.ts

@@ -365,6 +365,425 @@ export interface ContextBrowserStatus {
   source?: 'bridge' | 'files'
   memory: { available: boolean; total: number; state: string; reason?: string }
   threads: { available: boolean; total: number; active: number; stale: number; resolved: number; state: string; reason?: string }
+  /** Recent learning / To review, served by learning_bridge.py since 6.44.5. Absent on older bridges. */
+  learning?: LearningBlock
+  /** Knowledge graph status, served by learning_bridge.py since 6.44.5. Absent on older bridges. */
+  graph?: GraphBlock
+}
+
+export interface LearningBlock {
+  available: boolean
+  state: string
+  count?: number
+  to_review?: { patterns?: number; task_proposals?: number }
+  last_ts?: string
+  orphan_decisions?: number
+  stores_readable?: number
+}
+
+export interface GraphBlock {
+  available: boolean
+  state: string
+  entities?: number
+  relationships?: number
+  source_updated_at?: string
+  index_state?: string
+  index_built_at?: string
+  queue_pending?: number
+  owner_host?: string
+  is_owner?: boolean
+  replica?: boolean
+  processor_state?: string
+  lock_state?: string
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null
+}
+
+/**
+ * A count is carried ONLY when the bridge sent a clean integer. finiteInteger()
+ * would coerce '1', 1.5 and true to a number and default a missing field to 0,
+ * which is how an absent block would read as "0 to review".
+ */
+function integerOrAbsent(value: unknown): number | undefined {
+  return Number.isInteger(value) && (value as number) >= 0 ? value as number : undefined
+}
+
+function isoOrAbsent(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value) return undefined
+  const cleaned = cleanContextText(value, 40)
+  return Number.isFinite(Date.parse(cleaned)) ? cleaned : undefined
+}
+
+function stringOrAbsent(value: unknown, limit: number): string | undefined {
+  if (typeof value !== 'string' || !value) return undefined
+  const cleaned = cleanContextText(value, limit)
+  return cleaned || undefined
+}
+
+function booleanOrAbsent(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined
+}
+
+function defined<T extends Record<string, unknown>>(record: T): T {
+  for (const key of Object.keys(record)) if (record[key] === undefined) delete record[key]
+  return record
+}
+
+export function normalizeLearningBlock(value: unknown): LearningBlock | null {
+  const source = asRecord(value)
+  if (!source) return null
+  const review = asRecord(source.to_review)
+  const toReview = review ? defined({ patterns: integerOrAbsent(review.patterns), task_proposals: integerOrAbsent(review.task_proposals) }) : undefined
+  return defined({
+    available: source.available === true,
+    state: cleanContextText(source.state, 64) || (source.available === true ? 'ready' : 'unavailable'),
+    count: integerOrAbsent(source.count),
+    to_review: toReview && Object.keys(toReview).length ? toReview : undefined,
+    last_ts: isoOrAbsent(source.last_ts),
+    orphan_decisions: integerOrAbsent(source.orphan_decisions),
+    stores_readable: integerOrAbsent(source.stores_readable),
+  }) as LearningBlock
+}
+
+export function normalizeGraphBlock(value: unknown): GraphBlock | null {
+  const source = asRecord(value)
+  if (!source) return null
+  return defined({
+    available: source.available === true,
+    state: cleanContextText(source.state, 64) || (source.available === true ? 'ready' : 'unavailable'),
+    entities: integerOrAbsent(source.entities),
+    relationships: integerOrAbsent(source.relationships),
+    source_updated_at: isoOrAbsent(source.source_updated_at),
+    index_state: stringOrAbsent(source.index_state, 32),
+    index_built_at: isoOrAbsent(source.index_built_at),
+    queue_pending: integerOrAbsent(source.queue_pending),
+    owner_host: stringOrAbsent(source.owner_host, 128),
+    is_owner: booleanOrAbsent(source.is_owner),
+    replica: booleanOrAbsent(source.replica),
+    processor_state: stringOrAbsent(source.processor_state, 32),
+    lock_state: stringOrAbsent(source.lock_state, 32),
+  }) as GraphBlock
+}
+
+// ── Recent learning payloads (GET /context/learning, /context/learning/:id) ──
+
+export const LEARNING_EVENT_ID_PATTERN = /^evt_[a-f0-9]{16}$/
+export const LEARNING_EVENT_TYPES = new Set(['captured', 'proposed', 'promotable', 'saved', 'retrieved', 'used', 'checked', 'dismissed', 'reverted', 'reopened', 'consolidated', 'previewed'])
+const LEARNING_LIST_LIMIT = 50
+/** The strict To review set is small (121 today); one page shows it whole. */
+export const LEARNING_REVIEW_LIMIT = 200
+const LEARNING_DETAIL_KEYS = ['shape', 'task', 'kind', 'layer', 'date', 'future', 'logged_times', 'memory_type', 'capture', 'source', 'content', 'before', 'after', 'rule', 'status', 'occurrences', 'threshold', 'entry', 'truncated'] as const
+
+export interface LearningEvent {
+  event_id: string
+  lesson_id: string | null
+  event_type: string
+  ts: string
+  store: string
+  title: string
+  scope: string
+  category: string | null
+  engine: string
+  target: { kind: string | null; id: string; version: string | null }
+  applies_to: Array<{ kind: string; name: string; cadence: string | null; evidence: string }>
+  source_refs: Array<{ kind: string; id: string; excerpt: string }>
+  prior_event_id: string | null
+  outcome: { name: string; result: string; evaluator: string; ts: string | null } | null
+  provenance: string
+  ordinal?: number
+}
+
+function normalizeLearningEvent(value: unknown, excerptLimit: number): LearningEvent | null {
+  const source = asRecord(value)
+  if (!source || typeof source.event_id !== 'string' || !LEARNING_EVENT_ID_PATTERN.test(source.event_id)) return null
+  const eventType = cleanContextText(source.event_type, 32)
+  if (!LEARNING_EVENT_TYPES.has(eventType)) return null
+  const ts = isoOrAbsent(source.ts)
+  if (!ts) return null
+  const target = asRecord(source.target) ?? {}
+  const outcome = asRecord(source.outcome)
+  const appliesTo = Array.isArray(source.applies_to) ? source.applies_to.slice(0, 10).map(asRecord).filter((r): r is Record<string, unknown> => !!r).map(r => ({
+    kind: cleanContextText(r.kind, 16), name: cleanContextText(r.name, 160),
+    cadence: stringOrAbsent(r.cadence, 120) ?? null, evidence: cleanContextText(r.evidence, 240),
+  })) : []
+  const refs = Array.isArray(source.source_refs) ? source.source_refs.slice(0, 10).map(asRecord).filter((r): r is Record<string, unknown> => !!r).map(r => ({
+    kind: cleanContextText(r.kind, 32), id: cleanContextText(r.id, 200), excerpt: cleanContextText(r.excerpt, excerptLimit),
+  })) : []
+  const event: LearningEvent = {
+    event_id: source.event_id,
+    lesson_id: stringOrAbsent(source.lesson_id, 200) ?? null,
+    event_type: eventType,
+    ts,
+    store: cleanContextText(source.store, 40),
+    title: cleanContextText(source.title, 160),
+    scope: cleanContextText(source.scope, 24) || 'unknown',
+    category: stringOrAbsent(source.category, 160) ?? null,
+    engine: cleanContextText(source.engine, 24) || 'unknown',
+    target: { kind: stringOrAbsent(target.kind, 24) ?? null, id: cleanContextText(target.id, 200), version: stringOrAbsent(target.version, 64) ?? null },
+    applies_to: appliesTo,
+    source_refs: refs,
+    prior_event_id: typeof source.prior_event_id === 'string' && LEARNING_EVENT_ID_PATTERN.test(source.prior_event_id) ? source.prior_event_id : null,
+    outcome: outcome ? {
+      name: cleanContextText(outcome.name, 160), result: cleanContextText(outcome.result, 24),
+      evaluator: cleanContextText(outcome.evaluator, 64), ts: isoOrAbsent(outcome.ts) ?? null,
+    } : null,
+    provenance: cleanContextText(source.provenance, 24) || 'unavailable',
+  }
+  const ordinal = integerOrAbsent(source.ordinal)
+  if (ordinal !== undefined) event.ordinal = ordinal
+  return event
+}
+
+export interface LearningCoverage { [store: string]: { state: string; count: number; detail?: string } }
+
+export function normalizeLearningCoverage(value: unknown): LearningCoverage {
+  const source = asRecord(value) ?? {}
+  const out: LearningCoverage = {}
+  for (const [store, raw] of Object.entries(source).slice(0, 16)) {
+    const entry = asRecord(raw)
+    if (!entry) continue
+    const key = cleanContextText(store, 40)
+    if (!key) continue
+    out[key] = defined({
+      state: cleanContextText(entry.state, 32) || 'unavailable',
+      count: integerOrAbsent(entry.count) ?? 0,
+      detail: stringOrAbsent(entry.detail, 240),
+    }) as { state: string; count: number; detail?: string }
+  }
+  return out
+}
+
+export function normalizeLearningEvents(value: unknown, limit: number, max = LEARNING_LIST_LIMIT): {
+  events: LearningEvent[]; total: number; next_cursor: { since_ts: string; since_event_id: string } | null; coverage: LearningCoverage
+} {
+  const source = asRecord(value) ?? {}
+  const cap = Math.max(1, Math.min(limit, max))
+  const events = (Array.isArray(source.events) ? source.events : []).slice(0, cap)
+    .map(item => normalizeLearningEvent(item, 240)).filter((e): e is LearningEvent => !!e)
+  const cursor = asRecord(source.next_cursor)
+  const sinceTs = cursor ? isoOrAbsent(cursor.since_ts) : undefined
+  const sinceId = cursor && typeof cursor.since_event_id === 'string' && LEARNING_EVENT_ID_PATTERN.test(cursor.since_event_id) ? cursor.since_event_id : undefined
+  return {
+    events,
+    total: integerOrAbsent(source.total) ?? events.length,
+    next_cursor: sinceTs && sinceId ? { since_ts: sinceTs, since_event_id: sinceId } : null,
+    coverage: normalizeLearningCoverage(source.coverage),
+    ...(integerOrAbsent(source.review_count) !== undefined ? { review_count: integerOrAbsent(source.review_count) } : {}),
+  }
+}
+
+export function normalizeLearningEventDetail(value: unknown): (LearningEvent & { detail: Record<string, unknown> }) | null {
+  const event = normalizeLearningEvent(value, 1200)
+  if (!event) return null
+  const raw = asRecord((value as Record<string, unknown>).detail) ?? {}
+  const detail: Record<string, unknown> = {}
+  for (const key of LEARNING_DETAIL_KEYS) {
+    const item = raw[key]
+    if (item === undefined || item === null) continue
+    if (typeof item === 'boolean') detail[key] = item
+    else if (Number.isInteger(item)) detail[key] = item
+    else if (typeof item === 'string') detail[key] = cleanContextText(item, 1200)
+  }
+  if (Array.isArray(raw.bodies)) detail.bodies = raw.bodies.slice(0, 12).map(body => cleanContextText(body, 1200))
+  return { ...event, detail }
+}
+
+export interface LearningStatus {
+  stores: LearningCoverage & { [store: string]: { state: string; count: number; detail?: string; readable?: boolean; last_ts?: string } }
+  to_review: { count: number; pattern: number; 'task-proposal': number }
+  orphan_decisions: number
+  no_store_active: boolean
+  engines: string[]
+  counts_by_type: Record<string, number>
+}
+
+export function normalizeLearningStatus(value: unknown): LearningStatus {
+  const source = asRecord(value) ?? {}
+  const stores: LearningStatus['stores'] = {}
+  for (const [store, raw] of Object.entries(asRecord(source.stores) ?? {}).slice(0, 16)) {
+    const entry = asRecord(raw)
+    const key = cleanContextText(store, 40)
+    if (!entry || !key) continue
+    stores[key] = defined({
+      state: cleanContextText(entry.state, 32) || 'unavailable',
+      count: integerOrAbsent(entry.count) ?? 0,
+      readable: booleanOrAbsent(entry.readable),
+      last_ts: isoOrAbsent(entry.last_ts),
+    }) as LearningStatus['stores'][string]
+  }
+  const review = asRecord(source.to_review) ?? {}
+  const counts: Record<string, number> = {}
+  for (const [type, raw] of Object.entries(asRecord(source.counts_by_type) ?? {})) {
+    if (LEARNING_EVENT_TYPES.has(type) && Number.isInteger(raw)) counts[type] = raw as number
+  }
+  return {
+    stores,
+    to_review: { count: integerOrAbsent(review.count) ?? 0, pattern: integerOrAbsent(review.pattern) ?? 0, 'task-proposal': integerOrAbsent(review['task-proposal']) ?? 0 },
+    orphan_decisions: integerOrAbsent(source.orphan_decisions) ?? 0,
+    no_store_active: source.no_store_active === true,
+    engines: stringList(source.engines, 8, 24),
+    counts_by_type: counts,
+  }
+}
+
+// ── Knowledge graph payloads (GET /context/graph/*) ──
+
+export const GRAPH_ENTITY_ID_LIMIT = 200
+export const GRAPH_INDEX_STATES = new Set(['fresh', 'stale', 'missing', 'source_missing'])
+
+export function normalizeIndexReceipt(value: unknown): Record<string, unknown> | null {
+  const source = asRecord(value)
+  if (!source) return null
+  return defined({
+    state: stringOrAbsent(source.state, 16) ?? null,
+    started_at: isoOrAbsent(source.started_at) ?? null,
+    ended_at: isoOrAbsent(source.ended_at) ?? null,
+    pid: integerOrAbsent(source.pid) ?? null,
+    host: stringOrAbsent(source.host, 128) ?? null,
+    reason: stringOrAbsent(source.reason, 64) ?? null,
+    error: stringOrAbsent(source.error, 240) ?? null,
+    wall_s: typeof source.wall_s === 'number' && Number.isFinite(source.wall_s) ? source.wall_s : null,
+    peak_rss_mb: typeof source.peak_rss_mb === 'number' && Number.isFinite(source.peak_rss_mb) ? source.peak_rss_mb : null,
+    node_count: integerOrAbsent(source.node_count) ?? null,
+    edge_count: integerOrAbsent(source.edge_count) ?? null,
+    build_seq: integerOrAbsent(source.build_seq) ?? null,
+    degraded: source.degraded === true,
+  })
+}
+
+export function normalizeGraphStatus(value: unknown): Record<string, unknown> {
+  const source = asRecord(value) ?? {}
+  const src = asRecord(source.source) ?? {}
+  const queue = asRecord(source.queue) ?? {}
+  const budget = asRecord(source.budget) ?? {}
+  const lock = asRecord(source.lock) ?? {}
+  const processor = asRecord(source.processor) ?? {}
+  const indexState = stringOrAbsent(source.index_state, 32)
+  return {
+    entities: integerOrAbsent(source.entities) ?? null,
+    relationships: integerOrAbsent(source.relationships) ?? null,
+    source_updated_at: isoOrAbsent(source.source_updated_at) ?? null,
+    index_built_at: isoOrAbsent(source.index_built_at) ?? null,
+    index_state: indexState && GRAPH_INDEX_STATES.has(indexState) ? indexState : 'missing',
+    index_degraded: source.index_degraded === true,
+    build: normalizeIndexReceipt(source.build),
+    source: {
+      owner_host: stringOrAbsent(src.owner_host, 128) ?? null,
+      this_host: stringOrAbsent(src.this_host, 128) ?? null,
+      is_owner: src.is_owner === true,
+      owner_state: stringOrAbsent(src.owner_state, 16) ?? 'unset',
+      replica: src.replica === true,
+      source_sha256_prefix: stringOrAbsent(src.source_sha256_prefix, 16) ?? null,
+      index_built_on_host: stringOrAbsent(src.index_built_on_host, 128) ?? null,
+      index_host_mismatch: src.index_host_mismatch === true,
+    },
+    queue: {
+      live_total: integerOrAbsent(queue.live_total) ?? null,
+      pending: integerOrAbsent(queue.pending) ?? null,
+      failed: integerOrAbsent(queue.failed) ?? null,
+      deferred: integerOrAbsent(queue.deferred) ?? null,
+      oldest_pending_at: isoOrAbsent(queue.oldest_pending_at) ?? null,
+      oldest_pending_age_s: integerOrAbsent(queue.oldest_pending_age_s) ?? null,
+      missing_sources: integerOrAbsent(queue.missing_sources) ?? null,
+      conflict_copies: integerOrAbsent(queue.conflict_copies) ?? null,
+    },
+    budget: { used: integerOrAbsent(budget.used) ?? null, cap: integerOrAbsent(budget.cap) ?? null },
+    lock: { state: stringOrAbsent(lock.state, 16) ?? 'unknown', owner_pid: integerOrAbsent(lock.owner_pid) ?? null, error: stringOrAbsent(lock.error, 64) ?? null },
+    last_run: normalizeIndexReceipt(source.last_run),
+    processor: {
+      state: stringOrAbsent(processor.state, 24) ?? 'none',
+      plist: processor.plist === true,
+      cadence_s: integerOrAbsent(processor.cadence_s) ?? null,
+      last_run_at: isoOrAbsent(processor.last_run_at) ?? null,
+      last_outcome: stringOrAbsent(processor.last_outcome, 24) ?? null,
+    },
+  }
+}
+
+export function normalizeGraphSearch(value: unknown, limit: number): Record<string, unknown> {
+  const source = asRecord(value) ?? {}
+  const items = (Array.isArray(source.items) ? source.items : []).slice(0, Math.max(1, Math.min(limit, 30))).map(asRecord)
+    .filter((r): r is Record<string, unknown> => !!r && typeof r.id === 'string')
+    .map(r => ({ id: cleanContextText(r.id, GRAPH_ENTITY_ID_LIMIT), type: stringOrAbsent(r.type, 40) ?? null, degree: integerOrAbsent(r.degree) ?? 0, description: cleanContextText(r.description, 240) }))
+  return {
+    items,
+    total: integerOrAbsent(source.total) ?? items.length,
+    scope: stringOrAbsent(source.scope, 32) ?? 'full-index',
+    index_built_at: isoOrAbsent(source.index_built_at) ?? null,
+    index_state: stringOrAbsent(source.index_state, 32) ?? 'missing',
+    matcher: stringOrAbsent(source.matcher, 16) ?? null,
+    window: integerOrAbsent(source.window) ?? null,
+    offset: integerOrAbsent(source.offset) ?? 0,
+    limit: integerOrAbsent(source.limit) ?? items.length,
+  }
+}
+
+export function normalizeGraphEntity(value: unknown): Record<string, unknown> | null {
+  const source = asRecord(value)
+  if (!source || source.found !== true || typeof source.id !== 'string') return null
+  const edges = (Array.isArray(source.edges) ? source.edges : []).slice(0, 30).map(asRecord).filter((r): r is Record<string, unknown> => !!r).map(r => ({
+    source: cleanContextText(r.source, GRAPH_ENTITY_ID_LIMIT), target: cleanContextText(r.target, GRAPH_ENTITY_ID_LIMIT),
+    weight: typeof r.weight === 'number' && Number.isFinite(r.weight) ? r.weight : null, description: cleanContextText(r.description, 240),
+  }))
+  const neighbors = (Array.isArray(source.neighbors) ? source.neighbors : []).slice(0, 30).map(asRecord).filter((r): r is Record<string, unknown> => !!r).map(r => ({
+    id: cleanContextText(r.id, GRAPH_ENTITY_ID_LIMIT), type: stringOrAbsent(r.type, 40) ?? null, degree: integerOrAbsent(r.degree) ?? 0,
+  }))
+  return {
+    found: true,
+    id: cleanContextText(source.id, GRAPH_ENTITY_ID_LIMIT),
+    type: stringOrAbsent(source.type, 40) ?? null,
+    degree: integerOrAbsent(source.degree) ?? 0,
+    description: cleanContextText(source.description, 1200),
+    description_length: integerOrAbsent(source.description_length) ?? null,
+    descriptions: stringList(source.descriptions, 12, 1200),
+    created_at: integerOrAbsent(source.created_at) ?? null,
+    first_seen_build: integerOrAbsent(source.first_seen_build) ?? null,
+    edges, neighbors,
+    total_relationships: integerOrAbsent(source.total_relationships) ?? edges.length,
+    offset: integerOrAbsent(source.offset) ?? 0,
+    limit: integerOrAbsent(source.limit) ?? edges.length,
+    source_status: stringOrAbsent(source.source_status, 16) ?? 'unresolved',
+    source_count: integerOrAbsent(source.source_count) ?? 0,
+    source_resolved: integerOrAbsent(source.source_resolved) ?? 0,
+    index_built_at: isoOrAbsent(source.index_built_at) ?? null,
+    index_state: stringOrAbsent(source.index_state, 32) ?? 'missing',
+  }
+}
+
+export function normalizeGraphPassages(value: unknown): Record<string, unknown> {
+  const source = asRecord(value) ?? {}
+  const items = (Array.isArray(source.items) ? source.items : []).slice(0, 5).map(asRecord).filter((r): r is Record<string, unknown> => !!r).map(r => {
+    const src = asRecord(r.source) ?? {}
+    return {
+      chunk_id: cleanContextText(r.chunk_id, 80), doc_id: stringOrAbsent(r.doc_id, 80) ?? null,
+      order: integerOrAbsent(r.order) ?? null, excerpt: cleanContextText(r.excerpt, 1200),
+      source: {
+        status: stringOrAbsent(src.status, 16) ?? 'unresolved', key: stringOrAbsent(src.key, 200) ?? null,
+        title: stringOrAbsent(src.title, 200) ?? null, date: stringOrAbsent(src.date, 40) ?? null, summary: stringOrAbsent(src.summary, 120) ?? null,
+      },
+    }
+  })
+  return {
+    items,
+    total: integerOrAbsent(source.total) ?? items.length,
+    index_state: stringOrAbsent(source.index_state, 32) ?? null,
+    index_built_at: isoOrAbsent(source.index_built_at) ?? null,
+    fallback: stringOrAbsent(source.fallback, 24) ?? null,
+    unavailable: stringList(source.unavailable, 8, 64),
+    note: stringOrAbsent(source.note, 240) ?? null,
+  }
+}
+
+export function normalizeIndexBuildKickoff(value: unknown): { started: boolean; already_running: boolean; pid: number | null; receipt: Record<string, unknown> | null } {
+  const source = asRecord(value) ?? {}
+  return {
+    started: source.started === true,
+    already_running: source.already_running === true,
+    pid: integerOrAbsent(source.pid) ?? null,
+    receipt: normalizeIndexReceipt(source.receipt),
+  }
 }
 
 export function normalizeContextBrowserStatus(value: unknown): ContextBrowserStatus {
@@ -390,6 +809,10 @@ export function normalizeContextBrowserStatus(value: unknown): ContextBrowserSta
   const incompatibleState = protocolCompatible ? '' : 'bridge_outdated'
   const memoryState = incompatibleState || cleanState(memory.state, memoryAvailable ? 'ready' : 'unavailable')
   const threadState = incompatibleState || cleanState(threads.state, threadsAvailable ? 'ready' : 'unavailable')
+  // The learning and graph blocks (6.44.5) sit behind the SAME protocol gate; an
+  // absent block stays absent so the two toEqual pins on older payloads hold.
+  const learning = protocolCompatible ? normalizeLearningBlock(source.learning) : null
+  const graph = protocolCompatible ? normalizeGraphBlock(source.graph) : null
   return {
     available: protocolCompatible && source.available === true,
     protocol,
@@ -420,5 +843,7 @@ export function normalizeContextBrowserStatus(value: unknown): ContextBrowserSta
         ? { reason: 'bridge_outdated' }
         : threads.reason ? { reason: cleanState(threads.reason, threadState) } : {}),
     },
+    ...(learning ? { learning } : {}),
+    ...(graph ? { graph } : {}),
   }
 }

package/server/lib/python-bridge.ts

@@ -38,6 +38,26 @@ if (!COS_SCRIPTS_DIR) {
 export const PYTHON_BIN: string | null = COS_SCRIPTS_DIR ? resolve(COS_SCRIPTS_DIR, 'venv/bin/python3') : null
 const BRIDGE_SCRIPT: string | null = COS_SCRIPTS_DIR ? resolve(COS_SCRIPTS_DIR, 'cos_api_bridge.py') : null
 
+/**
+ * The bridge commands served by operations/scripts/learning_bridge.py (COS
+ * Control Memories, Phase 0.3). Every name here has an explicit file-tier case
+ * in `standaloneNoop` below, and python-bridge-files.test.ts pins this list
+ * against the Python bridge's `_LEARNING_COMMANDS` frozenset when that file is
+ * reachable. Grows in the same commit as each later command.
+ */
+export const LEARNING_COMMANDS = [
+  'context-learning-graph-status',
+  'learning-events',
+  'learning-event',
+  'learning-status',
+  'graph-status',
+  'graph-search',
+  'graph-entity',
+  'graph-passages',
+  'graph-index-build',
+  'learning-to-review',
+] as const
+
 // The optional Python bridge is available only when the user points us at a real
 // COS pipeline that ships the venv + bridge script. Standalone installs never
 // have these, so callPython() degrades to a no-op.
@@ -186,6 +206,29 @@ function standaloneNoop(args: string[]): unknown {
       return { error: 'cos_pipeline_not_configured' }
     }
     case 'badges': return {}
+    // Learning / knowledge commands (COS Control Memories, Phase 0.3). These
+    // need the Python bridge; the file tier has no learning stores or graph
+    // index to serve, so each says so in the STRING form the memory routes
+    // read. LEARNING_COMMANDS above is pinned against `_LEARNING_COMMANDS` in
+    // operations/scripts/cos_api_bridge.py by python-bridge-files.test.ts.
+    case 'context-learning-graph-status':
+      // The one learning command with a SHAPE: both blocks present and unavailable,
+      // so the /context/status merge path is exercised in the file tier too.
+      return {
+        learning: { available: false, state: 'cos_pipeline_not_configured' },
+        graph: { available: false, state: 'cos_pipeline_not_configured' },
+        protocol: 1,
+      }
+    case 'learning-events':
+    case 'learning-event':
+    case 'learning-status':
+    case 'graph-status':
+    case 'graph-search':
+    case 'graph-entity':
+    case 'graph-passages':
+    case 'graph-index-build':
+    case 'learning-to-review':
+      return { error: 'cos_pipeline_not_configured' }
     case 'task-rows':
     case 'task-capture':
     case 'task-set-run-at':
@@ -214,7 +257,10 @@ function callPythonDirect(args: string[], timeoutMs: number, input?: string): Pr
       { cwd: COS_SCRIPTS_DIR!, timeout: timeoutMs, maxBuffer: 1024 * 1024 },
       (err, stdout, stderr) => {
         if (err) {
-          const msg = stderr?.trim() || err.message
+          // The bridge prints its unknown-command answer to STDOUT and exits 1
+          // (cos_api_bridge.py), so an older checkout must be probed there too, or
+          // every learning route answers 503 instead of not-configured (QA 2026-09-06).
+          const msg = stderr?.trim() || stdout?.trim() || err.message
           if (typeof msg === 'string' && msg.includes('unknown command')) {
             return resolvePromise({ error: { code: 'cos_pipeline_not_configured', message: msg } })
           }

package/server/lib/task-dispatcher.ts

@@ -150,6 +150,19 @@ function classifySubmitError(error: unknown): 'identity_conflict' | 'adopt' | 'f
   return 'transient'
 }
 
+/** A task is dispatchable only once someone has said what finished looks like.
+ *
+ *  Checked in THREE places on purpose, because there are two dispatch paths:
+ *  runTaskNow refuses early so the caller gets a 409 before slots are taken,
+ *  pickEligible skips the row so the timer does not retry it every tick, and
+ *  mintRun is the fail-closed backstop — it is the one function BOTH paths call,
+ *  which the earlier "one choke point" comment on runTaskNow wrongly claimed of
+ *  runTaskNow itself. A due row with no finish line used to fire unattended.
+ */
+function hasFinishLine(row: BridgeTaskRow): boolean {
+  return Boolean(row.done_when && row.done_when.trim())
+}
+
 async function mintRun(
   deps: TaskDispatcherDeps,
   row: BridgeTaskRow,
@@ -159,6 +172,13 @@ async function mintRun(
   const config = configOf(deps)
   const clock = localClock(nowMs(deps), config.timezone)
   return serializeTaskWork(() => {
+    if (!hasFinishLine(row)) {
+      throw new TaskRunError(
+        409,
+        'done_when_required',
+        'Say what done looks like before running this task.',
+      )
+    }
     const paths = pathsOf(deps)
     const ledger = loadTaskLedger(paths)
     if (ledger.some(run => run.taskId === row.id && run.day === clock.day && (run.status === 'dispatching' || run.status === 'running'))) {
@@ -284,6 +304,10 @@ function pickEligible(
   if (todayRuns.length >= capPerDay) return []
   return rows.filter(row => {
     if (row.archived || row.delegated || row.is_checked) return false
+    // A scheduled run is unattended, so it needs the finish line MORE than a
+    // manual one, not less. Skipped here rather than thrown so the timer does
+    // not burn a dispatch slot on it every tick.
+    if (!hasFinishLine(row)) return false
     if (!isCatchUpDue(row, now, tz, catchUpMinutes)) return false
     if (row.agent_state === 'running') return false
     const inDay = todayRuns.filter(run => run.taskId === row.id)
@@ -359,9 +383,10 @@ export async function runTaskNow(id: string, domain: string, injected?: TaskDisp
     throw new TaskRunError(409, 'task_running', 'A run is already in flight for this task.')
   }
   // No finish line, no dispatch. An agent sent at a task with no definition of
-  // done cannot succeed at it and cannot be judged to have failed either, so
-  // this fails closed at the one choke point every dispatch passes through.
-  if (!row.done_when || !row.done_when.trim()) {
+  // done cannot succeed at it and cannot be judged to have failed either. This
+  // is the EARLY refusal on the manual path only — mintRun is the backstop both
+  // paths share. See hasFinishLine.
+  if (!hasFinishLine(row)) {
     throw new TaskRunError(
       409,
       'done_when_required',

package/server/routes/memory.ts

@@ -13,8 +13,18 @@ import { searchMemories } from '../lib/context-library-search.js'
 function contextConfigured(): boolean {
   return contextSourceAvailable() !== null
 }
-import {
+import { LEARNING_REVIEW_LIMIT,
+  GRAPH_ENTITY_ID_LIMIT,
+  LEARNING_EVENT_ID_PATTERN,
   MEMORY_ID_PATTERN,
+  normalizeGraphEntity,
+  normalizeGraphPassages,
+  normalizeGraphSearch,
+  normalizeGraphStatus,
+  normalizeIndexBuildKickoff,
+  normalizeLearningEventDetail,
+  normalizeLearningEvents,
+  normalizeLearningStatus,
   normalizeMemoryDetail,
   normalizeMemoryList,
   normalizeMemoryOverview,
@@ -25,6 +35,7 @@ export const memoryRouter = Router()
 let overviewCache: { expiresAt: number; value: ReturnType<typeof normalizeMemoryOverview> } | null = null
 
 memoryRouter.get('/context/status', async (_req, res) => {
+  noStore(res)
   if (!contextConfigured()) {
     const state = pythonBridgeState()
     res.json(normalizeContextBrowserStatus({
@@ -34,15 +45,241 @@ memoryRouter.get('/context/status', async (_req, res) => {
     }))
     return
   }
-  try {
-    const data = await callPython(['context-status'], 8_000)
-    res.json(normalizeContextBrowserStatus(data))
-  } catch {
+  // Both bridge calls are created in ONE synchronous statement so the second
+  // never extends the wall time past the first (8 s worst case, not 9.5 s,
+  // against Control's 12 s helper timeout). The base call keeps its exact
+  // semantics; the learning/graph blocks are additive and drop silently when
+  // the second call is rejected, slow, or answers with an error (an older
+  // bridge prints an unknown-command error and exits 1, which rejects).
+  const [base, extra] = await Promise.allSettled([
+    callPython(['context-status'], 8_000),
+    callPython(['context-learning-graph-status'], 1_500),
+  ])
+  if (base.status === 'rejected') {
     res.json(normalizeContextBrowserStatus({
       available: false, protocol: 1, state: 'bridge_error',
       memory: { available: false, total: 0, state: 'bridge_error', reason: 'bridge_error' },
       threads: { available: false, total: 0, active: 0, stale: 0, resolved: 0, state: 'bridge_error', reason: 'bridge_error' },
     }))
+    return
+  }
+  const extraPayload = extra.status === 'fulfilled' && bridgePayload(extra.value) ? extra.value : null
+  const baseValue = bridgePayload(base.value) ? base.value : {}
+  res.json(normalizeContextBrowserStatus({
+    ...baseValue,
+    ...(extraPayload ? { learning: extraPayload.learning, graph: extraPayload.graph } : {}),
+  }))
+})
+
+/** True only for an object payload that is not an `{ error }` answer. */
+/**
+ * A bridge answer that is a payload rather than a failure. An `error` KEY is not
+ * an error by itself: the graph-passages shape always carries one, `null` on
+ * success (graph_context._passages_shape), so only a non-null value counts.
+ */
+function bridgePayload(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) && bridgeErrorCode(value) === null
+}
+
+function bridgeErrorCode(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value) || !('error' in value)) return null
+  const error = (value as { error: unknown }).error
+  if (error === null || error === undefined) return null
+  if (typeof error === 'string') return error
+  if (error && typeof error === 'object' && typeof (error as { code?: unknown }).code === 'string') return (error as { code: string }).code
+  return 'bridge_error'
+}
+
+/**
+ * Map a learning/knowledge bridge answer to an HTTP status. Never a 200 for an
+ * `{ error }` payload: the file tier answers every learning command with the
+ * string-form `cos_pipeline_not_configured`, and an empty object would read as
+ * success.
+ */
+function sendBridgeAnswer(res: import('express').Response, data: unknown, normalize: (value: unknown) => unknown): void {
+  const code = bridgeErrorCode(data)
+  if (code) {
+    const notFound = code.endsWith('_not_found')
+    const invalid = code.startsWith('invalid_')
+    res.status(notFound ? 404 : invalid ? 400 : 503).json({ error: code })
+    return
+  }
+  const value = normalize(data)
+  if (value === null || value === undefined) {
+    res.status(404).json({ error: 'record_not_found' })
+    return
+  }
+  res.json(value)
+}
+
+function noStore(res: import('express').Response): void {
+  res.set('Cache-Control', 'private, no-store')
+}
+
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/
+
+// ── Recent learning (6.44.5) ──
+
+memoryRouter.get('/context/learning/status', async (_req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    sendBridgeAnswer(res, await callPython(['learning-status', '--no-memory'], 8_000), normalizeLearningStatus)
+  } catch (error) {
+    console.warn('[context] learning bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'learning_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/learning', async (req, res) => {
+  noStore(res)
+  const days = boundedInteger(req.query.days, 30, 1, 3650)
+  const limit = boundedInteger(req.query.limit, 50, 1, 50)
+  const kind = typeof req.query.kind === 'string' ? req.query.kind.replace(/[^a-z,]/g, '').slice(0, 160) : ''
+  const sinceTs = typeof req.query.since_ts === 'string' && Number.isFinite(Date.parse(req.query.since_ts)) ? req.query.since_ts.slice(0, 40) : ''
+  const sinceId = typeof req.query.since_event_id === 'string' && LEARNING_EVENT_ID_PATTERN.test(req.query.since_event_id) ? req.query.since_event_id : ''
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  const args = ['learning-events', `--days=${days}`, `--limit=${limit}`]
+  if (kind) args.push(`--kind=${kind}`)
+  if (sinceTs) args.push(`--since-ts=${sinceTs}`)
+  if (sinceId) args.push(`--since-event-id=${sinceId}`)
+  try {
+    sendBridgeAnswer(res, await callPython(args, 8_000), value => normalizeLearningEvents(value, limit))
+  } catch (error) {
+    console.warn('[context] learning bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'learning_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/learning/review', async (req, res) => {
+  noStore(res)
+  // The strict To review set (learning_events.to_review) as event rows, so the
+  // chip, Doctor and the list count the same thing. Small set: one page.
+  const limit = boundedInteger(req.query.limit, LEARNING_REVIEW_LIMIT, 1, LEARNING_REVIEW_LIMIT)
+  const days = req.query.days === undefined ? null : boundedInteger(req.query.days, 3650, 1, 3650)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    const args = ['learning-to-review', `--limit=${limit}`, ...(days ? [`--days=${days}`] : [])]
+    sendBridgeAnswer(res, await callPython(args, 8_000), value => normalizeLearningEvents(value, limit, LEARNING_REVIEW_LIMIT))
+  } catch (error) {
+    console.warn('[context] learning review bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'learning_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/learning/:id', async (req, res) => {
+  noStore(res)
+  if (!LEARNING_EVENT_ID_PATTERN.test(req.params.id)) { res.status(400).json({ error: 'invalid_event_id' }); return }
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    sendBridgeAnswer(res, await callPython(['learning-event', `--id=${req.params.id}`], 8_000), normalizeLearningEventDetail)
+  } catch (error) {
+    console.warn('[context] learning bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'learning_unavailable' })
+  }
+})
+
+// ── Knowledge graph (6.44.5) ──
+
+memoryRouter.get('/context/graph/status', async (_req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    sendBridgeAnswer(res, await callPython(['graph-status'], 8_000), normalizeGraphStatus)
+  } catch (error) {
+    console.warn('[context] graph bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/graph/search', async (req, res) => {
+  noStore(res)
+  const query = typeof req.query.q === 'string' ? req.query.q.trim() : ''
+  if (query.length < 2 || query.length > 160 || CONTROL_CHARACTER.test(query)) {
+    res.status(400).json({ error: 'q must be 2 to 160 characters', reason: 'invalid_query' })
+    return
+  }
+  const limit = boundedInteger(req.query.limit, 30, 1, 30)
+  const offset = boundedInteger(req.query.offset, 0, 0, 100_000)
+  const type = typeof req.query.type === 'string' ? req.query.type.replace(/[^A-Za-z0-9_ -]/g, '').slice(0, 40) : ''
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  // One token per value (`--q=...`): a value beginning with `-` is then never
+  // read by argparse as a flag (QA 2026-09-06).
+  const args = ['graph-search', `--q=${query}`, `--limit=${limit}`, `--offset=${offset}`]
+  if (type) args.push(`--type=${type}`)
+  try {
+    sendBridgeAnswer(res, await callPython(args, 8_000), value => normalizeGraphSearch(value, limit))
+  } catch (error) {
+    console.warn('[context] graph bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/graph/entity', async (req, res) => {
+  noStore(res)
+  const id = typeof req.query.id === 'string' ? req.query.id : ''
+  if (!id || id.length > GRAPH_ENTITY_ID_LIMIT || CONTROL_CHARACTER.test(id)) {
+    res.status(400).json({ error: 'invalid_entity_id' })
+    return
+  }
+  const limit = boundedInteger(req.query.limit, 30, 1, 30)
+  const offset = boundedInteger(req.query.offset, 0, 0, 100_000)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    const answer = await callPython(['graph-entity', `--id=${id}`, `--offset=${offset}`, `--limit=${limit}`], 8_000)
+    // A no-index or unknown-entity answer is a PAYLOAD from the bridge (found: false);
+    // it becomes a 404 with the class Control renders, never a 503 (QA 2026-09-06).
+    if (bridgePayload(answer) && answer.found !== true) {
+      res.status(404).json({ error: answer.index_state === 'missing' ? 'index_missing' : 'entity_not_found' })
+      return
+    }
+    sendBridgeAnswer(res, answer, value => normalizeGraphEntity(value))
+  } catch (error) {
+    console.warn('[context] graph bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
+  }
+})
+
+memoryRouter.get('/context/graph/passages', async (req, res) => {
+  noStore(res)
+  const entity = typeof req.query.entity === 'string' ? req.query.entity : ''
+  const relationA = typeof req.query.relationA === 'string' ? req.query.relationA : ''
+  const relationB = typeof req.query.relationB === 'string' ? req.query.relationB : ''
+  const bad = (value: string) => value.length > GRAPH_ENTITY_ID_LIMIT || CONTROL_CHARACTER.test(value)
+  if ((!entity && !(relationA && relationB)) || bad(entity) || bad(relationA) || bad(relationB) || (entity && (relationA || relationB))) {
+    res.status(400).json({ error: 'invalid_relation' })
+    return
+  }
+  const limit = boundedInteger(req.query.limit, 5, 1, 5)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  const args = entity
+    ? ['graph-passages', `--entity=${entity}`, `--limit=${limit}`]
+    : ['graph-passages', `--relation-a=${relationA}`, `--relation-b=${relationB}`, `--limit=${limit}`]
+  try {
+    sendBridgeAnswer(res, await callPython(args, 8_000), normalizeGraphPassages)
+  } catch (error) {
+    console.warn('[context] graph bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
+  }
+})
+
+/**
+ * 202 Accepted: the bridge command only SPAWNS the detached build
+ * (start_new_session) and returns its receipt at once, so this handler never
+ * holds a lock, imports the SDK, or parses GraphML, and returns well inside the
+ * drain windows. Poll GET /context/graph/status for `build.state`.
+ */
+memoryRouter.post('/context/graph/index', async (_req, res) => {
+  noStore(res)
+  if (!contextConfigured()) { res.status(503).json({ error: pythonBridgeState() }); return }
+  try {
+    const data = await callPython(['graph-index-build', '--reason', 'control'], 5_000)
+    const code = bridgeErrorCode(data)
+    if (code) { res.status(503).json({ error: code }); return }
+    res.status(202).json(normalizeIndexBuildKickoff(data))
+  } catch (error) {
+    console.warn('[context] graph bridge failure:', (error as Error).message)
+    res.status(503).json({ error: 'graph_unavailable' })
   }
 })