Arcology Engine

The Arcology Journal Agent Router

Contents
this is agentslop, need to review and overhaul it myself.

I have a mobile app that suffices as a decent journaling app, and I have a homelab with a little Framework Desktop that can run Qwen Flash Next against all my notes without feeding them to remote inference. This Arcology module binds my journal notes to a set of analysis agents to help me organize my notes. Each agent maintains their own journal, inbox, task list and memory as org-mode files under ~/org/agents.

  • dev-planner: take feature requests and bug reports and research the codebase to present a development plan

  • literate-coder: take a development plan and fire it off in opencode, ensuring literate development standards are maintained

  • personal-coach: act on personal notes guiding me in ways i want to go in life

  • organizer: slowly mold my mishmash of notes in to coherent web of thought

etc...

System Overview

  • The Producer watches Syncthing for changes and produces a "spool" of Heading events

  • The Drain uses a SystemOne decision model to route each Heading to a particular agent prompt in to a per-agent spool

  • The Dispatcher will run every five minutes against each agent spool to route them in to Hermes agent sessions to act on the heading

  • Nix Home Manager deploys all this stuff

Hard invariants

  • No :ID: properties are ever minted into user files. The producer and the other tools are strictly read-only over the org tree. Identity is derived: the heading's existing :ID: when it has one, else the pair (file, outline-path).

  • harness state lives under ~/.cache/arcology2/harness: snapshots under ~/.cache/arcology2/harness/snapshots/, the spool at ~/.cache/arcology2/harness/spool/YYYY-MM.ndjson, verdict cursors as one-integer files ~/.cache/arcology2/harness/cursors/AGENT.verdict, verdicts at ~/.cache/arcology2/harness/verdicts/YYYY-MM-DD.ndjson, wake dispatch cursors as one-integer files cursors/AGENT.dispatch, wake briefing and audit files at wakes/<agent>-<seq>.md and wakes/YYYY-MM-DD.ndjson, plus the producer's seq mirror and the shared LLM verdict cache as plain files, and cross-process advisory locks and agent wake leases under <state>/locks/. - Agent state, memory, tasks, etc, are stored in ~/org/agents. - The db is the reading view; the spool is the acting log. Zero reads or writes of any arcology.db in producer/enumeration paths, and there is no date-window semantics anywhere in the correctness path: diffs are file-scoped against snapshot state. - GPU discipline: exactly one classifier call in flight against the one resident small model. Every client here issues requests sequentially; no drain fan-out — drain down, not out. - Fail closed: if the classifier endpoint is unreachable, no verdict is written, the cursor does not advance, and the lag becomes visible in harness status. Nothing in this module weakens that default. - Only dispatch wakes, and it wakes deterministically.* harness dispatch is the module's single waking surface: it spawns at most one hermes session per fsynced yes verdict line, per-agent-capped, window- and lease-gated, and issues zero LLM calls of its own (*The wake dispatcher (P2)). Time-based hermes cron jobs are untouched by this module.

Producer

The Producer monitors my org directory using Syncthing. When a file is changed, it writes metadata to a JSON-ish file that the Dispatcher uses to route the note to different sub-agents.

The producer

kotlin#+name: harness-producer-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.indexer.SYNCTHING_LOCAL_CHANGE
import computer.whatthefuck.arcology.indexer.SYNCTHING_REMOTE_CHANGE
import computer.whatthefuck.arcology.indexer.IgnorePatterns
import computer.whatthefuck.arcology.indexer.SyncthingAuthException
import computer.whatthefuck.arcology.indexer.SyncthingClient
import computer.whatthefuck.arcology.indexer.SyncthingEvent
import computer.whatthefuck.arcology.indexer.SyncthingFolder
import computer.whatthefuck.arcology.indexer.isIndexableOrgItem
import computer.whatthefuck.arcology.indexer.isSyncConflictItem
import computer.whatthefuck.arcology.indexer.resolveSyncthingFolder
import computer.whatthefuck.arcology.indexer.resolveSyncthingItemPath
import computer.whatthefuck.arcology.llm.HeadingEnumerationException
import computer.whatthefuck.arcology.llm.HeadingRecord
import computer.whatthefuck.arcology.llm.enumerateHeadings
import computer.whatthefuck.arcology.llm.headingRevision
import kotlinx.coroutines.delay
import java.io.File
import java.time.OffsetDateTime
import java.time.format.DateTimeFormatter
kotlin#+name: harness-producer-diff
/** scope bucket from the tree layout: first segment, de-pluralized. */
internal fun scopeFor(file: String): String {
    val first = file.substringBefore('/', "")
    return when {
        first.isEmpty() -> "root"
        first.length > 1 && first.endsWith("s") -> first.dropLast(1)
        else -> first
    }
}

/** The text a classifier sees for one spooled event. */
internal fun classificationText(title: String?, todo: String?, body: String): String =
    ((todo?.let { "$it " } ?: "") + (title ?: "")) + (if (body.isBlank()) "" else "\n\n$body")

/** Default spool-body cap: the same ceiling =notes get= applies. */
const val DEFAULT_SPOOL_BODY_BYTES = 20_480

/**
 * Byte-exact body cap for spool lines. Cuts on a UTF-8 boundary and
 * appends an explicit marker; the marker is line-render noise — the
 * event's revision hash and risk stamp are always computed from the FULL
 * text, and the org tree itself stays the full-text archive (P2 dispatch
 * re-reads by (file, outline-path) when it needs everything).
 */
internal fun truncateBodyBytes(body: String, maxBytes: Int): String {
    if (body.toByteArray(Charsets.UTF_8).size <= maxBytes) return body
    var take = body.length
    while (take > 0 &&
        body.substring(0, take).toByteArray(Charsets.UTF_8).size > maxBytes
    ) take--
    return body.substring(0, take) + "\n\n[truncated at $maxBytes bytes]"
}

/** Deterministic per-file draft diff: constructed in match order, so the
 * refile pair (deleted, then added) stays adjacent. */
internal data class DiffDraft(
    val action: String,
    val outline: String,
    /** Current heading record for added/revised. */
    val record: HeadingRecord?,
    /** Old snapshot entry for deleted. */
    val old: SnapshotEntry?,
)

/**
 * Pure hash-diff between the old snapshot state and the freshly
 * enumerated records of one file. ID-bearing headings match by org_id
 * (position-independent, the refile pairing); ID-less headings match by
 * outline-path only. Duplicate org ids pair deterministically in outline
 * order.
 */
internal fun diffHeadings(
    relative: String,
    old: Map<String, SnapshotEntry>,
    records: List<HeadingRecord>,
): List<DiffDraft> {
    val drafts = mutableListOf<DiffDraft>()
    val claimedOld = mutableSetOf<String>()
    val revisionOf = records.associateBy({ it.outline }, { headingRevision(it) })

    // pass 1 — org-id matching, position-independent
    val oldById = old.entries
        .filter { it.value.orgId != null }
        .groupBy({ it.value.orgId!! }) { it.key }
    val newById = records.filter { it.orgId != null }.groupBy { it.orgId!! }
    for (id in (oldById.keys + newById.keys).toSortedSet()) {
        val oldKeys = oldById[id]?.sorted() ?: emptyList()
        val newRecs = newById[id]?.sortedBy { it.outline } ?: emptyList()
        val pairs = maxOf(oldKeys.size, newRecs.size)
        for (i in 0 until pairs) {
            val oldKey = oldKeys.getOrNull(i)
            val newRec = newRecs.getOrNull(i)
            if (oldKey == null) {
                // pair came from the new side: brand new org id
                if (newRec != null) {
                    drafts.add(DiffDraft("added", newRec.outline, newRec, null))
                }
            } else if (newRec == null) {
                // id vanished: old outline's heading is gone
                claimedOld.add(oldKey)
                drafts.add(DiffDraft("deleted", oldKey, null, old[oldKey]!!))
            } else if (oldKey == newRec.outline) {
                claimedOld.add(oldKey)
                if (old[oldKey]!!.hash != revisionOf[newRec.outline]) {
                    drafts.add(DiffDraft("revised", oldKey, newRec, null))
                }
            } else {
                // refile: derived identity moved, treat as two events
                claimedOld.add(oldKey)
                drafts.add(DiffDraft("deleted", oldKey, null, old[oldKey]!!))
                drafts.add(DiffDraft("added", newRec.outline, newRec, null))
            }
        }
    }

    // pass 2 — ID-less outline matching
    for (rec in records.filter { it.orgId == null }.sortedBy { it.outline }) {
        val oldEntry = old[rec.outline]
        when {
            oldEntry != null && rec.outline in claimedOld ->
                // The old entry at this outline belonged to an ID'd
                // heading; this ID-less newcomer is a fresh addition.
                drafts.add(DiffDraft("added", rec.outline, rec, null))
            oldEntry == null ->
                drafts.add(DiffDraft("added", rec.outline, rec, null))
            oldEntry.hash != revisionOf[rec.outline] ->
                drafts.add(DiffDraft("revised", rec.outline, rec, null))
            else -> { } // unchanged
        }
    }

    // Old ID-less entries whose (file, outline) identity no longer holds
    // an ID-less occupant: deleted. (A departing ID'd heading's event was
    // already emitted by pass 1; a slot turnover to an ID'd newcomer
    // produces its added event in pass 1 too.)
    for ((outline, entry) in old.entries.sortedBy { it.key }) {
        if (entry.orgId != null) continue
        if (records.any { it.outline == outline && it.orgId == null }) continue
        drafts.add(DiffDraft("deleted", outline, null, entry))
    }
    return drafts
}
kotlin#+name: harness-producer-core
/** Bootstrap behavior for a full produce walk (see [[*Bootstrap & replay
 * policy]]). [AUTO] baselines when the snapshot store is empty (the
 * default); [BASELINE] forces a re-seed even on an established store;
 * [FULL_EMIT] is the legacy cold start that emits every heading. */
enum class BootstrapMode { AUTO, BASELINE, FULL_EMIT }

/**
 * The produce half of the harness: enumerate → hash-diff → snapshot
 * (write-ahead) → append. State lives under [stateRoot]; org files are
 * read from [orgDir] and never written. =.arcologyignore= scopes
 * (indexer semantics) filter the tracked corpus on walks and resolve
 * live on the event path ([isIgnoredNow]); the vanished sweep always
 * runs on unfiltered discovery, so ignore scope suppresses only noise
 * about files that exist — never the record of one leaving the store.
 */
class HarnessProducer(
    private val stateRoot: File,
    private val orgDir: File,
    private val stamper: ProducerRiskClassifier,
    private val now: () -> OffsetDateTime = { OffsetDateTime.now() },
    private val log: (String) -> Unit = { println(it) },
    /** Depth roll-up for the enumeration: records only at level ≤
     * [maxDepth], deeper headings folded into their kept ancestor's body.
     * Default unlimited. Not snapshot state: changing it re-diffs
     * honestly (deep records vanish as deletions, ancestors revise). */
    private val maxDepth: Int = Int.MAX_VALUE,
    /** Spool-body byte cap: line-render truncation only — revision hashes
     * and risk stamps are computed from the FULL heading text above. */
    private val maxBodyBytes: Int = DEFAULT_SPOOL_BODY_BYTES,
) {
    private val spool = SpoolWriter(stateRoot)
    private val snapshots = SnapshotStore(stateRoot)

    fun snapshotCount(): Int = snapshots.count()

    /** Live ignore scopes for the event path: dir → =.arcologyignore=
     * content, keyed by the dir's tree-relative path (empty string for
     * the root). Single produce loop, single reader — no locking. */
    private var ignoreScopes: Map<String, String> = emptyMap()

    /** Dirs the event path probed between walks (absent from the walk's
     * own scope set); disk state cached for the process lifetime and
     * invalidated by an ignore-file event. */
    private var eventScopeProbes: MutableMap<String, String?> = mutableMapOf()

    /** Swap in a walk's scope set: walk truth supersedes anything the
     * event path probed live, so the probes reset per walk. */
    private fun adoptIgnoreScopes(walk: ProducerWalk) {
        eventScopeProbes.clear()
        ignoreScopes = walk.ignoreFiles
    }

    /**
     * Resolve one event path's ignore state NOW — the walk-time filter's
     * twin: compose the scope chain over the path's ancestor dirs and
     * apply the same file+ancestor-entry test ([isIgnoredPath]). Steady
     * state costs no IO; a first-ever probe of an ancestor costs one
     * stat (plus one read when it holds an ignore file), cached for the
     * process lifetime. A scope edited without an arriving event for
     * the file itself stays stale until the next walk re-reads it.
     */
    internal fun isIgnoredNow(relative: String): Boolean {
        val dirs = buildList {
            add("")
            var dir = relative.substringBeforeLast('/', "")
            while (dir.isNotEmpty()) {
                add(dir)
                dir = dir.substringBeforeLast('/', "")
            }
        }
        var patterns = IgnorePatterns.EMPTY
        for (scopeDir in dirs) {
            val content = when {
                scopeDir in ignoreScopes -> ignoreScopes[scopeDir]
                scopeDir in eventScopeProbes -> eventScopeProbes[scopeDir]
                else -> {
                    val ignoreFile = if (scopeDir.isEmpty()) File(orgDir, IGNORE_FILE_NAME)
                    else File(File(orgDir, scopeDir), IGNORE_FILE_NAME)
                    val probed = ignoreFile.takeIf { it.isFile }
                        ?.let { runCatching { it.readText() }.getOrNull() }
                    eventScopeProbes[scopeDir] = probed
                    probed
                }
            }
            if (content != null) patterns = patterns.plus(scopeDir, content)
        }
        return isIgnoredPath(patterns, relative)
    }

    /**
     * An event for a =.arcologyignore= file itself: drop that scope from
     * both caches so the next resolution re-reads it from disk (an edit
     * updates it, a deletion reverts to the parent scope). The file is
     * never tracked, never spooled — this is scope invalidation only.
     */
    internal fun refreshIgnoreScopes(containingDir: String) {
        ignoreScopes = ignoreScopes - containingDir
        eventScopeProbes.remove(containingDir)
    }

    /**
     * Diff one file against its snapshot and spool the events.
     * [absolute]==null or missing from disk ⇒ every tracked heading
     * deletes (and the snapshot file is removed BEFORE the events land —
     * state-ahead, so a restart can never re-emit the deletion batch).
     * A parse failure (torn write mid-sync) leaves state untouched: the
     * next pass re-diffs.
     */
    suspend fun processFile(relative: String, absolute: File?, modifiedBy: String): Int {
        val old = snapshots.load(relative)
        if (absolute == null || !absolute.isFile) {
            if (old.isEmpty()) return 0
            val drafts = old.keys.sorted().map { outline ->
                DiffDraft("deleted", outline, null, old[outline]!!)
            }
            val events = buildEvents(relative, drafts, modifiedBy)
            snapshots.remove(relative)
            for (event in events) spool.append(event)
            log("spooled ${events.size} deletion(s) for vanished file: $relative")
            return events.size
        }
        val records = try {
            enumerateHeadings(relative, absolute.readText(), maxDepth)
        } catch (e: HeadingEnumerationException) {
            log("skipping unparseable file (torn write?): $relative — ${e.message}")
            return 0
        }
        val drafts = diffHeadings(relative, old, records)
        val entries = records.associate { rec ->
            rec.outline to SnapshotEntry(
                hash = headingRevision(rec),
                orgId = rec.orgId,
                title = rec.title,
            )
        }
        // Write-ahead: hash-diff dedupe on restart requires the snapshot
        // to reflect everything already spooled (see the design note).
        snapshots.save(relative, entries)
        if (drafts.isEmpty()) return 0
        // ISO_OFFSET_DATE_TIME keeps the seconds field stable even when
        // they are zero (Instant toString drops them).
        val ts = DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now())
        for (event in buildEvents(relative, drafts, modifiedBy, ts)) {
            spool.append(event)
        }
        val counts = drafts.groupingBy { it.action }.eachCount()
            .entries.sortedBy { it.key }
            .joinToString(", ") { "${it.value} ${it.key}" }
        log("file $relative: $counts")
        return drafts.size
    }

    private suspend fun buildEvents(
        relative: String,
        drafts: List<DiffDraft>,
        modifiedBy: String,
        ts: String? = null,
    ): List<SpoolEvent> {
        val stampTs = ts ?: DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now())
        val scope = scopeFor(relative)
        return drafts.map { draft ->
            val eventText = when (draft.action) {
                "deleted" -> EventText(
                    title = draft.old?.title ?: "",
                    todo = null,
                    body = "",
                    revision = draft.old?.hash ?: "",
                    orgId = draft.old?.orgId,
                )
                else -> EventText(
                    title = draft.record?.title ?: "",
                    todo = draft.record?.todo,
                    body = draft.record?.body ?: "",
                    revision = draft.record?.let { headingRevision(it) } ?: "",
                    orgId = draft.record?.orgId,
                )
            }
            // One risk stamp per event over the FULL classification text,
            // sequential: the spool's acting log is not a full-text archive.
            val eventRisk = stamper.stamp(
                classificationText(eventText.title, eventText.todo, eventText.body)
            )
            SpoolEvent(
                ts = stampTs,
                scope = scope,
                file = relative,
                identity = SpoolIdentity(
                    orgId = eventText.orgId,
                    key = "$relative::${draft.outline}",
                ),
                action = draft.action,
                title = eventText.title,
                todo = eventText.todo,
                // Line-render cap: the identity (revision) and the risk
                // stamp above were computed from the full text.
                body = truncateBodyBytes(eventText.body, maxBodyBytes),
                revision = eventText.revision,
                risk = eventRisk,
                modifiedBy = modifiedBy,
            )
        }
    }

    private data class EventText(
        val title: String,
        val todo: String?,
        val body: String,
        val revision: String,
        val orgId: String?,
    )

    /**
     * Full walk: every tracked .org file under [orgDir], sorted, plus the
     * vanished-snapshot sweep that detects deletions missed while down.
     * The tracked set respects =.arcologyignore= scopes (indexer
     * semantics); the sweep never does — it trusts the UNFILTERED disk
     * discovery, so a tracked file inside a now-ignored scope is
     * silently skipped (snapshot retained — the scope-change rule),
     * where a file that truly vanished still spools its deletions.
     * [mode] selects the bootstrap behavior: baseline seeds snapshots
     * with zero events and appends one audit marker (post-ignore
     * counts); FULL_EMIT is the legacy emit-everything cold start; AUTO
     * baselines only when the snapshot store is empty.
     */
    suspend fun fullWalk(modifiedBy: String, mode: BootstrapMode = BootstrapMode.AUTO): Int {
        val baselining = when (mode) {
            BootstrapMode.BASELINE -> true
            BootstrapMode.FULL_EMIT -> false
            BootstrapMode.AUTO -> snapshots.count() == 0
        }
        if (baselining) {
            seedBaseline(modifiedBy)
            return 0
        }
        val walk = listOrgFilesWithIgnores(orgDir)
        adoptIgnoreScopes(walk)
        var total = 0
        for ((relative, file) in walk.files) {
            total += processFile(relative, file, modifiedBy)
        }
        // The vanished sweep trusts ALLDISCOVERED (the unfiltered disk
        // truth): tracked-but-now-ignored files sit there, so no
        // deletion masquerades; a tracked file in neither list truly
        // vanished and keeps the write-ahead delete path below.
        val onDisk = walk.allDiscovered.map { it.first }.toSet()
        for (relative in snapshots.trackedFiles().sorted()) {
            if (relative !in onDisk) {
                total += processFile(relative, null, modifiedBy)
            }
        }
        log("full walk ($modifiedBy) done: $total event(s) spooled, seq=${spool.currentSeq()}")
        return total
    }

    /**
     * BASELINE: seed snapshots for every tracked file, emit zero
     * per-heading events, append one audit marker. Tracking respects
     * =.arcologyignore= scopes: the seed and the marker's file/heading
     * counts are post-ignore, and a tracked-but-ignored file's stale
     * snapshot is left in place (the scope-change rule — the sweep only
     * drops snapshots for files GONE from the unfiltered disk, already
     * handled history). No implicit re-baseline — callers reach this
     * only via [BootstrapMode.BASELINE] or the empty-store AUTO trigger.
     */
    private suspend fun seedBaseline(modifiedBy: String): Int {
        val walk = listOrgFilesWithIgnores(orgDir)
        adoptIgnoreScopes(walk)
        var headings = 0
        for ((relative, file) in walk.files) {
            val records = try {
                enumerateHeadings(relative, file.readText(), maxDepth)
            } catch (e: HeadingEnumerationException) {
                log("baseline: skipping unparseable file: $relative — ${e.message}")
                continue
            }
            snapshots.save(
                relative,
                records.associate { rec ->
                    rec.outline to SnapshotEntry(
                        hash = headingRevision(rec),
                        orgId = rec.orgId,
                        title = rec.title,
                    )
                }
            )
            headings += records.size
        }
        // A forced re-seed over an established store: snapshots for files
        // GONE from the unfiltered disk drop WITHOUT events — already
        // handled history. Present-but-ignored files keep their
        // snapshots: un-ignore resumes via hash-diff, --baseline is the
        // documented reset.
        val onDisk = walk.allDiscovered.map { it.first }.toSet()
        for (relative in snapshots.trackedFiles().sorted()) {
            if (relative !in onDisk) {
                snapshots.remove(relative)
                log("baseline: dropped vanished snapshot: $relative")
            }
        }
        val markerTs = DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now())
        val head = spool.currentSeq()
        spool.appendRaw(SpoolWriter.buildBaselineMarker(walk.files.size, headings, head, markerTs))
        log(
            "baseline seeded by $modifiedBy: ${walk.files.size}/${walk.allDiscovered.size} " +
                "file(s) tracked, $headings heading(s), head seq $head; zero events emitted"
        )
        return 0
    }
}

/** Name of the ignore file the producer honors, anchored at any dir. */
internal const val IGNORE_FILE_NAME = ".arcologyignore"

/**
 * One walk's three outputs: [files] is the tracked corpus (every .org
 * file, '/'-separated, ignore-filtered), [allDiscovered] the UNFILTERED
 * on-disk .org set the vanished sweep trusts, [ignoreFiles] the
 * =.arcologyignore= contents found keyed by their anchor dir.
 */
internal data class ProducerWalk(
    val files: List<Pair<String, File>>,
    val allDiscovered: List<Pair<String, File>>,
    val ignoreFiles: Map<String, String>,
)

/**
 * Indexer walk semantics without descent control: a file is ignored when
 * its own relative path matches a scope, OR when any ancestor
 * directory's relative path does — the in-memory equivalent of the
 * indexer's walk pruning at the directory entry. A root pattern whose
 * last segment is a star over one directory level (the "agents" case in
 * the tests) covers the deeper file via the ancestor directory's entry,
 * exactly like the indexer's "archive" dir-entry test does. Note for
 * future editors: Kotlin block comments nest, so comment prose must
 * never contain a slash-star sequence — spell star patterns in words.
 */
internal fun isIgnoredPath(patterns: IgnorePatterns, relative: String): Boolean {
    if (patterns.shouldIgnore(relative)) return true
    var dir = relative.substringBeforeLast('/', "")
    while (dir.isNotEmpty()) {
        if (patterns.shouldIgnore(dir)) return true
        dir = dir.substringBeforeLast('/', "")
    }
    return false
}

/**
 * Sorted recursive .org walk, now scope-aware: the root
 * =.arcologyignore= parses first (indexer semantics —
 * [[file:../roam/indexer.org][the indexer's IgnorePatterns]]) and every
 * nested one merges via plus(dir, content) as the walk descends. The
 * traversal itself stays UNPRUNED — the identical discovery surface of
 * the pre-ignore walker — so the vanished sweep's unfiltered truth
 * holds; the indexer-identical tracked list comes from [isIgnoredPath]
 * filtering. The =.arcologyignore= files themselves are never emitted
 * (they are not .org files). Unreadable ignore files fall back to the
 * inherited scope rather than aborting the walk (the indexer's rule).
 */
internal fun listOrgFilesWithIgnores(root: File): ProducerWalk {
    val files = mutableListOf<Pair<String, File>>()
    val discovered = mutableListOf<Pair<String, File>>()
    val ignoreFiles = mutableMapOf<String, String>()
    fun walk(dir: File, dirRelative: String, scope: IgnorePatterns) {
        val entries = dir.listFiles() ?: return
        val ignoreFile = File(dir, IGNORE_FILE_NAME)
        val childScope = if (ignoreFile.isFile) {
            val content = runCatching { ignoreFile.readText() }.getOrNull()
            if (content != null) {
                ignoreFiles[dirRelative] = content
                scope.plus(dirRelative, content)
            } else {
                scope
            }
        } else {
            scope
        }
        for (entry in entries.sortedBy { it.name }) {
            if (entry.isDirectory) {
                if (entry.name.startsWith(".")) continue
                walk(
                    entry,
                    entry.relativeTo(root).path.replace(File.separatorChar, '/'),
                    childScope,
                )
            } else if (entry.isFile && entry.name.lowercase().endsWith(".org")) {
                val relative = entry.relativeTo(root).path.replace(File.separatorChar, '/')
                discovered.add(relative to entry)
                if (!isIgnoredPath(childScope, relative)) {
                    files.add(relative to entry)
                }
            }
        }
    }
    walk(root, "", IgnorePatterns.EMPTY)
    return ProducerWalk(files, discovered, ignoreFiles)
}

/**
 * Sorted recursive .org walker with the dotfile/.stfolder exclusions the
 * indexer applies, UNFILTERED: every .org file under [root] as
 * tree-relative ('/'-separated) paths. The ignore-respecting view lives
 * in [listOrgFilesWithIgnores]; this keeps the legacy public surface.
 */
fun listOrgFiles(root: File): List<Pair<String, File>> =
    listOrgFilesWithIgnores(root).allDiscovered

The watch service mirrors SyncthingWatchService's shape — startup full walk, cursor seed from the same mask, delete-wins batch dedupe, heartbeat on quiet polls, hourly reconcile — but dispatches to HarnessProducer instead of the indexer, carrying each event's device name through as modified_by.

kotlin#+name: harness-produce-service
/** One file's deduped batch outcome: delete wins, last modifier kept. */
private class PendingFile(val modifiedBy: String) {
    var isDelete = false
}

class HarnessProduceService(
    private val client: SyncthingClient,
    private val producer: HarnessProducer,
    private val orgDir: String,
    private val folderId: String? = null,
    private val pollTimeoutSeconds: Int = 60,
    private val rescanIntervalSeconds: Long = 3600,
    private val initialBackoffMs: Long = 10_000,
    private val maxBackoffMs: Long = 300_000,
    private val log: (String) -> Unit = { println(it) },
    /** Bootstrap behavior for the startup walk; reconcile walks are
     * always AUTO (post-establishment, the store is non-empty). */
    private val bootstrapMode: BootstrapMode = BootstrapMode.AUTO,
) {
    private var cursor: Long = 0L
    fun currentCursor(): Long = cursor

    /** Resolve the folder, run the startup walk (bootstrap semantics),
     * seed the cursor. */
    suspend fun startup(): SyncthingFolder {
        val folder = resolveSyncthingFolder(client.folders(), orgDir, folderId)
        log("Watching Syncthing folder ${folder.id} (${folder.label ?: "unlabeled"}) at ${folder.path}")
        producer.fullWalk("startup", bootstrapMode)
        cursor = client.latestEventId() ?: 0L
        log("Watching for events after id $cursor")
        return folder
    }

    /**
     * Poll loop: one long-poll per iteration, transient failures back
     * off with the cursor intact, auth failures abort, empty polls log
     * a heartbeat every 15th, and ~[rescanIntervalSeconds] of silence
     * triggers a reconcile full walk (the stall breaker). No ID-gap
     * detection — the startup scan is the safety net.
     */
    suspend fun watch(maxIterations: Int = Int.MAX_VALUE) {
        val folder = startup()
        var backoff = initialBackoffMs
        var emptyPolls = 0L
        val rescanAfterPolls = if (rescanIntervalSeconds > 0) {
            (rescanIntervalSeconds / pollTimeoutSeconds.coerceAtLeast(1)).coerceAtLeast(1)
        } else {
            Long.MAX_VALUE
        }
        repeat(maxIterations) {
            val events = try {
                client.events(cursor, pollTimeoutSeconds)
            } catch (e: SyncthingAuthException) {
                throw SyncthingAuthException("Syncthing rejected the API key: ${e.message}", e)
            } catch (e: Exception) {
                log("Syncthing API unreachable (${e.message}); retrying in ${backoff / 1000}s")
                delay(backoff)
                backoff = (backoff * 2).coerceAtMost(maxBackoffMs)
                return@repeat
            }
            backoff = initialBackoffMs
            if (events.isEmpty()) {
                emptyPolls++
                if (emptyPolls % 15L == 0L) {
                    log("No disk events for $emptyPolls polls; cursor=$cursor; continuing")
                }
                if (emptyPolls >= rescanAfterPolls) {
                    emptyPolls = 0
                    log("Idle for ~$rescanIntervalSeconds s; running reconciliation produce pass")
                    try {
                        producer.fullWalk("reconcile")
                    } catch (e: Exception) {
                        log("Reconciliation produce pass failed: ${e.message}")
                    }
                }
                return@repeat
            }
            emptyPolls = 0
            log("Got ${events.size} disk event(s) for folder ${folder.id}")
            processBatch(events, folder)
            cursor = events.last().id
        }
    }

    /**
     * Batch of disk events → per-file dispatch, deduped per path with
     * delete-wins semantics, .org files only, directories skipped, item
     * paths relativized against the folder root (the double-keyspace
     * regression's guard), last modifier carried through. An event for
     * a =.arcologyignore= file never tracks or spools — it only
     * refreshes the producer's scope cache so the rest of the batch
     * resolves against current scopes; an event inside an ignored scope
     * produces nothing (no add/change/delete, no snapshot writes). A
     * single dispatch error never kills the poll loop.
     */
    suspend fun processBatch(events: List<SyncthingEvent>, folder: SyncthingFolder) {
        val actions = LinkedHashMap<String, PendingFile>()
        for (event in events) {
            if (event.type != SYNCTHING_LOCAL_CHANGE && event.type != SYNCTHING_REMOTE_CHANGE) continue
            val data = event.data ?: continue
            val path = data.path ?: continue
            if (folder.id.isNotBlank() && data.folder != null && data.folder != folder.id) continue
            if (data.itemType != null && data.itemType != "file") continue
            val pending = actions.getOrPut(path) { PendingFile(data.modifiedBy ?: "local") }
            if (data.action == "deleted") {
                pending.isDelete = true
            }
        }
        for ((item, pending) in actions) {
            if (item.substringAfterLast('/').lowercase() == IGNORE_FILE_NAME) {
                // Scope invalidation only: the ignore file itself is
                // never an event-stream subject.
                producer.refreshIgnoreScopes(resolveSyncthingItemPath(item, folder.path))
                continue
            }
            if (!isIndexableOrgItem(item)) continue
            if (isSyncConflictItem(item)) {
                log("Conflict file detected, producing as-is (resolve it manually): $item")
            }
            val resolved = resolveSyncthingItemPath(item, folder.path)
            if (resolved.isEmpty()) {
                log("Skipping event outside folder root: $item")
                continue
            }
            if (producer.isIgnoredNow(resolved)) {
                // Ignored scope: no add/change/delete, no snapshot writes
                // (the scope-change rule — never masquerade a deletion).
                continue
            }
            try {
                producer.processFile(
                    resolved,
                    if (pending.isDelete) null else File(orgDir, resolved),
                    pending.modifiedBy
                )
            } catch (e: Exception) {
                log("Produce dispatch error for $resolved: ${e.message}")
            }
        }
    }
}
kotlin#+name: harness-producer-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessProducer.kt:noweb yes
<<harness-producer-imports>>

<<harness-producer-diff>>

<<harness-producer-core>>

<<harness-produce-service>>

Diff Semantics

Diff semantics per touched file (old snapshot state vs enumerateHeadings on the current content):

  • ID-bearing headings match by org_id first, position-independent: same id, same outline, changed hash ⇒ revised; same id, moved ⇒ refile (deleted at the old key + added at the new key); new id ⇒ added; id gone ⇒ deleted.

  • ID-less headings match by outline-path: identical hash ⇒ unchanged; changed ⇒ revised; new path ⇒ added; gone ⇒ deleted. An ID-less heading that shifted only because a sibling was inserted re-reports as the honest consequence of derived identity: give moved-about headings =:ID:=s if you want position-stable identity (org-mode's own advice).

  • Duplicate ids inside one file pair deterministically in outline order (a user error, not a crash).

  • Deleted events carry the old entry's title and revision; bodies are empty (the text left the tree).

Scope is bucketed from the tree layout: the first path segment, de-pluralized (journals/… → journal), root for top-level files; modified_by is the Syncthing event's device for remote pulls, local for local edits, startup or reconcile for walk passes. The --max-depth flag (default unlimited) coarsens the spool: one event per heading at level ≤ N with deeper text folded into the kept ancestor's body — the enumeration's roll-up, not snapshot state, so changing it re-diffs honestly. Values below 1 are rejected at the command layer before any produce state is touched (CliktError, nonzero exit): depth 0 on a previously walked tree would otherwise silently spool every tracked heading as a deletion.

Bootstrap & replay policy

The corpus is large and every agent config multiplies it: a naive cold start over an empty snapshot store emits one added event per heading — on the real tree that is 35706 nodes times as many agents as exist, all of them pointless classification of text that was already sitting in the tree before the harness existed. So the first produce over an empty snapshot store runs in *BASELINE mode* instead:

  • Snapshots are seeded for every tracked file (zero per-heading events appended), and one *audit marker line {"type":"baseline","ts":…,"files":N,"headings":M,"head_seq":S} is appended to the spool. It carries no seq and consumes none: markers ride the month files with events but every reader skips them (not events, not gaps, seq semantics unchanged). head_seq is the spool head at baseline time, so the marker answers "what did the state look like when the acting log started". - The implicit trigger is snapshot store empty — the store is never re-baselined on its own; once established, events flow from now forward exactly as before. - --emit-initial-events restores the legacy cold start (emit everything over an empty store) for tests and small trees. - --baseline forces a baseline re-seed* even on an established store by hand: snapshots rewritten from disk, zero events, one more marker. Corrupt state, scope changes, and "the spool is a pointer now, redo the seeding" all resolve through it.

Replay is the drain-side counterpart: a newly discovered agent config initializes its cursor at the *spool head and does not classify history (one stderr notice); re-classifying any window of the past is always deliberate via drain --from-seq N, bounded by --max-events-per-agent, and the cursor never regresses. Deliberate replay, never implicit catch-up. The A3 wake dispatcher mirrors this exactly: a fresh agent's dispatch cursor head-inits at the spool head with one stderr notice (history is never implicitly woken*), and deliberate wake-replay is the sanctioned manual knob — delete cursors/AGENT.dispatch (re-head-init at the spool head, nothing re-woken) or rewrite it to a seq N (everything with an fsynced yes above N wakes, capped by the per-agent lane budgets). Dispatch deliberately has no =--from-seq=-style flag: replay costs no LLM calls, so a cursor-file rewrite is enough.

The harness's Syncthing event subscription

The producer subscribes to LocalChangeDetected + RemoteChangeDetected with its own long-poll client and its own cursor. The syncthing watcher's pitfall stands: REST event id values are per-subscription (one buffered subscription per events mask), so the seed request MUST ask for exactly the mask the poll loop asks for, or the cursor lands in a foreign ID space and the loop stalls silently. The DTOs and folder-resolution/item-relativization helpers come from the indexer's syncthing.org module; this client is the harness's own class so the two watchers never share cursor state.

kotlin#+name: harness-client-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.indexer.SYNCTHING_LOCAL_CHANGE
import computer.whatthefuck.arcology.indexer.SYNCTHING_REMOTE_CHANGE
import computer.whatthefuck.arcology.indexer.SyncthingAuthException
import computer.whatthefuck.arcology.indexer.SyncthingClient
import computer.whatthefuck.arcology.indexer.SyncthingClientException
import computer.whatthefuck.arcology.indexer.SyncthingEvent
import computer.whatthefuck.arcology.indexer.SyncthingFolder
import io.ktor.client.*
import io.ktor.client.engine.*
import io.ktor.client.engine.cio.CIO
import io.ktor.client.plugins.ClientRequestException
import io.ktor.client.plugins.HttpTimeout
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import kotlinx.serialization.json.Json
kotlin#+name: harness-syncthing-client
/**
 * The harness producer's own Syncthing REST client over the indexer's
 * [[SyncthingClient]] interface — a second client instance is its own
 * event subscription. The seed (latestEventId) and the poll (events)
 * MUST carry the same disk-event mask: /rest/events ids are per-
 * subscription per mask, and a cursor from a differently-masked
 * subscription belongs to a different ID space (the original silent-
 * stall incident).
 */
class HarnessSyncthingClient(
    private val baseUrl: String,
    private val apiKey: String,
    pollTimeoutSeconds: Int = 60,
    engine: HttpClientEngine? = null,
) : SyncthingClient {

    private val json = Json { ignoreUnknownKeys = true }

    // The HTTP request timeout must exceed the server-side long-poll
    // window so a quiet stream reads as an empty array, not a timeout.
    private val clientConfig: HttpClientConfig<*>.() -> Unit = {
        expectSuccess = true
        install(HttpTimeout) {
            requestTimeoutMillis = (pollTimeoutSeconds + 30) * 1000L
        }
    }

    // Tests inject a MockEngine; production takes the CIO factory.
    private val client = if (engine != null) {
        HttpClient(engine, clientConfig)
    } else {
        HttpClient(CIO, clientConfig)
    }

    private suspend fun request(
        path: String,
        configure: HttpRequestBuilder.() -> Unit = {},
    ): String =
        try {
            client.get("$baseUrl$path") {
                header("X-API-Key", apiKey)
                configure()
            }.bodyAsText()
        } catch (e: ClientRequestException) {
            if (e.response.status.value == 403) {
                throw SyncthingAuthException("Syncthing returned 403 — check the API key", e)
            }
            throw SyncthingClientException("Syncthing request to $path failed: ${e.message}", e)
        }

    override suspend fun folders(): List<SyncthingFolder> =
        json.decodeFromString<List<SyncthingFolder>>(request("/rest/config/folders"))

    override suspend fun events(since: Long, timeoutSeconds: Int): List<SyncthingEvent> =
        json.decodeFromString<List<SyncthingEvent>>(
            request("/rest/events") {
                parameter("events", "$SYNCTHING_LOCAL_CHANGE,$SYNCTHING_REMOTE_CHANGE")
                parameter("since", since)
                parameter("timeout", timeoutSeconds)
            }
        )

    override suspend fun latestEventId(): Long? =
        json.decodeFromString<List<SyncthingEvent>>(
            request("/rest/events") {
                // The cursor must come from the same subscription the
                // poll loop reads: ids are per-mask on this endpoint.
                parameter("events", "$SYNCTHING_LOCAL_CHANGE,$SYNCTHING_REMOTE_CHANGE")
                parameter("since", 0)
                parameter("limit", 1)
            }
        ).lastOrNull()?.id
}
kotlin#+name: harness-client-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessSyncthingClient.kt:noweb yes
<<harness-client-imports>>

<<harness-syncthing-client>>

Spool: append-only ndjson

The spool line schema (one JSON object per line, field order fixed for greppability):

key meaning
seq global monotonic integer, gap-free, assigned by the single producer
ts ISO8601 with offset — production wall clock
scope content bucket from the tree layout (first path segment, de-pluralized; root)
file tree-relative org path
identity {org_id, key} — org_id nullable; key is always file::outline-path
action added revised deleted; refile = added plus deleted (two events, see below)
title heading title
todo heading TODO state, nullable
body heading text capped at --max-body-bytes (default 20480) with an explicit [truncated at N bytes] marker
revision sha256 hex of heading content (headingRevision)
risk {max, gated} — max nullable when the classifier was unreachable; gated is true whenever max is null (fail closed)
modified_by device name: the Syncthing event's modifiedBy for remote pulls, "local" for local edits, "startup"/"reconcile"

Parse tolerance: one extra line shape rides the same month files — the baseline audit marker {"type":"baseline","ts":…,"files":N,"headings":M,"head_seq":S} (*Bootstrap & replay policy). It carries *no seq*, consumes none, and every reader (drain event selection, status render, seq-resume scan) skips it silently: not an event, not a gap.

Refile is added plus deleted; treat as two events: a heading whose derived identity moved gets a deleted event at its old key and an added event at its new one. The refiled enum value is reserved by schema but never emitted literally.

Example line:

example
{"seq":41207,"ts":"2026-11-10T08:12:03-08:00","scope":"journal","file":"journals/2026-11/10.org","identity":{"org_id":"20261110T163846.123456","key":"journals/2026-11/10.org::4.2"},"action":"added","title":"Morning entry","body":"...","revision":"9f2c1a...","risk":{"max":0.3,"gated":false},"modified_by":"local"}
kotlin#+name: harness-spool-imports
package computer.whatthefuck.arcology.harness

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.contentOrNull
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.put
import java.io.File
import java.io.FileOutputStream
import java.nio.file.Files
kotlin#+name: harness-spool-types
/** identity.org_id is the heading's existing :ID: or null — never minted. */
@Serializable
data class SpoolIdentity(
    @SerialName("org_id") val orgId: String? = null,
    /** Derived identity key: always "file::outline-path". */
    val key: String,
)

/**
 * Per-event risk stamp, made at production time by the
 * [[ProducerRiskClassifier]]. [max] is the max category score; null means
 * the classifier could not be reached when the event was stamped — which
 * IS the fail-closed outcome: [gated] carries the gate decision and is
 * true whenever [max] is null.
 */
@Serializable
data class SpoolRisk(
    val max: Double? = null,
    val gated: Boolean,
)

/** One spool line. [action] ∈ added|revised|deleted (refiled arrives as
 * a deleted+added pair; the literal enum value is reserved by schema). */
@Serializable
data class SpoolEvent(
    val seq: Long = 0,
    /** ISO8601 with offset. */
    val ts: String,
    val scope: String,
    /** Tree-relative org path. */
    val file: String,
    val identity: SpoolIdentity,
    val action: String,
    val title: String,
    val todo: String? = null,
    val body: String = "",
    /** sha256 hex of the heading content. */
    val revision: String,
    val risk: SpoolRisk,
    @SerialName("modified_by") val modifiedBy: String,
)
kotlin#+name: harness-spool-writer
/**
 * Append-only ndjson spool under =<stateRoot>/spool/YYYY-MM.ndjson=. One
 * line per heading event; seq is assigned here, gap-free and strictly
 * monotonic across restarts (see [[*Seq resume takes max(seq file, spool
 * scan)]]). Append → fsync → seq-file persist, in that order, every line.
 */
class SpoolWriter(private val stateRoot: File) {
    private val spoolDir = File(stateRoot, "spool")
    private val seqFile = File(stateRoot, "producer.seq")
    private val json = Json { ignoreUnknownKeys = true }
    private var lastSeq: Long = 0

    init {
        spoolDir.mkdirs()
        lastSeq = scanHighestSeq()
    }

    private fun spoolFiles(): List<File> =
        spoolDir.listFiles()
            ?.filter { it.isFile && it.name.endsWith(".ndjson") }
            ?.sortedBy { it.name }
            ?: emptyList()

    /** max(seq file, highest seq in the spool): the crash-window-safe
     * resume rule. Unparseable (torn) lines are skipped, never gaps;
     * audit markers carry no seq and are skipped silently. */
    private fun scanHighestSeq(): Long {
        var highest = seqFile.takeIf { it.isFile }
            ?.readText()?.trim()?.toLongOrNull() ?: 0L
        for (file in spoolFiles()) {
            file.useLines { lines ->
                for (line in lines) {
                    if (isMarkerLine(line)) continue
                    val seq = SEQ_PREFIX.find(line)?.groupValues?.get(1)
                        ?.toLongOrNull() ?: continue
                    if (seq > highest) highest = seq
                }
            }
        }
        return highest
    }

    fun currentSeq(): Long = lastSeq

    fun monthFileFor(ts: String): File = File(spoolDir, ts.take(7) + ".ndjson")

    /**
     * Assign the next seq, append one fsynced line to the event's month
     * file, then persist the seq mirror. Returns the seq assigned.
     */
    fun append(event: SpoolEvent): Long {
        val seq = lastSeq + 1
        val fixed = event.copy(seq = seq)
        val target = monthFileFor(fixed.ts)
        FileOutputStream(target, true).use { out ->
            out.write((renderSpoolLine(fixed) + "\n").toByteArray(Charsets.UTF_8))
            out.flush()
            out.fd.sync()
        }
        lastSeq = seq
        Files.writeString(seqFile.toPath(), seq.toString() + "\n")
        return seq
    }

    /**
     * Append a raw line (an audit marker) with fsync, WITHOUT seq
     * assignment: markers carry no seq and consume none. The line's own
     * =ts= places it in the right month file.
     */
    fun appendRaw(line: String) {
        val ts = runCatching {
            Json.parseToJsonElement(line).jsonObject["ts"]
                ?.jsonPrimitive?.contentOrNull
        }.getOrNull() ?: throw IllegalArgumentException(
            "raw spool line must carry a ts (got: ${line.take(80)})"
        )
        val target = monthFileFor(ts)
        FileOutputStream(target, true).use { out ->
            out.write((line + "\n").toByteArray(Charsets.UTF_8))
            out.flush()
            out.fd.sync()
        }
    }

    /** Every event, oldest first: month files in name order, lines in
     * file order. Torn lines are skipped with a log line; audit markers
     * are skipped silently (known content, not an event, not a gap). */
    fun readEvents(log: (String) -> Unit = { }): List<SpoolEvent> {
        val out = mutableListOf<SpoolEvent>()
        for (file in spoolFiles()) {
            file.useLines { lines ->
                for (line in lines) {
                    if (line.isBlank()) continue
                    if (isMarkerLine(line)) continue
                    val event = parseSpoolLine(line)
                    if (event == null) {
                        log("skipping unparseable spool line in ${file.name}")
                        continue
                    }
                    out.add(event)
                }
            }
        }
        return out.sortedBy { it.seq }
    }

    /** Events with seq > [minSeq], oldest first, reading across month
     * boundaries (month files in name order). Audit markers carry no
     * seq and are skipped silently; torn lines are skipped with a log
     * line — the producer appending while the dispatcher reads is
     * tolerated, never a crash. This is the payload join behind
     * [[HarnessDispatch]] and the status collector's held-wake count. */
    fun eventsSince(minSeq: Long, log: (String) -> Unit = { }): List<SpoolEvent> {
        val out = mutableListOf<SpoolEvent>()
        for (file in spoolFiles()) {
            file.useLines { lines ->
                for (line in lines) {
                    if (line.isBlank()) continue
                    if (isMarkerLine(line)) continue
                    val event = parseSpoolLine(line)
                    if (event == null) {
                        log("skipping unparseable spool line in ${file.name}")
                        continue
                    }
                    if (event.seq > minSeq) out.add(event)
                }
            }
        }
        return out.sortedBy { it.seq }
    }

    companion object {
        private val SEQ_PREFIX = Regex("""^\{"seq":(\d+)""")
        private val MARKER_RE = Regex(""""type"\s*:\s*"baseline"""")

        /** Audit-marker detector: baseline markers ride the month files
         * with events but every reader must skip them. */
        fun isMarkerLine(line: String): Boolean = MARKER_RE.containsMatchIn(line)

        /** The baseline audit marker: no seq, consumes none. */
        fun buildBaselineMarker(
            files: Int,
            headings: Int,
            headSeq: Long,
            ts: String,
        ): String = buildJsonObject {
            put("type", JsonPrimitive("baseline"))
            put("ts", JsonPrimitive(ts))
            put("files", JsonPrimitive(files))
            put("headings", JsonPrimitive(headings))
            put("head_seq", JsonPrimitive(headSeq))
        }.toString()

        fun renderSpoolLine(event: SpoolEvent): String = buildJsonObject {
            put("seq", JsonPrimitive(event.seq))
            put("ts", JsonPrimitive(event.ts))
            put("scope", JsonPrimitive(event.scope))
            put("file", JsonPrimitive(event.file))
            put("identity", buildJsonObject {
                if (event.identity.orgId != null) put("org_id", JsonPrimitive(event.identity.orgId))
                put("key", JsonPrimitive(event.identity.key))
            })
            put("action", JsonPrimitive(event.action))
            put("title", JsonPrimitive(event.title))
            if (event.todo != null) put("todo", JsonPrimitive(event.todo))
            put("body", JsonPrimitive(event.body))
            put("revision", JsonPrimitive(event.revision))
            put("risk", buildJsonObject {
                if (event.risk.max != null) put("max", JsonPrimitive(event.risk.max))
                put("gated", JsonPrimitive(event.risk.gated))
            })
            put("modified_by", JsonPrimitive(event.modifiedBy))
        }.toString()

        fun parseSpoolLine(line: String): SpoolEvent? = try {
            spoolJson.decodeFromString(SpoolEvent.serializer(), line)
        } catch (e: Exception) {
            null
        }

        private val spoolJson = Json { ignoreUnknownKeys = true }
    }
}
kotlin#+name: harness-spool-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/SpoolWriter.kt:noweb yes
<<harness-spool-imports>>

<<harness-spool-types>>

<<harness-spool-writer>>

Snapshot store — file → outline-path → revision

One JSON file per tracked org file under ~/.cache/arcology2/harness/snapshots/, named =sha256(tree-relative-path)+".json=" — bounded, deterministic names because the org tree names files after their titles and URL-encoded mega-names (plus the atomic-write .tmp) blew past the kernel's 255-byte filename limit. The path lives inside the JSON ([SnapshotFile.file]); the title rides along so deleted events can carry one after the file is gone; the org id enables stable identity matching across moves (the refile pairing) even though the spool key stays file::outline-path. Pre-hash snapshots (URL-encoded names) migrate in place on first read: same state, zero re-emissions.

kotlin#+name: harness-snapshot-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.utils.HashUtils
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import java.io.File
import java.net.URLEncoder
kotlin#+name: harness-snapshot-types
/** entries: outline-path → revision state. */
@Serializable
data class SnapshotFile(
    val file: String,
    val entries: Map<String, SnapshotEntry>,
)

@Serializable
data class SnapshotEntry(
    val hash: String,
    val orgId: String? = null,
    val title: String? = null,
)
kotlin#+name: harness-snapshot-store
/**
 * Per-file snapshot files under =<stateRoot>/snapshots/=, one per tracked
 * org file. The name is =sha256(tree-relative path)+".json"= — bounded and
 * deterministic: the org tree names files after their titles, and
 * URL-encoded mega-names (plus the =.tmp= of the atomic write) blew past
 * the kernel's 255-byte filename limit. The identity lives INSIDE the
 * JSON ([SnapshotFile.file]), not in the name. Pre-hash snapshots
 * (URL-encoded-name scheme) migrate in place on first read — same state,
 * so no re-emissions on the next diff. Corrupt or torn snapshots read as
 * "unseen" — the next diff re-emits, the restart-dedupe contract is about
 * *fresh* hashes, not damaged state.
 */
class SnapshotStore(private val stateRoot: File) {
    private val snapshotDir = File(stateRoot, "snapshots")
    private val json = Json { ignoreUnknownKeys = true }

    init {
        snapshotDir.mkdirs()
    }

    fun fileFor(relative: String): File =
        File(snapshotDir, HashUtils.sha256(relative) + ".json")

    /** Pre-hash naming scheme (URL-encoded path): migrated on read. */
    private fun legacyFileFor(relative: String): File =
        File(snapshotDir, URLEncoder.encode(relative, "UTF-8") + ".json")

    private fun parseEntries(file: File): Map<String, SnapshotEntry> = try {
        json.decodeFromString(SnapshotFile.serializer(), file.readText()).entries
    } catch (e: Exception) {
        emptyMap()
    }

    fun load(relative: String): Map<String, SnapshotEntry> {
        val current = fileFor(relative)
        if (current.isFile) return parseEntries(current)
        val legacy = legacyFileFor(relative)
        if (legacy.isFile) {
            val entries = parseEntries(legacy)
            save(relative, entries)
            legacy.delete()
            return entries
        }
        return emptyMap()
    }

    fun save(relative: String, entries: Map<String, SnapshotEntry>) {
        val target = fileFor(relative)
        val tmp = File(snapshotDir, target.name + ".tmp")
        tmp.writeText(json.encodeToString(SnapshotFile.serializer(), SnapshotFile(relative, entries)))
        if (!tmp.renameTo(target)) {
            // Fall back to a direct write if rename hits a cross-device
            // or permission hiccup; still not a correctness surface.
            tmp.delete()
            target.writeText(
                json.encodeToString(SnapshotFile.serializer(), SnapshotFile(relative, entries))
            )
        }
        legacyFileFor(relative).takeIf { it.isFile }?.delete()
    }

    fun remove(relative: String) {
        fileFor(relative).delete()
        legacyFileFor(relative).delete()
    }

    fun count(): Int =
        snapshotDir.listFiles()
            ?.count { it.isFile && it.name.endsWith(".json") }
            ?: 0

    /** Every tracked path, read from the JSON bodies so BOTH naming
     * schemes (hashed and legacy URL-encoded) surface uniformly. */
    fun trackedFiles(): List<String> =
        snapshotDir.listFiles()
            ?.filter { it.isFile && it.name.endsWith(".json") }
            ?.mapNotNull { f ->
                try {
                    json.decodeFromString(SnapshotFile.serializer(), f.readText()).file
                } catch (e: Exception) {
                    null
                }
            }
            ?.distinct()
            ?: emptyList()
}
kotlin#+name: harness-snapshot-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/SnapshotStore.kt:noweb yes
<<harness-snapshot-imports>>

<<harness-snapshot-types>>

<<harness-snapshot-store>>

The shared LLM verdict cache

The classifier's llm_verdict_cache is a sqlite table keyed by (content hash, model) inside arcology.db. The harness may not touch any arcology.db, so the precedent is reused as a plain append-only ndjson file: ~/.cache/arcology2/harness/llm-verdict-cache.ndjson, keyed sha256|model|variant where variant disambiguates the question a verdict answers (risk for production stamps, agent-NAME-pge3 for the drain's act-tail verdicts and agent-NAME-urgency for urgency; the bare agent-NAME variant held the retired expected-level statistic and is never read or written any more). Unavailable classifications are never cached — the next run retries.

kotlin#+name: harness-cache-imports
package computer.whatthefuck.arcology.harness

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import java.io.File
import java.io.FileOutputStream
kotlin#+name: harness-llm-cache
/** One cache line; readers only touch the variant's own fields. */
@Serializable
data class LlmCacheLine(
    val ts: String,
    val key: String,
    val max: Double? = null,
    val gated: Boolean? = null,
    val conf: Double? = null,
)

class LlmVerdictCache(private val file: File?) {
    private val json = Json { ignoreUnknownKeys = true }
    private val entries = mutableMapOf<String, LlmCacheLine>()

    init {
        if (file != null && file.isFile) {
            try {
                file.useLines { lines ->
                    for (line in lines) {
                        if (line.isBlank()) continue
                        val parsed = runCatching {
                            json.decodeFromString(LlmCacheLine.serializer(), line)
                        }.getOrNull() ?: continue
                        entries[parsed.key] = parsed
                    }
                }
            } catch (e: Exception) {
                // A torn cache is a cache miss, never a correctness event.
                entries.clear()
            }
        }
    }

    fun lookupRisk(key: String): Pair<Double, Boolean>? =
        entries[key]?.let { line ->
            if (line.max != null && line.gated != null) line.max to line.gated else null
        }

    fun lookupConf(key: String): Double? = entries[key]?.conf

    /** Appends one line; last write wins in the in-memory map. */
    fun rememberRisk(key: String, max: Double, gated: Boolean, ts: String) {
        if (file == null) return
        entries[key] = LlmCacheLine(ts, key, max = max, gated = gated)
        append(LlmCacheLine(ts, key, max = max, gated = gated))
    }

    fun rememberConf(key: String, conf: Double, ts: String) {
        if (file == null) return
        entries[key] = LlmCacheLine(ts, key, conf = conf)
        append(LlmCacheLine(ts, key, conf = conf))
    }

    private fun append(line: LlmCacheLine) {
        FileOutputStream(file, true).use { out ->
            out.write((json.encodeToString(LlmCacheLine.serializer(), line) + "\n").toByteArray(Charsets.UTF_8))
            out.flush()
            out.fd.sync()
        }
    }
}
kotlin#+name: harness-cache-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/LlmVerdictCache.kt:noweb yes
<<harness-cache-imports>>

<<harness-llm-cache>>

Production-time risk stamping

D5: the spool only stamps risk per event; enforcement (withholding gated bodies from remote runners) is P2. Because the producer cannot open arcology.db, the stamp speaks to the same resident llm/classifier.org /v1/systemone endpoint through the existing RiskClassifier client directly — one sequential call set per event, cache-backed by the plain-file cache above. Fail-closed: no endpoint configured, or the endpoint unreachable ⇒ =max=null, gated=true= — the event still spools (it is the acting log; risk is an overlay), but nothing downstream may treat it as clean.

kotlin#+name: harness-risk-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.llm.ClassificationResult
import computer.whatthefuck.arcology.llm.RiskClassifier
import computer.whatthefuck.arcology.utils.HashUtils
import io.ktor.client.*
import java.io.File
import java.time.OffsetDateTime
kotlin#+name: harness-producer-risk
/**
 * Production-time risk classification for spool events. Reuses the
 * existing [[RiskClassifier]] client plus the llm_verdict_cache precedent
 * re-homed as a plain ndjson file (no arcology.db on this path). Blank
 * text mirrors the gate's blank-skip: nothing to protect, ungated.
 */
class ProducerRiskClassifier(
    private val endpoint: String?,
    private val model: String,
    private val threshold: Double,
    cacheFile: File?,
    private val httpClient: HttpClient,
    private val now: () -> String = { OffsetDateTime.now().toString() },
) {
    private val cache = LlmVerdictCache(cacheFile)
    private val classifier: RiskClassifier? =
        endpoint?.let { RiskClassifier(it, model, httpClient) }

    suspend fun stamp(text: String): SpoolRisk {
        if (text.isBlank()) return SpoolRisk(max = 0.0, gated = false)
        if (classifier == null) return SpoolRisk(max = null, gated = true)
        val contentHash = HashUtils.sha256(text)
        val key = "$contentHash|$model|risk"
        cache.lookupRisk(key)?.let { (max, gated) -> return SpoolRisk(max = max, gated = gated) }
        return when (val result = classifier.classify(text)) {
            is ClassificationResult.Success -> {
                val max = result.scores.overall
                val gated = max > threshold
                cache.rememberRisk(key, max, gated, now())
                SpoolRisk(max = max, gated = gated)
            }
            is ClassificationResult.Unavailable ->
                // Fail closed, do not cache: the next stamp retries.
                SpoolRisk(max = null, gated = true)
        }
    }
}
kotlin#+name: harness-risk-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/ProducerRiskClassifier.kt:noweb yes
<<harness-risk-imports>>

<<harness-producer-risk>>

The verdicts-only drain

Classification contract per agent agents/<name>/CLASSIFIER.org file; the named should_act question, sent as a decision-API score question whose instructions are the section's prose and whose criteria are the five nested =* Level 0..4= sections' body texts, parsed per-agent (never generic constants in code). The act statistic is the answer's tail probability P(level ≥ 3) (summed from the score answer's probability map) compared against the config's THRESHOLD; the older expected-level/4 statistic was measured (kev4b, seq 95, 2026-11-13) to sit exactly on its own pass-line for a pure level-3 answer and to collapse under hedge mass — 58 of 156 verdicts landed in the 0.60–0.75 dead zone below the gate, including events whose probability mass was a clear majority at act levels — so EV gating systematically under-woke; expected level/4 remains only as the urgency statistic (plus the optional urgency score question over the same outline shape, URGENCY flag). The API rejects everything but choice, score, and noul question types, and a score question requires non-empty criteria — the criteria-less yes-no shape this module originally sent never worked against the resident model (live 400, 2026-11-11). Verdicts append to ~/.cache/arcology2/harness/verdicts/YYYY-MM-DD.ndjson with fields seq, agent, verdict, confidence, model, ts plus urgency when asked — a grep/awk-flat calibration set; confidence carries the act tail (rows before 2026-11-13 carry the EV instead). Each agent owns a one-integer cursor at ~/.cache/arcology2/harness/cursors/AGENT.verdict (last seq classified); it advances only* after the verdict line is fsynced. A kill-and-restart re-selects the events whose cursor is behind, re-classifies from the plain-file cache, and re-logs nothing: the (seq, agent) seen-set is rebuilt from the verdict files themselves, so the mid-crash window between log-write and cursor-write is idempotent.

GPU discipline is structural: the drain is a sequential loop over grouped events — one in-flight call, ever, by construction (no launch, no async anywhere below).

Agent Configuration

kotlin#+name: harness-config-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.llm.renderEnumerationChunks
import computer.whatthefuck.arcology.parser.OrgFileParser
import computer.whatthefuck.arcology.parser.ParseResult
import xyz.lepisma.orgmode.OrgSection
import xyz.lepisma.orgmode.plainText
import java.io.File
import kotlin.time.Instant
kotlin#+name: harness-agent-config
/**
 * One agent's classifier configuration, parsed out of
 * =<agentsDir>/<agent>/CLASSIFIER.org=: file-level =THRESHOLD= (0..1,
 * default 0.65) and =URGENCY= (yes/no, default no) properties, a
 * =* should_act= heading whose leading prose is the instructions and
 * whose nested =** Level 0..4= sections carry the per-agent rubric
 * criteria in level order, and an optional =* urgency= heading with the
 * same outline shape. Plus the wake-policy properties (=WAKE=,
 * =MAX_WAKES=, =MAX_URGENT_WAKES=, =MIN_WAKE_INTERVAL=) that only the
 * dispatcher consults — the drain ignores them entirely, so a typo'd
 * wake knob costs wakes, never verifications. The document outline IS
 * the parse structure: a malformed rubric (missing, duplicate, or blank
 * level) makes the whole config unusable — the same fail-shut
 * convention as a missing section.
 */
data class AgentClassifierConfig(
    val agent: String,
    val configPath: File,
    val threshold: Double,
    val urgency: Boolean,
    val shouldAct: String,
    /** Per-agent criteria parsed from the should_act Level sections. */
    val shouldActCriteria: List<String>,
    val urgencyQuestion: String? = null,
    /** Same-shape urgency rubric; non-null iff [urgency]. */
    val urgencyCriteria: List<String>? = null,
    /** Wake opt-in + knobs, default off; [[WakePolicy.Malformed]] makes
     * the dispatcher skip the agent (fail-shut) while the drain keeps
     * running. */
    val wake: WakePolicy = WakePolicy.Off,
)

object ClassifierConfigs {
    const val FILE_NAME = "CLASSIFIER.org"
    /** THRESHOLD compares against the ACT tail statistic
     *  P(level >= 3) — not the expected level / 4. On the EV scale the
     *  same number meant something much stricter (a pure level-3 answer
     *  scores exactly 0.75 there, so 0.75 rejected every hedged level-3
     *  event); 0.65 on the tail scale is the re-anchored default. */
    const val DEFAULT_THRESHOLD = 0.65

    /** Rubric level section title: exactly "Level N", N a single digit
     * 0..4. Anything else nested under a question section is not part
     * of the rubric grammar. */
    private val LEVEL_TITLE = Regex("""Level ([0-4])""")

    /** Section body → instruction text via the enumeration renderer. */
    internal fun sectionBodyText(section: xyz.lepisma.orgmode.OrgSection): String {
        val sb = StringBuilder()
        renderEnumerationChunks(section.body, sb)
        return sb.toString().trim()
    }

    /**
     * Render only a section's LEADING body chunks — the elements before
     * its first nested OrgSection, i.e. the prose instructions that sit
     * above the =** Level N= rubric sections.
     */
    private fun leadingBodyText(
        section: xyz.lepisma.orgmode.OrgSection
    ): String {
        val sb = StringBuilder()
        renderEnumerationChunks(
            section.body.takeWhile { it !is xyz.lepisma.orgmode.OrgSection },
            sb,
        )
        return sb.toString().trim()
    }

    /**
     * The per-agent rubric: each nested =** Level N= section's rendered
     * body text as criteria entry N, returned sorted by level. null on
     * any malformed rubric — a missing or duplicate level, or a blank
     * level body — the config is unusable, fail-shut.
     */
    private fun levelCriteria(
        section: xyz.lepisma.orgmode.OrgSection
    ): List<String>? {
        val entries = mutableMapOf<Int, String>()
        for (child in section.body.filterIsInstance<xyz.lepisma.orgmode.OrgSection>()) {
            val match = LEVEL_TITLE.matchEntire(
                child.heading.title.plainText().trim()
            ) ?: continue
            val level = match.groupValues[1].toInt()
            val text = sectionBodyText(child)
            if (text.isBlank() || level in entries) return null
            entries[level] = text
        }
        return (0..4).map { entries[it] ?: return null }
    }

    fun parse(agent: String, path: File, content: String): AgentClassifierConfig? {
        val parseResult = OrgFileParser().parseFileContent(
            path.path, content, kotlin.time.Instant.fromEpochSeconds(0)
        )
        val document = (parseResult as? ParseResult.Success)?.document ?: return null
        // Properties are optional: threshold and urgency both default.
        val props = document.preamble.properties?.map ?: emptyMap()
        fun value(key: String): String? =
            props[key]?.let { line ->
                line.items.filterIsInstance<xyz.lepisma.orgmode.OrgInlineElem.Text>()
                    .joinToString("") { it.text }.trim().takeIf { it.isNotEmpty() }
            }

        val threshold = value("THRESHOLD")?.toDoubleOrNull()
            ?: DEFAULT_THRESHOLD
        val urgencyFlag = value("URGENCY")?.lowercase() in setOf("yes", "true")
        // Wake policy (A3): parsed from the same drawer, consulted only
        // by the dispatcher. WAKE absent/no/garbage stays Off; a knob
        // that is present but garbage/negative poisons the whole policy
        // into Malformed — the dispatcher then skips this agent (fail
        // shut) and the drain never notices the field exists.
        val wake = run {
            val flag = value("WAKE")?.lowercase()
            if (flag == null || flag !in setOf("yes", "true")) return@run WakePolicy.Off
            fun knobLong(key: String, default: Long): Long? {
                val raw = value(key) ?: return default
                val n = raw.toLongOrNull()
                return n?.takeIf { it >= 0 }
            }
            val maxWakes = knobLong("MAX_WAKES", WAKE_DEFAULT_MAX_WAKES.toLong())
                ?: return@run WakePolicy.Malformed("MAX_WAKES is not a non-negative integer")
            val maxUrgentWakes = knobLong("MAX_URGENT_WAKES", WAKE_DEFAULT_MAX_URGENT_WAKES.toLong())
                ?: return@run WakePolicy.Malformed("MAX_URGENT_WAKES is not a non-negative integer")
            val minInterval = knobLong("MIN_WAKE_INTERVAL", WAKE_DEFAULT_MIN_WAKE_INTERVAL_MINUTES)
                ?: return@run WakePolicy.Malformed("MIN_WAKE_INTERVAL is not a non-negative integer")
            WakePolicy.On(maxWakes.toInt(), maxUrgentWakes.toInt(), minInterval)
        }
        val sections = flattenSections(document.content)
        val shouldActSection = sections.firstOrNull {
            it.heading.title.plainText().trim() == "should_act"
        } ?: return null
        val shouldAct = leadingBodyText(shouldActSection)
        if (shouldAct.isBlank()) return null // fail-shut config: unusable
        val shouldActCriteria = levelCriteria(shouldActSection) ?: return null
        var urgencyQuestion: String? = null
        var urgencyCriteria: List<String>? = null
        if (urgencyFlag) {
            val urgencySection = sections.firstOrNull {
                it.heading.title.plainText().trim() == "urgency"
            } ?: return null
            urgencyQuestion = leadingBodyText(urgencySection)
            if (urgencyQuestion.isBlank()) return null
            urgencyCriteria = levelCriteria(urgencySection) ?: return null
        }
        return AgentClassifierConfig(
            agent = agent,
            configPath = path,
            threshold = threshold,
            urgency = urgencyFlag,
            shouldAct = shouldAct,
            shouldActCriteria = shouldActCriteria,
            urgencyQuestion = urgencyQuestion,
            urgencyCriteria = urgencyCriteria,
            wake = wake,
        )
    }

    private fun flattenSections(
        sections: List<xyz.lepisma.orgmode.OrgSection>
    ): List<xyz.lepisma.orgmode.OrgSection> = sections + sections.flatMap {
        flattenSections(it.body.filterIsInstance<xyz.lepisma.orgmode.OrgSection>())
    }

    /** Scan =<agentsDir>/<agent>/CLASSIFIER.org= for every agent dir. */
    fun discover(agentsDir: File): List<AgentClassifierConfig> {
        if (!agentsDir.isDirectory) return emptyList()
        return agentsDir.listFiles()
            ?.filter { it.isDirectory }
            ?.sortedBy { it.name }
            ?.mapNotNull { dir ->
                val cfg = File(dir, FILE_NAME)
                if (!cfg.isFile) return@mapNotNull null
                parse(dir.name, cfg, cfg.readText())
            }
            ?: emptyList()
    }
}
kotlin#+name: harness-config-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/AgentClassifierConfig.kt:noweb yes
<<harness-config-imports>>

<<harness-agent-config>>

Verdict Classifier

kotlin#+name: harness-verdict-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.llm.SystemOneResponse
import io.ktor.client.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonArray
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.doubleOrNull
import kotlinx.serialization.json.jsonPrimitive
import kotlinx.serialization.json.put
kotlin#+name: harness-verdict-classifier
/** One classification attempt against the decision API. */
sealed interface VerdictResult {
    /**
     * Rubric question. [score] is the probability-weighted level / 4,
     * clamped — the URGENCY statistic. [probAtLeast3] is the ACT
     * statistic: the tail probability P(level ≥ [ACT_MIN_LEVEL]) summed
     * from the answer's probability map, or null when the answer carries
     * no map. The should_act gate reads the tail, never the EV: EV
     * thresholded at a level boundary sinks pure-level-3 verdicts under
     * ANY hedge mass below (a lone ~15% hedge at level 0 was measured to
     * veto an event carrying 70% of its mass at ≥level 3 — kev4b live,
     * seq 95, 2026-11-13).
     */
    data class Score(
        val score: Double,
        val probAtLeast3: Double? = null,
    ) : VerdictResult
    /** Unreachable/unusable — every failure mode fails closed upstream. */
    data class Unavailable(val reason: String) : VerdictResult
}

/** Level at which the five-level rubric turns into "should act". Not an
 * agent-tunable rubric — every CLASSIFIER.org level means the same
 * act-scale thing by grammar; this is where the act statistic cuts the
 * tail. The urgency lane keeps its EV statistic (scalar time-
 * criticality, no act boundary to collapse against). */
const val ACT_MIN_LEVEL = 3

/**
 * The drain-side classifier: one resident decision model, one request in
 * flight — every call is sequential inside [HarnessDrain]'s loop, and
 * this class issues no concurrent work either. Both verdict questions
 * (should_act, urgency) go out exactly like [[RiskClassifier]]'s: score
 * questions whose criteria are the per-agent rubric parsed from
 * CLASSIFIER.org's =** Level 0..4= sections, answers decoded leniently;
 * anything unanswerable is [VerdictResult.Unavailable].
 */
class VerdictClassifier(
    private val endpoint: String,
    private val model: String,
    private val httpClient: HttpClient,
) {
    private val responseJson = Json { ignoreUnknownKeys = true }

    /**
     * Ask one score question. [criteria] is the agent's parsed 5-level
     * rubric ([AgentClassifierConfig.shouldActCriteria] /
     * [AgentClassifierConfig.urgencyCriteria]). Both statistics come back
     * from one answer: the probability-weighted level normalized out of
     * 4 (RiskClassifier's levelToScore, clamped) and, when the answer
     * carries its probability map, the act tail P(≥ [ACT_MIN_LEVEL]).
     */
    suspend fun score(
        text: String,
        questionName: String,
        instructions: String,
        criteria: List<String>,
    ): VerdictResult {
        require(criteria.isNotEmpty()) {
            "score question '$questionName' needs a non-empty criteria array"
        }
        val body = buildJsonObject {
            put("model", JsonPrimitive(model))
            put("state", JsonPrimitive(text))
            put("questions", buildJsonObject {
                put(questionName, buildJsonObject {
                    put("type", JsonPrimitive("score"))
                    put("instructions", JsonPrimitive(instructions))
                    put("criteria", JsonArray(criteria.map { JsonPrimitive(it) }))
                })
            })
        }
        return try {
            withContext(Dispatchers.IO) {
                val response = httpClient.post("$endpoint/v1/systemone") {
                    contentType(ContentType.Application.Json)
                    setBody(body.toString())
                }
                if (!response.status.isSuccess()) {
                    return@withContext VerdictResult.Unavailable(
                        "classifier http ${response.status.value}"
                    )
                }
                val parsed = try {
                    responseJson.decodeFromString(SystemOneResponse.serializer(), response.bodyAsText())
                } catch (e: Exception) {
                    return@withContext VerdictResult.Unavailable("classifier response not parseable")
                }
                val answer = parsed.answers[questionName]
                    ?: return@withContext VerdictResult.Unavailable(
                        "classifier response missing answer '$questionName'"
                    )
                val ev = answer["score"]?.jsonPrimitive?.doubleOrNull
                    ?: return@withContext VerdictResult.Unavailable(
                        "rubric answer missing numeric score"
                    )
                // Act tail: Σ P(level) over levels >= ACT_MIN_LEVEL. The
                // real API ships the map with every score answer; a
                // missing map is tolerated here (urgency never gates on
                // it) and fails closed at the should_act site.
                val tail = (answer["probabilities"] as? JsonObject)
                    ?.mapNotNull { (level, mass) ->
                        val idx = level.toIntOrNull() ?: return@mapNotNull null
                        val p = (mass as? JsonPrimitive)?.doubleOrNull
                            ?: return@mapNotNull null
                        if (idx >= ACT_MIN_LEVEL) p else null
                    }
                    ?.sum()
                    ?.let { clamp01(it) }
                VerdictResult.Score(clamp01(ev / 4.0), tail)
            }
        } catch (e: Exception) {
            VerdictResult.Unavailable("classifier unreachable: ${e.message}")
        }
    }
}

internal fun clamp01(v: Double): Double = when {
    v.isNaN() || v < 0.0 -> 0.0
    v > 1.0 -> 1.0
    else -> v
}
kotlin#+name: harness-verdict-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/VerdictClassifier.kt:noweb yes
<<harness-verdict-imports>>

<<harness-verdict-classifier>>

The drain engine plus its verdict-line JSON singleton (package-internal so the tests share it):

kotlin#+name: harness-drain-json
internal val VerdictJson = Json { ignoreUnknownKeys = true }
kotlin#+name: harness-drain-engine
@Serializable
data class VerdictLogLine(
    val seq: Long,
    val agent: String,
    /** "yes" when confidence ≥ the agent's threshold, else "no";
     * "stale" for horizon-expired auto-verdicts. */
    val verdict: String,
    /** Number for LLM verdicts, string "stale-rule" for stale rows —
     * the calibration file stays grep/awk-flat in both shapes. */
    val confidence: kotlinx.serialization.json.JsonElement,
    val model: String,
    val ts: String,
    /** Set only when the agent config enables the urgency rubric. */
    val urgency: Double? = null,
)

data class DrainAgentOutcome(
    val agent: String,
    val processed: Int,
    val cursor: Long,
)

data class DrainOutcome(
    val agents: List<DrainAgentOutcome>,
    val failed: Boolean,
    val reason: String? = null,
)

/** The stale auto-verdict: NO LLM call, no cache touch, explicitly
 * inert downstream — only verdict ==yes ever means act (P2). */
internal fun staleVerdictLine(
    seq: Long,
    agent: String,
    ts: String,
): VerdictLogLine = kotlinx.serialization.json.buildJsonObject {
    put("seq", kotlinx.serialization.json.JsonPrimitive(seq))
    put("agent", kotlinx.serialization.json.JsonPrimitive(agent))
    put("verdict", kotlinx.serialization.json.JsonPrimitive("stale"))
    put("confidence", kotlinx.serialization.json.JsonPrimitive("stale-rule"))
    put("model", kotlinx.serialization.json.JsonPrimitive("stale-rule"))
    put("ts", kotlinx.serialization.json.JsonPrimitive(ts))
}.let { line ->
    VerdictJson.decodeFromString(VerdictLogLine.serializer(), line.toString())
}

/**
 * Verdicts-only drain: global FIFO oldest-first over the spool, grouped
 * by file so consecutive events share the prompt prefix (drain order
 * does the prefix-cache work for free), grouped per agent cursor.
 * Bootstrap & replay ([*Bootstrap & replay policy]): a fresh agent
 * cursor initializes at the spool head (no history classification, one
 * stderr notice); =--from-seq= replays a deliberate window without ever
 * regressing the cursor; =--only-agent= narrows the run;
 * =--max-events-per-agent= bounds LLM calls per run; the stale horizon
 * auto-verdicts ancient events before endpoint availability is even
 * considered. Fail closed: an unreachable classifier writes nothing for
 * fresh events, advances no cursor, reports [DrainOutcome.failed].
 */
class HarnessDrain(
    private val stateRoot: File,
    private val configs: List<AgentClassifierConfig>,
    private val classifier: VerdictClassifier?,
    private val model: String,
    private val now: () -> OffsetDateTime = { OffsetDateTime.now() },
    private val log: (String) -> Unit = { println(it) },
    /** Deliberate replay window start (inclusive), this run only. */
    private val fromSeq: Long? = null,
    /** Process exactly one agent's config (cursor files of others untouched). */
    private val onlyAgent: String? = null,
    /** LLM classification budget per agent per run; 0 = unlimited. */
    private val maxEventsPerAgent: Int = 200,
    /** Events older than this many days auto-verdict stale (no LLM). */
    private val staleHorizonDays: Int = 7,
    /** Notices (cursor head-init) go to stderr, per the CLI contract. */
    private val stderr: (String) -> Unit = { System.err.println(it) },
) {
    private val spool = SpoolWriter(stateRoot)
    private val cursorsDir = File(stateRoot, "cursors")
    private val verdictsDir = File(stateRoot, "verdicts")
    private val cache = LlmVerdictCache(File(stateRoot, "llm-verdict-cache.ndjson"))

    init {
        cursorsDir.mkdirs()
        verdictsDir.mkdirs()
    }

    fun readCursor(agent: String): Long =
        File(cursorsDir, "$agent.verdict").takeIf { it.isFile }
            ?.readText()?.trim()?.toLongOrNull() ?: 0L

    private fun cursorFile(agent: String) = File(cursorsDir, "$agent.verdict")

    private fun writeCursor(agent: String, seq: Long) {
        Files.writeString(cursorFile(agent).toPath(), seq.toString() + "\n")
    }

    /** (seq, agent) pairs already logged; rebuilt from the verdict files
     * so a cursor lagging behind a fsynced verdict is idempotent. */
    internal fun loadSeenVerdicts(): MutableSet<String> {
        val seen = mutableSetOf<String>()
        val files = verdictsDir.listFiles()
            ?.filter { it.isFile && it.name.endsWith(".ndjson") }
            ?.sortedBy { it.name } ?: emptyList()
        for (file in files) {
            file.useLines { lines ->
                for (line in lines) {
                    if (line.isBlank()) continue
                    runCatching {
                        VerdictJson.decodeFromString(VerdictLogLine.serializer(), line)
                    }.getOrNull()?.let { seen.add("${it.seq}:${it.agent}") }
                }
            }
        }
        return seen
    }

    private fun appendVerdict(line: VerdictLogLine) {
        val day = now().toLocalDate().toString()
        val target = File(verdictsDir, "$day.ndjson")
        FileOutputStream(target, true).use { out ->
            out.write((VerdictJson.encodeToString(VerdictLogLine.serializer(), line) + "\n").toByteArray(Charsets.UTF_8))
            out.flush()
            out.fd.sync()
        }
    }

    private fun isStale(eventTs: String): Boolean = runCatching {
        OffsetDateTime.parse(eventTs).toInstant()
            .isBefore(now().toInstant().minus(java.time.Duration.ofDays(staleHorizonDays.toLong())))
    }.getOrDefault(false)

    suspend fun drain(): DrainOutcome {
        // Global FIFO oldest-first, grouped by file: groups ordered by
        // their lowest seq, events within a group by seq. Grouping breaks
        // strict seq order, so the cursor is NOT a highwater: it is
        // recomputed as the contiguous run of fsynced verdicts beyond it —
        // the cursor means classified OR deliberately skipped (a fresh
        // agent's head-init deliberately skips history), so the contiguous
        // run starts at the cursor, never at 1, and never regresses.
        val ordered = spool.readEvents(log)
            .groupBy { it.file }
            .values
            .sortedBy { group -> group.minOf { it.seq } }
            .flatMap { group -> group.sortedBy { it.seq } }
        val seen = loadSeenVerdicts()
        val selected = when (val name = onlyAgent) {
            null -> configs.sortedBy { it.agent }
            else -> configs.filter { it.agent == name }
        }
        val results = mutableListOf<DrainAgentOutcome>()
        var reason: String? = null
        outer@ for (config in selected) {
            var prior = readCursor(config.agent)
            val absent = !cursorFile(config.agent).isFile
            if (absent && fromSeq == null) {
                // Fresh agent config: no history classification. The
                // cursor jumps to the spool head; notice to stderr.
                val head = spool.currentSeq()
                writeCursor(config.agent, head)
                stderr(
                    "harness drain: ${config.agent}: no cursor file; " +
                        "initialized cursor at spool head seq=$head " +
                        "(history not classified; use --from-seq N to replay)"
                )
                prior = head
            }
            var processed = 0
            var llmCalls = 0
            var stopped: String? = null
            for (event in ordered) {
                if (fromSeq != null) {
                    // Deliberate replay window: this run selects from
                    // N regardless of the cursor (seen-set still dedupes).
                    if (event.seq < fromSeq) continue
                } else if (event.seq <= prior) {
                    continue
                }
                val seenKey = "${event.seq}:${config.agent}"
                if (seenKey in seen) {
                    // fsynced earlier: re-log nothing, re-classify nothing.
                    continue
                }
                // Stale horizon BEFORE endpoint availability: ancient
                // events auto-verdict inert even during an outage, with
                // zero LLM calls and no cache reads or writes.
                if (isStale(event.ts)) {
                    appendVerdict(
                        staleVerdictLine(event.seq, config.agent, isoNow())
                    )
                    seen.add(seenKey)
                    processed++
                    continue
                }
                if (classifier == null) {
                    stopped = "no classifier endpoint configured"
                    break
                }
                if (maxEventsPerAgent in 1..llmCalls) {
                    // Budget exhausted for this agent: the backlog stays
                    // visible as lag in status. Next agent's own budget.
                    break
                }
                val text = spoolEventClassificationText(event)
                val ts = isoNow()
                val contentHash = HashUtils.sha256(text)
                // The -pge3 variant pins the ACT statistic: P(>=3) tail.
                // Old EV-keyed entries (bare agent-NAME) must never feed
                // the tail gate, so the key bump retires them on sight.
                val cacheKey = "$contentHash|$model|agent-${config.agent}-pge3"
                // ONE call in flight: this loop is the only issuer.
                val confidence = (cache.lookupConf(cacheKey)
                    ?: when (val r = classifier.score(
                        text, "should_act", config.shouldAct, config.shouldActCriteria
                    )) {
                        is VerdictResult.Score -> r.probAtLeast3?.let { p ->
                            val c = clamp01(p)
                            cache.rememberConf(cacheKey, c, ts)
                            llmCalls++
                            c
                        } ?: run {
                            stopped = "classifier answer missing probability map"
                            null
                        }
                        is VerdictResult.Unavailable -> {
                            stopped = "classifier unavailable: ${r.reason}"
                            null
                        }
                    }) ?: break
                var urgency: Double? = null
                if (config.urgency) {
                    val urgencyKey = "$contentHash|$model|agent-${config.agent}-urgency"
                    urgency = cache.lookupConf(urgencyKey)
                        ?: when (val u = classifier.score(
                            text, "urgency", config.urgencyQuestion ?: "",
                            config.urgencyCriteria ?: emptyList()
                        )) {
                            is VerdictResult.Score -> {
                                val s = clamp01(u.score)
                                cache.rememberConf(urgencyKey, s, ts)
                                s
                            }
                            is VerdictResult.Unavailable -> {
                                stopped = "urgency classifier unavailable: ${u.reason}"
                                break
                            }
                        }
                }
                val verdict = if (confidence >= config.threshold) "yes" else "no"
                appendVerdict(
                    VerdictLogLine(
                        seq = event.seq, agent = config.agent,
                        verdict = verdict, confidence = JsonPrimitive(confidence),
                        model = model, ts = ts, urgency = urgency,
                    )
                )
                seen.add(seenKey)
                processed++
            }
            // Contiguous frontier recomputed from the seen set, starting
            // AT the cursor: the cursor means classified OR deliberately
            // skipped — a fresh agent head-inits by skipping history (no
            // verdict rows for 1..prior), so the contiguous run can only
            // start there. The cursor advances ONLY over fsynced verdicts
            // above the cursor and NEVER regresses from a prior head-init
            // or prior run. On a mid-loop abort the frontier still lands
            // over the un-skipped window: grouped order can fsync seq 35
            // before seq 4 — an unclassified 4 pins the frontier at 3;
            // stale rows already fsynced advance it normally, fresh-event
            // failures never do (their rows are never fsynced).
            val agentSeqs = sortedSetOf<Long>()
            for (key in seen) {
                val parts = key.split(":", limit = 2)
                if (parts.size == 2 && parts[1] == config.agent) {
                    parts[0].toLongOrNull()?.let { agentSeqs.add(it) }
                }
            }
            var frontier = prior
            while (frontier + 1L in agentSeqs) frontier++
            val newCursor = maxOf(prior, frontier)
            if (newCursor > readCursor(config.agent)) {
                writeCursor(config.agent, newCursor)
            }
            results.add(DrainAgentOutcome(config.agent, processed, newCursor))
            if (stopped != null) {
                reason = stopped
                break@outer
            }
        }
        return DrainOutcome(results, failed = reason != null, reason = reason)
    }

    private fun isoNow(): String = DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now())
}

internal fun spoolEventClassificationText(event: SpoolEvent): String =
    classificationText(event.title, event.todo, event.body)
kotlin#+name: harness-drain-imports
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.utils.HashUtils
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonPrimitive
import java.io.File
import java.io.FileOutputStream
import java.nio.file.Files
import java.time.OffsetDateTime
import java.time.format.DateTimeFormatter
kotlin#+name: harness-drain-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessDrain.kt:noweb yes
<<harness-drain-imports>>

<<harness-drain-json>>

<<harness-drain-engine>>

Dispatcher

The wake dispatcher (P2)

Classification contract per agent is unchanged and the dispatcher issues zero LLM calls of its own: it reads the fsynced verdict log the drain already produced, joins each yes row back to its spool event by seq, and spawns one fire-and-forget hermes session per wake. Everything else is deterministic plain-file bookkeeping over the caps, the wake window, the lease gate, and the audit file:

  • Selection: per agent, yes verdict rows with numeric confidence > THRESHOLD= (same rule as the drain — the drain only ever wrote yes above threshold, the re-check is defensive) with seq above cursors/AGENT.dispatch. Rows are grouped per agent; the drain writes them grouped-by-file, so dispatch requires seq contiguity before acting: the cursor may only pass seqs that have any verdict row, exactly like the drain's own frontier (*The verdicts-only drain (P1)). A budget-stopped partial drain batch leaves a hole, and the hole pins the dispatcher — no lost, out-of-order, or doubly-counted wakes, no matter how interleaved the two timers run.

  • Lanes: urgent iff the verdict row carries urgency > 0.75= (a plain constant, not a knob) and the agent enables the URGENCY rubric; everything else is regular. The two daily budgets are independent: urgent wakes never consume the regular budget and vice versa. This is the overnight lane — an agent on a waking schedule drains urgent wakes at night while regular wakes still stop at MAX_WAKES.

  • Caps and spacing (per-agent knobs in CLASSIFIER.org, defaults 3 1 60): daily budgets count spawn attempts (a failed systemd-run counts — a broken CLI must not thrash retries) and are read back from the daily audit file, so a restarted dispatcher can never double-wake past them; MIN_WAKE_INTERVAL spaces any lane's spawns per agent by wall-clock age read from the audit trail, 0 disables it.

  • One wake in flight per agent, absolute: the dispatcher skips an agent whose AGENT.lease is live ([Locks & leases]) before looking at a single candidate — nothing consumed, nothing advanced. The B3 run-protocol contract is that the woken session acquires its lease first and releases it last; that instruction is baked into every briefing. - Window: --wake-window HH:MM-HH:MM on harness dispatch (default 07:00-22:00 system-local; empty flag = always open; start > end wraps midnight for an overnight lane). Outside the window pending yeses are HELD — audited, not spawned, cursor frozen below them — and flush automatically when the window reopens. Per-agent windows are expressed by the hm module giving each agent its own dispatch unit (*Service units (user)). Under cron the schedule IS the window — the =/5= cron line spaces the gate ticks, so deployed cron gate scripts may omit the flag entirely; the flag remains for the systemd path, whose deployed timers (the hm module below) keep it byte-identical.

  • Briefing (not JSON): each wake writes a natural-language markdown briefing to wakes/<agent>-<seq>.md — what happened (lane, confidence, urgency), the event with title, verbatim body unless risk-gated, node id and outline key, the exact retrieval recipe (=journal user get "/ search"=-based; enumeration-independent), the task framing (charter/AGENTS.md + results written with the session's own journal capture), the lease run protocol, and the hard rules: journal text and attachments are local-only and a failed tool is reported-and-exited, never worked around. The woken session reads it via hermes --query-file; the unit's --source wake tag keeps wake sessions visible (and filterable) in the hermes listing clients, which otherwise hide =oneshot=-sourced sessions.

  • D5 gating: an event with risk.gated may never hand a body to anything remote. All spawned wakes run local hermes profiles anyway, but the stub-body rule stands: the briefing carries title/scope/file/id only, never body, and — gate semantics — prints no retrieval recipe: it says the entry is risk-gated, assess from the title, and if the task needs the body, capture that it is blocked, release the lease, and exit. The wake still fires.

  • Audit: one JSON line per wake attempt to <state>/wakes/YYYY-MM-DD.ndjson (combined per day, the verdict-file precedent): agent, seq, unit, spawnExit, dryRun, lane, reason, gated, ts + payload briefing path on spawns. Reasons: held | cap | interval | lease | event-missing. Briefing and audit files are kept (audit trail) and aged out after 30 days by systemd tmpfiles rules in the deployment module — the dispatcher never deletes anything.

Bootstrap, replay, and the dispatch cursor

cursors/AGENT.dispatch is one integer, the last seq whose wake-decision is resolved. A fresh agent config (no file) head-inits at the spool head with one stderr notice — the *Bootstrap & replay policy mirror: history is never implicitly woken. Deliberate replay is the sanctioned manual knob, deliberately not a CLI flag (replay here costs no LLM spend, only capped wakes):

  • Delete the file → next tick re-head-inits at the spool head, nothing re-woken.

  • Rewrite it to a seq N → everything with an fsynced yes above N wakes on the following ticks, bounded by the per-agent lane budgets (an overnight backlog flushes at MAX_WAKES per day, exactly as designed).

The cursor advance is atomic (tmp + fsync + rename-into-place) and follows one rule for every run shape: pending candidates stay above it, so held/capped/interval/lease-blocked candidates flush on a later tick; with nothing pending it passes the whole contiguous classified frontier — every seq there is either spawned (this run or recorded in the audit trail), permanently inert (=no=/stale/sub-threshold), or deduped-spawned.

The run loop

Per tick and per wake-enabled agent: probe drain.lock first (busy ⇒ skip the whole run, exit 0 — never read a mid-drain partial verdict batch); hold dispatch.lock for the entire run (busy ⇒ skip cleanly, exit 0 — two racing dispatch instances could both read "not yet woken" before either spawned, and the audit read-back cannot save a true simultaneous race); then per agent: head-init or cursor read; select candidates from the contiguous frontier; dedupe already-spawned seqs against the audit trail; process newest-first; audit every examined candidate; advance the cursor by the one rule above. Dry runs audit =dryRun=true= rows, write no briefing, consume no budget, and advance nothing.

Gate mode: the cron-facing waking surface

--gate is the dispatcher's consume-without-spawn mode — the cron-facing waking surface. Systemd-timer wake-spawns proved silent-killer-shaped: headless hermes chat --oneshot clients land in journald where no human surface looks, and an argv-vs-gateway build skew (2026-11-15: every spawn died exit 1 with "Gateway does not support source 'wake'" while spawnExit stayed 0) hides for hours. Hermes cron jobs, by contrast, run inside the gateway with platform delivery and hermes cron runs observability. So the fix shape inverts ownership: the systemd producer and drain stay untouched, the dispatcher keeps all waking authority, and a cron agent run IS the wake — the tick spawns nothing and instead prints a wake line that the cron deliverable consumes by doing the work itself.

Concretely: harness dispatch --state-dir … --agent NAME --gate runs today's whole run through the gate ladder — cursor bootstrap, candidate selection, cap/interval/lease/window — and only the winning branch changes: no systemd-run (no hermes, no subprocess of any kind), while the briefing is written exactly as a spawn would and the audit row is the spawn-shaped row with =spawnExit=null= and the new =gate=true=. The lane budget and the MIN_WAKE_INTERVAL clock consume as if spawned (one gate delivery per cron run, the remainder auditing interval, matching the systemd-run cadence), and the cursor rule treats the delivery as spawned. Nothing new to learn about restarts or replay: the audit file remains the ledger, so a restarted dispatcher dedupes gate rows, the caps still bound a day, and a gate row that somehow failed to consume would be the bug that wakes forever (the tests pin all three read-backs). The lease protocol is unchanged too: the briefing's run-protocol instructs the cron agent session to acquire the agent lease first and release it last — one wake in flight stays absolute even though nothing was spawned.

The stdout contract is the hermes cron script protocol (wake lines on stdout wake the agent; empty stdout does not skip, so silence must be explicit): a delivery prints exactly one line <seq>\t<briefing-path> (the absolute path, because the gateway daemon's cwd is not the dispatcher's), every quiet path — no candidates, live lease, window closed, interval, cap, =drain.lock=/=dispatch.lock= skip — prints exactly {"wakeAgent": false}, and both exit 0. Every cannot-decide path (unreadable state dir, missing or malformed agent config, malformed --wake-window, --gate without an explicit --agent, or --gate beside --dry-run) fails the run nonzero on stderr — a swallowed error must surface as a failed cron run, never as silence. Engine notices ride stderr in gate mode so stdout stays protocol-only.

kotlin#+name: harness-wake-imports
package computer.whatthefuck.arcology.harness

import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.JsonPrimitive
import kotlinx.serialization.json.doubleOrNull
import java.io.File
import java.io.FileOutputStream
import java.nio.file.Files
import java.nio.file.StandardCopyOption
import java.time.Duration
import java.time.LocalTime
import java.time.OffsetDateTime
import java.time.format.DateTimeFormatter
kotlin#+name: harness-wake-types
/** Wake-knob defaults: per-agent, editable in CLASSIFIER.org's property
 * drawer alongside THRESHOLD; these are only the fallbacks. */
internal const val WAKE_DEFAULT_MAX_WAKES = 3
internal const val WAKE_DEFAULT_MAX_URGENT_WAKES = 1
internal const val WAKE_DEFAULT_MIN_WAKE_INTERVAL_MINUTES = 60L

/** The urgent lane gate on a verdict row's urgency score. A plain
 * constant by settled design, not a CLASSIFIER.org knob. */
internal const val WAKE_URGENT_LANE_MIN_URGENCY = 0.75

/**
 * Wake opt-in and knobs, parsed from the same CLASSIFIER.org property
 * drawer as THRESHOLD/URGENCY ([[*CLASSIFIER.org configuration schema]]).
 * =WAKE= absent, =no=, or garbage is [Off] — fail-shut, no waking; a
 * present-but-unparseable knob under =WAKE: yes= is [Malformed] — the
 * dispatcher skips that agent entirely (one stderr notice) while the
 * drain keeps working.
 */
sealed interface WakePolicy {
    object Off : WakePolicy
    data class Malformed(val reason: String) : WakePolicy
    data class On(
        /** Regular wakes per local day. */
        val maxWakes: Int = WAKE_DEFAULT_MAX_WAKES,
        /** Separate daily budget for urgent wakes. */
        val maxUrgentWakes: Int = WAKE_DEFAULT_MAX_URGENT_WAKES,
        /** Minimum spacing between spawns for one agent; 0 = off. */
        val minWakeIntervalMinutes: Long = WAKE_DEFAULT_MIN_WAKE_INTERVAL_MINUTES,
    ) : WakePolicy
}

/** One wake candidate: a fsynced =yes= verdict row above the dispatch
 * cursor, with its numeric confidence and urgency. */
internal data class WakeCandidate(
    val seq: Long,
    val confidence: Double,
    val urgency: Double? = null,
)

/** Selection result: the contiguous classified frontier (the largest
 * seq ≤ which every seq has any verdict row — the drain's own frontier
 * discipline) and the wake candidates inside it, newest-first, minus
 * already-spawned seqs. */
internal data class WakeSelection(val frontier: Long, val candidates: List<WakeCandidate>)

/** "HH:MM-HH:MM" window in the system-local clock; null/empty parse =
 * always open. start > end wraps midnight: an overnight lane's wake
 * window stays open across the date line. Bounds are closed. */
data class WakeWindow(val start: LocalTime, val end: LocalTime) {
    fun contains(time: LocalTime): Boolean =
        if (!start.isAfter(end)) !time.isBefore(start) && !time.isAfter(end)
        else !time.isBefore(start) || !time.isAfter(end)

    companion object {
        const val DEFAULT = "07:00-22:00"

        /** null/empty = always open (null return); throws on garbage. */
        fun parse(raw: String?): WakeWindow? {
            if (raw.isNullOrEmpty()) return null
            val parts = raw.split("-", limit = 2)
            return WakeWindow(LocalTime.parse(parts[0].trim()), LocalTime.parse(parts[1].trim()))
        }
    }
}

/** Injectable spawn executor: tests record argv instead of touching
 * systemd-run. [env] merges into the child's environment; the operative
 * HERMES_HOME still rides argv because systemd-run strips the caller's
 * environment. */
fun interface CommandRunner {
    fun run(argv: List<String>, env: Map<String, String>): Int
}

object SystemCommandRunner : CommandRunner {
    override fun run(argv: List<String>, env: Map<String, String>): Int = try {
        val builder = ProcessBuilder(argv).inheritIO()
        builder.environment().putAll(env)
        builder.start().waitFor()
    } catch (e: Exception) {
        -1
    }
}

/** Wake files' JSON — audit NDJSON lines only: defaults encoded so
 * lines stay self-describing, explicit nulls omitted (no =reason=/=payload=
 * keys on rows that lack them). Wake payloads are markdown briefings
 * now ([wakeBriefing]); the gated one prints no body by construction. */
internal val WakeJson = Json {
    ignoreUnknownKeys = true
    encodeDefaults = true
    explicitNulls = false
}

/**
 * The in-memory wake record, rendered by [wakeBriefing] into the
 * briefing file =<state>/wakes/<agent>-<seq>.md= that the woken session
 * reads via hermes =--query-file=. The file is kept (audit trail) and
 * aged out after 30 days by tmpfiles. [instruction] carries the
 * run-protocol: acquire the agent lease first, do the work, release the
 * lease last — B3 etiquette, one wake in flight per agent.
 */
data class WakePayload(
    val agent: String,
    val seq: Long,
    /** The event's ISO8601-with-offset ts from the spool. */
    val ts: String,
    val scope: String,
    /** Tree-relative org path. */
    val file: String,
    val action: String,
    val title: String,
    val confidence: Double,
    val urgency: Double? = null,
    /** "regular" | "urgent". */
    val lane: String,
    /** risk.gated: title/scope/id stub only — never a body, and no
     * retrieval recipe (D5). */
    val gated: Boolean,
    /** The event's body from the spool; null when [gated]. */
    val body: String? = null,
    /** The heading's org-roam id, or null when the event has none. */
    val orgId: String? = null,
    /** The derived org-roam key =file::outline-path=. */
    val key: String? = null,
    val instruction: String,
)

/**
 * One wake ATTEMPT per JSON line, at
 * =<state>/wakes/YYYY-MM-DD.ndjson= (combined per day, the verdict-file
 * precedent). [reason] is null on a spawn attempt; otherwise one of
 * held | cap | interval | lease | event-missing. Dry-run rows carry
 * dryRun=true and no exit code and never consume a budget. Gate rows
 * ([gate]) carry the same spawn-shaped null [spawnExit] and reason —
 * the cron run that printed the wake line IS the attempt; the default
 * =false= keeps every historical row's wire shape and decode.
 */
@Serializable
data class WakeAuditLine(
    val agent: String,
    val seq: Long,
    /** The transient systemd unit name this candidate would use. */
    val unit: String,
    /** systemd-run exit code; null when nothing spawned (or in gate
     * mode, where no spawn is attempted at all yet delivery consumed). */
    val spawnExit: Int? = null,
    val dryRun: Boolean,
    /** "regular" | "urgent" — every row carries its lane. */
    val lane: String,
    val reason: String? = null,
    /** The event's risk.gated — the payload was (or would be) a stub. */
    val gated: Boolean,
    val ts: String,
    /** Briefing file path actually written for a spawn (when the
     * candidate was risk-gated, the briefing carries no body). */
    val payload: String? = null,
    /** --gate delivery: consumed-without-spawn (the cron agent run is
     * the wake). Default false = every historical row decodes unchanged. */
    val gate: Boolean = false,
)
kotlin#+name: harness-dispatch-engine
/**
 * Every verdict log row for [agent], day files in name order, indexed
 * by seq. All shapes matter (yes/no/stale): the frontier needs row
 * existence, not just candidates. Later rows win per seq in practice —
 * the drain never re-logs.
 */
internal fun loadVerdictRows(stateRoot: File, agent: String): Map<Long, VerdictLogLine> {
    val out = mutableMapOf<Long, VerdictLogLine>()
    val files = File(stateRoot, "verdicts").listFiles()
        ?.filter { it.isFile && it.name.endsWith(".ndjson") }
        ?.sortedBy { it.name } ?: emptyList()
    for (file in files) {
        file.useLines { lines ->
            for (line in lines) {
                if (line.isBlank()) continue
                val row = runCatching {
                    VerdictJson.decodeFromString(VerdictLogLine.serializer(), line)
                }.getOrNull() ?: continue
                if (row.agent != agent) continue
                out[row.seq] = row
            }
        }
    }
    return out
}

/** One-integer dispatch cursor; null = no file (fresh agent: the
 * head-init-with-notice bootstrap, and the sanctioned manual knob for
 * deliberate replay — delete to re-head-init, rewrite to a seq to wake
 * the fsynced yeses above it). */
internal fun readDispatchCursor(stateRoot: File, agent: String): Long? {
    val file = File(stateRoot, "cursors/$agent.dispatch")
    if (!file.isFile) return null
    return file.readText().trim().toLongOrNull() ?: 0L
}

/** Atomic cursor advance: tmp + fsync + rename-into-place, so a crash
 * lands the cursor before or after the wake batch, never mid-file. */
internal fun writeDispatchCursor(stateRoot: File, agent: String, seq: Long) {
    val dir = File(stateRoot, "cursors")
    dir.mkdirs()
    val tmp = File(dir, "$agent.dispatch.tmp")
    FileOutputStream(tmp).use { out ->
        out.write((seq.toString() + "\n").toByteArray(Charsets.UTF_8))
        out.flush()
        out.fd.sync()
    }
    Files.move(tmp.toPath(), File(dir, "$agent.dispatch").toPath(), StandardCopyOption.ATOMIC_MOVE)
}

/** Seqs with a recorded spawn attempt (any prior day): the dedupe and
 * budget read-back that make a restarted dispatcher safe. Dry-run rows
 * never count; failed spawns DO (attempt = consumption); gate rows DO
 * (the cron run that printed the wake line IS the attempt). */
internal fun loadSpawnedSeqs(stateRoot: File, agent: String): Set<Long> {
    val out = mutableSetOf<Long>()
    val files = File(stateRoot, "wakes").listFiles()
        ?.filter { it.isFile && it.name.endsWith(".ndjson") }
        ?.sortedBy { it.name } ?: emptyList()
    for (file in files) {
        file.useLines { lines ->
            for (line in lines) {
                if (line.isBlank()) continue
                val row = runCatching {
                    WakeJson.decodeFromString(WakeAuditLine.serializer(), line)
                }.getOrNull() ?: continue
                if (row.agent == agent && !row.dryRun &&
                    (row.spawnExit != null || row.gate)
                ) out.add(row.seq)
            }
        }
    }
    return out
}

internal fun wakeAuditFile(stateRoot: File, day: String): File =
    File(stateRoot, "wakes/$day.ndjson")

private fun decodeAudit(line: String): WakeAuditLine? = runCatching {
    WakeJson.decodeFromString(WakeAuditLine.serializer(), line)
}.getOrNull()

/** Spawned attempts today for agent+lane: the per-lane budget read-back
 * that survives dispatcher restarts. Spawns AND gate deliveries count —
 * a gate row that failed to consume the lane's budget is exactly the
 * bug that would wake forever; the audit file is the ledger. */
internal fun wakesSpawnedToday(
    stateRoot: File,
    agent: String,
    lane: String,
    nowTs: OffsetDateTime,
): Int {
    val file = wakeAuditFile(stateRoot, nowTs.toLocalDate().toString())
    if (!file.isFile) return 0
    var count = 0
    file.useLines { lines ->
        for (line in lines) {
            val row = decodeAudit(line) ?: continue
            if (row.agent == agent && row.lane == lane && !row.dryRun &&
                (row.spawnExit != null || row.gate)
            ) count++
        }
    }
    return count
}

/** Most recent spawn-attempt ts for the agent (any lane, any day): the
 * MIN_WAKE_INTERVAL read-back. Gate deliveries advance this clock like
 * a spawn — one cron deliverable per tick spaces exactly like
 * systemd-run did. */
internal fun lastSpawnAt(stateRoot: File, agent: String): OffsetDateTime? {
    var last: OffsetDateTime? = null
    val files = File(stateRoot, "wakes").listFiles()
        ?.filter { it.isFile && it.name.endsWith(".ndjson") }
        ?.sortedBy { it.name } ?: emptyList()
    for (file in files) {
        file.useLines { lines ->
            for (line in lines) {
                val row = decodeAudit(line) ?: continue
                if (row.agent != agent || row.dryRun ||
                    (row.spawnExit == null && !row.gate)
                ) continue
                val ts = runCatching { OffsetDateTime.parse(row.ts) }.getOrNull() ?: continue
                if (last == null || ts.toInstant().isAfter(last!!.toInstant())) last = ts
            }
        }
    }
    return last
}

/** The agent's wake selection: yes rows above [cursor] up to the
 * contiguous classified frontier, newest-first, minus already-spawned
 * seqs, and (when [threshold] is non-null) a defensive re-check of the
 * agent's THRESHOLD — the drain already applied it when writing =yes=.
 * Shared with the status collector so "held" means exactly the same
 * thing on both surfaces. */
internal fun selectWakeCandidates(
    stateRoot: File,
    agent: String,
    cursor: Long,
    threshold: Double?,
): WakeSelection {
    val rows = loadVerdictRows(stateRoot, agent)
    var frontier = cursor
    while (rows.containsKey(frontier + 1)) frontier++
    if (frontier <= cursor) return WakeSelection(cursor, emptyList())
    val spawned = loadSpawnedSeqs(stateRoot, agent)
    val candidates = mutableListOf<WakeCandidate>()
    for (seq in frontier downTo cursor + 1) { // newest-first
        val row = rows[seq] ?: continue
        if (row.verdict != "yes") continue
        val confidence = (row.confidence as? kotlinx.serialization.json.JsonPrimitive)?.doubleOrNull
            ?: continue
        if (threshold != null && confidence < threshold) continue
        if (seq in spawned) continue
        candidates.add(WakeCandidate(seq, confidence, row.urgency))
    }
    return WakeSelection(frontier, candidates)
}

/** The urgent lane gate: verdict-row urgency at or above the constant,
 * only for an agent whose CLASSIFIER.org enables the urgency rubric. */
internal fun wakeLaneOf(config: AgentClassifierConfig, candidate: WakeCandidate): String =
    if (config.urgency && candidate.urgency != null &&
        candidate.urgency >= WAKE_URGENT_LANE_MIN_URGENCY
    ) "urgent" else "regular"

internal fun wakeIntervalBlocked(
    policy: WakePolicy.On,
    lastSpawn: OffsetDateTime?,
    nowTs: OffsetDateTime,
): Boolean {
    if (policy.minWakeIntervalMinutes <= 0L) return false
    val last = lastSpawn ?: return false
    val age = Duration.between(last.toInstant(), nowTs.toInstant())
    return age.toMinutes() < policy.minWakeIntervalMinutes
}

/** B3 run-protocol instruction baked into every wake briefing: the
 * woken session acquires the agent lease first, does the work, releases
 * the lease last. */
internal fun wakeInstruction(agent: String): String =
    "Run protocol: before doing any work, run `arcology2 harness lease acquire --agent $agent` " +
        "(it refuses while a lease is live); do exactly the work this wake describes; " +
        "when done, run `arcology2 harness lease release --agent $agent` — acquire first, release last."

/**
 * The verified spawn recipe (2026-11-12): user-level transient unit
 * named per seq, =--collect= so a failed unit's logs stay attached;
 * HERMES_HOME rides argv through =env= because systemd-run strips the
 * caller's environment; one hermes chat per wake, oneshot, stream-json,
 * session-id passthrough, 30 turns. No =--run-budget=: the gateway
 * CLI mode rejects it outright (2026-11-14 wake failures, exit 2
 * "Unsupported gateway CLI options"); the wall-clock budget belongs
 * in =agent.run_budget_seconds= in each profile's config.yaml.
 * =--source wake= tags the transient unit so wake sessions stay
 * visible in the hermes listing clients (source =oneshot= sits in the
 * clients' internal-listing hide set; =wake= does not); =--oneshot=
 * stays. Fire-and-forget: dispatch waits only for systemd-run to queue
 * the unit, never for the session to finish.
 */
internal fun wakeSpawnArgv(
    agent: String,
    seq: Long,
    payloadFile: File,
    hermesProfilesDir: File,
): List<String> = listOf(
    "systemd-run", "--user", "--unit=arcology-wake-$agent-$seq", "--collect",
    "env", "HERMES_HOME=${File(hermesProfilesDir, agent).path}",
    "hermes", "chat",
    "--query-file", payloadFile.path,
    "--oneshot", "--source", "wake",
    "--format", "stream-json", "--pass-session-id",
    "--max-turns", "30",
)

data class DispatchAgentOutcome(
    val agent: String,
    val spawnedRegular: Int,
    val spawnedUrgent: Int,
    val held: Int,
    val capped: Int,
    val interval: Int,
    val leaseSkipped: Int,
    val eventMissing: Int,
    val cursor: Long,
    /** --gate mode only: deliveries in order (newest-first by
     * construction, exactly one whenever MIN_WAKE_INTERVAL spaces the
     * ticks). The CLI renders one cron wake line each; these carry no
     * spawned-count change — the pinned summary renderer is identical
     * in both modes. */
    val gateWinners: List<GateDelivery> = emptyList(),
)

/**
 * One --gate delivery: the winning seq, and the ABSOLUTE path of the
 * briefing file the cron agent reads. The cron script's stdout line is
 * "seq<TAB>briefing-path"; the path is absolute because the gateway
 * daemon's cwd is not the dispatcher's.
 */
data class GateDelivery(val seq: Long, val briefingPath: String)

data class DispatchOutcome(
    val agents: List<DispatchAgentOutcome>,
    /** true when the run skipped cleanly on a held lock (exit 0). */
    val busy: Boolean = false,
)

/**
 * Deterministic wake decisions over fsynced verdicts — zero LLM calls
 * of its own: the verdicts were already classified and fsynced by the
 * drain, so dispatch is pure plain-file bookkeeping plus one
 * fire-and-forget spawn per wake. Per agent it walks its yes-verdicts
 * newest-first against the agent's [[WakePolicy]] knobs, the wake
 * window, the one-wake-in-flight [[LeaseStore]] gate, and lane budgets
 * read back from the daily audit file, so a restarted dispatcher can
 * never double-wake past the caps. Bootstrap & replay policy
 * ([[*Bootstrap & replay policy]]): a fresh agent head-inits its
 * dispatch cursor at the spool head with one stderr notice; deliberate
 * replay is the sanctioned manual knob (delete or rewrite the cursor
 * file), never a CLI flag.
 *
 * Locks are engine-level, like the drain's: while =drain.lock= is held
 * the run skips cleanly (exit 0, nothing read, nothing written — never
 * a mid-drain partial verdict batch), and =dispatch.lock= (held for the
 * whole run) serializes concurrent dispatch instances.
 *
 * With [gate] set the same ladder runs for a cron gate script — the
 * cron agent run IS the wake (systemd-run and hermes are never called
 * from the dispatcher; the briefing's lease run-protocol is unchanged):
 * the winner is reported to the CLI, which prints one
 * =seq<TAB>briefing-path= wake line per delivery. Consumption is
 * identical to a spawn (audit row, lane budget, interval clock, cursor
 * rule) so a restarted dispatcher dedupes it and the caps hold; see
 * [[*Gate mode: the cron-facing waking surface]].
 *
 * GPU discipline: there is no inference here by construction — no
 * HttpClient, no classifier, no cache touches.
 */
class HarnessDispatch(
    private val stateRoot: File,
    private val configs: List<AgentClassifierConfig>,
    /** Process exactly one agent's config (other cursors untouched). */
    private val onlyAgent: String? = null,
    /** Decide and audit, spawn nothing, consume and advance nothing. */
    private val dryRun: Boolean = false,
    /** --gate mode: the run walks the whole gate ladder identically, but
     * the winning branch makes NO commandRunner call — the cron agent
     * run that receives the wake line IS the wake. The briefing is
     * written exactly as a spawn would, the audit row is the
     * spawn-shaped row with =spawnExit=null= and =gate=true=, the
     * interval clock and the lane budget consume as if spawned, and the
     * winners ride [DispatchAgentOutcome.gateWinners] to the CLI's
     * stdout contract. */
    private val gate: Boolean = false,
    /** null = always open; the CLI's empty --wake-window parses to null. */
    private val wakeWindow: WakeWindow? = null,
    private val hermesProfilesDir: File = File(System.getProperty("user.home"), "hermes/profiles"),
    private val commandRunner: CommandRunner = SystemCommandRunner,
    private val procRoot: String = "/proc",
    private val now: () -> OffsetDateTime = { OffsetDateTime.now() },
    private val log: (String) -> Unit = { println(it) },
    private val stderr: (String) -> Unit = { System.err.println(it) },
) {
    /** Lazy: a lock-busy skip must not even scan the spool. */
    private val spool: SpoolWriter by lazy { SpoolWriter(stateRoot) }
    private val locks = HarnessLocks(stateRoot)
    private val leaseStore = LeaseStore(stateRoot, procRoot = procRoot, now = now)

    private fun cursorFile(agent: String) = File(stateRoot, "cursors/$agent.dispatch")

    fun dispatch(): DispatchOutcome {
        // Skip cleanly while the drain holds its lock: never wake from a
        // mid-drain partial verdict batch.
        if (locks.isLocked("drain.lock")) {
            log("harness dispatch: drain.lock held; skipping (nothing read, nothing consumed)")
            return DispatchOutcome(emptyList(), busy = true)
        }
        // One dispatcher at a time, across default and per-agent units:
        // audit read-back is per-process-read, and two racing
        // dispatchers could both see "not yet woken" before either
        // spawned.
        val lock = locks.tryAcquire("dispatch.lock")
            ?: run {
                log("harness dispatch: dispatch.lock held by another run; skipping")
                return DispatchOutcome(emptyList(), busy = true)
            }
        try {
            val selected = when (val name = onlyAgent) {
                null -> configs.sortedBy { it.agent }
                else -> configs.filter { it.agent == name }
            }
            val results = mutableListOf<DispatchAgentOutcome>()
            for (config in selected) {
                when (val policy = config.wake) {
                    is WakePolicy.Off -> {} // opt-in off: never dispatched
                    is WakePolicy.Malformed -> stderr(
                        "harness dispatch: ${config.agent}: unusable wake policy " +
                            "(${policy.reason}); agent skipped, nothing consumed"
                    )
                    is WakePolicy.On -> results.add(dispatchAgent(config, policy))
                }
            }
            return DispatchOutcome(results)
        } finally {
            lock.close()
        }
    }

    private fun dispatchAgent(config: AgentClassifierConfig, policy: WakePolicy.On): DispatchAgentOutcome {
        val agent = config.agent
        val absent = readDispatchCursor(stateRoot, agent) == null
        if (absent) {
            // Fresh agent config: no history is ever implicitly woken.
            // The cursor jumps to the spool head; notice to stderr, and
            // nothing processes this run. Deliberate replay is manual:
            // delete this file to re-head-init, rewrite it to a seq to
            // wake the fsynced yeses above that seq (cap-bounded).
            val head = spool.currentSeq()
            writeDispatchCursor(stateRoot, agent, head)
            stderr(
                "harness dispatch: $agent: no cursor file; initialized dispatch " +
                    "cursor at spool head seq=$head (history not woken; delete or " +
                    "rewrite ${cursorFile(agent).path} for deliberate replay)"
            )
            return DispatchAgentOutcome(agent, 0, 0, 0, 0, 0, 0, 0, head)
        }
        val prior = readDispatchCursor(stateRoot, agent) ?: 0L
        val selection = selectWakeCandidates(stateRoot, agent, prior, config.threshold)
        val frontier = selection.frontier
        val candidates = selection.candidates
        if (candidates.isEmpty() && frontier == prior) {
            return DispatchAgentOutcome(agent, 0, 0, 0, 0, 0, 0, 0, prior)
        }
        // The payload join: month files across boundaries, markers and
        // torn lines skipped, producer growth tolerated.
        val events = if (candidates.isEmpty()) emptyMap()
        else spool.eventsSince(prior, log).associateBy { it.seq }
        val windowOpen = wakeWindow == null || wakeWindow!!.contains(now().toLocalTime())
        val leaseLive = leaseStore.live(agent) != null
        var lastSpawn: OffsetDateTime? = lastSpawnAt(stateRoot, agent)
        var spawnedRegular = 0
        var spawnedUrgent = 0
        var heldOut = 0
        var cappedOut = 0
        var intervalOut = 0
        var leaseOut = 0
        var missingOut = 0
        val gateWinners = mutableListOf<GateDelivery>()
        val pending = mutableListOf<Long>()
        for (candidate in candidates) { // newest-first
            // event==null means reason "event-missing", always pending
            // (fail-visible); hoist the check so the spawn path below
            // sees a non-null event.
            val event = events[candidate.seq]
            if (event == null) {
                missingOut++
                pending.add(candidate.seq)
                appendAudit(
                    WakeAuditLine(
                        agent, candidate.seq, "arcology-wake-$agent-${candidate.seq}",
                        null, dryRun, wakeLaneOf(config, candidate), "event-missing",
                        false, isoNow(),
                    )
                )
                continue
            }
            val lane = wakeLaneOf(config, candidate)
            val gated = event.risk.gated
            val unit = "arcology-wake-$agent-${candidate.seq}"
            val reason: String? = when {
                leaseLive -> "lease"             // one wake in flight, absolute
                !windowOpen -> "held"            // outside window: not spawned, not advanced
                wakeIntervalBlocked(policy, lastSpawn, now()) -> "interval"
                wakesSpawnedToday(stateRoot, agent, lane, now()) >=
                    (if (lane == "urgent") policy.maxUrgentWakes else policy.maxWakes) -> "cap"
                else -> null
            }
            if (reason != null) {
                when (reason) {
                    "lease" -> leaseOut++
                    "held" -> heldOut++
                    "interval" -> intervalOut++
                    else -> cappedOut++
                }
                pending.add(candidate.seq)
                appendAudit(
                    WakeAuditLine(
                        agent, candidate.seq, unit, null, dryRun, lane, reason, gated, isoNow(),
                    )
                )
                continue
            }
            val payload = WakePayload(
                agent = agent, seq = candidate.seq, ts = event.ts,
                scope = event.scope, file = event.file, action = event.action,
                title = event.title, confidence = candidate.confidence,
                urgency = candidate.urgency, lane = lane, gated = gated,
                // D5: a gated body may only reach a local-inference
                // runner. All spawned wakes run local hermes profiles,
                // but the stub-body rule stands anyway: gated means
                // never a body, and no retrieval recipe.
                body = if (gated) null else event.body,
                orgId = event.identity.orgId,
                key = event.identity.key,
                instruction = wakeInstruction(agent),
            )
            var spawnExit: Int? = null
            var payloadPath: String? = null
            var gateWon: GateDelivery? = null
            if (!dryRun) {
                val payloadFile = File(stateRoot, "wakes/$agent-${candidate.seq}.md")
                writeBriefing(payloadFile, payload)
                payloadPath = "wakes/$agent-${candidate.seq}.md"
                if (gate) {
                    // --gate: the cron agent run that receives this
                    // delivery IS the wake — no commandRunner call at
                    // all, the briefing is the exact same file a spawn
                    // would have written, and the ABSOLUTE path rides
                    // the stdout line (the gateway daemon's cwd is not
                    // the dispatcher's).
                    gateWon = GateDelivery(candidate.seq, payloadFile.absolutePath)
                } else {
                    spawnExit = commandRunner.run(
                        wakeSpawnArgv(agent, candidate.seq, payloadFile, hermesProfilesDir),
                        mapOf("HERMES_HOME" to File(hermesProfilesDir, agent).path),
                    )
                }
                // Attempt = consumption: a failed spawn counts against
                // today's lane budget so a broken CLI cannot thrash; a
                // gate delivery advances the interval clock identically
                // (at most one wake line per gate run — the remainder
                // audits as interval — matching systemd-run cadence).
                lastSpawn = now()
            }
            if (lane == "urgent") spawnedUrgent++ else spawnedRegular++
            appendAudit(
                WakeAuditLine(
                    agent, candidate.seq, unit, spawnExit, dryRun, lane, null, gated,
                    isoNow(), payload = payloadPath, gate = gateWon != null,
                )
            )
            gateWon?.let { gateWinners.add(it) }
        }
        if (dryRun) {
            // Preview consumed and advanced nothing (gate mode is
            // unreachable here: the CLI refuses the combination).
            return DispatchAgentOutcome(
                agent, spawnedRegular, spawnedUrgent, heldOut, cappedOut,
                intervalOut, leaseOut, missingOut, prior,
            )
        }
        // One cursor rule for every run shape: pending candidates stay
        // above the cursor (they flush on a later tick); with none
        // pending it passes the whole contiguous classified frontier —
        // every seq there is spawned (this run, or deduped from the
        // audit trail), permanently inert, or otherwise resolved. A
        // gate delivery counts as spawned: it consumed, so the cursor
        // may pass it.
        val minPending = pending.minOrNull()
        val newCursor = when {
            pending.isNotEmpty() -> maxOf(prior, minPending!! - 1)
            else -> maxOf(prior, frontier)
        }
        if (newCursor > prior) writeDispatchCursor(stateRoot, agent, newCursor)
        return DispatchAgentOutcome(
            agent, spawnedRegular, spawnedUrgent, heldOut, cappedOut,
            intervalOut, leaseOut, missingOut, newCursor, gateWinners,
        )
    }

    private fun appendAudit(line: WakeAuditLine) {
        val target = wakeAuditFile(stateRoot, now().toLocalDate().toString())
        target.parentFile?.mkdirs()
        FileOutputStream(target, true).use { out ->
            out.write(
                (WakeJson.encodeToString(WakeAuditLine.serializer(), line) + "\n")
                    .toByteArray(Charsets.UTF_8)
            )
            out.flush()
            out.fd.sync()
        }
    }

    private fun writeBriefing(target: File, payload: WakePayload) {
        target.parentFile?.mkdirs()
        FileOutputStream(target).use { out ->
            out.write(
                (wakeBriefing(payload) + "\n")
                    .toByteArray(Charsets.UTF_8)
            )
            out.flush()
            out.fd.sync()
        }
    }

    private fun isoNow(): String = DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now())
}

The briefing

The woken session gets a framed task, not a blob. The briefing is the only thing it reads before acting: what woke it (lane/confidence/urgency), the event with its title, verbatim body unless risk-gated, node id and outline key, the exact retrieval recipe, the task framing (charter + own capture), the lease run protocol, and the hard rules (local-only privacy; a failed tool is reported and exited, never worked around). Gated events get no recipe at all — a recipe would just fetch the withheld body.

kotlin#+name: harness-wake-briefing
/** The no-id search recipe's distinctive words: whitespace-split,
 * words of four chars or more, first three, single-spaced; the full
 * trimmed title when nothing qualifies. */
internal fun wakeSearchQuery(title: String): String {
    val words = title.trim().split(Regex("\\s+"))
        .filter { it.length >= 4 }
    return when {
        words.isEmpty() -> title.trim()
        else -> words.take(3).joinToString(" ")
    }
}

/**
 * The wake briefing: the natural-language markdown handed to the woken
 * session via hermes =--query-file=. Replaces the A3 raw-JSON payload —
 * a session needs framing (what happened, where the entry lives, the
 * task, the lease protocol, the guardrails) before it touches
 * anything. Three conditional shapes: the node id line (with or without
 * an :ID:), the entry body (verbatim / risk-gated withhold note /
 * title-only statement), and the retrieval recipe (id lookup / search /
 * nothing-at-all when risk-gated — a recipe would just fetch the
 * withheld body, so the gate says assess-from-title-and-exit instead).
 */
internal fun wakeBriefing(payload: WakePayload): String {
    val agent = payload.agent
    val urgencyText = payload.urgency?.let { "$it" } ?: "not scored"
    val nodeId = payload.orgId?.let { "`$it`" }
        ?: "none — this heading has no :ID:; do not search for one"
    val gateLine =
        if (payload.gated) "GATED — the entry body is withheld by the risk gate"
        else "open"
    val bodySection = when {
        payload.gated -> {
            "> Withheld by the risk gate. This event was classified above the\n" +
            "> privacy threshold when its spool line was produced, so the\n" +
            "> harness hands you the stub only; the body never leaves the\n" +
            "> tree. Do not attempt to reconstruct it or work around the gate."
        }
        payload.body.isNullOrBlank() ->
            "> The heading has no body; the title above is the whole entry."
        else -> payload.body.trim()
    }
    val retrievalSection = when {
        payload.gated ->
            "Not provided: this event is risk-gated; assess from the title " +
            "only, and if your task needs the body, capture that it is " +
            "blocked, release the lease, and exit."
        payload.orgId != null -> {
            "    cd ~/org/agents/$agent\n" +
            "    journal user get \"${payload.orgId}\""
        }
        else -> {
            "    cd ~/org/agents/$agent\n" +
            "    journal user search --query \"${wakeSearchQuery(payload.title)}\"\n" +
            "# then, with the id from the result:\n" +
            "    journal user get \"<id from result>\"\n" +
            "\n" +
            "    This heading has no :ID: — do not search for one."
        }
    }
    // trim(): the raw string opens with a newline (the content starts on
    // the source's own line); the trailing newline comes from
    // writeBriefing's fsynced line.
    return """
# Arcology wake: $agent — event seq ${payload.seq}

You are the `$agent` wake session, spawned by the Arcology harness
dispatcher. An entry in the org tree was classified for `$agent` and crossed
the wake threshold; you are the single hermes session spawned for it.

- Wake reason: `${payload.lane}` lane; confidence `${payload.confidence}` >= the agent's threshold; urgency `$urgencyText`

## The event

- File: `${payload.file}` (action `${payload.action}`, spool ts `${payload.ts}`)
- Outline key: `${payload.key}`
- Node id: $nodeId
- Risk gate: $gateLine

## Entry title

> ${payload.title.trim()}

## Entry body

$bodySection

## Retrieval recipe (exact syntax — do not guess CLI shapes)

$retrievalSection

## Task

Do what `AGENTS.md` and your charter prescribe for this entry, working from
the heading above (retrieved with the recipe if you need the live node).
Write your results with your own journal capture — do not rewrite the
woken entry.

## Run protocol

${payload.instruction}

## Hard rules

1. Journal text and attachments are LOCAL ONLY: never upload, attach,
   embed, or otherwise transmit journal text or media to a cloud or
   third-party endpoint. Everything you read stays inside your local
   context.
2. If a tool fails, do NOT work around it: no curl with base64 media
   to inference endpoints, no delegating images, no cloud aliases.
   Capture that the task is blocked, release the lease, and exit.
""".trim() + "\n"
}
kotlin#+name: harness-wake-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessDispatch.kt:noweb yes
<<harness-wake-imports>>

<<harness-wake-types>>

<<harness-dispatch-engine>>

<<harness-wake-briefing>>

CLASSIFIER.org configuration schema

Per-agent config lives at <agents-dir>/<agent-name>/CLASSIFIER.org (the brief's settled D3: thresholds live per-agent in these tangled configs; the instances themselves are rrix-edited and deliberately not repo tangle targets — copy the example and templates below out of this doc). The file is an ordinary org file, parsed with OrgFileParser:

  • File-level properties drawer:

    • THRESHOLD — float in [0,1]; the act tail probability P(level ≥ 3) above which the verdict logs yes. Default 0.65 (tail scale; an EV-scale 0.75 re-anchors here).

    • URGENCY — yes enables an optional urgency rubric question (a = urgency= section with the full Level outline must then exist). Default no. - WAKE — yes opts the agent into waking (*The wake dispatcher (P2)). Absent, no, or garbage ⇒ off — fail-shut, no waking. Default no. - Only when WAKE: yes: MAX_WAKES (regular wakes per local day, default 3), MAX_URGENT_WAKES (separate daily budget for urgent wakes — verdict yes with the URGENCY rubric enabled and urgency > 0.75=; default 1; the two budgets are independent lanes), MIN_WAKE_INTERVAL (minutes of spacing between spawns for one agent, default 60; 0 = off). Any knob present but unparseable (garbage or negative) makes the wake policy unusable: the dispatcher skips that agent entirely with one stderr notice — fail-shut — while the drain, which ignores these properties entirely, keeps classifying. - = should_act= heading (required): the leading prose — the body elements before the first nested = Level 0= — is the question's instructions; each nested = Level 0..4= section's body text is that level's criterion, sent on the wire as the score question's criteria array in level order. The answer's tail probability P(level ≥ 3) becomes confidence, compared against THRESHOLD (an EV-scale 0.75 re-anchors to ~0.65 on the tail scale). - = urgency= heading (optional, required iff URGENCY: yes): the same outline shape — prose instructions plus = Level 0..4= time-criticality sections; the level/4 score rides verdict lines as urgency. - The rubric criteria are the =* Level= sections of each per-agent instance file under ~/org/agents — never generic constants in code. A malformed rubric (missing level, duplicate Level N, blank level body, or URGENCY: yes with the urgency outline missing its levels) makes the whole config unusable and discovery skips it — fail-shut at the config layer.

A missing or blank should_act question makes the whole config unusable and it is skipped at discovery — fail-shut at the config layer too.

Worked example — dev-planner (abridged from the live instance)

#+begin_example org :PROPERTIES: :ID: classifier-agent-dev-planner :THRESHOLD: 0.65 :URGENCY: yes :END:

,* should_act How strongly should dev-planner act on this journal event? Judge only whether the event awaits a written plan.

,** Level 0 content of other lanes and states: personal reflection, chores, reference captures, or development work that already awaits building.

,** Level 1 a tech-log recording finished development work with nothing left to plan.

,** Level 2 development-status discussion that could seed a future work item.

,** Level 3 a concrete task named and awaiting scoping, unblocking the next step.

,** Level 4 a direct request to plan, scope, break down, or revise a plan.

,* urgency How time-critical is producing the plan? Judge only deadlines.

,** Level 0 no time signal: open-ended ideas, future possibilities.

,** Level 1 weeks of slack in the planning queue.

,** Level 2 fits the queue this week; days of slack.

,** Level 3 wanted today or tomorrow, something waiting on the plan.

,** Level 4 same-day deadline, or the plan blocks a broken deployment. #+end_example

Empty templates (copy out, edit, untangle — these are NOT tangle targets)

#+begin_example org :PROPERTIES: :ID: classifier-agent-literate-coder :THRESHOLD: 0.65 :URGENCY: no :WAKE: no :MAX_WAKES: 3 :MAX_URGENT_WAKES: 1 :MIN_WAKE_INTERVAL: 60 :END:

,* should_act <prose: the question plus a focus clause separating this judgment from neighboring lanes>

,** Level 0 <exclusions: the other lanes' content, judged alone>

,* Level 1 , Level 2 , Level 3 ,* Level 4 <one self-contained situation per level> #+end_example

#+begin_example org :PROPERTIES: :ID: classifier-agent-nix-infra-coder :THRESHOLD: 0.65 :URGENCY: no :END:

, should_act <prose + , Level 0..4 outline, as above> #+end_example

#+begin_example org :PROPERTIES: :ID: classifier-agent-org-anizer :THRESHOLD: 0.65 :URGENCY: no :END:

, should_act <prose + , Level 0..4 outline, as above> #+end_example

#+begin_example org :PROPERTIES: :ID: classifier-agent-make-legible :THRESHOLD: 0.65 :URGENCY: no :END:

, should_act <prose + , Level 0..4 outline, as above> #+end_example

#+begin_example org :PROPERTIES: :ID: classifier-agent-personal-coach :THRESHOLD: 0.65 :URGENCY: no :END:

, should_act <prose + , Level 0..4 outline, as above> #+end_example

Locks & leases

Everything under <state>/locks/. Locks are advisory, cross-process, and short-lived — producer.lock and drain.lock guard the two long-running surfaces via FileChannel.tryLock so the systemd timer never double-fires a run: produce fails fast on a held lock (clear stderr line, exit 2 — a double-producer would race the seq), while drain skips cleanly when busy (one stdout note, exit 0 — a timer must not see errors from a previous run still in progress). Release happens in finally, always.

Wake leases are the opposite trade: they outlive the process that may still wake the agent later. A lease file <state>/locks/AGENT.lease holds {"pid","started","wake_key","ttl_minutes"} and is *live iff its age is below the TTL AND /proc/PID exists AND (when /proc/PID/cmdline is readable) it mentions the agent name — an unreadable cmdline falls back to TTL-only liveness. harness lease acquire refuses to clobber a live lease (exit 1, prints the holder; --force steals), release is idempotent, check exits 0 when live and 1 when free. Lease commands never wake anything and write nowhere outside <state>/locks. The dispatcher (*The wake dispatcher (P2)) reads* lease liveness — one wake in flight per agent, absolute — and holds its own dispatch.lock for the whole run, skipping cleanly like the drain when it is busy.

kotlin#+name: harness-locks-imports
package computer.whatthefuck.arcology.harness

import java.io.File
import java.io.RandomAccessFile
import java.nio.channels.FileChannel
import java.nio.channels.FileLock
import java.nio.channels.OverlappingFileLockException
kotlin#+name: harness-locks
/**
 * Advisory cross-process lock via FileChannel.tryLock on one lock file.
 * Not reentrant within a process; always used through
 * [HarnessLocks.tryAcquire] with a finally-release at the call site.
 */
class HarnessFileLock(private val file: File) : AutoCloseable {
    private var channel: FileChannel? = null
    private var lock: FileLock? = null

    /** false when another channel already holds the lock. */
    fun tryLock(): Boolean {
        file.parentFile?.mkdirs()
        val chan = RandomAccessFile(file, "rw").channel
        channel = chan
        val fl = try {
            chan.tryLock()
        } catch (e: OverlappingFileLockException) {
            null
        }
        lock = fl
        return fl != null
    }

    override fun close() {
        runCatching { lock?.release() }
        runCatching { channel?.close() }
        lock = null
        channel = null
    }
}

/** The lock files under =<state>/locks/=: producer.lock, drain.lock,
 * and (A3) dispatch.lock — the dispatcher holds it for its whole run
 * and skips cleanly when busy, like the drain. */
class HarnessLocks(private val stateRoot: File) {
    private val dir = File(stateRoot, "locks")

    init {
        dir.mkdirs()
    }

    fun file(name: String): File = File(dir, name)

    /** null ⇒ busy (another process holds the lock). */
    fun tryAcquire(name: String): HarnessFileLock? {
        val lock = HarnessFileLock(file(name))
        return if (lock.tryLock()) {
            lock
        } else {
            lock.close()
            null
        }
    }

    /** Non-invasive probe for status: try-and-release. */
    fun isLocked(name: String): Boolean {
        val lock = HarnessFileLock(file(name))
        val got = runCatching { lock.tryLock() }.getOrDefault(false)
        lock.close()
        return !got
    }
}
kotlin#+name: harness-locks-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessLocks.kt:noweb yes
<<harness-locks-imports>>

<<harness-locks>>
kotlin#+name: harness-lease-imports
package computer.whatthefuck.arcology.harness

import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json
import java.io.File
import java.time.OffsetDateTime
import java.time.format.DateTimeFormatter
kotlin#+name: harness-lease
@Serializable
data class AgentLease(
    val pid: Long,
    /** ISO8601 with offset — acquire wall clock. */
    val started: String,
    @SerialName("wake_key") val wakeKey: String = "",
    @SerialName("ttl_minutes") val ttlMinutes: Int,
)

/** acquire outcome: [Refused] carries the live holder. */
sealed interface LeaseAcquire {
    data class Granted(val lease: AgentLease) : LeaseAcquire
    data class Refused(val lease: AgentLease) : LeaseAcquire
}

/**
 * Agent wake leases under =<state>/locks/AGENT.lease=. A lease is live
 * iff age < TTL AND the pid exists in procfs AND (when the cmdline is
 * readable) it mentions the agent name; an unreadable cmdline falls back
 * to TTL-and-pid-exists. Nothing here wakes anything: procfs is read
 * only, [procRoot] is injectable for tests.
 */
class LeaseStore(
    stateRoot: File,
    private val procRoot: String = "/proc",
    private val now: () -> OffsetDateTime = { OffsetDateTime.now() },
) {
    private val json = Json { ignoreUnknownKeys = true }
    private val dir = File(stateRoot, "locks")

    init {
        dir.mkdirs()
    }

    fun file(agent: String): File = File(dir, "$agent.lease")

    fun load(agent: String): AgentLease? = try {
        json.decodeFromString(AgentLease.serializer(), file(agent).readText())
    } catch (e: Exception) {
        // Torn or foreign lease file: not a live lease.
        null
    }

    fun live(agent: String): AgentLease? = load(agent)?.takeIf { isLive(agent, it) }

    private fun isLive(agent: String, lease: AgentLease): Boolean {
        val started = runCatching { OffsetDateTime.parse(lease.started) }
            .getOrNull() ?: return false
        val age = java.time.Duration.between(started.toInstant(), now().toInstant())
        if (age.toSeconds() >= lease.ttlMinutes * 60L) return false
        val pidDir = File("$procRoot/${lease.pid}")
        if (!pidDir.isDirectory) return false
        val cmdline = File(pidDir, "cmdline")
        if (!cmdline.isFile) return true // unreadable cmdline: TTL-only
        return try {
            cmdline.readBytes().toString(Charsets.UTF_8).contains(agent)
        } catch (e: Exception) {
            true
        }
    }

    /** [Refused] with the live holder unless [force] steals the lease. */
    fun acquire(
        agent: String,
        ttlMinutes: Int,
        wakeKey: String,
        force: Boolean,
    ): LeaseAcquire {
        val existing = if (force) null else live(agent)
        if (existing != null) return LeaseAcquire.Refused(existing)
        val lease = AgentLease(
            pid = ProcessHandle.current().pid(),
            started = DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now()),
            wakeKey = wakeKey,
            ttlMinutes = ttlMinutes,
        )
        file(agent).writeText(json.encodeToString(AgentLease.serializer(), lease))
        return LeaseAcquire.Granted(lease)
    }

    /** Idempotent: false just means the lease was not held. */
    fun release(agent: String): Boolean =
        file(agent).takeIf { it.isFile }?.delete() ?: false
}
kotlin#+name: harness-lease-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessLease.kt:noweb yes
<<harness-lease-imports>>

<<harness-lease>>

The command family

Wired into ArcologyCli next to sync, exactly that command's option layout. produce, drain, dispatch and status are all live surfaces; dispatch consumes fsynced act-verdicts and never classifies anything; status is deterministic.

kotlin#+name: harness-commands-imports
package computer.whatthefuck.arcology.harness

import com.github.ajalt.clikt.core.CliktCommand
import com.github.ajalt.clikt.core.CliktError
import com.github.ajalt.clikt.parameters.options.default
import com.github.ajalt.clikt.parameters.options.flag
import com.github.ajalt.clikt.parameters.options.option
import com.github.ajalt.clikt.parameters.options.required
import com.github.ajalt.clikt.parameters.types.double
import com.github.ajalt.clikt.parameters.types.int
import com.github.ajalt.clikt.parameters.types.long
import io.ktor.client.*
import io.ktor.client.plugins.*
import kotlinx.coroutines.runBlocking
import java.io.File
import java.time.OffsetDateTime
kotlin#+name: harness-commands
class HarnessCommand : CliktCommand(
    name = "harness",
    help = "Dumb-harness spool: produce, drain, dispatch, status"
) {
    override fun run() = Unit
}

class HarnessProduceCommand : CliktCommand(
    name = "produce",
    help = "Watch Syncthing for org changes and append heading-revision events to the spool (deployed by services.arcology2go.harness; the P0 /var/harness cron note is obsolete)"
) {
    private val orgDir: String by option("--org-dir", help = "Root org-mode directory").default("~/org")
    private val apiUrl: String by option("--api-url", help = "Syncthing REST API base URL").default("http://127.0.0.1:8384")
    private val apiKeyOption: String? by option("--api-key", help = "Syncthing REST API key (defaults to \$ARCOLOGY_SYNCTHING_API_KEY)")
    private val folderId: String? by option("--folder", help = "Explicit Syncthing folder ID (overrides path matching)")
    private val pollTimeoutSeconds: Int by option("--poll-timeout", help = "Event long-poll timeout in seconds").int().default(60)
    private val rescanIntervalSeconds: Long by option(
        "--rescan-interval", help = "Run a reconciliation full walk after this many idle seconds; 0 disables"
    ).long().default(3600)
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")
    private val once: Boolean by option(
        "--once", help = "Run one full walk (with bootstrap semantics) and exit, without the Syncthing connection"
    ).flag(default = false)
    private val baseline: Boolean by option(
        "--baseline", help = "Force a baseline re-seed: snapshots from disk, zero events, one audit marker — even on an established store"
    ).flag(default = false)
    private val emitInitialEvents: Boolean by option(
        "--emit-initial-events", help = "Legacy cold start: emit an event for every heading over an empty snapshot store"
    ).flag(default = false)
    private val maxDepth: Int by option(
        "--max-depth",
        help = "Keep one spool event per heading up to this level; deeper headings roll into their kept ancestor's body (default: unlimited)"
    ).int().default(Int.MAX_VALUE)
    private val maxBodyBytes: Int by option(
        "--max-body-bytes",
        help = "Spool-line body cap in bytes (default 20480); revisions and risk stamps always hash the FULL text, and the org tree stays the archive"
    ).int().default(DEFAULT_SPOOL_BODY_BYTES)
    private val riskEndpoint: String? by option(
        "--risk-endpoint", help = "Ollama http://host:port for production-time risk stamping (default: \$ARCOLOGY_RISK_ENDPOINT)"
    )
    private val riskModel: String? by option("--risk-model", help = "Decision model name (default: \$ARCOLOGY_RISK_MODEL or kev4b)")
    private val riskThreshold: Double by option(
        "--risk-threshold", help = "Score above which an event's risk.gated stamps true"
    ).double().default(0.40)

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        if (maxDepth < 1) {
            throw CliktError("--max-depth must be at least 1 (omit the flag for unlimited depth)")
        }
        if (maxBodyBytes < 1) {
            throw CliktError("--max-body-bytes must be at least 1")
        }
        if (baseline && emitInitialEvents) {
            throw CliktError("--baseline and --emit-initial-events are mutually exclusive")
        }
        val mode = when {
            baseline -> BootstrapMode.BASELINE
            emitInitialEvents -> BootstrapMode.FULL_EMIT
            else -> BootstrapMode.AUTO
        }
        val stateRoot = File(expand(stateDir))
        val orgRoot = File(expand(orgDir)).absoluteFile
        val endpoint = riskEndpoint ?: System.getenv("ARCOLOGY_RISK_ENDPOINT")
        val model = riskModel ?: System.getenv("ARCOLOGY_RISK_MODEL") ?: "kev4b"
        val apiKey = apiKeyOption ?: System.getenv("ARCOLOGY_SYNCTHING_API_KEY")
        // The producer lock fails fast: a second producer would race the
        // seq. --once runs under it too (scripted walks still race).
        val locks = HarnessLocks(stateRoot)
        val lock = locks.tryAcquire("producer.lock")
            ?: run {
                System.err.println(
                    "harness produce: producer.lock is held by another process; not starting"
                )
                kotlin.system.exitProcess(2)
            }
        try {
            val httpClient = HttpClient {
                install(HttpTimeout) { requestTimeoutMillis = 45_000 }
            }
            val stamper = ProducerRiskClassifier(
                endpoint = endpoint,
                model = model,
                threshold = riskThreshold,
                cacheFile = File(stateRoot, "llm-verdict-cache.ndjson"),
                httpClient = httpClient,
            )
            val producer = HarnessProducer(
                stateRoot, orgRoot, stamper,
                maxDepth = maxDepth, maxBodyBytes = maxBodyBytes,
            )
            if (once) {
                runBlocking { producer.fullWalk("once", mode) }
                return
            }
            if (apiKey.isNullOrBlank()) {
                throw CliktError("--api-key or ARCOLOGY_SYNCTHING_API_KEY must be set")
            }
            val client = HarnessSyncthingClient(apiUrl, apiKey, pollTimeoutSeconds)
            val service = HarnessProduceService(
                client = client,
                producer = producer,
                orgDir = orgRoot.path,
                folderId = folderId,
                pollTimeoutSeconds = pollTimeoutSeconds,
                rescanIntervalSeconds = rescanIntervalSeconds,
                bootstrapMode = mode,
            )
            println("harness produce: org=$orgRoot state=$stateRoot endpoint=${endpoint ?: "(none — risk stamps fail closed)"}")
            runBlocking { service.watch() }
        } finally {
            lock.close()
        }
    }
}

class HarnessDrainCommand : CliktCommand(
    name = "drain",
    help = "Classify spooled events per agent into the verdicts log (verdicts only; never spawns sessions; timer-driven oneshot under services.arcology2go.harness)"
) {
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")
    private val agentsDir: String by option(
        "--agents-dir", help = "Directory of per-agent folders holding CLASSIFIER.org"
    ).default("~/org/agents")
    private val endpoint: String? by option(
        "--endpoint", help = "Ollama http://host:port for the resident decision model (default: \$ARCOLOGY_RISK_ENDPOINT)"
    )
    private val model: String? by option("--model", help = "Decision model name (default: \$ARCOLOGY_RISK_MODEL or kev4b)")
    private val fromSeq: Long? by option(
        "--from-seq", help = "Deliberate replay window start (inclusive) for this run only; never regresses the cursor"
    ).long()
    private val onlyAgent: String? by option(
        "--only-agent", help = "Process just this agent's config; other agents' cursors are untouched"
    )
    private val maxEventsPerAgent: Int by option(
        "--max-events-per-agent", help = "Cap LLM classifications per agent this run; 0 = unlimited (default 200)"
    ).int().default(200)
    private val staleHorizonDays: Int by option(
        "--stale-horizon-days", help = "Auto-verdict events older than this many days as inert 'stale', no LLM (default 7)"
    ).int().default(7)

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        if (maxEventsPerAgent < 0) {
            throw CliktError("--max-events-per-agent must be 0 (unlimited) or a positive count")
        }
        if (staleHorizonDays < 0) {
            throw CliktError("--stale-horizon-days must be 0 or a positive day count")
        }
        val stateRoot = File(expand(stateDir))
        val configs = ClassifierConfigs.discover(File(expand(agentsDir)))
        if (configs.isEmpty()) {
            println("no ${ClassifierConfigs.FILE_NAME} agent configs under ${expand(agentsDir)}; nothing to drain")
            return
        }
        if (onlyAgent != null && configs.none { it.agent == onlyAgent }) {
            throw CliktError("no agent config named '$onlyAgent' under ${expand(agentsDir)}")
        }
        // The drain lock SKIPS when busy: the systemd timer must not see
        // errors from a previous run still in progress.
        val locks = HarnessLocks(stateRoot)
        val lock = locks.tryAcquire("drain.lock")
            ?: run {
                println("drain skipped: previous run still in progress")
                return
            }
        try {
            val resolvedEndpoint = endpoint ?: System.getenv("ARCOLOGY_RISK_ENDPOINT")
            val resolvedModel = model ?: System.getenv("ARCOLOGY_RISK_MODEL") ?: "kev4b"
            val classifier = resolvedEndpoint?.let { ep ->
                VerdictClassifier(
                    endpoint = ep,
                    model = resolvedModel,
                    httpClient = HttpClient {
                        install(HttpTimeout) { requestTimeoutMillis = 45_000 }
                    },
                )
            }
            val drain = HarnessDrain(
                stateRoot = stateRoot, configs = configs, classifier = classifier,
                model = resolvedModel,
                fromSeq = fromSeq, onlyAgent = onlyAgent,
                maxEventsPerAgent = maxEventsPerAgent,
                staleHorizonDays = staleHorizonDays,
            )
            val outcome = runBlocking { drain.drain() }
            println("harness drain: agents=${outcome.agents.size} failed=${outcome.failed}")
            for (agent in outcome.agents) {
                println("  ${agent.agent}: processed ${agent.processed}, cursor ${agent.cursor}")
            }
            if (outcome.failed) {
                // Fail closed, loudly: nothing advanced, lag is status-visible.
                throw CliktError(outcome.reason ?: "drain failed closed")
            }
        } finally {
            lock.close()
        }
    }
}

class HarnessDispatchCommand : CliktCommand(
    name = "dispatch",
    help = "Wake agent sessions from fsynced act-verdicts: one hermes session per yes, per-agent " +
        "capped and lease-gated; never classifies anything (skips cleanly when drain.lock " +
        "or dispatch.lock is held). The supported driver is --gate from the Hermes agent " +
        "cron gate scripts; direct spawning is the manual/legacy path"
) {
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")
    private val agentsDir: String by option(
        "--agents-dir", help = "Directory of per-agent folders holding CLASSIFIER.org"
    ).default("~/org/agents")
    private val onlyAgent: String? by option(
        "--agent", help = "Dispatch just this agent's config; other agents' cursors are untouched"
    )
    private val dryRun: Boolean by option(
        "--dry-run", help = "Decide and audit, spawn nothing, consume and advance nothing"
    ).flag(default = false)
    private val gate: Boolean by option(
        "--gate",
        help = "Cron gate mode: consume WITHOUT spawning — run the full gate ladder, write the " +
            "winner's briefing as always, consume the budget and clock as if spawned, and print " +
            "exactly one line \"<seq>\\t<briefing-path>\" per delivery on stdout (a cron agent run " +
            "that reads it IS the wake); every quiet path prints {\"wakeAgent\": false}. " +
            "Requires --agent; mutually exclusive with --dry-run; composes with --wake-window"
    ).flag(default = false)
    private val wakeWindowRaw: String by option(
        "--wake-window",
        help = "Wake window HH:MM-HH:MM in the system-local clock (start>end wraps midnight); " +
            "empty string = always open; default 07:00-22:00"
    ).default(WakeWindow.DEFAULT)
    private val hermesProfiles: String by option(
        "--hermes-profiles",
        help = "Per-agent hermes profiles dir; the wake env carries HERMES_HOME=<dir>/<agent>"
    ).default("~/hermes/profiles")

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        // Gate-mode argument hygiene, before any state is touched: a
        // cannot-decide invocation must be a failed cron run, never a
        // silent one (no fail-quiet excepts in gate mode).
        gateModeCliktError(gate, dryRun, onlyAgent)?.let { throw CliktError(it) }
        // Empty string parses to null (always open); garbage is a CLI error.
        val window = try {
            WakeWindow.parse(wakeWindowRaw)
        } catch (e: Exception) {
            throw CliktError("--wake-window must be HH:MM-HH:MM (or empty for always open): ${e.message}")
        }
        val stateRoot = File(expand(stateDir))
        val configs = ClassifierConfigs.discover(File(expand(agentsDir)))
        if (configs.isEmpty() && !gate) {
            // Timer-path quiet. Gate mode deliberately falls through to
            // the named-agent error instead: an empty or unusable agents
            // dir is a cannot-decide that must fail the cron run.
            println("no ${ClassifierConfigs.FILE_NAME} agent configs under ${expand(agentsDir)}; nothing to dispatch")
            return
        }
        if (onlyAgent != null && configs.none { it.agent == onlyAgent }) {
            // In gate mode this covers the malformed-config cannot-decide
            // case too: discovery only returns usable configs, so an agent
            // whose CLASSIFIER.org is unusable is "no agent config named"
            // — a nonzero exit, message on stderr.
            throw CliktError("no agent config named '$onlyAgent' under ${expand(agentsDir)}")
        }
        // The locks live inside the engine, like the drain's: drain.lock
        // busy -> skip cleanly, dispatch.lock busy -> skip cleanly. Both
        // exit 0 — a timer must not see errors from a previous run.
        // Gate mode keeps stdout reserved for the cron protocol (one
        // wake line per delivery, else the explicit quiet line): the
        // engine's notices join the stderr lane, where journald takes
        // them on the timer path.
        val engineLog: (String) -> Unit = {
            if (gate) System.err.println(it) else println(it)
        }
        val dispatcher = HarnessDispatch(
            stateRoot = stateRoot,
            configs = configs,
            onlyAgent = onlyAgent,
            dryRun = dryRun,
            gate = gate,
            wakeWindow = window,
            hermesProfilesDir = File(expand(hermesProfiles)),
            log = engineLog,
        )
        val outcome = dispatcher.dispatch()
        if (gate) {
            // The cron script protocol: wake lines on stdout wake the
            // agent, the quiet line is EXPLICIT silence (empty stdout
            // must never be load-bearing), exit 0 either way. The timer
            // path's summary rides stderr for hermes cron runs
            // observability; lock-skip notices already got there via the
            // engine's log.
            if (!outcome.busy) {
                for (agent in outcome.agents) System.err.println(agentSummary(agent))
            }
            println(gateStdoutLine(outcome))
            return
        }
        if (outcome.busy) {
            println("harness dispatch: skipped (lock held)")
            return
        }
        println("harness dispatch: agents=${outcome.agents.size}${if (dryRun) " (dry-run)" else ""}")
        for (agent in outcome.agents) println(agentSummary(agent))
    }

    private fun agentSummary(agent: DispatchAgentOutcome): String =
        "  ${agent.agent}: spawned regular=${agent.spawnedRegular} urgent=${agent.spawnedUrgent}, " +
            "held=${agent.held} cap=${agent.capped} interval=${agent.interval} " +
            "lease=${agent.leaseSkipped} missing=${agent.eventMissing}, cursor ${agent.cursor}"
}

/** The quiet half of the gate script's stdout contract: printed verbatim
 * (with a single space after the colon) when a gate run delivers
 * nothing. Empty stdout is never used for silence — a cron deliverable
 * must be unambiguous. */
internal const val GATE_QUIET_LINE = """{"wakeAgent": false}"""

/**
 * The --gate CLI validations, factored out of [HarnessDispatchCommand]
 * so jvmTest may pin the messages without constructing a Clikt command
 * (the kotest/mordant classpath conflict — see [[*Tests]]). null = the
 * combination is valid. A gate delivery is one agent's cron run: an
 * unnamed agent cannot decide, and a gate run must not be a dry run.
 */
internal fun gateModeCliktError(gate: Boolean, dryRun: Boolean, agent: String?): String? =
    when {
        gate && dryRun ->
            "--gate is mutually exclusive with --dry-run (a gate delivery consumes; a dry-run must not)"
        gate && agent == null ->
            "--gate requires an explicit --agent <name> (the cron script names one agent and takes its wake)"
        else -> null
    }

/**
 * The gate script's stdout rendering for a dispatch result: exactly one
 * "seq<TAB>absolute briefing path" wake line per [GateDelivery], else
 * [GATE_QUIET_LINE]. With the default MIN_WAKE_INTERVAL spacing there is
 * exactly one delivery per run — "one line and nothing else"; with
 * spacing explicitly disabled the extra deliveries still print (losing
 * a consumed seq's line would strand its work silently, and the audit
 * row already consumed it — nothing would ever re-deliver it).
 */
internal fun gateStdoutLine(outcome: DispatchOutcome): String {
    val lines = outcome.agents.flatMap { agent ->
        agent.gateWinners.map { delivery -> "${delivery.seq}\t${delivery.briefingPath}" }
    }
    return if (lines.isEmpty()) GATE_QUIET_LINE else lines.joinToString("\n")
}

class HarnessStatusCommand : CliktCommand(
    name = "status",
    help = "Deterministic harness report: spool lag, depth, snapshots, today's events, cursors, locks, leases"
) {
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")
    private val json: Boolean by option(
        "--json", help = "Machine-readable report (json on stdout, exit 0 always — metrics must not fail closed)"
    ).flag(default = false)

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        val stateRoot = File(expand(stateDir))
        if (json) {
            println(statusJson.encodeToString(HarnessStatusReport.serializer(), collectHarnessStatus(stateRoot, OffsetDateTime.now())))
            return
        }
        print(renderHarnessStatus(stateRoot, OffsetDateTime.now()))
    }
}

class HarnessLeaseCommand : CliktCommand(
    name = "lease",
    help = "Agent wake leases under <state>/locks — acquire|release|check; never wakes anything"
) {
    override fun run() = Unit
}

class LeaseAcquireCommand : CliktCommand(
    name = "acquire",
    help = "Acquire an agent's wake lease; refuses a live lease unless --force steals it"
) {
    private val agent: String by option("--agent", help = "Agent name the lease is for").required()
    private val ttlMinutes: Int by option("--ttl-minutes", help = "Lease TTL in minutes").int().default(60)
    private val wakeKey: String by option("--wake-key", help = "Opaque wake token to carry on the lease").default("")
    private val force: Boolean by option("--force", help = "Steal a live lease").flag(default = false)
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        if (ttlMinutes < 1) throw CliktError("--ttl-minutes must be at least 1")
        val store = LeaseStore(File(expand(stateDir)))
        when (val outcome = store.acquire(agent, ttlMinutes, wakeKey, force)) {
            is LeaseAcquire.Granted -> println(
                "lease acquired: agent=$agent pid=${outcome.lease.pid} " +
                    "ttl_minutes=${outcome.lease.ttlMinutes} wake_key='${outcome.lease.wakeKey}'"
            )
            is LeaseAcquire.Refused -> throw CliktError(
                "lease held by pid ${outcome.lease.pid} since ${outcome.lease.started} " +
                    "(wake_key '${outcome.lease.wakeKey}') — use --force to steal"
            )
        }
    }
}

class LeaseReleaseCommand : CliktCommand(
    name = "release",
    help = "Release an agent's wake lease (idempotent)"
) {
    private val agent: String by option("--agent", help = "Agent name the lease is for").required()
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        val had = LeaseStore(File(expand(stateDir))).release(agent)
        println(if (had) "lease released: $agent" else "lease not held: $agent")
    }
}

class LeaseCheckCommand : CliktCommand(
    name = "check",
    help = "Exit 0 when the agent's lease is live (printing the holder), 1 when free"
) {
    private val agent: String by option("--agent", help = "Agent name the lease is for").required()
    private val stateDir: String by option("--state-dir", help = "Harness state root").default("~/.cache/arcology2/harness")

    private fun expand(path: String) = path.replace("~", System.getProperty("user.home"))

    override fun run() {
        val live = LeaseStore(File(expand(stateDir))).live(agent)
        if (live == null) {
            println("lease free: $agent")
            kotlin.system.exitProcess(1)
        }
        println(
            "lease live: agent=$agent pid=${live.pid} started=${live.started} " +
                "ttl_minutes=${live.ttlMinutes} wake_key='${live.wakeKey}'"
        )
    }
}
kotlin#+name: harness-commands-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessCommands.kt:noweb yes
<<harness-commands-imports>>

<<harness-commands>>

Status — deterministic, no LLM

One command, plain lines: spool lag (newest event vs now), spool depth (current-month line count), snapshot file count, today's event titles, and the per-agent verdict cursors so classifier-outage lag is visible without any inference. The --json report additionally carries per-agent dispatch fields (dispatch cursor, wakes-today per lane, held wake count — see *The wake dispatcher (P2)); the text renderer deliberately does not print them, so its output stays byte-identical under A3.

kotlin#+name: harness-status-imports
package computer.whatthefuck.arcology.harness

import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json
import java.io.File
import java.time.Duration
import java.time.OffsetDateTime
import java.time.format.DateTimeFormatter
kotlin#+name: harness-status
/**
 * Pure render over the plain files. Reads: spool month files, snapshots
 * dir, cursors dir, lock files, [LeaseStore] (procfs reads), today's
 * verdicts. Writes: nothing.
 */
fun renderHarnessStatus(
    stateRoot: File,
    now: OffsetDateTime,
    procRoot: String = "/proc",
): String {
    val lines = mutableListOf<String>()
    lines.add("harness status (state: ${stateRoot.path})")
    val spoolDir = File(stateRoot, "spool")
    val spoolFiles = spoolDir.listFiles()
        ?.filter { it.isFile && it.name.endsWith(".ndjson") }
        ?.sortedBy { it.name } ?: emptyList()

    var newest: OffsetDateTime? = null
    var maxSeq = 0L
    for (file in spoolFiles) {
        file.useLines { fileLines ->
            for (line in fileLines) {
                val event = SpoolWriter.parseSpoolLine(line) ?: continue
                if (event.seq > maxSeq) maxSeq = event.seq
                runCatching { OffsetDateTime.parse(event.ts) }.getOrNull()?.let { ts ->
                    if (newest == null || ts.toInstant().isAfter(newest!!.toInstant())) {
                        newest = ts
                    }
                }
            }
        }
    }
    lines.add(
        if (newest == null) {
            "spool lag: spool empty"
        } else {
            "spool lag: ${Duration.between(newest!!.toInstant(), now.toInstant()).seconds}s " +
                "(newest $newest, now $now)"
        }
    )

    val monthName = "%04d-%02d".format(now.year, now.monthValue)
    val monthFile = File(spoolDir, "$monthName.ndjson")
    // Depth counts EVENTS: audit markers ride the same files but are
    // parse-tolerant noise to every reader.
    val depth = monthFile.takeIf { it.isFile }
        ?.useLines { fileLines -> fileLines.count { it.startsWith("{\"seq\":") } }
        ?: 0L
    lines.add("spool depth: $depth events in $monthName.ndjson")

    lines.add("snapshot files: ${SnapshotStore(stateRoot).count()}")

    val today = "%04d-%02d-%02d".format(now.year, now.monthValue, now.dayOfMonth)
    val todays = mutableListOf<String>()
    if (monthFile.isFile) {
        monthFile.useLines { fileLines ->
            for (line in fileLines) {
                val event = SpoolWriter.parseSpoolLine(line) ?: continue
                if (event.ts.take(10) == today) {
                    todays.add("  ${event.seq} ${event.action} ${event.title}")
                }
            }
        }
    }
    lines.add("today's events:")
    lines.addAll(if (todays.isEmpty()) listOf("  (none)") else todays)

    val cursors = File(stateRoot, "cursors").listFiles()
        ?.filter { it.isFile && it.name.endsWith(".verdict") }
        ?.sortedBy { it.name } ?: emptyList()
    lines.add("verdict cursors:")
    if (cursors.isEmpty()) {
        lines.add("  (none)")
    } else {
        for (cursorFile in cursors) {
            val agent = cursorFile.name.removeSuffix(".verdict")
            val seq = cursorFile.readText().trim().toLongOrNull() ?: 0L
            lines.add("  $agent: $seq (lag ${maxSeq - seq})")
        }
    }

    // Locks and leases: probes and procfs reads only, no LLM anywhere.
    val locks = HarnessLocks(stateRoot)
    lines.add("producer lock: ${if (locks.isLocked("producer.lock")) "held" else "free"}")
    lines.add("drain lock: ${if (locks.isLocked("drain.lock")) "held" else "free"}")

    val leaseStore = LeaseStore(stateRoot, procRoot = procRoot, now = { now })
    val agentLeases = File(stateRoot, "locks").listFiles()
        ?.filter { it.isFile && it.name.endsWith(".lease") }
        ?.map { it.name.removeSuffix(".lease") }
        ?.sorted()
        ?.mapNotNull { agent -> leaseStore.live(agent)?.let { agent to it } }
        ?: emptyList()
    lines.add("leases:")
    if (agentLeases.isEmpty()) {
        lines.add("  (none)")
    } else {
        for ((agent, lease) in agentLeases) {
            val ageSec = runCatching {
                Duration.between(
                    OffsetDateTime.parse(lease.started).toInstant(), now.toInstant()
                ).seconds
            }.getOrDefault(0L)
            lines.add("  $agent: pid ${lease.pid}, age ${ageSec}s")
        }
    }

    val todayVerdicts = File(stateRoot, "verdicts").resolve("$today.ndjson")
    val staleToday = todayVerdicts.takeIf { it.isFile }?.useLines { fileLines ->
        fileLines.count { line ->
            runCatching {
                VerdictJson.decodeFromString(VerdictLogLine.serializer(), line)
            }.getOrNull()?.verdict == "stale"
        }
    } ?: 0
    lines.add("today's stale verdicts: $staleToday")
    return lines.joinToString("\n") + "\n"
}

// ── Machine-readable status ────────────────────────────────────────
//
// The A2 contract: same plain-file reads as the text renderer, no
// writes, zero LLM, and a schema that stays stable across releases.

/** Spool-side numbers; null [lagSeconds]/[newest] mean the spool is empty. */
@Serializable
data class HarnessSpoolStatus(
    val maxSeq: Long,
    val newest: String? = null,
    /** Seconds between [newest] and [HarnessStatusReport.now]; null = empty spool. */
    val lagSeconds: Long? = null,
    val depthThisMonth: Long,
)

@Serializable
data class HarnessLocksStatus(val producer: Boolean, val drain: Boolean)

@Serializable
data class HarnessAgentStatus(
    val agent: String,
    val cursor: Long,
    /** [HarnessStatusReport] maxSeq minus the cursor. */
    val lag: Long? = null,
    val verdictsToday: Int,
    val staleToday: Int,
    /** v1 semantics: the drain cannot run at all — no ARCOLOGY_RISK_ENDPOINT. */
    val failed: Boolean,
    // ── A3 additive dispatch fields ──────────────────────────────────
    // Old consumers ignore them; statusJson encodes defaults, so the
    // schema stays self-describing. The text renderer prints none of
    // these — its output is byte-identical under A3.
    /** null = no cursors/AGENT.dispatch file yet (never head-inited). */
    val dispatchCursor: Long? = null,
    val wakesRegularToday: Int = 0,
    val wakesUrgentToday: Int = 0,
    /** Wake candidates the dispatcher would consider on its next
     * in-window tick: yes rows above the dispatch cursor up to the
     * contiguous classified frontier, minus already-spawned seqs. */
    val heldWakes: Int = 0,
)

@Serializable
data class HarnessStatusReport(
    /** ISO8601 with offset — the report's reading time. */
    val now: String,
    /** ARCOLOGY_RISK_ENDPOINT as seen by this process; null = unset, drain fails closed. */
    val endpoint: String? = null,
    val spool: HarnessSpoolStatus,
    val snapshotFiles: Int,
    val locks: HarnessLocksStatus,
    val agents: List<HarnessAgentStatus> = emptyList(),
)

/**
 * The machine-readable half of [[renderHarnessStatus]]: the same reads,
 * collected into a [[HarnessStatusReport]] for =status --json= (and the
 * deployment module's textfile metrics). The text renderer keeps its
 * own body byte-for-byte; the collector re-parses the (small) state
 * files so the two surfaces can drift only in presentation.
 * [endpointEnv] injects the endpoint lookup so tests never touch the
 * process environment.
 */
internal fun collectHarnessStatus(
    stateRoot: File,
    now: OffsetDateTime,
    procRoot: String = "/proc",
    endpointEnv: () -> String? = { System.getenv("ARCOLOGY_RISK_ENDPOINT") },
): HarnessStatusReport {
    val endpoint = endpointEnv()
    val spoolDir = File(stateRoot, "spool")
    val spoolFiles = spoolDir.listFiles()
        ?.filter { it.isFile && it.name.endsWith(".ndjson") }
        ?.sortedBy { it.name } ?: emptyList()
    var newest: OffsetDateTime? = null
    var maxSeq = 0L
    for (file in spoolFiles) {
        file.useLines { fileLines ->
            for (line in fileLines) {
                val event = SpoolWriter.parseSpoolLine(line) ?: continue
                if (event.seq > maxSeq) maxSeq = event.seq
                runCatching { OffsetDateTime.parse(event.ts) }.getOrNull()?.let { ts ->
                    if (newest == null || ts.toInstant().isAfter(newest!!.toInstant())) {
                        newest = ts
                    }
                }
            }
        }
    }
    val monthName = "%04d-%02d".format(now.year, now.monthValue)
    val depth = File(spoolDir, "$monthName.ndjson").takeIf { it.isFile }
        ?.useLines { fileLines -> fileLines.count { it.startsWith("{\"seq\":") }.toLong() }
        ?: 0L
    val today = "%04d-%02d-%02d".format(now.year, now.monthValue, now.dayOfMonth)
    val perAgent = mutableMapOf<String, Pair<Int, Int>>() // verdicts to stale
    File(stateRoot, "verdicts").resolve("$today.ndjson").takeIf { it.isFile }?.useLines { fileLines ->
        for (line in fileLines) {
            val row = runCatching {
                VerdictJson.decodeFromString(VerdictLogLine.serializer(), line)
            }.getOrNull() ?: continue
            val (verdicts, stale) = perAgent[row.agent] ?: (0 to 0)
            perAgent[row.agent] = (verdicts + 1) to (stale + if (row.verdict == "stale") 1 else 0)
        }
    }
    val agents = File(stateRoot, "cursors").listFiles()
        ?.filter { it.isFile && (it.name.endsWith(".verdict") || it.name.endsWith(".dispatch")) }
        ?.map { it.name.removeSuffix(".verdict").removeSuffix(".dispatch") }
        ?.distinct()
        ?.sorted()
        ?.map { agent ->
            val seq = File(stateRoot, "cursors/$agent.verdict").takeIf { it.isFile }
                ?.readText()?.trim()?.toLongOrNull() ?: 0L
            val (verdicts, stale) = perAgent[agent] ?: (0 to 0)
            val dispatchCursor = readDispatchCursor(stateRoot, agent)
            val wakesRegular = if (dispatchCursor != null)
                wakesSpawnedToday(stateRoot, agent, "regular", now) else 0
            val wakesUrgent = if (dispatchCursor != null)
                wakesSpawnedToday(stateRoot, agent, "urgent", now) else 0
            val held = if (dispatchCursor != null)
                selectWakeCandidates(stateRoot, agent, dispatchCursor, null).candidates.size
            else 0
            HarnessAgentStatus(
                agent = agent,
                cursor = seq,
                lag = maxSeq - seq,
                verdictsToday = verdicts,
                staleToday = stale,
                failed = endpoint == null,
                dispatchCursor = dispatchCursor,
                wakesRegularToday = wakesRegular,
                wakesUrgentToday = wakesUrgent,
                heldWakes = held,
            )
        } ?: emptyList()
    return HarnessStatusReport(
        now = DateTimeFormatter.ISO_OFFSET_DATE_TIME.format(now),
        endpoint = endpoint,
        spool = HarnessSpoolStatus(
            maxSeq = maxSeq,
            newest = newest?.toString(),
            lagSeconds = newest
                ?.let { Duration.between(it.toInstant(), now.toInstant()).seconds },
            depthThisMonth = depth,
        ),
        snapshotFiles = SnapshotStore(stateRoot).count(),
        locks = HarnessLocksStatus(
            producer = HarnessLocks(stateRoot).isLocked("producer.lock"),
            drain = HarnessLocks(stateRoot).isLocked("drain.lock"),
        ),
        agents = agents,
    )
}

/** --json's encoder: explicit defaults so the schema stays self-describing. */
internal val statusJson = Json { encodeDefaults = true }
kotlin#+name: harness-status-composed:tangle ../src/jvmMain/kotlin/computer/whatthefuck/arcology/harness/HarnessStatus.kt:noweb yes
<<harness-status-imports>>

<<harness-status>>

Deployment — homeManagerModules.harness

The harness CLI is fully built and verified; what it needed is a deploy that can read /home/rrix/org. System units can't: the langlemangle VM's services run outside the user's home while the org tree is user-owned. So the harness deploys as a home-manager user unit — flake.nix exports homeManagerModules.harness import ./nix/hm-harness.nix=, shaped exactly like homeManagerModules.sync (nix/hm-module.nix, the user-level Syncthing watcher). There is no harness NixOS module: nix/module.nix (nixosModules.server) stays untouched, and — the first draft's mistake, corrected — the harness options are self-contained in their own subtree, services.arcology2goHarness, with zero mixing against services.arcology2go. User units also mean StateDirectory is off the table: every path rides %h, which systemd expands in user-unit ExecStart argv — so the harness state lands precisely where the manual runs left it.

Options

  • services.arcology2goHarness.enable — gates the producer service, the drain timer/service pair and the textfile knob.

  • services.arcology2goHarness.package — the CLI derivation (default pkgs.callPackage ../default.nix {}, mirroring services.arcology2goSync).

  • services.arcology2goHarness.stateDir — default %h/.cache/arcology2/harness — the reason this deploy works: exactly where the manual runs left their state, adopted wholesale. It is passed to every unit automatically (produce, drain, dispatch, and the textfile's status call), so it is deliberately not something to repeat under settings. Spool, snapshots, cursors, verdicts, wakes, locks and the plain-file LLM cache live under it.

  • services.arcology2goHarness.drainInterval — the timer cadence and the GPU-backoff knob: one in-flight classifier call, one drain instance (drain.lock skips cleanly); raise it when the model is busy.

  • services.arcology2goHarness.environment — the units' environment: ARCOLOGY_RISK_ENDPOINT (drain + producer risk stamping) and ARCOLOGY_RISK_MODEL (default kev4b). Fail closed: without an endpoint the drain writes no verdicts and the failed metric reads 1.

  • services.arcology2goHarness.apiKeyFile — file holding the Syncthing API key for the producer (sync module's keyed-wrapper pattern); null relies on the session environment. The file must be readable by the user unit: a plain 0600 file under the home (~/.config/arcology/syncthing-api-key works) or a sops-nix home-manager secret path both qualify — the system-level sops store cannot be referenced from a user module that does not enable it.

  • services.arcology2goHarness.textfile.enable .directory .interval — the A2 knob: a user-space oneshot + timer writing harness-<host>.prom for the textfile collector.

  • Wake dispatch no longer deploys systemd units: the Hermes agent cron gate scripts run arcology2 harness dispatch --gate (consume-without-spawn; the cron agent run that reads the wake line IS the wake), and the per-agent wake window collapses into each agent's cron schedule.

  • Wake files aging: systemd.user.tmpfiles.rules remove =<stateDir>/wakes/.md= (briefings) and =<stateDir>/wakes/.ndjson= (audit) after 30 days. The dispatcher itself never deletes: briefing + audit are the kept audit trail; legacy A3 =.json= payloads are cleaned by hand, no compat rule. - services.arcology2goHarness.settings.produce / .drain — all the remaining command-line arguments*, verbatim, one attr per --flag: the attr name is the flag without its dashes (quoted when dashed, e.g. "org-dir" / "poll-timeout"), the value a string/int/bool. null drops the flag; true emits a bare flag (--once); false drops it. --state-dir is auto-prefixed before the settings so an entry in settings can still override it (Clikt's last-occurrence rule). This is the escape hatch for anything the module does not model — it exists because Syncthing's folder resolution cannot match when the harness VM sees the org tree on a different path than the syncthing host does (the virtiofsd plumb on langlemangle, 2026-11-12): setting folder overrides path matching entirely.

nix#+name: harness-hm-options:noweb-ref harness-hm-options
enable = mkEnableOption "harness produce/drain/status deployment (user-level)";

package = mkOption {
  type = types.package;
  default = pkgs.callPackage ../default.nix {};
  defaultText = literalExpression "pkgs.callPackage ../default.nix {}";
  description = "The arcology2 CLI derivation.";
};

drainInterval = mkOption {
  type = types.str;
  default = "5m";
  description = ''
    Timer cadence for the verdict-only drain (systemd time-span) — the
    GPU-backoff knob: one in-flight classifier call, one drain instance
    (drain.lock skips cleanly), so raising this only changes how often
    the drain gets its turn at the model.
  '';
};

stateDir = mkOption {
  type = types.str;
  default = "%h/.cache/arcology2/harness";
  description = ''
    Harness state root (the CLI's --state-dir). The CLI default is the
    user's own XDG cache, so the user-level service adopts whatever the
    manual runs left behind. Spool, snapshots, cursors, verdicts, locks
    and the plain-file LLM cache live under it. Passed to every unit
    automatically and therefore not a settings entry.
  '';
};

environment = mkOption {
  type = types.attrsOf types.str;
  default = {};
  example = {
    ARCOLOGY_RISK_ENDPOINT = "http://tomorrow-untrodden:8080";
    ARCOLOGY_RISK_MODEL = "kev4b";
  };
  description = ''
    Environment for all harness units. ARCOLOGY_RISK_ENDPOINT and
    ARCOLOGY_RISK_MODEL feed the drain and the producer's risk stamping;
    without an endpoint the drain fails closed before writing anything.
  '';
};

apiKeyFile = mkOption {
  type = types.nullOr types.path;
  default = null;
  description = ''
    File whose content is the Syncthing API key, exported as
    ARCOLOGY_SYNCTHING_API_KEY for the producer — the sync module's
    keyed-wrapper pattern. null relies on the session environment.
  '';
};

settings = mkOption {
  description = ''
    All the remaining command-line arguments, one attr per --flag. Attr
    names are the flags without their dashes (quote dashed names in
    nix: "org-dir"); null drops the flag, true emits a bare flag, false
    drops it, everything else stringifies after two dashes.
  '';
  default = {};
  type = types.submodule {
    options = {
      produce = mkOption {
        type = types.attrsOf (
          types.nullOr (types.either types.bool (types.either types.int types.str))
        );
        default = {};
        example = literalExpression ''
          {
            "org-dir" = "%h/org";
            folder = "MYFOLDER-ID";  # overrides syncthing path matching
            "poll-timeout" = 30;
          }
        '';
        description = "Arguments for =arcology2 harness produce=.";
      };
      drain = mkOption {
        type = types.attrsOf (
          types.nullOr (types.either types.bool (types.either types.int types.str))
        );
        default = {};
        example = literalExpression ''
          {
            "agents-dir" = "%h/org/agents";
            "stale-horizon-days" = 14;
          }
        '';
        description = "Arguments for =arcology2 harness drain=.";
      };
    };
  };
};

textfile = {
  enable = mkOption {
    type = types.bool;
    default = false;
    description = "Write harness-<host>.prom for the prometheus textfile collector.";
  };
  directory = mkOption {
    type = types.str;
    default = "%h/.local/share/node_exporter";
    description = ''
      Directory the node_exporter's textfile collector must scrape
      (point its flag here). %h expands in user-unit ExecStart argv.
    '';
  };
  interval = mkOption {
    type = types.str;
    default = "5m";
    description = "Timer cadence for the status-to-metrics oneshot.";
  };
};

My Configuration

nix:tangle ~/nix/hm/arcology2go-harness.nix:mkdirp yes
{ inputs, pkgs, config, ... }:

{
  imports = [ inputs.arcology2go.homeManagerModules.harness ];

  services.arcology2goHarness = {
    enable = true;
    # stateDir stays at the default %h/.cache/arcology2/harness — exactly
    # where the manual runs left their state, adopted wholesale.
    environment = {
      ARCOLOGY_RISK_MODEL = "kev4b";
      ARCOLOGY_RISK_ENDPOINT = "http://tomorrow-untrodden:8080";
    };
    # The user-level Syncthing API key for the producer's event tail.
    # No sops dependency at user level: point this at wherever the key
    # lives (a sops-nix home-manager secret path, or a 0600 file under
    # ~/.config — put it there with install -m 0600).
    apiKeyFile = "${config.home.homeDirectory}/.config/arcology/syncthing-api-key";

    # CLI options
    settings.produce = {
      "org-dir" = "%h/org";
      "api-url" = "http://last-bank:8384";
      "max-depth" = 1;
      folder = "p1kld-oxnwd";
    };
    settings.drain."agents-dir" = "%h/org/agents";
    # A4: wake dispatch is the Hermes cron gate scripts' job
    # (arcology2 harness dispatch --gate); no systemd dispatch units.
  };
}

Service units (user)

The textfile unit's prom path rides ExecStart *argv* — systemd expands %h specifiers in user-unit argv, but never inside a script body, so the writeShellScript writes through =$1=/$2 and the timer/host name comes from the shell.

A4 removed the systemd wake-dispatch units (=arcology-harness-dispatch= and the per-agent =arcology-harness-agent-= service/timer pairs): wake dispatch is driven by the Hermes agent cron gate scripts running arcology2 harness dispatch --gate, which consume verdicts WITHOUT spawning sessions — the cron agent run that reads the printed <seq>\t<briefing-path> line is the wake. The engine still holds dispatch.lock for its run and skips cleanly while drain.lock is busy, so a gate tick overlapping the drain timer is safe by construction. Wake payloads and audit lines land under <state>/wakes and are aged out after 30 days by user tmpfiles rules.

nix#+name: harness-hm-module:tangle ../nix/hm-harness.nix:mkdirp yes:noweb yes
{ config, lib, pkgs, ... }:

with lib;

let
  cfg = config.services.arcology2goHarness;

  # Mirror of services.arcology2goSync's keyed wrapper: the producer
  # needs the Syncthing API key; the drain needs only the endpoint env.
  produceKeyed = pkgs.writeShellScript "arcology-harness-producer-keyed" ''
    export ARCOLOGY_SYNCTHING_API_KEY="$(cat ${cfg.apiKeyFile})"
    exec ${cfg.package}/bin/arcology2 harness produce "$@"
  '';
  # Generic CLI-argument renderer for [settings]: every attr becomes
  # --name value; null and false drop the flag, true emits a bare flag,
  # everything else stringifies. --state-dir rides first in produceArgs
  # / drainArgs, so a settings entry that wants to override it wins per
  # Clikt's last-occurrence rule.
  cliArgs = attrs: concatStringsSep " " (builtins.filter (s: s != "") (
    mapAttrsToList
      (name: value:
        if value == null then ""
        else if value == true then "--${name}"
        else if value == false then ""
        else "--${name} ${toString value}"
      )
      attrs
  ));
  produceArgs = concatStringsSep " " (builtins.filter (s: s != "") [
    "--state-dir ${cfg.stateDir}"
    (cliArgs cfg.settings.produce)
  ]);
  produceExec =
    if cfg.apiKeyFile != null
    then "${produceKeyed} ${produceArgs}"
    else "${cfg.package}/bin/arcology2 harness produce ${produceArgs}";
  drainArgs = concatStringsSep " " (builtins.filter (s: s != "") [
    "--state-dir ${cfg.stateDir}"
    (cliArgs cfg.settings.drain)
  ]);
  drainExec = "${cfg.package}/bin/arcology2 harness drain ${drainArgs}";
  textfileScript = pkgs.writeShellScript "arcology-harness-textfile" ''
    prom="$1/harness-$HOSTNAME.prom"
    ${cfg.package}/bin/arcology2 harness status --state-dir "$2" --json \
      | ${pkgs.jq}/bin/jq -r '
          "# TYPE arcology_harness_spool_lag_seconds gauge",
          (if .spool.lagSeconds == null then empty
           else "arcology_harness_spool_lag_seconds \(.spool.lagSeconds)" end),
          "# TYPE arcology_harness_spool_max_seq gauge",
          "arcology_harness_spool_max_seq \(.spool.maxSeq)",
          "# TYPE arcology_harness_endpoint_configured gauge",
          "arcology_harness_endpoint_configured \(if .endpoint == null then 0 else 1 end)",
          "# TYPE arcology_harness_cursor_seq gauge",
          (.agents[] | "arcology_harness_cursor_seq{agent=\"\(.agent)\"} \(.cursor)"),
          "# TYPE arcology_harness_verdicts_today gauge",
          (.agents[] | "arcology_harness_verdicts_today{agent=\"\(.agent)\"} \(.verdictsToday)"),
          "# TYPE arcology_harness_failed gauge",
          (.agents[] | "arcology_harness_failed{agent=\"\(.agent)\"} \(.failed | if . then 1 else 0 end)")
        ' \
      > "$prom.tmp" && mv "$prom.tmp" "$prom"
  '';
in {
  options.services.arcology2goHarness = {
    <<harness-hm-options>>
  };

  config = mkIf cfg.enable (mkMerge [ {
    systemd.user.services.arcology-harness-producer = {
      Unit = {
        Description = "Arcology harness spool producer";
        After = [ "default.target" ];
      };
      Service = {
        Type = "simple";
        ExecStart = produceExec;
        Restart = "always";
        RestartSec = 10;
        Environment = mapAttrsToList (name: value: "${name}=${value}") cfg.environment;
      };
      Install = { WantedBy = [ "default.target" ]; };
    };

    systemd.user.services.arcology-harness-drain = {
      Unit = {
        Description = "Arcology verdicts classifier drain";
        After = [ "default.target" ];
      };
      Service = {
        Type = "oneshot";
        ExecStart = drainExec;
        Environment = mapAttrsToList (name: value: "${name}=${value}") cfg.environment;
        TimeoutStartSec = "20min";
        # drain.lock makes timer overlap safe: a busy drain skips with
        # one stdout note and exit 0.
      };
    };

    systemd.user.timers.arcology-harness-drain = {
      Install = { WantedBy = [ "timers.target" ]; };
      Timer = {
        OnBootSec = "2min";
        OnUnitActiveSec = cfg.drainInterval;
      };
    };

    systemd.user.services.arcology-harness-textfile = mkIf cfg.textfile.enable {
      Unit = {
        Description = "Arcology harness status to prometheus textfile metrics";
        After = [ "default.target" ];
      };
      Service = {
        Type = "oneshot";
        # %h expands in user-unit argv but never inside script bodies, so
        # the writeShellScript takes the prom directory and the state dir
        # as $1/$2 and the host name comes from the shell's $HOSTNAME.
        ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p ${cfg.textfile.directory}";
        ExecStart = "${textfileScript} ${cfg.textfile.directory} ${cfg.stateDir}";
        Environment = mapAttrsToList (name: value: "${name}=${value}") cfg.environment;
        TimeoutStartSec = "2min";
      };
    };

    systemd.user.timers.arcology-harness-textfile = mkIf cfg.textfile.enable {
      Install = { WantedBy = [ "timers.target" ]; };
      Timer = {
        OnBootSec = "2min";
        OnUnitActiveSec = cfg.textfile.interval;
      };
    };
  }

  {
    # A4: wake dispatch moved to the Hermes cron gate scripts
    # (--gate); no dispatch systemd units are deployed anymore.
    # Wake payloads + audit lines are KEPT (audit trail) and aged out
    # after 30 days; the dispatcher never deletes anything itself.
    systemd.user.tmpfiles.rules = [
      "R ${cfg.stateDir}/wakes/*.md - - 30d"
      "R ${cfg.stateDir}/wakes/*.ndjson - - 30d"
    ];
  } ]);
}

Metrics

All values are *gauges: lag_seconds is an instantaneous reading, cursor_seq is a pointer rather than an accumulation, verdicts_today resets at midnight (counters must never reset), failed and endpoint_configured are 0/1 bits. Labels only ever =agent="<name>"=, taken from the cursor filenames. The lag metric is absent* on an empty spool rather than reporting a fake infinity; arcology_harness_spool_max_seq carries the depth the lag hides. failed v1 semantics: no ARCOLOGY_RISK_ENDPOINT in the unit's environment — the drain would fail closed before writing anything.

Deploy checklist

  • loginctl enable-linger rrix on the VM — without linger the user units only run inside a login session.

  • install -m 0600 <key> ~/.config/arcology/syncthing-api-key — the producer's keyed wrapper reads it at start; a missing file fails the producer visibly (fail closed, =Restart=always= will keep retrying).

  • systemctl --user status arcology-harness-producer — =Restart=always= keeps the watcher pinned; journalctl --user -u arcology-harness-producer shows the watch heartbeat and full walks.

  • systemctl --user list-timers 'arcology-harness-*' — drain and textfile timers present, next-el fire times sane.

  • First drain journalctl --user -u arcology-harness-drain line: the fresh-agent head-init notice, then cursor files under ~/.cache/arcology2/harness.

  • Spool lag self-heals across one drain tick; verdict file grows by one row per event per agent.

  • journalctl --user -u arcology-harness-drain cadence: strictly sequential model calls, one in flight.

  • ~/.local/share/node_exporter/harness-<host>.prom (host name resolved at run time from $HOSTNAME) exists and the exporter's textfile collector flag points at that directory.

  • Cron gate: agent-gate.py <agent> <mode> (Hermes scripts) runs arcology2 harness dispatch --state-dir ~/.cache/arcology2/harness --agents-dir ~/org/agents --agent <agent> --gate and forwards its wake line ("seq<TAB>briefing path") or the {"wakeAgent": false} quiet line.

  • First gate tick for a fresh agent: head-init notice on stderr, cursors/AGENT.dispatch appears, wake line or quiet JSON on stdout.

  • Wake attempts land in ~/.cache/arcology2/harness/wakes/ (briefings <agent>-<seq>.md, audit YYYY-MM-DD.ndjson); spawned wakes appear as arcology-wake-<agent>-<seq> user units tagged --source wake, so they show in the hermes listing clients; both file kinds age out after 30 days via user tmpfiles.

  • Deliberate wake replay = delete or rewrite cursors/AGENT.dispatch: delete re-head-inits at the spool head (nothing re-woken); rewrite to a seq N wakes the fsynced yeses above N, capped by the per-agent lane budgets.

  • journalctl --user -u arcology-harness-drain + status --json must agree: while drain.lock is busy, dispatch ticks exit 0 with a "skipped" note and touch nothing.

Tests

All pure-function, tmp-dir, or embedded-Ktor-server tests — no Clikt parse() (the kotest/mordant classpath conflict documented in tools.org makes command construction unrunnable in jvmTest), no live Ollama, and never a touch of ~/org.

SpoolWriter tests

kotlin#+name: harness-spool-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/SpoolWriterTest.kt
package computer.whatthefuck.arcology.harness

import java.io.File
import java.nio.file.Files
import kotlin.test.*

class SpoolWriterTest {
    private fun stateRoot() = Files.createTempDirectory("harness-spool").toFile()

    private fun event(ts: String = "2026-11-10T08:12:03-08:00") = SpoolEvent(
        ts = ts, scope = "journal", file = "journals/2026-11/10.org",
        identity = SpoolIdentity(orgId = null, key = "journals/2026-11/10.org::4.2"),
        action = "added", title = "Morning entry", todo = null,
        body = "Coffee, then planning.", revision = "9f2c1a",
        risk = SpoolRisk(max = 0.3, gated = false), modifiedBy = "local",
    )

    @Test
    fun `seq starts at 1 and increments gap-free`() {
        val writer = SpoolWriter(stateRoot())
        assertEquals(1L, writer.append(event()))
        assertEquals(2L, writer.append(event()))
        assertEquals(3L, writer.append(event()))
    }

    @Test
    fun `lines render schema field order and parse back`() {
        val root = stateRoot()
        val writer = SpoolWriter(root)
        writer.append(event())
        val line = File(root, "spool/2026-11.ndjson").readLines().single()
        assertTrue(
            line.startsWith("""{"seq":1,"ts":"2026-11-10T08:12:03-08:00","scope":"journal","""),
            "fixed field order for greppability: $line"
        )
        assertTrue(line.contains(""""identity":{"key":""""))
        assertTrue(line.contains(""""risk":{"max":0.3,"gated":false}"""))
        val parsed = SpoolWriter.parseSpoolLine(line)
        assertEquals(1L, parsed?.seq)
        assertEquals("added", parsed?.action)
        assertEquals("journals/2026-11/10.org::4.2", parsed?.identity?.key)
        assertNull(parsed?.todo)
    }

    @Test
    fun `restart after crash between append and seq persist resumes from spool scan`() {
        val root = stateRoot()
        val writer = SpoolWriter(root)
        writer.append(event())
        writer.append(event())
        // crash after the 3rd append, before its seq-file persist:
        assertEquals(3L, writer.append(event()))
        File(root, "producer.seq").writeText("2\n")
        val restarted = SpoolWriter(root)
        assertEquals(4L, restarted.append(event()))
        val seqs = File(root, "spool/2026-11.ndjson").readLines()
            .map { """\d+""".toRegex().find(it)!!.value.toLong() }
        assertEquals(listOf(1L, 2L, 3L, 4L), seqs)
    }

    @Test
    fun `seq file ahead of the spool keeps monotonicity`() {
        val root = stateRoot()
        File(root, "producer.seq").writeText("50\n")
        val writer = SpoolWriter(root)
        assertEquals(51L, writer.append(event()))
    }

    @Test
    fun `torn trailing lines are skipped not gaps`() {
        val root = stateRoot()
        val writer = SpoolWriter(root)
        writer.append(event())
    }

    @Test
    fun `month rollover writes the event ts month file`() {
        val root = stateRoot()
        val writer = SpoolWriter(root)
        writer.append(event(ts = "2026-11-30T23:59:00-08:00"))
        writer.append(event(ts = "2026-12-01T00:00:00-08:00"))
        assertEquals(1, File(root, "spool/2026-11.ndjson").countLines())
        assertEquals(1, File(root, "spool/2026-12.ndjson").countLines())
    }

    @Test
    fun `readEvents orders globally by seq across month files`() {
        val root = stateRoot()
        val writer = SpoolWriter(root)
        writer.append(event(ts = "2026-11-30T10:00:00-08:00"))
        writer.append(event(ts = "2026-12-01T10:00:00-08:00"))
        writer.append(event(ts = "2026-12-02T10:00:00-08:00"))
        assertEquals(listOf(1L, 2L, 3L), writer.readEvents().map { it.seq })
    }

    @Test
    fun `baseline marker rides the spool without consuming seq`() {
        val root = stateRoot()
        val writer = SpoolWriter(root)
        writer.append(event())
        val marker = SpoolWriter.buildBaselineMarker(
            files = 2, headings = 9, headSeq = 1, ts = "2026-11-10T08:12:03-08:00"
        )
        assertTrue(SpoolWriter.isMarkerLine(marker), "marker detected")
        assertFalse(SpoolWriter.isMarkerLine(SpoolWriter.renderSpoolLine(event())), "events are not markers")
        writer.appendRaw(marker)
        // Crash-style restart: the seq mirror is lost, the resume scan
        // skips the marker — the next seq neither gaps nor duplicates.
        File(root, "producer.seq").writeText("0\n")
        val restarted = SpoolWriter(root)
        assertEquals(2L, restarted.append(event()))
        // Every reader: markers are not events.
        assertEquals(
            listOf(1L, 2L),
            restarted.readEvents().map { it.seq }
        )
        val lines = File(root, "spool/2026-11.ndjson").readLines()
        assertEquals(3, lines.size)
        assertTrue(SpoolWriter.isMarkerLine(lines[1]), "marker rode the same month file")
    }

    @Test
    fun `raw spool lines must carry a ts to place their month file`() {
        val writer = SpoolWriter(stateRoot())
        assertFailsWith<IllegalArgumentException> {
            writer.appendRaw("""{"type":"baseline","files":1}""")
        }
    }

    private fun File.countLines(): Int = useLines { it.count() }
}

Snapshot store tests

kotlin#+name: harness-snapshot-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/SnapshotStoreTest.kt
package computer.whatthefuck.arcology.harness

import java.nio.file.Files
import kotlin.test.*

class SnapshotStoreTest {

    @Test
    fun `entries roundtrip through mangled per-file names`() {
        val store = SnapshotStore(Files.createTempDirectory("harness-snap").toFile())
        val entries = mapOf(
            "4.2" to SnapshotEntry(hash = "abc", orgId = "id-1", title = "Morning entry"),
            "5" to SnapshotEntry(hash = "def"),
        )
        store.save("journals/2026-11/10.org", entries)
        assertTrue(store.fileFor("journals/2026-11/10.org").isFile)
        assertFalse(store.fileFor("journals/2026-11/10.org").name.contains('/'))
        assertEquals(entries, store.load("journals/2026-11/10.org"))
        assertEquals(listOf("journals/2026-11/10.org"), store.trackedFiles())
        assertEquals(1, store.count())
    }

    @Test
    fun `missing and corrupt snapshots read as unseen`() {
        val store = SnapshotStore(Files.createTempDirectory("harness-snap").toFile())
        assertTrue(store.load("ghost.org").isEmpty())
        val f = store.fileFor("broken.org")
        f.writeText("not { json")
        assertTrue(store.load("broken.org").isEmpty())
    }

    @Test
    fun `remove untracks a deleted file`() {
        val store = SnapshotStore(Files.createTempDirectory("harness-snap").toFile())
        store.save("gone.org", mapOf("1" to SnapshotEntry(hash = "x")))
        assertEquals(1, store.count())
        store.remove("gone.org")
        assertEquals(0, store.count())
        assertTrue(store.load("gone.org").isEmpty())
    }

    @Test
    fun `snapshot names hash to bounded files for absurd org file names`() {
        // Real case: journal files named by their titles blew the 255-byte
        // filename limit with URL-encoded names + the atomic-write .tmp.
        val store = SnapshotStore(Files.createTempDirectory("harness-snap").toFile())
        val longName = "20211009172429-" + "actually_breaking_up".repeat(30) + ".org"
        val entries = mapOf("1" to SnapshotEntry(hash = "abc", title = "long file"))
        store.save(longName, entries)
        val name = store.fileFor(longName).name
        assertTrue(name.length <= 69, "sha256 hex + .json, bounded: $name")
        assertFalse(name.contains('/'))
        assertEquals(entries, store.load(longName))
        // A second save cycles the tmp file without ENAMETOOLONG.
        store.save(longName, entries)
        assertEquals(entries, store.load(longName))
        assertEquals(listOf(longName), store.trackedFiles())
    }

    @Test
    fun `legacy url-encoded snapshots migrate on read without re-emitting`() {
        val store = SnapshotStore(Files.createTempDirectory("harness-snap").toFile())
        val relative = "journals/2026-11/10.org"
        val entries = mapOf(
            "4.2" to SnapshotEntry(hash = "rev1", orgId = "id1", title = "Morning")
        )
        // Hand-write a pre-hash (URL-encoded-name) snapshot.
        val legacy = java.io.File(
            store.fileFor(relative).parentFile,
            java.net.URLEncoder.encode(relative, "UTF-8") + ".json"
        )
        legacy.writeText(
            """{"file":"journals/2026-11/10.org",""" +
                """"entries":{"4.2":{"hash":"rev1","orgId":"id1","title":"Morning"}}}"""
        )
        val loaded = store.load(relative)
        assertEquals(entries, loaded, "legacy state survives migration")
        assertFalse(legacy.exists(), "migrated away from the long name")
        assertTrue(store.fileFor(relative).isFile)
        assertEquals(listOf(relative), store.trackedFiles())
        // A resave keeps the hash file authoritative (no re-emissions).
        store.save(relative, entries)
        assertEquals(entries, store.load(relative))
    }
}

Producer diff tests

kotlin#+name: harness-producer-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/HarnessProducerTest.kt
package computer.whatthefuck.arcology.harness

import computer.whatthefuck.arcology.indexer.SyncthingAuthException
import computer.whatthefuck.arcology.indexer.SyncthingClient
import computer.whatthefuck.arcology.indexer.SyncthingEvent
import computer.whatthefuck.arcology.indexer.SyncthingEventData
import computer.whatthefuck.arcology.indexer.SyncthingFolder
import computer.whatthefuck.arcology.indexer.SYNCTHING_LOCAL_CHANGE
import computer.whatthefuck.arcology.indexer.SYNCTHING_REMOTE_CHANGE
import computer.whatthefuck.arcology.llm.enumerateHeadings
import computer.whatthefuck.arcology.llm.headingRevision
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.contentOrNull
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive
import java.io.File
import java.nio.file.Files
import kotlin.test.*

private fun localEvent(id: Long, path: String, action: String = "modified", modifiedBy: String? = null) =
    SyncthingEvent(
        id = id,
        type = if (modifiedBy == null) SYNCTHING_LOCAL_CHANGE else SYNCTHING_REMOTE_CHANGE,
        data = SyncthingEventData(
            path = path, folder = "org-folder", action = action,
            itemType = "file", modifiedBy = modifiedBy,
        ),
    )

private fun fakeClient(
    folders: List<SyncthingFolder> = listOf(SyncthingFolder("org-folder", "Org", "/tmp/does-not-matter")),
    seededEventId: Long? = 0,
    steps: MutableList<List<SyncthingEvent>> = mutableListOf(),
    latestSeeds: Int = 1,
) : SyncthingClient {
    val queue = ArrayDeque(steps.map { it.toList() })
    var latestCalls = 0
    return object : SyncthingClient {
        override suspend fun folders() = folders
        override suspend fun events(since: Long, timeoutSeconds: Int): List<SyncthingEvent> =
            queue.removeFirstOrNull() ?: emptyList()
        override suspend fun latestEventId(): Long? {
            if (latestCalls++ < latestSeeds) return seededEventId
            return null
        }
    }
}

/** A pass-through risk stamper: no endpoint, so every event stamps
 * fail-closed (max=null, gated=true) — never blocks the spool. */
internal fun stamper() = ProducerRiskClassifier(
    endpoint = null, model = "test", threshold = 0.40,
    cacheFile = null, httpClient = io.ktor.client.HttpClient { },
)

private fun producer(stateRoot: File, orgDir: File) = HarnessProducer(
    stateRoot = stateRoot, orgDir = orgDir, stamper = stamper(),
    now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
    log = { },
)

class HarnessProducerTest {
    private lateinit var state: File
    private lateinit var org: File
    private val fixture = """
,#+TITLE: Producer fixture

,* First
First body.

,* Second
Second body.
""".trimIndent()

    @BeforeTest
    fun setup() {
        state = Files.createTempDirectory("harness-state").toFile()
        org = Files.createTempDirectory("harness-org").toFile()
        java.nio.file.Files.createDirectories(File(org, "journals/2026-11").toPath())
    }

    private fun writeFile(relative: String, content: String) {
        File(org, relative).writeText(content)
    }

    private fun spoolLines(state: File): List<Pair<Long, String>> =
        SpoolWriter(state).readEvents().map { it.seq to "${it.action} ${it.identity.key}" }

    @Test
    fun `startup walk spools added events for every heading`() = kotlinx.coroutines.test.runTest {
        // Legacy emission semantics: --emit-initial-events on an empty
        // store. The S0.5 default is the baseline (new tests below).
        writeFile("journals/2026-11/10.org", fixture)
        val p = producer(state, org)
        assertEquals(2, p.fullWalk("startup", BootstrapMode.FULL_EMIT))
        assertEquals(
            listOf(
                1L to "added journals/2026-11/10.org::1",
                2L to "added journals/2026-11/10.org::2",
            ),
            spoolLines(state)
        )
        assertEquals(1, p.snapshotCount())
    }

    @Test
    fun `restart with unchanged tree spools zero duplicates`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        producer(state, org).fullWalk("startup", BootstrapMode.FULL_EMIT)
        assertEquals(2, spoolLines(state).size)
        // A fully restarted producer: fresh SpoolWriter / SnapshotStore
        // instances against the same state root. Hash-diff dedupes.
        assertEquals(0, producer(state, org).fullWalk("startup", BootstrapMode.FULL_EMIT))
        assertEquals(2, spoolLines(state).size, "restart must not re-emit revisions")
        assertTrue(spoolLines(state).all { it.second.startsWith("added") })
    }

    @Test
    fun `revised event on body change carries new revision hash`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        // Legacy emission start: this is a diff/seq-semantics test; the
        // baseline path has its own tests below.
        producer(state, org).fullWalk("startup", BootstrapMode.FULL_EMIT)
        writeFile(
            "journals/2026-11/10.org",
            fixture.replace("Second body.", "Second body, revised.")
        )
        assertEquals(1, producer(state, org).fullWalk("reconcile"))
        assertEquals(
            listOf(3L to "revised journals/2026-11/10.org::2"),
            spoolLines(state).drop(2)
        )
    }

    @Test
    fun `deleted heading spools deletion with old title and key`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        producer(state, org).fullWalk("startup")
        // NOTE: the patterns here match the TANGLED (uncommaed) text; the
        // trimIndent'd fixture carries no trailing newline, so the pattern
        // strips the last heading by its bare two lines.
        val pruned = fixture.replace("* Second\nSecond body.", "")
        writeFile("journals/2026-11/10.org", pruned)
        assertEquals(1, producer(state, org).fullWalk("reconcile"))
        val events = SpoolWriter(state).readEvents()
        val deleted = events.last()
        assertEquals("deleted", deleted.action)
        assertEquals("journals/2026-11/10.org::2", deleted.identity.key)
        assertEquals("Second", deleted.title)
        assertEquals("", deleted.body)
    }

    @Test
    fun `vanished file removes snapshot state-ahead and spools deletions`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        producer(state, org).fullWalk("startup")
        File(org, "journals/2026-11/10.org").delete()
        assertEquals(2, producer(state, org).fullWalk("reconcile"))
        assertTrue(spoolLines(state).drop(2)
            .all { it.second.startsWith("deleted") })
        assertEquals(0, producer(state, org).snapshotCount())
    }

    @Test
    fun `org-id move spools the refile pair deleted then added`() = kotlinx.coroutines.test.runTest {
        val before = """
,#+TITLE: Refile fixture

,* Alpha
:PROPERTIES:
:ID: alpha-id
:END:
Alpha body.

,* Beta
Beta body.
""".trimIndent()
        val after = """
,#+TITLE: Refile fixture

,* Beta
Beta body.

,* Alpha
:PROPERTIES:
:ID: alpha-id
:END:
Alpha body.
""".trimIndent()
        writeFile("r.org", before)
        producer(state, org).fullWalk("startup", BootstrapMode.FULL_EMIT)
        writeFile("r.org", after)
        // Alpha (ID-bearing) moved from outline 1 to 2, its content intact:
        // refile = deleted(old key) + added(new key), adjacent. Beta (ID-less)
        // shifted slots 2→1 under it: honest (file, outline) turnover events.
        assertEquals(4, producer(state, org).fullWalk("reconcile"))
        val events = SpoolWriter(state).readEvents().drop(2)
        // The refile pair, adjacent:
        assertEquals("deleted", events[0].action)
        assertEquals("r.org::1", events[0].identity.key)
        assertEquals("Alpha", events[0].title)
        assertEquals("added", events[1].action)
        assertEquals("r.org::2", events[1].identity.key)
        assertEquals("alpha-id", events[1].identity.orgId)
        // The displaced ID-less heading's slot turnover:
        assertEquals(
            listOf("r.org::1", "r.org::2"),
            events.drop(2).map { it.identity.key }
        )
        assertEquals(
            listOf("added", "deleted"),
            events.drop(2).map { it.action }
        )
    }

    @Test
    fun `id-less sibling shift honestly re-reports as revisions`() = kotlinx.coroutines.test.runTest {
        writeFile("r.org", fixture)
        producer(state, org).fullWalk("startup", BootstrapMode.FULL_EMIT)
        // Replacement patterns match the tangled (uncommaed) text.
        writeFile(
            "r.org",
            fixture.replace("* First", "* Preamble\nPreamble body.\n\n* First")
        )
        // Insert above: every ID-less outline shifts position — the new
        // first heading is added; the shifted ones report as revised at
        // their (file, outline) identity. Give mobile headings :ID:s.
        assertEquals(3, producer(state, org).fullWalk("reconcile"))
        val actions = SpoolWriter(state).readEvents().drop(2).map { it.action }
        // Emission order is outline-sorted: slots 1 and 2 see different
        // content, slot 3 appears.
        assertEquals(listOf("revised", "revised", "added"), actions)
    }

    @Test
    fun `scope bucket comes from the first tree segment`() {
        assertEquals("journal", scopeFor("journals/2026-11/10.org"))
        assertEquals("root", scopeFor("index.org"))
        assertEquals("task", scopeFor("tasks/plan.org"))
    }

    @Test
    fun `production stamps carry modified_by and fixed ts`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        producer(state, org).fullWalk("startup", BootstrapMode.FULL_EMIT)
        val events = SpoolWriter(state).readEvents()
        assertTrue(events.all { it.modifiedBy == "startup" })
        assertTrue(events.all { it.ts == "2026-11-10T08:12:03-08:00" })
        assertTrue(events.all { it.risk.gated }, "no endpoint: fail-closed stamps")
    }

    @Test
    fun `spool bodies cap past max-body-bytes while revisions hash the full text`() = kotlinx.coroutines.test.runTest {
        val capped = """
#+TITLE: Capped

,* Capped heading
word word word word word word word word word word tail end.
""".trimIndent()
        writeFile("cap.org", capped)
        val p = HarnessProducer(
            stateRoot = state, orgDir = org, stamper = stamper(),
            now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
            log = { }, maxBodyBytes = 30,
        )
        assertEquals(1, p.fullWalk("startup", BootstrapMode.FULL_EMIT))
        val event = SpoolWriter(state).readEvents().single()
        assertTrue(event.body.contains("[truncated at 30 bytes]"), "explicit marker: ${event.body}")
        assertFalse(event.body.contains("tail end."), "beyond-cap text stays out of the line")
        // Identity is NOT the truncated line: the revision covers the
        // full heading text.
        val fullRecord = enumerateHeadings("cap.org", capped).single()
        assertEquals(headingRevision(fullRecord), event.revision, "revision over full text")
    }

    @Test
    fun `spool body cap cuts on a UTF-8 boundary`() = kotlinx.coroutines.test.runTest {
        val unicode = """
#+TITLE: Utf8

,* Café heading
café café café café café café café short tail.
""".trimIndent()
        writeFile("utf8.org", unicode)
        val p = HarnessProducer(
            stateRoot = state, orgDir = org, stamper = stamper(),
            now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
            log = { }, maxBodyBytes = 7,
        )
        assertEquals(1, p.fullWalk("startup", BootstrapMode.FULL_EMIT))
        val event = SpoolWriter(state).readEvents().single()
        assertTrue(event.body.startsWith("café c"), "byte-boundary cut, no mojibake: ${event.body}")
        assertTrue(event.body.contains("[truncated at 7 bytes]"))
    }

    @Test
    fun `max-depth rolls deep headings into the kept ancestor's spool events`() = kotlinx.coroutines.test.runTest {
        val deep = """
#+TITLE: Deep

,* Top
Top body.

,** Mid
Mid body.

,*** Leaf
Leaf body.
""".trimIndent()
        writeFile("deep.org", deep)
        val p = HarnessProducer(
            stateRoot = state, orgDir = org, stamper = stamper(),
            now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
            log = { }, maxDepth = 2,
        )
        assertEquals(2, p.fullWalk("startup", BootstrapMode.FULL_EMIT), "one event per heading at level ≤ 2")
        val events = SpoolWriter(state).readEvents()
        assertEquals(
            listOf("deep.org::1", "deep.org::1.1"),
            events.map { it.identity.key }
        )
        // The leaf text rides the level-2 event's body: no content loss.
        val mid = events.last()
        assertTrue(mid.body.contains("Mid body."))
        assertTrue(mid.body.contains("*** Leaf") && mid.body.contains("Leaf body."))
        // A deep edit moves the ANCESTOR's revision, not a leaf event.
        writeFile(
            "deep.org",
            deep.replace("Leaf body.", "Leaf body, edited.")
        )
        assertEquals(1, p.fullWalk("reconcile"))
        val revised = SpoolWriter(state).readEvents().last()
        assertEquals("revised", revised.action)
        assertEquals("deep.org::1.1", revised.identity.key)
    }

    @Test
    fun `cold start baselines - zero events, one marker, snapshots seeded`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        writeFile("index.org", """
#+TITLE: Solo

,* Solo heading
Solo body.
""".trimIndent())
        val p = producer(state, org)
        assertEquals(0, p.fullWalk("startup"), "the S0.5 default is baseline: no per-heading events")
        val events = SpoolWriter(state).readEvents()
        assertTrue(events.isEmpty(), "zero events from the baseline walk")
        val lines = File(state, "spool/2026-11.ndjson").readLines()
        assertEquals(1, lines.size, "exactly one audit marker")
        assertTrue(SpoolWriter.isMarkerLine(lines[0]))
        val marker = kotlinx.serialization.json.Json.parseToJsonElement(lines[0]).jsonObject
        assertEquals(
            "baseline",
            marker["type"]?.jsonPrimitive?.contentOrNull,
        )
        assertEquals(2, marker["files"]?.jsonPrimitive?.contentOrNull?.toInt())
        assertEquals(3, marker["headings"]?.jsonPrimitive?.contentOrNull?.toInt())
        assertEquals(0L, marker["head_seq"]?.jsonPrimitive?.contentOrNull?.toLong())
        assertNotNull(marker["ts"])
        assertEquals(2, p.snapshotCount(), "every tracked file seeded")
    }

    @Test
    fun `no implicit re-baseline after establishment`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        val p = producer(state, org)
        p.fullWalk("startup") // baseline: empty store
        assertEquals(1, spoolFileLines().count { SpoolWriter.isMarkerLine(it) }, "one marker after baseline")

        writeFile(
            "journals/2026-11/10.org",
            fixture.replace("Second body.", "Second body, edited.")
        )
        assertEquals(1, p.fullWalk("reconcile"), "events flow from now forward")
        val events = SpoolWriter(state).readEvents()
        assertEquals(listOf("revised"), events.map { it.action })
        assertEquals(
            1,
            spoolFileLines().count { SpoolWriter.isMarkerLine(it) },
            "established stores are never re-baselined implicitly"
        )
    }

    private fun spoolFileLines(): List<String> =
        File(state, "spool").listFiles()
            ?.filter { it.name.endsWith(".ndjson") }
            ?.flatMap { it.readLines().filter { l -> l.isNotBlank() } }
            ?: emptyList()

    @Test
    fun `explicit baseline re-seeds an established store`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        val p = producer(state, org)
        p.fullWalk("startup") // baseline #1
        writeFile(
            "journals/2026-11/10.org",
            fixture.replace("Second body.", "Second body, edited.")
        )
        assertEquals(0, p.fullWalk("reconcile", BootstrapMode.BASELINE), "forced baseline emits zero events")
        assertEquals(
            2,
            spoolFileLines().count { SpoolWriter.isMarkerLine(it) },
            "one marker per baseline"
        )
        // Snapshots match the CURRENT disk state: a follow-up auto walk
        // re-differs clean and emits nothing.
        assertEquals(0, p.fullWalk("reconcile"))
        assertTrue(SpoolWriter(state).readEvents().isEmpty())
        assertEquals(2, spoolFileLines().count { SpoolWriter.isMarkerLine(it) })
    }

    @Test
    fun `baseline restart re-seeds with zero duplicates and one more marker`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        val p = producer(state, org)
        p.fullWalk("startup", BootstrapMode.BASELINE)
        val restart = producer(state, org)
        restart.fullWalk("reconcile", BootstrapMode.BASELINE)
        assertTrue(SpoolWriter(state).readEvents().isEmpty(), "no duplicate revisions across baseline restarts")
        assertEquals(2, spoolFileLines().count { SpoolWriter.isMarkerLine(it) })
    }

    // ── .arcologyignore scope semantics (indexer-mirror) ──────────────
    // Ignore fixture files use \n-escaped single-line strings: their
    // content lines stay mid-line in the tangled source, so no tangle
    // comma escaping applies (the org fixture reuses the escaped val).

    @Test
    fun `walk ignores the agents subtree and collects ignore files`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        java.nio.file.Files.createDirectories(File(org, "agents/dev-planner").toPath())
        File(org, "agents/dev-planner/CLASSIFIER.org").writeText(fixture)
        // Root-scope ignore, bare-dir pattern: the walk must not track
        // the agents subtree, but the unfiltered discovery still sees it
        // (the vanished sweep's truth), and the ignore file is collected.
        File(org, ".arcologyignore").writeText("agents\n")
        val walk = listOrgFilesWithIgnores(org)
        assertEquals(listOf("journals/2026-11/10.org"), walk.files.map { it.first })
        assertEquals(
            listOf("agents/dev-planner/CLASSIFIER.org", "journals/2026-11/10.org"),
            walk.allDiscovered.map { it.first }
        )
        assertEquals(mapOf("" to "agents\n"), walk.ignoreFiles)
    }

    @Test
    fun `nested arcologyignore excludes only within its anchor`() = kotlinx.coroutines.test.runTest {
        java.nio.file.Files.createDirectories(File(org, "agents/dev-planner").toPath())
        java.nio.file.Files.createDirectories(File(org, "agents/literate-coder").toPath())
        java.nio.file.Files.createDirectories(File(org, "site").toPath())
        File(org, "agents/dev-planner/CLASSIFIER.org").writeText(fixture)
        File(org, "agents/literate-coder/CLASSIFIER.org").writeText(fixture)
        File(org, "agents/dev-planner-tasks.org").writeText(fixture)
        File(org, "site/outside.org").writeText(fixture)
        File(org, "agents/.arcologyignore").writeText("dev-planner\n")
        val walk = listOrgFilesWithIgnores(org)
        assertEquals(
            listOf(
                "agents/dev-planner-tasks.org",
                "agents/literate-coder/CLASSIFIER.org",
                "site/outside.org",
            ),
            walk.files.map { it.first },
            "the anchor-scoped pattern ignores only the dev-planner subtree"
        )
        assertEquals("dev-planner\n", walk.ignoreFiles["agents"])
        assertNull(walk.ignoreFiles[""])
    }

    @Test
    fun `dir entry pattern covers deeper files gitignore style`() = kotlinx.coroutines.test.runTest {
        java.nio.file.Files.createDirectories(File(org, "agents/dev-planner").toPath())
        java.nio.file.Files.createDirectories(File(org, "site").toPath())
        File(org, "agents/dev-planner/CLASSIFIER.org").writeText(fixture)
        File(org, "agents/tasks.org").writeText(fixture)
        File(org, "site/x.org").writeText(fixture)
        // agents-star (root pattern, bare star) matches the
        // agents/dev-planner DIRECTORY entry, not the two-segment file
        // path — the ancestor test carries the gitignore dir-exclusion
        // semantics without descent pruning.
        File(org, ".arcologyignore").writeText("agents/*\n")
        val walk = listOrgFilesWithIgnores(org)
        assertEquals(listOf("site/x.org"), walk.files.map { it.first })
    }

    @Test
    fun `event inside an ignored scope produces nothing`() = kotlinx.coroutines.test.runTest {
        java.nio.file.Files.createDirectories(File(org, "agents/dev-planner").toPath())
        File(org, "agents/dev-planner/CLASSIFIER.org").writeText(fixture)
        File(org, "journals/2026-11/10.org").writeText(fixture)
        File(org, ".arcologyignore").writeText("agents\n")
        val p = producer(state, org)
        val svc = HarnessProduceService(
            client = fakeClient(), producer = p, orgDir = org.path,
            folderId = "org-folder", log = { },
        )
        val folder = SyncthingFolder("org-folder", "Org", org.path)
        svc.processBatch(
            listOf(localEvent(1, "agents/dev-planner/CLASSIFIER.org")),
            folder,
        )
        assertTrue(SpoolWriter(state).readEvents().isEmpty(), "ignored scope: no events")
        assertEquals(0, p.snapshotCount(), "ignored scope: no snapshot writes")
        // Control: the same change outside the ignored scope produces.
        svc.processBatch(
            listOf(localEvent(2, "journals/2026-11/10.org")),
            folder,
        )
        assertEquals(listOf("added", "added"), SpoolWriter(state).readEvents().map { it.action })
    }

    @Test
    fun `arcologyignore event refreshes the scope for the rest of the batch`() = kotlinx.coroutines.test.runTest {
        java.nio.file.Files.createDirectories(File(org, "agents/dev-planner").toPath())
        java.nio.file.Files.createDirectories(File(org, "journals/2026-11").toPath())
        File(org, "agents/dev-planner/CLASSIFIER.org").writeText(fixture)
        File(org, "journals/2026-11/10.org").writeText(fixture)
        val p = producer(state, org)
        val svc = HarnessProduceService(
            client = fakeClient(), producer = p, orgDir = org.path,
            folderId = "org-folder", log = { },
        )
        val folder = SyncthingFolder("org-folder", "Org", org.path)
        // One batch, in encounter order: the ignore file lands FIRST, so
        // the change under it — arriving AFTER it — must be suppressed.
        File(org, ".arcologyignore").writeText("agents\n")
        svc.processBatch(
            listOf(
                localEvent(1, ".arcologyignore"),
                localEvent(2, "agents/dev-planner/CLASSIFIER.org"),
                localEvent(3, "journals/2026-11/10.org"),
            ),
            folder,
        )
        // The ignore file itself spools nothing; the journals change
        // processes; the agents change produces nothing.
        assertEquals(
            listOf("added", "added"),
            SpoolWriter(state).readEvents().map { it.action }
        )
        assertTrue(
            SpoolWriter(state).readEvents().all { it.file == "journals/2026-11/10.org" }
        )
    }

    @Test
    fun `scope change is silent and the snapshot survives until un-ignore`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        producer(state, org).fullWalk("startup")
        File(org, ".arcologyignore").writeText("journals\n")
        val p = producer(state, org)
        assertEquals(0, p.fullWalk("reconcile"), "ignored scope: no events")
        assertTrue(SpoolWriter(state).readEvents().isEmpty())
        // No deleted masquerade: the snapshot stays in place as the
        // hash-diff baseline for an un-ignore.
        assertEquals(
            true,
            SnapshotStore(state).fileFor("journals/2026-11/10.org").isFile,
            "scope change keeps the snapshot (no silent state churn)"
        )
        // Un-ignored: revise while ignored, then resolve — the hash-diff
        // resumes with exactly ONE revised event, no added flood.
        File(org, ".arcologyignore").delete()
        writeFile(
            "journals/2026-11/10.org",
            fixture.replace("Second body.", "Second body, edited.")
        )
        assertEquals(1, p.fullWalk("reconcile"))
        // The spool carried zero events (baseline seeded silently), so
        // the resumed revision is seq 1.
        assertEquals(
            listOf(1L to "revised journals/2026-11/10.org::2"),
            spoolLines(state)
        )
    }

    @Test
    fun `a file that vanishes inside a now-ignored scope still spools deletions`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        producer(state, org).fullWalk("startup")
        // Scope narrows AND the file leaves, in one gap: the sweep runs
        // on unfiltered discovery, so the corpus exit is recorded even
        // though the path is now ignored.
        File(org, ".arcologyignore").writeText("journals\n")
        File(org, "journals/2026-11/10.org").delete()
        assertEquals(2, producer(state, org).fullWalk("reconcile"))
        val lines = spoolLines(state)
        assertEquals(2, lines.size, "the corpus exit is recorded")
        assertTrue(
            lines.all { it.second.startsWith("deleted") },
            "ignore scope suppresses noise about files that exist, never exits"
        )
        assertEquals(0, producer(state, org).snapshotCount())
    }

    @Test
    fun `baseline seeds and counts only the filtered corpus`() = kotlinx.coroutines.test.runTest {
        writeFile("journals/2026-11/10.org", fixture)
        java.nio.file.Files.createDirectories(File(org, "agents/dev-planner").toPath())
        File(org, "agents/dev-planner/CLASSIFIER.org").writeText(fixture)
        File(org, ".arcologyignore").writeText("agents\n")
        val p = producer(state, org)
        assertEquals(0, p.fullWalk("startup", BootstrapMode.BASELINE))
        assertEquals(1, p.snapshotCount(), "only the tracked corpus is snapshotted")
        // The baseline marker's counts are post-ignore: 1 file, 2 headings.
        val marker = spoolFileLines().first { SpoolWriter.isMarkerLine(it) }
        val parsed = Json.parseToJsonElement(marker).jsonObject
        assertEquals(
            "1",
            (parsed["files"] as kotlinx.serialization.json.JsonPrimitive).content,
        )
        assertEquals(
            "2",
            (parsed["headings"] as kotlinx.serialization.json.JsonPrimitive).content,
        )
        assertEquals(
            "0",
            (parsed["head_seq"] as kotlinx.serialization.json.JsonPrimitive).content,
        )
    }
}

class HarnessProduceServiceTest {
    private lateinit var state: File
    private lateinit var org: File

    @BeforeTest
    fun setup() {
        state = Files.createTempDirectory("harness-svc-state").toFile()
        org = Files.createTempDirectory("harness-svc-org").toFile()
    }

    private fun service(
        client: SyncthingClient,
        rescanSeconds: Long = 0,
        bootstrapMode: BootstrapMode = BootstrapMode.FULL_EMIT,
    ) =
        HarnessProduceService(
            client = client,
            producer = HarnessProducer(state, org, stamper(),
                now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
                log = { }),
            orgDir = org.path,
            folderId = "org-folder",
            pollTimeoutSeconds = 10,
            rescanIntervalSeconds = rescanSeconds,
            initialBackoffMs = 1, maxBackoffMs = 4,
            log = { },
            bootstrapMode = bootstrapMode,
        )

    @Test
    fun `startup full walks then seeds cursor in the disk subscription`() = kotlinx.coroutines.test.runTest {
        val client = fakeClient(seededEventId = 7)
        val svc = service(client)
        val folder = svc.startup()
        assertEquals("org-folder", folder.id)
        assertEquals(7L, svc.currentCursor())
    }

    @Test
    fun `watch processes event batches and advances cursor`() = kotlinx.coroutines.test.runTest {
        File(org, "note.org").writeText("""
,#+TITLE: t

,* Watched
Watched body.
""".trimIndent())
        val client = fakeClient(seededEventId = 0, steps = mutableListOf(
            // Startup full walk spools note.org; the subsequent modified
            // event re-diffs it (no change) and a deleted event for an
            // untracked file produces nothing.
            listOf(localEvent(1, "note.org")),
            listOf(localEvent(2, "other.org", action = "deleted")),
        ))
        val svc = service(client)
        svc.watch(maxIterations = 2)
        assertEquals(2L, svc.currentCursor())
        val actions = SpoolWriter(state).readEvents().map { it.action }
        assertEquals(listOf("added"), actions)
    }

    @Test
    fun `event delete for a tracked file dispatches deletions`() = kotlinx.coroutines.test.runTest {
        File(org, "note.org").writeText("""
,#+TITLE: t

,* Watched
Watched body.
""".trimIndent())
        val client = fakeClient(seededEventId = 0, steps = mutableListOf(
            listOf(localEvent(1, "note.org", action = "deleted")),
        ))
        val svc = service(client)
        svc.watch(maxIterations = 1)
        // Startup walk spooled it as added; the delete event then spool
        // the deletion pair (removed state-ahead) and the file untracks.
        val actions = SpoolWriter(state).readEvents().map { it.action }
        assertEquals(listOf("added", "deleted"), actions)
        assertEquals(0, HarnessProducer(state, org, stamper()).snapshotCount())
    }

    @Test
    fun `remote events carry their device as modified_by`() = kotlinx.coroutines.test.runTest {
        File(org, "note.org").writeText("""
,#+TITLE: t

,* Watched
Watched body.
""".trimIndent())
        // The startup walk stamps modified_by=startup; drive the EVENT
        // path directly so the device from the event payload rides the
        // freshly diffed event.
        HarnessProducer(
            state, org, stamper(),
            now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
            log = { },
        ).processFile("note.org", File(org, "note.org"), "startup")
        File(org, "note.org").writeText("""
,#+TITLE: t

,* Watched
Watched body, changed on the peer.
""".trimIndent())
        val client = fakeClient(seededEventId = 0)
        val svc = service(client)
        svc.processBatch(
            listOf(localEvent(1, "note.org", modifiedBy = "BPDFDTU")),
            SyncthingFolder("org-folder", null, org.path),
        )
        val events = SpoolWriter(state).readEvents()
        assertEquals(listOf("added", "revised"), events.map { it.action })
        assertEquals("BPDFDTU", events.last().modifiedBy)
    }

    @Test
    fun `watch runs reconciliation pass on idle`() = kotlinx.coroutines.test.runTest {
        val client = fakeClient(seededEventId = 0)
        val logs = mutableListOf<String>()
        val svc = HarnessProduceService(
            client = client,
            producer = HarnessProducer(
                state, org, stamper(),
                now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
                log = { logs.add(it) },
            ),
            orgDir = org.path, folderId = "org-folder",
            pollTimeoutSeconds = 10, rescanIntervalSeconds = 30,
            initialBackoffMs = 1, maxBackoffMs = 4, log = { logs.add(it) },
        )
        svc.watch(maxIterations = 5)
        assertTrue(logs.any { it.contains("Idle for ~30 s; running reconciliation produce pass") })
    }

    @Test
    fun `batch dedupes with delete-wins and relativizes absolute paths`() = kotlinx.coroutines.test.runTest {
        File(org, "j.org").writeText("""
,#+TITLE: t

,* Watched
Watched body.
""".trimIndent())
        // Track the file first (full-emit startup walk); then one batch
        // carrying a modify + delete for it resolves delete-wins to one
        // deletion.
        val producer = HarnessProducer(
            state, org, stamper(),
            now = { java.time.OffsetDateTime.parse("2026-11-10T08:12:03-08:00") },
            log = { },
        )
        producer.fullWalk("startup", BootstrapMode.FULL_EMIT)
        val client = fakeClient(seededEventId = 0)
        val svc = service(client)
        svc.processBatch(
            listOf(
                localEvent(1, org.path + "/j.org"),
                localEvent(2, "j.org", action = "deleted"),
                localEvent(3, "outside.org"),
            ),
            SyncthingFolder("org-folder", null, org.path),
        )
        val events = SpoolWriter(state).readEvents()
        assertEquals(listOf("added", "deleted"), events.map { it.action })
        assertFalse(events.any { it.file == "outside.org" }, "untracked vanish produces nothing")
    }

    @Test
    fun `start baselines an empty store without the syncthing poll`() = kotlinx.coroutines.test.runTest {
        File(org, "note.org").writeText("""
#+TITLE: Baseline svc

,* Watched
Watched body.
""".trimIndent())
        val client = fakeClient(seededEventId = 3, steps = mutableListOf(
            listOf(localEvent(1, "note.org")),
        ))
        val svc = service(client, bootstrapMode = BootstrapMode.AUTO)
        svc.watch(maxIterations = 1)
        assertTrue(SpoolWriter(state).readEvents().isEmpty(), "baseline: zero events")
        val lines = File(state, "spool/2026-11.ndjson").readLines()
        assertEquals(1, lines.count { SpoolWriter.isMarkerLine(it) }, "one audit marker")
        assertEquals(
            1,
            HarnessProducer(state, org, stamper()).snapshotCount(),
            "snapshots seeded"
        )
    }

    @Test
    fun `watch aborts on auth failure`() = kotlinx.coroutines.test.runTest {
        val client = object : SyncthingClient {
            // The startup path needs folders()+latestEventId(); the abort
            // happens on the first poll.
            override suspend fun folders() = listOf(
                SyncthingFolder("org-folder", null, org.path)
            )
            override suspend fun events(since: Long, timeoutSeconds: Int) =
                throw SyncthingAuthException("403")
            override suspend fun latestEventId(): Long? = 0
        }
        assertFailsWith<SyncthingAuthException> {
            service(client).watch(maxIterations = 1)
        }
    }
}

Syncthing client tests (codified pitfalls, copied)

kotlin#+name: harness-client-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/HarnessSyncthingClientTest.kt
package computer.whatthefuck.arcology.harness

import io.ktor.client.engine.mock.MockEngine
import io.ktor.client.engine.mock.respondOk
import io.ktor.http.*
import kotlinx.coroutines.test.runTest
import kotlin.test.*

class HarnessSyncthingClientTest {
    private fun diskEventsJson(ids: List<Long>) =
        ids.joinToString(",", "[", "]") { id ->
            """{"id":$id,"globalID":${id * 10},"time":"2026-01-01T00:00:00Z",""" +
                """"type":"LocalChangeDetected","data":{"path":"a.org","folder":"abc-def",""" +
                """"action":"modified","type":"file"}}"""
        }

    private fun capturedRequests(block: suspend (HarnessSyncthingClient) -> Unit): List<Url> {
        val urls = mutableListOf<Url>()
        val engine = MockEngine { request ->
            urls.add(request.url)
            respondOk(diskEventsJson(listOf(1)))
        }
        val client = HarnessSyncthingClient(
            baseUrl = "http://127.0.0.1:8384",
            apiKey = "test-key",
            pollTimeoutSeconds = 60,
            engine = engine,
        )
        // runBlocking: the calling tests are already runTest-wrapped, and
        // only one runTest per test is allowed.
        kotlinx.coroutines.runBlocking { block(client) }
        engine.close()
        return urls
    }

    @Test
    fun `events poll requests the disk-event mask with since and timeout`() = runTest {
        val urls = capturedRequests { it.events(42, 60) }
        assertEquals(1, urls.size)
        assertEquals("/rest/events", urls[0].encodedPath)
        assertEquals(
            "LocalChangeDetected,RemoteChangeDetected",
            urls[0].parameters["events"],
        )
        assertEquals("42", urls[0].parameters["since"])
        assertEquals("60", urls[0].parameters["timeout"])
    }

    @Test
    fun `latestEventId seeds from the same disk-event mask`() = runTest {
        // Per-subscription ids: a seed from a differently-masked
        // subscription stalls the poll forever. Copy of the syncthing.org
        // regression for the harness's OWN subscription.
        val urls = capturedRequests { it.latestEventId() }
        assertEquals(1, urls.size)
        assertEquals(
            "LocalChangeDetected,RemoteChangeDetected",
            urls[0].parameters["events"],
        )
        assertEquals("0", urls[0].parameters["since"])
        assertEquals("1", urls[0].parameters["limit"])
    }

    @Test
    fun `events decodes disk event json`() = runTest {
        val engine = MockEngine { respondOk(diskEventsJson(listOf(7))) }
        val client = HarnessSyncthingClient(
            "http://127.0.0.1:8384", "test-key", 60, engine,
        )
        assertEquals(listOf(7L), client.events(0, 60).map { it.id })
        engine.close()
    }

    @Test
    fun `client api key header is set`() = runTest {
        val headers = mutableListOf<String>()
        val engine = MockEngine { request ->
            headers.add(request.headers["X-API-Key"] ?: "")
            respondOk(diskEventsJson(listOf(1)))
        }
        val client = HarnessSyncthingClient(
            "http://127.0.0.1:8384", "sekrit", 60, engine,
        )
        client.events(0, 60)
        engine.close()
        assertTrue(headers.all { it == "sekrit" })
    }
}

Classifier config + verdict client tests

kotlin#+name: harness-verdict-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/AgentClassifierConfigTest.kt
package computer.whatthefuck.arcology.harness

import io.ktor.client.*
import io.ktor.client.engine.mock.*
import io.ktor.http.*
import java.nio.file.Files
import kotlin.test.*

class AgentClassifierConfigTest {
    // Fixture bodies are real multi-line Kotlin raw strings: every org
    // syntax line inside them starts at a line start, so each carries
    // the tangle comma escape (the leading comma before the stars).
    private val devPlanner = """
:PROPERTIES:
:ID: classifier-agent-dev-planner
:THRESHOLD: 0.80
:URGENCY: yes
:END:

,* should_act
does this heading ask the planner to produce or revise a plan

,** Level 4
a direct request to act now

,** Level 0
content of other lanes only

,** Level 2
plausibly this agent's work: its size or
sequence still open

,** Level 1
a recording of finished work

,** Level 3
a concrete task awaiting scoping

,* urgency
how time-critical is this request

,** Level 3
wanted today or tomorrow

,** Level 0
no time signal

,** Level 2
days of slack

,** Level 1
weeks of slack

,** Level 4
same-day deadline
""".trimIndent()

    @Test
    fun `parse reads threshold urgency and rubric levels out of order`() {
        val config = ClassifierConfigs.parse(
            "dev-planner", java.io.File("/agents/dev-planner/CLASSIFIER.org"), devPlanner
        )
        requireNotNull(config)
        assertEquals("dev-planner", config.agent)
        assertEquals(0.80, config.threshold)
        assertTrue(config.urgency)
        assertEquals(
            "does this heading ask the planner to produce or revise a plan",
            config.shouldAct,
            "instructions are the leading prose, never level text"
        )
        val criteria = config.shouldActCriteria
        assertEquals(5, criteria.size, "exactly one criterion per level 0..4")
        // File order was 4,0,2,1,3: criteria must come out in LEVEL order.
        assertEquals("content of other lanes only", criteria[0])
        assertEquals("a recording of finished work", criteria[1])
        assertTrue(criteria[2].contains("its size or"), criteria[2])
        assertTrue(criteria[2].contains("still open"), criteria[2])
        assertEquals("a concrete task awaiting scoping", criteria[3])
        assertEquals("a direct request to act now", criteria[4])
        assertEquals(
            "how time-critical is this request",
            config.urgencyQuestion
        )
        assertEquals(
            listOf(
                "no time signal",
                "weeks of slack",
                "days of slack",
                "wanted today or tomorrow",
                "same-day deadline",
            ),
            config.urgencyCriteria
        )
    }

    @Test
    fun `threshold defaults to 0_75 and urgency defaults off`() {
        val config = ClassifierConfigs.parse(
            "minimal", java.io.File("/agents/minimal/CLASSIFIER.org"),
            """
:PROPERTIES:
:ID: classifier-agent-minimal
:END:

,* should_act
does this mention the agent

,** Level 0
other lanes only

,** Level 1
a finished-work recording

,** Level 2
topic without concrete work

,** Level 3
concrete work awaiting

,** Level 4
direct request
""".trimIndent()
        )
        requireNotNull(config)
        assertEquals(0.65, config.threshold)
        assertFalse(config.urgency)
        assertNull(config.urgencyQuestion)
        assertNull(config.urgencyCriteria)
        assertEquals(5, config.shouldActCriteria.size)
    }

    @Test
    fun `missing should_act is unusable`() {
        assertNull(
            ClassifierConfigs.parse(
                "empty", java.io.File("/agents/empty/CLASSIFIER.org"),
                """
:PROPERTIES:
:THRESHOLD: 0.75
:END:

Just prose, no question section.
""".trimIndent()
            )
        )
        // URGENCY yes without an urgency section is equally unusable.
        assertNull(
            ClassifierConfigs.parse(
                "broken", java.io.File("/agents/broken/CLASSIFIER.org"),
                """
:PROPERTIES:
:URGENCY: yes
:END:

,* should_act
anything at all
""".trimIndent()
            )
        )
    }

    @Test
    fun `missing level 2 is unusable`() {
        assertNull(
            ClassifierConfigs.parse(
                "gap", java.io.File("/agents/gap/CLASSIFIER.org"),
                """
:PROPERTIES:
:END:

,* should_act
the question

,** Level 0
other lanes only

,** Level 1
a recording of finished work

,** Level 3
concrete work awaiting

,** Level 4
direct request
""".trimIndent()
            )
        )
    }

    @Test
    fun `duplicate level 3 is unusable`() {
        assertNull(
            ClassifierConfigs.parse(
                "twin", java.io.File("/agents/twin/CLASSIFIER.org"),
                """
:PROPERTIES:
:END:

,* should_act
the question

,** Level 0
other lanes only

,** Level 1
a recording of finished work

,** Level 3
concrete work awaiting

,** Level 3
the same level again

,** Level 4
direct request
""".trimIndent()
            )
        )
    }

    @Test
    fun `blank level body is unusable`() {
        assertNull(
            ClassifierConfigs.parse(
                "hollow", java.io.File("/agents/hollow/CLASSIFIER.org"),
                """
:PROPERTIES:
:END:

,* should_act
the question

,** Level 0
other lanes only

,** Level 1
a recording of finished work

,** Level 2

,** Level 3
concrete work awaiting

,** Level 4
direct request
""".trimIndent()
            )
        )
    }

    @Test
    fun `urgency section without levels is unusable`() {
        assertNull(
            ClassifierConfigs.parse(
                "flat-urgency", java.io.File("/agents/flat-urgency/CLASSIFIER.org"),
                """
:PROPERTIES:
:URGENCY: yes
:END:

,* should_act
the question

,** Level 0
other lanes only

,** Level 1
a recording of finished work

,** Level 2
a topic without work

,** Level 3
concrete work awaiting

,** Level 4
direct request

,* urgency
how time-critical is this request, prose only
""".trimIndent()
            )
        )
    }

    @Test
    fun `discover scans agent dirs sorted and skips unusable`() {
        val agentsDir = Files.createTempDirectory("harness-agents").toFile()
        java.io.File(agentsDir, "dev-planner").mkdirs()
        java.io.File(agentsDir, "dev-planner/CLASSIFIER.org").writeText(devPlanner)
        java.io.File(agentsDir, "make-legible").mkdirs()
        // NOTE: strings-as-\n-escapes carry their stars mid-line, so no
        // comma escaping applies here (uncomma only fires on line starts).
        java.io.File(agentsDir, "make-legible/CLASSIFIER.org").writeText(
            ":PROPERTIES:\n:THRESHOLD: 0.75\n:END:\n\n* should_act\nlegible prose question\n\n** Level 0\nother lanes only\n\n** Level 1\nprivate drafts\n\n** Level 2\npublishing discussion\n\n** Level 3\na page with a legibility problem\n\n** Level 4\na direct request to fix it\n"
        )
        // A malformed rubric (no Level 2) drops the agent at discovery.
        java.io.File(agentsDir, "broken-rubric").mkdirs()
        java.io.File(agentsDir, "broken-rubric/CLASSIFIER.org").writeText(
            ":PROPERTIES:\n:THRESHOLD: 0.75\n:END:\n\n* should_act\nquestion\n\n** Level 0\nother lanes\n\n** Level 1\nx\n\n** Level 3\ny\n"
        )
        java.io.File(agentsDir, "org-anizer").mkdirs() // no CLASSIFIER.org at all
        val configs = ClassifierConfigs.discover(agentsDir)
        assertEquals(listOf("dev-planner", "make-legible"), configs.map { it.agent })
    }

    // ── A3 wake policy: WAKE + knobs in the properties drawer ──────────

    private val wakeAgent = """
:PROPERTIES:
:ID: classifier-agent-wake-agent
:THRESHOLD: 0.75
:URGENCY: no
:WAKE: yes
:MAX_WAKES: 5
:MAX_URGENT_WAKES: 2
:MIN_WAKE_INTERVAL: 0
:END:

,* should_act
does this heading ask the agent to act

,** Level 0
other lanes only

,** Level 1
a recording of finished work

,** Level 2
discussion without concrete work

,** Level 3
a concrete task awaiting scoping

,** Level 4
a direct request to act now
""".trimIndent()

    private fun parseWakeFixture(content: String) = ClassifierConfigs.parse(
        "dev-planner", java.io.File("/agents/dev-planner/CLASSIFIER.org"), content
    )

    @Test
    fun `wake knobs parse from the properties drawer`() {
        val config = ClassifierConfigs.parse(
            "wake-agent", java.io.File("/agents/wake-agent/CLASSIFIER.org"), wakeAgent
        )
        requireNotNull(config)
        val on = config.wake as WakePolicy.On
        assertEquals(5, on.maxWakes)
        assertEquals(2, on.maxUrgentWakes)
        assertEquals(0L, on.minWakeIntervalMinutes)
    }

    @Test
    fun `wake defaults to off when the property is absent or garbage`() {
        val absent = requireNotNull(parseWakeFixture(devPlanner))
        assertEquals(WakePolicy.Off, absent.wake, "no WAKE property: fail-shut off")
        val garbage = requireNotNull(
            parseWakeFixture(devPlanner.replace(":URGENCY: yes", ":URGENCY: yes\n:WAKE: banana"))
        )
        assertEquals(WakePolicy.Off, garbage.wake, "garbage WAKE value: off, never a crash")
        val explicitNo = requireNotNull(
            parseWakeFixture(devPlanner.replace(":URGENCY: yes", ":URGENCY: yes\n:WAKE: no"))
        )
        assertEquals(WakePolicy.Off, explicitNo.wake)
    }

    @Test
    fun `malformed or negative wake knobs fail shut into Malformed`() {
        val badMax = requireNotNull(
            parseWakeFixture(devPlanner.replace(":URGENCY: yes", ":URGENCY: yes\n:WAKE: yes\n:MAX_WAKES: banana"))
        )
        assertTrue(badMax.wake is WakePolicy.Malformed)
        val negativeInterval = requireNotNull(
            parseWakeFixture(devPlanner.replace(":URGENCY: yes", ":URGENCY: yes\n:WAKE: yes\n:MIN_WAKE_INTERVAL: -5"))
        )
        assertTrue(negativeInterval.wake is WakePolicy.Malformed)
        val badUrgent = requireNotNull(
            parseWakeFixture(devPlanner.replace(":URGENCY: yes", ":URGENCY: yes\n:WAKE: yes\n:MAX_URGENT_WAKES: 3.5"))
        )
        assertTrue(badUrgent.wake is WakePolicy.Malformed)
        // Zero stays valid everywhere: MAX_WAKES=0 means hold the lane.
        val zeroed = requireNotNull(
            parseWakeFixture(devPlanner.replace(":URGENCY: yes", ":URGENCY: yes\n:WAKE: yes\n:MAX_WAKES: 0"))
        )
        assertEquals(0, (zeroed.wake as WakePolicy.On).maxWakes)
    }
}

Production risk + verdict client tests (embedded endpoint)

A name-aware fake /v1/systemone: it reads the question name the request asks (=health=…=/political= for the risk client, =should_act=/=urgency= for the drain's VerdictClassifier) and answers with the right shape for each — score answers everywhere, should_act included (the criteria-less yes-no shape died with the 2026-11-11 live 400) — counting requests so cache behavior is observable and recording the raw request bodies so the verdict-question tests pin the wire shape: type score with a non-empty 5-entry criteria array, for both should_act and urgency.

kotlin#+name: harness-risk-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/ProducerRiskClassifierTest.kt
package computer.whatthefuck.arcology.harness

import io.ktor.client.*
import io.ktor.client.plugins.*
import io.ktor.http.*
import io.ktor.server.cio.*
import io.ktor.server.engine.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.coroutines.test.runTest
import java.nio.file.Files
import java.util.concurrent.atomic.AtomicInteger
import kotlin.test.*

internal fun httpClient() = HttpClient {
    install(HttpTimeout) { requestTimeoutMillis = 5_000 }
}

class FakeDecisionServer(
    /** should_act rubric level (0..4): confidence = level / 4. */
    private val confidenceLevel: Double = 3.0,
    /** Rubric level (0..4) for urgency. */
    private val scoreLevel: Double = 1.0,
    /** Rubric level (0..4) for the five risk categories. */
    private val riskLevel: Double = 1.0,
) {
    private val port = java.net.ServerSocket(0).use { it.localPort }
    val requests = AtomicInteger(0)
    /** Raw request bodies — pinned by the wire-shape regression tests. */
    val requestBodies = java.util.concurrent.CopyOnWriteArrayList<String>()
    private val server = embeddedServer(CIO, host = "127.0.0.1", port = port) {
        routing {
            post("/v1/systemone") {
                requests.incrementAndGet()
                val req = call.receiveText()
                requestBodies.add(req)
                val asked = Regex(""""questions":\{"([A-Za-z_]+)""")
                    .find(req)?.groupValues?.get(1) ?: "should_act"
                val answer = when (asked) {
                    // should_act carries a probability map whose TAIL is
                    // exactly confidenceLevel/4 (mass only at 0 and 3), so
                    // tail-gate assertions keep the same numbers the old
                    // EV fake produced.
                    "should_act" -> {
                        val tail = confidenceLevel / 4.0
                        "{\"type\":\"score\",\"score\":$confidenceLevel," +
                            "\"legend\":{\"0\":\"Irrelevant\",\"4\":\"Act now\"}," +
                            "\"probabilities\":{\"0\":${1.0 - tail},\"3\":$tail},\"confidence\":0.6}"
                    }
                    "urgency" -> """{"type":"score","score":$scoreLevel,"legend":{"0":"None","4":"Dominated"}}"""
                    else -> """{"type":"score","score":$riskLevel,"legend":{"0":"None","4":"Dominated"},""" +
                        """"probabilities":{"0":0.5},"confidence":0.5}"""
                }
                call.respondText(
                    """{"model":"test","answers":{"$asked":$answer},"usage":{"input_tokens":10,"output_tokens":1}}""",
                    ContentType.Application.Json
                )
            }
        }
    }
    val endpoint = "http://127.0.0.1:$port"

    fun start() { server.start(wait = false) }
    fun stop() { server.stop(1000, 2000) }
}

class ProducerRiskClassifierTest {

    @Test
    fun `risk answers normalize levels into the 0-1 band`() = runTest {
        val server = FakeDecisionServer(riskLevel = 1.0)
        server.start()
        val stamper = ProducerRiskClassifier(
            endpoint = server.endpoint, model = "test", threshold = 0.40,
            cacheFile = null, httpClient = httpClient(),
        )
        // Every risk category answers level 1.0 of 4 → 0.25: ungated.
        val risk = stamper.stamp("plain daily note")
        assertEquals(0.25, risk.max)
        assertEquals(false, risk.gated)
        server.stop()
    }

    @Test
    fun `blank text mirrors the gate's blank-skip`() = runTest {
        val stamper = ProducerRiskClassifier(
            endpoint = null, model = "test", threshold = 0.40,
            cacheFile = null, httpClient = httpClient(),
        )
        val risk = stamper.stamp("   ")
        assertEquals(0.0, risk.max)
        assertEquals(false, risk.gated)
    }

    @Test
    fun `risk answer gates when it crosses the threshold`() = runTest {
        val server = FakeDecisionServer(riskLevel = 2.72)
        server.start()
        val stamper = ProducerRiskClassifier(
            endpoint = server.endpoint, model = "test", threshold = 0.40,
            cacheFile = null, httpClient = httpClient(),
        )
        val risk = stamper.stamp("private-ish content")
        assertEquals(0.68, risk.max, "level 2.72 of 4 → 0.68")
        assertTrue(risk.gated, "0.68 > 0.40 threshold")
        server.stop()
    }

    @Test
    fun `unreachable endpoint stamps fail-closed and does not cache`() = runTest {
        val cacheFile = Files.createTempDirectory("harness-cache").resolve("c.ndjson").toFile()
        val stamper = ProducerRiskClassifier(
            endpoint = "http://127.0.0.1:1", model = "test", threshold = 0.40,
            cacheFile = cacheFile, httpClient = httpClient(),
        )
        val risk = stamper.stamp("some private content")
        assertNull(risk.max)
        assertTrue(risk.gated, "unreachable ⇒ gated=true: fail closed")
        assertTrue(
            !cacheFile.exists() || cacheFile.readText().isBlank(),
            "fail-closed results are never cached"
        )
    }

    @Test
    fun `no endpoint configured stamps fail-closed`() = runTest {
        val stamper = ProducerRiskClassifier(
            endpoint = null, model = "test", threshold = 0.40,
            cacheFile = null, httpClient = httpClient(),
        )
        val risk = stamper.stamp("some private content")
        assertNull(risk.max)
        assertTrue(risk.gated)
    }

    @Test
    fun `cache hit skips the server entirely`() = runTest {
        val server = FakeDecisionServer(riskLevel = 1.0)
        server.start()
        val stamper = ProducerRiskClassifier(
            endpoint = server.endpoint, model = "test", threshold = 0.40,
            cacheFile = Files.createTempDirectory("harness-cache").resolve("c.ndjson").toFile(),
            httpClient = httpClient(),
        )
        val text = "the same text twice"
        val first = stamper.stamp(text)
        val after = server.requests.get()
        val second = stamper.stamp(text)
        assertEquals(after, server.requests.get(), "cache hit must not re-classify")
        assertEquals(first.max, second.max)
        server.stop()
    }
}

class VerdictClassifierTest {

    @Test
    fun `score decodes the rubric level normalized out of four`() = runTest {
        val server = FakeDecisionServer(scoreLevel = 3.0)
        server.start()
        val classifier = VerdictClassifier(server.endpoint, "test", httpClient())
        val result = classifier.score(
            "text", "urgency", "rubric text",
            listOf("n0", "n1", "n2", "n3", "n4")
        )
        assertTrue(result is VerdictResult.Score)
        assertEquals(0.75, result.score)
        // An answer without a probability map yields NO act tail —
        // urgency tolerates the gap; should_act fails closed on it.
        assertNull(result.probAtLeast3)
        server.stop()
    }

    /**
     * Seq-95 regression pin (2026-11-13): the measured kev4b distribution
     * for a development-ask heading — EV conf 0.686 (the old gate's input,
     * which vetoed) while 70.4% of the mass sits at levels >= 3. The act
     * statistic must report the TAIL, immune to low-level hedge mass.
     */
    @Test
    fun `the act statistic is the tail probability over levels 3 and 4`() = runTest {
        val port = java.net.ServerSocket(0).use { it.localPort }
        val server = embeddedServer(CIO, host = "127.0.0.1", port = port) {
            routing {
                post("/v1/systemone") {
                    call.respondText(
                        """{"model":"test","answers":{"should_act":{"type":"score",""" +
                            """"score":2.742898140957105,"probabilities":{""" +
                            """"0":0.14461174155756729,"1":0.047061592231193904,""" +
                            """"2":0.10389625683853415,"3":0.32967760244197586,""" +
                            """"4":0.37475280693072877}}}}""",
                        ContentType.Application.Json
                    )
                }
            }
        }
        server.start(wait = false)
        val classifier = VerdictClassifier("http://127.0.0.1:$port", "test", httpClient())
        val result = classifier.score(
            "text", "should_act", "ins", listOf("n0", "n1", "n2", "n3", "n4")
        )
        server.stop(1000, 2000)
        assertTrue(result is VerdictResult.Score)
        val s = result as VerdictResult.Score
        assertEquals(2.742898140957105 / 4.0, s.score, 1e-12)
        assertEquals(0.7044304093727046, s.probAtLeast3!!, 1e-12)
    }

    /**
     * Wire-shape regression pin (this bug's guard): both verdict
     * questions ride out as type=score with the non-empty 5-entry rubric
     * as criteria, and the criteria are parsed from a real CLASSIFIER.org
     * fixture — config files, not constants (the exact regression class
     * the live router rejected: a criteria-less yesno question type).
     */
    @Test
    fun `sends a score question with a non-empty 5-entry criteria array`() = runTest {
        val fixtureDir = Files.createTempDirectory("harness-pin").toFile()
        val agentDir = java.io.File(fixtureDir, "dev-planner").apply { mkdirs() }
        val fixture = java.io.File(agentDir, "CLASSIFIER.org")
        fixture.writeText("""
:PROPERTIES:
:URGENCY: yes
:END:

,* should_act
does it matter?

,** Level 0
file-fixture level-zero marker: other lanes only

,** Level 1
a tech-log recording finished work

,** Level 2
discussion without concrete work

,** Level 3
concrete work awaiting scoping

,** Level 4
direct request to act now

,* urgency
how time-critical is this

,** Level 0
file-fixture urgency level-zero marker: no time signal

,** Level 1
weeks of slack

,** Level 2
days of slack

,** Level 3
today or tomorrow

,** Level 4
same-day deadline
""".trimIndent())
        val config = requireNotNull(
            ClassifierConfigs.parse("dev-planner", fixture, fixture.readText())
        )
        val server = FakeDecisionServer()
        server.start()
        val classifier = VerdictClassifier(server.endpoint, "test", httpClient())
        assertTrue(
            classifier.score("text", "should_act", config.shouldAct, config.shouldActCriteria)
                is VerdictResult.Score
        )
        assertTrue(
            classifier.score(
                "text", "urgency", config.urgencyQuestion ?: "",
                config.urgencyCriteria ?: emptyList()
            ) is VerdictResult.Score
        )
        server.stop()
        assertEquals(2, server.requestBodies.size, "one pinned body per verdict question")
        assertTrue(
            server.requestBodies[0].contains("file-fixture level-zero marker"),
            "should_act criteria must carry the fixture's Level 0 text: ${server.requestBodies[0]}"
        )
        assertTrue(
            server.requestBodies[1].contains("urgency level-zero marker"),
            "urgency criteria must carry the fixture's Level 0 text: ${server.requestBodies[1]}"
        )
        for ((name, criteria, ins) in listOf(
            Triple("should_act", config.shouldActCriteria, config.shouldAct),
            Triple(
                "urgency", config.urgencyCriteria ?: emptyList(),
                config.urgencyQuestion ?: ""
            ),
        )) {
            val body = server.requestBodies.first { it.contains("\"$name\"") }
            val question = (((kotlinx.serialization.json.Json.parseToJsonElement(body)
                as kotlinx.serialization.json.JsonObject)["questions"])
                as kotlinx.serialization.json.JsonObject)[name]
                as kotlinx.serialization.json.JsonObject
            assertEquals(
                "score",
                (question["type"] as kotlinx.serialization.json.JsonPrimitive).content,
                "$name must be pinned to the score question type",
            )
            assertEquals(
                criteria,
                (question["criteria"] as kotlinx.serialization.json.JsonArray)
                    .map { (it as kotlinx.serialization.json.JsonPrimitive).content },
                "$name must pin the config file's parsed rubric as criteria",
            )
            assertEquals(
                ins,
                (question["instructions"] as kotlinx.serialization.json.JsonPrimitive).content,
            )
            assertFalse(body.contains("\"yesno\""), "the dead yes/no shape must never return")
        }
    }

    @Test
    fun `score answer missing the numeric score fails closed`() = runTest {
        val port = java.net.ServerSocket(0).use { it.localPort }
        val server = embeddedServer(CIO, host = "127.0.0.1", port = port) {
            routing {
                post("/v1/systemone") {
                    call.respondText(
                        """{"model":"test","answers":{"should_act":{"type":"score"}}}""",
                        ContentType.Application.Json
                    )
                }
            }
        }
        server.start(wait = false)
        val classifier = VerdictClassifier("http://127.0.0.1:$port", "test", httpClient())
        val result = classifier.score(
            "text", "should_act", "ins", listOf("n0", "n1", "n2", "n3", "n4")
        )
        assertTrue(result is VerdictResult.Unavailable)
        server.stop(1000, 2000)
    }
}

Drain tests

kotlin#+name: harness-drain-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/HarnessDrainTest.kt
package computer.whatthefuck.arcology.harness

import io.ktor.http.*
import io.ktor.server.cio.*
import io.ktor.server.engine.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import java.io.File
import java.nio.file.Files
import java.util.concurrent.atomic.AtomicInteger
import kotlin.test.*

private fun drainConfig(agent: String = "dev-planner", threshold: Double = 0.75, urgency: Boolean = false) =
    AgentClassifierConfig(
        agent = agent,
        configPath = File("/agents/$agent/CLASSIFIER.org"),
        threshold = threshold,
        urgency = urgency,
        shouldAct = "does this heading ask the planner to act",
        shouldActCriteria = listOf(
            "distinctive level-zero exclusion marker from the test config",
            "a recording of finished work",
            "discussion without concrete work",
            "concrete work awaiting scoping",
            "a direct request to act now",
        ),
        urgencyQuestion = if (urgency) "how urgent" else null,
        urgencyCriteria = if (urgency) listOf(
            "distinctive urgency level-zero marker: no time signal",
            "weeks of slack",
            "days of slack",
            "today or tomorrow",
            "same-day deadline",
        ) else null,
    )

private fun spoolEvent(
    seq: Long,
    file: String,
    title: String,
    body: String = "Body of $title.",
    ts: String = "2026-11-10T08:12:03-08:00",
) = SpoolEvent(
    ts = ts, scope = scopeFor(file), file = file,
    identity = SpoolIdentity(orgId = null, key = "$file::1"),
    action = "added", title = title, body = body,
    revision = "rev-$seq", risk = SpoolRisk(max = 0.1, gated = false),
    modifiedBy = "local",
)

/** Establish a cursor so the agent is NOT fresh: a fresh config
 * head-inits at the spool head and classifies nothing (S0.5). Tests
 * that exercise classification call this first. */
private fun seedCursorImpl(
    state: File,
    agent: String = "dev-planner",
    seq: Long = 0,
) {
    File(state, "cursors").mkdirs()
    File(state, "cursors/$agent.verdict").writeText("$seq\n")
}

/** Numeric read for the calibration-style assertions. */
private fun numConf(line: VerdictLogLine): Double =
    (line.confidence as kotlinx.serialization.json.JsonPrimitive).content.toDouble()

class HarnessDrainTest {
    private lateinit var state: File

    @BeforeTest
    fun setup() {
        state = Files.createTempDirectory("harness-drain").toFile()
    }

    private fun fillSpool(vararg events: SpoolEvent) {
        val writer = SpoolWriter(state)
        for (event in events) writer.append(event)
    }

    private fun verdictLines(): List<VerdictLogLine> =
        File(state, "verdicts").listFiles()
            ?.filter { it.name.endsWith(".ndjson") }
            ?.flatMap { it.readLines().filter { line -> line.isNotBlank() } }
            ?.mapNotNull { line ->
                runCatching {
                    VerdictJson.decodeFromString(VerdictLogLine.serializer(), line)
                }.getOrNull()
            }
            ?: emptyList()

    private fun drain(
        configs: List<AgentClassifierConfig>,
        classifier: VerdictClassifier?,
    ) = HarnessDrain(
        stateRoot = state, configs = configs, classifier = classifier,
        model = "test",
        now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
        log = { },
    )

    private fun readCursor(where: File, agent: String): Long =
        HarnessDrain(where, listOf(drainConfig()), null, "m").readCursor(agent)

    @Test
    fun `drains oldest-first grouped by file for prefix-cache locality`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "a.org", "A1"),
            spoolEvent(2, "b.org", "B1"),
            spoolEvent(3, "a.org", "A2"),
        )
        val server = FakeDecisionServer()
        server.start()
        drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        server.stop()
        val seqs = verdictLines().map { it.seq }
        // groups: a.org {1,3} first, then b.org {2} — grouped per file so
        // consecutive same-file events share the prompt prefix.
        assertEquals(listOf(1L, 3L, 2L), seqs)
    }

    @Test
    fun `verdict lines and cursor advance per agent`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        val server = FakeDecisionServer(confidenceLevel = 3.6)
        server.start()
        val outcome = drain(
            listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())
        ).drain()
        server.stop()
        assertFalse(outcome.failed)
        assertEquals(2, outcome.agents.single().processed)
        assertEquals(2L, outcome.agents.single().cursor)
        assertEquals(2L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
        val lines = verdictLines()
        assertEquals(2, lines.size)
        assertTrue(lines.all { it.agent == "dev-planner" })
        assertTrue(lines.all { it.model == "test" })
        assertTrue(lines.all { it.verdict == "yes" }, "0.9 ≥ 0.75")
        assertTrue(lines.all { it.ts == "2026-11-10T09:00:00-08:00" })
    }

    @Test
    fun `threshold compares confidence against the agent config`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"))
        val server = FakeDecisionServer(confidenceLevel = 2.2)
        server.start()
        drain(
            listOf(drainConfig(threshold = 0.75)),
            VerdictClassifier(server.endpoint, "test", httpClient()),
        ).drain()
        server.stop()
        val line = verdictLines().single()
        assertEquals("no", line.verdict, "0.55 < 0.75")
        assertEquals(0.55, numConf(line), "confidence stays numeric on LLM verdicts")
        // The verdict was logged, so the cursor advances past it.
        assertEquals(1L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
    }

    @Test
    fun `unreachable classifier fails closed with no lines and no cursor advance`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"))
        val outcome = drain(
            listOf(drainConfig()),
            VerdictClassifier("http://127.0.0.1:1", "test", httpClient()),
        ).drain()
        assertTrue(outcome.failed)
        assertTrue(outcome.reason!!.contains("unreachable"))
        assertTrue(verdictLines().isEmpty())
        assertEquals(0L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
    }

    @Test
    fun `should_act answer without a probability map fails closed`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"))
        val port = java.net.ServerSocket(0).use { it.localPort }
        val server = embeddedServer(CIO, host = "127.0.0.1", port = port) {
            routing {
                post("/v1/systemone") {
                    // A score answer with NO probabilities map: the act
                    // statistic is undefined — never gate on the EV.
                    call.respondText(
                        """{"model":"test","answers":{"should_act":{"type":"score","score":4.0}}}""",
                        ContentType.Application.Json
                    )
                }
            }
        }
        server.start(wait = false)
        val outcome = drain(
            listOf(drainConfig()),
            VerdictClassifier("http://127.0.0.1:$port", "test", httpClient()),
        ).drain()
        server.stop(1000, 2000)
        assertTrue(outcome.failed)
        assertTrue(outcome.reason!!.contains("missing probability map"))
        assertTrue(verdictLines().isEmpty())
        assertEquals(0L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
    }

    @Test
    fun `no endpoint configured fails closed loudly`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"))
        val outcome = drain(listOf(drainConfig()), classifier = null).drain()
        assertTrue(outcome.failed)
        assertTrue(outcome.reason!!.contains("no classifier endpoint"))
        assertTrue(verdictLines().isEmpty())
        assertEquals(0L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
    }

    @Test
    fun `fresh config head-inits at spool head without classifying history`() = kotlinx.coroutines.test.runTest {
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        seedCursorImpl(state, agent = "make-legible", seq = 0)
        val notes = mutableListOf<String>()
        val configs = listOf(drainConfig(), drainConfig("make-legible"))
        val outcome = HarnessDrain(
            stateRoot = state, configs = configs, classifier = null, model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
            log = { },
            stderr = { notes.add(it) },
        ).drain()
        // The fresh config (no cursor file) head-inits before any
        // endpoint check — no history classification even with no
        // endpoint. The established agent (make-legible, pending events,
        // no endpoint) fails closed.
        assertTrue(outcome.failed, "make-legible has fresh pending events and no endpoint")
        assertTrue(outcome.reason!!.contains("no classifier endpoint"))
        assertEquals(2L, readCursor(state, "dev-planner"), "head-init at the spool head")
        assertTrue(
            notes.any { it.contains("dev-planner") && it.contains("head seq=2") },
            "one stderr notice: $notes"
        )
        assertTrue(notes.none { it.contains("make-legible") }, "established agent does not re-init")
        assertTrue(verdictLines().isEmpty(), "history is never classified")

        // And a run with an endpoint still writes nothing for history:
        // the cursor covers it.
        val server = FakeDecisionServer()
        server.start()
        val second = HarnessDrain(
            stateRoot = state, configs = configs,
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:05:00-08:00") },
            log = { }, stderr = { },
        ).drain()
        server.stop()
        assertEquals(
            0,
            verdictLines().count { it.agent == "dev-planner" },
            "nothing below head re-classifies"
        )
        assertTrue(verdictLines().all { it.agent == "make-legible" })
        assertEquals(2L, second.agents.first { it.agent == "dev-planner" }.cursor)
    }

    @Test
    fun `from-seq replay advances without regressing the cursor`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "a.org", "A1"),
            spoolEvent(2, "a.org", "A2"),
            spoolEvent(3, "b.org", "B1"),
        )
        val server = FakeDecisionServer()
        server.start()
        drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        // Established: cursor 3, verdicts 1..3.
        assertEquals(3L, readCursor(state, "dev-planner"))
        assertEquals(3, verdictLines().size)

        fillSpool(
            spoolEvent(4, "a.org", "A3"),
            spoolEvent(5, "b.org", "B2", ts = "2026-10-01T08:00:00-08:00"),
        )
        // Deliberate replay from 2: seqs 2,3 dedupe via the seen-set; 4
        // classifies; 5 auto-verdicts stale (40 days old, 14d horizon).
        val requestsBeforeReplay = server.requests.get()
        val replay = HarnessDrain(
            stateRoot = state, configs = listOf(drainConfig()),
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
            log = { }, fromSeq = 2, staleHorizonDays = 14,
        ).drain()
        assertEquals(requestsBeforeReplay + 1, server.requests.get(), "stale event consumed no LLM call")
        assertEquals(2, verdictLines().count { it.seq >= 4L }, "replayed the rest of the window")
        assertEquals(5, verdictLines().size, "seen-set dedupe: no duplicate lines for 2 and 3")
        assertEquals(5L, readCursor(state, "dev-planner"), "cursor advanced over the replayed window")

        // Pure-dedupe replay: a window over already-seen seqs makes zero
        // calls and never regresses the cursor.
        val requestsBefore = server.requests.get()
        val again = HarnessDrain(
            stateRoot = state, configs = listOf(drainConfig()),
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:10:00-08:00") },
            log = { }, fromSeq = 1,
        ).drain()
        server.stop()
        assertEquals(requestsBefore, server.requests.get(), "zero re-classifications")
        assertEquals(5, verdictLines().size, "no duplicates")
        assertEquals(4, verdictLines().count { it.verdict != "stale" })
        assertEquals(0, again.agents.single().processed)
    }

    @Test
    fun `kill-restart between log and cursor is idempotent on seq-agent`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        val server = FakeDecisionServer()
        server.start()
        val runDrain = { drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())) }
        runDrain().drain()
        // Kill-restart simulation: the cursor file lags (lost mid-crash),
        // the verdict log survives. The (seq, agent) seen-set rebuilt from
        // verdict files answers before any re-classification happens.
        File(state, "cursors/dev-planner.verdict").writeText("0\n")
        val requestsBefore = server.requests.get()
        val outcome = runDrain().drain()
        server.stop()
        assertFalse(outcome.failed)
        assertEquals(requestsBefore, server.requests.get(), "seen-set dedupe: zero re-classifications")
        assertEquals(2, verdictLines().size, "no duplicate verdict lines")
        assertEquals(2L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
    }

    @Test
    fun `classification cache skips repeat server hits`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "a.org", "Same title", body = "Same body."),
            spoolEvent(2, "b.org", "Same title", body = "Same body."),
        )
        val server = FakeDecisionServer()
        server.start()
        drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        server.stop()
        assertEquals(2, verdictLines().size)
        // One classification serves both: identical (title, todo, body).
        assertEquals(1, server.requests.get(), "content hash cache hit for the twin event")
    }

    @Test
    fun `urgency rides the verdict line when configured`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"))
        val server = FakeDecisionServer(scoreLevel = 3.0)
        server.start()
        drain(
            listOf(drainConfig(urgency = true)),
            VerdictClassifier(server.endpoint, "test", httpClient()),
        ).drain()
        server.stop()
        val line = verdictLines().single()
        assertEquals(0.75, line.urgency, "level 3.0 of 4")
        assertEquals(2, server.requests.get(), "score plus urgency: two sequential calls")
    }

    /**
     * Drain-level wire pin (this bug's guard): the real regression was
     * the drain's should_act + urgency requests going out criteria-less
     * as yesno. The config here goes through the REAL parse path
     * (ClassifierConfigs.parse over a CLASSIFIER.org fixture), so the
     * pinned assertions prove criteria arrive from the file's Level
     * sections, not from constants, and ride the score wire shape.
     */
    @Test
    fun `verdict questions are pinned to the score shape with five criteria`() = kotlinx.coroutines.test.runTest {
        val agentsDir = Files.createTempDirectory("harness-pin-agents").toFile()
        val dir = java.io.File(agentsDir, "dev-planner").apply { mkdirs() }
        val file = java.io.File(dir, ClassifierConfigs.FILE_NAME)
        // Fixture levels appear out of order on purpose: the parsed
        // criteria are sorted 0..4 regardless (the file is a single-line
        // \n-escaped string — stars stay mid-line, no tangle commas).
        file.writeText(
            ":PROPERTIES:\n:THRESHOLD: 0.75\n:URGENCY: yes\n:END:\n\n" +
                "* should_act\ndoes this heading ask the planner to act\n\n" +
                "** Level 4\na direct request to act now\n\n" +
                "** Level 0\ndistinctive level-zero exclusion marker from the file fixture\n\n" +
                "** Level 2\ndiscussion without concrete work\n\n" +
                "** Level 1\na recording of finished work\n\n" +
                "** Level 3\nconcrete work awaiting scoping\n\n" +
                "* urgency\nhow urgent\n\n" +
                "** Level 0\ndistinctive urgency level-zero marker: no time signal\n\n" +
                "** Level 1\nweeks of slack\n\n" +
                "** Level 2\ndays of slack\n\n" +
                "** Level 3\ntoday or tomorrow\n\n" +
                "** Level 4\nsame-day deadline\n"
        )
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"))
        val config = requireNotNull(
            ClassifierConfigs.parse("dev-planner", file, file.readText())
        )
        val server = FakeDecisionServer(scoreLevel = 3.0)
        server.start()
        drain(
            listOf(config),
            VerdictClassifier(server.endpoint, "test", httpClient()),
        ).drain()
        server.stop()
        assertEquals(2, server.requestBodies.size, "should_act plus urgency, both pinned")
        // Two in flight, ever: confidence classifies first, urgency second.
        assertTrue(
            server.requestBodies[0].contains("should_act") &&
                server.requestBodies[0]
                    .contains("distinctive level-zero exclusion marker"),
            "should_act criteria must come from the fixture's Level 0: ${server.requestBodies[0]}"
        )
        assertTrue(
            server.requestBodies[1].contains("urgency") &&
                server.requestBodies[1]
                    .contains("distinctive urgency level-zero marker"),
            "urgency criteria must come from the fixture's Level 0: ${server.requestBodies[1]}"
        )
        for ((body, criteria) in server.requestBodies.zip(
            listOf(config.shouldActCriteria, config.urgencyCriteria!!)
        )) {
            val question = (((kotlinx.serialization.json.Json.parseToJsonElement(body)
                as kotlinx.serialization.json.JsonObject)["questions"])
                as kotlinx.serialization.json.JsonObject).values.single()
                as kotlinx.serialization.json.JsonObject
            assertEquals(
                "score",
                (question["type"] as kotlinx.serialization.json.JsonPrimitive).content,
                "every drain verdict question must be a score question: $body",
            )
            assertEquals(
                criteria,
                (question["criteria"] as kotlinx.serialization.json.JsonArray)
                    .map { (it as kotlinx.serialization.json.JsonPrimitive).content },
                "wire criteria equal the parsed config's rubric: $body",
            )
            assertTrue(
                criteria.all { it.isNotBlank() },
                "criteria entries must be non-blank rubric levels: $body",
            )
            assertFalse(body.contains("\"yesno\""), "the dead yes/no shape must never return")
        }
    }

    @Test
    fun `caught-up restart makes zero classifier calls`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        val server = FakeDecisionServer()
        server.start()
        val runDrain = { drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())) }
        runDrain().drain()
        val firstRunRequests = server.requests.get()
        val outcome = runDrain().drain()
        assertEquals(firstRunRequests, server.requests.get())
        assertFalse(outcome.failed)
        assertEquals(listOf(1L, 2L), verdictLines().map { it.seq })
        server.stop()
    }

    @Test
    fun `only-agent narrows the drain to one config`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state, agent = "dev-planner", seq = 0)
        seedCursorImpl(state, agent = "make-legible", seq = 0)
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        val server = FakeDecisionServer()
        server.start()
        val outcome = HarnessDrain(
            stateRoot = state,
            configs = listOf(drainConfig("dev-planner"), drainConfig("make-legible")),
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
            log = { }, onlyAgent = "dev-planner",
        ).drain()
        server.stop()
        assertEquals(1, outcome.agents.size, "only the named agent ran")
        assertEquals(2L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
        assertEquals(
            0L,
            HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("make-legible"),
            "the other agent's cursor is untouched"
        )
        assertTrue(verdictLines().all { it.agent == "dev-planner" })
    }

    @Test
    fun `budget cutoff yields the capped verdicts and a visible backlog`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"),
            spoolEvent(3, "a.org", "A3"), spoolEvent(4, "a.org", "A4"),
            spoolEvent(5, "a.org", "A5"),
        )
        val server = FakeDecisionServer()
        server.start()
        fun budgeted(now: String, budget: Int) = HarnessDrain(
            stateRoot = state, configs = listOf(drainConfig()),
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse(now) },
            log = { }, maxEventsPerAgent = budget,
        )
        val first = budgeted("2026-11-10T09:00:00-08:00", 2).drain()
        assertFalse(first.failed, "a budget stop is a normal bounded stop")
        assertEquals(2, first.agents.single().processed)
        assertEquals(2, first.agents.single().cursor, "cursor lands on the 2nd event")
        assertEquals(2, server.requests.get(), "two LLM classifications")
        assertEquals(2, verdictLines().size)
        // The backlog stays visible as lag: tail(5) - cursor(2) = 3.
        val tail = SpoolWriter(state).readEvents().maxOf { it.seq }
        assertEquals(3L, tail - first.agents.single().cursor, "lag after the bounded run")

        val second = budgeted("2026-11-10T09:01:00-08:00", 2).drain()
        server.stop()
        assertEquals(2, second.agents.single().processed, "budget refills per run")
        assertEquals(4, second.agents.single().cursor)
        assertEquals(4, server.requests.get())
        assertEquals(1L, tail - second.agents.single().cursor, "one event of lag stays visible")
    }

    @Test
    fun `zero budget means unlimited classifications`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        val server = FakeDecisionServer()
        server.start()
        val outcome = HarnessDrain(
            stateRoot = state, configs = listOf(drainConfig()),
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
            log = { }, maxEventsPerAgent = 0,
        ).drain()
        server.stop()
        assertFalse(outcome.failed)
        assertEquals(2, server.requests.get(), "budget 0 = unlimited")
        assertEquals(2, verdictLines().size)
        assertEquals(2, outcome.agents.single().processed)
    }

    @Test
    fun `stale events auto-verdict with zero LLM calls even under outage`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "old.org", "Ancient entry", ts = "2026-10-01T08:00:00-08:00"),
            spoolEvent(2, "new.org", "Fresh entry"),
        )
        // The server RUNS — proving the stale path never consults it —
        // while the UNREACHABLE classifier stands in for the outage the
        // fresh event must fail closed on.
        val server = FakeDecisionServer()
        server.start()
        val outcome = HarnessDrain(
            stateRoot = state, configs = listOf(drainConfig()),
            classifier = VerdictClassifier("http://127.0.0.1:1", "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
            log = { }, staleHorizonDays = 7,
        ).drain()
        server.stop()
        assertEquals(0, server.requests.get(), "zero HTTP requests, ever")
        val lines = verdictLines()
        assertEquals(1, lines.size)
        val stale = lines.single()
        assertEquals(1, stale.seq)
        assertEquals("stale", stale.verdict)
        assertEquals("stale-rule", (stale.confidence as kotlinx.serialization.json.JsonPrimitive).content)
        assertEquals("stale-rule", stale.model)
        // Cursor advanced normally over the stale row; the fresh event
        // failed closed.
        assertEquals(
            1L,
            HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner")
        )
        assertTrue(outcome.failed, "the fresh event still fails closed during the outage")
        assertTrue(outcome.reason!!.contains("unreachable"))
    }

    @Test
    fun `stale events are inert when the endpoint is up`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "old.org", "Ancient entry", ts = "2026-10-01T08:00:00-08:00"),
            spoolEvent(2, "new.org", "Fresh entry"),
        )
        val server = FakeDecisionServer()
        server.start()
        val outcome = drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        server.stop()
        assertFalse(outcome.failed)
        // Exactly ONE LLM call: only the fresh event hit the model.
        assertEquals(1, server.requests.get())
        val lines = verdictLines().sortedBy { it.seq }
        assertEquals("stale", lines[0].verdict)
        assertEquals("stale-rule", (lines[0].confidence as kotlinx.serialization.json.JsonPrimitive).content)
        assertEquals("yes", lines[1].verdict)
    }

    // ── Cursor semantics: classified OR deliberately skipped ─────────
    // The contiguous run starts AT the cursor: a head-initialized agent
    // has no verdict rows for 1..prior, so starting the run at 1 pinned
    // the cursor forever (the 2026-11-12 live find).

    @Test
    fun `head-init skipped history still lets the cursor advance`() = kotlinx.coroutines.test.runTest {
        fillSpool(spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"))
        val server = FakeDecisionServer()
        server.start()
        // Fresh config: head-inits at the spool head, classifies nothing.
        val first = drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        assertFalse(first.failed)
        assertEquals(0, first.agents.single().processed)
        assertEquals(2L, first.agents.single().cursor)
        assertEquals(0, verdictLines().size, "history stays unclassified")
        // New events after the head-init — the cursor must move on the
        // SAME run that fsyncs their verdicts.
        fillSpool(spoolEvent(3, "a.org", "A3"), spoolEvent(4, "b.org", "B4"))
        val second = drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        server.stop()
        assertFalse(second.failed)
        assertEquals(2, second.agents.single().processed)
        assertEquals(4L, second.agents.single().cursor, "the run beyond the head-init advances it")
        assertEquals(4L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
        assertEquals(listOf(3L, 4L), verdictLines().map { it.seq })
    }

    @Test
    fun `a mid-run hole pins the cursor until the next run fills it`() = kotlinx.coroutines.test.runTest {
        // Fresh agent head-inits at spool head seq=2; then four more
        // events spool. SpoolWriter renumbers by append order, so the
        // files end up x.org = seqs {3, 6} and y.org = {4, 5}; file
        // grouping orders x.org's group (min 3) FIRST, hence the grouped
        // order 3, 6, 4, 5 — seq 6 is attempted BEFORE 4 and 5. The
        // stateful fake answers the first verdict (seq 3) and fails
        // everything after: an abort leaves {3} fsynced, with the
        // unclassified 4 pinning the run below the fsynced 6.
        fillSpool(spoolEvent(1, "x.org", "A1"), spoolEvent(2, "x.org", "A2"))
        drain(listOf(drainConfig()), VerdictClassifier("http://127.0.0.1:1", "test", httpClient())).drain()
        fillSpool(
            spoolEvent(3, "x.org", "A3"), spoolEvent(4, "y.org", "B4"),
            spoolEvent(5, "y.org", "B5"), spoolEvent(6, "x.org", "A6"),
        )
        val port = java.net.ServerSocket(0).use { it.localPort }
        val calls = AtomicInteger(0)
        val flaky = embeddedServer(CIO, host = "127.0.0.1", port = port) {
            routing {
                post("/v1/systemone") {
                    if (calls.incrementAndGet() == 1) {
                        call.respondText(
                            """{"model":"test","answers":{""" +
                                """"should_act":{"type":"score","score":3.0,""" +
                                """"probabilities":{"0":0.1,"3":0.4},"confidence":0.6}}}""",
                            ContentType.Application.Json
                        )
                    } else {
                        call.respond(HttpStatusCode.InternalServerError, "")
                    }
                }
            }
        }
        flaky.start(wait = false)
        val broken = drain(listOf(drainConfig()), VerdictClassifier("http://127.0.0.1:$port", "test", httpClient())).drain()
        flaky.stop()
        assertTrue(broken.failed)
        assertEquals(3L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"),
            "the unclassified seq 4 pins the contiguous run at 3, even though 6's group came earlier")
        assertEquals(listOf(3L), verdictLines().map { it.seq })
        // The next run (fresh server) fills the hole and completes the run.
        val server = FakeDecisionServer()
        server.start()
        val fixed = drain(listOf(drainConfig()), VerdictClassifier(server.endpoint, "test", httpClient())).drain()
        server.stop()
        assertFalse(fixed.failed)
        assertEquals(6L, fixed.agents.single().cursor, "hole filled: the contiguous run completes")
        assertEquals(6L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
        // Rows land in processing order: 3 and 6 in the aborted run, 4
        // and 5 in the fill run — the grouped-order interleave made
        // itself visible in the verdict log.
        assertEquals(
            listOf(3L, 4L, 5L, 6L),
            verdictLines().map { it.seq }.sorted()
        )
    }

    @Test
    fun `replay below the cursor fills interior holes without advancing`() = kotlinx.coroutines.test.runTest {
        seedCursorImpl(state)
        fillSpool(
            spoolEvent(1, "a.org", "A1"), spoolEvent(2, "a.org", "A2"),
            spoolEvent(3, "a.org", "A3"), spoolEvent(4, "b.org", "B4"),
            spoolEvent(5, "b.org", "B5"),
        )
        val established = FakeDecisionServer()
        established.start()
        drain(listOf(drainConfig()), VerdictClassifier(established.endpoint, "test", httpClient())).drain()
        established.stop()
        assertEquals(5L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
        // Manufacture the crash-era hole: seq 3's verdict row vanishes
        // while the cursor file still reads 5.
        val verdictFile = File(state, "verdicts/2026-11-10.ndjson")
        verdictFile.writeText(
            verdictFile.readLines()
                .filter { !it.contains("\"seq\":3,") }
                .joinToString("\n", postfix = "\n")
        )
        assertEquals(4, verdictLines().size)
        // Drop the plain-file verdict cache too: it legitimately serves
        // repeat verdicts across restarts (a cache-only holeFill would
        // re-log the row with zero LLM calls); deleting it proves the
        // full hole→window→classify→fsync path in this test.
        File(state, "llm-verdict-cache.ndjson").delete()
        val server = FakeDecisionServer()
        server.start()
        val replay = HarnessDrain(
            stateRoot = state, configs = listOf(drainConfig()),
            classifier = VerdictClassifier(server.endpoint, "test", httpClient()),
            model = "test",
            now = { java.time.OffsetDateTime.parse("2026-11-10T09:00:00-08:00") },
            log = { }, fromSeq = 3,
        ).drain()
        server.stop()
        assertFalse(replay.failed)
        assertEquals(1, server.requests.get(), "only the hole re-classifies; 4 and 5 dedupe")
        assertEquals(5, verdictLines().size, "the interior hole is filled")
        // Nothing beyond the cursor exists, so the cursor stays at 5 —
        // and the fix never regressed it below prior.
        assertEquals(5L, HarnessDrain(state, listOf(drainConfig()), null, "m").readCursor("dev-planner"))
    }
}

Dispatch tests

All jvmTest, no hermes, no real systemd-run: the spawn executor is an injectable recording CommandRunner fake, procfs rides the LeaseStore procRoot seam with a fake /proc tree, the clock is injected, and verdict rows are written straight into verdicts/*.ndjson — dispatch's own inputs.

kotlin#+name: harness-dispatch-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/HarnessDispatchTest.kt
package computer.whatthefuck.arcology.harness

import java.io.File
import java.nio.file.Files
import java.time.LocalTime
import java.time.OffsetDateTime
import kotlin.test.*
import kotlinx.serialization.json.JsonPrimitive

/** Wake configs default to wide budgets, zero spacing, always-open
 * window unless the test narrows them. */
private fun wakeConfig(
    agent: String = "dev-planner",
    threshold: Double = 0.75,
    urgency: Boolean = false,
    wake: WakePolicy = WakePolicy.On(maxWakes = 3, maxUrgentWakes = 1, minWakeIntervalMinutes = 0),
) = AgentClassifierConfig(
    agent = agent,
    configPath = File("/agents/$agent/CLASSIFIER.org"),
    threshold = threshold,
    urgency = urgency,
    shouldAct = "does this heading ask the planner to act",
    shouldActCriteria = listOf(
        "l0 exclusion", "l1 recording", "l2 discussion", "l3 concrete task", "l4 direct request",
    ),
    wake = wake,
)

private class RecordingRunner : CommandRunner {
    val argvs = mutableListOf<List<String>>()
    override fun run(argv: List<String>, env: Map<String, String>): Int {
        argvs.add(argv)
        return 0
    }
}

class HarnessDispatchTest {
    private lateinit var state: File

    @BeforeTest
    fun setup() {
        state = Files.createTempDirectory("harness-dispatch").toFile()
    }

    private fun window(startHour: Int, endHour: Int) =
        WakeWindow(LocalTime.of(startHour, 0), LocalTime.of(endHour, 0))

    private fun engine(
        configs: List<AgentClassifierConfig> = listOf(wakeConfig()),
        onlyAgent: String? = null,
        dryRun: Boolean = false,
        gate: Boolean = false,
        wakeWindow: WakeWindow? = null,
        commandRunner: CommandRunner = RecordingRunner(),
        procRoot: String = File(state, "proc-fake").path,
        now: () -> OffsetDateTime = { OffsetDateTime.parse("2026-11-12T09:00:00-08:00") },
        stderr: (String) -> Unit = {},
    ) = HarnessDispatch(
        stateRoot = state, configs = configs, onlyAgent = onlyAgent,
        dryRun = dryRun, gate = gate, wakeWindow = wakeWindow,
        hermesProfilesDir = File(state, "profiles"),
        commandRunner = commandRunner, procRoot = procRoot, now = now,
        log = {}, stderr = stderr,
    )

    private fun spoolEvent(
        seq: Long,
        title: String,
        ts: String = "2026-11-12T08:00:00-08:00",
        orgId: String? = null,
    ) =
        SpoolEvent(
            ts = ts, scope = "journal", file = "journals/2026-11/$seq.org",
            identity = SpoolIdentity(orgId, "journals/2026-11/$seq.org::$seq"),
            action = "added", title = title, body = "Body of $title.",
            revision = "rev-$seq", risk = SpoolRisk(max = 0.1, gated = false),
            modifiedBy = "local",
        )

    private fun verdict(
        seq: Long,
        agent: String = "dev-planner",
        verdict: String = "yes",
        confidence: Double = 0.9,
        urgency: Double? = null,
    ) {
        File(state, "verdicts").apply { mkdirs() }.resolve("2026-11-12.ndjson").appendText(
            VerdictJson.encodeToString(
                VerdictLogLine.serializer(),
                VerdictLogLine(
                    seq = seq, agent = agent, verdict = verdict,
                    confidence = JsonPrimitive(confidence), model = "test",
                    ts = "2026-11-12T08:30:00-08:00", urgency = urgency,
                ),
            ) + "\n"
        )
    }

    private fun seedCursor(agent: String = "dev-planner", seq: Long) {
        File(state, "cursors").mkdirs()
        File(state, "cursors/$agent.dispatch").writeText("$seq\n")
    }

    private fun dispatchCursor(agent: String = "dev-planner"): Long =
        File(state, "cursors/$agent.dispatch").takeIf { it.isFile }
            ?.readText()?.trim()?.toLongOrNull() ?: -1L

    private fun auditRows(): List<WakeAuditLine> {
        val dir = File(state, "wakes")
        if (!dir.isDirectory) return emptyList()
        val out = mutableListOf<WakeAuditLine>()
        dir.listFiles()?.filter { it.isFile && it.name.endsWith(".ndjson") }?.sortedBy { it.name }
            ?.forEach { file ->
                file.useLines { lines ->
                    for (line in lines) {
                        if (line.isBlank()) continue
                        runCatching { WakeJson.decodeFromString(WakeAuditLine.serializer(), line) }
                            .getOrNull()?.let { out.add(it) }
                    }
                }
            }
        return out
    }

    /** Live-lease fixture: lease json + a fake procfs cmdline naming the
     * agent (procRoot = state, per the engine default in these tests). */
    private fun makeLive(agent: String = "dev-planner", pid: Long = 4242) {
        File(state, "proc-fake/$pid").mkdirs()
        File(state, "proc-fake/$pid/cmdline").writeText("hermes chat --profile $agent")
        File(state, "locks").mkdirs()
        File(state, "locks/$agent.lease").writeText(
            """{"pid":$pid,"started":"2026-11-12T08:50:00-08:00","wake_key":"k","ttl_minutes":60}"""
        )
    }

    private fun payload(agent: String = "dev-planner", seq: Long): File =
        File(state, "wakes/$agent-$seq.md")

    @Test
    fun `fresh agent head-inits its dispatch cursor at the spool head with a stderr notice`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        writer.append(spoolEvent(0, "Two"))
        val notices = mutableListOf<String>()
        val runner = RecordingRunner()
        val outcome = engine(commandRunner = runner, stderr = { notices.add(it) }).dispatch()
        assertTrue(
            notices.any { "initialized dispatch cursor at spool head seq=2" in it },
            "one stderr notice: $notices"
        )
        assertEquals(2L, outcome.agents.single().cursor)
        assertEquals(2L, dispatchCursor(), "head-init wrote the spool head")
        assertEquals(0, runner.argvs.size, "head-init classifies and wakes nothing")
        assertEquals(0, auditRows().size, "head-init audits nothing")
        // The sanctioned replay knob is documented in the notice.
        assertTrue(notices.single().contains("delete or rewrite"))
    }

    @Test
    fun `dispatch cursor advances independently of the drain cursor`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        writer.append(spoolEvent(0, "Two"))
        writer.append(spoolEvent(0, "Three"))
        seedCursor(seq = 1)
        verdict(2)
        verdict(3)
        val runner = RecordingRunner()
        engine(commandRunner = runner).dispatch()
        assertEquals(2, runner.argvs.size, "one hermes spawn per yes-verdict")
        assertEquals(3L, dispatchCursor())
        assertFalse(
            File(state, "cursors/dev-planner.verdict").isFile,
            "the drain cursor is never touched by dispatch"
        )
        assertTrue(
            payload(seq = 3).readText().contains("Body of Three."),
            "the briefing carries the verbatim body"
        )
        // The audit row's payload field points at the briefing file.
        assertEquals(
            "wakes/dev-planner-3.md",
            auditRows().first { it.seq == 3L }.payload,
        )
    }

    @Test
    fun `regular and urgent budgets drain independently per lane`() {
        val writer = SpoolWriter(state)
        repeat(4) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1, urgency = null)      // regular
        verdict(2, urgency = 0.4)       // below the urgent-lane constant: regular
        verdict(3, urgency = 0.95)      // urgent
        verdict(4, urgency = 0.8)       // urgent
        val cfg = wakeConfig(
            urgency = true,
            wake = WakePolicy.On(maxWakes = 2, maxUrgentWakes = 1, minWakeIntervalMinutes = 0),
        )
        val runner = RecordingRunner()
        engine(configs = listOf(cfg), commandRunner = runner).dispatch()
        val rows = auditRows()
        assertEquals(4, rows.size, "one audit row per attempt")
        assertEquals(3, runner.argvs.size, "2 regular + 1 urgent: budgets never cross")
        assertEquals(1, rows.count { it.lane == "urgent" && it.spawnExit == 0 })
        assertEquals(2, rows.count { it.lane == "regular" && it.spawnExit == 0 })
        assertEquals("cap", rows.first { it.seq == 3L }.reason)
        assertEquals(2L, dispatchCursor(), "pending yes at seq 3 pins the cursor below it")
    }

    @Test
    fun `urgent lane requires enabled urgency at or above the urgent threshold`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        // Urgency rubric DISABLED: even a 0.99 score rides the regular lane.
        verdict(1, urgency = 0.99)
        engine().dispatch()
        assertEquals("regular", auditRows().first { it.seq == 1L }.lane)
        // Rubric enabled: 0.6 stays regular, 0.8 crosses the 0.75 constant.
        verdict(2, urgency = 0.6)
        verdict(3, urgency = 0.8)
        engine(configs = listOf(wakeConfig(urgency = true))).dispatch()
        assertEquals("regular", auditRows().first { it.seq == 2L }.lane)
        assertEquals("urgent", auditRows().first { it.seq == 3L }.lane)
    }

    @Test
    fun `min wake interval spaces spawns per agent`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2); verdict(3)
        var now = OffsetDateTime.parse("2026-11-12T09:00:00-08:00")
        val cfg = listOf(
            wakeConfig(wake = WakePolicy.On(maxWakes = 5, maxUrgentWakes = 5, minWakeIntervalMinutes = 60))
        )
        // Tick 1: newest spawns; the older candidates wait their spacing.
        engine(configs = cfg, now = { now }).dispatch()
        assertEquals(setOf(3L), auditRows().filter { it.spawnExit == 0 }.map { it.seq }.toSet())
        // Tick 2 (+10min): spacing still binds both pending candidates.
        now = now.plusMinutes(10)
        engine(configs = cfg, now = { now }).dispatch()
        assertEquals(1, auditRows().count { it.spawnExit == 0 }, "nothing spawned yet")
        assertTrue(auditRows().any { it.reason == "interval" && it.seq == 2L })
        // Tick 3 (+60min): seq 2 flushes; seq 1 waits another spacing turn.
        now = now.plusMinutes(60)
        engine(configs = cfg, now = { now }).dispatch()
        assertEquals(setOf(2L, 3L), auditRows().filter { it.spawnExit == 0 }.map { it.seq }.toSet())
    }

    @Test
    fun `zero min wake interval disables the spacing check`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        val cfg = listOf(
            wakeConfig(wake = WakePolicy.On(maxWakes = 5, maxUrgentWakes = 5, minWakeIntervalMinutes = 0))
        )
        val runner = RecordingRunner()
        engine(configs = cfg, commandRunner = runner).dispatch()
        assertEquals(2, runner.argvs.size, "both spawn in one tick with spacing off")
    }

    @Test
    fun `held outside the wake window does not advance the cursor and flushes inside`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        val runner = RecordingRunner()
        // 23:30 is outside 07:00-22:00: audited as held, zero spawns.
        var now = OffsetDateTime.parse("2026-11-12T23:30:00-08:00")
        engine(wakeWindow = window(7, 22), commandRunner = runner, now = { now }).dispatch()
        assertEquals(0, runner.argvs.size)
        assertEquals(0L, dispatchCursor(), "held verdicts are not consumed")
        assertEquals(
            setOf("held", "held"),
            auditRows().map { it.reason }.toSet(),
        )
        // Next morning inside the window: the held candidates flush.
        now = OffsetDateTime.parse("2026-11-13T08:00:00-08:00")
        engine(wakeWindow = window(7, 22), commandRunner = runner, now = { now }).dispatch()
        assertEquals(2, runner.argvs.size, "held candidates flush when the window reopens")
        assertEquals(2L, dispatchCursor())
    }

    @Test
    fun `midnight-spanning wake window is open across the date line`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        val runner = RecordingRunner()
        // Window 22:00-06:00 wraps midnight: 23:30 is open.
        var now = OffsetDateTime.parse("2026-11-12T23:30:00-08:00")
        engine(wakeWindow = window(22, 6), commandRunner = runner, now = { now }).dispatch()
        assertEquals(2, runner.argvs.size)
        // 09:00 is closed on both legs: the next candidate holds.
        verdict(3)
        now = OffsetDateTime.parse("2026-11-13T09:00:00-08:00")
        engine(wakeWindow = window(22, 6), commandRunner = runner, now = { now }).dispatch()
        assertEquals(2, runner.argvs.size, "nothing new spawned outside the wrapped window")
        assertEquals("held", auditRows().first { it.seq == 3L }.reason)
        assertEquals(2L, dispatchCursor())
    }

    @Test
    fun `gated event wakes with a stub payload and never a body`() {
        val writer = SpoolWriter(state)
        writer.append(
            spoolEvent(0, "Sensitive").copy(
                risk = SpoolRisk(max = null, gated = true)
            )
        )
        writer.append(spoolEvent(0, "Ordinary"))
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        engine().dispatch()
        val gated = auditRows().first { it.seq == 1L }
        assertEquals(true, gated.gated)
        assertTrue(payload(seq = 1).isFile, "a gated event still wakes (local profiles)")
        val gatedText = payload(seq = 1).readText()
        assertTrue(
            "GATED — the entry body is withheld by the risk gate" in gatedText,
            "the gate line explains the withholding: $gatedText"
        )
        assertTrue(
            gatedText.contains("Withheld by the risk gate."),
            "the briefing says the body is withheld: $gatedText"
        )
        assertFalse(gatedText.contains("Body of Sensitive."), "never the body text")
        // Ruling (A): a risk-gated briefing prints no retrieval recipe —
        // a recipe would just fetch the withheld body — and it points at
        // the blocked-capture exit instead.
        assertFalse(gatedText.contains("journal user"), "no recipe for a gated event")
        assertTrue(
            gatedText.contains("assess from the title") &&
                gatedText.contains("release the lease, and exit"),
            "the gate section routes to the blocked-capture exit: $gatedText"
        )
        val plain = auditRows().first { it.seq == 2L }
        assertEquals(false, plain.gated)
        assertTrue(
            payload(seq = 2).readText().contains("Body of Ordinary."),
            "the un-gated briefing carries the verbatim body"
        )
    }

    @Test
    fun `wake opt-in defaults to false and off configs are never dispatched`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        verdict(1)
        val outcome = engine(configs = listOf(wakeConfig(wake = WakePolicy.Off))).dispatch()
        assertEquals(0, outcome.agents.size, "off configs are invisible to dispatch")
        assertFalse(File(state, "cursors/dev-planner.dispatch").isFile, "not even head-init")
        assertEquals(0, auditRows().size)
    }

    @Test
    fun `malformed wake knob fails shut and consumes nothing`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        verdict(1); verdict(2)
        val notices = mutableListOf<String>()
        val runner = RecordingRunner()
        val outcome = engine(
            configs = listOf(
                wakeConfig(wake = WakePolicy.Malformed("MAX_WAKES is not a non-negative integer"))
            ),
            commandRunner = runner,
            stderr = { notices.add(it) },
        ).dispatch()
        assertEquals(0, outcome.agents.size)
        assertEquals(0, runner.argvs.size)
        assertFalse(File(state, "cursors/dev-planner.dispatch").isFile, "fail-shut skips before head-init")
        assertEquals(0, auditRows().size)
        assertTrue(notices.single().contains("unusable wake policy"))
    }

    @Test
    fun `live lease skips the agent without consuming budget or cursor`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        makeLive()
        val runner = RecordingRunner()
        engine(commandRunner = runner).dispatch()
        assertEquals(0, runner.argvs.size, "one wake in flight per agent, absolute")
        assertEquals(0L, dispatchCursor(), "the skip consumes nothing")
        assertEquals(
            setOf("lease"),
            auditRows().map { it.reason }.toSet(),
        )
        // Once the lease is gone the candidates flush normally.
        File(state, "locks/dev-planner.lease").delete()
        engine(commandRunner = runner).dispatch()
        assertEquals(2, runner.argvs.size)
    }

    @Test
    fun `dead lease does not block`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        seedCursor(seq = 0)
        verdict(1)
        // Lease file present, but the pid does not exist in procfs.
        File(state, "locks").mkdirs()
        File(state, "locks/dev-planner.lease").writeText(
            """{"pid":999999,"started":"2026-11-12T08:50:00-08:00","wake_key":"k","ttl_minutes":60}"""
        )
        val runner = RecordingRunner()
        engine(commandRunner = runner).dispatch()
        assertEquals(1, runner.argvs.size, "a dead lease is not a live lease")
    }

    @Test
    fun `dry run audits dryRun true and spawns zero sessions`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        val runner = RecordingRunner()
        engine(dryRun = true, commandRunner = runner).dispatch()
        assertEquals(0, runner.argvs.size, "zero spawns")
        val rows = auditRows()
        assertEquals(2, rows.size)
        assertTrue(rows.all { it.dryRun })
        assertTrue(rows.all { it.spawnExit == null })
        assertEquals(0L, dispatchCursor(), "dry-run advances nothing")
        assertFalse(File(state, "wakes/dev-planner-1.md").isFile, "no briefing files in dry-run")
        // Nothing consumed: a real run right after wakes both.
        val reals = RecordingRunner()
        engine(commandRunner = reals).dispatch()
        assertEquals(2, reals.argvs.size)
    }

    @Test
    fun `audit read-back keeps a restarted dispatcher under the caps`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2); verdict(3)
        val cfg = listOf(wakeConfig(wake = WakePolicy.On(maxWakes = 2, maxUrgentWakes = 1, minWakeIntervalMinutes = 0)))
        val first = RecordingRunner()
        engine(configs = cfg, commandRunner = first).dispatch()
        assertEquals(2, first.argvs.size, "budget 2 spent on newest-first desc order")
        assertEquals("cap", auditRows().first { it.seq == 1L }.reason)
        // Restart: a fresh engine instance reads the audit file and
        // dedupes; nothing double-wakes, the capped candidate stays.
        val second = RecordingRunner()
        engine(configs = cfg, commandRunner = second).dispatch()
        assertEquals(0, second.argvs.size, "audit read-back dedupes already-woken seqs")
        assertEquals("cap", auditRows().last { it.seq == 1L }.reason)
        assertEquals(0L, dispatchCursor(), "pending candidate keeps the cursor pinned")
    }

    @Test
    fun `dispatch cursor follows the classified frontier and never skips a hole`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1)
        verdict(3) // drain writes grouped-by-file: a hole at seq 2
        val runner = RecordingRunner()
        engine(commandRunner = runner).dispatch()
        assertEquals(1, runner.argvs.size, "only seq 1 is inside the contiguous frontier")
        assertEquals(1L, dispatchCursor(), "the hole pins the cursor at 1 — never skips to 3")
        // The drain fills the hole (an inert 'no' row is enough): the
        // frontier opens and seq 3 wakes on the next tick.
        verdict(2, verdict = "no")
        engine(commandRunner = runner).dispatch()
        assertEquals(2, runner.argvs.size)
        assertEquals(3L, dispatchCursor())
    }

    @Test
    fun `payload joins across a month boundary`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "October tail", ts = "2026-10-31T23:00:00-07:00"))
        writer.append(spoolEvent(0, "November head", ts = "2026-11-01T00:30:00-08:00"))
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        val runner = RecordingRunner()
        engine(commandRunner = runner).dispatch()
        assertEquals(2, runner.argvs.size, "both month files are read, oldest first")
        assertTrue(payload(seq = 1).readText().contains("October tail"))
        assertTrue(payload(seq = 2).readText().contains("November head"))
    }

    @Test
    fun `baseline marker line and torn trailing line are skipped when reading payloads`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        writer.append(spoolEvent(0, "Two"))
        // The baseline audit marker rides the month files; a torn line
        // (the producer growing the file mid-read) rides along too.
        writer.appendRaw(SpoolWriter.buildBaselineMarker(2, 10, 2, "2026-11-12T07:00:00-08:00"))
        File(state, "spool/2026-11.ndjson").appendText("""{"seq":99,"ts":"2026-11-1""")
        seedCursor(seq = 0)
        verdict(1)
        val logs = mutableListOf<String>()
        val runner = RecordingRunner()
        val dispatcher = HarnessDispatch(
            stateRoot = state, configs = listOf(wakeConfig()),
            commandRunner = runner, procRoot = state.path,
            hermesProfilesDir = File(state, "profiles"),
            log = { logs.add(it) },
        )
        dispatcher.dispatch()
        assertEquals(1, runner.argvs.size)
        assertTrue(payload(seq = 1).readText().contains("> One"), "the briefing blockquotes the title")
        assertFalse(auditRows().any { it.reason != null }, "markers and torn lines are not events, not gaps")
        assertTrue(
            logs.any { it.contains("skipping unparseable spool line") },
            "the torn trailing line is logged, never interpreted: $logs"
        )
        assertEquals(1L, dispatchCursor())
    }

    @Test
    fun `drain lock held skips dispatch cleanly with busy true`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        verdict(1)
        val locks = HarnessLocks(state)
        val held = locks.tryAcquire("drain.lock")
        val runner = RecordingRunner()
        val outcome = engine(commandRunner = runner).dispatch()
        held?.close()
        assertTrue(outcome.busy)
        assertEquals(0, outcome.agents.size)
        assertEquals(0, runner.argvs.size)
        assertFalse(File(state, "cursors/dev-planner.dispatch").isFile, "even head-init waits")
        assertEquals(0, auditRows().size)
    }

    @Test
    fun `dispatch lock held skips cleanly and is released after the run`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        seedCursor(seq = 0)
        verdict(1)
        val locks = HarnessLocks(state)
        val held = locks.tryAcquire("dispatch.lock")
        val runner = RecordingRunner()
        val busy = engine(commandRunner = runner).dispatch()
        held?.close()
        assertTrue(busy.busy)
        assertEquals(0, runner.argvs.size)
        // Second instance gets through — the lock is released in finally.
        val outcome = engine(commandRunner = runner).dispatch()
        assertFalse(outcome.busy)
        assertEquals(1, runner.argvs.size)
        assertFalse(locks.isLocked("dispatch.lock"), "no leaked lock after the run")
    }

    // ── Wake briefings (replacing the raw-JSON payloads) ────────────────

    @Test
    fun `briefing carries the exact journal user get recipe when the entry has an org id`() {
        val writer = SpoolWriter(state)
        writer.append(
            spoolEvent(0, "Morning entry", orgId = "20261110T163846.123456")
        )
        seedCursor(seq = 0)
        verdict(1)
        engine().dispatch()
        val text = payload(seq = 1).readText()
        assertTrue(
            text.contains("""journal user get "20261110T163846.123456""""),
            "the exact get recipe is baked in: $text"
        )
        assertTrue(text.contains("cd ~/org/agents/dev-planner"))
        assertFalse(
            text.contains("journal user search --query"),
            "no search recipe when the id is baked in"
        )
    }

    @Test
    fun `briefing carries the search recipe and no-ID wording when the org id is absent`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "Quarterly planning retreat and offsite"))
        seedCursor(seq = 0)
        verdict(1)
        engine().dispatch()
        val text = payload(seq = 1).readText()
        assertTrue(
            text.contains("""journal user search --query "Quarterly planning retreat""""),
            "the search recipe with distilled title words: $text"
        )
        assertTrue(text.contains("""journal user get "<id from result>""""))
        assertTrue(text.contains("has no :ID:"), "the no-ID wording is explicit")
        assertTrue(text.contains("do not search for one"))
    }

    @Test
    fun `briefing carries the lease protocol and the anti-workaround hard rules`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        seedCursor(seq = 0)
        verdict(1)
        engine().dispatch()
        val text = payload(seq = 1).readText()
        assertTrue(text.startsWith("# Arcology wake: dev-planner — event seq 1"))
        assertTrue(
            text.contains("lease acquire --agent dev-planner") &&
                text.contains("lease release --agent dev-planner"),
            "the run protocol names the exact commands: $text"
        )
        assertTrue(text.contains("LOCAL ONLY"), "the privacy rule is explicit")
        assertTrue(
            text.contains("do NOT work around it") && text.contains("no curl with base64 media"),
            "the anti-workaround rule is explicit"
        )
        assertTrue(text.contains("release the lease, and exit"))
    }

    @Test
    fun `spawn argv tags the session source wake`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        seedCursor(seq = 0)
        verdict(1)
        val runner = RecordingRunner()
        engine(commandRunner = runner).dispatch()
        assertEquals(1, runner.argvs.size)
        val argv = runner.argvs.first()
        assertTrue(
            argv.windowed(2).contains(listOf("--source", "wake")),
            "the visible, filterable source tag rides the argv: $argv"
        )
        assertTrue(argv.contains("--oneshot"), "--oneshot stays")
    }

    @Test
    fun `title-only entry briefing says the heading has no body`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "Bare heading").copy(body = ""))
        seedCursor(seq = 0)
        verdict(1)
        engine().dispatch()
        val text = payload(seq = 1).readText()
        assertTrue(
            text.contains("The heading has no body; the title above is the whole entry."),
            "no phantom-content hunting on a title-only heading: $text"
        )
    }

    @Test
    fun `wakeSearchQuery distills three distinctive title words with a full-title fallback`() {
        assertEquals(
            "Quarterly planning retreat",
            wakeSearchQuery("Quarterly planning retreat and offsite"),
        )
        assertEquals(
            "a an of",
            wakeSearchQuery("a an of"),
            "fallback: the full trimmed title when nothing qualifies",
        )
        assertEquals("Bare heading", wakeSearchQuery("Bare heading"), "two words qualify, both kept")
    }

    // ── Gate mode (--gate): the cron runs IS the wake ───────────────────

    /** T1: a gate delivery writes the spawn-shaped gate row, prints the
     * exact one-line cron protocol, and calls commandRunner zero times. */
    @Test
    fun `gate delivery audits a gate row prints the wake line and spawns nothing`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        seedCursor(seq = 0)
        verdict(1)
        val runner = RecordingRunner()
        val outcome = engine(commandRunner = runner, gate = true).dispatch()
        assertEquals(0, runner.argvs.size, "no subprocess of any kind: the cron run IS the wake")
        val briefing = payload(seq = 1)
        assertTrue(briefing.isFile, "the winner's briefing is written exactly as a spawn would")
        assertTrue(briefing.readText().contains("Body of One."))
        val row = auditRows().single()
        assertEquals(1L, row.seq)
        assertEquals(null, row.spawnExit, "spawn-shaped null exit")
        assertEquals(null, row.reason, "a delivery, not a refusal")
        assertFalse(row.dryRun)
        assertTrue(row.gate, "the gate bit is the only new field on the row")
        assertEquals("wakes/dev-planner-1.md", row.payload)
        val winner = outcome.agents.single().gateWinners.single()
        assertEquals(1L, winner.seq)
        assertEquals(
            briefing.absolutePath, winner.briefingPath,
            "the cron script's cwd is not the dispatcher's: absolute path",
        )
        assertEquals(
            "1\t${briefing.absolutePath}",
            gateStdoutLine(outcome),
            "the exact one-line wake protocol on stdout",
        )
        assertEquals(1, outcome.agents.single().spawnedRegular, "same spawned counts as a spawn run")
        assertEquals(1L, dispatchCursor(), "consumed: nothing pending, the cursor passes")
    }

    /** T2: the gated seq never re-appears; the second run is explicit
     * silence. */
    @Test
    fun `gate dedupe makes the second run over the same state the quiet line`() {
        val writer = SpoolWriter(state)
        writer.append(spoolEvent(0, "One"))
        seedCursor(seq = 0)
        verdict(1)
        engine(gate = true).dispatch()
        val second = engine(gate = true).dispatch()
        assertTrue(second.agents.single().gateWinners.isEmpty(), "no new winner")
        assertEquals(
            GATE_QUIET_LINE, gateStdoutLine(second),
            "the quiet line is printed, not an empty stdout",
        )
        val cursor = dispatchCursor()
        assertTrue(
            selectWakeCandidates(state, "dev-planner", cursor, null).candidates.none { it.seq == 1L },
            "the gate-consumed seq never re-appears as a candidate",
        )
        assertEquals(1, auditRows().count { it.seq == 1L }, "one delivery row, not two")
    }

    /** T3: gate deliveries count against the lane's daily budget to the
     * cap — the gate rows are the ledger. */
    @Test
    fun `gate deliveries count against the lane budget to the cap`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2); verdict(3)
        val cfg = listOf(
            wakeConfig(wake = WakePolicy.On(maxWakes = 2, maxUrgentWakes = 1, minWakeIntervalMinutes = 0))
        )
        val first = engine(configs = cfg, gate = true).dispatch()
        // Spacing is off, so both in-budget deliveries land in one tick:
        assertEquals(2, first.agents.single().gateWinners.size, "MAX_WAKES gate deliveries")
        assertEquals(2, auditRows().count { it.gate && it.reason == null })
        assertEquals("cap", auditRows().first { it.seq == 1L }.reason, "the rest audits cap")
        val second = engine(configs = cfg, gate = true).dispatch()
        assertEquals(0, second.agents.single().gateWinners.size)
        assertEquals(GATE_QUIET_LINE, gateStdoutLine(second), "capped: quiet")
        assertEquals(0L, dispatchCursor(), "the cap-pending seq keeps the cursor pinned")
    }

    /** T4: the interval clock reads gate rows — an immediate second run
     * audits interval. */
    @Test
    fun `gate interval an immediate second run reads the gate row's clock`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        val cfg = listOf(
            wakeConfig(wake = WakePolicy.On(maxWakes = 5, maxUrgentWakes = 5, minWakeIntervalMinutes = 60))
        )
        val first = engine(configs = cfg, gate = true).dispatch()
        val winner = first.agents.single().gateWinners.single()
        assertEquals(2L, winner.seq, "newest-first: one gate line per tick")
        assertEquals(1, auditRows().count { it.reason == "interval" }, "the rest audits interval")
        val second = engine(configs = cfg, gate = true).dispatch()
        assertEquals(0, second.agents.single().gateWinners.size)
        assertEquals(GATE_QUIET_LINE, gateStdoutLine(second))
        assertTrue(
            auditRows().any { it.reason == "interval" && it.seq == 1L },
            "the interval clock reads gate rows as spawn attempts",
        )
        assertEquals(0L, dispatchCursor(), "the interval-blocked seq stays above the cursor")
    }

    /** T5: a live lease is quiet and consumes nothing, exactly as a
     * spawn run; no briefing is written while blocked. */
    @Test
    fun `gate lease-live run prints quiet consumes nothing and writes no briefing`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        makeLive()
        val runner = RecordingRunner()
        val outcome = engine(commandRunner = runner, gate = true).dispatch()
        assertEquals(GATE_QUIET_LINE, gateStdoutLine(outcome))
        assertEquals(0, outcome.agents.single().gateWinners.size)
        assertEquals(
            setOf("lease"),
            auditRows().map { it.reason }.toSet(),
            "the ladder audits lease refusals identically to a spawn run",
        )
        assertEquals(0L, dispatchCursor(), "cursor frozen")
        assertEquals(0, runner.argvs.size)
        assertFalse(payload(seq = 1).isFile, "briefing untouched: nothing was written while blocked")
        assertFalse(payload(seq = 2).isFile)
    }

    /** T6: historical pre-gate rows decode with the =gate=false= wire
     * default and still consume — dedupe and budget — exactly as before. */
    @Test
    fun `pre-gate audit rows decode with the gate default and still consume`() {
        val writer = SpoolWriter(state)
        repeat(3) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2); verdict(3)
        // A historical spawn row, exactly as the pre-gate dispatcher
        // wrote it — no gate key on the wire (2026-11-15 incident files'):
        val audits = File(state, "wakes").apply { mkdirs() }.resolve("2026-11-12.ndjson")
        val historical = """{"agent":"dev-planner","seq":2,""" +
            """"unit":"arcology-wake-dev-planner-2","spawnExit":0,"dryRun":false,""" +
            """"lane":"regular","gated":false,"ts":"2026-11-12T07:55:00-08:00",""" +
            """"payload":"wakes/dev-planner-2.md"}"""
        audits.writeText(historical + "\n")
        val decoded = WakeJson.decodeFromString(WakeAuditLine.serializer(), historical)
        assertEquals(false, decoded.gate, "historical rows decode with the wire default")
        assertEquals(0, decoded.spawnExit)
        val cfg = listOf(
            wakeConfig(wake = WakePolicy.On(maxWakes = 2, maxUrgentWakes = 1, minWakeIntervalMinutes = 0))
        )
        val outcome = engine(configs = cfg, gate = true).dispatch()
        assertEquals(
            listOf(3L), outcome.agents.single().gateWinners.map { it.seq },
            "seq 2 was already attempted: the next eligible seq delivers",
        )
        assertTrue(
            selectWakeCandidates(state, "dev-planner", 0L, null).candidates.none { it.seq == 2L },
            "the pre-gate seq never re-appears as a candidate",
        )
        assertEquals(
            "cap", auditRows().first { it.seq == 1L }.reason,
            "the historical row's budget slot is still spent against the gate run",
        )
    }

    /** T7: gate consumption counts as spawned for the frontier rule. */
    @Test
    fun `gate consumption advances the cursor like a spawn and never past a pending seq`() {
        val writer = SpoolWriter(state)
        repeat(2) { writer.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        // Pending below the winner: the cursor stays under it.
        val cfg = listOf(
            wakeConfig(wake = WakePolicy.On(maxWakes = 1, maxUrgentWakes = 1, minWakeIntervalMinutes = 0))
        )
        engine(configs = cfg, gate = true).dispatch()
        assertEquals(0L, dispatchCursor(), "the cap-pending seq 1 stays above the cursor")
        // With nothing pending the cursor passes the gate-consumed seq.
        state = Files.createTempDirectory("harness-dispatch-gate-cursor").toFile()
        val writer2 = SpoolWriter(state)
        repeat(2) { writer2.append(spoolEvent(0, "Event ${it + 1}")) }
        seedCursor(seq = 0)
        verdict(1); verdict(2)
        engine(gate = true).dispatch()
        assertEquals(
            2L, dispatchCursor(),
            "delivered ⇒ consumed, even though nothing was spawned",
        )
    }

    /** T8: the --gate CLI refusals, pinned via the factored validation. */
    @Test
    fun `gate CLI validations pin the refuse messages`() {
        assertEquals(null, gateModeCliktError(gate = false, dryRun = false, agent = null))
        assertEquals(
            null,
            gateModeCliktError(gate = true, dryRun = false, agent = "demo"),
            "a named agent in plain gate mode is the deployed shape",
        )
        val withDryRun = gateModeCliktError(gate = true, dryRun = true, agent = "demo")
        assertNotNull(withDryRun)
        assertTrue(withDryRun.contains("mutually exclusive with --dry-run"), withDryRun)
        val withoutAgent = gateModeCliktError(gate = true, dryRun = false, agent = null)
        assertNotNull(withoutAgent)
        assertTrue(withoutAgent.contains("--agent"), withoutAgent)
    }

    /** T9: gate deliveries report in the SAME spawned counts, so the
     * pinned text renderer stays byte-identical. */
    @Test
    fun `gate deliveries render in the same spawned counts as a spawn run`() {
        fun render(agent: DispatchAgentOutcome): String =
            "  ${agent.agent}: spawned regular=${agent.spawnedRegular} urgent=${agent.spawnedUrgent}, " +
                "held=${agent.held} cap=${agent.capped} interval=${agent.interval} " +
                "lease=${agent.leaseSkipped} missing=${agent.eventMissing}, cursor ${agent.cursor}"
        fun seed() {
            val writer = SpoolWriter(state)
            writer.append(spoolEvent(0, "Urgent one"))
            writer.append(spoolEvent(0, "Regular two"))
            seedCursor(seq = 0)
            verdict(1, urgency = 0.95)
            verdict(2)
        }
        val cfg = listOf(
            wakeConfig(urgency = true, wake = WakePolicy.On(maxWakes = 3, maxUrgentWakes = 1, minWakeIntervalMinutes = 0))
        )
        seed()
        val spawnRunner = RecordingRunner()
        val spawnText = render(engine(configs = cfg, commandRunner = spawnRunner).dispatch().agents.single())
        state = Files.createTempDirectory("harness-dispatch-gate-render").toFile()
        seed()
        val gateOutcome = engine(configs = cfg, gate = true).dispatch()
        val gateAgent = gateOutcome.agents.single()
        assertEquals(
            spawnText, render(gateAgent),
            "the pinned CLI summary renders a gate delivery in the same spawned counts",
        )
        assertEquals(2, gateAgent.gateWinners.size, "regular + urgent delivered, one cron wake line each")
        assertEquals(2, auditRows().count { it.gate && it.reason == null })
    }
}

Locks and lease tests

kotlin#+name: harness-locks-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/HarnessLocksTest.kt
package computer.whatthefuck.arcology.harness

import java.io.File
import java.nio.file.Files
import java.time.OffsetDateTime
import kotlin.test.*

class HarnessLocksTest {

    private fun makeLockFile(name: String): File =
        File(Files.createTempDirectory("harness-locks").toFile(), name)

    @Test
    fun `second channel is busy until release`() {
        val lockFile = makeLockFile("producer.lock")
        val first = HarnessFileLock(lockFile)
        assertTrue(first.tryLock(), "first acquisition")
        val second = HarnessFileLock(lockFile)
        assertFalse(second.tryLock(), "contended: busy")
        first.close()
        assertTrue(second.tryLock(), "release frees the lock")
        second.close()
    }

    @Test
    fun `locks helper surfaces busy and free for status probes`() {
        val locks = HarnessLocks(Files.createTempDirectory("harness-locks-h").toFile())
        val held = locks.tryAcquire("drain.lock")
        assertNotNull(held)
        assertNull(locks.tryAcquire("drain.lock"), "second acquire is busy")
        assertTrue(locks.isLocked("drain.lock"))
        held.close()
        assertFalse(locks.isLocked("drain.lock"))
        // produce-exit-2 / drain-exit-0 map off exactly this: a null
        // acquire means "busy" — produce exits 2 with a stderr line,
        // drain prints one stdout line and exits 0 (CLI wiring).
    }
}

class LeaseStoreTest {
    private lateinit var state: File
    private lateinit var proc: File

    @BeforeTest
    fun setup() {
        state = Files.createTempDirectory("harness-lease").toFile()
        proc = Files.createTempDirectory("harness-proc").toFile()
    }

    private val now: () -> OffsetDateTime = {
        OffsetDateTime.parse("2026-11-10T09:00:30-08:00")
    }

    private fun store() = LeaseStore(state, procRoot = proc.path, now = now)

    private fun writeLease(
        pid: Long,
        started: String = "2026-11-10T09:00:00-08:00",
        ttlMinutes: Int = 60,
        wakeKey: String = "w1",
        cmdline: String? = null,
    ) {
        Files.createDirectories(store().file("dev-planner").parentFile.toPath())
        store().file("dev-planner").writeText(
            """{"pid":$pid,"started":"$started","wake_key":"$wakeKey","ttl_minutes":$ttlMinutes}"""
        )
        // No cmdline argument ⇒ the pid dir is NOT provisioned: a dead pid.
        if (cmdline != null) {
            val pidDir = File(proc, "$pid").apply { mkdirs() }
            File(pidDir, "cmdline").writeBytes(cmdline.toByteArray())
        }
    }

    @Test
    fun `acquire grants and holds - a live holder refuses and force steals`() {
        // A live lease for pid 42: dir exists in the fake procfs, cmdline
        // carries the agent name (nul-separated like the real one).
        writeLease(pid = 42, cmdline = "hermes-agent\u0000--service\u0000dev-planner\u0000")
        val refused = store().acquire("dev-planner", ttlMinutes = 60, wakeKey = "w2", force = false)
        assertTrue(refused is LeaseAcquire.Refused, "live holder refuses")
        assertEquals(42L, (refused as LeaseAcquire.Refused).lease.pid)
        // Force steals: the file is rewritten with OUR pid.
        val stolen = store().acquire("dev-planner", ttlMinutes = 60, wakeKey = "w2", force = true)
        assertTrue(stolen is LeaseAcquire.Granted)
        val holder = (stolen as LeaseAcquire.Granted).lease
        assertTrue(holder.pid > 0, "steal rewrote the lease with our real pid")
        // A re-acquire is granted: the holder pid has no fake-proc dir.
        assertTrue(store().acquire("dev-planner", 60, "w3", force = false) is LeaseAcquire.Granted)
        // Release is idempotent.
        assertTrue(store().release("dev-planner"))
        assertFalse(store().release("dev-planner"))
        assertNull(store().file("dev-planner").takeIf { it.isFile })
    }

    @Test
    fun `ttl expiry frees the lease`() {
        writeLease(pid = 42, started = "2026-11-10T07:00:00-08:00", ttlMinutes = 60)
        // 2h old > 60m TTL, dead pid aside.
        assertNull(store().live("dev-planner"), "expired lease is not live")
    }

    @Test
    fun `dead pid frees the lease even inside its ttl`() {
        writeLease(pid = 42) // no fake-proc dir for 42
        assertNull(store().live("dev-planner"), "pid gone: not live")
    }

    @Test
    fun `unreadable cmdline falls back to ttl-only liveness`() {
        writeLease(pid = 42) // no cmdline file
        // Alive pid: the dir exists in procfs but cmdline is unreadable.
        java.nio.file.Files.createDirectories(File(proc, "42").toPath())
        assertNotNull(store().live("dev-planner"), "alive pid, unreadable cmdline: TTL-only")
    }

    @Test
    fun `cmdline without the agent name reads as dead`() {
        writeLease(pid = 42, cmdline = "hermes-agent\u0000unrelated-service\u0000")
        assertNull(store().live("dev-planner"), "cmdline mismatch: not this agent's lease")
    }

    @Test
    fun `acquire writes the lease json and check reads it back`() {
        val outcome = store().acquire("dev-planner", ttlMinutes = 5, wakeKey = "k", force = false)
        assertTrue(outcome is LeaseAcquire.Granted)
        val lease = store().load("dev-planner")
        requireNotNull(lease)
        assertEquals(lease.ttlMinutes, 5)
        assertEquals(lease.wakeKey, "k")
        assertEquals(lease.pid, ProcessHandle.current().pid())
        // Status-render liveness: provision the fake procfs dir for OUR
        // own pid (no cmdline file → TTL-only fallback).
        Files.createDirectories(File(proc, "${lease.pid}").toPath())
        assertNotNull(store().live("dev-planner"))
    }
}

Status tests

kotlin#+name: harness-status-tests:tangle ../src/jvmTest/kotlin/computer/whatthefuck/arcology/harness/HarnessStatusTest.kt
package computer.whatthefuck.arcology.harness

import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json
import java.io.File
import java.nio.file.Files
import kotlin.test.*

class HarnessStatusTest {
    private lateinit var state: File

    @BeforeTest
    fun setup() {
        state = Files.createTempDirectory("harness-status").toFile()
    }

    private fun now() = java.time.OffsetDateTime.parse("2026-11-10T08:35:46-08:00")

    private fun status() = renderHarnessStatus(state, now())

    @Test
    fun `empty state renders none-markers`() {
        val text = status()
        assertTrue(text.contains("spool lag: spool empty"))
        assertTrue(text.contains("spool depth: 0 events in 2026-11.ndjson"))
        assertTrue(text.contains("snapshot files: 0"))
        assertTrue(text.contains("today's events:\n  (none)"))
        assertTrue(text.contains("verdict cursors:\n  (none)"))
    }

    @Test
    fun `lag depth snapshots and today titles render in one shot`() {
        val writer = SpoolWriter(state)
        writer.append(
            SpoolEvent(
                ts = "2026-11-09T20:00:00-08:00", scope = "journal",
                file = "journals/2026-11/09.org",
                identity = SpoolIdentity(null, "journals/2026-11/09.org::1"),
                action = "added", title = "Yesterday entry", body = "",
                revision = "r1", risk = SpoolRisk(max = 0.2, gated = false),
                modifiedBy = "local",
            )
        )
        writer.append(
            SpoolEvent(
                ts = "2026-11-10T08:12:03-08:00", scope = "journal",
                file = "journals/2026-11/10.org",
                identity = SpoolIdentity(null, "journals/2026-11/10.org::4.2"),
                action = "revised", title = "Morning entry", body = "",
                revision = "r2", risk = SpoolRisk(max = 0.3, gated = false),
                modifiedBy = "local",
            )
        )
        SnapshotStore(state).save(
            "journals/2026-11/10.org",
            mapOf("4.2" to SnapshotEntry("r2"))
        )
        File(state, "cursors").mkdirs()
        File(state, "cursors/dev-planner.verdict").writeText("1\n")

        val text = status()
        // lag: newest 08:12:03 vs now 08:35:46 → 1423 s
        assertTrue(
            text.contains(
                "spool lag: 1423s (newest 2026-11-10T08:12:03-08:00, now 2026-11-10T08:35:46-08:00)"
            ),
            "lag computed from the newest event ts: $text"
        )
        assertTrue(text.contains("spool depth: 2 events in 2026-11.ndjson"))
        assertTrue(text.contains("snapshot files: 1"))
        assertTrue(text.contains("  2 revised Morning entry"), "today's titles with seq/action")
        assertFalse(text.contains("Yesterday entry"), "yesterday's event is not today's list")
        assertTrue(text.contains("verdict cursors:\n  dev-planner: 1 (lag 1)"))
    }

    @Test
    fun `markers locks leases and stale counts render deterministically`() {
        val writer = SpoolWriter(state)
        writer.append(
            SpoolEvent(
                ts = "2026-11-10T08:12:03-08:00", scope = "journal",
                file = "j.org", identity = SpoolIdentity(null, "j.org::1"),
                action = "added", title = "Event", body = "", revision = "r1",
                risk = SpoolRisk(max = 0.1, gated = false), modifiedBy = "local",
            )
        )
        writer.appendRaw(
            SpoolWriter.buildBaselineMarker(
                files = 7, headings = 42, headSeq = 1, ts = "2026-11-10T08:00:00-08:00"
            )
        )
        // producer.lock held from THIS process: the probe channel in
        // status sees it as held (advisory locks are per-process).
        val heldLock = HarnessLocks(state).tryAcquire("drain.lock")
        // A live lease for a fake procfs pid.
        val proc = Files.createTempDirectory("harness-status-proc").toFile()
        File(proc, "4242").mkdirs()
        File(state, "locks").mkdirs()
        File(state, "locks/dev-planner.lease").writeText(
            """{"pid":4242,"started":"2026-11-10T08:30:00-08:00",""" +
                """"wake_key":"w1","ttl_minutes":60}"""
        )
        // A stale verdict in today's verdicts file.
        File(state, "verdicts").mkdirs()
        File(state, "verdicts/2026-11-10.ndjson").writeText(
            """{"seq":9,"agent":"dev-planner","verdict":"stale",""" +
                """"confidence":"stale-rule","model":"stale-rule",""" +
                """"ts":"2026-11-10T08:00:01-08:00"}""" + "\n"
        )

        val text = renderHarnessStatus(state, now(), procRoot = proc.path)
        assertTrue(text.contains("spool depth: 1 events in 2026-11.ndjson"), "markers do not inflate depth: $text")
        assertTrue(text.contains("producer lock: free"))
        assertTrue(text.contains("drain lock: held"))
        assertTrue(text.contains("leases:\n  dev-planner: pid 4242, age 346s"), "agent, pid, age")
        assertTrue(text.contains("today's stale verdicts: 1"))
        heldLock?.close()
    }

    // ── status --json (the A2 machine-readable schema) ────────────────

    private fun writeVerdictRow(seq: Long, agent: String, verdict: String = "yes") =
        File(state, "verdicts").also { it.mkdirs() }
            .resolve("2026-11-10.ndjson")
            .appendText(
                VerdictJson.encodeToString(
                    VerdictLogLine.serializer(),
                    VerdictLogLine(
                        seq = seq, agent = agent, verdict = verdict,
                        confidence = if (verdict == "stale")
                            kotlinx.serialization.json.JsonPrimitive("stale-rule")
                        else
                            kotlinx.serialization.json.JsonPrimitive(0.75),
                        model = if (verdict == "stale") "stale-rule" else "test",
                        ts = "2026-11-10T08:00:01-08:00",
                    )
                ) + "\n"
            )

    private fun cursorFile(agent: String, seq: Long) {
        File(state, "cursors").also { it.mkdirs() }
            .resolve("$agent.verdict").writeText("$seq\n")
    }

    @Test
    fun `empty state report is stable and nulls stay null`() {
        val report = collectHarnessStatus(state, now(), endpointEnv = { null })
        assertEquals(0L, report.spool.maxSeq)
        assertNull(report.spool.newest)
        assertNull(report.spool.lagSeconds, "an empty spool reads as absent lag, not zero")
        assertEquals(0L, report.spool.depthThisMonth)
        assertEquals(0, report.snapshotFiles)
        assertTrue(report.agents.isEmpty())
        assertNull(report.endpoint)
        assertTrue(report.locks.producer.not() && report.locks.drain.not())
    }

    @Test
    fun `verdict rows count per agent and failed tracks the endpoint`() {
        writeVerdictRow(30, "dev-planner")
        writeVerdictRow(31, "dev-planner", verdict = "stale")
        writeVerdictRow(32, "dev-planner")
        writeVerdictRow(33, "make-legible")
        cursorFile("dev-planner", 30)
        cursorFile("make-legible", 29)
        // One fresh spool event. SpoolWriter assigns the REAL seq (1) —
        // the cursor labels are deliberately above it, so the lag reads
        // NEGATIVE: a head-initialized agent whose cursor sits past a
        // deliberately-skipped history.
        SpoolWriter(state).append(
            SpoolEvent(
                ts = "2026-11-10T08:35:07-08:00", scope = "journal",
                file = "journals/2026-11/10.org",
                identity = SpoolIdentity(null, "journals/2026-11/10.org::1"),
                action = "added", title = "Fresh", body = "",
                revision = "r", risk = SpoolRisk(max = 0.1, gated = false),
                modifiedBy = "local",
            )
        )
        val report = collectHarnessStatus(state, now(), endpointEnv = { "http://model:11434" })
        assertEquals("http://model:11434", report.endpoint)
        assertEquals(1L, report.spool.maxSeq, "the producer's real head, not the fixture label")
        assertEquals(39L, report.spool.lagSeconds, "now is 39s after the event timestamp")
        assertEquals("2026-11-10T08:35:07-08:00", report.spool.newest)
        assertEquals(-29L, report.agents.first { it.agent == "dev-planner" }.lag)
        assertEquals(-28L, report.agents.first { it.agent == "make-legible" }.lag)
        val dev = report.agents.first { it.agent == "dev-planner" }
        assertEquals(3, dev.verdictsToday)
        assertEquals(1, dev.staleToday)
        assertFalse(dev.failed)
        // The A2 v1 semantics: no endpoint in the environment = failed.
        val failed = collectHarnessStatus(state, now(), endpointEnv = { null })
        assertTrue(failed.agents.all { it.failed })
        assertEquals(null, failed.endpoint)
    }

    @Test
    fun `json round-trips and pins the schema field names`() {
        writeVerdictRow(30, "dev-planner")
        cursorFile("dev-planner", 30)
        val report = collectHarnessStatus(state, now(), endpointEnv = { "http://h" })
        val json = statusJson.encodeToString(HarnessStatusReport.serializer(), report)
        val back = statusJson.decodeFromString(HarnessStatusReport.serializer(), json)
        assertEquals(report, back)
        // Schema pins: the textfile jq transform depends on these names.
        assertTrue(json.contains("\"now\""))
        assertTrue(json.contains("\"endpoint\""))
        assertTrue(json.contains("\"spool\""))
        assertTrue(json.contains("\"lagSeconds\""))
        assertTrue(json.contains("\"agents\""))
        assertTrue(json.contains("\"verdictsToday\""))
        assertTrue(json.contains("\"failed\""))
        assertTrue(json.contains("\"dev-planner\""))
    }

    // ── A3 additive dispatch fields ─────────────────────────────────────

    private fun writeAuditRow(seq: Long, lane: String, spawned: Boolean = true) =
        File(state, "wakes").also { it.mkdirs() }
            .resolve("2026-11-10.ndjson")
            .appendText(
                WakeJson.encodeToString(
                    WakeAuditLine.serializer(),
                    WakeAuditLine(
                        agent = "dev-planner", seq = seq,
                        unit = "arcology-wake-dev-planner-$seq",
                        spawnExit = if (spawned) 0 else null,
                        dryRun = false, lane = lane, reason = null, gated = false,
                        ts = "2026-11-10T08:05:00-08:00",
                        payload = if (spawned) "wakes/dev-planner-$seq.md" else null,
                    )
                ) + "\n"
            )

    private fun dispatchCursorFile(agent: String, seq: Long) {
        File(state, "cursors").also { it.mkdirs() }
            .resolve("$agent.dispatch").writeText("$seq\n")
    }

    @Test
    fun `dispatch fields read additively from wakes and dispatch cursors`() {
        writeVerdictRow(30, "dev-planner")
        writeVerdictRow(31, "dev-planner")
        cursorFile("dev-planner", 30)
        dispatchCursorFile("dev-planner", 29)
        writeAuditRow(30, lane = "regular")
        writeAuditRow(31, lane = "urgent", spawned = false) // not an attempt
        val report = collectHarnessStatus(state, now(), endpointEnv = { "http://h" })
        val dev = report.agents.first { it.agent == "dev-planner" }
        assertEquals(29L, dev.dispatchCursor)
        assertEquals(1, dev.wakesRegularToday, "only spawned-attempts count")
        assertEquals(0, dev.wakesUrgentToday)
        assertEquals(1, dev.heldWakes, "yes row 31 above cursor, not yet spawned")
        // A make-legible dispatch cursor shows up even with no drain
        // activity — agents are the union of both cursor families.
        dispatchCursorFile("make-legible", 5)
        val report2 = collectHarnessStatus(state, now(), endpointEnv = { "http://h" })
        assertEquals(2, report2.agents.size)
        val legible = report2.agents.first { it.agent == "make-legible" }
        assertEquals(5L, legible.dispatchCursor)
        assertEquals(0L, legible.cursor, "no verdict cursor yet")
    }

    @Test
    fun `json schema pins the dispatch field names`() {
        dispatchCursorFile("dev-planner", 29)
        val report = collectHarnessStatus(state, now(), endpointEnv = { "http://h" })
        val json = statusJson.encodeToString(HarnessStatusReport.serializer(), report)
        assertTrue(json.contains("\"dispatchCursor\""))
        assertTrue(json.contains("\"wakesRegularToday\""))
        assertTrue(json.contains("\"wakesUrgentToday\""))
        assertTrue(json.contains("\"heldWakes\""))
        val back = statusJson.decodeFromString(HarnessStatusReport.serializer(), json)
        assertEquals(report, back, "the additive fields round-trip")
    }

    @Test
    fun `text renderer stays byte-identical across dispatch state`() {
        writeVerdictRow(30, "dev-planner")
        cursorFile("dev-planner", 30)
        val before = renderHarnessStatus(state, now())
        dispatchCursorFile("dev-planner", 29)
        writeAuditRow(30, lane = "regular")
        val after = renderHarnessStatus(state, now())
        assertEquals(before, after, "A3 dispatch state never changes the text render")
    }
}

Related modules

  • llm/tools.org — the notes headings enumeration this module consumes; EXCLUDE_TAG_SET semantics

  • llm/classifier.org — RiskClassifier client and fail-closed posture; the llm_verdict_cache precedent re-homed as a plain ndjson file here

  • roam/syncthing.org — the codified per-subscription event pitfall and the watch-loop shape this module copies

  • app/cli.org — the command tree the harness family hangs from

  • roam/indexer.org — the db the harness deliberately never touches</think>Let me fix the verdict test block I sketched poorly (embedded-server approach like RiskClassifierTest instead):<tool_call>edit