claude-code-session-manager 0.55.1 → 0.57.0

package/src/main/__tests__/bilkoHostCore.test.cjs

@@ -0,0 +1,72 @@
+// bilkoHostCore.cjs — pure multi-document bundle logic for the "Host on
+// Bilko.run" tab (subpath validation, document-set invariants, path/URL math).
+const assert = require('node:assert/strict');
+const {
+  validateSubpath,
+  validateDocumentSet,
+  documentDistRelPath,
+  documentUrl,
+} = require('../bilkoHostCore.cjs');
+
+test('validateSubpath: "" (root) is always valid', () => {
+  assert.equal(validateSubpath('').ok, true);
+});
+
+test('validateSubpath: accepts lowercase kebab-case, single or multi-segment', () => {
+  assert.equal(validateSubpath('special-doc').ok, true);
+  assert.equal(validateSubpath('special-doc/01').ok, true);
+  assert.equal(validateSubpath('a/b/c').ok, true);
+});
+
+test('validateSubpath: rejects leading/trailing slash', () => {
+  assert.equal(validateSubpath('/foo').ok, false);
+  assert.equal(validateSubpath('foo/').ok, false);
+});
+
+test('validateSubpath: rejects uppercase, spaces, dot-segments', () => {
+  assert.equal(validateSubpath('Foo').ok, false);
+  assert.equal(validateSubpath('foo bar').ok, false);
+  assert.equal(validateSubpath('..').ok, false);
+  assert.equal(validateSubpath('foo/../bar').ok, false);
+});
+
+test('validateSubpath: rejects excessive depth or length', () => {
+  assert.equal(validateSubpath(Array(10).fill('a').join('/')).ok, false);
+  assert.equal(validateSubpath('a'.repeat(300)).ok, false);
+});
+
+test('validateDocumentSet: requires exactly one root document', () => {
+  assert.equal(validateDocumentSet([]).ok, false);
+  assert.equal(validateDocumentSet([{ id: '1', subpath: 'x' }]).ok, false);
+  assert.equal(validateDocumentSet([{ id: '1', subpath: '' }]).ok, true);
+  assert.equal(
+    validateDocumentSet([{ id: '1', subpath: '' }, { id: '2', subpath: '' }]).ok,
+    false,
+  );
+});
+
+test('validateDocumentSet: rejects duplicate subpaths', () => {
+  const res = validateDocumentSet([
+    { id: '1', subpath: '' },
+    { id: '2', subpath: 'doc' },
+    { id: '3', subpath: 'doc' },
+  ]);
+  assert.equal(res.ok, false);
+  assert.match(res.error, /duplicate subpath/);
+});
+
+test('validateDocumentSet: propagates a bad segment error with the document id', () => {
+  const res = validateDocumentSet([{ id: '1', subpath: '' }, { id: 'bad-doc', subpath: 'Not Ok' }]);
+  assert.equal(res.ok, false);
+  assert.match(res.error, /bad-doc/);
+});
+
+test('documentDistRelPath: root -> index.html, sub-path -> <subpath>/index.html', () => {
+  assert.equal(documentDistRelPath(''), 'index.html');
+  assert.equal(documentDistRelPath('special-doc/01'), 'special-doc/01/index.html');
+});
+
+test('documentUrl: root has no sub-path segment, sub-path is nested under the slug', () => {
+  assert.equal(documentUrl('my-app', ''), 'https://bilko.run/projects/my-app/');
+  assert.equal(documentUrl('my-app', 'special-doc/01'), 'https://bilko.run/projects/my-app/special-doc/01/');
+});

package/src/main/__tests__/scheduler-reconcile-history-backfill.test.cjs

@@ -0,0 +1,105 @@
+/**
+ * scheduler-reconcile-history-backfill.test.cjs — regression test for the
+ * bug found 2026-08-02 while investigating why session-manager's own
+ * Scheduler tab showed an empty Queue AND an empty History: a completed
+ * job's PRD `.md` is archived immediately (archiveCompletedPrd, called right
+ * when the job finishes) — long before HISTORY_RETENTION_MS (7 days) would
+ * ever cause queueHistory.partitionJobs to append it to history.jsonl. The
+ * very next reconcile() pass then found the .md gone and silently dropped
+ * the job's row from jobs[] via the "terminal job whose .md is gone was
+ * archived on purpose" branch, without ever writing it to history.jsonl —
+ * total loss of the completed job's record.
+ *
+ * reconcile() must now backfill history.jsonl for exactly this case before
+ * dropping the row.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/scheduler-reconcile-history-backfill.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, afterEach, vi } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const tmpDirs = [];
+
+function makeFixtureCwd() {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-reconcile-history-'));
+  tmpDirs.push(cwd);
+  return cwd;
+}
+
+afterEach(() => {
+  vi.resetModules();
+  while (tmpDirs.length) {
+    const dir = tmpDirs.pop();
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('reconcile() backfills history.jsonl for a completed job whose PRD file is already gone', async () => {
+  const cwd = makeFixtureCwd();
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  fs.mkdirSync(path.join(opsRoot, 'scheduler', 'prds'), { recursive: true });
+  fs.mkdirSync(path.join(opsRoot, 'scheduler', 'state'), { recursive: true });
+
+  const { reconcile } = require('../scheduler.cjs');
+
+  const job = {
+    slug: '999-vanished-prd',
+    title: 'Vanished PRD',
+    cwd,
+    status: 'completed',
+    finishedAt: new Date().toISOString(),
+    exitCode: 0,
+    error: null,
+    runId: 'run-1',
+  };
+  // No matching .md anywhere under prds/ or prds-archived/ for this slug —
+  // simulates the file having already been archived by archiveCompletedPrd
+  // in the same tick the job finished, well before this reconcile() call.
+  const state = { jobs: [job] };
+
+  await reconcile(state);
+
+  expect(state.jobs.find((j) => j.slug === job.slug)).toBeUndefined();
+
+  const historyPath = path.join(opsRoot, 'scheduler', 'state', 'history.jsonl');
+  expect(fs.existsSync(historyPath)).toBe(true);
+  const lines = fs.readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
+  const recorded = lines.map((l) => JSON.parse(l)).find((e) => e.slug === job.slug);
+  expect(recorded).toBeDefined();
+  expect(recorded.status).toBe('completed');
+  expect(recorded.runId).toBe('run-1');
+});
+
+test('reconcile() does not double-write history for a job already recorded there', async () => {
+  const cwd = makeFixtureCwd();
+  const opsRoot = path.join(cwd, 'session-manager-operations');
+  fs.mkdirSync(path.join(opsRoot, 'scheduler', 'prds'), { recursive: true });
+  const stateDir = path.join(opsRoot, 'scheduler', 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+
+  const job = {
+    slug: '998-already-recorded',
+    title: 'Already recorded',
+    cwd,
+    status: 'completed',
+    finishedAt: new Date().toISOString(),
+    exitCode: 0,
+    error: null,
+    runId: 'run-2',
+  };
+  const historyPath = path.join(stateDir, 'history.jsonl');
+  fs.writeFileSync(historyPath, JSON.stringify(job) + '\n', 'utf8');
+
+  const { reconcile } = require('../scheduler.cjs');
+  const state = { jobs: [job] };
+  await reconcile(state);
+
+  const lines = fs.readFileSync(historyPath, 'utf8').trim().split('\n').filter(Boolean);
+  const matches = lines.map((l) => JSON.parse(l)).filter((e) => e.slug === job.slug);
+  expect(matches.length).toBe(1);
+});

package/src/main/agentLibrary.cjs

@@ -42,13 +42,14 @@ const PERSONA_NAME_RE = /^[a-z][a-z0-9-]*$/;
  * assign/remove the relationship from either side. Stored the same
  * comma-list way as `tools` for one parser to cover both.
  */
-function serializePersona({ name, description, tools, model, color, tags, body }) {
+function serializePersona({ name, description, tools, model, color, tags, title, body }) {
   const lines = ['---', `name: ${name}`];
   if (description) lines.push(`description: ${description}`);
   if (tools && tools.length) lines.push(`tools: ${tools.join(', ')}`);
   if (model && model !== 'inherit') lines.push(`model: ${model}`);
   if (color) lines.push(`color: ${color}`);
   if (tags && tags.length) lines.push(`tags: ${tags.join(', ')}`);
+  if (title) lines.push(`title: ${title}`);
   lines.push('---', '');
   return lines.join('\n') + (body || '').trim() + '\n';
 }
@@ -66,6 +67,7 @@ async function savePersona({
   model,
   color,
   tags,
+  title,
   body,
   globalDir = path.join(os.homedir(), '.claude', 'agents'),
   validatePath = configMgr.validatePath,
@@ -75,7 +77,7 @@ async function savePersona({
     throw new Error('agent name must be lowercase, hyphenated (e.g. "my-agent")');
   }
   const target = validatePath(path.join(globalDir, `${name}.md`));
-  const text = serializePersona({ name, description, tools, model, color, tags, body });
+  const text = serializePersona({ name, description, tools, model, color, tags, title, body });
   await writeTextAtomic(target, text);
   if (originalName && originalName !== name) {
     const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));
@@ -201,6 +203,7 @@ async function listPersonas({
       model: fm.model || null,
       color: fm.color || null,
       tags: parseTools(fm.tags),
+      title: fm.title || null,
       path: real,
       body: body.trim(),
       overridingProjects,

package/src/main/bilkoHost.cjs

@@ -0,0 +1,305 @@
+'use strict';
+
+/**
+ * bilkoHost.cjs — Stage A (deterministic bundle prep) for the "Host on
+ * Bilko.run" tab. See session-manager-operations/architecture/
+ * bilko-host-integration.md for the full design.
+ *
+ * Model: ONE Bilko project (slug) hosts a LIST of documents — a root
+ * document (subpath '', dist/index.html — "the project itself") plus any
+ * number of sub-path documents (subpath 'special-doc/01',
+ * dist/special-doc/01/index.html → bilko.run/projects/<slug>/special-doc/01/).
+ * `documents.json` is the list; `dist/` is always rebuilt wholesale from it
+ * (rm + rewrite) so it can never drift from the list — the same "full
+ * replace" semantics Bilko's own publish_static_project already uses, which
+ * is exactly what makes local deletion reliably propagate live (see
+ * bilkoHostCore.cjs's header comment).
+ *
+ * This module owns `session-manager-operations/bilko-host/documents.json` +
+ * `dist/{**,manifest.json}` (writer id `bilko-host`, OWNERS-enforced via
+ * config.cjs's write helpers). It never talks to the bilko-host MCP itself
+ * and never writes publish-state.json — that's Stage B, run by the
+ * bilko-host-publisher Epic's own session with its own Write tool
+ * (agent-authored artifact, same as project-pages/output/*.html; not
+ * enforceable by OWNERS). Directory removal (rm -rf of dist/ before a
+ * rebuild) uses raw fs directly, same precedent as epicMint.cjs/
+ * queueStore.cjs using raw fs for their own owned namespace — this module
+ * IS the declared owner of `bilko-host`, so there is no foreign-writer risk
+ * to guard against here.
+ */
+
+const { ipcMain } = require('electron');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+const { gzipSync } = require('node:zlib');
+const config = require('./config.cjs');
+const {
+  validateSubpath,
+  validateDocumentSet,
+  documentDistRelPath,
+  documentUrl,
+} = require('./bilkoHostCore.cjs');
+
+const WRITER = 'bilko-host';
+const PROJECT_PAGE_LENSES = new Set(['home', 'marketing', 'feature', 'architecture']);
+
+function bilkoHostDir(cwd) {
+  return path.join(cwd, 'session-manager-operations', 'bilko-host');
+}
+
+function distDir(cwd) {
+  return path.join(bilkoHostDir(cwd), 'dist');
+}
+
+function documentsPath(cwd) {
+  return path.join(bilkoHostDir(cwd), 'documents.json');
+}
+
+/** Kebab-case a project name into a slug candidate. Pure. */
+function deriveSlug(projectDirName) {
+  return String(projectDirName)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'project';
+}
+
+function gitInfo(cwd) {
+  const run = (args, fallback) => {
+    try {
+      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+    } catch {
+      return fallback;
+    }
+  };
+  return {
+    gitSha: run(['rev-parse', '--short', 'HEAD'], '0000000'),
+    gitBranch: run(['rev-parse', '--abbrev-ref', 'HEAD'], 'main'),
+  };
+}
+
+async function readDocuments(cwd) {
+  const result = await config.readJson(documentsPath(cwd));
+  if (result.exists && !result.parseError && Array.isArray(result.data?.documents)) {
+    return result.data.documents;
+  }
+  return null;
+}
+
+async function writeDocuments(cwd, documents) {
+  await config.writeJson(documentsPath(cwd), { documents }, { writer: WRITER });
+}
+
+/**
+ * Reads everything the tab needs to render its status card: whether a
+ * Project Page exists to seed a root document from, the project's
+ * package.json (for the compatibility gate + default slug/version), the
+ * current document list, and any bundle/publish state already on disk.
+ */
+async function get({ cwd }) {
+  const realCwd = config.validatePath(cwd);
+
+  const marketingResult = await config.readText(
+    path.join(realCwd, 'session-manager-operations', 'project-pages', 'output', 'marketing.html'),
+  );
+  const pkgResult = await config.readJson(path.join(realCwd, 'package.json'));
+  const pkg = pkgResult.exists && !pkgResult.parseError ? pkgResult.data : null;
+
+  const documents = (await readDocuments(realCwd)) ?? [];
+
+  const bundleManifestResult = await config.readJson(path.join(distDir(realCwd), 'manifest.json'));
+  const bundleManifest = bundleManifestResult.exists && !bundleManifestResult.parseError
+    ? bundleManifestResult.data
+    : null;
+
+  const publishStateResult = await config.readJson(path.join(bilkoHostDir(realCwd), 'publish-state.json'));
+  const publishState = publishStateResult.exists && !publishStateResult.parseError
+    ? publishStateResult.data
+    : null;
+
+  const slug = bundleManifest?.slug
+    ?? deriveSlug(pkg && typeof pkg.name === 'string' ? pkg.name : path.basename(realCwd));
+
+  return {
+    hasMarketingPage: marketingResult.exists,
+    projectName: pkg && typeof pkg.name === 'string' ? pkg.name : path.basename(realCwd),
+    packagePrivate: pkg ? pkg.private === true : false,
+    packageHomepage: pkg && typeof pkg.homepage === 'string' ? pkg.homepage : null,
+    packageVersion: pkg && typeof pkg.version === 'string' ? pkg.version : '0.0.0',
+    defaultSlug: deriveSlug(pkg && typeof pkg.name === 'string' ? pkg.name : path.basename(realCwd)),
+    documents: documents.map((d) => ({ ...d, url: documentUrl(slug, d.subpath) })),
+    // A rebuild is owed whenever the bundle on disk doesn't reflect the
+    // current document list — the tab uses this to gray out "up to date"
+    // vs. prompt "Prepare Bundle" again, and (post-publish) to warn that a
+    // removed document is still live until the next Publish.
+    bundleStale: bundleManifest ? bundleManifest.documentCount !== documents.length : documents.length > 0,
+    bundleManifest,
+    publishState,
+  };
+}
+
+/** Seeds documents.json with a single root document (the Marketing Project Page) if it doesn't exist yet. */
+async function ensureSeededDocuments(cwd) {
+  const existing = await readDocuments(cwd);
+  if (existing) return existing;
+  const seeded = [{
+    id: crypto.randomUUID(),
+    subpath: '',
+    title: 'Project (Marketing)',
+    source: { kind: 'project-page-lens', lens: 'marketing' },
+    addedAt: new Date().toISOString(),
+  }];
+  await writeDocuments(cwd, seeded);
+  return seeded;
+}
+
+/**
+ * Add a hosted document. `source` is either
+ * `{ kind: 'project-page-lens', lens: 'home'|'marketing'|'feature'|'architecture' }`
+ * (reuses an already-generated Project Page lens) or
+ * `{ kind: 'file', path: <repo-relative path> }` (any other local HTML —
+ * e.g. a HUMAN_LEARN page or a hand-authored explainer).
+ */
+async function addDocument({ cwd, subpath, title, source }) {
+  const realCwd = config.validatePath(cwd);
+  const subpathCheck = validateSubpath(subpath);
+  if (!subpathCheck.ok) throw new Error(subpathCheck.error);
+  if (source.kind === 'project-page-lens' && !PROJECT_PAGE_LENSES.has(source.lens)) {
+    throw new Error(`unknown Project Page lens: ${source.lens}`);
+  }
+
+  const documents = (await readDocuments(realCwd)) ?? await ensureSeededDocuments(realCwd);
+  if (subpath === '') {
+    throw new Error('the root document (subpath "") always exists — edit it instead of adding a second one');
+  }
+  if (documents.some((d) => d.subpath === subpath)) {
+    throw new Error(`a document already uses subpath "${subpath}"`);
+  }
+
+  const next = [...documents, {
+    id: crypto.randomUUID(),
+    subpath,
+    title,
+    source,
+    addedAt: new Date().toISOString(),
+  }];
+  const setCheck = validateDocumentSet(next);
+  if (!setCheck.ok) throw new Error(setCheck.error);
+
+  await writeDocuments(realCwd, next);
+  return { documents: next };
+}
+
+/**
+ * Remove a hosted document (never the root). This only updates
+ * documents.json — the file stays in `dist/` (and, if already published,
+ * live on bilko.run) until the next Prepare Bundle + Publish, which is the
+ * confirmed mechanism that actually removes it (Bilko's publish tool
+ * rm -rf's + rebuilds the whole slug directory every publish).
+ */
+async function removeDocument({ cwd, id }) {
+  const realCwd = config.validatePath(cwd);
+  const documents = (await readDocuments(realCwd)) ?? [];
+  const target = documents.find((d) => d.id === id);
+  if (!target) throw new Error(`no document with id ${id}`);
+  if (target.subpath === '') throw new Error('cannot remove the root document');
+
+  const next = documents.filter((d) => d.id !== id);
+  await writeDocuments(realCwd, next);
+  return { documents: next };
+}
+
+async function resolveDocumentHtml(cwd, doc) {
+  if (doc.source.kind === 'project-page-lens') {
+    const result = await config.readText(
+      path.join(cwd, 'session-manager-operations', 'project-pages', 'output', `${doc.source.lens}.html`),
+    );
+    if (!result.exists) {
+      throw new Error(`document "${doc.title}" points at the ${doc.source.lens} Project Page, but it hasn't been generated yet`);
+    }
+    return result.text;
+  }
+  if (doc.source.kind === 'file') {
+    const abs = config.validatePath(path.join(cwd, doc.source.path));
+    const result = await config.readText(abs);
+    if (!result.exists) throw new Error(`document "${doc.title}"'s source file is missing: ${doc.source.path}`);
+    return result.text;
+  }
+  throw new Error(`unknown document source kind: ${doc.source.kind}`);
+}
+
+/**
+ * Stage A: rebuild the ENTIRE dist/ tree from documents.json (rm + rewrite,
+ * mirroring Bilko's own full-replace publish semantics so local state can
+ * never lag the document list) + dist/manifest.json (host-contract manifest
+ * schema, one per bundle — golden.path/expect always point at the root
+ * document). Idempotent.
+ */
+async function prepareBundle({ cwd, slug }) {
+  const realCwd = config.validatePath(cwd);
+  const documents = await ensureSeededDocuments(realCwd);
+
+  const setCheck = validateDocumentSet(documents);
+  if (!setCheck.ok) throw new Error(setCheck.error);
+
+  const pkgResult = await config.readJson(path.join(realCwd, 'package.json'));
+  const pkg = pkgResult.exists && !pkgResult.parseError ? pkgResult.data : {};
+  const version = typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+
+  const dist = distDir(realCwd);
+  await fsp.rm(dist, { recursive: true, force: true });
+
+  let totalGz = 0;
+  for (const doc of documents) {
+    const html = await resolveDocumentHtml(realCwd, doc);
+    const relPath = documentDistRelPath(doc.subpath);
+    await config.writeTextAtomic(path.join(dist, relPath), html, { writer: WRITER });
+    totalGz += gzipSync(Buffer.from(html, 'utf8')).length;
+  }
+
+  const { gitSha, gitBranch } = gitInfo(realCwd);
+  const goldenExpect = pkg && typeof pkg.name === 'string' ? pkg.name : slug;
+
+  const manifest = {
+    schemaVersion: 1,
+    slug,
+    version,
+    builtAt: new Date().toISOString(),
+    gitSha,
+    gitBranch,
+    hostKit: { version: '0.0.0' },
+    golden: { path: `/projects/${slug}/`, expect: goldenExpect },
+    health: {},
+    bundle: { sizeBytesGz: totalGz, fileCount: documents.length },
+    // Not part of the host-contract schema itself — this app's own staleness
+    // check (get()'s bundleStale) compares this against documents.length.
+    documentCount: documents.length,
+    documents: documents.map((d) => ({ subpath: d.subpath, title: d.title })),
+  };
+
+  await config.writeJson(path.join(dist, 'manifest.json'), manifest, { writer: WRITER });
+
+  return { distPath: dist, manifest };
+}
+
+function registerBilkoHostIpc() {
+  const { schemas: s, validated: v } = require('./ipcSchemas.cjs');
+  ipcMain.handle('bilko-host:get', v(s.bilkoHostCwd, get));
+  ipcMain.handle('bilko-host:prepare-bundle', v(s.bilkoHostPrepareBundle, prepareBundle));
+  ipcMain.handle('bilko-host:add-document', v(s.bilkoHostAddDocument, addDocument));
+  ipcMain.handle('bilko-host:remove-document', v(s.bilkoHostRemoveDocument, removeDocument));
+}
+
+module.exports = {
+  registerBilkoHostIpc,
+  get,
+  prepareBundle,
+  addDocument,
+  removeDocument,
+  deriveSlug,
+  bilkoHostDir,
+  distDir,
+};

package/src/main/bilkoHostCore.cjs

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * bilkoHostCore.cjs — pure logic for the "Host on Bilko.run" tab's
+ * multi-document bundle model. No fs/IPC here (that's bilkoHost.cjs) so
+ * this stays unit-testable without a real project directory.
+ *
+ * Model: ONE Bilko project (one registry slug, one `dist/` tree) can host
+ * MANY documents — exactly one root document (subpath `''`, becomes
+ * dist/index.html — "the project itself") plus any number of sub-path
+ * documents (subpath 'special-doc/01', becomes dist/special-doc/01/
+ * index.html → bilko.run/projects/<slug>/special-doc/01/). This mirrors how
+ * Bilko's own publish_static_project already works: it `rm -rf`s then
+ * `cp -r`s the WHOLE public/projects/<slug>/ tree on every publish, so
+ * removing a document locally and re-publishing is guaranteed to remove it
+ * live too — no separate per-document delete API needed on Bilko's side.
+ */
+
+const SUBPATH_SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const MAX_SEGMENTS = 6;
+const MAX_SUBPATH_LENGTH = 200;
+
+/**
+ * Validates a document's subpath. `''` (root) is always valid. Otherwise
+ * every '/'-separated segment must be lowercase kebab-case, no '.'/'..',
+ * no leading/trailing/double slashes, bounded depth and length.
+ */
+function validateSubpath(subpath) {
+  if (typeof subpath !== 'string') return { ok: false, error: 'subpath must be a string' };
+  if (subpath === '') return { ok: true, error: null };
+  if (subpath.length > MAX_SUBPATH_LENGTH) return { ok: false, error: 'subpath is too long' };
+  if (subpath.startsWith('/') || subpath.endsWith('/')) {
+    return { ok: false, error: 'subpath must not start or end with /' };
+  }
+  const segments = subpath.split('/');
+  if (segments.length > MAX_SEGMENTS) return { ok: false, error: `subpath has more than ${MAX_SEGMENTS} segments` };
+  for (const seg of segments) {
+    if (!SUBPATH_SEGMENT.test(seg)) {
+      return { ok: false, error: `invalid subpath segment "${seg}" — use lowercase kebab-case` };
+    }
+  }
+  return { ok: true, error: null };
+}
+
+/**
+ * Validates a full document list: subpaths individually valid, exactly one
+ * root document, no duplicate subpaths. Pure — takes the array shape
+ * documents.json stores, `[{ id, subpath, ... }]`.
+ */
+function validateDocumentSet(documents) {
+  if (!Array.isArray(documents) || documents.length === 0) {
+    return { ok: false, error: 'at least one document (the root) is required' };
+  }
+  const seen = new Set();
+  let rootCount = 0;
+  for (const doc of documents) {
+    const v = validateSubpath(doc.subpath);
+    if (!v.ok) return { ok: false, error: `document "${doc.id}": ${v.error}` };
+    if (seen.has(doc.subpath)) return { ok: false, error: `duplicate subpath "${doc.subpath}"` };
+    seen.add(doc.subpath);
+    if (doc.subpath === '') rootCount += 1;
+  }
+  if (rootCount !== 1) return { ok: false, error: 'exactly one document must have subpath "" (the project root)' };
+  return { ok: true, error: null };
+}
+
+/** Where a document's rendered HTML lands inside dist/. Pure path math. */
+function documentDistRelPath(subpath) {
+  return subpath === '' ? 'index.html' : `${subpath}/index.html`;
+}
+
+/**
+ * The bilko.run URL a document resolves to once published, given the
+ * project's slug. Pure — used by the tab to render "will be live at" links
+ * before anything is actually published.
+ */
+function documentUrl(slug, subpath) {
+  return subpath === '' ? `https://bilko.run/projects/${slug}/` : `https://bilko.run/projects/${slug}/${subpath}/`;
+}
+
+module.exports = {
+  SUBPATH_SEGMENT,
+  MAX_SEGMENTS,
+  MAX_SUBPATH_LENGTH,
+  validateSubpath,
+  validateDocumentSet,
+  documentDistRelPath,
+  documentUrl,
+};

package/src/main/config.cjs

@@ -136,14 +136,6 @@ function validateWrite(realAbs) {
       if (realAbs === browserSub || realAbs.startsWith(browserSub + path.sep)) {
         return;
       }
-      // Feedback inbox writes (scheduler RCA hook — rcaFeedbackHook.cjs — and
-      // any interactive feedback filing): narrowly scoped to
-      // session-manager-operations/feedback/, this repo's existing
-      // per-project intake convention.
-      const feedbackSub = path.join(realRoot, 'session-manager-operations', 'feedback');
-      if (realAbs === feedbackSub || realAbs.startsWith(feedbackSub + path.sep)) {
-        return;
-      }
       // PromptSession persistence (active-index.json + per-session archives,
       // promptSessions.ts) and the scheduler's own read-modify-write of that
       // same active index (promptSessionEvents.cjs, PRD 814) — narrowly
@@ -170,6 +162,14 @@ function validateWrite(realAbs) {
       if (realAbs === briefSub || realAbs.startsWith(briefSub + path.sep)) {
         return;
       }
+      // Host on Bilko.run bundle prep (bilkoHost.cjs's prepareBundle/
+      // addDocument/removeDocument): narrowly scoped to
+      // session-manager-operations/bilko-host/, this repo's existing
+      // per-project artifact-store convention.
+      const bilkoHostSub = path.join(realRoot, 'session-manager-operations', 'bilko-host');
+      if (realAbs === bilkoHostSub || realAbs.startsWith(bilkoHostSub + path.sep)) {
+        return;
+      }
     }
   }
   throw new Error(`Write outside allowed write boundaries: ${realAbs}`);

package/src/main/index.cjs

@@ -62,6 +62,7 @@ const memoryTool = require('./memoryTool.cjs');
 const { registerMemoryAggregateIpc } = require('./memoryAggregate.cjs');
 const { registerProjectBriefIpc } = require('./projectBrief.cjs');
 const { registerProjectPagesIpc } = require('./projectPages.cjs');
+const { registerBilkoHostIpc } = require('./bilkoHost.cjs');
 const promptSessionTranscript = require('./promptSessionTranscript.cjs');
 const agentMemory = require('./agentMemory.cjs');
 const git = require('./git.cjs');
@@ -821,6 +822,7 @@ activeIndexMerge.registerActiveIndexMergeHandlers();
 registerMemoryAggregateIpc();
 registerProjectBriefIpc();
 registerProjectPagesIpc();
+registerBilkoHostIpc();
 ipcMain.handle('promptSessionTranscript:append', validated(schemas.promptSessionTranscriptAppend, async ({ cwd, epicId, role, text, at, eventId }) => {
   const ok = await promptSessionTranscript.appendTurn(cwd, epicId, { role, text, at, eventId });
   return { ok };