@nocville/npc 0.2.0 → 0.2.1

package/README.md

@@ -38,6 +38,31 @@ Prefer a global install? Run `npm i -g @nocville/npc`, then `nocville-npc setup
 When setup runs through `npx`, it copies itself to `~/.config/nocville/runtime/` so the hooks
 keep working after npm clears its cache.
 
+### Choose which sessions appear
+
+By default every agent session publishes to your office. To keep some out, or to show only
+some, edit `~/.config/nocville/sessions.json` (setup creates an empty one):
+
+```json
+{
+  "allow": { "projects": [], "sessions": [] },
+  "deny": { "projects": ["client-*", "~/work/secret"], "sessions": ["*private*"] }
+}
+```
+
+- **Empty lists** (or no file): every session publishes.
+- **`deny` always wins.** If any `allow` entry is set, **only** matching sessions publish.
+- **`projects`**: a folder name anywhere in the session's working directory (`client-*` also
+  covers `~/work/client-acme/api`), or a path containing `/` (`~/work/secret` covers that folder
+  and everything inside it).
+- **`sessions`**: a Claude Code session name (set with `/rename`). Unnamed sessions never match.
+- Patterns are case-insensitive; `*` matches anything, `?` one character.
+
+The file is read on every update, so edits apply to running sessions without reinstalling: a
+session that becomes filtered out leaves the office on its next update. If the file can't be
+parsed, nothing publishes until it's fixed. `npx @nocville/npc sessions` shows the rules and
+checks the current folder (`--project=<dir>`, `--name=<session name>` to test others).
+
 ### Per-agent commands
 
 | Claude Code                          | Codex                                          |

package/dist/cjs/cli.js

@@ -39,6 +39,7 @@ const node_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const config_js_1 = require("./core/config.js");
 const logger_js_1 = require("./core/logger.js");
+const session_filter_js_1 = require("./core/session-filter.js");
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
 // run on every tool call, so they must not pay for loading every NPC (and pngjs).
 const USAGE = `
@@ -56,6 +57,10 @@ Config:
                           Save credentials (prompts for the key if omitted) to ~/.config/nocville/config.json (0600)
                           so no other command needs --api-key
   doctor                  Check API connectivity and a test status push
+  sessions [--project=<dir>] [--name=<session name>]
+                          Show which AI sessions publish to your office
+                          (allow/deny lists in ~/.config/nocville/sessions.json)
+                          and test a folder (default: current) or session name
 
 AI coding agents (one NPC per session, named "Claude · <project>"):
   claude-code setup       Install hooks into ~/.claude/settings.json
@@ -195,6 +200,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'codex') {
@@ -205,6 +212,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'gemini') {
@@ -215,6 +224,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'cursor') {
@@ -225,6 +236,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'init') {
@@ -233,6 +246,12 @@ async function main() {
     }
     if (parsed.command === 'setup') {
         await runSetupAll(parsed.flags);
+        if (!process.exitCode)
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'sessions') {
+        runSessionsCommand(parsed.flags);
         return;
     }
     if (parsed.command === 'uninstall') {
@@ -478,6 +497,38 @@ async function resolveSetupKey(flags) {
     return resolved.source === 'saved' ? undefined : resolved.key;
 }
 /** `setup`: save credentials, then install Claude Code + Codex hooks where present. */
+/** After setup: make sure sessions.json exists and tell the user how to filter sessions. */
+function announceSessionFilter() {
+    const { path, created } = (0, session_filter_js_1.ensureSessionFilterTemplate)();
+    console.log(`\n  Choose which sessions appear in your office: ${created ? 'created' : 'edit'} ${tildify(path)}\n` +
+        '  (allow/deny by project folder or session name; empty = all sessions publish).\n' +
+        '  Check the result with: npx @nocville/npc sessions');
+}
+function tildify(p) {
+    const home = (0, node_os_1.homedir)();
+    return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+/** `nocville-npc sessions`: show the allow/deny rules and test a folder / session name. */
+function runSessionsCommand(flags) {
+    const { path, created } = (0, session_filter_js_1.ensureSessionFilterTemplate)();
+    const filter = (0, session_filter_js_1.loadSessionFilter)(path);
+    console.log(`Session filter: ${tildify(path)}${created ? ' (created an empty template)' : ''}`);
+    if (filter.error) {
+        console.log(`  ✗ ${filter.error}\n  Nothing publishes until the file is fixed.`);
+        process.exitCode = 1;
+        return;
+    }
+    const show = (label, list) => console.log(`  ${label.padEnd(16)} ${list.length ? list.map((p) => JSON.stringify(p)).join(', ') : '(none)'}`);
+    show('allow projects:', filter.allow.projects);
+    show('allow sessions:', filter.allow.sessions);
+    show('deny projects:', filter.deny.projects);
+    show('deny sessions:', filter.deny.sessions);
+    const projectDir = (0, config_js_1.stringFlag)(flags, 'project') ?? process.cwd();
+    const name = (0, config_js_1.stringFlag)(flags, 'name');
+    const verdict = (0, session_filter_js_1.sessionPublishDecision)(filter, { projectDir, name });
+    const subject = `Sessions in ${tildify(projectDir)}${name ? ` named "${name}"` : ''}`;
+    console.log(`\n${verdict.publish ? '✓' : '✗'} ${subject} ${verdict.publish ? 'publish' : 'do NOT publish'} — ${verdict.reason}.`);
+}
 async function runSetupAll(flags) {
     const { setupHooks } = await Promise.resolve().then(() => __importStar(require('./npcs/claude-code/index.js')));
     const { setupCodexHooks } = await Promise.resolve().then(() => __importStar(require('./npcs/codex/index.js')));

package/dist/cjs/core/session-filter.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_FILTER_TEMPLATE = void 0;
+exports.sessionFilterPath = sessionFilterPath;
+exports.loadSessionFilter = loadSessionFilter;
+exports.ensureSessionFilterTemplate = ensureSessionFilterTemplate;
+exports.sessionPublishDecision = sessionPublishDecision;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const user_config_js_1 = require("./user-config.js");
+const EMPTY = { projects: [], sessions: [] };
+exports.SESSION_FILTER_TEMPLATE = {
+    _help: [
+        'Choose which AI agent sessions (Claude Code, Codex, Gemini CLI, Cursor) appear in your Nocville office.',
+        'Leave every list empty to publish all sessions (the default).',
+        'deny always wins. If any allow entry is set, ONLY sessions matching an allow entry publish.',
+        'projects: a folder name anywhere in the session working directory, e.g. "client-*",',
+        '  or a path containing / such as "~/work/secret" (that folder and everything inside it).',
+        'sessions: a Claude Code session name, e.g. "*private*".',
+        'Patterns are case-insensitive; * matches anything, ? one character.',
+        'Changes apply to running sessions on their next update. Check with: npx @nocville/npc sessions',
+    ],
+    allow: { projects: [], sessions: [] },
+    deny: { projects: [], sessions: [] },
+};
+/** `NOCVILLE_SESSIONS_CONFIG` overrides; otherwise `sessions.json` beside config.json. */
+function sessionFilterPath() {
+    return (process.env['NOCVILLE_SESSIONS_CONFIG'] || (0, node_path_1.join)((0, node_path_1.dirname)((0, user_config_js_1.userConfigPath)()), 'sessions.json'));
+}
+function rules(raw, where) {
+    if (raw === undefined || raw === null)
+        return EMPTY;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error(`"${where}" must be an object with "projects" and "sessions" lists`);
+    const list = (key) => {
+        const value = raw[key];
+        if (value === undefined || value === null)
+            return [];
+        if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
+            throw new Error(`"${where}.${key}" must be a list of strings`);
+        return value.map((v) => v.trim()).filter(Boolean);
+    };
+    return { projects: list('projects'), sessions: list('sessions') };
+}
+/** Never throws. A missing file means "publish everything". */
+function loadSessionFilter(path = sessionFilterPath()) {
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { allow: EMPTY, deny: EMPTY };
+        return { allow: EMPTY, deny: EMPTY, error: `can't read ${path}: ${err.message}` };
+    }
+    try {
+        const raw = JSON.parse(text);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error('expected a JSON object with "allow" and "deny"');
+        const obj = raw;
+        return { allow: rules(obj['allow'], 'allow'), deny: rules(obj['deny'], 'deny') };
+    }
+    catch (err) {
+        return { allow: EMPTY, deny: EMPTY, error: `${path}: ${err.message}` };
+    }
+}
+/** Write the commented template if no file exists; returns the path. */
+function ensureSessionFilterTemplate(path = sessionFilterPath()) {
+    if ((0, node_fs_1.existsSync)(path))
+        return { path, created: false };
+    try {
+        const dir = (0, node_path_1.dirname)(path);
+        if (!(0, node_fs_1.existsSync)(dir))
+            (0, node_fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+        (0, node_fs_1.writeFileSync)(path, JSON.stringify(exports.SESSION_FILTER_TEMPLATE, null, 2) + '\n', {
+            encoding: 'utf-8',
+            mode: 0o600,
+            flag: 'wx',
+        });
+        return { path, created: true };
+    }
+    catch {
+        return { path, created: false };
+    }
+}
+const normalizePath = (p) => p.replace(/\\/g, '/').replace(/\/+$/, '');
+function globRegExp(pattern, pathMode) {
+    let src = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                src += '.*';
+                i++;
+            }
+            else
+                src += pathMode ? '[^/]*' : '.*';
+        }
+        else if (c === '?')
+            src += pathMode ? '[^/]' : '.';
+        else
+            src += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${src}$`, 'i');
+}
+function projectMatches(pattern, projectDir) {
+    const dir = normalizePath(projectDir);
+    if (!dir)
+        return false;
+    const isPath = pattern.includes('/') || pattern.includes('\\') || pattern.startsWith('~');
+    if (!isPath) {
+        const re = globRegExp(pattern, false);
+        return dir.split('/').some((segment) => segment && re.test(segment));
+    }
+    const expanded = normalizePath(pattern.startsWith('~') ? (0, node_os_1.homedir)() + pattern.slice(1) : pattern);
+    const re = globRegExp(expanded, true);
+    // The directory itself or any ancestor: a rule for a folder covers its subfolders.
+    for (let p = dir; p; p = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '') {
+        if (re.test(p))
+            return true;
+    }
+    return false;
+}
+function firstMatch(set, who) {
+    for (const p of set.projects)
+        if (projectMatches(p, who.projectDir))
+            return `project "${p}"`;
+    if (who.name)
+        for (const p of set.sessions)
+            if (globRegExp(p, false).test(who.name.trim()))
+                return `session "${p}"`;
+    return null;
+}
+/** Decide whether a session may publish. Pure apart from `homedir()` for `~` patterns. */
+function sessionPublishDecision(filter, who) {
+    if (filter.error)
+        return { publish: false, reason: `sessions.json is invalid (${filter.error})` };
+    const denied = firstMatch(filter.deny, who);
+    if (denied)
+        return { publish: false, reason: `denied by ${denied}` };
+    const hasAllow = filter.allow.projects.length > 0 || filter.allow.sessions.length > 0;
+    if (!hasAllow)
+        return { publish: true, reason: 'no allowlist (all sessions publish)' };
+    const allowed = firstMatch(filter.allow, who);
+    return allowed
+        ? { publish: true, reason: `allowed by ${allowed}` }
+        : { publish: false, reason: 'not on the allowlist' };
+}
+//# sourceMappingURL=session-filter.js.map

package/dist/cjs/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.installGeminiHooksInto = exports.uninstallGeminiHooks = exports.setupGeminiHooks = exports.handleGeminiHookEvent = exports.geminiServiceId = exports.geminiTransition = exports.GEMINI_ADAPTER = exports.GEMINI_DEFAULTS = exports.WebPageWatcherNPC = exports.GitHubWatcherNPC = exports.ReceptionistNPC = exports.LogWatcherNPC = exports.ProcessWatcherNPC = exports.InternetConnectivityNPC = exports.userConfigPath = exports.saveUserConfig = exports.loadUserConfig = exports.redactSecrets = exports.shortPath = exports.shortCommand = exports.describeToolUse = exports.CodexWatcher = exports.parseRolloutLine = exports.uninstallCodexHooks = exports.setupCodexHooks = exports.codexTransition = exports.handleCodexHookEvent = exports.handleCodexCommand = exports.claudeTransition = exports.processHookEvent = exports.uninstallHooks = exports.setupHooks = exports.handleHookEvent = exports.handleClaudeCodeCommand = exports.ClaudeCodeNPC = exports.SystemMonitorNPC = exports.pushHistory = exports.statusColor = exports.truncate = exports.worstStatus = exports.evaluateThreshold = exports.numberFlag = exports.boolFlag = exports.stringFlag = exports.resolveConfig = exports.parseArgs = exports.Logger = exports.EventNPC = exports.PollingNPC = exports.BaseNPC = void 0;
-exports.normalizeCursorEvent = exports.isCursorInvocation = exports.CURSOR_HOOK_EVENTS = exports.installCursorHooksInto = exports.uninstallCursorHooks = exports.setupCursorHooks = exports.handleCursorHookEvent = exports.cursorServiceId = exports.CURSOR_ADAPTER = exports.CURSOR_DEFAULTS = exports.GEMINI_HOOK_EVENTS = void 0;
+exports.geminiServiceId = exports.geminiTransition = exports.GEMINI_ADAPTER = exports.GEMINI_DEFAULTS = exports.WebPageWatcherNPC = exports.GitHubWatcherNPC = exports.ReceptionistNPC = exports.LogWatcherNPC = exports.ProcessWatcherNPC = exports.InternetConnectivityNPC = exports.ensureSessionFilterTemplate = exports.sessionPublishDecision = exports.sessionFilterPath = exports.loadSessionFilter = exports.userConfigPath = exports.saveUserConfig = exports.loadUserConfig = exports.redactSecrets = exports.shortPath = exports.shortCommand = exports.describeToolUse = exports.CodexWatcher = exports.parseRolloutLine = exports.uninstallCodexHooks = exports.setupCodexHooks = exports.codexTransition = exports.handleCodexHookEvent = exports.handleCodexCommand = exports.claudeTransition = exports.processHookEvent = exports.uninstallHooks = exports.setupHooks = exports.handleHookEvent = exports.handleClaudeCodeCommand = exports.ClaudeCodeNPC = exports.SystemMonitorNPC = exports.pushHistory = exports.statusColor = exports.truncate = exports.worstStatus = exports.evaluateThreshold = exports.numberFlag = exports.boolFlag = exports.stringFlag = exports.resolveConfig = exports.parseArgs = exports.Logger = exports.EventNPC = exports.PollingNPC = exports.BaseNPC = void 0;
+exports.normalizeCursorEvent = exports.isCursorInvocation = exports.CURSOR_HOOK_EVENTS = exports.installCursorHooksInto = exports.uninstallCursorHooks = exports.setupCursorHooks = exports.handleCursorHookEvent = exports.cursorServiceId = exports.CURSOR_ADAPTER = exports.CURSOR_DEFAULTS = exports.GEMINI_HOOK_EVENTS = exports.installGeminiHooksInto = exports.uninstallGeminiHooks = exports.setupGeminiHooks = exports.handleGeminiHookEvent = void 0;
 // Core
 var base_npc_js_1 = require("./core/base-npc.js");
 Object.defineProperty(exports, "BaseNPC", { enumerable: true, get: function () { return base_npc_js_1.BaseNPC; } });
@@ -53,6 +53,11 @@ var user_config_js_1 = require("./core/user-config.js");
 Object.defineProperty(exports, "loadUserConfig", { enumerable: true, get: function () { return user_config_js_1.loadUserConfig; } });
 Object.defineProperty(exports, "saveUserConfig", { enumerable: true, get: function () { return user_config_js_1.saveUserConfig; } });
 Object.defineProperty(exports, "userConfigPath", { enumerable: true, get: function () { return user_config_js_1.userConfigPath; } });
+var session_filter_js_1 = require("./core/session-filter.js");
+Object.defineProperty(exports, "loadSessionFilter", { enumerable: true, get: function () { return session_filter_js_1.loadSessionFilter; } });
+Object.defineProperty(exports, "sessionFilterPath", { enumerable: true, get: function () { return session_filter_js_1.sessionFilterPath; } });
+Object.defineProperty(exports, "sessionPublishDecision", { enumerable: true, get: function () { return session_filter_js_1.sessionPublishDecision; } });
+Object.defineProperty(exports, "ensureSessionFilterTemplate", { enumerable: true, get: function () { return session_filter_js_1.ensureSessionFilterTemplate; } });
 var index_js_4 = require("./npcs/internet-connectivity/index.js");
 Object.defineProperty(exports, "InternetConnectivityNPC", { enumerable: true, get: function () { return index_js_4.InternetConnectivityNPC; } });
 var index_js_5 = require("./npcs/process-watcher/index.js");

package/dist/cjs/npcs/agent-common/session.js

@@ -24,6 +24,7 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_1 = require("@nocville/node");
+const session_filter_js_1 = require("../../core/session-filter.js");
 const text_js_1 = require("../../core/text.js");
 const lock_js_1 = require("./lock.js");
 /** Behavior hints + subStatus for a phase (shared by every agent NPC). */
@@ -285,6 +286,25 @@ async function flushSession(adapter, config, sessionId, deps = {}) {
             if (!state || !config.apiKey || state.offlineDeliveryStopped)
                 return false;
             const rev = state.rev ?? 0;
+            const verdict = (0, session_filter_js_1.sessionPublishDecision)(deps.sessionFilter ?? (0, session_filter_js_1.loadSessionFilter)(), {
+                projectDir: state.projectDir,
+                name: state.name,
+            });
+            // Filtered out (sessions.json). Never shown: consume the revision so nothing retries.
+            // Already shown (e.g. renamed into the denylist): despawn it once, then go quiet.
+            // Checked on every push, so later edits to the file take effect without reinstalling.
+            if (!verdict.publish && !state.published) {
+                await (0, lock_js_1.withStateLock)(path, () => {
+                    const fresh = readSessionState(adapter.stateDir, sessionId);
+                    if (!fresh)
+                        return;
+                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, fresh.rev ?? 0);
+                    fresh.flushAt = undefined;
+                    writeSessionState(adapter.stateDir, fresh);
+                }, deps.lockWaitMs);
+                return true;
+            }
+            const despawnFiltered = !verdict.publish;
             if (!deps.force && rev <= (state.pushedRev ?? 0)) {
                 await (0, lock_js_1.withStateLock)(path, () => {
                     const fresh = readSessionState(adapter.stateDir, sessionId);
@@ -299,7 +319,8 @@ async function flushSession(adapter, config, sessionId, deps = {}) {
                 ((sid, payload) => defaultPush(config, sid, payload, deps.timeoutMs ?? 4000));
             let ok = false;
             try {
-                const result = await push(state.serviceId, buildAgentPayload(adapter, state, config));
+                const shown = despawnFiltered ? { ...state, offline: true } : state;
+                const result = await push(state.serviceId, buildAgentPayload(adapter, shown, config));
                 ok = result.success;
                 deps.onResult?.(result);
             }
@@ -312,8 +333,9 @@ async function flushSession(adapter, config, sessionId, deps = {}) {
                     return;
                 // Retain terminal state until cleanup so late hooks/watchers cannot revive it.
                 if (ok) {
-                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, rev);
+                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, despawnFiltered ? (fresh.rev ?? 0) : rev);
                     fresh.lastPushAt = Date.now();
+                    fresh.published = !despawnFiltered && !state.offline;
                 }
                 if (!fresh.flushAt || fresh.flushAt <= Date.now())
                     fresh.flushAt = undefined;

package/dist/cjs/npcs/codex/watcher.js

@@ -6,6 +6,7 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_1 = require("@nocville/node");
 const logger_js_1 = require("../../core/logger.js");
+const session_filter_js_1 = require("../../core/session-filter.js");
 const session_js_1 = require("../agent-common/session.js");
 const defaults_js_1 = require("./defaults.js");
 const hook_handler_js_1 = require("./hook-handler.js");
@@ -296,6 +297,20 @@ class CodexWatcher {
             s.pushedRev = rev;
             return;
         }
+        const verdict = (0, session_filter_js_1.sessionPublishDecision)(this.opts.sessionFilter ?? (0, session_filter_js_1.loadSessionFilter)(), {
+            projectDir: s.state.projectDir,
+            name: s.state.name,
+        });
+        if (!verdict.publish) {
+            // Filtered out by sessions.json: never show it, and remove it if it was showing.
+            s.pushedRev = rev;
+            if (s.spawned) {
+                s.spawned = false;
+                const offline = { ...s.state, offline: true };
+                await this.send(s.state.serviceId, (0, session_js_1.buildAgentPayload)(hook_handler_js_1.CODEX_ADAPTER, offline, this.config));
+            }
+            return;
+        }
         const now = this.now();
         if (s.spawned && now - s.lastPushAt < this.minPushGapMs) {
             // Coalesce; the next tick after the gap pushes the latest state.
@@ -307,7 +322,7 @@ class CodexWatcher {
         await this.send(s.state.serviceId, (0, session_js_1.buildAgentPayload)(hook_handler_js_1.CODEX_ADAPTER, s.state, this.config));
     }
     async despawn(s) {
-        if (this.hooksOwn(s.state.sessionId))
+        if (this.hooksOwn(s.state.sessionId) || !s.spawned)
             return;
         const offline = { ...s.state, offline: true };
         await this.send(s.state.serviceId, (0, session_js_1.buildAgentPayload)(hook_handler_js_1.CODEX_ADAPTER, offline, this.config));

package/dist/cli.js

@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { parseArgs, resolveConfig, stringFlag, numberFlag, boolFlag } from './core/config.js';
 import { Logger } from './core/logger.js';
+import { ensureSessionFilterTemplate, loadSessionFilter, sessionPublishDecision, } from './core/session-filter.js';
 // NPC modules are imported lazily per command: `claude-code hook` / `codex hook`
 // run on every tool call, so they must not pay for loading every NPC (and pngjs).
 const USAGE = `
@@ -21,6 +22,10 @@ Config:
                           Save credentials (prompts for the key if omitted) to ~/.config/nocville/config.json (0600)
                           so no other command needs --api-key
   doctor                  Check API connectivity and a test status push
+  sessions [--project=<dir>] [--name=<session name>]
+                          Show which AI sessions publish to your office
+                          (allow/deny lists in ~/.config/nocville/sessions.json)
+                          and test a folder (default: current) or session name
 
 AI coding agents (one NPC per session, named "Claude · <project>"):
   claude-code setup       Install hooks into ~/.claude/settings.json
@@ -160,6 +165,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'codex') {
@@ -170,6 +177,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'gemini') {
@@ -180,6 +189,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'cursor') {
@@ -190,6 +201,8 @@ async function main() {
             flags: parsed.flags,
             args: parsed.args,
         });
+        if (parsed.subcommand === 'setup' && !parsed.flags['uninstall'])
+            announceSessionFilter();
         return;
     }
     if (parsed.command === 'init') {
@@ -198,6 +211,12 @@ async function main() {
     }
     if (parsed.command === 'setup') {
         await runSetupAll(parsed.flags);
+        if (!process.exitCode)
+            announceSessionFilter();
+        return;
+    }
+    if (parsed.command === 'sessions') {
+        runSessionsCommand(parsed.flags);
         return;
     }
     if (parsed.command === 'uninstall') {
@@ -443,6 +462,38 @@ async function resolveSetupKey(flags) {
     return resolved.source === 'saved' ? undefined : resolved.key;
 }
 /** `setup`: save credentials, then install Claude Code + Codex hooks where present. */
+/** After setup: make sure sessions.json exists and tell the user how to filter sessions. */
+function announceSessionFilter() {
+    const { path, created } = ensureSessionFilterTemplate();
+    console.log(`\n  Choose which sessions appear in your office: ${created ? 'created' : 'edit'} ${tildify(path)}\n` +
+        '  (allow/deny by project folder or session name; empty = all sessions publish).\n' +
+        '  Check the result with: npx @nocville/npc sessions');
+}
+function tildify(p) {
+    const home = homedir();
+    return p.startsWith(home) ? '~' + p.slice(home.length) : p;
+}
+/** `nocville-npc sessions`: show the allow/deny rules and test a folder / session name. */
+function runSessionsCommand(flags) {
+    const { path, created } = ensureSessionFilterTemplate();
+    const filter = loadSessionFilter(path);
+    console.log(`Session filter: ${tildify(path)}${created ? ' (created an empty template)' : ''}`);
+    if (filter.error) {
+        console.log(`  ✗ ${filter.error}\n  Nothing publishes until the file is fixed.`);
+        process.exitCode = 1;
+        return;
+    }
+    const show = (label, list) => console.log(`  ${label.padEnd(16)} ${list.length ? list.map((p) => JSON.stringify(p)).join(', ') : '(none)'}`);
+    show('allow projects:', filter.allow.projects);
+    show('allow sessions:', filter.allow.sessions);
+    show('deny projects:', filter.deny.projects);
+    show('deny sessions:', filter.deny.sessions);
+    const projectDir = stringFlag(flags, 'project') ?? process.cwd();
+    const name = stringFlag(flags, 'name');
+    const verdict = sessionPublishDecision(filter, { projectDir, name });
+    const subject = `Sessions in ${tildify(projectDir)}${name ? ` named "${name}"` : ''}`;
+    console.log(`\n${verdict.publish ? '✓' : '✗'} ${subject} ${verdict.publish ? 'publish' : 'do NOT publish'} — ${verdict.reason}.`);
+}
 async function runSetupAll(flags) {
     const { setupHooks } = await import('./npcs/claude-code/index.js');
     const { setupCodexHooks } = await import('./npcs/codex/index.js');

package/dist/core/session-filter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Which AI-agent sessions publish to the office (`~/.config/nocville/sessions.json`).
+ *
+ * - Empty lists (or no file): every session publishes — the default.
+ * - `deny` always wins.
+ * - If `allow` has any entry, only sessions matching one of them publish.
+ *
+ * Patterns are case-insensitive globs (`*` any run of characters, `?` one character).
+ * A `projects` pattern without a slash matches any folder name on the session's working
+ * directory path (so `client-*` also covers `~/work/client-acme/api`); with a slash (or a
+ * leading `~`) it matches that directory or anything inside it (`~/work/secret`,
+ * `~/work/*`). A `sessions` pattern matches the agent's session name (Claude Code's
+ * session title); sessions without a name never match it.
+ *
+ * Read on every push, so edits apply to running sessions without reinstalling hooks.
+ */
+export interface SessionRules {
+    projects: string[];
+    sessions: string[];
+}
+export interface SessionFilter {
+    allow: SessionRules;
+    deny: SessionRules;
+    /** Set when the file exists but can't be used; nothing publishes until it's fixed. */
+    error?: string;
+}
+export interface SessionIdentity {
+    /** The session's working directory. */
+    projectDir: string;
+    /** Session name/title, when the agent has one. */
+    name?: string;
+}
+export interface PublishDecision {
+    publish: boolean;
+    reason: string;
+}
+export declare const SESSION_FILTER_TEMPLATE: {
+    _help: string[];
+    allow: {
+        projects: never[];
+        sessions: never[];
+    };
+    deny: {
+        projects: never[];
+        sessions: never[];
+    };
+};
+/** `NOCVILLE_SESSIONS_CONFIG` overrides; otherwise `sessions.json` beside config.json. */
+export declare function sessionFilterPath(): string;
+/** Never throws. A missing file means "publish everything". */
+export declare function loadSessionFilter(path?: string): SessionFilter;
+/** Write the commented template if no file exists; returns the path. */
+export declare function ensureSessionFilterTemplate(path?: string): {
+    path: string;
+    created: boolean;
+};
+/** Decide whether a session may publish. Pure apart from `homedir()` for `~` patterns. */
+export declare function sessionPublishDecision(filter: SessionFilter, who: SessionIdentity): PublishDecision;
+//# sourceMappingURL=session-filter.d.ts.map

package/dist/core/session-filter.js

@@ -0,0 +1,143 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { userConfigPath } from './user-config.js';
+const EMPTY = { projects: [], sessions: [] };
+export const SESSION_FILTER_TEMPLATE = {
+    _help: [
+        'Choose which AI agent sessions (Claude Code, Codex, Gemini CLI, Cursor) appear in your Nocville office.',
+        'Leave every list empty to publish all sessions (the default).',
+        'deny always wins. If any allow entry is set, ONLY sessions matching an allow entry publish.',
+        'projects: a folder name anywhere in the session working directory, e.g. "client-*",',
+        '  or a path containing / such as "~/work/secret" (that folder and everything inside it).',
+        'sessions: a Claude Code session name, e.g. "*private*".',
+        'Patterns are case-insensitive; * matches anything, ? one character.',
+        'Changes apply to running sessions on their next update. Check with: npx @nocville/npc sessions',
+    ],
+    allow: { projects: [], sessions: [] },
+    deny: { projects: [], sessions: [] },
+};
+/** `NOCVILLE_SESSIONS_CONFIG` overrides; otherwise `sessions.json` beside config.json. */
+export function sessionFilterPath() {
+    return (process.env['NOCVILLE_SESSIONS_CONFIG'] || join(dirname(userConfigPath()), 'sessions.json'));
+}
+function rules(raw, where) {
+    if (raw === undefined || raw === null)
+        return EMPTY;
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        throw new Error(`"${where}" must be an object with "projects" and "sessions" lists`);
+    const list = (key) => {
+        const value = raw[key];
+        if (value === undefined || value === null)
+            return [];
+        if (!Array.isArray(value) || value.some((v) => typeof v !== 'string'))
+            throw new Error(`"${where}.${key}" must be a list of strings`);
+        return value.map((v) => v.trim()).filter(Boolean);
+    };
+    return { projects: list('projects'), sessions: list('sessions') };
+}
+/** Never throws. A missing file means "publish everything". */
+export function loadSessionFilter(path = sessionFilterPath()) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { allow: EMPTY, deny: EMPTY };
+        return { allow: EMPTY, deny: EMPTY, error: `can't read ${path}: ${err.message}` };
+    }
+    try {
+        const raw = JSON.parse(text);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error('expected a JSON object with "allow" and "deny"');
+        const obj = raw;
+        return { allow: rules(obj['allow'], 'allow'), deny: rules(obj['deny'], 'deny') };
+    }
+    catch (err) {
+        return { allow: EMPTY, deny: EMPTY, error: `${path}: ${err.message}` };
+    }
+}
+/** Write the commented template if no file exists; returns the path. */
+export function ensureSessionFilterTemplate(path = sessionFilterPath()) {
+    if (existsSync(path))
+        return { path, created: false };
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(path, JSON.stringify(SESSION_FILTER_TEMPLATE, null, 2) + '\n', {
+            encoding: 'utf-8',
+            mode: 0o600,
+            flag: 'wx',
+        });
+        return { path, created: true };
+    }
+    catch {
+        return { path, created: false };
+    }
+}
+const normalizePath = (p) => p.replace(/\\/g, '/').replace(/\/+$/, '');
+function globRegExp(pattern, pathMode) {
+    let src = '';
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === '*') {
+            if (pattern[i + 1] === '*') {
+                src += '.*';
+                i++;
+            }
+            else
+                src += pathMode ? '[^/]*' : '.*';
+        }
+        else if (c === '?')
+            src += pathMode ? '[^/]' : '.';
+        else
+            src += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${src}$`, 'i');
+}
+function projectMatches(pattern, projectDir) {
+    const dir = normalizePath(projectDir);
+    if (!dir)
+        return false;
+    const isPath = pattern.includes('/') || pattern.includes('\\') || pattern.startsWith('~');
+    if (!isPath) {
+        const re = globRegExp(pattern, false);
+        return dir.split('/').some((segment) => segment && re.test(segment));
+    }
+    const expanded = normalizePath(pattern.startsWith('~') ? homedir() + pattern.slice(1) : pattern);
+    const re = globRegExp(expanded, true);
+    // The directory itself or any ancestor: a rule for a folder covers its subfolders.
+    for (let p = dir; p; p = p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '') {
+        if (re.test(p))
+            return true;
+    }
+    return false;
+}
+function firstMatch(set, who) {
+    for (const p of set.projects)
+        if (projectMatches(p, who.projectDir))
+            return `project "${p}"`;
+    if (who.name)
+        for (const p of set.sessions)
+            if (globRegExp(p, false).test(who.name.trim()))
+                return `session "${p}"`;
+    return null;
+}
+/** Decide whether a session may publish. Pure apart from `homedir()` for `~` patterns. */
+export function sessionPublishDecision(filter, who) {
+    if (filter.error)
+        return { publish: false, reason: `sessions.json is invalid (${filter.error})` };
+    const denied = firstMatch(filter.deny, who);
+    if (denied)
+        return { publish: false, reason: `denied by ${denied}` };
+    const hasAllow = filter.allow.projects.length > 0 || filter.allow.sessions.length > 0;
+    if (!hasAllow)
+        return { publish: true, reason: 'no allowlist (all sessions publish)' };
+    const allowed = firstMatch(filter.allow, who);
+    return allowed
+        ? { publish: true, reason: `allowed by ${allowed}` }
+        : { publish: false, reason: 'not on the allowlist' };
+}
+//# sourceMappingURL=session-filter.js.map

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export { handleCodexCommand, handleCodexHookEvent, codexTransition, setupCodexHo
 export type { CodexSetupOptions, CodexWatcherOptions, RolloutSignal } from './npcs/codex/index.js';
 export { describeToolUse, shortCommand, shortPath, redactSecrets, } from './npcs/agent-common/activity.js';
 export { loadUserConfig, saveUserConfig, userConfigPath } from './core/user-config.js';
+export { loadSessionFilter, sessionFilterPath, sessionPublishDecision, ensureSessionFilterTemplate, } from './core/session-filter.js';
+export type { SessionFilter, SessionRules, PublishDecision } from './core/session-filter.js';
 export type { UserConfig } from './core/user-config.js';
 export { InternetConnectivityNPC } from './npcs/internet-connectivity/index.js';
 export type { InternetConnectivityConfig } from './npcs/internet-connectivity/index.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export { ClaudeCodeNPC, handleClaudeCodeCommand, handleHookEvent, setupHooks, un
 export { handleCodexCommand, handleCodexHookEvent, codexTransition, setupCodexHooks, uninstallCodexHooks, parseRolloutLine, CodexWatcher, } from './npcs/codex/index.js';
 export { describeToolUse, shortCommand, shortPath, redactSecrets, } from './npcs/agent-common/activity.js';
 export { loadUserConfig, saveUserConfig, userConfigPath } from './core/user-config.js';
+export { loadSessionFilter, sessionFilterPath, sessionPublishDecision, ensureSessionFilterTemplate, } from './core/session-filter.js';
 export { InternetConnectivityNPC } from './npcs/internet-connectivity/index.js';
 export { ProcessWatcherNPC } from './npcs/process-watcher/index.js';
 export { LogWatcherNPC } from './npcs/log-watcher/index.js';

package/dist/npcs/agent-common/session.d.ts

@@ -1,4 +1,5 @@
 import type { StatusUpdate, AgentStats } from '@nocville/node';
+import { type SessionFilter } from '../../core/session-filter.js';
 import type { NpcConfig, Status, Mood, BehaviorHints } from '../../core/types.js';
 /**
  * Shared session plumbing for hook-driven AI-agent NPCs (Claude Code, Codex).
@@ -54,6 +55,11 @@ export interface AgentSessionState {
     mood?: Mood;
     /** Offline sentinel pending push (session ended). */
     offline?: boolean;
+    /**
+     * The office currently shows this session (last delivered push was not offline). Lets a
+     * session that becomes filtered out (sessions.json) despawn once instead of lingering.
+     */
+    published?: boolean;
     /** Monotonic revision bumped on every applied change. */
     rev?: number;
     /** Revision last pushed successfully. */
@@ -163,6 +169,8 @@ export interface PushDeps {
     timeoutMs?: number;
     force?: boolean;
     lockWaitMs?: number;
+    /** Override sessions.json (tests). */
+    sessionFilter?: SessionFilter;
 }
 /**
  * Push the session's current state if it has unpushed changes (or is offline),

package/dist/npcs/agent-common/session.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { join } from 'node:path';
 import { NocvilleClient } from '@nocville/node';
+import { loadSessionFilter, sessionPublishDecision, } from '../../core/session-filter.js';
 import { truncate } from '../../core/text.js';
 import { withStateLock } from './lock.js';
 /** Behavior hints + subStatus for a phase (shared by every agent NPC). */
@@ -263,6 +264,25 @@ export async function flushSession(adapter, config, sessionId, deps = {}) {
             if (!state || !config.apiKey || state.offlineDeliveryStopped)
                 return false;
             const rev = state.rev ?? 0;
+            const verdict = sessionPublishDecision(deps.sessionFilter ?? loadSessionFilter(), {
+                projectDir: state.projectDir,
+                name: state.name,
+            });
+            // Filtered out (sessions.json). Never shown: consume the revision so nothing retries.
+            // Already shown (e.g. renamed into the denylist): despawn it once, then go quiet.
+            // Checked on every push, so later edits to the file take effect without reinstalling.
+            if (!verdict.publish && !state.published) {
+                await withStateLock(path, () => {
+                    const fresh = readSessionState(adapter.stateDir, sessionId);
+                    if (!fresh)
+                        return;
+                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, fresh.rev ?? 0);
+                    fresh.flushAt = undefined;
+                    writeSessionState(adapter.stateDir, fresh);
+                }, deps.lockWaitMs);
+                return true;
+            }
+            const despawnFiltered = !verdict.publish;
             if (!deps.force && rev <= (state.pushedRev ?? 0)) {
                 await withStateLock(path, () => {
                     const fresh = readSessionState(adapter.stateDir, sessionId);
@@ -277,7 +297,8 @@ export async function flushSession(adapter, config, sessionId, deps = {}) {
                 ((sid, payload) => defaultPush(config, sid, payload, deps.timeoutMs ?? 4000));
             let ok = false;
             try {
-                const result = await push(state.serviceId, buildAgentPayload(adapter, state, config));
+                const shown = despawnFiltered ? { ...state, offline: true } : state;
+                const result = await push(state.serviceId, buildAgentPayload(adapter, shown, config));
                 ok = result.success;
                 deps.onResult?.(result);
             }
@@ -290,8 +311,9 @@ export async function flushSession(adapter, config, sessionId, deps = {}) {
                     return;
                 // Retain terminal state until cleanup so late hooks/watchers cannot revive it.
                 if (ok) {
-                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, rev);
+                    fresh.pushedRev = Math.max(fresh.pushedRev ?? 0, despawnFiltered ? (fresh.rev ?? 0) : rev);
                     fresh.lastPushAt = Date.now();
+                    fresh.published = !despawnFiltered && !state.offline;
                 }
                 if (!fresh.flushAt || fresh.flushAt <= Date.now())
                     fresh.flushAt = undefined;

package/dist/npcs/codex/watcher.d.ts

@@ -1,4 +1,5 @@
 import type { StatusUpdate } from '@nocville/node';
+import { type SessionFilter } from '../../core/session-filter.js';
 import type { NpcConfig } from '../../core/types.js';
 import type { AgentSessionState } from '../agent-common/session.js';
 /**
@@ -25,6 +26,8 @@ export interface CodexWatcherOptions {
     now?: () => number;
     /** Hook state dir consulted for hook ownership (tests). */
     hookStateDir?: string;
+    /** Override sessions.json (tests). */
+    sessionFilter?: SessionFilter;
 }
 /** Day directories to scan: today and yesterday (local time, like Codex). */
 export declare function recentDayDirs(root: string, now: number): string[];

package/dist/npcs/codex/watcher.js

@@ -2,6 +2,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readSync, readdirSync, stat
 import { join } from 'node:path';
 import { NocvilleClient } from '@nocville/node';
 import { Logger } from '../../core/logger.js';
+import { loadSessionFilter, sessionPublishDecision, } from '../../core/session-filter.js';
 import { buildAgentPayload, pushHistory, stateFilePath } from '../agent-common/session.js';
 import { CODEX_DEFAULTS } from './defaults.js';
 import { CODEX_ADAPTER, codexServiceId } from './hook-handler.js';
@@ -292,6 +293,20 @@ export class CodexWatcher {
             s.pushedRev = rev;
             return;
         }
+        const verdict = sessionPublishDecision(this.opts.sessionFilter ?? loadSessionFilter(), {
+            projectDir: s.state.projectDir,
+            name: s.state.name,
+        });
+        if (!verdict.publish) {
+            // Filtered out by sessions.json: never show it, and remove it if it was showing.
+            s.pushedRev = rev;
+            if (s.spawned) {
+                s.spawned = false;
+                const offline = { ...s.state, offline: true };
+                await this.send(s.state.serviceId, buildAgentPayload(CODEX_ADAPTER, offline, this.config));
+            }
+            return;
+        }
         const now = this.now();
         if (s.spawned && now - s.lastPushAt < this.minPushGapMs) {
             // Coalesce; the next tick after the gap pushes the latest state.
@@ -303,7 +318,7 @@ export class CodexWatcher {
         await this.send(s.state.serviceId, buildAgentPayload(CODEX_ADAPTER, s.state, this.config));
     }
     async despawn(s) {
-        if (this.hooksOwn(s.state.sessionId))
+        if (this.hooksOwn(s.state.sessionId) || !s.spawned)
             return;
         const offline = { ...s.state, offline: true };
         await this.send(s.state.serviceId, buildAgentPayload(CODEX_ADAPTER, offline, this.config));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocville/npc",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Put your Claude Code and Codex sessions (and your servers) in the Nocville office as live NPCs",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,7 @@
   ],
   "dependencies": {
     "pngjs": "^7.0.0",
-    "@nocville/node": "^0.2.0"
+    "@nocville/node": "^0.2.1"
   },
   "peerDependencies": {
     "puppeteer-core": "*"