akm-cli 0.8.0-rc2 → 0.8.0

package/dist/core/state-db.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * state.db — Durable SQLite database for non-regenerable akm state.
  *
@@ -315,6 +318,138 @@ const MIGRATIONS = [
         ON task_history(status);
     `,
     },
+    // ── Migration 003 — improve_runs ────────────────────────────────────────────
+    //
+    // Records every `akm improve` invocation as a durable row, replacing the
+    // legacy `<stash>/.akm/runs/<runId>/improve-result.json` artifact files.
+    //
+    // The `dry_run` column is FIRST-CLASS and indexed so productivity audits can
+    // cleanly filter dry-run probes out of real-run analyses without parsing
+    // `result_json`. The dry-run/real-run artifact-trap (recorded in
+    // feedback_akm_dryrun_artifact_trap) was the specific motivating bug.
+    //
+    // Indexed (query) columns:
+    //   id            TEXT PK   — runId (`buildImproveRunId()` output).
+    //   started_at    TEXT      — ISO-8601; indexed for time-range queries.
+    //   stash_dir     TEXT      — absolute stash root; multi-stash scoping.
+    //   dry_run       INTEGER   — 0/1; indexed for productivity audits.
+    //   scope_mode    TEXT      — "all" | "type" | "ref"; indexed via composite
+    //                              with stash_dir for stash-scoped scope queries.
+    //
+    // Non-indexed payload:
+    //   completed_at  TEXT      — ISO-8601 or NULL if interrupted.
+    //   profile       TEXT      — improve profile name (nullable).
+    //   scope_value   TEXT      — type name or asset ref (nullable).
+    //   guidance      TEXT      — user-provided guidance text, if any.
+    //   ok            INTEGER   — 0/1; whether the run produced ok=true.
+    //   result_json   TEXT      — full AkmImproveResult JSON.
+    //   metrics_json  TEXT      — aggregate counts extracted from result, cheap
+    //                              to query without parsing result_json.
+    //
+    // Extensible (metadata_json) columns:
+    //   metadata_json TEXT      — JSON object for future improve-run fields.
+    //
+    // ADD COLUMN extension points (future migrations):
+    //   ALTER TABLE improve_runs ADD COLUMN duration_ms INTEGER DEFAULT NULL;
+    //   ALTER TABLE improve_runs ADD COLUMN host TEXT DEFAULT NULL;
+    //
+    // TTL: rows where started_at < NOW() - 90 days can be deleted by
+    // `purgeOldImproveRuns()`. No automatic deletion occurs here.
+    {
+        id: "003-improve-runs",
+        up: `
+      CREATE TABLE IF NOT EXISTS improve_runs (
+        id            TEXT    PRIMARY KEY,
+        started_at    TEXT    NOT NULL,
+        completed_at  TEXT,
+        stash_dir     TEXT    NOT NULL,
+        dry_run       INTEGER NOT NULL DEFAULT 0,
+        profile       TEXT,
+        scope_mode    TEXT    NOT NULL,
+        scope_value   TEXT,
+        guidance      TEXT,
+        ok            INTEGER NOT NULL,
+        result_json   TEXT    NOT NULL,
+        metrics_json  TEXT,
+        metadata_json TEXT    NOT NULL DEFAULT '{}'
+      );
+
+      -- Query patterns supported:
+      --   SELECT … WHERE started_at >= ? AND started_at <= ?
+      --     → idx_improve_runs_started
+      --   SELECT … WHERE dry_run = 0
+      --     → idx_improve_runs_dry_run (productivity audits filter trap)
+      --   SELECT … WHERE stash_dir = ? AND scope_mode = ?
+      --     → idx_improve_runs_stash_scope
+      CREATE INDEX IF NOT EXISTS idx_improve_runs_started
+        ON improve_runs(started_at);
+      CREATE INDEX IF NOT EXISTS idx_improve_runs_dry_run
+        ON improve_runs(dry_run);
+      CREATE INDEX IF NOT EXISTS idx_improve_runs_stash_scope
+        ON improve_runs(stash_dir, scope_mode);
+    `,
+    },
+    // ── Migration 004 — extract_sessions_seen ───────────────────────────────────
+    //
+    // Tracks which platform sessions the extractor has processed, so the discovery
+    // pass in `akm extract --since <window>` skips sessions whose content hasn't
+    // changed since the last successful run. Replaces the akm-plugin
+    // session-checkpoint hook's implicit "write-once" memory of what's been
+    // captured — but persistent and queryable.
+    //
+    // Indexed (query) columns:
+    //   harness          TEXT     — harness name (claude-code, opencode, ...).
+    //   session_id       TEXT     — platform-native session identifier.
+    //   processed_at     TEXT     — ISO-8601 UTC; when extract last ran on this session.
+    //   session_ended_at TEXT     — session.endedAt at processing time. When a
+    //                                later listSessions reports a *newer* endedAt
+    //                                for the same session_id, the extractor
+    //                                re-processes the appended events.
+    //   outcome          TEXT     — "candidates_queued" | "no_candidates" |
+    //                                "skipped" | "failed".
+    //
+    // Non-indexed columns:
+    //   candidate_count  INTEGER  — number of candidates the LLM produced.
+    //   proposal_count   INTEGER  — number of proposals actually queued
+    //                                (candidates may fail downstream validation).
+    //   rationale        TEXT     — for "no_candidates", the LLM's explanation.
+    //   source_run       TEXT     — sourceRun id for PROV-DM traceability.
+    //   metadata_json    TEXT     — future-proofing (pre-filter stats, LLM
+    //                                model+version, prompt token count, etc.).
+    //
+    // PK: (harness, session_id) — one row per session per harness. A re-extract
+    // updates the row in place via INSERT OR REPLACE.
+    //
+    // TTL: no automatic deletion. Sessions stay tracked as long as the source
+    // session files exist on disk. Operator can `DELETE FROM extract_sessions_seen
+    // WHERE processed_at < ?` for cleanup if desired.
+    {
+        id: "004-extract-sessions-seen",
+        up: `
+      CREATE TABLE IF NOT EXISTS extract_sessions_seen (
+        harness          TEXT    NOT NULL,
+        session_id       TEXT    NOT NULL,
+        processed_at     TEXT    NOT NULL,
+        session_ended_at TEXT,
+        outcome          TEXT    NOT NULL,
+        candidate_count  INTEGER NOT NULL DEFAULT 0,
+        proposal_count   INTEGER NOT NULL DEFAULT 0,
+        rationale        TEXT,
+        source_run       TEXT,
+        metadata_json    TEXT    NOT NULL DEFAULT '{}',
+        PRIMARY KEY (harness, session_id)
+      );
+
+      -- Query patterns:
+      --   SELECT … WHERE harness = ?                       → idx_extract_sessions_harness
+      --   SELECT … WHERE processed_at >= ?                 → idx_extract_sessions_processed
+      --   SELECT … WHERE harness = ? AND session_id = ?    → PK
+      CREATE INDEX IF NOT EXISTS idx_extract_sessions_harness
+        ON extract_sessions_seen(harness);
+      CREATE INDEX IF NOT EXISTS idx_extract_sessions_processed
+        ON extract_sessions_seen(processed_at);
+    `,
+    },
 ];
 /**
  * Create the migrations table if it does not exist. This must be called
@@ -498,12 +633,21 @@ export function readStateEvents(db, options = {}) {
 /**
  * Delete events older than `retentionDays` (default: 90). Safe to call from
  * a maintenance cron; uses a single DELETE with an index-covered ts predicate.
+ *
+ * Returns the number of rows actually deleted so callers can emit an
+ * `events_purged` observability event. A non-positive or non-finite
+ * `retentionDays` is treated as "disabled" and returns 0 without scanning.
  */
 export function purgeOldEvents(db, retentionDays = 90) {
     if (!Number.isFinite(retentionDays) || retentionDays <= 0)
-        return;
+        return 0;
     const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-    db.prepare("DELETE FROM events WHERE ts < ?").run(cutoff);
+    const result = db.prepare("DELETE FROM events WHERE ts < ?").run(cutoff);
+    // bun:sqlite's run() returns { changes, lastInsertRowid }. `changes` may be
+    // a number or bigint depending on the underlying lib; coerce to number for
+    // the metadata payload.
+    const changes = result.changes ?? 0;
+    return typeof changes === "bigint" ? Number(changes) : changes;
 }
 // ── proposals table helpers ──────────────────────────────────────────────────
 /**
@@ -643,27 +787,52 @@ export function queryTaskHistory(db, options = {}) {
  * monotonic integer ids. Callers that persisted a byte-offset cursor must
  * discard it after migration and use the returned `maxId` as the new cursor.
  *
- * The import is wrapped in a single transaction for atomicity. If the file
- * has already been imported (the events table is non-empty and the file
- * has not changed since last import), callers should skip calling this
- * function — de-duplication is NOT performed here to keep the hot path fast.
+ * **Idempotency**: each line is pre-checked against the `events` table using
+ * `(event_type, ts, ref, metadata_json)` as the duplicate key. Lines whose
+ * exact tuple is already present are skipped and reported as `skipped` in the
+ * return value. This makes the migration safe to re-run (the v0.7→v0.8
+ * migration guide recommends re-running the script as a recovery path; without
+ * this guard, every re-run would double-import the entire event log).
+ *
+ * Duplicate detection is per-import-tuple, not a table-wide UNIQUE constraint:
+ * the events table has no UNIQUE constraint at runtime so that
+ * `appendEvent` can write multiple events with the same ts (sub-millisecond
+ * bursts produce identical `(event_type, ts, ref)` triples in practice). The
+ * SELECT-first check is scoped to the import path only.
+ *
+ * The import is wrapped in a single transaction for atomicity.
  *
  * @param db       - Open state.db connection.
  * @param jsonlPath - Absolute path to the events.jsonl file to import.
- * @returns         Number of rows inserted and the max id assigned.
+ * @returns         Number of rows inserted, the max id assigned, and the
+ *                  count of rows skipped because an identical event already
+ *                  existed in the table.
  */
 export async function importEventsJsonl(db, jsonlPath) {
     const { readFileSync, existsSync } = await import("node:fs");
     if (!existsSync(jsonlPath)) {
-        return { imported: 0, maxId: 0 };
+        return { imported: 0, maxId: 0, skipped: 0 };
     }
     const text = readFileSync(jsonlPath, "utf8");
     const lines = text.split("\n").filter((l) => l.trim().length > 0);
     let imported = 0;
     let maxId = 0;
-    const stmt = db.prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
+    let skipped = 0;
+    const insertStmt = db.prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
      VALUES (?, ?, ?, ?)
      RETURNING id`);
+    // Dedup pre-check: matches by the full tuple including metadata_json so an
+    // import is idempotent over identical rows but does not collide with two
+    // genuinely different events that happen to share (event_type, ts, ref).
+    //
+    // Uses IS for ref so two NULL refs compare equal (a plain `=` would treat
+    // NULL = NULL as NULL and the row would be re-inserted on every run).
+    const existsStmt = db.prepare(`SELECT 1 FROM events
+     WHERE event_type = ?
+       AND ts = ?
+       AND ref IS ?
+       AND metadata_json = ?
+     LIMIT 1`);
     db.transaction(() => {
         for (const line of lines) {
             let parsed;
@@ -677,7 +846,12 @@ export async function importEventsJsonl(db, jsonlPath) {
             const ts = typeof parsed.ts === "string" ? parsed.ts : new Date().toISOString();
             const ref = typeof parsed.ref === "string" ? parsed.ref : null;
             const metadata = parsed.metadata !== undefined && typeof parsed.metadata === "object" ? JSON.stringify(parsed.metadata) : "{}";
-            const result = stmt.get(eventType, ts, ref, metadata);
+            const duplicate = existsStmt.get(eventType, ts, ref, metadata);
+            if (duplicate) {
+                skipped++;
+                continue;
+            }
+            const result = insertStmt.get(eventType, ts, ref, metadata);
             if (result) {
                 imported++;
                 if (result.id > maxId)
@@ -685,7 +859,170 @@ export async function importEventsJsonl(db, jsonlPath) {
             }
         }
     })();
-    return { imported, maxId };
+    return { imported, maxId, skipped };
+}
+/**
+ * Compute the cheap aggregate metrics blob from a full improve result.
+ *
+ * Pure function — no I/O. Used by {@link recordImproveRun} to populate
+ * `metrics_json`. Exposed for tests and for any future call site that wants
+ * the same aggregation logic without hitting state.db.
+ */
+export function computeImproveRunMetrics(result) {
+    const plannedCount = Array.isArray(result.plannedRefs) ? result.plannedRefs.length : 0;
+    const actions = Array.isArray(result.actions) ? result.actions : [];
+    const actionsCount = actions.length;
+    let acceptedCount = 0;
+    let rejectedCount = 0;
+    let autoAcceptedCount = 0;
+    let errorCount = 0;
+    for (const action of actions) {
+        switch (action.mode) {
+            case "reflect":
+            case "distill":
+            case "memory-inference":
+            case "graph-extraction":
+                acceptedCount++;
+                break;
+            case "reflect-cooldown":
+            case "reflect-skipped":
+            case "distill-skipped":
+                rejectedCount++;
+                break;
+            case "reflect-failed":
+            case "error":
+                errorCount++;
+                break;
+            case "memory-prune":
+                // Prune is bookkeeping, not "accepted" content authoring; count
+                // separately as a no-op for the audit aggregate.
+                break;
+        }
+        // Legacy: pre-gate action results may carry autoAccepted: true (reflect path).
+        const r = action.result;
+        if (r && r.autoAccepted === true)
+            autoAcceptedCount++;
+    }
+    // Add gate-promoted count from the unified PostPhaseAutoAcceptGate (all phases).
+    autoAcceptedCount += result.gateAutoAcceptedCount ?? 0;
+    return { plannedCount, actionsCount, acceptedCount, rejectedCount, autoAcceptedCount, errorCount };
+}
+/**
+ * Insert a single improve-run row into `improve_runs`. Uses parameterised SQL.
+ *
+ * Idempotency: the table's PRIMARY KEY is `id`, so re-running with the same
+ * runId would error. Callers mint a fresh runId per invocation via
+ * {@link buildImproveRunId} so this is not a concern in practice — but the
+ * default behaviour is INSERT (not REPLACE) so accidental dupes surface as
+ * a SQLite constraint error rather than silently overwriting a prior record.
+ *
+ * The `metrics` parameter defaults to the output of
+ * {@link computeImproveRunMetrics} when not supplied. Pass an explicit
+ * `metrics` object to override the derivation (e.g. tests).
+ */
+export function recordImproveRun(db, input) {
+    const metricsObj = input.metrics ?? computeImproveRunMetrics(input.result);
+    db.prepare(`
+    INSERT INTO improve_runs
+      (id, started_at, completed_at, stash_dir, dry_run, profile,
+       scope_mode, scope_value, guidance, ok, result_json, metrics_json, metadata_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
+}
+/**
+ * Delete improve_runs rows older than `retentionDays` (default: 90). Mirrors
+ * {@link purgeOldEvents} — same default, same return shape (number of rows
+ * actually deleted), same disabled-when-non-finite semantics.
+ *
+ * Safe to call from the improve post-loop maintenance pass alongside
+ * `purgeOldEvents(db, retentionDays)`.
+ */
+export function purgeOldImproveRuns(db, retentionDays = 90) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return 0;
+    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
+    const result = db.prepare("DELETE FROM improve_runs WHERE started_at < ?").run(cutoff);
+    const changes = result.changes ?? 0;
+    return typeof changes === "bigint" ? Number(changes) : changes;
+}
+/**
+ * Record (or update) one session's extract outcome. INSERT-OR-REPLACE so the
+ * row reflects the most recent run; downstream skip-logic compares
+ * `session_ended_at` against the live session metadata to decide if anything
+ * new arrived since `processed_at`.
+ */
+export function upsertExtractedSession(db, input) {
+    const endedAtIso = typeof input.sessionEndedAt === "number" && Number.isFinite(input.sessionEndedAt)
+        ? new Date(input.sessionEndedAt).toISOString()
+        : null;
+    db.prepare(`
+    INSERT OR REPLACE INTO extract_sessions_seen
+      (harness, session_id, processed_at, session_ended_at, outcome,
+       candidate_count, proposal_count, rationale, source_run, metadata_json)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.harness, input.sessionId, input.processedAt, endedAtIso, input.outcome, input.candidateCount, input.proposalCount, input.rationale ?? null, input.sourceRun ?? null, JSON.stringify(input.metadata ?? {}));
+}
+/**
+ * Fetch a single session's last extract record, or `undefined` when the
+ * session has never been processed.
+ */
+export function getExtractedSession(db, harness, sessionId) {
+    // bun:sqlite returns null (not undefined) when no row matches — normalize so
+    // callers can rely on `if (!row)` and `toBeUndefined()` equivalently.
+    const row = db
+        .prepare("SELECT * FROM extract_sessions_seen WHERE harness = ? AND session_id = ?")
+        .get(harness, sessionId);
+    return row ?? undefined;
+}
+/**
+ * Bulk-fetch session-extract status for a list of sessionIds in one harness.
+ * Returns a Map keyed by sessionId so callers can do O(1) lookups while
+ * iterating the discovery list.
+ */
+export function getExtractedSessionsMap(db, harness, sessionIds) {
+    const out = new Map();
+    if (sessionIds.length === 0)
+        return out;
+    // SQLite has a ~999 param ceiling; chunk if a caller ever exceeds that.
+    const CHUNK = 500;
+    for (let i = 0; i < sessionIds.length; i += CHUNK) {
+        const chunk = sessionIds.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT * FROM extract_sessions_seen
+         WHERE harness = ? AND session_id IN (${placeholders})`)
+            .all(harness, ...chunk);
+        for (const row of rows)
+            out.set(row.session_id, row);
+    }
+    return out;
+}
+/**
+ * Decide whether a session should be skipped because the extractor has
+ * already processed it AND nothing has changed since. The "anything new since
+ * last extract?" rule is: the live `sessionEndedAtMs` is strictly later than
+ * the recorded `session_ended_at`. Same-or-earlier endedAt means we'd be
+ * re-processing the exact same content for no gain.
+ *
+ * Returns:
+ *   - `false` — no prior row, or session has new content since last extract.
+ *     The caller should process it.
+ *   - `true`  — the session was already processed and hasn't been updated.
+ *     The caller should skip.
+ */
+export function shouldSkipAlreadyExtractedSession(prior, liveSessionEndedAtMs) {
+    if (!prior)
+        return false;
+    // No live timestamp → can't tell if anything's new. Be conservative and
+    // skip — the operator can pass --force later if we add it.
+    if (typeof liveSessionEndedAtMs !== "number" || !Number.isFinite(liveSessionEndedAtMs)) {
+        return true;
+    }
+    const priorMs = prior.session_ended_at ? Date.parse(prior.session_ended_at) : Number.NaN;
+    if (!Number.isFinite(priorMs))
+        return false;
+    // Re-process when there's new content; skip when the session is unchanged.
+    return liveSessionEndedAtMs <= priorMs;
 }
 // ── registry_index_cache (goes in index.db, not state.db) ───────────────────
 /**
@@ -696,7 +1033,7 @@ export async function importEventsJsonl(db, jsonlPath) {
  * created with CREATE TABLE IF NOT EXISTS so it is safe to call inside
  * ensureSchema() or as a standalone migration.
  *
- * Purpose: caches the result of resolving and fetching remote registry kit
+ * Purpose: caches the result of resolving and fetching remote registry stash
  * indexes so `akm search` does not hit the network on every invocation.
  *
  * Indexed (query) columns:
@@ -729,47 +1066,3 @@ export const REGISTRY_INDEX_CACHE_DDL = `
   CREATE INDEX IF NOT EXISTS idx_registry_cache_fetched
     ON registry_index_cache(fetched_at);
 `;
-/**
- * Ensure the `registry_index_cache` table exists in the given database
- * (intended for use with the index.db connection from openDatabase()).
- * Idempotent — safe to call on every open.
- */
-export function ensureRegistryIndexCacheSchema(db) {
-    db.exec(REGISTRY_INDEX_CACHE_DDL);
-}
-/**
- * Upsert a registry index cache entry.
- *
- * @param db          - Open index.db connection.
- * @param registryUrl - Canonical URL of the registry.
- * @param indexJson   - Serialised registry index document.
- * @param etag        - HTTP ETag from the response (optional).
- * @param lastModified - HTTP Last-Modified from the response (optional).
- */
-export function upsertRegistryIndexCache(db, registryUrl, indexJson, etag, lastModified) {
-    db.prepare(`
-    INSERT INTO registry_index_cache (registry_url, fetched_at, etag, last_modified, index_json)
-    VALUES (?, ?, ?, ?, ?)
-    ON CONFLICT(registry_url) DO UPDATE SET
-      fetched_at    = excluded.fetched_at,
-      etag          = excluded.etag,
-      last_modified = excluded.last_modified,
-      index_json    = excluded.index_json
-  `).run(registryUrl, new Date().toISOString(), etag ?? null, lastModified ?? null, indexJson);
-}
-/**
- * Look up a cached registry index entry. Returns undefined when not found or
- * when the entry is older than `maxAgeMs`.
- */
-export function getRegistryIndexCache(db, registryUrl, maxAgeMs = 3_600_000 /* 1 hour */) {
-    const row = db
-        .prepare(`SELECT fetched_at, etag, last_modified, index_json
-       FROM registry_index_cache WHERE registry_url = ?`)
-        .get(registryUrl);
-    if (!row)
-        return undefined;
-    const fetchedAt = Date.parse(row.fetched_at);
-    if (Number.isNaN(fetchedAt) || Date.now() - fetchedAt > maxAgeMs)
-        return undefined;
-    return { indexJson: row.index_json, etag: row.etag, lastModified: row.last_modified };
-}

package/dist/core/text-truncation.js

@@ -0,0 +1,107 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Shared text-truncation heuristics used by `distill` and `consolidate`.
+ *
+ * Both commands need to recognise when an LLM-produced description string was
+ * sliced mid-sentence (typically the model hit its output budget). The two
+ * implementations historically maintained overlapping-but-not-identical
+ * vocabularies of hanging-connector words, which was a maintenance trap.
+ *
+ * This module is the single source of truth. `distill` continues to layer its
+ * own section-heading regex on top (those patterns are distill-specific and
+ * intentionally stay local to that module).
+ */
+/**
+ * Words that, when ending a sentence, suggest the description was truncated
+ * mid-sentence. Prepositions, conjunctions, articles, and auxiliary verbs that
+ * almost always have *something* following them in well-formed prose.
+ *
+ * This is the UNION of the two prior vocabularies used by `distill` and
+ * `consolidate` — a superset of both, so behaviour is at least as strict as
+ * either previous check.
+ *
+ * Stored lowercased; callers must lower-case the last word before lookup.
+ */
+export const TRUNCATION_TRAILING_WORDS = new Set([
+    "a",
+    "after",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "been",
+    "before",
+    "being",
+    "but",
+    "by",
+    "can",
+    "could",
+    "did",
+    "do",
+    "does",
+    "for",
+    "from",
+    "had",
+    "has",
+    "have",
+    "if",
+    "in",
+    "into",
+    "is",
+    "may",
+    "might",
+    "must",
+    "of",
+    "on",
+    "onto",
+    "or",
+    "per",
+    "shall",
+    "should",
+    "so",
+    "than",
+    "that",
+    "the",
+    "to",
+    "upon",
+    "via",
+    "was",
+    "were",
+    "when",
+    "which",
+    "while",
+    "will",
+    "with",
+    "would",
+]);
+/**
+ * Returns a reason string when `description` looks truncated mid-sentence;
+ * returns `null` if the description appears complete.
+ *
+ * Heuristics:
+ *   - Trailing `,`, `;`, `:`, or `+` (operator-style cutoff like `max-width:100% +`)
+ *   - Trailing ellipsis (`...` or `…`)
+ *   - Last word matches {@link TRUNCATION_TRAILING_WORDS}
+ *
+ * Does NOT detect section-heading fragments — that check is distill-specific
+ * and lives in `src/commands/distill.ts` (`HEADING_FRAGMENT_PATTERNS`).
+ */
+export function detectTruncatedDescription(description) {
+    const trimmed = description.trim();
+    if (trimmed.length === 0)
+        return null; // empty handled elsewhere
+    if (/[,;:+]$/.test(trimmed))
+        return "ends with trailing punctuation/operator";
+    if (/\.{3,}$/.test(trimmed) || /…$/.test(trimmed))
+        return "ends with ellipsis";
+    const lastWord = trimmed.split(/\s+/).pop() ?? "";
+    const normalized = lastWord.toLowerCase();
+    if (TRUNCATION_TRAILING_WORDS.has(normalized)) {
+        return `ends with hanging connector "${lastWord}"`;
+    }
+    return null;
+}

package/dist/core/time.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Shared time and date utilities.
  *

package/dist/core/tty.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Terminal-glyph and color gating helpers (#486).
+ *
+ * Honor the [NO_COLOR](https://no-color.org/) convention — when NO_COLOR is
+ * present in the environment (with any value, including empty), the CLI
+ * suppresses both ANSI color codes AND decorative emoji glyphs. Emoji often
+ * render as garbage in non-Unicode terminals or get logged as literal bytes
+ * when output is piped to text aggregators, so we treat them as a subset of
+ * "color" decoration.
+ *
+ * Detection is also automatic on non-TTY stderr (output piped or redirected
+ * to a file), where decorative glyphs add nothing.
+ */
+/**
+ * Returns true when decorative glyphs and color codes should be emitted.
+ * False when NO_COLOR is set or stderr is not a TTY (unless FORCE_COLOR
+ * overrides per the de-facto Node convention).
+ */
+export function shouldDecorate() {
+    if (process.env.NO_COLOR !== undefined)
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "" && process.env.FORCE_COLOR !== "0") {
+        return true;
+    }
+    return process.stderr.isTTY === true;
+}
+// Map known decorative emoji to plain ASCII fallbacks. Anything not listed
+// is still removed by the catch-all sweep below when decoration is off.
+const EMOJI_FALLBACKS = [
+    [/\u{1F44B}\s*/gu, ""], // wave (with trailing space)
+    [/✓/g, "[ok]"],
+    [/✗/g, "[x]"],
+    [/✘/g, "[x]"],
+    [/⚠️?/g, "[!]"],
+    [/\u{1F4DA}\s*/gu, ""], // books
+];
+/**
+ * If decoration is disabled, replace known emoji with ASCII fallbacks and
+ * strip any remaining pictograph code points. If decoration is enabled,
+ * return the input unchanged.
+ */
+export function plainize(text) {
+    if (shouldDecorate())
+        return text;
+    let out = text;
+    for (const [pattern, repl] of EMOJI_FALLBACKS) {
+        out = out.replace(pattern, repl);
+    }
+    // Catch-all for unmapped pictographs. Future-proof when new emoji are added
+    // to call sites without updating the explicit map.
+    out = out.replace(/[\u{1F300}-\u{1FAFF}]/gu, "");
+    // Collapse runs of whitespace introduced by emoji removal, but preserve
+    // intentional leading indentation. Only collapses interior runs.
+    out = out.replace(/(\S)[ \t]{2,}/g, "$1 ");
+    return out;
+}

package/dist/core/warn.js

@@ -1,3 +1,6 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
  * Module-level quiet/verbose flags and optional file sink for stderr output.
  *
@@ -81,8 +84,10 @@ function appendToLogFile(level, args) {
     try {
         fs.appendFileSync(logFilePath, `[${ts}] [${level}] ${msg}\n`);
     }
-    catch {
-        // Never throw from a logging function — log failures are silent.
+    catch (e) {
+        // Log file write failed — emit directly to stderr so the message is not lost.
+        process.stderr.write(`[akm:warn] log-file write failed (${logFilePath}): ${e}\n`);
+        process.stderr.write(`[${ts}] [${level}] ${msg}\n`);
     }
 }
 /**