@nocville/npc 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeff Marshall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ a hand when it needs you, dozes when idle, and shows what it's doing on its spee
 desk sign: `Editing src/GameScene.ts`, `Running pnpm test`, `Searching for 'reconnect'`,
 `Needs your approval`, `Thinking…`. It leaves the office when the session ends.
 
-Requires Node.js 20+. Your team API key is in your Nocville team settings.
+Requires Node.js 20+. Get an agent key in your Nocville office under **Connect AI coworkers**.
 
 ## Quick start: AI coworkers
 
@@ -16,28 +16,53 @@ npx @nocville/npc setup
 ```
 
 Paste your key at the prompt (input is hidden, so the key never lands in your shell history).
-For scripts, pass `--api-key=<your team key>` or set `NOCVILLE_API_KEY` instead. That's it. The command saves your key to `~/.config/nocville/config.json` (mode 0600), then
-hooks up whichever agents you have installed:
+For scripts, pass `--api-key=<your key>` or set `NOCVILLE_API_KEY` instead. That's it. The
+command saves your key to `~/.config/nocville/config.json` (readable only by you), then hooks
+up whichever agents you have installed:
 
 - **Claude Code**: adds hooks to `~/.claude/settings.json`. New sessions show up right away;
   restart sessions that are already running.
 - **Codex**: adds hooks to `~/.codex/hooks.json`. Codex won't run a new hook until you've
   approved it, so start Codex once and run **`/hooks`** to trust the Nocville hooks.
+- **Gemini CLI**: adds hooks to `~/.gemini/settings.json`, keeping your settings and existing
+  hooks. Start a new session after setup.
+- **Cursor**: adds hooks to `~/.cursor/hooks.json`. Start a new chat after setup.
 
-- **Gemini CLI**: adds eight telemetry hooks to `~/.gemini/settings.json`, preserving your
-  settings and existing hooks. Start a new session after setup. Hooks return only `{}`.
+Your existing hooks are left alone, and Nocville's hooks never answer permission prompts or
+change what your agent does; they only report activity.
 
-- **Cursor**: adds native hooks to `~/.cursor/hooks.json`. Existing Nocville Claude hooks
-  also detect Cursor when its third-party hook imports are enabled. Both installations share
-  one coworker and deduplicate matching events. No permission decisions or model output are sent.
-
-Self-hosting or developing locally? Add `--api-url=http://localhost:3601`. To send sessions to
-a map other than your team's default, add `--map="Trading Floor"`.
+Running your own Nocville server? Add `--api-url=https://your-server`. To send sessions to a
+map other than your team's default, add `--map="Trading Floor"`.
 
 Prefer a global install? Run `npm i -g @nocville/npc`, then `nocville-npc setup --api-key=…`.
 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                                          |
@@ -46,26 +71,8 @@ keep working after npm clears its cache.
 | `nocville-npc claude-code uninstall` | `nocville-npc codex uninstall`                 |
 |                                      | `nocville-npc codex watch` (no-hooks fallback) |
 
-`nocville-npc gemini setup` and `nocville-npc gemini uninstall` manage Gemini alone.
-Gemini uses a 5000 ms hook timeout; pushes and end-of-turn git summaries are detached.
-Its Node process is identified by the Gemini executable path, not an unrelated Node parent.
-
-`nocville-npc cursor setup` and `nocville-npc cursor uninstall` manage native Cursor hooks.
-Native commands use 10-second timeouts. Setup installs only sessionStart/sessionEnd,
-beforeSubmitPrompt, postToolUse/postToolUseFailure, afterFileEdit, stop, subagentStop and
-preCompact; it removes older Nocville permission hooks while preserving other hooks.
-Activity comes from completed tools. Native and imported Cursor invocations return exactly
-`{}` with no decision fields. Payload fields identify imported Cursor; `CURSOR_VERSION`
-alone never reclassifies Claude launched inside its terminal. The launcher suppresses child
-stdout for every agent, including debug logs, and emits only the appropriate neutral response.
-Cursor does not watch the editor process or start a watchdog: an abandoned conversation uses
-the one-hour fallback heartbeat interval (unknown after two hours, despawn ten minutes later).
-Uninstall intentionally leaves `{"version":1}` when no other settings remain.
-
-Cursor's [documented tool names](https://cursor.com/docs/hooks#configuration) include Grep,
-Delete, Task and MCP tools. Their summaries use the shared redaction/path handling; MCP names
-are normalized to the shared MCP format. Real Cursor Shell/Read/Write verification with both
-Claude-imported-only and native hooks is still required before a public support claim.
+`nocville-npc gemini setup|uninstall` and `nocville-npc cursor setup|uninstall` manage
+Gemini CLI and Cursor on their own. For Cursor, start a new chat after setup.
 
 `nocville-npc uninstall` removes every Nocville hook. `nocville-npc init` only saves
 credentials. Every setup command takes the key from `--api-key`, then `NOCVILLE_API_KEY`, then
@@ -86,58 +93,22 @@ are shortened to their first line, and anything that looks like a secret is reda
 env assignments, `--token=`/`--password` flags, bearer headers, URL credentials, and long
 key-like strings. Paths are shown relative to the project.
 
-**Lifecycle and overhead:** normal hooks run asynchronously, update a locked local state file,
-and hand HTTP delivery to a detached process. Same-phase bursts coalesce at 1.5 seconds.
-SessionEnd stays synchronous with a short timeout to deliver the offline update; failures
-remain pending for retry. Hooks never output instructions or permission decisions.
-
-A watchdog checks a known agent process every 15 seconds and heartbeats once a minute.
-A killed process leaves the office on the next check. If the machine sleeps or loses power,
-the NPC becomes unknown after three minutes and disappears after thirteen. Hosts where
-process liveness cannot be established retain the legacy one-hour heartbeat fallback.
-Claude subagent activity appears below the parent's current activity and disappears when
-the subagent stops (or after ten minutes without activity).
-
-Setup installs a stable `~/.config/nocville/bin/nocville-hook` launcher (respecting
-`XDG_CONFIG_HOME` and `NOCVILLE_CONFIG`) and an immutable runtime copy when needed.
-Re-running setup updates the runtime pointer without changing the hook command or Codex's
-command trust. Old snapshots remain available to running watchdogs. Windows uses the sibling
-`nocville-hook.cmd` launcher, which resolves the saved Node path and runs the same bootstrap.
-Windows setup writes plain commands, never `-EncodedCommand` or an execution-policy override.
-Re-running setup replaces the former encoded commands; uninstall still recognizes them.
-
-| Agent       | Windows command host and verification                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code | Explicit per-hook `shell: "powershell"`; invokes `& '<shim>.cmd' claude-code hook`. Claude selects PowerShell 7 or falls back to 5.1. CI exercises both. [Claude hook shell reference](https://code.claude.com/docs/en/hooks#windows-powershell-tool).                                                                                                                                                                                                                                                   |
-| Gemini      | Its hook runner selects PowerShell 7 or 5.1. The saved `cmd.exe /d /s /c --% ...` preserves cmd quoting, with a terminating newline before Gemini's appended exit check. CI exercises both hosts with that check. [Hook reference](https://geminicli.com/docs/hooks/reference/), [runner](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/hooks/hookRunner.ts), [shell selection](https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/utils/shell-utils.ts). |
-| Cursor      | Explicit `cmd.exe /d /s /c` launcher; CI executes the saved string under cmd. The [published hook contract](https://cursor.com/docs/hooks) does not specify the Windows outer shell; real Windows Cursor verification remains required.                                                                                                                                                                                                                                                                  |
-| Codex       | Explicit `cmd.exe /d /s /c` launcher; CI executes the saved string under cmd. The [published hook contract](https://learn.chatgpt.com/docs/hooks) does not identify the Windows outer shell; real Windows Codex verification remains required.                                                                                                                                                                                                                                                           |
-
-PowerShell's [stop-parsing token](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing#the-stop-parsing-token)
-ends at a newline, not a semicolon. Keep Gemini's saved newline: its runner appends PowerShell
-code to the command. No event input is interpolated into shell commands. Windows support remains
-unverified until the Windows CI job and real-agent checks pass; macOS tests cannot establish it.
-**Windows Cursor users:** install native hooks with `nocville-npc cursor setup`; do not rely on
-Cursor importing Claude Code hooks. Claude's saved hook uses PowerShell syntax and an explicit
-`shell` field. If Cursor's import path ignores that field and uses cmd, the imported command can
-fail before the shim runs and produce hook errors. Nocville cannot control Cursor's import path.
-
-Windows real-agent owner checklist (required before support claims):
-
-- Run the native Windows CI job, including PowerShell 5.1/7 and a spaced `O’Neil` profile path.
-- Verify native Cursor Shell/Read/Write events after `nocville-npc cursor setup`.
-- With Claude hooks also installed, check whether Cursor imports them and honors their `shell`
-  field. Record agent versions and any duplicate/error events; verify native Cursor hooks work
-  independently. Do not count an imported Claude hook as proof of native Cursor support.
-- Verify the actual Claude, Gemini and Codex hosts using their installed saved commands.
-
-Claude's single-quoted path doubles straight and curly apostrophes according to
-[PowerShell quoting rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules#including-quote-characters-in-a-string).
-
-Both launchers discard child stdout and preserve stderr; all SDK logger levels use stderr.
-If Node is unavailable, the shim drains stdin and returns neutral `{}` for Cursor/Gemini
-and Claude hooks (which may have been imported by Cursor); Codex stays silent. Session records are local, including terminal
-records that prevent late events from reviving an ended NPC; `cleanup` removes old records.
+**Overhead:** hooks return immediately and send updates from a background process, so your
+agent never waits on the network. Rapid bursts of activity are combined into one update.
+
+If an agent is killed, its coworker leaves the office within about 15 seconds. If your machine
+sleeps or goes offline, the coworker greys out after a few minutes and leaves after about
+thirteen. Claude subagent activity appears below the parent's current activity.
+
+### Windows
+
+Setup works the same way on Windows; it writes a small `nocville-hook.cmd` launcher to
+`~/.config/nocville/bin/` and points each agent's hooks at it. **Cursor users on Windows:**
+install Cursor's own hooks with `nocville-npc cursor setup` rather than relying on Cursor
+importing your Claude Code hooks.
+
+Re-running `setup` (for example after upgrading with `npx @nocville/npc@latest setup`) keeps
+your hooks in place and switches them to the new version; running sessions are not interrupted.
 
 ### How the Codex integration works
 
@@ -150,9 +121,8 @@ hooks, makes a one-time `hooks.json.nocville-backup`, and is safe to run again.
 reads the rollout logs Codex writes to `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. It
 shows one NPC per interactive session (subagent and reviewer threads are skipped; add
 `--include-exec` to include `codex exec` runs). A session leaves the office after 30 minutes
-without log activity (`--idle-timeout=<minutes>`) or when you press Ctrl-C. If hooks are
-installed for a session (any hook state file, including an old terminal record), the watcher
-leaves that session to them. `doctor` warns when both modes are running.
+without log activity (`--idle-timeout=<minutes>`) or when you press Ctrl-C. Sessions that
+hooks already report are left to the hooks.
 
 ## Monitoring NPCs
 
@@ -199,7 +169,7 @@ import type { CollectedMetrics } from '@nocville/npc';
 
 await new SystemMonitorNPC({
   apiUrl: 'https://nocville.com',
-  apiKey: 'noc_…',
+  apiKey: 'nvk_…',
   serviceId: 'web-1',
 }).start();
 
@@ -213,32 +183,7 @@ class MyNPC extends PollingNPC {
 }
 ```
 
-## Developing in the monorepo
-
-```bash
-pnpm install
-pnpm --filter @nocville/npc build
-pnpm --filter @nocville/npc test
-node libs/nocville-npc-library/dist/cli.js --help
-SMOKE_STUB=1 pnpm --filter @nocville/npc smoke   # every payload shape, no server needed
-```
-
-**Watch an AI-coworker NPC without running an agent.** `simulate` plays a scripted session
-(start → prompt → Read → Edit → `pnpm test` → approval wait → idle → end) through the real
-built hook handlers. It works in a throwaway HOME, so your `~/.claude` and `~/.codex` are
-untouched, and the NPC appears as "Claude · demo" (or "Codex · demo"):
+## Help
 
-```bash
-pnpm --filter @nocville/npc simulate claude --api-key=<key> --api-url=http://localhost:3601
-pnpm --filter @nocville/npc simulate codex --api-key=<key> --project=gridbreak --fast
-#   --hold   stay idle after Stop until Ctrl-C, then end the session
-#   --fast   5x shorter pauses (CI)
-```
-
-**Real hooks against your local checkout.** This writes real hooks into `~/.claude` and
-`~/.codex` that run your working copy's `dist/cli.js`:
-
-```bash
-node libs/nocville-npc-library/dist/cli.js setup --api-key=<key> --api-url=http://localhost:3601
-node libs/nocville-npc-library/dist/cli.js uninstall   # remove them again
-```
+`nocville-npc --help` lists every command and flag, and `nocville-npc doctor` checks that your
+key and connection work. More at [nocville.com](https://nocville.com).

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,152 @@
+"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));
+    }
+    // A trailing `/*` or `/**` means "this folder and everything in it": subfolders already
+    // match through their ancestors, so drop it and the folder itself matches too.
+    const expanded = normalizePath((pattern.startsWith('~') ? (0, node_os_1.homedir)() + pattern.slice(1) : pattern).replace(/(\/\*{1,2})+$/, ''));
+    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/secret/*` and `~/work/secret/**` are equivalent). 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,145 @@
+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));
+    }
+    // A trailing `/*` or `/**` means "this folder and everything in it": subfolders already
+    // match through their ancestors, so drop it and the folder itself matches too.
+    const expanded = normalizePath((pattern.startsWith('~') ? homedir() + pattern.slice(1) : pattern).replace(/(\/\*{1,2})+$/, ''));
+    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.2",
   "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.2"
   },
   "peerDependencies": {
     "puppeteer-core": "*"
@@ -59,11 +59,6 @@
   ],
   "license": "MIT",
   "homepage": "https://nocville.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/marshmansf/nocville.git",
-    "directory": "libs/nocville-npc-library"
-  },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({ type: 'commonjs' }))\" && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
     "clean": "rm -rf dist",