Introduction

The arcology2 notes sub-commands provide machine-readable query mechanisms designed to be wrapped by agent harnesses. Harnesses can read, search, query timelines, capture, and query notes without filesystem access.. no constant file_read prompts, no allowlist on ~/org, no leaking private notes to remote inference.

No file paths on any read tool. Note access is by org-roam node ID. Queries never return the file path.
Private data is omitted from the remote harness. A local GPU runs Together AI's tev1:4b decision model through Ollama's /v1/systemone endpoint (classifier.org) to judge the risk of sending the file content to remote inference providers. nimble:9b and tev1:0.8b speak the same endpoint and swap in via --risk-model.
Exclusion matches the web interface. EXCLUDE_TAGS hides nodes, and their subheadings here too. An excluded note returns not_found so its existence isn't confirmed.
Fail closed. When the risk classifier gates a note, note-get returns only the echo of the requested ID plus the risk block: no title, tags, aliases, properties, links, or children, because all of those leak signal about otherwise-withheld content. If the classifier is unavailable, the agent harness is locked out from accessing the system.
*--verbose is a debug instrument.* Invoked per tool, it attaches the classifier's request/response transcript to the risk block (see classifier.org).

The `arcology2 notes` Command Group

kotlin#+name: tools-notes-parent

class NotesCommand : CliktCommand(
    name = "notes",
    help = "LLM-harness tools: get, search, timeline, capture, sql"
) {
    override fun run() = Unit
}

Common Base

kotlin#+name: tools-base-command

/**
 * Tags that suppress a note from tool output, mirroring the publishing
 * layer's exclusions. Case-sensitive on purpose: :ARCHIVE: hides,
 * :Archive: (a knowledge-organization tag) does not. Declared once in
 * [[*TimestampsIndexerPlugin — all DTStamp entities at index time]]'s tangle
 * target (commonMain) so both the plugin and the jvmMain tools see it.
 */
const val DEFAULT_MAX_BODY_BYTES: Long = 20_480L

abstract class NoteToolBase(name: String, help: String) : CliktCommand(name = name, help = help) {
    protected val dbPath: String by option("--db", help = "Path to SQLite database")
        .default("~/org/arcology.db")
    protected val orgDir: String by option("--org-dir", help = "Root org-mode directory")
        .default("~/org")
    // Nullable options with no explicit default: Clikt yields null when
    // absent. Env fallback happens in makeGate — same pattern as SyncCommand.
    protected val riskEndpoint: String? by option(
        "--risk-endpoint",
        help = "Ollama http://host:port for the risk classifier (default: \$ARCOLOGY_RISK_ENDPOINT)"
    )
    protected val riskModel: String? by option(
        "--risk-model", help = "Decision model name (default: \$ARCOLOGY_RISK_MODEL or tev1:4b)"
    )
    protected val riskThreshold: Double by option(
        "--risk-threshold", help = "Overall score above which content is redacted (score = rubric level/4; bench calibration: 0.40 ≈ identifying-detail level, clean notes top out ≈ 0.3)"
    ).double().default(0.40)

    /** =--no-risk-gate=: explicit escape hatch for trusted local runs. */
    protected val noRiskGate: Boolean by option(
        "--no-risk-gate", help = "Disable risk gating for this invocation"
    ).flag(default = false)

    /** =--verbose=: attach the classifier input/output transcript to the envelope. */
    protected val verbose: Boolean by option(
        "--verbose", help = "Include the classifier request/response transcript in the risk block"
    ).flag(default = false)

    /**
     * =--ensure-fresh=: run one incremental indexing pass (hash-skip cheap)
     * before the read, for cron contexts that can't run `notes reindex`
     * first. Opt-in; never the default.
     */
    protected val ensureFresh: Boolean by option(
        "--ensure-fresh", help = "Run one incremental index pass before reading"
    ).flag(default = false)

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

    protected fun openRepo(): ToolQueryRepository =
        ToolQueryRepositoryImpl(DatabaseFactory.createDatabase(expandTilde(dbPath)))

    /** Classifier when endpoint configured; else null — gate fails closed. */
    protected fun makeGate(repo: ToolQueryRepository): RiskGate {
        val endpoint = riskEndpoint ?: System.getenv("ARCOLOGY_RISK_ENDPOINT")
        val model = riskModel ?: System.getenv("ARCOLOGY_RISK_MODEL") ?: "tev1:4b"
        val classifier = endpoint?.let { ep ->
            RiskClassifier(
                endpoint = ep,
                model = model,
                httpClient = HttpClient {
                    install(HttpTimeout) { requestTimeoutMillis = 45_000 }
                }
            )
        }
        return RiskGate(repo, classifier, model = model, trustLocal = noRiskGate)
    }

    suspend fun printEnvelope(envelope: ToolEnvelope) {
        println(ToolJson.encodeToString(ToolEnvelope.serializer(), envelope))
    }

    /** Emit an error envelope and abort with the message. */
    protected suspend fun fail(code: String, message: String): Nothing {
        println(
            ToolJson.encodeToString(
                ToolEnvelope.serializer(),
                ToolEnvelope(ok = false, error = ToolError(code, message))
            )
        )
        throw CliktError(message)
    }
}

`arcology2 notes get`

Metadata, child discovery stubs, links/refs, and the leaf body — gated.

kotlin#+name: tools-note-get


/** Tool-facing node projection — no file path field, by design. */
data class NodeRecord(
    val id: String,
    val level: Long,
    val todo: String?,
    val priority: String?,
    val scheduled: String?,
    val deadline: String?,
    val title: String?,
    val properties: String?,
    val olp: String?
)

Body rendering — the document-AST walk

The parser's nodeContents map is a content-roll-up aggregate built for FTS indexing: ID-less headings' text rolls up to the nearest ID-bearing ancestor, unfiltered by exclusion tags. notes get instead renders straight from the parsed document AST with publishing-layer exclusion semantics:

The focused section's own text: paragraphs, lists, tables, and blocks (quote, verse, src, etc)... HTML export blocks #+begin_html are publisher markup, not prose, and are elided.
ID-less nested headings render *inline with their title line as an org heading followed by their text, their text has no node of its own to fetch, and org semantics put it in the parent's content stream. - ID-bearing nested headings collapse to =* Title [id:…]= stubs to be pulled on their own - Any nested heading tagged =noexport=/=NOEXPORT=/=ARCHIVE= is elided entirely*.
All this holds for file-level nodes too.

kotlin#+name: tools-body-renderer

/**
 * True when the heading itself carries an exclusion tag (noexport/NOEXPORT/
 * ARCHIVE) — mirrors the publishing layer's EXCLUDE_TAGS semantics. Only the
 * heading's *own* tags count here: inherited exclusion (an excluded parent
 * already removed this subtree during the walk) and excluded ancestors are
 * handled by the recursive render, and filetags deliberately do NOT exclude
 * (a file tagged :noshow: still wants its tool output).
 */
internal fun isExcludedHeading(heading: xyz.lepisma.orgmode.OrgHeading): Boolean {
    val tags = heading.tags?.tags ?: return false
    return tags.any { it in EXCLUDE_TAG_SET }
}

/** Recursive plaintext walk over org chunks with heading rendering. */
internal fun renderChunksPlaintext(
    chunks: List<xyz.lepisma.orgmode.OrgChunk>,
    sb: StringBuilder
) {
    for (chunk in chunks) {
        when (chunk) {
            is xyz.lepisma.orgmode.OrgChunk.OrgParagraph -> {
                val line = chunk.tokens.joinToString("") { it.text }.trim()
                if (line.isNotEmpty()) {
                    sb.appendLine(line)
                    sb.appendLine()
                }
            }
            is xyz.lepisma.orgmode.OrgChunk.OrgTable ->
                (listOfNotNull(chunk.header) + chunk.subtables.flatten())
                    .joinTo(sb, "\n", postfix = "\n\n") { row ->
                        row.cells.joinToString(" | ") { it.plainText() }
                    }
            is xyz.lepisma.orgmode.OrgList.OrgUnorderedList ->
                chunk.items.forEach { item ->
                    item.content.forEach { renderChunksInline(it, sb) }
                }
            is xyz.lepisma.orgmode.OrgList.OrgOrderedList ->
                chunk.items.forEach { item ->
                    item.content.forEach { renderChunksInline(it, sb) }
                }
            is xyz.lepisma.orgmode.OrgSection ->
                renderSectionPlaintext(chunk, sb)
            // Org blocks render: OrgBlock is a sealed *namespace* (its 12
            // subclasses extend OrgChunk directly), so delegate the renderable
            // members explicitly rather than testing the namespace type. HTML
            // and the parser-commented comment/video/center types fall to
            // renderChunksInline's catch-all.
            is xyz.lepisma.orgmode.OrgBlock.OrgQuoteBlock,
            is xyz.lepisma.orgmode.OrgBlock.OrgVerseBlock,
            is xyz.lepisma.orgmode.OrgBlock.OrgSourceBlock,
            is xyz.lepisma.orgmode.OrgBlock.OrgExampleBlock,
            is xyz.lepisma.orgmode.OrgChunk.OrgFixedWidthArea,
            is xyz.lepisma.orgmode.OrgBlock.OrgAsideBlock,
            is xyz.lepisma.orgmode.OrgBlock.OrgEditsBlock,
            is xyz.lepisma.orgmode.OrgBlock.OrgPageIntroBlock ->
                renderChunksInline(chunk, sb)
            else -> { } // keyword lines, logbooks, review data: noise for the harness
        }
    }
}

/** Non-section chunk rendered by [[renderChunksPlaintext]] — shared with lists. */
internal fun renderChunksInline(
    chunk: xyz.lepisma.orgmode.OrgChunk,
    sb: StringBuilder
) {
    when (chunk) {
        is xyz.lepisma.orgmode.OrgChunk.OrgParagraph -> {
            val line = chunk.tokens.joinToString("") { it.text }.trim()
            if (line.isNotEmpty()) {
                sb.appendLine(line)
                sb.appendLine()
            }
        }
        is xyz.lepisma.orgmode.OrgBlock.OrgSourceBlock ->
            if (chunk.body.isNotBlank()) {
                sb.appendLine(chunk.body.trim())
                sb.appendLine()
            }
        is xyz.lepisma.orgmode.OrgBlock.OrgExampleBlock ->
            if (chunk.text.isNotBlank()) {
                sb.appendLine(chunk.text.trim())
                sb.appendLine()
            }
        is xyz.lepisma.orgmode.OrgChunk.OrgFixedWidthArea ->
            if (chunk.text.isNotBlank()) {
                sb.appendLine(chunk.text.trim())
                sb.appendLine()
            }
        is xyz.lepisma.orgmode.OrgChunk.OrgTable ->
            (listOfNotNull(chunk.header) + chunk.subtables.flatten())
                .joinTo(sb, "\n", postfix = "\n\n") { row ->
                    row.cells.joinToString(" | ") { it.plainText() }
                }
        is xyz.lepisma.orgmode.OrgBlock.OrgQuoteBlock ->
            chunk.body.forEach { renderChunksInline(it, sb) }
        is xyz.lepisma.orgmode.OrgList.OrgUnorderedList ->
            chunk.items.forEach { item ->
                item.content.forEach { renderChunksInline(it, sb) }
            }
        is xyz.lepisma.orgmode.OrgList.OrgOrderedList ->
            chunk.items.forEach { item ->
                item.content.forEach { renderChunksInline(it, sb) }
            }
        is xyz.lepisma.orgmode.OrgBlock.OrgVerseBlock ->
            if (chunk.body.isNotBlank()) {
                sb.appendLine(chunk.body.trim())
                sb.appendLine()
            }
        is xyz.lepisma.orgmode.OrgBlock.OrgAsideBlock ->
            chunk.body.forEach { renderChunksInline(it, sb) }
        is xyz.lepisma.orgmode.OrgBlock.OrgEditsBlock ->
            chunk.body.forEach { renderChunksInline(it, sb) }
        is xyz.lepisma.orgmode.OrgBlock.OrgPageIntroBlock ->
            chunk.body.forEach { renderChunksInline(it, sb) }
        is xyz.lepisma.orgmode.OrgBlock.OrgHTMLBlock ->
            { } // publisher markup, not prose; elided from plaintext harness output
        is xyz.lepisma.orgmode.OrgSection ->
            renderSectionPlaintext(chunk, sb)
        else -> { }
    }
}

/**
 * Render one heading's section: excluded headings vanish with their subtree;
 * ID-bearing headings collapse to stubs; ID-less headings render their title
 * line and body inline with recursive exclusion checks.
 */
internal fun renderSectionPlaintext(
    section: xyz.lepisma.orgmode.OrgSection,
    sb: StringBuilder
) {
    val tags = section.heading.tags?.tags ?: emptyList()
    if (tags.any { it in EXCLUDE_TAG_SET }) {
        // Excluded subtree: emit nothing, not even a stub. The publishing
        // layer treats the heading as unpublished; the tool treats it as
        // unknowable.
        return
    }

    val id = section.heading.properties?.map
        ?.get("ID")
        ?.let { line -> line.items.filterIsInstance<xyz.lepisma.orgmode.OrgInlineElem.Text>()
            .joinToString("") { it.text }.trim() }
        ?.takeIf { it.isNotEmpty() }

    if (id != null) {
        // ID-bearing child: stub for discovery. NOT the content — the
        // harness fetches it by ID.
        sb.appendLine("${"*".repeat(section.heading.level.level)} ${section.heading.title.plainText()} [id:$id]")
        sb.appendLine()
        return
    }

    // ID-less heading: title line, then body — its text is part of this
    // body. Render inline.
    sb.appendLine("${"*".repeat(section.heading.level.level)} ${section.heading.title.plainText()}")
    sb.appendLine()
    renderChunksPlaintext(section.body, sb)
}

The loader itself:

kotlin#+name: tools-body-loader

/**
 * Render the plaintext body of a note by ID. For a regular heading node:
 * its own section (ID-less children inline, ID-bearing children as stubs,
 * excluded subtrees elided). For the file-level node: preface + all
 * top-level sections with the same rules.
 *
 * Returns null when the node/file is missing or unparseable — callers
 * treat null as "no body". The node's file path never crosses the tool
 * boundary.
 */
suspend fun loadLeafBody(
    database: ArcologyDatabase,
    nodeId: String,
    orgDir: String,
    maxBytes: Long
): String? = withContext(Dispatchers.IO) {
    val relative = database.toolsQueries.selectToolNodeFileById(nodeId)
        .executeAsOneOrNull() ?: return@withContext null
    val file = File(orgDir, relative)
    if (!file.exists()) return@withContext null
    val parseResult = OrgFileParser().parseFileContent(
        relative, file.readText(), Instant.fromEpochSeconds(0)
    )
    val success = parseResult as? ParseResult.Success ?: return@withContext null
    val document = success.document ?: return@withContext null

    val sb = StringBuilder()
    val isFileLevel = nodeId == document.preamble.properties?.map?.get("ID")
        ?.let { line -> line.items.filterIsInstance<xyz.lepisma.orgmode.OrgInlineElem.Text>()
            .joinToString("") { it.text }.trim() }

    if (isFileLevel == true) {
        // File-level node: preface paragraphs + every top-level section,
        // each under the recursion/exclusion/stub rules.
        renderChunksPlaintext(document.preface.body, sb)
        document.content.forEach { section ->
            renderSectionPlaintext(section, sb)
        }
    } else {
        val section = findToolSection(document.content, nodeId) ?: return@withContext null
        renderChunksPlaintext(section.body, sb)
    }

    val body = sb.toString().trim()
    if (body.isEmpty()) return@withContext null
    if (body.length > maxBytes) {
        body.take(maxBytes.toInt()) + "\n\n[truncated at $maxBytes bytes]"
    } else {
        body
    }
}

/** Section lookup owned by the llm package (same logic as publishing's helper). */
internal tailrec fun findToolSection(
    sections: List<xyz.lepisma.orgmode.OrgSection>,
    nodeId: String
): xyz.lepisma.orgmode.OrgSection? {
    if (sections.isEmpty()) return null
    for (section in sections) {
        val sectionId = section.heading.properties?.map?.get("ID")
            ?.let { line -> line.items.filterIsInstance<xyz.lepisma.orgmode.OrgInlineElem.Text>()
                .joinToString("") { it.text }.trim() }
        if (sectionId == nodeId) return section
    }
    // recurse: sections' nested bodies are the children lists
    val nested = sections.flatMap { it.body.filterIsInstance<xyz.lepisma.orgmode.OrgSection>() }
    return findToolSection(nested, nodeId)
}

The CLI command wrapper:

kotlin#+name: tools-note-get-command

class NoteGetCommand : NoteToolBase(
    name = "get",
    help = "Fetch a note by org ID: metadata, child ids+titles, links, refs, and leaf body as plaintext"
) {
    private val id: String by argument(help = "Org-mode node ID")
    private val maxBodyBytes: Long by option("--max-body-bytes", help = "Body size cap in bytes")
        .long().default(DEFAULT_MAX_BODY_BYTES)

    override fun run() = runBlocking {
        if (ensureFresh) runFreshIndexPass(expandTilde(dbPath), expandTilde(orgDir))
        val database = computer.whatthefuck.arcology.database.DatabaseFactory.createDatabase(expandTilde(dbPath))
        val repo = ToolQueryRepositoryImpl(database)

        val record = repo.selectNodeById(id)
            ?: return@runBlocking fail("not_found", "no such note")
        val ancestorTags = repo.selectAncestorTags(id)
        if (ancestorTags.any { it in EXCLUDE_TAG_SET }) {
            fail("not_found", "no such note")
        }

        val body = loadLeafBody(database, id, expandTilde(orgDir), maxBodyBytes)

        val gate = makeGate(repo)
        val gateResult = if (body != null) gate.gate(body, riskThreshold, verbose) else null
        val gated = gateResult?.gated == true

        // Gated metadata policy: a redacted note returns only what the
        // harness itself supplied — the ID (echo of the request) and the
        // risk block. Links/tags/aliases/properties/children all leak
        // signal about otherwise-withheld content, so none of them flow.
        val data = if (gated) {
            buildJsonObject {
                put("id", JsonPrimitive(record.id))
                put("body", buildJsonObject { put("redacted", JsonPrimitive(true)) })
            }
        } else {
            val linksFrom = repo.selectLinksFrom(id)
            val linksTo = repo.selectLinksTo(id)
            val rawLinks = repo.selectRawLinks(id)
            val refs = repo.selectRefsByNode(id)
            val aliases = repo.selectAliasesByNode(id)
            val tags = repo.selectTagsByNode(id)
            val children = repo.selectChildNodes(id)
            buildJsonObject {
                put("id", JsonPrimitive(record.id))
                record.title?.let { put("title", JsonPrimitive(it)) }
                record.todo?.let { put("todo", JsonPrimitive(it)) }
                record.priority?.let { put("priority", JsonPrimitive(it)) }
                record.scheduled?.let { put("scheduled", JsonPrimitive(it)) }
                record.deadline?.let { put("deadline", JsonPrimitive(it)) }
                put("tags", JsonArray(tags.map { JsonPrimitive(it) }))
                put("aliases", JsonArray(aliases.map { JsonPrimitive(it) }))
                put("properties", parsePropertiesString(record.properties))
                put("children", JsonArray(children.map { c ->
                    buildJsonObject {
                        put("id", JsonPrimitive(c.id))
                        c.title?.let { put("title", JsonPrimitive(it)) }
                        c.todo?.let { put("todo", JsonPrimitive(it)) }
                    }
                }))
                put("links", buildJsonObject {
                    put("outgoing", JsonArray(linksFrom.map { l ->
                        buildJsonObject {
                            put("id", JsonPrimitive(l.targetId))
                            l.targetTitle?.let { put("title", JsonPrimitive(it)) }
                        }
                    }))
                    put("incoming", JsonArray(linksTo.map { l ->
                        buildJsonObject {
                            put("id", JsonPrimitive(l.targetId))
                            l.targetTitle?.let { put("title", JsonPrimitive(it)) }
                        }
                    }))
                    put("external", JsonArray(rawLinks.map { rl ->
                        buildJsonObject {
                            rl.type?.let { put("type", JsonPrimitive(it)) }
                            rl.properties?.takeIf { it.isNotBlank() }?.let { put("target", JsonPrimitive(it)) }
                        }
                    }))
                })
                put("refs", JsonArray(refs.map { r ->
                    buildJsonObject {
                        put("ref", JsonPrimitive(r.ref))
                        put("type", JsonPrimitive(r.type))
                    }
                }))
                put(
                    "body",
                    when {
                        body == null -> buildJsonObject {
                            put("redacted", JsonPrimitive(true))
                            put("missing", JsonPrimitive(true))
                        }
                        else -> JsonPrimitive(body)
                    }
                )
            }
        }

        printEnvelope(ToolEnvelope(ok = true, data = data, risk = gateResult?.block))
    }
}

/** Parse the serialized `properties` column ("k: v\nk2: v2…") into a JSON object. */
internal fun parsePropertiesString(raw: String?): kotlinx.serialization.json.JsonObject {
    if (raw.isNullOrBlank()) return kotlinx.serialization.json.buildJsonObject { }
    val obj = kotlinx.serialization.json.buildJsonObject {
        raw.lineSequence()
            .map { it.trim() }
            .filter { it.contains(": ") }
            .forEach { line ->
                val idx = line.indexOf(": ")
                put(line.substring(0, idx), JsonPrimitive(line.substring(idx + 2)))
            }
    }
    return obj
}

`arcology2 notes search`

This subcommand uses the existing SearchService (BM25 over FTS). It outputs IDs/titles/outline only, content is revealed via notes get where classification gates access. Excluded-tagged nodes are filtered even as titles.

kotlin#+name: tools-note-search

class NoteSearchCommand : NoteToolBase(
    name = "search",
    help = "Search notes by title/content; returns ids, titles and outline paths only"
) {
    private val query: String by option("--query", "-q", help = "Search query").required()
    private val mode: String by option("--mode", help = "title | content | combined")
        .default("combined")
    private val limit: Int by option("--limit", help = "Max results").int().default(20)

    override fun run() = runBlocking {
        if (ensureFresh) runFreshIndexPass(expandTilde(dbPath), expandTilde(orgDir))
        val database = DatabaseFactory.createDatabase(expandTilde(dbPath))
        val service = SearchService(RoamRepositoryImpl(database))
        val results = when (mode) {
            "title" -> service.searchPrimary(query, limit)
            "content" -> service.searchContent(query, limit = limit)
            else -> service.searchCombined(query, primaryLimit = limit, totalLimit = limit)
        }

        val repo = ToolQueryRepositoryImpl(database)
        val filtered = results.filter { r ->
            repo.selectAncestorTags(r.node.id).none { it in EXCLUDE_TAG_SET }
        }

        val data = buildJsonObject {
            put("results", JsonArray(filtered.map { r ->
                buildJsonObject {
                    put("id", JsonPrimitive(r.node.id))
                    r.node.title?.let { put("title", JsonPrimitive(it)) }
                    put("outline", JsonArray(r.node.outlinePath.map { JsonPrimitive(it) }))
                    put("score", JsonPrimitive(r.rank))
                }
            }))
        }
        printEnvelope(ToolEnvelope(ok = true, data = data))
    }
}

`arcology2 notes timeline`

An agent needs a way to see recent entries, to understand the current focus and flow. Timeline v2 reads tool_timestamps — every timestamp entity at index time: planning =SCHEDULED=/=DEADLINE=/=CLOSED=, LOGBOOK state changes, and inline active and inactive stamps on headings with or without :ID: — plus the classic journal-node sweep over daily files. Per rrix:

ID-less rows are first-class: id is null, context comes from olp + snippet. There is no notes get on such rows by construction — no new read surface opens.
Per-row gating: each row's snippet (+title) is classified individually; only tripped rows collapse to {"kind":…,"date":…,"redacted":true} — snippet, id, olp, title withheld — while clean rows stay fully visible. The verdict cache keeps repeat windows cheap. Trades whole-output redaction for per-row context; the count of visible rows still flows (only a fully-tripped window redacts nothing back — there IS no all-redacted shape here).
--kind is a CSV over scheduled,deadline,closed,active,inactive,logbook,journal; *default = all of them, inactive included. journal rows (ID'd journal headings from daily files) merge into the same list by date. - Old =scheduled=/=journal= two-array shape is replaced*; the one consumer (the VM gateway's journal-sweep cron) migrates at landing.

kotlin#+name: tools-note-timeline

internal val DATE_RE = Regex("""\d{4}-\d{2}-\d{2}""")

private val TIMELINE_KINDS = setOf(
    "scheduled", "deadline", "closed", "active", "inactive", "logbook", "journal"
)

class NoteTimelineCommand : NoteToolBase(
    name = "timeline",
    help = "Timestamp entities in a date range (planning, logbook, inline stamps, journal entries)"
) {
    private val from: String by option("--from", help = "Start date YYYY-MM-DD (inclusive)").required()
    private val to: String by option("--to", help = "End date YYYY-MM-DD (inclusive)").required()
    private val kind: String by option(
        "--kind",
        help = "CSV of scheduled,deadline,closed,active,inactive,logbook,journal (default: all)"
    ).default(TIMELINE_KINDS.joinToString(","))

    override fun run() = runBlocking {
        if (!DATE_RE.matches(from) || !DATE_RE.matches(to)) {
            fail("bad_date", "--from/--to must be YYYY-MM-DD")
        }
        val kinds = kind.split(",").map { it.trim().lowercase() }.filter { it.isNotEmpty() }
        val unknown = kinds.filter { it !in TIMELINE_KINDS }
        if (unknown.isNotEmpty()) {
            fail("bad_kind", "unknown kinds '$unknown'; valid: $TIMELINE_KINDS")
        }
        if (ensureFresh) runFreshIndexPass(expandTilde(dbPath), expandTilde(orgDir))

        val repo = openRepo()

        // Stamp rows: tool_timestamps over the window (journal entries
        // themselves are ID'd headings in the daily files, joined by the
        // classic sweep when requested).
        val stamps = if (kinds.any { it != "journal" }) {
            repo.selectTimestampsBetween(from, to).filter { it.kind in kinds }
        } else emptyList()
        val journal = if ("journal" in kinds) repo.selectJournalNodesBetween(
            "journals/$from.org", "journals/$to.org"
        ) else emptyList()

        val gate = makeGate(repo)

        data class Row(val date: String, val epoch: Long?, val json: JsonObject)

        fun redact(row: JsonObject): JsonObject = buildJsonObject {
            row["kind"]?.let { put("kind", it) }
            row["date"]?.let { put("date", it) }
            put("redacted", JsonPrimitive(true))
        }

        // Per-row gating: each row's snippet/title/olp classified alone;
        // tripped rows keep only kind/date and a redacted flag.
        suspend fun stampRow(s: TimelineStampRecord): Row {
            val json = buildJsonObject {
                s.nodeId?.let { put("id", JsonPrimitive(it)) }
                s.nodeTitle?.let { put("title", JsonPrimitive(it)) }
                s.nodeTodo?.let { put("todo", JsonPrimitive(it)) }
                put("kind", JsonPrimitive(s.kind))
                put("date", JsonPrimitive(s.date))
                s.epoch?.let { put("epoch", JsonPrimitive(it)) }
                s.repeater?.let { put("repeater", JsonPrimitive(it)) }
                s.olp?.takeIf { it.isNotBlank() }?.let { put("olp", JsonPrimitive(it)) }
                s.snippet?.let { put("snippet", JsonPrimitive(it)) }
            }
            val gateable = listOfNotNull(s.nodeTitle, s.nodeTodo, s.snippet, s.olp).joinToString("\n")
            return if (gateable.isBlank()) {
                Row(s.date, s.epoch, json)
            } else {
                val result = gate.gate(gateable, riskThreshold, verbose)
                if (result.gated) Row(s.date, s.epoch, redact(json)) else Row(s.date, s.epoch, json)
            }
        }

        suspend fun journalRow(j: TimelineRecord): Row {
            val day = j.id.take(10) // datetime ID prefix → day
            val json = buildJsonObject {
                put("id", JsonPrimitive(j.id))
                j.title?.let { put("title", JsonPrimitive(it)) }
                j.todo?.let { put("todo", JsonPrimitive(it)) }
                put("kind", JsonPrimitive("journal"))
                put("date", JsonPrimitive(day))
            }
            val gateable = j.title ?: return Row(day, null, json)
            val result = gate.gate(gateable, riskThreshold, verbose)
            return if (result.gated) Row(day, null, redact(json)) else Row(day, null, json)
        }

        val all = (stamps.map { stampRow(it) } + journal.map { journalRow(it) }).sortedWith(
            compareBy({ it.date }, { it.epoch ?: Long.MAX_VALUE })
        )

        val data = buildJsonObject {
            put("entries", JsonArray(all.map { it.json }))
            put("entry_count", JsonPrimitive(all.size))
        }
        printEnvelope(ToolEnvelope(ok = true, data = data))
    }
}

NEXT this should pull [in]active timestamps and whatnot directly from the Tasks table in the Agenda sub-system.

`arcology2 notes todo`

Toggle a node's TODO state by positional ID, writing through to the org file via the OrgDocumentEditor. This is the same text-surgery path the Android editor uses, including :LOGBOOK: state-change entries and repeater advance-on-DONE (persistAndReindex refreshes the DB).

Keyword whitelist comes from the AppPreferences surface: --todo-states CSV or $ARCOLOGY_TODO_STATES, defaulting to NEXT,INPROGRESS,DONE (AppPreferences' DEFAULT_TODO_STATES). --clear removes the keyword.
Excluded-tag ancestors ⇒ not_found, same as reads.
Writes don't exfiltrate: no classifier call on the write path. The envelope echoes =from=/=to=/=rescheduled= but never the file path.

kotlin#+name: tools-note-todo

class NoteTodoCommand : NoteToolBase(
    name = "todo",
    help = "Toggle a note's TODO state by ID; writes LOGBOOK and honors repeaters"
) {
    private val id: String by argument(help = "Org-mode node ID")
    private val set: String? by option("--set", help = "TODO keyword to set (validated against --todo-states)")
    private val clear: Boolean by option("--clear", help = "Remove the TODO keyword").flag(default = false)
    private val todoStates: String by option(
        "--todo-states",
        help = "CSV of allowed keywords (default: \$ARCOLOGY_TODO_STATES or NEXT,INPROGRESS,DONE)"
    ).default("")

    override fun run() = runBlocking {
        if (set != null && clear) {
            fail("bad_args", "--set and --clear are mutually exclusive")
        }
        if (set == null && !clear) {
            fail("bad_args", "nothing to do: pass --set <STATE> or --clear")
        }
        val statesCsv = todoStates.ifBlank {
            System.getenv("ARCOLOGY_TODO_STATES") ?: "NEXT,INPROGRESS,DONE"
        }
        val states = statesCsv.split(",").map { it.trim() }.filter { it.isNotEmpty() }
        if (set != null && set !in states) {
            fail("bad_todo", "'$set' not in todo states [$statesCsv]; add it to --todo-states or ARCOLOGY_TODO_STATES")
        }

        val database = DatabaseFactory.createDatabase(expandTilde(dbPath))
        val repo = ToolQueryRepositoryImpl(database)
        repo.selectNodeById(id) ?: return@runBlocking fail("not_found", "no such note")
        val ancestorTags = repo.selectAncestorTags(id)
        if (ancestorTags.any { it in EXCLUDE_TAG_SET }) {
            fail("not_found", "no such note")
        }

        val fileSystem = JvmFileSystem(java.nio.file.Paths.get(expandTilde(orgDir)))
        val roamRepo = RoamRepositoryImpl(database)
        val indexService = createIndexingService(
            databasePath = expandTilde(dbPath), config = IndexingConfig(), basePath = expandTilde(orgDir)
        )
        val editor = computer.whatthefuck.arcology.editor.OrgDocumentEditor(
            fileSystem = fileSystem,
            repository = roamRepo,
            indexingService = indexService
        )
        val from = repo.selectNodeById(id)?.todo
        val result = editor.updateTodoState(id, if (clear) null else set)
        when (result) {
            is computer.whatthefuck.arcology.editor.EditResult.Success -> printEnvelope(
                ToolEnvelope(
                    ok = true,
                    data = buildJsonObject {
                        put("id", JsonPrimitive(id))
                        put("from", JsonPrimitive(from))
                        put("to", JsonPrimitive(if (clear) null else set))
                        // Repeater advance-on-DONE rewrites the planning
                        // line; the editor doesn't report it, so surface
                        // success only.
                    },
                    risk = null
                )
            )
            is computer.whatthefuck.arcology.editor.EditResult.Error ->
                fail("todo_failed", result.message)
        }
    }
}

`arcology2 notes capture`

Direct write via the same CaptureService path the Android app uses: build the heading, append to the daily file, re-index it so the new node is immediately queryable. Captured entries are plain headings unless --gen-id opts into generating the datetime ID. Passing --heading <id> files the entry as the target node's last child instead of the journal, via OrgDocumentEditor.appendHeadingUnder.

The repeatable --ref <URL> option attaches ROAM_REFS to the new node: every occurrence appends one quoted token to the :ROAM_REFS: property, in the space-separated quote-aware multi-value syntax the Android capture core emits and the parser reads back. Because the parser lifts heading properties (refs included) only from ID-bearing headings, --ref implies the datetime ID — an ID-less entry would write the drawer to the file and then drop its refs at index time. The refs then flow through the standard indexing pipeline into the refs table keyed by the envelope's node_id: notes get returns them in the refs array, and published pages' external-reference sections (the web-ref backlinks of the source URL) read the same rows, so no hand property editing is needed. Values are trimmed, blank values are rejected, repeats deduplicate, and the list rides the risk gate alongside --title / --body. Verify after a capture:

SELECT ref, type FROM refs WHERE node_id = '<node_id>';

kotlin#+name: tools-note-capture

class NoteCaptureCommand : NoteToolBase(
    name = "capture",
    help = "Append a capture entry to the daily journal or under a heading (--heading), and re-index"
) {
    private val title: String by option("--title", help = "Entry title").required()
    private val bodyOpt: String by option("--body", help = "Entry body text").default("")
    private val tags: String by option("--tags", help = "Comma-separated tags").default("")
    private val todo: String? by option("--todo", help = "TODO keyword, e.g. TODO")
    private val date: String by option("--date", help = "'today' or YYYY-MM-DD (journal targets only)").default("today")
    private val heading: String? by option("--heading", help = "Target heading node ID: file the entry as its last child instead of the journal")
    private val genId: Boolean by option("--gen-id", help = "Generate and attach a datetime :ID: to the new entry (default: no ID)").flag(default = false)
    private val refs: List<String> by option(
        "--ref", metavar = "URL",
        help = "ROAM_REFS entry for the new node (repeatable). Implies --gen-id"
    ).multiple()

    override fun run() = runBlocking {
        val targetDate = if (heading == null) {
            if (date != "today" && !DATE_RE.matches(date)) {
                fail("bad_date", "--date must be 'today' or YYYY-MM-DD")
            }
            if (date == "today") {
                val now = java.time.LocalDate.now()
                "%04d-%02d-%02d".format(now.year, now.monthValue, now.dayOfMonth)
            } else {
                date
            }
        } else null

        val repo = openRepo()
        val fileSystem = JvmFileSystem(java.nio.file.Paths.get(expandTilde(orgDir)))
        val now = (kotlin.time.Clock.System.now().toLocalDateTime(kotlinx.datetime.TimeZone.currentSystemDefault()))

        val cleanedRefs = refs.map { it.trim() }.filter { it.isNotEmpty() }.distinct()
        if (refs.isNotEmpty() && cleanedRefs.isEmpty()) {
            fail("bad_ref", "--ref values must not be blank")
        }

        val captureId: String? = if (genId || cleanedRefs.isNotEmpty()) {
            // --ref implies an ID: the parser lifts heading properties
            // (ROAM_REFS included) only for ID-bearing nodes — an ID-less
            // entry would drop its refs on the floor at index time.
            CaptureService.generateId(
                LocalDateTime(
                    now.date.year, now.date.monthNumber, now.date.dayOfMonth,
                    now.time.hour, now.time.minute, now.time.second, 0
                )
            )
        } else null

        val entry = CaptureService.buildCaptureEntry(
            body = bodyOpt,
            title = title,
            tags = tags.split(",").map { it.trim() }.filter { it.isNotEmpty() },
            todoState = todo,
            refs = cleanedRefs,
            id = captureId,
            time = LocalTime(now.hour, now.minute)
        )

        // Classify before writing so the score lands in the envelope.
        val gate = makeGate(repo)
        val gateResult = gate.gate(
            (listOf(title, bodyOpt) + cleanedRefs).joinToString("\n"), riskThreshold, verbose
        )

        val headingTarget: String? = heading // capture: delegated props don't smart-cast

        val config = IndexingConfig(
            batchSize = 1, memoryMonitoring = false, enableFtsDefer = false,
            exportDatabaseAfterIndexing = false
        )
        val indexer = createIndexingService(
            databasePath = expandTilde(dbPath), config = config, basePath = expandTilde(orgDir)
        )

        if (headingTarget != null) {
            val targetId: String = headingTarget
            repo.selectNodeById(targetId)
                ?: return@runBlocking fail("not_found", "no such note")
            val ancestorTags = repo.selectAncestorTags(targetId)
            if (ancestorTags.any { it in EXCLUDE_TAG_SET }) {
                fail("not_found", "no such note")
            }

            val editor = computer.whatthefuck.arcology.editor.OrgDocumentEditor(
                fileSystem = fileSystem,
                repository = computer.whatthefuck.arcology.database.RoamRepositoryImpl(
                    DatabaseFactory.createDatabase(expandTilde(dbPath))
                ),
                indexingService = indexer
            )
            when (val result = editor.appendHeadingUnder(targetId, entry)) {
                is computer.whatthefuck.arcology.editor.EditResult.Success -> printEnvelope(
                    ToolEnvelope(
                        ok = true,
                        data = buildJsonObject {
                            put("target_id", JsonPrimitive(targetId))
                            put("filed", JsonPrimitive("under"))
                            captureId?.let { put("node_id", JsonPrimitive(it)) }
                        },
                        risk = gateResult.block
                    )
                )
                is computer.whatthefuck.arcology.editor.EditResult.Error ->
                    fail("capture_failed", result.message)
            }
        } else {
            val relativePath = "journals/$targetDate.org"
            // First capture of the day: the daily file may not exist yet.
            // Create it with the built-in level-0 header so CLI-only days
            // get a proper file-level node (the JVM CLI cannot read Android
            // preferences; custom daily-file-header content stays
            // Android-side only — the identity drawer and header structure
            // stay standardized from both capture entry points).
            ensureDailyFileHeader(fileSystem, relativePath, now)
            fileSystem.appendToFile(relativePath, "\n" + entry)

            when (val result = indexer.indexFile(relativePath)) {
                is FileIndexResult.Success -> printEnvelope(
                    ToolEnvelope(
                        ok = true,
                        data = buildJsonObject {
                            captureId?.let { put("node_id", JsonPrimitive(it)) }
                            put("file", JsonPrimitive(relativePath))
                            put("nodes_indexed", JsonPrimitive(result.nodesCount))
                        },
                        risk = gateResult.block
                    )
                )
                is FileIndexResult.Error -> fail("index_failed", result.message)
                is FileIndexResult.Skipped -> fail("index_skipped", result.reason)
            }
        }
    }
}

Daily file header creation (the level-0 node)

When notes capture targets a journal file that does not exist yet, the first write must create the file-level (level-0) node: properties drawer with a generated :ID: and the file title. The built-in DEFAULT_DAILY_FILE_PATTERN is used unconditionally — the JVM CLI cannot read Android preferences, so custom daily-file-header content is an Android-side-only feature; the identity drawer and header structure stay standardized from both capture entry points (the Android capture core applies the same guarantee via its :ID:-guard). Existing files are never touched, so Emacs-written days are left alone.

kotlin#+name: tools-capture-daily-header

/**
 * Ensure a daily journal file exists. When the file is absent, write the
 * built-in daily-file header (CaptureService.DEFAULT_DAILY_FILE_PATTERN,
 * ID-guarded) so CLI-only days get a proper level-0 node; the caller then
 * appends the capture entry. Existing files are never touched.
 */
suspend fun ensureDailyFileHeader(
    fileSystem: FileSystemInterface,
    relativePath: String,
    dateTime: LocalDateTime
) {
    if (fileSystem.fileExists(relativePath)) return
    val micros = (Clock.System.now().nanosecondsOfSecond / 1000)
    val header = CaptureService.buildDailyFileContent(
        dateTime, CaptureService.generateId(dateTime, micros)
    )
    fileSystem.appendToFile(relativePath, header)
}

`arcology2 notes sql`

This provides a read-only query system for the SQLite DB. The results are gated by the classifier because it's possible to query the full-text database using this tool.

kotlin#+name: tools-note-sql

class NoteSqlCommand : NoteToolBase(
    name = "sql",
    help = "Run a read-only SELECT against the arcology database"
) {
    private val query: String by option("--query", "-q", help = "A single SELECT statement").required()
    private val maxRows: Int by option("--max-rows", help = "Row cap").int().default(200)

    override fun run() = runBlocking {
        val trimmed = query.trim()
        val statement = trimmed.removeSuffix(";").trim()
        val firstWord = statement.split(Regex("\\s+"), limit = 2).firstOrNull()?.uppercase()
        if (statement.isEmpty() || firstWord != "SELECT" || statement.contains(';')) {
            fail("rejected", "only a single-statement SELECT is allowed")
        }

        val repo = openRepo()
        val rows = try {
            executeReadOnlySelect(statement, maxRows, expandTilde(dbPath))
        } catch (e: Exception) {
            fail("sql_error", e.message ?: "query failed")
        }

        val gate = makeGate(repo)
        val gateResult = gate.gate(
            rows.joinToString("\n") { row -> row.entries.joinToString(" | ") { "${it.key}: ${it.value ?: ""}" } },
            riskThreshold,
            verbose
        )

        val data = buildJsonObject {
            if (gateResult.gated) {
                // Gated: only the risk block carries information. Row count
                // itself leaks (a count of sensitive rows is sensitive).
                put(
                    "rows",
                    buildJsonObject { put("redacted", JsonPrimitive(true)) }
                )
            } else {
                put(
                    "rows",
                    JsonArray(rows.map { row ->
                                  buildJsonObject { row.forEach { (k, v) -> put(k, JsonPrimitive(v)) } } })
                )
                put("row_count", JsonPrimitive(rows.size))
            }
        }
        printEnvelope(ToolEnvelope(ok = true, data = data, risk = gateResult.block))
    }
}

The SQL Runtime

kotlin#+name: tools-sql-runtime

/**
 * Indexer freshness, shared by the `reindex` verb and the read tools'
 * =--ensure-fresh=. A thin adapter over the same
 * =createIndexingService(...).indexDirectory()= pipeline =arcology index=
 * drives — identical plugins and hash-skip — differing only in defaults
 * (notes-style --db/--org-dir) and output: a parseable {ok,data} envelope
 * instead of ad-hoc terminal rendering. Delta vs running =arcology index=
 * directly: no db-into-indexed-dir default, no exportDatabaseAfterIndexing
 * copy, no interactive progress bar — cron/skill consumable output.
 */
suspend fun runFreshIndexPass(dbPath: String, orgDir: String): IndexResult {
    val config = IndexingConfig(
        batchSize = 50, memoryMonitoring = false, enableFtsDefer = false,
        exportDatabaseAfterIndexing = false
    )
    val indexer = createIndexingService(
        databasePath = dbPath, config = config, basePath = orgDir
    )
    return indexer.indexDirectory(orgDir)
}

/**
 * Open the database read-only and run [sql], returning up to [maxRows] rows
 * with cell values truncated to [maxCellChars].
 *
 * Read-only enforcement is two-layered: PRAGMA query_only=ON makes the
 * connection itself reject any write (INSERT/UPDATE/DDL/PRAGMA writes), and
 * the CLI's statement-shape guard runs before this. The xerial driver is
 * already on the runtime classpath via sqldelight's sqlite-driver, so the
 * org.sqlite.SQLiteConfig convenience is unnecessary — connection properties
 * suffice.
 */
fun executeReadOnlySelect(
    sql: String,
    maxRows: Int,
    dbPath: String,
    maxCellChars: Int = 2000
): List<Map<String, String?>> {
    val path = dbPath.replace("~", System.getProperty("user.home"))
    val props = Properties().apply {
        put("open_mode", "1")  // SQLITE_OPEN_READONLY
        put("busy_timeout", "5000")
        put("query_only", "true")
    }
    DriverManager.getConnection("jdbc:sqlite:$path", props).use { connection ->
        connection.createStatement().use { statement ->
            statement.queryTimeout = 10
            statement.executeQuery(sql).use { resultSet ->
                val meta = resultSet.metaData
                val columns = (1..meta.columnCount).map { i -> i to meta.getColumnName(i) }
                val rows = mutableListOf<Map<String, String?>>()
                while (resultSet.next() && rows.size < maxRows) {
                    rows.add(columns.associate { (i, name) ->
                        name to resultSet.getString(i)?.take(maxCellChars)
                    })
                }
                return rows
            }
        }
    }
}

`arcology2 notes reindex`

Indexer freshness for agent consumers: the skill/cron runs this before working, or relies on the sync watcher. It is a thin adapter — one shared runFreshIndexPass, notes-consistent defaults and envelope output, no second engine.

kotlin#+name: tools-note-reindex

class NoteReindexCommand : NoteToolBase(
    name = "reindex",
    help = "Run one incremental indexing pass (hash-skip: cheap) so notes reads are fresh"
) {
    override fun run() = runBlocking {
        val result = try {
            runFreshIndexPass(expandTilde(dbPath), expandTilde(orgDir))
        } catch (e: Exception) {
            fail("index_failed", e.message ?: "indexing failed")
        }
        printEnvelope(
            ToolEnvelope(
                ok = result.failed == 0,
                data = buildJsonObject {
                    put("indexed", JsonPrimitive(result.successful))
                    put("skipped", JsonPrimitive(result.skipped))
                    put("failed", JsonPrimitive(result.failed))
                    put("removed", JsonPrimitive(result.removed))
                },
                risk = null
            )
        )
    }
}

Tool Plumbing

Tools' SQLDelight Queries

Tools.sq is a new file in the shared ArcologyDatabase, it has the queries the tools below use, and provides a cache for the risk classifier. SQLDelight names its query holder toolsQueries from the filename.

sql#+name: tools-schema:tangle ../src/commonMain/sqldelight/computer/whatthefuck/arcology/db/Tools.sq

-- Verdict cache for the risk classifier (llm/classifier.org), keyed by
-- content hash + model — re-classification happens when content or model
-- changes, not on a wall clock.
CREATE TABLE IF NOT EXISTS llm_verdict_cache (
  content_hash TEXT NOT NULL,
  model TEXT NOT NULL,
  health REAL NOT NULL,
  private_score REAL NOT NULL,
  financial REAL NOT NULL,
  employer REAL NOT NULL,
  political REAL NOT NULL,
  created_at INTEGER NOT NULL,
  PRIMARY KEY (content_hash, model)
);

insertVerdict:
INSERT OR REPLACE INTO llm_verdict_cache
  (content_hash, model, health, private_score, financial, employer, political, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?);

selectVerdict:
SELECT health, private_score, financial, employer, political, created_at
FROM llm_verdict_cache WHERE content_hash = ? AND model = ?;

-- Timestamp entities harvested at index time by TimestampsIndexerPlugin:
-- planning SCHEDULED/DEADLINE/CLOSED, LOGBOOK drawer entries, and inline
-- DTStamp/DTRange tokens in heading titles and body chunks — active AND
-- inactive, for headings with or without an :ID: (timeline requirement in
-- rrix's note 20261001T212917.593002). Not FK-locked to task_headings —
-- that table (agenda/models.org) only carries task-ish headings and its
-- extractor drops inactive stamps by design.
-- pos: heading char offset (heading.tokens.first().range.first), 0 for
-- file-level stamps. offset: the stamp/logbook line's char offset —
-- disambiguates same (heading, kind, day) rows and aids debugging.
-- kind: scheduled | deadline | closed | active | inactive | logbook.
-- Rows from EXCLUDE_TAG subtrees (noexport/NOEXPORT/ARCHIVE) are never
-- inserted at all, so the tool query needs no read-time tag check.
CREATE TABLE IF NOT EXISTS tool_timestamps (
  file TEXT NOT NULL,
  pos INTEGER NOT NULL,
  kind TEXT NOT NULL,
  date TEXT NOT NULL,
  epoch INTEGER,
  repeater TEXT,
  node_id TEXT,
  olp TEXT,
  snippet TEXT,
  offset INTEGER NOT NULL,
  PRIMARY KEY (file, pos, kind, offset)
);

CREATE INDEX IF NOT EXISTS idx_tool_timestamps_date ON tool_timestamps (date);
CREATE INDEX IF NOT EXISTS idx_tool_timestamps_node ON tool_timestamps (node_id);

insertToolTimestamp:
INSERT OR REPLACE INTO tool_timestamps
  (file, pos, kind, date, epoch, repeater, node_id, olp, snippet, offset)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?);

deleteToolTimestampsByFile:
DELETE FROM tool_timestamps WHERE file = ?;

Tool-facing node projection. Omits `file` and `pos`: the harness never learns file paths from these tools.