@agentwhy/cli 0.1.0 → 0.2.1

package/dist/cli/commands/start-cli-command.js

@@ -1,8 +1,10 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { parseSince } from '../../core/session-filter.js';
 import { EXIT_CODE } from '../exit-codes.js';
 export const START_USAGE = `Usage: agentwhy start [--since <span | date>] [--out <dir>] [--policy <file> | --settings <file>]
-                     [--no-open] [--serve | --no-serve] [--share]
+                     [--no-open] [--serve | --no-serve | --detach] [--share] [--session <id>] [--quiet]
 
 Lists every session of the current directory's project on one page, writes a report for each
 session active inside the range, and opens the page. The page it opens is served from 127.0.0.1,
@@ -18,8 +20,15 @@ after 30 minutes with no request, or with Ctrl+C. The reports are files either w
   --no-open           write the files and print where, without opening anything
   --serve             serve the page even with --no-open, and print its address
   --no-serve          open the page as a file and return; marks on it are copied as commands
+  --detach            serve the page from the background and return at once: the server already
+                      running for this project if there is one, else a new one, which stops 30
+                      minutes after its last page is closed. Where none can run, the page is a file
   --share             no session ids, no project path, nothing above the project root. This
                       reduces exposure; it does not anonymise
+  --session <id>      open this session's report instead of the list, beside every other one, so
+                      its "All conversations" leads back to them. Written whatever the range
+  --quiet             say where the page is and nothing else - for an agent opening a report
+                      because you said yes, as \`report --quiet\` does
   -h, --help          this text
 `;
 // A Record over the outcome union: a new outcome does not compile until it has an exit code.
@@ -52,6 +61,9 @@ export class StartCliCommand {
                     serve: { type: 'boolean' },
                     'no-serve': { type: 'boolean', default: false },
                     share: { type: 'boolean', default: false },
+                    session: { type: 'string' },
+                    quiet: { type: 'boolean', default: false },
+                    detach: { type: 'boolean', default: false },
                     help: { type: 'boolean', short: 'h', default: false },
                 },
                 strict: true,
@@ -66,10 +78,23 @@ export class StartCliCommand {
         if (values.serve === true && values['no-serve']) {
             return { kind: 'usage-error', message: '--serve and --no-serve cannot be given together', usage: this.usage };
         }
+        // A shared page names no session, and has none to open by its id.
+        if (values.share && values.session !== undefined) {
+            return { kind: 'usage-error', message: '--session names a session by its id, which --share leaves out', usage: this.usage };
+        }
+        if (values.session === '')
+            return { kind: 'usage-error', message: '--session needs a session id', usage: this.usage };
+        // PF3: from the background is served, and a shared page is never served (R37).
+        if (values.detach && (values.share || values['no-serve'] || values.serve === true)) {
+            return { kind: 'usage-error', message: '--detach serves the page, and cannot be given with --share, --serve or --no-serve', usage: this.usage };
+        }
+        const detached = this.#dependencies.detached;
+        if (values.detach && detached === undefined)
+            return { kind: 'usage-error', message: '--detach is not available here', usage: this.usage };
         const since = parseSince(values.since, this.#dependencies.now);
         if ('error' in since)
             return { kind: 'usage-error', message: since.error, usage: this.usage };
-        const result = await this.#dependencies.start.run({
+        const result = await (values.detach ? detached : this.#dependencies.start).run({
             since,
             ...(values.out === undefined || values.out === '' ? {} : { out: values.out }),
             ...(values.policy === undefined ? {} : { policyPath: values.policy }),
@@ -77,6 +102,8 @@ export class StartCliCommand {
             open: !values['no-open'],
             share: values.share,
             ...(values['no-serve'] ? { serve: false } : values.serve === true ? { serve: true } : {}),
+            ...(values.session === undefined ? {} : { session: values.session }),
+            ...(values.quiet ? { quiet: true } : {}),
         });
         return { kind: 'completed', output: result.output, exitCode: EXIT_CODE_BY_OUTCOME[result.outcome] };
     }

package/dist/cli/commands/watch-cli-command.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from 'node:util';
 import { ALERT_THRESHOLDS } from '../../report/watch/agent-alert.js';
 import { SAID_AS } from '../../report/watch/notice-choices.js';
@@ -20,8 +22,8 @@ and a Stop hook that exits 2 keeps the turn from ending.
   --settings <file>   a settings file whose deny rules stand in for a policy, as for \`report\`
   --on <level>        value (default): only a value written from a protected file.
                       reached: also an agent that reached a protected file.
-                      refused: also an attempt a rule refused, where nothing was reached -
-                      the one notice that asks for nothing and says a rule held
+                      refused: also an attempt that was stopped - by a rule, by auto mode or
+                      by you - where nothing was reached: the one notice that asks for nothing
   --clean <when>      when a turn that found nothing says so, in the conversation
                       once (default): the first quiet turn says the session is being watched.
                       off: nothing is ever said about a quiet turn, as before.

package/dist/cli/exit-codes.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 // Documented in each command's usage text; tests/cli/commands/doctor-usage.test.ts pins the doctor usage to it.
 export const EXIT_CODE = {
     ok: 0,

package/dist/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { homedir, tmpdir } from 'node:os';
 import { EXIT_CODE, HOOK_BLOCK_EXIT_CODE } from './cli/exit-codes.js';
 import { runSwitching } from './cli/project-switches.js';
@@ -48,6 +50,14 @@ async function main(argv) {
         // the script as it was started, and the `PATH` a hook's shell would look it up on.
         script: process.argv[1],
         path: process.env.PATH,
+        // The shell and environment the check written into `~/.codex` is tried in once, as Codex runs it
+        // (`2026-10-02-codex-approves-its-own-hook.md` AO14).
+        shell: process.env.SHELL,
+        variables: process.env,
+        // A page server is remembered under the process that runs it, and agentwhy is started again in the background by
+        // the Node running it now (`2026-10-02-a-page-not-a-file.md` PF2, PF3).
+        pid: process.pid,
+        node: process.execPath,
     });
     // which-project V14, amended: one page server for the process, so a switched-from project's pages still reach it.
     const server = processServer();
@@ -61,7 +71,8 @@ function write(result) {
             process.stdout.write(result.usage);
             return EXIT_CODE.ok;
         case 'usage-error':
-            process.stderr.write(`agentwhy: ${result.message}\n\n${result.usage}`);
+            // R73: the message is the first thing on stderr, before any help this one carries.
+            process.stderr.write(`agentwhy: ${result.message}\n\n${result.hint === undefined ? '' : `${result.hint}\n\n`}${result.usage}`);
             return EXIT_CODE.usage;
         case 'completed':
             process.stdout.write(result.output);

package/dist/composition-root.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * A port for a place where nobody can be asked. The served Settings view runs setup with its own confirm step as
  * the consent (R58, `interactive: false`), so a question here would be a question with no one at the other end:
@@ -16,6 +18,8 @@ import { projectDirectoryName } from './adapter/claude-code/contract/projects.js
 import { ClaudeCodeSessionCatalogue } from './adapter/claude-code/discovery/claude-code-session-catalogue.js';
 import { ClaudeCodeSessionDiscovery } from './adapter/claude-code/discovery/claude-code-session-discovery.js';
 import { ClaudeCodeSessionTitles } from './adapter/claude-code/discovery/claude-code-session-titles.js';
+import { ClaudeDesktopTitles } from './adapter/claude-code/discovery/claude-desktop-titles.js';
+import { DESKTOP_SESSIONS } from './adapter/claude-code/contract/desktop-sessions.js';
 import { ClaudeCodeProjectCatalogue } from './adapter/claude-code/discovery/claude-code-project-catalogue.js';
 import { ClaudeCodeSessionSource } from './adapter/claude-code/events/claude-code-session-source.js';
 import { ClaudeCodeProbe } from './adapter/claude-code/probe/claude-code-probe.js';
@@ -25,6 +29,7 @@ import { CodexSessionDiscovery } from './adapter/codex/discovery/codex-session-d
 import { CodexSessionIndex } from './adapter/codex/discovery/codex-session-index.js';
 import { CodexSessionCatalogue } from './adapter/codex/discovery/codex-session-catalogue.js';
 import { CodexSessionTitles } from './adapter/codex/discovery/codex-session-titles.js';
+import { codexOnThisComputer } from './adapter/codex/discovery/codex-on-this-computer.js';
 import { CodexProjectCatalogue } from './adapter/codex/discovery/codex-project-catalogue.js';
 import { SESSIONS_ROOT as CODEX_SESSIONS_ROOT, THREAD_NAMES } from './adapter/codex/contract/session.js';
 import { CodexSessionSource } from './adapter/codex/events/codex-session-source.js';
@@ -38,6 +43,11 @@ import { CheckCliCommand } from './cli/commands/check-cli-command.js';
 import { InitCliCommand } from './cli/commands/init-cli-command.js';
 import { RefuseCliCommand } from './cli/commands/refuse-cli-command.js';
 import { CodexStopCliCommand } from './cli/commands/codex-stop-cli-command.js';
+import { codexTurnFormat } from './report/watch/codex-turn-format.js';
+import { DetachedStart } from './report/start/detached-start.js';
+import { FilePageServers } from './infrastructure/file-page-servers.js';
+import { NodeBackgroundRun } from './infrastructure/node-background-run.js';
+import { NodePageProbe } from './infrastructure/node-page-probe.js';
 import { CodexTurnRefusals } from './adapter/codex/hooks/stop-refusals.js';
 import { DoctorCliCommand } from './cli/commands/doctor-cli-command.js';
 import { ReportCliCommand } from './cli/commands/report-cli-command.js';
@@ -53,6 +63,7 @@ import { SessionReport } from './report/session-report.js';
 import { TextDigestRenderer } from './report/check/render/text-digest-renderer.js';
 import { SessionCheck } from './report/check/session-check.js';
 import { CommandRefusal } from './refuse/command-refusal.js';
+import { ShellCommandTrial } from './infrastructure/shell-command-trial.js';
 import { CodexMirror } from './setup/codex-mirror.js';
 import { ProjectSetup } from './setup/project-setup.js';
 import { ReportPageRenderer } from './report/render/report-page/report-page-renderer.js';
@@ -60,6 +71,8 @@ import { ConversationsRenderer } from './report/start/conversations/conversation
 import { SettingsRenderer } from './report/start/settings/settings-renderer.js';
 import { MonthRenderer } from './report/start/month/month-renderer.js';
 import { ToFixRenderer } from './report/start/to-fix/to-fix-renderer.js';
+import { projectName } from './report/start/app-nav.js';
+import { welcomeIn } from './report/start/onboarding/welcome-decision.js';
 import { SessionStart } from './report/start/session-start.js';
 import { NoticeWordsRenderer } from './report/watch/render/notice-words.js';
 import { NoticeSettings } from './report/watch/notice-settings.js';
@@ -92,6 +105,7 @@ import { TerminalBanner } from './infrastructure/terminal-banner.js';
 import { FileAlertStore } from './infrastructure/file-alert-store.js';
 import { OsNotifier } from './infrastructure/os-notifier.js';
 import { TAGLINE, terminalLogo } from './shared/terminal-logo.js';
+import { leftAlone } from './core/guarded-places.js';
 /**
  * Where a person's answers about being told are kept (`the-agent-tells-you.md` R22): one file, beside the marks,
  * under the directory this tool already owns in their home - outside every project, and so outside every repository.
@@ -127,8 +141,15 @@ export function createCommandRouter(environment) {
     const codexCatalogue = new CodexSessionCatalogue({ index: codexIndex, directories: files, sessionsRoot: codexRoot });
     // XD5: one list of a project's conversations for both AIs, each row naming its AI.
     const catalogue = new CombinedSessionCatalogue([claudeCatalogue, codexCatalogue]);
-    // codex-blocks-too CK6: a project uses Codex where a Codex conversation is listed for it.
-    const codexConversations = async () => (await codexCatalogue.list(environment.workingDirectory)).sessions.length > 0;
+    // CK6 with AO1: Codex is used on this computer where its `~/.codex` folder is - the one gate the setup and
+    // Settings' Codex line ask, since the check agentwhy writes is the person's own, outside every project.
+    const codexHere = () => codexOnThisComputer(files, environment.home);
+    // AO14: the one trial run of the check before it is written into `~/.codex`, as Codex runs a hook, from a folder no
+    // project is above. Absent `variables`, no trial can be made and the mirror writes nothing there.
+    const codexTrial = environment.variables === undefined
+        ? {}
+        : { trial: new ShellCommandTrial({ platform: environment.platform, ...(environment.shell === undefined ? {} : { shell: environment.shell }), environment: environment.variables }) };
+    const codexMirrorShared = { ...codexTrial, trialFolder: environment.temporaryDirectory, home: environment.home, codexOnThisComputer: codexHere };
     const formats = new SessionFormats([
         { provider: 'codex', recognise: (input) => recogniseCodex(codexDiscovery, files, input) },
         { provider: 'claude-code', recognise: (input) => recogniseClaudeCode(files, input) },
@@ -189,17 +210,27 @@ export function createCommandRouter(environment) {
     // Codex's are the names Codex gave its threads (`THREAD_NAMES`, measured 2026-09-30); a thread it named nothing - a
     // `codex exec` run - keeps the missing-title state rather than a message guessed at.
     const titleRedactor = new Redactor(randomUUID());
+    // The Claude desktop app writes no `ai-title`; its own file names the conversation (`claude-desktop-conversations.md`
+    // CD2). macOS is the one system where that file's place is measured (CD6, CDD4) - elsewhere nothing is looked for.
+    // One reader for both lists below, so a file is read once however many lists ask (CD5).
+    const desktopTitles = environment.platform === 'darwin'
+        ? new ClaudeDesktopTitles({ directories: files, files, folder: join(environment.home, ...DESKTOP_SESSIONS.folder) })
+        : undefined;
     const titles = new ProviderTitles({
-        'claude-code': new ClaudeCodeSessionTitles({ transcripts: files, redactor: titleRedactor }),
+        'claude-code': new ClaudeCodeSessionTitles({ transcripts: files, redactor: titleRedactor, ...(desktopTitles === undefined ? {} : { desktop: desktopTitles }) }),
         codex: new CodexSessionTitles({ files, directories: files, path: join(environment.home, ...THREAD_NAMES.file), redactor: titleRedactor }),
     });
     // which-project V9-V11: the person's projects, for the window the sidebar's card opens. A title from another project
     // passes a redactor of its own, as this project's titles do.
     // A folder only Codex worked in is listed under the id Claude Code would give it, so a folder in both is one project
     // (decided 2026-09-29).
+    // which-project V10b: on macOS, another project's folder where the system asks before an app reads is not looked into.
+    const leaveAlone = environment.platform === 'darwin'
+        ? (folder) => leftAlone(folder, environment.workingDirectory, environment.home)
+        : undefined;
     const projects = new CombinedProjectCatalogue([
-        new ClaudeCodeProjectCatalogue({ directories: files, transcripts: files, redactor: new Redactor(randomUUID()), home: environment.home }),
-        new CodexProjectCatalogue({ index: codexIndex, directories: files, sessionsRoot: codexRoot, projectId: projectDirectoryName }),
+        new ClaudeCodeProjectCatalogue({ directories: files, transcripts: files, redactor: new Redactor(randomUUID()), home: environment.home, ...(leaveAlone === undefined ? {} : { leaveAlone }), ...(desktopTitles === undefined ? {} : { desktop: desktopTitles }) }),
+        new CodexProjectCatalogue({ index: codexIndex, directories: files, sessionsRoot: codexRoot, projectId: projectDirectoryName, ...(leaveAlone === undefined ? {} : { leaveAlone }) }),
     ]);
     // One person's record of what they did about a file, beside nothing else and outside every project
     // (`worth-running-every-day` R33). The directory is named the way Claude Code names the project's sessions.
@@ -217,7 +248,19 @@ export function createCommandRouter(environment) {
         path: preferencesPath(environment),
         workingDirectory: environment.workingDirectory,
     });
+    // PF2: the page server running for this project, remembered in the person's own folder under the project's key.
+    const pageServers = new FilePageServers(join(environment.home, '.agentwhy'));
+    const thisProject = projectDirectoryName(environment.workingDirectory);
+    const pid = environment.pid;
     const start = new SessionStart({
+        ...(pid === undefined
+            ? {}
+            : {
+                pageServer: {
+                    write: (url) => pageServers.write(thisProject, { url, pid, startedAt: Date.now() }),
+                    remove: () => pageServers.remove(thisProject, pid),
+                },
+            }),
         catalogue,
         report,
         files,
@@ -278,8 +321,10 @@ export function createCommandRouter(environment) {
             interactive: false,
             workingDirectory: environment.workingDirectory,
             invocation,
-            codexConversations,
+            ...codexMirrorShared,
         }),
+        // CK6, amended 2026-10-01: Settings' Codex line, in a project with no Codex conversation of its own.
+        codexOnThisComputer: codexHere,
         // R26a: the panel that says what a person is told, writing the one file outside every project.
         notices,
         printer: new StreamPrinter(environment.output),
@@ -303,11 +348,11 @@ export function createCommandRouter(environment) {
         workingDirectory: environment.workingDirectory,
         now: environment.now,
     });
-    const watch = new SubagentWatch({
-        source: new ClaudeCodeSessionSource({ discovery: new ClaudeCodeSessionDiscovery(files), files }),
+    // What both hooks share - Claude Code's `watch` and Codex's Stop (`codex-says-it-too` CX1): the redactor, the words,
+    // the store, the person's choices and how agentwhy runs. What differs is handed to each below.
+    const watching = {
         files,
         tell,
-        input: new NodeTextInput(environment.input),
         // Its own salt, as every report has: nothing it redacts means anything outside this one run.
         createRedactor: (projectRoot) => new Redactor(randomUUID(), projectRoot, false),
         renderer: new NoticeWordsRenderer(),
@@ -317,19 +362,54 @@ export function createCommandRouter(environment) {
         store: new FileAlertStore(environment.temporaryDirectory, environment.user),
         // What a person chose about being told: their own file, outside every project, read on every run (R22, R25).
         preferencesPath: preferencesPath(environment),
-        // R14: the agent is asked to speak only where a person is reading, and the entry point is what says so.
-        ...(environment.entryPoint === undefined ? {} : { entryPoint: environment.entryPoint }),
         // R29: the language of a line nobody chose one for.
         ...(environment.locale === undefined ? {} : { locale: environment.locale }),
+        invocation,
+    };
+    const codexWatch = new SubagentWatch({
+        ...watching,
+        source: new CodexSessionSource({ discovery: codexDiscovery, files, sessionsRoot: codexRoot, index: codexIndex }),
+        input: new NodeTextInput(environment.input),
+        turnFormat: codexTurnFormat(files, new CodexTurnRefusals(files), join(environment.home, ...THREAD_NAMES.file), environment.home),
+    });
+    const watch = new SubagentWatch({
+        ...watching,
+        source: new ClaudeCodeSessionSource({ discovery: new ClaudeCodeSessionDiscovery(files), files }),
+        input: new NodeTextInput(environment.input),
+        // R14: the agent is asked to speak only where a person is reading, and the entry point is what says so.
+        ...(environment.entryPoint === undefined ? {} : { entryPoint: environment.entryPoint }),
         // R18: the agent runs agentwhy the way this project's hook does; J6: else the way this hook was started.
         ...(environment.projectDirectory === undefined ? {} : { projectDirectory: environment.projectDirectory }),
-        invocation,
     });
     // Drawn above the first question each of these commands asks, and not again: one banner per command.
     const logo = () => new TerminalBanner(terminalLogo([TAGLINE], { colour: environment.colour, ascii: false }));
     const setupBanner = logo();
     // Registration order is the order `--help` lists them in, so the way in comes first.
-    const start_ = new StartCliCommand({ start, now: environment.now });
+    // PF3-PF6: the pages served from the background - the running server reused, else one started, else files.
+    const detached = new DetachedStart({
+        servers: pageServers,
+        probe: new NodePageProbe(),
+        background: new NodeBackgroundRun(environment.node ?? 'node', environment.script),
+        browser,
+        project: thisProject,
+        files: start,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        clock: () => Date.now(),
+        // AW1: the address `--detach` hands over names the welcome where this project is to meet it, as the address a
+        // served run prints does. The same decision the run itself asks (W23), from the same record and settings files.
+        welcome: {
+            file: APP_LINKS.onboarding,
+            project: projectName(environment.workingDirectory),
+            opens: async () => (await welcomeIn(environment.workingDirectory, {
+                store: onboarding,
+                files,
+                home: environment.home,
+                realHome,
+                now: () => Date.now(),
+            })).opens,
+        },
+    });
+    const start_ = new StartCliCommand({ start, detached, now: environment.now });
     const check_ = new CheckCliCommand({ check, now: environment.now });
     const setupChooser = new ClackChooser(environment.input, environment.output, setupBanner);
     const init_ = new InitCliCommand(new CodexMirror({
@@ -349,7 +429,7 @@ export function createCommandRouter(environment) {
         interactive: environment.interactive,
         workingDirectory: environment.workingDirectory,
         invocation,
-        codexConversations,
+        ...codexMirrorShared,
     }));
     // One banner for both ports this command can ask through - the range question, then the list - so it is drawn once.
     const sessionsBanner = logo();
@@ -406,6 +486,11 @@ export function createCommandRouter(environment) {
             }),
             interactive: environment.inputIsTerminal,
         }),
-        new CodexStopCliCommand(new CodexTurnRefusals(new NodeTextInput(environment.input), files), environment.inputIsTerminal),
-    ], environment.interactive ? start_ : undefined);
+        new CodexStopCliCommand(codexWatch, environment.inputIsTerminal),
+        // R73 stands (`a-page-not-a-file` PFD3): off a terminal a bare `agentwhy` opens nothing and serves nothing. But the
+        // reader of that refusal is usually an AI agent asked to start agentwhy and send a link, and the usage alone left it
+        // guessing: measured 2026-10-04 in three apps, one guessed `start --detach` and one gave up. So the refusal names it.
+    ], environment.interactive ? start_ : undefined, 'There is no terminal here, so a bare agentwhy opens nothing and serves nothing.\n' +
+        'To serve a page and return at once - what an agent asked to send someone a link needs - run:\n' +
+        '  agentwhy start --detach');
 }

package/dist/core/access/command-line.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * The paths a command line could be addressing.
  *
@@ -49,6 +51,19 @@ const PRINTS_CONTENT = new Set([
     'xxd',
     'od',
 ]);
+/**
+ * Programs that print nothing when they succeed (`said-where-the-person-is` SWO1): `cd apps && cat .env` prints the
+ * file and nothing else, and reading it as a listing because of `cd` left a key the agent read untraced (SWB4).
+ */
+const PRINTS_NOTHING = new Set(['cd']);
+/**
+ * Programs that print the names of what they were pointed at - a directory's entries, the paths a walk found - and
+ * never a file's text. Beside a content program (`ls -la && cat .env`, `cat x || find . -name x`) the output is both:
+ * its names a listing, its `KEY=value` lines the file's (SWO1). `find` joined on 2026-10-02: `cat <told file> || find
+ * …` in one line read the key and traced nothing, so the person heard "no value found" over a value in the chat.
+ * Not a search: a search prints a file's lines, and is read as one (`search-hits-are-reads`).
+ */
+const LISTS_NAMES = new Set(['ls', 'find']);
 /** `NAME=value` before a program sets a variable; it runs nothing. */
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
 /** Unquoted, each of these ends a simple command. `&` directly before `>` redirects instead (`&>file`). */
@@ -342,8 +357,39 @@ export function commitsIn(command) {
 }
 /** True when every command in the line only prints what it was given, so its output enumerates nothing. */
 export function printsContentOnly(commands) {
-    const programs = commands.flatMap((command) => readCommand(command).flatMap((simple) => (simple.program === undefined ? [] : [simple.program])));
-    return programs.length > 0 && programs.every((program) => PRINTS_CONTENT.has(basename(program)));
+    const programs = printingPrograms(commands);
+    return programs.length > 0 && programs.every((program) => PRINTS_CONTENT.has(program));
+}
+/**
+ * True when the line prints files' text beside a directory's names, and nothing else (SWO1): `cd apps && ls -la && cat
+ * .env`. Its output is neither content only nor a listing only, so a caller reads its `KEY=value` lines as the files'
+ * and every other line as the listing's.
+ */
+export function printsContentBesideNames(commands) {
+    const programs = printingPrograms(commands);
+    return programs.some((program) => PRINTS_CONTENT.has(program)) && programs.some((program) => LISTS_NAMES.has(program)) &&
+        programs.every((program) => PRINTS_CONTENT.has(program) || LISTS_NAMES.has(program));
+}
+/** Whether a program, by its base name, prints the text of what it is given. */
+export function printsContent(program) {
+    return PRINTS_CONTENT.has(basename(program));
+}
+/**
+ * The words a line's printing programs are given to open: the non-option arguments of `cat`, `head` and the others
+ * that print a file's text, leaving out the programs whose arguments are text (`echo`). Each is a file by position -
+ * `cat demo.env` names one whatever it looks like - which is what lets a bare name match a wildcard rule
+ * (`said-where-the-person-is` SW17): read as guessed text, `cat demo.env` under the blocked `.env` wildcard named no
+ * file, the key it printed was never traced, and the line said nothing was opened.
+ */
+export function fileOperandsIn(commands) {
+    return commands.flatMap(simpleCommandsIn)
+        .filter((simple) => printsContent(simple.program) && !addressesNothing(simple.program))
+        .flatMap((simple) => simple.args)
+        .filter((word) => !word.startsWith('-'));
+}
+/** The programs a line runs that print something, by base name: `cd` prints nothing, and says nothing of the output. */
+function printingPrograms(commands) {
+    return commands.flatMap((command) => readCommand(command).flatMap((simple) => (simple.program === undefined ? [] : [basename(simple.program)]))).filter((program) => !PRINTS_NOTHING.has(program));
 }
 function basename(program) {
     const parts = program.split('/');

package/dist/core/access/listing.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * The paths a listing could be naming.
  *

package/dist/core/access/path-tokens.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 /**
  * Pulls path-like tokens out of a piece of text, so they can be held against the policy.
  *

package/dist/core/access/protected-access.js

@@ -1,6 +1,6 @@
 import { matchesGlob } from '../policy/glob.js';
 import { protectionOf } from '../policy/policy.js';
-import { commandPathCandidates, printsContentOnly } from './command-line.js';
+import { commandPathCandidates, fileOperandsIn, printsContentBesideNames, printsContentOnly } from './command-line.js';
 import { listingPathCandidates } from './listing.js';
 import { pathTokens, stringsIn } from './path-tokens.js';
 import { outputIsClean, outputShowsReach } from './recorded-effect.js';
@@ -31,6 +31,9 @@ function accessesOf(event, policy) {
     const fromInput = dedupe([
         ...protectedTargets(event.targets, policy),
         ...protectedPathsAmong(event.commands.flatMap(commandPathCandidates), policy, { allowWhitespace: true }),
+        // SW17: what a printing program was given to open is a file by position, so a bare name still meets a wildcard
+        // rule - `cat demo.env` read a key under the `.env` wildcard, and nothing here called it a file.
+        ...protectedPathsAmong(fileOperandsIn(event.commands), policy, { allowWhitespace: true, positional: true }),
     ]);
     const named = new Set(fromInput.map(([path]) => path));
     // Only a listing says the call reached what it names. The content of a file that mentions `.env` says the
@@ -135,6 +138,31 @@ export function searchOf(event) {
 export function readsContent(event) {
     return event.resultShape === 'content' || (event.resultShape === 'listing' && printsContentOnly(event.commands));
 }
+/**
+ * Whether what came back holds the text of what the call named beside a directory's names (`said-where-the-person-is`
+ * SWO1): `cd apps && ls -la && cat .env`. Its `KEY=value` lines are the files'; the rest is read as a listing, as before.
+ */
+export function readsContentBesideNames(event) {
+    return event.resultShape === 'listing' && !readsContent(event) && printsContentBesideNames(event.commands);
+}
+/** A shell word that sends output away rather than naming a file read: `2>/dev/null` is read as `2` and `/dev/null`. */
+const SENT_AWAY = /^(?:\d|\/dev\/null)$/;
+/**
+ * Whether what came back is the text of `paths` and of nothing else (`2026-10-02-said-where-the-person-is.md` SW14):
+ * the call prints what it named (`readsContent`), and every file it names - each target of a tool, each word of a
+ * shell line that is not an option - is one of them. Found by review: any call that named a private file was taken
+ * for one that printed it, so `ls -a .env && printenv` hid a key printed from the environment, and `cat .env notes.txt`
+ * one from `notes.txt`.
+ */
+export function printsOnly(event, paths) {
+    if (paths.size === 0 || !(readsContent(event) || readsContentBesideNames(event)))
+        return false;
+    // The files a shell line printed are the words of its programs that print a file: `cd`'s folder and `ls`'s print
+    // none, and `echo`'s words are text.
+    const words = fileOperandsIn(event.commands).filter((word) => !SENT_AWAY.test(word));
+    const named = [...event.targets.filter((target) => target !== ''), ...words];
+    return named.length > 0 && named.every((word) => paths.has(word) || pathTokens(word).some((token) => paths.has(token)));
+}
 /**
  * The protected paths one command line names, with the pattern that protects each - read exactly as a report reads the
  * command of a call, so a hook refusing a command and the report on the session cannot disagree about whether it named
@@ -142,7 +170,11 @@ export function readsContent(event) {
  * print is not known before it runs.
  */
 export function protectedPathsInCommand(command, policy) {
-    return protectedPathsAmong(commandPathCandidates(command), policy, { allowWhitespace: true });
+    return dedupe([
+        ...protectedPathsAmong(commandPathCandidates(command), policy, { allowWhitespace: true }),
+        // SW17, exactly as `accessesOf` reads it, so the hook and the report never disagree about a bare operand.
+        ...protectedPathsAmong(fileOperandsIn([command]), policy, { allowWhitespace: true, positional: true }),
+    ]);
 }
 /**
  * A candidate holding whitespace is not offered to the policy. A path may legitimately contain a space, and
@@ -271,7 +303,7 @@ function protectedPathsAmong(candidates, policy, options = {}) {
     for (const candidate of usable) {
         if (found.has(candidate))
             continue;
-        const protection = protectionFor(policy, candidate, false);
+        const protection = protectionFor(policy, candidate, options.positional === true);
         if (protection !== undefined)
             found.set(candidate, protection.pattern);
     }
@@ -298,6 +330,7 @@ function protectedPathsPerLine(lines, policy) {
 function toAccess(event, source, path, pattern, outcome, lines) {
     return {
         ...(lines === undefined ? {} : { lines }),
+        ...(outcome === 'blocked' && event.result?.refusedBy !== undefined ? { refusedBy: event.result.refusedBy } : {}),
         eventId: event.id,
         agentId: event.agentId,
         toolName: event.toolName,

package/dist/core/access/protected-values.js

@@ -1,5 +1,6 @@
 import { unquote } from '../redaction/value-shapes.js';
 import { codeReadsNamedFile, printsContentOnly } from './command-line.js';
+import { readsContentBesideNames } from './protected-access.js';
 const KEYED = /^(?:export\s+)?[A-Za-z_][A-Za-z0-9_.-]*\s*[=:]\s*(.*)$/;
 const JSON_KEYED = /^"[^"]+"\s*:\s*("[^"]*"|[^,\s]+)/;
 /**
@@ -50,6 +51,12 @@ export function protectedValues(model, accesses) {
             for (const line of content.split('\n'))
                 add(event.agentId, named, line);
         }
+        else if (named.length > 0 && readsContentBesideNames(event)) {
+            // SWO1: a file's text beside a directory's names. Only a `KEY=value` line is the file's: a name `ls` printed is not
+            // a value, and tracing one would find it in every answer that mentions the file.
+            for (const line of keyedLines(content))
+                add(event.agentId, named, line);
+        }
         else {
             // An interpreter whose own code opened the file: its output is read as the file's, against the files it named.
             const opened = named.filter((path) => codeReadsNamedFile(event.commands, path));
@@ -66,6 +73,16 @@ export function protectedValues(model, accesses) {
     }
     return values;
 }
+/**
+ * The lines of a call's output shaped `KEY=value`, `"key": "value"` or `//registry/:key=value` (SWO1): where a file's
+ * text is printed beside a directory's names, these are the file's, and no line `ls` prints has that shape.
+ */
+export function keyedLines(content) {
+    return content.split('\n').filter((raw) => {
+        const line = raw.replace(LINE_NUMBER, '').trim();
+        return !line.startsWith('#') && (JSON_KEYED.test(line) || KEYED.test(line) || REGISTRY_KEYED.test(line));
+    });
+}
 /** The succeeded accesses of each call, in the order the calls were met: one call's content is read once. */
 function byEvent(accesses) {
     const groups = new Map();

package/dist/core/access/search-output.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { listingPathCandidates } from './listing.js';
 const LINE_NUMBER = /^\d+[:-]/;
 const CONTEXT_LINE = /^(.+)-(\d+)-(.*)$/;

package/dist/core/access/search-reach.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { addressesNothing, simpleCommandsIn } from './command-line.js';
 const GREPS = new Set(['grep', 'egrep', 'fgrep']);
 /** A glob character the shell expands in an unquoted word. */

package/dist/core/combined-project-catalogue.js

@@ -29,8 +29,14 @@ export class CombinedProjectCatalogue {
 function merged(first, second) {
     return {
         ...first,
-        exists: first.exists || second.exists,
+        folder: mergedFolder(first.folder, second.folder),
         conversations: first.conversations + second.conversations,
         newest: second.newest.modifiedAt > first.newest.modifiedAt ? second.newest : first.newest,
     };
 }
+/** One folder, looked at by two catalogues: there if either saw it, not looked at if either left it, gone otherwise. */
+function mergedFolder(first, second) {
+    if (first === 'there' || second === 'there')
+        return 'there';
+    return first === 'not-looked' || second === 'not-looked' ? 'not-looked' : 'gone';
+}

package/dist/core/correlation/correlate.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Nessprim Karol Kozer
+// SPDX-License-Identifier: Apache-2.0
 import { outcomeOfExecution } from '../access/recorded-effect.js';
 import { MAIN_AGENT_TYPE } from '../agent.js';
 import { capabilityGaps } from '../capability.js';
@@ -184,7 +186,8 @@ function reportRunning(records, results) {
         .reduce((latest, call) => (latest === undefined || call.sequence > latest.sequence ? call : latest), undefined);
     if (last === undefined || results.has(last.id))
         return undefined;
-    return last.commands.length === 1 && AGENTWHY_REPORT.test(last.commands[0] ?? '') ? last : undefined;
+    const command = last.commands.length === 1 ? (last.commands[0] ?? '') : undefined;
+    return command !== undefined && (AGENTWHY_REPORT.test(command) || OPENS_ONE_SESSION.test(command)) ? last : undefined;
 }
 /**
  * `agentwhy report` with flags and plain values only: no shell operator, quote, substitution or second line. agentwhy
@@ -194,6 +197,13 @@ function reportRunning(records, results) {
  * are split where a shell splits them, on a space or a tab: a line break passed for one, and so did a second command.
  */
 const AGENTWHY_REPORT = new RegExp(`^[ \\t]*(?:${PLAIN_INVOCATION_SOURCE})${WORD_BREAK}report(?:${WORD_BREAK}[\\w@%+=:,./~-]+)*[ \\t]*$`);
+/**
+ * `agentwhy start` opening one session's report, with flags and plain values only, as `AGENTWHY_REPORT` reads `report`:
+ * the command the agent is now asked to run (`2026-10-02-said-where-the-person-is.md` SW10), so the report opened from
+ * the chat shows no gap where it reads the call that opened it. Only with `--session`: `start` alone opens no report of
+ * this session, and is a call like any other.
+ */
+const OPENS_ONE_SESSION = new RegExp(`^[ \\t]*(?:${PLAIN_INVOCATION_SOURCE})${WORD_BREAK}start(?:${WORD_BREAK}[\\w@%+=:,./~-]+)*${WORD_BREAK}--session(?:${WORD_BREAK}[\\w@%+=:,./~-]+)+[ \\t]*$`);
 /**
  * Retries are separate calls with separate ids (§4.3 rule 7), so two results for one id is not a retry - it is
  * an ambiguity, and picking one of them would hand the event a confident outcome it has not earned. They are
@@ -299,6 +309,8 @@ function toResult(result) {
     return {
         ...(result.content === undefined ? {} : { content: result.content }),
         ...(result.denial === undefined ? {} : { denialKind: result.denial.kind }),
+        // WS2: who refused, only where the adapter recognised the marker - an unknown one names nobody.
+        ...(result.denial?.recognised === true ? { refusedBy: result.denial.source } : {}),
         ...(result.launchNotice === true ? { launchNotice: true } : {}),
         stage: result.stage,
         completeness: result.completeness,