@spexcode/spec-cli 0.6.6 → 0.6.8

package/dist/help.js

@@ -38,7 +38,7 @@ The successful receipt names what to read, monitor, and reply on. --ssh uses an
 communication tunnel: its full id anchors the remote project, creation stays parentless and remote, and its
 prompt carries a runnable reply path over that same tunnel.`, ['project-bound']],
         ls: [['spex session ls [SEL…] [--children[=<PARENT-SEL>]] [--status a,b] [--all] [--json]', 'spex session ls --ssh <address> <FULL-SESSION-ID> [--children=<PARENT-SEL>] [--status a,b] [--json]'],
-            'One-shot table of this project\'s live sessions, with each direct parent beside the row. --children scopes it to the caller\'s direct children; --children=<PARENT-SEL> names another parent without changing positional selector grammar. The heading summarizes the displayed scope by status. Shelved sessions ([[archive]]) are hidden; --all includes them, and naming one explicitly always shows it. An explicit id missing from the session list is diagnosed from terminal-close history: closed is a successful answer, while no live, archived, or closed history is a named miss. --ssh uses an existing gateway-to-gateway communication tunnel; its full id anchors one remote project rather than filtering the table, and archive projection stays unavailable on that peer route.', ['selector']],
+            'One-shot table of this project\'s session records, with each direct parent beside the row. --children scopes it to the caller\'s direct children; --children=<PARENT-SEL> names another parent without changing positional selector grammar. The heading summarizes the displayed scope by status. Closed records are hidden from the working projection; --all includes them, and naming one explicitly always shows it. A missing id is a loud record miss. --ssh uses an existing gateway-to-gateway communication tunnel; its full id anchors one remote project rather than filtering the table.', ['selector']],
         resources: ['spex session resources [--json]', 'Read-only host/process ownership, budgets, shared refs, and findings.'],
         files: [['spex session files add <path>', 'spex session files ls', 'spex session files retract <path>'],
             'Publish, list, or withdraw YOUR session’s live file paths. Posting stores an absolute path beside the session record without copying bytes; the dashboard downloads it only when the human clicks.'],
@@ -72,16 +72,14 @@ provably cannot land.`, ['selector', 'project-bound']],
 existing gateway-to-gateway communication tunnel and requires a full session id; live-pane capture stays local.`, ['selector']],
         resume: ['spex session resume <SEL> [--force]', 'Relaunch ONLY if confirmed offline; --force is for a wedged session.', ['selector', 'project-bound']],
         stop: ['spex session stop <SEL>', 'Soft stop: kill the exact agent and KEEP the worktree resumable.', ['selector', 'project-bound']],
-        archive: ['spex session archive <SEL>', 'Cold-archive it: exact leaf/runtime stopped, worktree and conversation kept.', ['selector']],
-        unarchive: ['spex session unarchive <SEL>', 'Deprecated compatibility spelling: same behavior as resume, relaunching the same conversation.', ['selector']],
-        close: [['spex session close <SEL>', 'spex session close --ssh <address> <FULL-SESSION-ID>'], `Retire ANOTHER session — one you dispatched — deleting its worktree, branch and record.
+        close: [['spex session close <SEL>', 'spex session close --ssh <address> <FULL-SESSION-ID>'], `Close ANOTHER session — one you dispatched — after an exact cold stop. Dirty work is committed to refs/spex-archive/<id>; only the worktree is removed. The branch, record, transcript, and conversation remain available to resume.
 <SEL> names that session; it is never \`.\` and never your own id. Closing yourself deletes the worktree
-you are running in, mid-turn. Your own ending is a declaration: \`done --propose close\`. --ssh uses an existing
+you are running in, mid-turn. A live turn is refused; stop it first. Your own ending is a declaration: \`done --propose close\`. --ssh uses an existing
 gateway-to-gateway communication tunnel and requires a full session id.`, ['selector', 'project-bound']],
         quarantine: ['spex session quarantine <ID> --adapter <harness> [--thread <native-id>] --tmux <id> --worktree <absent-path> --branch <absent-branch> [--restore]',
             'Move only an unreadable record after the backend proves every named residue absent. --thread is an adapter-native conversation id, never the SpexCode session id; omit it for Claude. Quarantine and --restore both require the original exact id because corrupt rows are outside selectors.', ['project-bound']],
         done: ['spex session done --propose merge|nothing|close [--note T]',
-            '`merge` declares review: committed work ready for human review, and it is the ONLY declaration that offers a clickable merge. `nothing` is an intended trap: it writes no state and sends the agent to the true merge, close, ask, or park destination. `close` declares close-pending only for settled work: discardable worktree and no outstanding human decision, follow-up, or inspection. The human closes it. This declaration is how a session ends itself; never run `session close` on your own id.'],
+            '`merge` declares review: committed work ready for human review and is the ONLY declaration that offers a clickable merge. `nothing` is an intended trap: it writes no state and sends the agent to the true merge, close, ask, or park destination. `close` declares close-pending only for settled work: discardable worktree and no outstanding human decision, follow-up, or inspection. The human closes it. This declaration is how a session ends itself; never run `session close` on your own id.'],
         park: ['spex session park --note <what-you-await>',
             'Declare parked only when a managed watch delivery or real background task will wake your own session. It self-resumes; waiting for a human is asking, not parked.'],
         ask: ['spex session ask --note <what-you-await>',
@@ -92,7 +90,7 @@ LOCAL-only (fails loud on a remote backend); show --capture and send are non-int
 }
 const SESSION_HELP_GROUPS = [
     { title: 'Manager verbs (dispatch, monitor, land)', verbs: ['new', 'ls', 'resources', 'watch', 'wait', 'review', 'merge', 'reparent'] },
-    { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'archive', 'unarchive', 'close', 'quarantine'] },
+    { title: 'Control another session', verbs: ['send', 'interrupt', 'rename', 'show', 'resume', 'stop', 'close', 'quarantine'] },
     { title: 'Worker verbs (declare YOUR OWN state — a claim the graph and your supervisor act on)', verbs: ['done', 'park', 'ask', 'files', 'web'] },
     { title: 'Human escape hatch', verbs: ['attach'] },
 ];
@@ -150,7 +148,11 @@ Scaffolds adoption in one shot: seeds a starter .spec tree (project root + .plug
 spexcode.json, installs the git hooks, and materializes the harness artifacts (contract block +
 shims). --harness is REQUIRED — the explicit choice of which harnesses materialize delivers into
 (stamped as spexcode.json "harnesses"; only their launchers are seeded); a pre-existing "harnesses"
-field satisfies it. Additive — never overwrites your files. --preset picks the .plugins plugin tier (cumulative).
+field satisfies it; --harness none delivers into NO harness (spec tree + lint + git hooks only, nothing
+written into any agent's config). Additive: it never replaces a file you own — where a harness discovers its
+hooks in your own config (.claude/settings.json, …) only SpexCode's entries are merged in and out, and a
+skill/agent name you already use is skipped and reported rather than overwritten.
+--preset picks the .plugins plugin tier (cumulative).
 Footprint is fixed: materialized artifacts are never tracked — hidden via the per-clone .git/info/exclude, with
 a tracked/mixed CLAUDE.md/AGENTS.md covered by the clean/smudge filter (see spex guide footprint).`,
         see: 'spex guide (the full setup workflow) · spex uninstall (the inverse) · spex spec lint (adoption TODO)',
@@ -473,6 +475,7 @@ Machine plumbing — called by generated hooks and launch scripts, never typed b
   session-state <st> --session <id>   a lifecycle hook authors the session's state
   session-fail  --session <id>        the StopFailure hook marks the session errored
   session-idle  --session <id>        the idle-prompt hook marks an active session idle
+  session-hook-state --session <id>    hook-only canonical lifecycle read (tab-separated)
   commit-gate       the Stop gate's deterministic commit check (exit 0 = ready to declare done)
   hook-prompt <name>                  render canonical model-facing text for a runtime hook
   nudge <node>      the post-merge hook prints the issue nudge for a merged node

package/dist/hook-prompts.js

@@ -58,6 +58,14 @@ const DEFINITIONS = Object.freeze([
         content: NO_PROMPT('session-fail', 'It records a failed governed turn as error.'),
         render: () => '',
     },
+    {
+        name: 'session-listen',
+        title: 'session-listen',
+        description: 'Lifecycle delivery signal; runtime adopter messages are delivered at harness input boundaries.',
+        role: 'signal',
+        content: NO_PROMPT('session-listen', 'It delivers adopter-owned queued messages as runtime context when configured.'),
+        render: () => '',
+    },
     {
         name: 'spec-first',
         title: 'spec-first',

package/dist/host-resources.js

@@ -4,11 +4,12 @@ import { randomUUID } from 'node:crypto';
 import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { defaultHarness, HARNESSES, harnessById, harnessByIdOrNull, sessionIdentityEnvVars } from './harness.js';
-import { listSessionIds, readConfig, readJsonConfig, readPublicRecordEntry, readRawRecord, runtimeRoot } from '@spexcode/spec-core';
+import { listSessionIds, readConfig, readJsonConfig, readPublicRecordEntry, runtimeRoot } from '@spexcode/spec-core';
 import { repoRoot } from '@spexcode/spec-core';
 import { endpointRecordPath } from './host.js';
 import { detachedRuntimeGenerationToken, parseProcStat, processStartToken, verifyDetachedRuntime } from '@spexcode/spec-core';
 import { readBackendInstanceRecords } from './runtime-ownership.js';
+import { configuredSessionApplicationIfCutover } from './session-application.js';
 const DEFAULTS = {
     sessionRssMiB: 1024,
     backendRssMiB: 2048,
@@ -146,20 +147,40 @@ const descendants = (root, procs) => {
 };
 const publicRecordInventory = () => {
     const entries = listSessionIds().map(readPublicRecordEntry);
+    const application = configuredSessionApplicationIfCutover();
     const byId = new Map();
-    for (const entry of entries) {
+    const projected = entries.map((entry) => {
+        if (entry.kind !== 'ok' || !application || !entry.raw.governed)
+            return entry;
+        const state = application.readState(entry.raw.session_id);
+        if (!state)
+            throw new ResourceConflict(`session ${entry.raw.session_id} has no canonical application state after JSON cutover`);
+        return {
+            ...entry,
+            raw: {
+                ...entry.raw,
+                status: state.status,
+                proposal: state.proposal,
+                note: state.note,
+                parent: state.parentSessionId,
+            },
+        };
+    });
+    for (const entry of projected) {
         if (entry.kind === 'ok')
             byId.set(entry.raw.session_id, entry);
         else if (entry.kind === 'corrupt')
             byId.set(entry.sessionId, entry);
     }
     return {
-        entries,
-        records: entries.flatMap((entry) => entry.kind === 'ok' ? [entry.raw] : []),
+        entries: projected,
+        records: projected.flatMap((entry) => entry.kind === 'ok' ? [entry.raw] : []),
         byId,
     };
 };
-const rawRecords = () => listSessionIds().map(readRawRecord).filter((r) => !!r);
+// Resource ownership must use the same lifecycle projection as the board. The raw reader remains for
+// ungoverned/runtime identity discovery, but governed rows come from the canonical inventory above.
+const rawRecords = () => publicRecordInventory().records;
 const runtimePid = (file) => {
     try {
         const pid = Number(readFileSync(file, 'utf8').trim());
@@ -374,9 +395,9 @@ const ownerTotals = (processes) => ({
     cpuPercent: Math.round(processes.reduce((n, p) => n + p.cpuPercent, 0) * 10) / 10,
 });
 const terminal = (rec) => !!rec && rec.status === 'awaiting' && (rec.proposal === 'nothing' || rec.proposal === 'close');
-const probeRuntime = async (descriptor) => {
+const probeRuntime = async (descriptor, referenceIds) => {
     try {
-        return await descriptor.probe();
+        return await descriptor.probe(referenceIds);
     }
     catch (error) {
         return { healthy: false, references: [], error: error.message };
@@ -473,7 +494,7 @@ const sessionStopBlocker = async (id, harnessId, recs = rawRecords(), knownProbe
     }
     return null;
 };
-const probeShared = async (shared) => new Map(await Promise.all([...shared].map(async ([key, entry]) => [key, await probeRuntime(entry.descriptor)])));
+const probeShared = async (shared) => new Map(await Promise.all([...shared].map(async ([key, entry]) => [key, await probeRuntime(entry.descriptor, entry.recs.map((rec) => rec.harness_session_id).filter((id) => !!id))])));
 const sharedFindings = (references, probe) => {
     const findings = [];
     if (!probe.healthy)

package/dist/host.d.ts

@@ -36,6 +36,13 @@ export type ProjectDirectoryListing = {
 };
 export declare function browseProjectDirectories(dir?: string): ProjectDirectoryListing;
 export declare function addKnownProject(dir: string): string;
+export type RemoveProjectResult = {
+    root: string;
+    projectId: string;
+    sessions: number;
+    runtimeRecordRemoved: boolean;
+};
+export declare function removeKnownProject(root: string, confirmation: string): RemoveProjectResult;
 export type ProjectEntry = {
     projectId: string;
     root: string;

package/dist/host.js

@@ -13,6 +13,7 @@ import { MachinePeerGateway } from './machine-peer.js';
 import { DEFAULT_PROJECT_ICON, requireIdentityChoice } from '@spexcode/spec-core/identity';
 import { resolveProjectIdentity, writeGatewayIcon, } from '@spexcode/spec-core';
 import { cliEntrypointArgs } from './tsx-bin.js';
+import { clearProjectPassword } from './gateway-auth.js';
 const here = dirname(fileURLToPath(import.meta.url));
 export const endpointRecordPath = (root) => join(spexcodeHome(), 'projects', encodeProject(root), 'backend.json');
 // atomic publish: tmp + rename, so a reader never sees a torn record (the old write-in-place could be
@@ -174,6 +175,70 @@ function catalogAdd(root) {
         return;
     writeCatalog([...entries, { root, addedAt: new Date().toISOString() }]);
 }
+function activeProjectSessions(root) {
+    const dir = join(spexcodeHome(), 'projects', encodeProject(root), 'sessions');
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return 0;
+    }
+    let active = 0;
+    for (const id of entries) {
+        try {
+            const record = JSON.parse(readFileSync(join(dir, id, 'runtime.json'), 'utf8'));
+            if (record?.archived !== true && record?.stopped !== true && record?.closedAt == null)
+                active++;
+        }
+        catch {
+            // An unreadable record is not safe to classify as inactive. It stays a loud blocker for removal.
+            active++;
+        }
+    }
+    return active;
+}
+export function removeKnownProject(root, confirmation) {
+    const entries = readCatalog();
+    const entry = entries.find((e) => e.root === root);
+    const projectId = encodeProject(root);
+    if (!entry)
+        throw Object.assign(new Error(`project '${projectId}' is not in the catalog`), { status: 404 });
+    const sessions = activeProjectSessions(root);
+    if (sessions)
+        throw Object.assign(new Error(`project has ${sessions} active session record(s); stop or close them before removing the registration`), { status: 409 });
+    const snapshotEntry = snapshot.find((p) => p.root === root);
+    if (snapshotEntry?.online)
+        throw Object.assign(new Error('project backend is online; stop it before removing the registration'), { status: 409 });
+    const expected = `REMOVE ${snapshotEntry?.identity.title || basename(root)}`;
+    if (confirmation !== expected)
+        throw Object.assign(new Error(`confirmation must exactly equal '${expected}'`), { status: 400 });
+    let runtimeRecordRemoved = false;
+    const recordFile = endpointRecordPath(root);
+    const record = readEndpointRecord(recordFile);
+    if (record) {
+        let alive = false;
+        try {
+            process.kill(record.pid, 0);
+            alive = true;
+        }
+        catch { /* no process at that pid */ }
+        if (alive) {
+            throw Object.assign(new Error('backend runtime could not be proven stopped; registration was preserved'), { status: 409 });
+        }
+    }
+    writeCatalog(entries.filter((e) => e.root !== root));
+    clearProjectPassword(projectId);
+    if (record) {
+        try {
+            rmSync(recordFile);
+            runtimeRecordRemoved = true;
+        }
+        catch { /* already gone */ }
+    }
+    snapshot = snapshot.filter((p) => p.root !== root);
+    return { root, projectId, sessions, runtimeRecordRemoved };
+}
 async function fetchInstance(url) {
     const ctrl = new AbortController();
     const t = setTimeout(() => ctrl.abort(), 900);
@@ -515,6 +580,34 @@ export function startHostDashboard(opts) {
                 }
                 return true;
             }
+            const remove = path.match(/^\/projects\/([^/]+)$/);
+            if (remove && req.method === 'DELETE') {
+                const projectId = decodeURIComponent(remove[1]);
+                if (!projectId) {
+                    json(res, 404, { error: 'unknown project' });
+                    return true;
+                }
+                let body = {};
+                try {
+                    body = JSON.parse(await readBody(req) || '{}');
+                }
+                catch { /* validation below is the answer */ }
+                try {
+                    const list = await reconcileNow();
+                    const entry = list.find((p) => p.projectId === projectId);
+                    if (!entry) {
+                        json(res, 404, { error: `unknown project '${projectId}'` });
+                        return true;
+                    }
+                    const removed = removeKnownProject(entry.root, typeof body?.confirmation === 'string' ? body.confirmation : '');
+                    json(res, 200, { ok: true, ...removed });
+                }
+                catch (e) {
+                    const error = e;
+                    json(res, error.status ?? 400, { error: error.message });
+                }
+                return true;
+            }
             if (path === '/projects/icon' && req.method === 'PUT') {
                 let body;
                 try {