@gotcos/glasses-server 6.44.3 → 6.44.5

package/CHANGELOG.md

@@ -1,3 +1,55 @@
+## 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.
+- Eight 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.
+
+- A task row carries `stage` (planning, active or review) and `doneWhen`. Both
+  live in the tasks.md line, not a sidecar: the task id is a sha256 of the
+  normalized description, so an id-keyed store would orphan itself the first time
+  the text was edited. An unmarked row reads as planning, so nothing needed
+  migrating.
+- `PATCH /api/tasks/:id` accepts `stage` and `doneWhen`.
+- **`runTaskNow` refuses a task with no finish line**, `409 done_when_required`,
+  at the single choke point every dispatch passes through. An agent sent at a
+  task with no definition of done cannot succeed at it and cannot be judged to
+  have failed either.
+- Fixes a round-trip bug older than this release: the writer joins end-of-line
+  markers with spaces while the reader's regex allowed none between them, so a
+  row carrying both a run time and an agent marker silently lost the run time on
+  every read.
+
 ## 6.44.3
 
 A task row carries enough to show and edit it.

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 with the bridge state 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.3",
+  "version": "6.44.5",
   "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,423 @@ 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
+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): {
+  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, LEARNING_LIST_LIMIT))
+  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),
+  }
+}
+
+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 (key === 'bodies' as string) 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: '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 +807,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 +841,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,25 @@ 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',
+] 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 +205,28 @@ 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':
+      return { error: 'cos_pipeline_not_configured' }
     case 'task-rows':
     case 'task-capture':
     case 'task-set-run-at':

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)
@@ -358,6 +382,17 @@ export async function runTaskNow(id: string, domain: string, injected?: TaskDisp
   if (row.agent_state === 'running') {
     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. 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',
+      'Say what done looks like before running this task.',
+    )
+  }
   const runAt = parseRunAt(row.run_at)
   if (runAt && runAt.day > clock.day) {
     throw new TaskRunError(409, 'scheduled_future', 'Run now is not allowed on a future scheduled task.')

package/server/lib/task-store.ts

@@ -102,6 +102,12 @@ export interface BridgeTaskRow {
   agent_no: number | null
   section: string
   section_day: string | null
+  /** Workflow stage. null/absent means planning, the unmarked default.
+   *  Optional so new server code against an older bridge degrades to planning
+   *  rather than throwing during a partial deploy. */
+  stage?: 'planning' | 'active' | 'review' | null
+  /** The finish line. A dispatch is refused while this is empty. */
+  done_when?: string | null
 }
 
 export interface TaskFlags {
@@ -112,6 +118,10 @@ export interface TaskFlags {
   carriedOver: boolean
 }
 
+/** Board stage. Planning is the default and carries no marker in tasks.md. */
+export type TaskStage = 'planning' | 'active' | 'review'
+export const TASK_STAGES: readonly TaskStage[] = ['planning', 'active', 'review']
+
 export interface TaskBoardRow {
   id: string
   ref: string
@@ -131,6 +141,9 @@ export interface TaskBoardRow {
   runAt?: string
   section: string
   sectionDay?: string
+  stage: TaskStage
+  /** Absent until someone says what finished looks like. Gates `run`. */
+  doneWhen?: string
   due: boolean
   missed: boolean
   failed: boolean
@@ -414,6 +427,8 @@ export function projectRow(
     ...(runAt ? { runAt: new Date(taskInstant(runAt.day, runAt.minutes, tz)).toISOString() } : {}),
     section: row.section,
     ...(row.section_day ? { sectionDay: row.section_day } : {}),
+    stage: row.stage ?? 'planning',
+    ...(row.done_when ? { doneWhen: row.done_when } : {}),
     ...mark,
   }
 }
@@ -486,6 +501,26 @@ export async function setTaskText(domain: string, id: string, text: string): Pro
   await withLockRetry(() => bridge(['task-set-text', domain, id], clean))
 }
 
+/** Move a task between board stages. 'planning' clears the marker. */
+export async function setTaskStage(domain: string, id: string, stage: TaskStage): Promise<void> {
+  if (!TASK_STAGES.includes(stage)) {
+    throw new TaskRunError(422, 'invalid_stage', `stage must be one of ${TASK_STAGES.join(', ')}`)
+  }
+  await withLockRetry(() => bridge(['task-set-stage', domain, id, stage === 'planning' ? '--clear' : stage]))
+}
+
+/** Set or clear the finish line. Empty clears it, which re-blocks `run`. */
+export async function setTaskDoneWhen(domain: string, id: string, text: string): Promise<void> {
+  const clean = text.replace(/\s+/g, ' ').trim()
+  if (clean.length > 500) {
+    throw new TaskRunError(422, 'done_when_too_long', 'done_when must be 500 characters or fewer')
+  }
+  if (clean.includes('**')) {
+    throw new TaskRunError(422, 'invalid_done_when', 'done_when cannot contain ** markup')
+  }
+  await withLockRetry(() => bridge(['task-set-done-when', domain, id], clean))
+}
+
 export async function moveTask(domain: string, id: string, section: string, nowMs = Date.now()): Promise<void> {
   const { clock } = briefContext(nowMs)
   const args = ['task-move', domain, id, '--section', section]

package/server/routes/memory.ts

@@ -14,7 +14,17 @@ function contextConfigured(): boolean {
   return contextSourceAvailable() !== null
 }
 import {
+  GRAPH_ENTITY_ID_LIMIT,
+  LEARNING_EVENT_ID_PATTERN,
   MEMORY_ID_PATTERN,
+  normalizeGraphEntity,
+  normalizeGraphPassages,
+  normalizeGraphSearch,
+  normalizeGraphStatus,
+  normalizeIndexBuildKickoff,
+  normalizeLearningEventDetail,
+  normalizeLearningEvents,
+  normalizeLearningStatus,
   normalizeMemoryDetail,
   normalizeMemoryList,
   normalizeMemoryOverview,
@@ -34,15 +44,209 @@ 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: '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 {
+    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', String(days), '--limit', String(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 {
+    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 {
+    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 {
+    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 }
+  const args = ['graph-search', '--q', query, '--limit', String(limit), '--offset', String(offset)]
+  if (type) args.push('--type', type)
+  try {
+    sendBridgeAnswer(res, await callPython(args, 8_000), value => normalizeGraphSearch(value, limit))
+  } catch {
+    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 {
+    sendBridgeAnswer(res, await callPython(['graph-entity', '--id', id, '--offset', String(offset), '--limit', String(limit)], 8_000),
+      value => normalizeGraphEntity(value))
+  } catch {
+    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', String(limit)]
+    : ['graph-passages', '--relation-a', relationA, '--relation-b', relationB, '--limit', String(limit)]
+  try {
+    sendBridgeAnswer(res, await callPython(args, 8_000), normalizeGraphPassages)
+  } catch {
+    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 {
+    res.status(503).json({ error: 'graph_unavailable' })
   }
 })
 

package/server/routes/tasks.ts

@@ -19,6 +19,9 @@ import {
   taskDomains,
   tasksGate,
   workBadgeCount,
+  setTaskStage,
+  setTaskDoneWhen,
+  type TaskStage,
 } from '../lib/task-store.js'
 
 export const tasksRouter = Router()
@@ -191,8 +194,12 @@ tasksRouter.patch('/tasks/:id', async (req, res) => {
       await moveTask(domain, req.params.id, String(body.section))
     } else if ('checked' in body) {
       await checkTask({ domain, id: req.params.id, checked: body.checked === true })
+    } else if ('stage' in body) {
+      await setTaskStage(domain, req.params.id, String(body.stage) as TaskStage)
+    } else if ('doneWhen' in body) {
+      await setTaskDoneWhen(domain, req.params.id, body.doneWhen == null ? '' : String(body.doneWhen))
     } else {
-      throw new TaskRunError(400, 'invalid_patch', 'Expected text, runAt, section, or checked.')
+      throw new TaskRunError(400, 'invalid_patch', 'Expected text, runAt, section, checked, stage, or doneWhen.')
     }
     res.json({ ok: true })
   } catch (error) {