@joe-broadhead/opencode-mem 0.9.12 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. package/CHANGELOG.md +1934 -2
  2. package/README.md +29 -17
  3. package/SECURITY.md +3 -1
  4. package/docs/agent-instructions.md +17 -0
  5. package/docs/agent-protocol.md +8 -8
  6. package/docs/permissions.md +22 -4
  7. package/package.json +7923 -217
  8. package/shared/page-paths.js +44 -0
  9. package/skills/mem.pages/SKILL.md +8 -1
  10. package/skills/mem.usage/SKILL.md +15 -15
  11. package/src/action-grant-keys.js +159 -0
  12. package/src/action-grant.js +439 -0
  13. package/src/actions.js +1690 -0
  14. package/src/backend/records.js +25 -2
  15. package/src/backend/v3.js +76 -22
  16. package/src/call-shapes.js +17 -16
  17. package/src/collector-lock.js +533 -62
  18. package/src/collector-service.js +153 -26
  19. package/src/collector.js +627 -33
  20. package/src/config.js +79 -6
  21. package/src/connect.js +106 -8
  22. package/src/credentials.js +123 -25
  23. package/src/events.js +174 -3
  24. package/src/forget-turn.js +141 -0
  25. package/src/host-refusal.js +78 -0
  26. package/src/index.js +209 -22
  27. package/src/jobs/host.js +557 -0
  28. package/src/ops/codes.js +110 -0
  29. package/src/ops/copy-lineage.js +42 -0
  30. package/src/ops/index.js +28 -0
  31. package/src/ops/space-ops.js +1936 -0
  32. package/src/outlinks.js +103 -0
  33. package/src/p2-reservation.js +151 -0
  34. package/src/permissions.js +30 -0
  35. package/src/plugins/descriptor.js +62 -0
  36. package/src/plugins/discovery.js +318 -0
  37. package/src/plugins/grants.js +178 -0
  38. package/src/plugins/locate.js +319 -0
  39. package/src/plugins/manifest.js +1162 -0
  40. package/src/plugins/source-contract/index.js +34 -0
  41. package/src/plugins/source-contract/policy.js +102 -0
  42. package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
  43. package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
  44. package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
  45. package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
  46. package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
  47. package/src/plugins/source-contract/vendor/broker-client.js +93 -0
  48. package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
  49. package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
  50. package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
  51. package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
  52. package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
  53. package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
  54. package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
  55. package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
  56. package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
  57. package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
  58. package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
  59. package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
  60. package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
  61. package/src/plugins/source-contract/vendor/cursor.js +26 -0
  62. package/src/plugins/source-contract/vendor/descriptor.js +34 -0
  63. package/src/plugins/source-contract/vendor/events.js +257 -0
  64. package/src/plugins/source-contract/vendor/index.js +10 -0
  65. package/src/plugins/source-contract/vendor/params.js +22 -0
  66. package/src/plugins/source-contract/vendor/permission.js +28 -0
  67. package/src/plugins/source-contract/vendor/pick.js +22 -0
  68. package/src/plugins/source-contract/vendor/read.js +29 -0
  69. package/src/plugins/source-contract/vendor/registry.js +23 -0
  70. package/src/plugins/source-contract/vendor/schema.js +17 -0
  71. package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
  72. package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
  73. package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
  74. package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
  75. package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
  76. package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
  77. package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
  78. package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
  79. package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
  80. package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
  81. package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
  82. package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
  83. package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
  84. package/src/plugins/source-contract/vendor/schemas.js +19 -0
  85. package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
  86. package/src/plugins/verify.js +56 -0
  87. package/src/protocol.js +21 -5
  88. package/src/recall.js +104 -5
  89. package/src/records.js +61 -2
  90. package/src/requests.js +216 -0
  91. package/src/runtime.js +89 -7
  92. package/src/setup-time.js +68 -0
  93. package/src/skills.js +230 -8
  94. package/src/source-ids.js +25 -0
  95. package/src/sources/declaration.js +365 -0
  96. package/src/sources/reads.js +772 -0
  97. package/src/sources/rpc.js +151 -0
  98. package/src/sources.js +409 -90
  99. package/src/spaces.js +283 -11
  100. package/src/spool.js +61 -4
  101. package/src/stated.js +10 -5
  102. package/src/storable.js +139 -0
  103. package/src/tools/commitments.js +47 -5
  104. package/src/tools/held-write.js +36 -13
  105. package/src/tools/index.js +27 -0
  106. package/src/tools/ingest.js +27 -2
  107. package/src/tools/memory.js +52 -14
  108. package/src/tools/page.js +95 -9
  109. package/src/tools/recall.js +208 -4
  110. package/src/tools/records-kit.js +2 -1
  111. package/src/tools/share.js +42 -3
  112. package/src/tools/shared.js +44 -4
  113. package/src/tools/space-lifecycle.js +278 -0
  114. package/src/tools/spaces.js +373 -29
  115. package/src/tools/status.js +9 -2
  116. package/src/tools/wiki.js +34 -4
  117. package/src/util.js +110 -6
  118. package/src/vendor/source-contract/README.md +24 -0
  119. package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
  120. package/src/vendor/source-contract/VENDOR.json +81 -0
  121. package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
  122. package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
  123. package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
  124. package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
  125. package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
  126. package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
  127. package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
  128. package/src/vendor/source-contract/cursor.js +26 -0
  129. package/src/vendor/source-contract/events.js +257 -0
  130. package/src/vendor/source-contract/registry.js +23 -0
  131. package/src/vendor/source-contract/tools-rpc.js +42 -0
  132. package/src/views/access-reads.js +256 -0
  133. package/src/views/communities.js +77 -0
  134. package/src/views/contracts.js +1183 -36
  135. package/src/views/inbox-bytes.js +103 -0
  136. package/src/views/overdue.js +1 -1
  137. package/src/views/profile.js +31 -0
  138. package/src/views/receipt.js +81 -0
  139. package/src/views/records-reads.js +869 -37
  140. package/src/views/rpc.js +159 -11
  141. package/src/views/shape.js +8 -5
  142. package/views/memory.html +16 -3
  143. package/views/pages.html +2 -2
  144. package/views/remembered.html +130 -0
@@ -1,6 +1,6 @@
1
1
  import fs from "node:fs"
2
2
  import path from "node:path"
3
- import { DEFAULT_ACCOUNT, cadenceMs, collectSessionId, collectSessionRules, collectableSources, createCollector, hostSourceLister, rulesHash } from "./collector.js"
3
+ import { DEFAULT_ACCOUNT, cadenceMs, collectSessionId, collectSessionRules, collectableSources, createCollector, hostBrokerTransport, hostSourceLister, hostSourceProber, rulesHash } from "./collector.js"
4
4
  import { createLease } from "./collector-lock.js"
5
5
  import { knownSources, sourceEntry } from "./sources.js"
6
6
  import { errorMessage, isPlainObject, oneLine } from "./util.js"
@@ -98,6 +98,15 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
98
98
  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 })
99
99
  const temp = `${sessionsFile}.${lock.id}.tmp`
100
100
  fs.writeFileSync(temp, JSON.stringify(value, null, 2), { mode: 0o600 })
101
+ // Fenced at its commit, as the status write is: a sessions file already
102
+ // in flight when another process takes the lease never lands, so a lost
103
+ // holder cannot clobber the new holder's record of a binding's session.
104
+ // `held` (not `stillHolder`): this write is also made outside a run, by
105
+ // an unbind, where a lost lease is not this call's to report.
106
+ if (!lock.held()) {
107
+ fs.rmSync(temp, { force: true })
108
+ return
109
+ }
101
110
  fs.renameSync(temp, sessionsFile)
102
111
  } catch (error) {
103
112
  log?.warn?.("collector sessions could not be written", { error: errorMessage(error) })
@@ -232,7 +241,15 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
232
241
  }
233
242
 
234
243
  // No host schedule (0.9.7): it needed one session for every source; collection runs here, per binding.
235
- const collector = createCollector({ scheduler: null, lister: hostSourceLister(ctx), log })
244
+ // The broker is offered by the host's tools RPC channel alone (B3); a host
245
+ // without one runs every declared read embedded.
246
+ const brokerState = { timedOut: false, embedded: new Set() }
247
+ const collector = createCollector({
248
+ scheduler: null,
249
+ lister: hostSourceLister(ctx, { broker: hostBrokerTransport(ctx, { state: brokerState }), brokerState }),
250
+ prober: hostSourceProber(ctx),
251
+ log,
252
+ })
236
253
 
237
254
  const timers = { startup: null, interval: null, heartbeat: null, catchUp: null }
238
255
  let active = null
@@ -241,12 +258,24 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
241
258
  let last = null
242
259
  let stopped = false
243
260
  let lastStartedAt = 0
261
+ /** Set when a run finds the lease has gone to another process: it stops, and writes no further status as a holder. */
262
+ let leaseLost = false
263
+
264
+ /** A run's refusal once the lease is another process's: it must not read, write or report as a holder. */
265
+ const LOST = "another OpenCode process holds the collector lease now; this run stopped before writing more"
244
266
 
245
267
  function writeStatus(status) {
246
268
  try {
247
269
  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 })
248
270
  const temp = `${statusFile}.${lock.id}.tmp`
249
271
  fs.writeFileSync(temp, JSON.stringify(status, null, 2), { mode: 0o600 })
272
+ // The commit is fenced too, not only the start of the write: a status
273
+ // already in flight when another process takes the lease never lands, so
274
+ // a lost holder cannot clobber the new holder's status with it.
275
+ if (!stillHolder()) {
276
+ fs.rmSync(temp, { force: true })
277
+ return
278
+ }
250
279
  fs.renameSync(temp, statusFile)
251
280
  } catch (error) {
252
281
  log?.warn?.("collector status could not be written", { error: errorMessage(error) })
@@ -323,6 +352,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
323
352
  }
324
353
  const started = clock.now()
325
354
  lastStartedAt = started
355
+ leaseLost = false
326
356
  const results = []
327
357
  active = { started, trigger, only, results, probes: [], promise: null }
328
358
  active.promise = collect(trigger, { only, sessionID, results, started })
@@ -336,32 +366,69 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
336
366
  return { started: true }
337
367
  }
338
368
 
369
+ /** Is this process still the collector? A lost lease stops the run before its next read or write. */
370
+ function stillHolder() {
371
+ if (lock.heartbeat()) return true
372
+ if (!leaseLost) log?.warn?.("collection stopped: another OpenCode process holds the collector lease", { trigger: last?.trigger })
373
+ leaseLost = true
374
+ leader = false
375
+ return false
376
+ }
377
+
378
+ /**
379
+ * Refuse to act unless this process still demonstrably holds the lease: every
380
+ * read and every write the lease guards is taken only after this, so a
381
+ * process whose lease another one took (a machine that woke, a displaced
382
+ * taker) never writes as a holder — not even the run's first status line.
383
+ */
384
+ function guard() {
385
+ if (stillHolder()) return
386
+ throw new Error(LOST)
387
+ }
388
+
339
389
  function remember(trigger, outcome) {
340
- last = { trigger, at: new Date(clock.now()).toISOString(), state: "skipped", reason: outcome.skipped, sources: [] }
341
- log?.debug?.("collection skipped", { trigger, reason: outcome.skipped })
342
- return outcome
390
+ // A skipped run's reason is kept in the status file and shown from it: a
391
+ // broker's or a lock's failure text, so redacted where it is kept (F1/F2).
392
+ const reason = outcome.skipped === undefined ? undefined : oneLine(errorMessage(outcome.skipped), 300)
393
+ last = { trigger, at: new Date(clock.now()).toISOString(), state: "skipped", reason, sources: [] }
394
+ log?.debug?.("collection skipped", { trigger, reason })
395
+ return { ...outcome, skipped: reason }
343
396
  }
344
397
 
345
398
  async function collect(trigger, { only, sessionID, results, started }) {
346
399
  // The last run's state, read before this run's "running" line replaces it: its cadence times and what was left behind.
347
400
  const previous = readStatus()
348
401
  const collected = isPlainObject(previous?.collected) ? previous.collected : {}
349
- writeStatus({ state: "running", trigger, pid: process.pid, started: new Date(started).toISOString(), sources: [], collected })
350
402
  const records = recordsOf(toolkit)
403
+ // Every call behind the lease re-verifies it first: this run reads and
404
+ // writes nothing as a holder unless the lock still proves it is one.
405
+ const call = (operation, body, where) => {
406
+ guard()
407
+ return records.call(operation, body, where)
408
+ }
409
+ guard()
410
+ writeStatus({ state: "running", trigger, pid: process.pid, started: new Date(started).toISOString(), sources: [], collected })
351
411
  let where = { sessionID }
352
412
  if (toolkit.control) {
353
413
  const resolved = await toolkit.resolvePrivateSpace({}, { sessionID, agent: runtime.agentFor?.(sessionID) })
354
414
  if (resolved.invalid || resolved.error) throw new Error(resolved.invalid || resolved.error)
355
415
  where = { space: resolved.context.space_id }
356
416
  }
357
- const listed = await records.call("sources.list", {}, where)
417
+ const listed = await call("sources.list", {}, where)
358
418
  const sources = listed?.sources ?? []
419
+ guard()
359
420
  await collector.sync(sources)
421
+ guard()
360
422
  await pruneSessions(sources, listed?.requests)
361
423
  // Each binding's calls run in that binding's own session (least privilege); never a broader one.
362
- const rpc = (binding) => rpcSession(null, binding)
424
+ const rpc = (binding) => {
425
+ // Read nothing as a holder that has lost the lease (a machine that woke
426
+ // after another process took over): the binding is reported, not read.
427
+ if (!stillHolder()) throw new Error(LOST)
428
+ return rpcSession(null, binding)
429
+ }
363
430
  const probes = active?.probes ?? []
364
- await collector.probeRequests({ requests: listed?.requests, only, now: clock.now(), sessionID: rpc, probes, report: (body) => records.call("sources.report", body, where) })
431
+ await collector.probeRequests({ requests: listed?.requests, only, now: clock.now(), sessionID: rpc, probes, report: (body) => call("sources.report", body, where) })
365
432
  const behind = new Set((Array.isArray(previous?.sources) ? previous.sources : []).filter((row) => row?.more && !row?.error).map((row) => keyOf(row)))
366
433
  const rows = new Map((Array.isArray(sources) ? sources : []).filter(isPlainObject).map((row) => [keyOf(row), row]))
367
434
  await collector.runOnce({
@@ -376,8 +443,17 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
376
443
  const last = Date.parse(collected[key] ?? rows.get(key)?.cursor_at ?? "")
377
444
  return !Number.isFinite(last) || clock.now() - last >= cadenceMs(binding.source) - DUE_SLACK_MS
378
445
  },
379
- cursor: (binding) => records.call("events.cursor", binding, where),
446
+ cursor: (binding) => call("events.cursor", binding, where),
447
+ // §8.3.4: a pause is the binding's, in the store, so every process and
448
+ // every job sees it — not only this run's result. One binding, one row.
449
+ // The reason is the source's own failure text and the store keeps it for
450
+ // every process and the console to read: redacted here, where it is
451
+ // stored, not only where it is shown (0.10.4's gate; review F1).
452
+ pause: (binding, reason, code) => call("plugins.pause", { source: binding.source, account: binding.account, reason: oneLine(errorMessage(reason), 200), code }, where),
380
453
  ingest: async (input) => {
454
+ // And write nothing as one: the page never lands, and the run leaves the
455
+ // status to the holder that has the lease.
456
+ guard()
381
457
  try {
382
458
  return await records.call("events.ingest", input, where)
383
459
  } catch (error) {
@@ -389,7 +465,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
389
465
  }
390
466
  },
391
467
  })
392
- await reportCollections(records, where, results)
468
+ await reportCollections(call, where, results)
393
469
  return finish(trigger, started, results, "", collectableSources(sources, { only }).length === 0, { probes, collected })
394
470
  }
395
471
 
@@ -399,13 +475,15 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
399
475
  * effort: a service older than 0.9.8 does not know the call, and a failed
400
476
  * report never fails the collection.
401
477
  */
402
- async function reportCollections(records, where, results) {
478
+ async function reportCollections(call, where, results) {
403
479
  for (const result of results) {
404
480
  if (result.notDue || typeof result.source !== "string") continue
405
- const body = { source: result.source, account: result.account ?? "default", ok: !result.error, accepted: Number.isInteger(result.accepted) ? result.accepted : undefined }
406
- if (result.error) body.error = oneLine(result.error, 300)
481
+ // `more` travels with the report (review S5): the console's Sources row says
482
+ // "catching up" from records, so it must know the run left pages behind.
483
+ const body = { source: result.source, account: result.account ?? "default", ok: !result.error, accepted: Number.isInteger(result.accepted) ? result.accepted : undefined, more: result.more === true }
484
+ if (result.error) body.error = oneLine(errorMessage(result.error), 300)
407
485
  try {
408
- await records.call("sources.collected", body, where)
486
+ await call("sources.collected", body, where)
409
487
  } catch (error) {
410
488
  log?.debug?.("the collection report was not recorded", { source: result.source, error: errorMessage(error) })
411
489
  }
@@ -423,13 +501,17 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
423
501
  pid: process.pid,
424
502
  started: new Date(started).toISOString(),
425
503
  ended: new Date(ended).toISOString(),
426
- ...(error ? { error: oneLine(error, 300) } : {}),
504
+ ...(error ? { error: oneLine(errorMessage(error), 300) } : {}),
427
505
  ...(none ? { none: true } : {}),
428
- sources: results.map(({ done: _done, ...result }) => ({ ...result, ...(result.error ? { error: oneLine(result.error, 300) } : {}) })),
506
+ sources: results.map(({ done: _done, ...result }) => storedResult(result)),
429
507
  ...(probes.length ? { probes: probes.map((probe) => ({ ...probe })) } : {}),
430
508
  collected: at,
431
509
  }
432
- writeStatus(last)
510
+ // A run writes no status as a holder unless the lock still proves it is
511
+ // one: the check is made now, not only when the run first noticed.
512
+ if (!leaseLost) stillHolder()
513
+ if (leaseLost) log?.info?.("collection run stopped: the lease is another process's", { trigger })
514
+ else writeStatus(last)
433
515
  const behind = results.some((result) => result.more && !result.error)
434
516
  if (behind && catchUps < CATCH_UP_RUNS && !stopped) {
435
517
  catchUps += 1
@@ -547,19 +629,33 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
547
629
  const who = !holder || lock.isStale(holder) ? "no process holds collector.lock now" : holder.id === lock.id ? "this process collects (it holds collector.lock)" : holderText(holder)
548
630
  lines.push(`collector: ${mode}; ${who}`)
549
631
  if (collector.scheduled) lines.push("collector: the host also runs the memory-collect schedule")
550
- if (last?.state === "skipped") lines.push(`collector: last attempt ${oneLine(last.at ?? "", 40)} (${oneLine(last.trigger ?? "?", 20)}) skipped: ${oneLine(last.reason ?? "", 200)}`)
632
+ if (last?.state === "skipped") lines.push(`collector: last attempt ${oneLine(last.at ?? "", 40)} (${oneLine(last.trigger ?? "?", 20)}) skipped: ${oneLine(errorMessage(last.reason ?? "unknown"), 200)}`)
551
633
  const status = active ? { state: "running", trigger: active.trigger, started: new Date(active.started).toISOString(), sources: active.results } : (readStatus() ?? (last?.state === "skipped" ? null : last))
552
634
  if (!status) {
553
635
  if (last?.state !== "skipped") lines.push("collector: no run yet")
554
636
  return lines.join("\n")
555
637
  }
556
638
  const when = status.state === "running" ? `running since ${oneLine(status.started ?? "", 40)}` : `last run ${oneLine(status.ended ?? status.started ?? "", 40)}`
557
- lines.push(`collector: ${when} (${oneLine(status.trigger ?? "?", 20)}${status.pid ? `, pid ${status.pid}` : ""})${status.state === "failed" ? ` failed: ${oneLine(status.error ?? "", 200)}` : ""}${status.none ? ": no source is enabled and confirmed" : ""}`)
639
+ lines.push(`collector: ${when} (${oneLine(status.trigger ?? "?", 20)}${status.pid ? `, pid ${status.pid}` : ""})${status.state === "failed" ? ` failed: ${oneLine(errorMessage(status.error ?? ""), 200)}` : ""}${status.none ? ": no source is enabled and confirmed" : ""}`)
558
640
  for (const result of Array.isArray(status.sources) ? status.sources : []) lines.push(`- ${describeResult(result)}`)
559
641
  for (const probe of Array.isArray(status.probes) ? status.probes : []) lines.push(`- ${describeProbe(probe)}`)
560
642
  return lines.join("\n")
561
643
  }
562
644
 
645
+ /**
646
+ * The bindings whose last run ended with `more: true` and no error: the source
647
+ * has more pages to give and the next run reads them. A binding's own row says
648
+ * so (G7) — `describeResult` says it in the run's lines, and this is the same
649
+ * fact for the sources list, keyed as the store keys a binding.
650
+ *
651
+ * @returns {Set<string>} `${source}\u0000${account}`
652
+ */
653
+ function behind() {
654
+ const status = active ? { state: "running", sources: active.results } : readStatus()
655
+ const rows = Array.isArray(status?.sources) ? status.sources : []
656
+ return new Set(rows.filter((row) => row?.more && !row?.error).map((row) => `${row.source}\u0000${row.account ?? "default"}`))
657
+ }
658
+
563
659
  return {
564
660
  // The core's surface, which mem_spaces and mem_ingest use.
565
661
  get scheduled() {
@@ -580,6 +676,7 @@ export function createCollectorService({ ctx, runtime, toolkit, clock = REAL_CLO
580
676
  begin,
581
677
  trigger,
582
678
  describe,
679
+ behind,
583
680
  get leader() {
584
681
  return leader
585
682
  },
@@ -600,19 +697,49 @@ function keyOf(row) {
600
697
  return `${row?.source ?? ""}\u0000${row?.account || DEFAULT_ACCOUNT}`
601
698
  }
602
699
 
700
+ /**
701
+ * What the status file keeps of one result. The file is read by every process
702
+ * and by the console, and it holds text a source or a plugin wrote — a
703
+ * refusal's reason, the sentence a source says about its own setup, a failed
704
+ * pause — so each is redacted here, at the file, as well as where it is made
705
+ * (0.10.4's gate; review F1 and F2).
706
+ */
707
+ export function storedResult(result) {
708
+ const kept = { ...result }
709
+ if (kept.error) kept.error = oneLine(errorMessage(kept.error), 300)
710
+ if (kept.refused_reason) kept.refused_reason = oneLine(errorMessage(kept.refused_reason), 200)
711
+ if (kept.setup) kept.setup = oneLine(errorMessage(kept.setup), 400)
712
+ if (kept.held) kept.held = oneLine(errorMessage(kept.held), 100)
713
+ if (kept.pause_error) kept.pause_error = oneLine(errorMessage(kept.pause_error), 200)
714
+ return kept
715
+ }
716
+
603
717
  /** One bind request's line: the account the source reported, or why it could not. */
604
718
  export function describeProbe(probe) {
605
719
  const name = `${oneLine(probe.source ?? "?", 40)}:${oneLine(probe.account ?? "?", 80)}`
606
- if (probe.error && !probe.owner?.id && probe.note === undefined) return `${name}: bind request: not asked this run (${oneLine(probe.error, 240)})`
607
- const what = probe.owner?.id ? `bind request: signed in as ${oneLine(probe.owner.label ?? probe.owner.id, 120)}; waiting for the person to confirm it` : `bind request: no account yet${probe.note ? ` (${oneLine(probe.note, 240)})` : ""}`
608
- const note = probe.owner?.id && probe.note ? `; the source says: ${oneLine(probe.note, 240)}` : ""
609
- return `${name}: ${what}${note}${probe.error ? `; the report failed (${oneLine(probe.error, 160)})` : ""}`
720
+ if (probe.error && !probe.owner?.id && probe.note === undefined) return `${name}: bind request: not asked this run (${oneLine(errorMessage(probe.error), 240)})`
721
+ // The note is the source's own sentence, kept in `plugin_requests.note`: a
722
+ // file the store holds and every answer reads, so it is shown redacted too.
723
+ const says = probe.note ? oneLine(errorMessage(probe.note), 240) : ""
724
+ const what = probe.owner?.id ? `bind request: signed in as ${oneLine(probe.owner.label ?? probe.owner.id, 120)}; waiting for the person to confirm it` : `bind request: no account yet${says ? ` (${says})` : ""}`
725
+ const note = probe.owner?.id && says ? `; the source says: ${says}` : ""
726
+ return `${name}: ${what}${note}${probe.error ? `; the report failed (${oneLine(errorMessage(probe.error), 160)})` : ""}`
610
727
  }
611
728
 
612
- /** One source's line: its counts, and why it stopped. */
729
+ /** One source's line: its counts, what it refused, and why it stopped. */
613
730
  export function describeResult(result) {
614
731
  if (result.notDue) return `${oneLine(result.source ?? "?", 40)}:${oneLine(result.account ?? "?", 80)}: not due (collected every ${Number(result.everyMinutes) || 30} minutes)`
615
732
  const counts = `${Number(result.accepted) || 0} new, ${Number(result.duplicates) || 0} already had, ${Number(result.refused) || 0} refused, ${Number(result.pages) || 0} page(s)`
733
+ // A refused event is a real loss — the contract's cursor moves past it — so
734
+ // the line names the newest one and why, not only how many (DESIGN §2.3.1).
735
+ const refused =
736
+ Number(result.refused) > 0 && (result.refused_reason || result.refused_id)
737
+ ? `; ${result.refused_id ? `the newest ${oneLine(result.refused_id, 100)} was refused` : "the newest refusal"}: ${oneLine(errorMessage(result.refused_reason ?? "no reason given"), 200)}`
738
+ : ""
616
739
  const name = `${oneLine(result.source ?? "?", 40)}:${oneLine(result.account ?? "?", 80)}`
617
- return `${name}: ${result.error ? `stopped (${oneLine(result.error, 240)}); ` : ""}${counts}${result.more ? "; more waits for the next run" : ""}${result.setup ? `; the source says: ${oneLine(result.setup, 240)}` : ""}`
740
+ // The message, never "[object Object]": a source’s failure arrives as a plain
741
+ // object, and the 0.10.3 gate (A15) caught an answer repeating the placeholder.
742
+ // The refusal trace is build/0.11’s (fix/source-kinds): a refused event is a
743
+ // real loss, so the line names the newest one and why.
744
+ return `${name}: ${result.error ? `stopped (${oneLine(errorMessage(result.error), 240)}); ` : ""}${counts}${refused}${result.more ? "; more waits for the next run" : ""}${result.setup ? `; the source says: ${oneLine(errorMessage(result.setup), 240)}` : ""}`
618
745
  }