spexcode 0.6.2 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/localIssues.js

@@ -0,0 +1,582 @@
+// @@@ the local issue store - the LOCAL store of the one Issue object ([[issues]] / [[local-issues]] /
+// [[mentions]]). A thread IS an Issue whose `store` is 'local' — membership implied by WHERE the file lives,
+// never written into it. One thread = one PLAIN markdown file at <main>/.spec/.issues/<id>.md; there is
+// deliberately no content-kind taxonomy (a change suggestion, an annotation, a Q&A are the same mechanism —
+// the prose says what it is). Others reply/discuss like an async chatroom; a supervisor drains it via
+// `spex issue ls` (reading is the port's job, issues.ts — this module owns only the store + its write verbs).
+// Because a thread file is NOT named spec.md, the spec walk never nodes it and isSpecMd ignores it —
+// invisible to lint / drift / deriveStatus / board with ZERO exemption. The store lives on the TRUNK, not
+// per-branch: reads and writes target the main checkout and commit STRAIGHT to it (--no-verify, provably
+// store-only), so a post-merge thread lands durably even though the author's own branch already merged.
+// A committing write is allowed ONLY from the trunk checkout itself (isPrimaryCheckout) — a linked-worktree
+// backend sharing that main is refused loud, never left to fabricate a stray commit on a main it doesn't own;
+// SPEXCODE_ISSUES_DIR routes an e2e/test rig to a disposable plain-file store (see localStoreDir below).
+// The on-disk dir was historically `.spec/.forum`; a one-shot self-migration ([[issues-store-rename]])
+// renames any legacy `.spec/.forum` to `.spec/.issues` on the first store touch after a toolchain update.
+import { readdirSync, existsSync, mkdirSync, writeFileSync, readFileSync, rmdirSync, statSync } from 'node:fs';
+import { join, dirname, resolve as resolvePath } from 'node:path';
+import { git, headSha, repoRoot } from '@spexcode/spec-core';
+import { mainCheckout, envSessionId, readConfig } from '@spexcode/spec-core';
+import { dispatchNewMentions, parseMentions } from './mentions.js';
+const LOCAL_STORE_REL = '.spec/.issues';
+// the pre-rename dir ([[issues-store-rename]]); ensureStoreMigrated() renames it to LOCAL_STORE_REL once.
+const LEGACY_STORE_REL = '.spec/.forum';
+// @@@ the on/off switch - the issues workflow is an OPT-OUTABLE feature (default ON). The single source of
+// truth is `spexcode.json`'s `issues.enabled` (the same settings file that carries every other toggle),
+// read via readConfig so a machine-local `spexcode.local.json` can override it. OFF silences the post-merge
+// nudge (and, in the dashboard, hides the issues view); the raw write verbs stay usable, since running one
+// is explicit consent. There is deliberately NO CLI toggle verb (v0.3.0 — "no `spex config set`" is this
+// project's standing rule): flip the key by editing the JSON, effective immediately because readConfig
+// reads the working tree. A legacy pre-rename `proposals.enabled` key is NOT read (no fallback — fail
+// toward the default); `spex doctor` reports it so an old settings file gets repaired, not silently obeyed.
+export const issuesEnabled = () => readConfig(mainCheckout()).issues?.enabled ?? true;
+const list = (v) => v ? v.split(',').map((s) => s.trim()).filter(Boolean) : [];
+// @@@ where a store write lands — ONE deterministic rule ([[local-issues]] "only the trunk checkout may
+// commit"). Every backend resolves the store to `mainCheckout()` (dirname of the shared git-common-dir), so a
+// backend serving a LINKED WORKTREE would git-commit a stray issue onto the REAL, live main — dirtying it and
+// racing its index.lock. The rule:
+//   1. SPEXCODE_ISSUES_DIR override → a DISPOSABLE store of plain files (no git, no shared main); the e2e/test
+//      seam. Both reads and writes target it, so a test rig throws its whole store away.
+//   2. else the trunk `.spec/.issues/` — but a *committing* write is allowed ONLY from the trunk checkout
+//      itself (repoRoot === mainCheckout: the primary backend, or a throwaway clone owning its own main). A
+//      linked-worktree backend is refused loud (requirePrimaryStore) rather than silently writing someone
+//      else's main. Reads always resolve to the trunk (visibility never hostages on being primary).
+const overrideStoreDir = () => {
+    const p = process.env.SPEXCODE_ISSUES_DIR?.trim();
+    return p ? p : null;
+};
+// is THIS process rooted in the trunk checkout itself? True for the primary backend and for a clone (its own
+// .git → its own disposable main); false for a linked-worktree backend, the store-write footgun.
+const isPrimaryCheckout = () => {
+    try {
+        return resolvePath(repoRoot()) === resolvePath(mainCheckout());
+    }
+    catch {
+        return false;
+    }
+};
+// fail LOUD before a committing write from a non-trunk checkout: never fabricate a commit on a shared main
+// this process does not own. (The disposable override bypasses this — it commits to nothing.)
+function requirePrimaryStore(action) {
+    if (isPrimaryCheckout())
+        return;
+    throw new Error(`refusing to ${action}: this backend serves a linked worktree (${resolvePath(repoRoot())}), not the trunk ` +
+        `checkout (${resolvePath(mainCheckout())}) — committing here would land a stray issue on the REAL main and ` +
+        `race its index. Run the write from the trunk checkout (or its backend), or, for a throwaway/e2e run, set ` +
+        `SPEXCODE_ISSUES_DIR=<disposable-dir> to write plain files nowhere near the real store.`);
+}
+// the local issue store dir — a fixed path directly under the trunk's .spec (name-independent, unlike the
+// .plugins system which nests under the named root node), OR the disposable override. Every read and write goes here.
+const localStoreDir = () => overrideStoreDir() ?? join(mainCheckout(), LOCAL_STORE_REL);
+// the author's signature: the effective governed session id (envSessionId handles the claude/codex split).
+export const currentSession = () => envSessionId() || 'unknown';
+// a synchronous sleep for the commit-retry backoff (Date/timers-free, safe in any runtime).
+const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+// ── file format ──────────────────────────────────────────────────────────────────────────────────────
+// frontmatter (concern/by/status/nodes/evidence/created) + a prose body, then any replies — each
+// preceded by a `<!-- reply: <by> @ <iso> -->` sentinel: invisible in rendered markdown, unambiguous to
+// parse. Only the store writes these files, so a fixed shape is safe.
+//
+// A REMARK ([[remark-substrate]]) is a reply carrying extra state, appended to the SAME sentinel as a
+// ` :: <space-joined k=v attrs>` tail (a plain reply has no tail → parses unchanged, backward compatible):
+//   rid=<id>            stable per-remark id — its presence marks the reply a remark
+//   sha=<targetCodeSha> the reading the remark was authored against
+//   resolved=<by>@<at>  present only once resolved (absent ⟹ resolved:false)
+const REPLY_RE = /^<!-- reply: (.+?) @ (.+?)(?: :: (.+))? -->$/;
+function parse(id, text) {
+    const m = text.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    const fm = {};
+    for (const line of (m ? m[1] : '').split('\n')) {
+        const mm = line.match(/^([a-zA-Z]+):\s*(.*)$/);
+        if (mm)
+            fm[mm[1]] = mm[2].trim();
+    }
+    const body = [];
+    const replies = [];
+    let cur = null;
+    for (const line of (m ? m[2] : text).replace(/^\n+/, '').split('\n')) {
+        const rm = line.match(REPLY_RE);
+        if (rm) {
+            cur = { by: rm[1], at: rm[2], body: '', ...parseRemarkAttrs(rm[3]) };
+            replies.push(cur);
+            continue;
+        }
+        if (cur)
+            cur.body += (cur.body ? '\n' : '') + line;
+        else
+            body.push(line);
+    }
+    return {
+        id,
+        store: 'local',
+        concern: fm.concern || id,
+        by: fm.by || 'unknown',
+        status: fm.status === 'landed' ? 'landed' : 'open',
+        nodes: list(fm.nodes),
+        created: fm.created || '',
+        body: body.join('\n').trim(),
+        replies: replies.map((r) => ({ ...r, body: r.body.trim() })),
+        evidence: list(fm.evidence),
+        labels: [],
+    };
+}
+// user body text must never FORGE a reply sentinel: a line matching `<!-- reply: … -->` in a body would be
+// re-read as a thread boundary, splitting the thread and truncating the body. Neutralize the marker in user
+// content (a zero-width space breaks the `<!-- reply:` prefix — invisible on render, idempotent), so only
+// serialize's OWN sentinels parse as boundaries. Frontmatter scalars are single-line-stripped for the same
+// reason (a newline/`---` in a concern can't break the block).
+const safeBody = (t) => t.trim().replace(/<!-- reply:/g, '<!--​reply:');
+const safeScalar = (t) => t.replace(/[\r\n]+/g, ' ').trim();
+// the ` :: k=v k=v` remark tail on a reply sentinel ↔ the reply's remark fields. `undefined` attrs (a plain
+// reply) → no remark fields; `rid` present → the reply IS a remark ([[remark-substrate]]). Values are
+// space-free (ids, a codeSha, a session id, an ISO instant), so a space-split is unambiguous.
+function parseRemarkAttrs(attrs) {
+    if (!attrs)
+        return {};
+    const kv = new Map();
+    for (const tok of attrs.trim().split(/\s+/)) {
+        const i = tok.indexOf('=');
+        if (i > 0)
+            kv.set(tok.slice(0, i), tok.slice(i + 1));
+    }
+    if (!kv.has('rid'))
+        return {};
+    const out = { rid: kv.get('rid'), targetCodeSha: kv.get('sha') ?? '', resolved: false };
+    const r = kv.get('resolved');
+    if (r) {
+        const at = r.indexOf('@');
+        out.resolved = true;
+        out.resolvedBy = r.slice(0, at);
+        out.resolvedAt = r.slice(at + 1);
+    }
+    return out;
+}
+function serializeRemarkAttrs(r) {
+    if (r.rid === undefined)
+        return '';
+    const parts = [`rid=${r.rid}`, `sha=${r.targetCodeSha ?? ''}`];
+    if (r.resolved)
+        parts.push(`resolved=${r.resolvedBy ?? ''}@${r.resolvedAt ?? ''}`);
+    return ` :: ${parts.join(' ')}`;
+}
+function serialize(p) {
+    const fm = [
+        `concern: ${safeScalar(p.concern)}`,
+        `by: ${safeScalar(p.by)}`,
+        `status: ${safeScalar(p.status)}`,
+        p.nodes.length ? `nodes: ${p.nodes.join(', ')}` : '',
+        p.evidence.length ? `evidence: ${p.evidence.join(', ')}` : '',
+        `created: ${p.created}`,
+    ].filter(Boolean);
+    let out = `---\n${fm.join('\n')}\n---\n\n${safeBody(p.body)}\n`;
+    for (const r of p.replies)
+        out += `\n<!-- reply: ${safeScalar(r.by)} @ ${safeScalar(r.at)}${serializeRemarkAttrs(r)} -->\n${safeBody(r.body)}\n`;
+    return out;
+}
+export function loadLocalIssues() {
+    ensureStoreMigrated(); // read path: a pre-rename deployment migrates on first read, so no thread is lost
+    const dir = localStoreDir();
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => parse(e.name.replace(/\.md$/, ''), readFileSync(join(dir, e.name), 'utf8')))
+        .sort((a, b) => a.created.localeCompare(b.created));
+}
+export function loadOne(id) {
+    ensureStoreMigrated();
+    const f = join(localStoreDir(), `${id}.md`);
+    if (!existsSync(f))
+        throw new Error(`no local issue '${id}' (see \`spex issue ls --all --store local\`)`);
+    return parse(id, readFileSync(f, 'utf8'));
+}
+// a filesystem-safe, readable, collision-free id from the concern (slug + numeric suffix if taken).
+// RESERVED_IDS are the words an issue address gives its own meaning — `new` is the compose PAGE
+// ([[issues-view]]), so an issue owning that id would be unreachable at its own detail address. The slug
+// steps around them with the same numeric suffix a taken id gets: a collision, not a silent shadow.
+const RESERVED_IDS = new Set(['new']);
+function uniqueId(concern) {
+    const base = concern.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'issue';
+    const dir = localStoreDir();
+    let id = base;
+    for (let n = 2; RESERVED_IDS.has(id) || existsSync(join(dir, `${id}.md`)); n++)
+        id = `${base}-${n}`;
+    return id;
+}
+// @@@ store lock - local-issue writes contend two ways: git commits share the repo index.lock, and a
+// reply's read-modify-write of one thread file loses an update if two race (both read the base, last write
+// wins). A single cross-process lock serializes the WHOLE prepare→write→commit, killing both. It is an
+// atomic `mkdir` (in .git, never committed); a lock whose holder crashed is stolen after it goes stale.
+// Because the commit is `--no-verify` fast (below), serialized writes stay quick even under a burst. The
+// lock FILE keeps its historical `spexcode-forum.lock` name ON PURPOSE: during the one-shot store-dir
+// migration ([[issues-store-rename]]) an old and a new toolchain can run against the SAME checkout at once,
+// and they mutually exclude only while contending on the SAME lock name — renaming it would open exactly
+// the migration race the lock exists to close.
+let lockHeld = false; // re-entrancy guard so ensureStoreMigrated() no-ops when reached from inside a hold
+function withStoreLock(fn) {
+    // the disposable store locks inside its own dir; the trunk store locks in the shared `.git` (one lock name
+    // across every worktree of the clone, so all writers of the SAME real store mutually exclude).
+    const override = overrideStoreDir();
+    const lock = override ? join(override, '.spexcode-issues.lock') : join(mainCheckout(), '.git', 'spexcode-forum.lock');
+    mkdirSync(dirname(lock), { recursive: true }); // parent must exist for the atomic mkdir-acquire (a no-op for .git)
+    for (let i = 0;; i++) {
+        try {
+            mkdirSync(lock);
+            break;
+        } // atomic acquire
+        catch {
+            try {
+                if (Date.now() - statSync(lock).mtimeMs > 20000)
+                    rmdirSync(lock);
+            }
+            catch { /* released meanwhile */ }
+            sleep(40 + Math.floor(Math.random() * 80)); // spin with jitter until free / stolen
+        }
+    }
+    lockHeld = true;
+    try {
+        return fn();
+    }
+    finally {
+        lockHeld = false;
+        try {
+            rmdirSync(lock);
+        }
+        catch { /* already gone */ }
+    }
+}
+// @@@ one-shot store-dir migration ([[issues-store-rename]]) - the local issue store's on-disk dir was
+// historically `.spec/.forum`; it is now `.spec/.issues`. Any pre-rename deployment migrates ITSELF on the
+// first store touch after its toolchain updates: a single committed `git mv` on the trunk, so a thread's
+// whole reply history reads identically afterwards (`git log --follow` traces through the rename — the data
+// is git, and a rename preserves it). Called at every store entrypoint BEFORE the lock is taken; it takes
+// the lock itself to do the mv, so the whole find→check→mv is atomic against a concurrent first-touch burst:
+// exactly ONE mv commit, because a racer that waited on the lock re-checks under it and finds nothing to do.
+// Fast path: no legacy dir → instant, no lock (the common case after migration / on a fresh repo). Both
+// dirs present (pathological) → fail LOUD with the repair, never a silent merge.
+function ensureStoreMigrated() {
+    if (lockHeld)
+        return; // inside a hold: an outer entrypoint already ran this
+    if (overrideStoreDir())
+        return; // disposable store: no legacy trunk dir to migrate
+    if (!isPrimaryCheckout())
+        return; // a git-committing migration is trunk-only; the primary migrates on its next touch
+    const root = mainCheckout();
+    if (!existsSync(join(root, LEGACY_STORE_REL)))
+        return; // fresh or already-migrated: nothing to do (no lock)
+    withStoreLock(() => {
+        const r = mainCheckout();
+        const legacy = join(r, LEGACY_STORE_REL), current = join(r, LOCAL_STORE_REL);
+        if (!existsSync(legacy))
+            return; // a racer migrated it while we waited on the lock
+        if (existsSync(current))
+            throw new Error(`both ${LEGACY_STORE_REL} and ${LOCAL_STORE_REL} exist in ${r} — refusing to auto-merge the local ` +
+                `issue store. Reconcile by hand: move any threads from ${LEGACY_STORE_REL} into ${LOCAL_STORE_REL}, ` +
+                `then \`git rm -r ${LEGACY_STORE_REL} && git commit\`, and re-run.`);
+        git(['-C', r, 'mv', LEGACY_STORE_REL, LOCAL_STORE_REL]);
+        git(['-C', r, 'commit', '--no-verify', '-m', `issues: store dir ${LEGACY_STORE_REL} → ${LOCAL_STORE_REL}`,
+            '--', LEGACY_STORE_REL, LOCAL_STORE_REL]);
+    });
+}
+// write + commit ONE store file STRAIGHT to the trunk. The commit is `--no-verify`: the file is DATA,
+// structurally invisible to spec-lint, and the commit is provably store-only (one .spec/.issues/ path), so the
+// pre-commit gate would only pass anyway — running it just burns seconds (tsx cold-start) holding the lock.
+// A NO-CHANGE write is idempotent SUCCESS, never a failure: when the serialized bytes already equal the
+// stored state (a duplicate close — the store IS the requested state), `git commit` would exit 1
+// 'nothing to commit', so we detect the no-op after `add` (the staged path equals HEAD → status is silent)
+// and skip the commit. Returns whether the store actually changed, so a caller can say 'already <state>'.
+// MUST run while holding withStoreLock — it is the write half of a locked read-modify-write; its callers
+// (commitStore, findOrCreateEvalThread) own the lock, so it never acquires one itself (mkdir is not re-entrant).
+function writeStoreFile(p, message) {
+    const override = overrideStoreDir();
+    if (override) { // disposable store: a plain file, never a commit, never a shared main
+        mkdirSync(override, { recursive: true });
+        const f = join(override, `${p.id}.md`);
+        const data = serialize(p);
+        if (existsSync(f) && readFileSync(f, 'utf8') === data)
+            return false;
+        writeFileSync(f, data);
+        return true;
+    }
+    requirePrimaryStore('write a local issue'); // a linked-worktree backend must NOT commit onto the real main
+    const root = mainCheckout();
+    const rel = `${LOCAL_STORE_REL}/${p.id}.md`;
+    mkdirSync(join(root, LOCAL_STORE_REL), { recursive: true });
+    writeFileSync(join(root, rel), serialize(p));
+    git(['-C', root, 'add', '--', rel]);
+    if (!git(['-C', root, 'status', '--porcelain', '--', rel]).trim())
+        return false; // staged == HEAD: the no-op
+    git(['-C', root, 'commit', '--no-verify', '-m', message, '--', rel]);
+    return true;
+}
+// @@@ the shared trunk-data commit — the committing half of the store discipline, exported for OTHER
+// git-tracked data writes that need a durable landing with no worktree ritual behind them (the eval
+// sidecar's human-ok, [[human-ok]]). Same rules as the issue store's own write: only the trunk checkout
+// itself commits (a linked-worktree caller gets 'not-primary' back and leaves its append for its own
+// session's ritual commit — the sidecar, unlike the issue store, legitimately lives per-branch and
+// merges); the commit is `--no-verify` and provably scoped to the one data path; the shared store lock
+// serializes it against every other trunk data write so racing writers never fight over the git index.
+export function commitTrunkData(relPath, message) {
+    if (overrideStoreDir())
+        return 'not-primary'; // a disposable-store test rig commits nothing, ever
+    if (!isPrimaryCheckout())
+        return 'not-primary';
+    return withStoreLock(() => {
+        const root = mainCheckout();
+        git(['-C', root, 'add', '--', relPath]);
+        if (!git(['-C', root, 'status', '--porcelain', '--', relPath]).trim())
+            return 'no-op';
+        git(['-C', root, 'commit', '--no-verify', '-m', message, '--', relPath]);
+        return 'committed';
+    });
+}
+// prepare (a FRESH read-modify or a new thread) + write + commit a single store file, all under the store
+// lock so the read-modify-write is atomic. prepare() runs INSIDE the lock, so a reply/close reads the
+// current thread, never a stale copy. A pre-rename store migrates first (before the lock — ensure takes it).
+// `changed: false` = the store already held exactly this state (see writeStoreFile) — success, nothing committed.
+function commitStore(message, prepare) {
+    ensureStoreMigrated();
+    return withStoreLock(() => {
+        const p = prepare();
+        const changed = writeStoreFile(p, message);
+        return { issue: p, changed };
+    });
+}
+// `author` defaults to the effective session id, but a caller (the dashboard's human write path) may pass
+// `'human'` — the write mechanism is identical either way, only the signature differs.
+// The thread's `nodes:` are INFERRED from the text's `[[node]]` topic links ([[mentions]] — the one in-text
+// reference primitive every input already carries), unioned with any explicitly-passed ids (`--node`): a
+// writer links nodes by writing them, never by re-typing ids into a separate field.
+export function openIssue(concern, opts = {}) {
+    const nodes = [...new Set([...(opts.nodes || []), ...parseMentions(`${concern}\n${opts.body || ''}`).nodes])];
+    return commitStore(`issue: ${concern}`, () => ({
+        id: uniqueId(concern), // minted INSIDE the lock, so two racing posts can't pick the same id
+        store: 'local',
+        concern,
+        by: opts.author || currentSession(),
+        status: 'open',
+        nodes,
+        created: new Date().toISOString(),
+        body: (opts.body || `(no detail given — ${concern})`).trim(),
+        replies: [],
+        evidence: opts.evidence || [],
+        labels: [],
+    })).issue;
+}
+// mint a per-thread-unique remark id (retry on the rare collision within one thread). Short + readable so a
+// `<thread-id>#<rid>` ref is typeable; stable, so a resolve/retract never lands on the wrong remark.
+function mintRid(existing) {
+    let rid;
+    do {
+        rid = 'r' + Math.random().toString(36).slice(2, 6);
+    } while (existing.has(rid));
+    return rid;
+}
+// a REMARK ([[remark-substrate]]) rides the SAME committed reply write, just stamping the remark fields: a
+// fresh unresolved bit + a minted stable rid + the codeSha it was authored against. Absent `remark` this is
+// an ordinary reply, unchanged. Returns the thread; the new reply is its last, so a caller reads back its rid.
+export function reply(id, body, author, evidence, remark) {
+    const by = author || currentSession();
+    return commitStore(remark ? `remark(${id}): by ${by}` : `issue(${id}): reply by ${by}`, () => {
+        const p = loadOne(id); // fresh read under the lock → no lost-update when replies race
+        const post = { by, at: new Date().toISOString(), body: body.trim() };
+        if (remark) {
+            post.rid = mintRid(new Set(p.replies.map((r) => r.rid).filter((x) => !!x)));
+            post.targetCodeSha = remark.targetCodeSha;
+            post.resolved = false;
+        }
+        p.replies.push(post);
+        // an anchored annotation carries its frame blob: the reply's evidence hashes accrue onto the THREAD's
+        // typed evidence[] (deduped), so the thread stays the one place a video finding's blobs are indexed.
+        if (evidence?.length)
+            p.evidence = [...new Set([...p.evidence, ...evidence])];
+        return p;
+    }).issue;
+}
+// @@@ the PROGRAMMATIC store write surface — the dashboard's human write path calls these (author `'human'`).
+// The store is git-native data, so a human's write goes through the SAME open/reply the CLI uses (committed
+// straight to the trunk). @session remains text in that committed discussion; only @new dispatches after it.
+// Originator courtesy is composed above this store because it needs eval-aware candidate resolution.
+export async function replyLocalIssue(id, body, author, evidence, remark) {
+    const thread = reply(id, body, author, evidence, remark);
+    return {
+        thread,
+        outcomes: await dispatchNewMentions(body, { threadId: id, node: thread.nodes[0] || null, author, status: thread.status }),
+    };
+}
+export async function postLocalIssue(concern, opts) {
+    const thread = openIssue(concern, { nodes: opts.nodes, body: opts.body, evidence: opts.evidence, author: opts.author });
+    return {
+        thread,
+        outcomes: await dispatchNewMentions(opts.body || concern, {
+            threadId: thread.id,
+            node: thread.nodes[0] || null,
+            author: opts.author,
+            status: thread.status,
+        }),
+    };
+}
+export function closeLocalIssue(id) {
+    const { changed } = commitStore(`issue(${id}): close`, () => {
+        const p = loadOne(id);
+        p.status = 'landed';
+        return p;
+    });
+    return { status: 'landed', already: !changed };
+}
+// ── remarks ([[remark-substrate]]) ──────────────────────────────────────────────────────────────────
+// A remark is a reply carrying a resolvable bit, attached to a HOST: a local issue, or a scenario keyed by
+// (node, scenario). The scenario track is NOT a new store — it is the annotator's lazy eval thread, keyed by
+// its `eval: <node> · <scenario>` concern; a remark reuses it, creating it on first remark as a stub
+// container (every remark is a reply, never the thread body, so the resolved bit always lives in one place).
+// @@@ the eval-concern format, once - composer and parser side by side. The parser existed in two copies while
+// a CLI surface down here had to recognise the format without being able to import the module that composes it;
+// [[issues-cli]] removed that constraint, so the format is one pair now. `node` is matched non-greedily because
+// it can never contain ' · ' while a scenario name may.
+const evalConcernKey = (node, scenario) => `eval: ${node} · ${scenario}`;
+const EVAL_CONCERN_RE = /^eval: (.+?) · (.+)$/;
+export const parseEvalConcern = (concern) => {
+    const m = EVAL_CONCERN_RE.exec(concern);
+    return m ? { node: m[1].trim(), scenario: m[2].trim() } : null;
+};
+// find-or-create the ONE scenario thread for (node, scenario), keyed by its eval concern, ATOMICALLY under
+// the store lock. R4 says a scenario's remark track lives ONCE — but a concurrent first-remark burst is a
+// normal dogfood situation (SpexCode runs parallel workers), and if the not-found read sat OUTSIDE the lock
+// two racers could both read "absent" and both create, minting a second thread whose remarks are invisible
+// to the concern key (a silent teeth blind spot). Holding one lock across both the find AND the create closes
+// that window: a racer either sees the thread the first created, or is the first. The stub is a pure
+// container (its body carries a [[wiki-link]], never an @-reference), so it needs no async notification — a
+// synchronous create suffices, and staying sync is exactly what lets it share the lock hold.
+function findOrCreateEvalThread(node, scenario, author) {
+    ensureStoreMigrated(); // migrate before the lock (ensure takes it itself; never nest a store-lock hold)
+    const concern = evalConcernKey(node, scenario);
+    return withStoreLock(() => {
+        const existing = loadLocalIssues().find((t) => t.store === 'local' && t.concern === concern);
+        if (existing)
+            return existing;
+        const p = {
+            id: uniqueId(concern), store: 'local', concern, by: author, status: 'open',
+            nodes: [node], created: new Date().toISOString(),
+            body: `Remarks on the \`${scenario}\` eval of [[${node}]].`, replies: [], evidence: [], labels: [],
+        };
+        writeStoreFile(p, `issue: ${concern}`);
+        return p;
+    });
+}
+function resolveRemarkHost(host, author) {
+    if (host.scenario) {
+        const node = host.node;
+        if (!node)
+            throw new Error('a scenario remark needs a node plus --scenario <name>');
+        return findOrCreateEvalThread(node, host.scenario, author).id;
+    }
+    if (!host.issue)
+        throw new Error('a remark needs a host: an issue id, or a node with --scenario <name>');
+    return loadOne(host.issue).id; // throws loudly if the issue doesn't exist
+}
+// author a remark on a host — the ONE write both the CLI (`spex remark add`) and the server call. Stamps the
+// codeSha it was authored against (the worktree HEAD by default — R2). Returns the `<thread-id>#<rid>` ref.
+export async function remarkOnHost(host, body, opts = {}) {
+    const author = opts.author || currentSession();
+    const codeSha = opts.codeSha || headSha(repoRoot());
+    const id = resolveRemarkHost(host, author);
+    const { thread, outcomes } = await replyLocalIssue(id, body, author, opts.evidence, { targetCodeSha: codeSha });
+    const rid = thread.replies[thread.replies.length - 1].rid;
+    return { ref: `${id}#${rid}`, rid, codeSha, thread, author, outcomes };
+}
+// a remark ref is `<thread-id>#<rid>`; the thread id (a store slug) never contains '#', so split on the last.
+function parseRemarkRef(ref) {
+    const i = ref.lastIndexOf('#');
+    if (i <= 0 || i === ref.length - 1)
+        throw new Error(`bad remark ref '${ref}' — expected <thread-id>#<rid> (the id \`spex remark add\` printed)`);
+    return { id: ref.slice(0, i), rid: ref.slice(i + 1) };
+}
+// resolve a remark (R3): a DELIBERATE call by a SECOND PARTY — never the author (no self-resolve: an
+// identity comparison, so the dashboard's `human` cannot resolve a human-authored remark either), and
+// MONOTONIC (no un-resolve — a regression is a NEW remark). The resolver's identity is derived by the
+// SURFACE ([[remark-substrate]] LAW L): a governed session id from the CLI, the `human` sentinel from the
+// dashboard — both are real second parties, so the same rule runs on both. `by` is the resolving party.
+export function resolveRemark(ref, by) {
+    const { id, rid } = parseRemarkRef(ref);
+    const { issue: thread } = commitStore(`remark(${id}#${rid}): resolved by ${by}`, () => {
+        const p = loadOne(id);
+        const r = p.replies.find((x) => x.rid === rid);
+        if (!r)
+            throw new Error(`no remark '${ref}' in that thread`);
+        if (!by || by === 'unknown')
+            throw new Error(`resolve needs a real identity (got '${by || 'none'}'): run it under a governed session, or from the dashboard (its actor is 'human')`);
+        if (r.resolved)
+            throw new Error(`remark '${ref}' is already resolved — monotonic: a regression is a NEW remark, never an un-resolve`);
+        if (r.by === by)
+            throw new Error(`refusing to self-resolve '${ref}': the author (${by}) may not resolve their own remark — resolve is a second party's deliberate judgment`);
+        r.resolved = true;
+        r.resolvedBy = by;
+        r.resolvedAt = new Date().toISOString();
+        return p;
+    });
+    return { thread, rid };
+}
+// retract a remark (R3): the AUTHOR withdraws their OWN remark, removing it — but ONLY while it is
+// unresolved. Only the author may retract; and once a SECOND party has deliberately resolved it, the remark
+// (and that recorded judgment) is part of the record — retract may not erase it. This makes R3's
+// monotonicity two-sided: resolve can't be undone, and retract can't back-door an un-resolve by deleting the
+// resolved remark. A regression after a resolve is a NEW remark, never a retract-and-reraise.
+export function retractRemark(ref, by) {
+    const { id, rid } = parseRemarkRef(ref);
+    const { issue: thread } = commitStore(`remark(${id}#${rid}): retracted by ${by}`, () => {
+        const p = loadOne(id);
+        const idx = p.replies.findIndex((x) => x.rid === rid);
+        if (idx < 0)
+            throw new Error(`no remark '${ref}' in that thread`);
+        if (p.replies[idx].by !== by)
+            throw new Error(`only the author (${p.replies[idx].by}) may retract '${ref}' — you are '${by}'`);
+        if (p.replies[idx].resolved)
+            throw new Error(`refusing to retract '${ref}': it was resolved by ${p.replies[idx].resolvedBy} — a resolved remark is part of the record (monotonic), retract only withdraws an UNRESOLVED remark; a regression is a NEW remark`);
+        p.replies.splice(idx, 1);
+        return p;
+    });
+    return { thread, rid };
+}
+// the post-merge nudge TEXT ([[local-issues]]) — produced HERE so the toggle and the wording live in one
+// place; the post-merge git hook is a thin caller that just echoes this. Returns '' when the feature is OFF,
+// so the hook prints nothing.
+export function nudge(node) {
+    if (!issuesEnabled())
+        return '';
+    return [
+        '── issues ─────────────────────────────────────────────────────────',
+        `Your work (${node || 'this node'}) just landed. Two issue checks before you close:`,
+        '',
+        '1. CLOSE what you finished. An issue whose work just landed is closed, not',
+        '   left open — the open set is the OUTSTANDING work, so a stale open reads as a',
+        '   lie:  spex issue ls --store local     then   spex issue close <id>',
+        '',
+        '2. RECORD only what OUTLIVES this task — a concern you are NOT acting on now:',
+        '   an off-mainline smell / awkward boundary / wish, or a trivial-but-must-not-',
+        "   forget to-do that doesn't earn a spec node. NOT a bug tracker (that is the",
+        '   spec graph + the forge), NOT your assigned task or a fix you are about to',
+        '   make — those need no issue. Only the taste that would otherwise evaporate:',
+        '     spex issue ls                            # read first — reply if already raised',
+        '     spex issue open "<concern>" [--node <id>]   # else open one',
+        'A supervisor drains the store later. (Advisory — skip if nothing is owed.)',
+        '───────────────────────────────────────────────────────────────────',
+    ].join('\n');
+}
+// @@@ close-time issue closeout ([[local-issues]] / [[state]]) — the DATA half of the propose-close nudge:
+// appended to the `done --propose close` declaration BESIDE the resource-cleanup reminder (cli.ts, same
+// insertion point, same semantics — a nudge, never a gate). Data-driven so it earns its line: it lists the
+// still-open local threads THIS session touched (authored or replied; eval `eval: <node> · <scenario>`
+// containers excluded — they host remarks and outlive every session by design) and prints NOTHING when the
+// session owes nothing, when the feature is OFF, or when there is no session identity. Some issues rightly
+// outlive their session (a taste concern waiting for the drain), so the ask is close OR say why it stays
+// open — never a forced close.
+export function closeoutNudge(sessionId) {
+    if (!sessionId || sessionId === 'unknown' || !issuesEnabled())
+        return '';
+    const mine = loadLocalIssues().filter((t) => t.status === 'open' && !parseEvalConcern(t.concern) &&
+        (t.by === sessionId || t.replies.some((r) => r.by === sessionId)));
+    if (!mine.length)
+        return '';
+    return `\n\nIssue closeout — ${mine.length} still-open local issue(s) you touched (opened or replied): ${mine.map((t) => t.id).join(', ')}. For each, close it now if its work is finished (\`spex issue close <id>\`), or reply why it should stay open past this session (\`spex issue reply <id> --body "<why>"\`). Some issues rightly outlive their session — this is a reminder to sweep, not a gate.`;
+}
+// ───────────────────────── CLI ─────────────────────────

package/node_modules/@spexcode/spec-cli/dist/login-page.d.ts

@@ -0,0 +1,5 @@
+export declare function loginPage(error?: boolean, opts?: {
+    action?: string;
+    heading?: string;
+    sub?: string;
+}): string;

package/{spec-cli/src/login-page.ts → node_modules/@spexcode/spec-cli/dist/login-page.js}

@@ -5,12 +5,12 @@
 // One page serves every gate: the single-project gateway's /login (the defaults) and the multi-project
 // hub's admin + per-project logins ([[gateway-hub]] passes action/heading/sub). Every option is
 // HTML-escaped at this sink — projectIds are path-derived, attacker-influencable strings.
-export function loginPage(error = false, opts: { action?: string; heading?: string; sub?: string } = {}): string {
-  const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!))
-  const action = esc(opts.action ?? '/login')
-  const heading = esc(opts.heading ?? 'Restricted access')
-  const sub = esc(opts.sub ?? 'This is a private agent workspace. Enter the access password to continue.')
-  return `<!doctype html>
+export function loginPage(error = false, opts = {}) {
+    const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+    const action = esc(opts.action ?? '/login');
+    const heading = esc(opts.heading ?? 'Restricted access');
+    const sub = esc(opts.sub ?? 'This is a private agent workspace. Enter the access password to continue.');
+    return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
@@ -82,5 +82,5 @@ export function loginPage(error = false, opts: { action?: string; heading?: stri
     <div class="foot">Trusted collaborators only.</div>
   </form>
 </body>
-</html>`
+</html>`;
 }

package/node_modules/@spexcode/spec-cli/dist/loop-in.d.ts

@@ -0,0 +1,23 @@
+import { type LoopIn } from './mentions.js';
+import { replyIssue } from './issues.js';
+import { remarkOnHost } from './localIssues.js';
+/** `issue reply` for every store, with the originator loop-in composed on top. */
+export declare function replyIssueWithLoopIn(id: string, body: string, opts?: {
+    author?: string;
+    node?: string | null;
+    evidence?: string[];
+}): Promise<Awaited<ReturnType<typeof replyIssue>> & {
+    loopIn: LoopIn | null;
+}>;
+/** `remark add` on a host, with the same loop-in composed by the same code. */
+export declare function remarkWithLoopIn(host: {
+    issue?: string;
+    node?: string;
+    scenario?: string;
+}, body: string, opts?: {
+    codeSha?: string;
+    author?: string;
+    evidence?: string[];
+}): Promise<Awaited<ReturnType<typeof remarkOnHost>> & {
+    loopIn: LoopIn | null;
+}>;