@lawaty/lacode 1.3.0-beta.9 → 2.0.0-beta.0

package/docs/CONTEXT.md

@@ -30,8 +30,7 @@ the exploration it replaces is worse than no map:
   `src/orders/`". The cartographer is forbidden by name from writing directory
   listings, copying source, or restating what the README already says.
 - **One file per question.** Five navigation files, each with a defined scope, so
-  an agent reads one of them rather than all of them. A sixth file,
-  `active.md`, holds the work in flight rather than a map of the repository.
+  an agent reads one of them rather than all of them.
 - **Canonical entry points.** The highest-value thing in the map is a short
   "Start here" list per subsystem: the canonical files an agent should open, each
   with a one-phrase reason.
@@ -48,8 +47,7 @@ harness that produces a number for your own workload.
 
 ## The files in the map
 
-`.opencode/context/` holds the five navigation files below, plus one file that is
-a work list rather than a map:
+`.opencode/context/` holds the five navigation files below:
 
 | File | What belongs in it |
 | --- | --- |
@@ -58,7 +56,6 @@ a work list rather than a map:
 | `conventions.md` | Repository-specific rules: naming, module layout, error handling, testing, persistence. Read this before writing code, not after. |
 | `workflows.md` | The few runtime flows worth tracing end to end — how a request becomes a mutation, how a plugin hook reaches the thing it hooks. Read this when you need to know what actually happens at runtime. |
 | `decisions.md` | Architectural constraints that bind future work and that the repository's own decision log does not already record. Each entry states the constraint and points at the page or path that owns it. Capped at 120 non-blank lines; decision records and deliberation are not copied here. |
-| `active.md` | The active backlog: work in flight, grouped by the ISO week each task was opened in. A task that is not marked `[x]` is open and is never removed; a task that is finished and dated is kept for a week after it was finished, then dropped. The plugin enforces that window — see [How it stays current](#how-it-stays-current). Not a navigation file: there is no question it is the answer to. |
 
 The project's root `AGENTS.md` is the standing-instructions home: the client's
 own statement of intent, what they want worked on and how they want it
@@ -98,20 +95,19 @@ Every navigation entry has one shape, in every file:
   the drift check.
 
 Every file has a hard cap, counted in **non-blank lines**: architecture 150,
-contexts 200, conventions 150, workflows 150, decisions 120, active 60. Lines
-are the unit because they are what a reader pays for, they bound an entry that
-wraps to three lines, and the validator can count them exactly; an entry count
-does not bound cost, and a token count needs a tokenizer and is model-specific.
-The cap is enforced by a post-generation validator, not only by the prompt.
-
-The lifecycle generalises the window `active.md` already had. A finished backlog
-task is dropped after 7 days. A `[provisional]` entry in any navigation file is
-dropped 30 days after its `verified` date unless it is re-verified. `[binding]`
-and `[disputed]` never expire by age. An entry whose cited source no longer
-exists is **never** auto-dropped: it may be the only copy, so it is reported as
-unarchived and kept. Only provisional entries whose source still resolves are
-eligible for the sweep. The arithmetic lives in `src/lib/map-schema.ts`; the
-cartographer writes the shape, code decides what has aged out.
+contexts 200, conventions 150, workflows 150, decisions 120. Lines are the unit
+because they are what a reader pays for, they bound an entry that wraps to three
+lines, and the validator can count them exactly; an entry count does not bound
+cost, and a token count needs a tokenizer and is model-specific. The cap is
+enforced by a post-generation validator, not only by the prompt.
+
+A `[provisional]` entry in any navigation file is dropped 30 days after its
+`verified` date unless it is re-verified. `[binding]` and `[disputed]` never
+expire by age. An entry whose cited source no longer exists is **never**
+auto-dropped: it may be the only copy, so it is reported as unarchived and kept.
+Only provisional entries whose source still resolves are eligible for the sweep.
+The arithmetic lives in `src/lib/map-schema.ts`; the cartographer writes the
+shape, code decides what has aged out.
 
 The map is **local and untracked**. It describes *your* checkout on *this*
 machine, so committing it would churn on every session that edits a file, and
@@ -193,25 +189,13 @@ your source.
 If you have defined a command of the same name, yours wins and is left exactly
 as you wrote it — the same merge-without-clobber rule the agents follow.
 
-`active.md` is the file the plugin maintains as a backlog rather than as a
-navigation map. The cartographer records what happened — work in flight, and a
-task marked finished with the date it finished — and the plugin decides what is
-still worth keeping: the file is regrouped by week and a task that was finished
-more than a week ago is dropped. The arithmetic lives in
-`src/lib/active-backlog.ts`, not in the cartographer's prompt, because a rule a
-model applies is a rule the model applies when it feels like it, and the failure
-is silent — the backlog just grows. The plugin normalizes the file on every edit
-of it and once when the session starts, so a hand edit is grouped and pruned
-whether the cartographer ran or not, and the file is rewritten only when its
-canonical form differs from what is on disk, so the write cannot loop.
-
 The same code owns the navigation files' lifecycle, but it may only **drop** an
 entry that is `[provisional]`, past its 30-day window, and whose cited source
 still exists. It never drops a binding constraint or disputed entry, and it
 never drops an entry with no source — that is the one case where the map may be
 the only copy. The plugin is not a second writer of the map in the permission
 sense: `context` is still the only **agent** that writes it. The lifecycle is
-housekeeping by code, the same category as the backlog window.
+housekeeping by code, applied after a run and then audited.
 
 ## One writer
 
@@ -301,7 +285,7 @@ to check is that permission rule, not the map's content.
 - The prompt the model actually runs, in one place: `src/lib/cartographer-prompt.ts`; the tracked copy is `.opencode/prompts/context.txt`, and a test pins equality.
 - The idle/edit trigger and the post-run audit wiring: `src/plugins/context-autoupdate.ts`.
 - The schema, budget, lifecycle and deterministic drift check: `src/lib/map-schema.ts`.
-- The active backlog's window: `src/lib/active-backlog.ts`.
+
 - The one-writer rule check: `src/lib/writer-rule.ts`.
 - Fixtures and their report: `tests/fixtures/context-map/`, `scripts/context-map-fixture.mjs`.
 - The behavioural contracts, with acceptance criteria a test asserts:

package/docs/USER-STORIES.md

@@ -471,6 +471,29 @@ Enforcement is split deliberately, and the split matters: **what the permission
 - [ ] Given the user's config already defines one of the three commands, When the config hook runs, Then that command is left byte-identical while the other two are still added.
 - [ ] Given the commands are injected, When each one's target agent is resolved against the same config object, Then all three resolve to an agent that actually exists there — a command must never point at a missing agent.
 
+### US-35: A timeline survives a restart and resumes unfinished work
+**As a** user whose opencode process restarts in the middle of a session, **I want** the timeline to remember what it has already summarized and to finish the slice it had not written yet, **so that** a crash or restart never silently loses part of the session's work record.
+
+The cursor and retry state used to live only in memory; a process that stopped between messages and the next idle flush forgot that a slice was pending, and a successful summary that produced no bullet text advanced the cursor only in memory, so a restart could summarize the same slice again. The plugin now writes a small per-session state file next to the JSONL timeline (cursor, pending flag, failure count, next retry time); startup resumes pending work, and a deleted session removes both files.
+
+**Story ID(s) for tests:** US-35
+**Acceptance criteria:**
+- [ ] Given a session has a pending timeline slice recorded on disk, When the process restarts, Then the timeline resumes and completes that slice without waiting for a new message event.
+- [ ] Given a summarization succeeds but produces no bullet text, When the process restarts, Then the advanced cursor is still known and the same transcript slice is not summarized again.
+- [ ] Given a session is deleted, When its timeline is removed, Then its durable state file is removed with it.
+
+### US-36: A failed timeline summary retries with backoff
+**As a** user whose summarizer call fails transiently, **I want** the timeline to retry on its own with an increasing delay, **so that** a temporary model or network failure does not leave the timeline permanently behind the session.
+
+A failed summarization used to clear the pending flag and never reschedule, so only new session activity could try again. A failure now marks the slice pending, records the next attempt time, and schedules a retry; repeated failures back off exponentially up to a cap, and an idle event during the wait re-arms the timer instead of bypassing it. A successful retry clears the failure count.
+
+**Story ID(s) for tests:** US-36
+**Acceptance criteria:**
+- [ ] Given a summarization fails transiently, When the retry interval elapses, Then the timeline retries without waiting for new session activity.
+- [ ] Given repeated failures, When retries are scheduled, Then the wait grows with each failure up to a configured cap.
+- [ ] Given a retry is waiting, When the session goes idle before the backoff window elapses, Then the idle event does not bypass the wait.
+- [ ] Given a retry succeeds, When entries are appended, Then the failure count resets to zero and the timeline is no longer pending.
+
 ---
 
 ## Epic H — Retention (sweeps)
@@ -554,6 +577,8 @@ table was filled in.
 | US-20 | G | `tests/stories/g-context-management.test.mjs` |
 | US-21 | G | `tests/stories/g-context-management.test.mjs`, `tests/permission-test.mjs` |
 | US-22 | G | `tests/stories/g-context-management.test.mjs` |
+| US-35 | G | `tests/stories/j-timeline-reliability.test.mjs` |
+| US-36 | G | `tests/stories/j-timeline-reliability.test.mjs` |
 | US-32 | H | `tests/retire-old-sessions-test.mjs` |
 | US-33 | H | `tests/prune-old-events-test.mjs` |
 
@@ -561,8 +586,8 @@ The nine suites under `tests/` are unit-style; the `tests/stories/` suites are
 the behavioural layer, written one epic per file with every test name carrying
 its story id. Run everything with `npm test`.
 
-**No story is uncovered.** The guard reports 33 stories, 325 test cases, and
-33/33 stories with at least one behavioural test; US-1, US-2, US-3, US-6, and
+**No story is uncovered.** The guard reports 36 stories, 348 test cases, and
+36/36 stories with at least one behavioural test; US-1, US-2, US-3, US-6, and
 all of epic F have tests, and the coverage guard fails the build if any of them
 loses one. The scan covers the `tests/stories/` suites and the root-level
 `tests/*-test.mjs` suites.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lawaty/lacode",
-  "version": "1.3.0-beta.9",
+  "version": "2.0.0-beta.0",
   "description": "Ultimate opencode setup for Go users — cost-controlled pooled subagents, hang recovery, and notifications for opencode.",
   "license": "MIT",
   "type": "module",
@@ -50,7 +50,8 @@
     "CHANGELOG.md",
     "README.md",
     "docs",
-    "scripts/score-models.mjs"
+    "scripts/score-models.mjs",
+    "scripts/refresh-pool.mjs"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
@@ -58,7 +59,8 @@
     "postpublish": "node scripts/sync-hosts.mjs && ./bin/oc-sync",
     "test": "node --test tests/",
     "benchmark": "node tests/benchmark/run.mjs",
-    "score": "node scripts/score-models.mjs"
+    "score": "node scripts/score-models.mjs",
+    "refresh-pool": "node scripts/refresh-pool.mjs"
   },
   "devDependencies": {
     "esbuild": "^0.28.2"

package/scripts/refresh-pool.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// Daily-refreshable pool builder.
+//
+// Reads the scorer's output (~/.config/lacode/model-scores.json) and proposes a
+// rewritten ~/.config/lacode/pool.txt. It never partially writes and never
+// writes on a fail-closed condition.
+//
+// Layout (exact, per spec):
+//   1. every free opencode-go model with ok:true and a numeric score, one slot
+//      each, sorted by score descending, weight 4
+//   2. every slot from the current pool whose provider is NOT present in the
+//      score file, preserved exactly (raw line text, weight/bucket/notify, order)
+//   3. exactly one free opencode model — the best ok:true numeric score —
+//      weight 2, with b:opencode
+//
+// Total = #opencode-go free + #preserved unscored + 1.
+//
+// This file ships as source and must run with plain `node` (ESM, no TS).
+
+import { mkdirSync, renameSync, writeFileSync, readFileSync, existsSync } from "node:fs"
+import { execFileSync } from "node:child_process"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const HOME = homedir()
+export const DEFAULT_SCORES_PATH = join(HOME, ".config", "lacode", "model-scores.json")
+export const DEFAULT_POOL_PATH = join(HOME, ".config", "lacode", "pool.txt")
+export const SYSTEMD_USER_DIR = (home = HOME) => join(home, ".config", "systemd", "user")
+export const REFRESH_SERVICE_NAME = "lacode-refresh-pool.service"
+export const REFRESH_TIMER_NAME = "lacode-refresh-pool.timer"
+
+const isSlotLine = (line) => {
+  const stripped = String(line).split("#")[0].trim()
+  return stripped.length > 0 && stripped.includes("/")
+}
+
+const providerOf = (modelOrLine) => {
+  const stripped = String(modelOrLine).split("#")[0].trim()
+  const token = stripped.split(/\s+/)[0] || ""
+  const slash = token.indexOf("/")
+  return slash < 0 ? token : token.slice(0, slash)
+}
+
+const isFree = (modelId) => {
+  const id = String(modelId || "")
+  return id.endsWith(":free") || id.endsWith("-free")
+}
+
+const numericScore = (row) => typeof row?.score === "number" && Number.isFinite(row.score)
+
+const okFreeRows = (providerEntry) => {
+  const rows = Array.isArray(providerEntry?.rows) ? providerEntry.rows : []
+  return rows.filter((row) => row?.ok === true && numericScore(row) && isFree(row.model))
+}
+
+function splitHeaderAndSlots(text) {
+  const lines = String(text ?? "").split(/\r?\n/)
+  // Drop a single trailing empty element produced by a final newline so we can
+  // reason about the file's logical lines; we re-add a final newline on output.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop()
+  let first = -1
+  for (let i = 0; i < lines.length; i++) {
+    if (isSlotLine(lines[i])) { first = i; break }
+  }
+  if (first === -1) return { header: lines, slots: [] }
+  return { header: lines.slice(0, first), slots: lines.slice(first) }
+}
+
+function refreshComment(now, scoresGeneratedAt) {
+  const when = now instanceof Date ? now.toISOString() : String(now)
+  const gen = scoresGeneratedAt ? ` (scores generated ${scoresGeneratedAt})` : ""
+  return `# Refreshed ${when} from model-scores.json${gen}: opencode-go free models first, best opencode last.`
+}
+
+function withRefreshComment(headerLines, comment) {
+  const kept = headerLines.filter((line) => !/^#\s*Refreshed\b/.test(String(line)))
+  return [...kept, comment]
+}
+
+function formatGeneratedLine(model, weight, bucket) {
+  const parts = [String(model), String(weight)]
+  if (bucket) parts.push(`b:${bucket}`)
+  return parts.join("  ")
+}
+
+/**
+ * Pure builder. Throws on every fail-closed condition; never touches the filesystem.
+ *
+ * @param {{ scores: any, currentPoolText: string, now?: Date|string }} input
+ * @returns {{ text: string, slots: string[], warnings: string[], chosen: { opencodeGo: string[], opencode: string, preserved: string[] } }}
+ */
+export function buildPool(input) {
+  const warnings = []
+  const scores = input?.scores
+  if (!scores || typeof scores !== "object" || !Array.isArray(scores.providers)) {
+    throw new Error("score file is missing or invalid (expected { providers: [...] })")
+  }
+
+  const providerEntries = scores.providers
+  const scoredProviders = new Set(
+    providerEntries.map((p) => String(p?.provider ?? "").trim()).filter(Boolean),
+  )
+
+  const goEntry = providerEntries.find((p) => p?.provider === "opencode-go")
+  const goRows = okFreeRows(goEntry).sort((a, b) => b.score - a.score)
+  if (goRows.length === 0) {
+    throw new Error("no free opencode-go model with ok:true and a numeric score is available; refusing to write pool.txt")
+  }
+
+  const opEntry = providerEntries.find((p) => p?.provider === "opencode")
+  const opRows = okFreeRows(opEntry).sort((a, b) => b.score - a.score)
+  if (opRows.length === 0) {
+    throw new Error("no free opencode model with ok:true and a numeric score is available; refusing to write pool.txt")
+  }
+  const bestOp = opRows[0].model
+
+  const { header, slots: currentSlots } = splitHeaderAndSlots(input?.currentPoolText ?? "")
+  const preserved = currentSlots.filter((line) => {
+    if (!isSlotLine(line)) return false
+    return !scoredProviders.has(providerOf(line))
+  })
+
+  const block1 = goRows.map((row) => formatGeneratedLine(row.model, 4))
+  const block3 = [formatGeneratedLine(bestOp, 2, "opencode")]
+  const outSlots = [...block1, ...preserved, ...block3]
+
+  const comment = refreshComment(input?.now ?? new Date(), scores.generatedAt)
+  const outHeader = withRefreshComment(header, comment)
+
+  const text = [...outHeader, "", ...outSlots, ""].join("\n")
+  return {
+    text,
+    slots: outSlots,
+    warnings,
+    chosen: {
+      opencodeGo: goRows.map((r) => r.model),
+      opencode: bestOp,
+      preserved: preserved.map((l) => String(l).split("#")[0].trim().split(/\s+/)[0]),
+    },
+  }
+}
+
+function readJsonFile(path) {
+  if (!existsSync(path)) throw new Error(`file not found: ${path}`)
+  const raw = readFileSync(path, "utf8")
+  try {
+    return JSON.parse(raw)
+  } catch (error) {
+    throw new Error(`invalid JSON in ${path}: ${String(error?.message ?? error)}`)
+  }
+}
+
+function readTextFile(path) {
+  if (!existsSync(path)) return ""
+  return readFileSync(path, "utf8")
+}
+
+function atomicWriteSimple(path, text) {
+  const dir = dirname(path)
+  const tmp = join(dir, `.pool.txt.tmp-${process.pid}-${Date.now()}`)
+  writeFileSync(tmp, text, "utf8")
+  renameSync(tmp, path)
+}
+
+function runScorer(max) {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const scorer = resolve(here, "score-models.mjs")
+  if (!existsSync(scorer)) throw new Error(`scorer not found: ${scorer}`)
+  const args = [scorer, "--max", String(max)]
+  execFileSync(process.execPath, args, { stdio: "inherit" })
+}
+
+export function renderTimerUnits(input = {}) {
+  const nodePath = input.nodePath || process.execPath
+  const scriptPath = input.scriptPath || fileURLToPath(import.meta.url)
+  const home = input.home || HOME
+  const servicePath = join(SYSTEMD_USER_DIR(home), REFRESH_SERVICE_NAME)
+  const timerPath = join(SYSTEMD_USER_DIR(home), REFRESH_TIMER_NAME)
+  const service = `[Unit]
+Description=Refresh the LaCode model pool from free-model scores
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=${nodePath} ${scriptPath}
+Environment=PATH=${home}/.opencode/bin:/usr/local/bin:/usr/bin:/bin
+Nice=10
+`
+  const timer = `[Unit]
+Description=Daily LaCode model pool refresh
+
+[Timer]
+OnCalendar=daily
+RandomizedDelaySec=2h
+Persistent=true
+Unit=${REFRESH_SERVICE_NAME}
+
+[Install]
+WantedBy=timers.target
+`
+  return { service, timer, servicePath, timerPath }
+}
+
+function installTimerUnits() {
+  const units = renderTimerUnits({
+    nodePath: process.execPath,
+    scriptPath: fileURLToPath(import.meta.url),
+    home: HOME,
+  })
+  mkdirSync(dirname(units.servicePath), { recursive: true })
+  writeFileSync(units.servicePath, units.service, "utf8")
+  writeFileSync(units.timerPath, units.timer, "utf8")
+  try {
+    execFileSync("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" })
+    execFileSync("systemctl", ["--user", "enable", "--now", REFRESH_TIMER_NAME], { stdio: "inherit" })
+  } catch (error) {
+    console.error(`failed to install systemd user timer: ${String(error?.message ?? error)}`)
+    console.error(`unit files written:`)
+    console.error(`  ${units.servicePath}`)
+    console.error(`  ${units.timerPath}`)
+    console.error(`manual commands:`)
+    console.error(`  systemctl --user daemon-reload`)
+    console.error(`  systemctl --user enable --now ${REFRESH_TIMER_NAME}`)
+    process.exitCode = 1
+    return false
+  }
+  console.log(`installed ${units.servicePath}`)
+  console.log(`installed ${units.timerPath}`)
+  console.log(`enabled ${REFRESH_TIMER_NAME}`)
+  return true
+}
+
+function usage() {
+  console.log(`Usage: node scripts/refresh-pool.mjs [options]
+
+  --from-scores     skip scoring, use the existing ~/.config/lacode/model-scores.json
+  --install-timer   install and enable a user systemd oneshot service + daily timer
+  --print           print the proposed pool.txt and make no changes (alias: --dry-run)
+  --dry-run         same as --print
+  --max N           models per provider passed to the scorer (default: 20)
+  --scores PATH     scores file (default: ${DEFAULT_SCORES_PATH})
+  --pool PATH       pool file to read/compare/write (default: ${DEFAULT_POOL_PATH})
+  -h, --help        this message`)
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  if (argv.includes("--help") || argv.includes("-h")) { usage(); return }
+  if (argv.includes("--install-timer")) {
+    installTimerUnits()
+    return
+  }
+  const fromScores = argv.includes("--from-scores")
+  const printOnly = argv.includes("--print") || argv.includes("--dry-run")
+  const value = (flag, fallback) => {
+    const hit = argv.find((a) => a === flag || a.startsWith(`${flag}=`))
+    if (!hit) return fallback
+    return hit.includes("=") ? hit.slice(hit.indexOf("=") + 1) : argv[argv.indexOf(hit) + 1]
+  }
+  const max = Math.max(1, Number(value("--max", "20")) || 20)
+  const scoresPath = value("--scores", DEFAULT_SCORES_PATH)
+  const poolPath = value("--pool", DEFAULT_POOL_PATH)
+
+  if (!fromScores) {
+    try {
+      runScorer(max)
+    } catch (error) {
+      console.error(`scorer failed; pool.txt not written: ${String(error?.message ?? error)}`)
+      process.exitCode = 1
+      return
+    }
+  }
+
+  let scores
+  try {
+    scores = readJsonFile(scoresPath)
+  } catch (error) {
+    console.error(String(error?.message ?? error))
+    process.exitCode = 1
+    return
+  }
+
+  const currentPoolText = readTextFile(poolPath)
+  let built
+  try {
+    built = buildPool({ scores, currentPoolText, now: new Date() })
+  } catch (error) {
+    console.error(`refresh refused (fail closed): ${String(error?.message ?? error)}`)
+    process.exitCode = 1
+    return
+  }
+
+  const oldSlotCount = splitHeaderAndSlots(currentPoolText).slots.filter(isSlotLine).length
+  const newSlotCount = built.slots.filter(isSlotLine).length
+  const summary = [
+    `opencode-go [${built.chosen.opencodeGo.join(", ")}]`,
+    `preserved-unscored [${built.chosen.preserved.join(", ")}]`,
+    `opencode-last [${built.chosen.opencode}]`,
+  ].join(" | ")
+
+  if (printOnly) {
+    process.stdout.write(built.text)
+    console.error(`--print: proposed ${oldSlotCount} -> ${newSlotCount} slots; no changes written. ${summary}`)
+    return
+  }
+
+  if (existsSync(poolPath)) {
+    try {
+      const existing = readFileSync(poolPath, "utf8")
+      if (existing === built.text) {
+        console.log(`unchanged: ${poolPath} (${newSlotCount} slots). ${summary}`)
+        return
+      }
+    } catch {}
+  }
+
+  try {
+    atomicWriteSimple(poolPath, built.text)
+  } catch (error) {
+    console.error(`failed to write ${poolPath}: ${String(error?.message ?? error)}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(`wrote ${poolPath}: ${oldSlotCount} -> ${newSlotCount} slots. ${summary}`)
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+if (isMain) {
+  main().catch((error) => {
+    console.error(String(error?.stack ?? error?.message ?? error))
+    process.exitCode = 1
+  })
+}