@hwip/cli 0.1.16 → 0.1.18

package/README.md

@@ -558,20 +558,33 @@ Linux a systemd user unit (`app.hwip.listener.service`, see
 `--service-status` shows what the installed one points at; `hwip install`
 offers it during setup and `hwip uninstall` takes it away again.
 
-What you get back after a reboot is your **past sessions**, ready to
-resume from the phone — not live agents. tmux does not survive a reboot
+What you get back after a reboot is your **recent projects**, ready for a
+new session from the phone — not live agents. tmux does not survive a reboot
 either, and this doesn't try to bring those sessions back to life.
-A resume starts the agent in the directory it last ran in; for Claude Code,
+A new session starts the agent in the directory the project last ran in, with
+a fresh conversation. An older app can still ask to resume a session; that
+starts it in the same directory, and for Claude Code,
 OpenCode, Codex, Pi and Hermes it also picks up the conversation that session
 last had (`claude --resume <id>`, `opencode --session <id>`,
 `codex resume <thread>`, `pi --session <file>`, `hermes --resume <id>` — the
 id this machine read off the live pane's own process; an id two panes both
 answered to is not kept). Claude Code, Codex and Pi start fresh when that
 conversation is no longer on disk, and the other agents always start a new one.
-Each ended run of a name is its own row on the phone, and starting one
-again picks up that run's conversation, not the newest one. If the name
-is live again by then, that run starts beside it under the next free name
-of the family (`<name>-2`, `<name>-3`, …) instead of being refused.
+An older app that names a run picks up that run's conversation, not the
+newest one. If the name is live again by then, that run starts beside it
+under the next free name of the family (`<name>-2`, `<name>-3`, …) instead
+of being refused.
+
+The phone can also start a **new** session in a project this machine has
+run before: the same request with `fresh: true` starts the agent recorded
+for that session in its directory, with no conversation picked up, under
+the session's name or — when that runs — the next free name of its family.
+The directory and the agent still come only from this machine's record, so
+the phone cannot name either. The listener advertises `session-start-v1`
+so the apps offer it only to a build that knows it. Ending a session from
+the phone is `agent.session.exit.request`: `C-c`, the agent's own quit
+command, then `C-d` — never a forced kill, so an agent that will not quit is
+reported as still running.
 
 Two details worth knowing:
 
@@ -640,8 +653,8 @@ So on macOS the listener runs `caffeinate -s -w <its pid>` for as long as
 it lives. `-s` is honoured **on AC power only** — on battery macOS ignores
 it, so a laptop still sleeps and nothing drains. The display still turns
 off; a closed lid still sleeps. Activity Monitor shows the daemon under
-"Preventing Sleep". It holds even when no agent session is open: resuming a
-past session from the phone needs this Mac awake to answer. Opt out with `--no-keep-awake` or `"keepAwake": false`
+"Preventing Sleep". It holds even when no agent session is open: starting a
+session from the phone needs this Mac awake to answer. Opt out with `--no-keep-awake` or `"keepAwake": false`
 in `~/.hwip/config.json`; the log's `keep-awake:` line says which way it
 went.
 
@@ -691,16 +704,17 @@ tmux's `session_created` in epoch seconds). The app uses it to keep one run's
 conversation apart from the one before it under the same name; a chunk read
 after a restart keeps the run it was recorded in. What a session writes with no
 run to name (a name whose tmux session has ended while its file is still written
-to) is not recorded: the server takes no chunk without a run. The listener's record of past
-sessions keeps runs apart the same way: closing `hwip cc` and starting it again
-in the same folder leaves the first run as a past session of its own (the
-newest ten runs of a name are kept, 100 in all, and up to 50 are reported to
-the phone). Each run is reported with the block of chunk numbers it took — the
-first and, once it has ended, the last — kept in `run-seqs.json` next to the
-registry, so the server reads one run's conversation from that range instead of
-every chunk the name ever had. Deleting a past run from the phone forgets that
-run on this machine too, even while a later run of the same name is going; the
-run that is going is refused (`still_running`).
+to) is not recorded: the server takes no chunk without a run. The listener's record of
+runs keeps them apart the same way: closing `hwip cc` and starting it again
+in the same folder leaves the first run as a run of its own (the newest ten
+runs of a name are kept, 100 in all). The phone is told only the projects this
+machine ran lately — up to 12, each agent of a project once with the newest
+session it ran there — which is the list a new session is started from. A
+running run is reported with the first chunk number it took, kept in
+`run-seqs.json` next to the registry, so the server reads that run's
+conversation from there instead of every chunk the name ever had. An older app
+that deletes an ended run also asks this machine to forget it; the run that is
+going is refused (`still_running`).
 
 When a session waits for your approval, the listener also sends what it is waiting
 for — the tool, the command or the diff, and the answers — so the app can show it

package/dist/device-presence.d.ts

@@ -1,3 +1,9 @@
+/**
+ * This build reads `fresh` on a resume request (`listener.ts` `handleSessionResumeRequest`): the phone may start a new
+ * session in a recorded session's project. An older listener would resume the recorded conversation instead, so the apps
+ * offer it only to a computer that lists this.
+ */
+export declare const SESSION_START_CAPABILITY = "session-start-v1";
 /** The one message both halves of presence ride; the server answers
  *  `listener.presence.ack` or `listener.presence.error`. */
 export declare const LISTENER_PRESENCE = "listener.presence";

package/dist/device-presence.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = void 0;
+exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = exports.SESSION_START_CAPABILITY = void 0;
 /**
  * Per-device E2E (ADR-0007) — put this machine's public key on its device
  * record, so other devices can wrap pushes and files for it.
@@ -28,13 +28,20 @@ exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = void 0;
  * a file in chunks only for a device that lists `file-chunk-v1`, and one over
  * the relay's ceiling over LAN only to one that lists `lan-large-v1`; an app
  * offers `once` schedules and schedules into a session only to one that lists
- * `schedule-session-v1`. In one frame
+ * `schedule-session-v1`, and a new session in a project only to one that
+ * lists `session-start-v1`. In one frame
  * with the key, because a server from before `capabilities` answers a frame
  * that carries nothing else it knows with an error.
  */
 const file_crypto_js_1 = require("./file-crypto.js");
 const lan_receiver_js_1 = require("./lan-receiver.js");
 const schedule_js_1 = require("./schedule.js");
+/**
+ * This build reads `fresh` on a resume request (`listener.ts` `handleSessionResumeRequest`): the phone may start a new
+ * session in a recorded session's project. An older listener would resume the recorded conversation instead, so the apps
+ * offer it only to a computer that lists this.
+ */
+exports.SESSION_START_CAPABILITY = 'session-start-v1';
 /** The one message both halves of presence ride; the server answers
  *  `listener.presence.ack` or `listener.presence.error`. */
 exports.LISTENER_PRESENCE = 'listener.presence';
@@ -45,7 +52,7 @@ const createDeviceKeyRegistration = (deps) => {
     const register = async () => {
         try {
             const publicKey = await deps.publicKey();
-            const sent = deps.send({ type: exports.LISTENER_PRESENCE, data: { publicKey, capabilities: [file_crypto_js_1.FILE_CHUNK_CAPABILITY, lan_receiver_js_1.LAN_LARGE_CAPABILITY, schedule_js_1.SCHEDULE_SESSION_CAPABILITY] } });
+            const sent = deps.send({ type: exports.LISTENER_PRESENCE, data: { publicKey, capabilities: [file_crypto_js_1.FILE_CHUNK_CAPABILITY, lan_receiver_js_1.LAN_LARGE_CAPABILITY, schedule_js_1.SCHEDULE_SESSION_CAPABILITY, exports.SESSION_START_CAPABILITY] } });
             if (!sent)
                 deps.log('device key: not registered — no connection right now, retried at the next open');
             return sent;

package/dist/keep-awake.js

@@ -30,10 +30,10 @@ const startKeepAwake = (opts) => {
     // Never keep the event loop alive on the child's account: the daemon's
     // lifetime is the socket loop's, and `-w` ties caffeinate to it anyway.
     child.unref();
-    // Held with no agent session open too: the phone resumes a past session
-    // or starts one only while this Mac is awake to answer (C25 — say so
+    // Held with no agent session open too: the phone starts a session
+    // only while this Mac is awake to answer (C25 — say so
     // rather than let the Mac's sleeplessness go unexplained).
-    opts.log(`keep-awake: caffeinate -s -w ${pid} — blocks idle sleep on AC power only, even with no agent session open, so the phone can resume one (--no-keep-awake to disable)`);
+    opts.log(`keep-awake: caffeinate -s -w ${pid} — blocks idle sleep on AC power only, even with no agent session open, so the phone can start one (--no-keep-awake to disable)`);
     return {
         stop: () => {
             if (stopped)

package/dist/listener.d.ts

@@ -222,31 +222,8 @@ export type StaleConnectionAction =
  * tested as what it is: two guards around one lever.
  */
 export declare const staleConnectionAction: (message: unknown, drops: number) => StaleConnectionAction;
-export declare const KNOWN_SESSIONS_REPORTED = 50;
-export interface ReportedKnownSession {
-    name: string;
-    agentKind: string;
-    project?: string;
-    label?: string;
-    /** The run's id and start (hwip docs/session-runs.md); absent for entries recorded before runs. */
-    runId?: string;
-    startedAt?: string;
-    /** The seq block the run's chunks took (Q24): the server reads its conversation from that key range alone. */
-    firstSeq?: number;
-    lastSeq?: number;
-    /** The later tmux sessions the run went on in (Q35): the server ends another run's push window at their start. */
-    tmuxRunIds?: string[];
-    /** The last name the agent gave the run, and who gave it (hwip docs/session-runs.md Q39): what the phone calls it once ended. */
-    providerSessionName?: string;
-    providerSessionNameSource?: ProviderNameSource;
-    /** Whether starting the run again picks its conversation back up (Q43) — never the conversation id itself. */
-    resumable: boolean;
-    lastSeenAt: string;
-}
 /** Each live run's first seq, for the report (Q24). A run that has recorded nothing yet has none. */
 export declare const withRunSeqs: (sessions: AgentSession[], seqs?: Map<string, RunSeqs>) => AgentSession[];
-export declare const knownSessionsToReport: (live: readonly AgentSession[], now?: number, seqs?: Map<string, RunSeqs>) => ReportedKnownSession[];
-export declare const knownSessionsFingerprint: (known: ReportedKnownSession[]) => string;
 export declare const sessionsFingerprint: (sessions: AgentSession[]) => string;
 /** True when this cycle's inventory must be sent: it changed, or the
  *  idle heartbeat is due. */
@@ -551,6 +528,12 @@ export interface SessionResumeRequest {
      * it reads as a run id.
      */
     runId?: string;
+    /**
+     * A new session in that session's project, not the session again (hwip docs/session-runs.md Q47): the recorded
+     * directory and agent, no conversation picked up, and beside the name when it runs. Read only when it is `true`.
+     * Advertised as `SESSION_START_CAPABILITY` (`device-presence.ts`) — an older listener would resume the recorded conversation instead.
+     */
+    fresh?: boolean;
     requestId?: string;
 }
 export interface SessionResumeResult {
@@ -638,7 +621,7 @@ export interface SessionForgetResult {
  * running, so only actually running that name again restores it.
  *
  * The refusals: unknown name is nothing to delete rather than something to
- * guess at. Still running means it is not a past session at all — the phone is
+ * guess at. Still running means it is not an ended run at all — the phone is
  * looking at a live one, and ending it is a different request that this must
  * not quietly stand in for.
  */

package/dist/listener.js

@@ -25,9 +25,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withSettledPrompts = exports.PROMPT_SEAL_WAIT_MS = exports.withBlockedPrompts = exports.setPromptSealer = exports.deriveSessionState = exports.resetSessionStates = exports.continueRuns = exports.runIdOfEpoch = exports.__checkoutCacheSize = exports.parseSessionName = exports.resetPaneFitClaims = exports.tmuxTargetFor = exports.subagentTranscriptFor = exports.recordTargets = exports.recordSubagentTranscripts = exports.isSubagentSessionName = exports.detectRemoteAgent = exports.sessionLiveness = exports.sessionExists = exports.liveSessionNames = exports.tmuxArgs = exports.silenceListenerLog = exports.invalidateTmuxSocketCache = exports.wheelInput = exports.wheelEvents = exports.WHEEL_STATE_FORMAT = exports.resolveWheel = exports.resolveKeys = exports.probePane = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.commandsReportDue = exports.commandsFingerprint = exports.COMMAND_SCAN_INTERVAL_MS = exports.sessionsReportDue = exports.sessionsFingerprint = exports.knownSessionsFingerprint = exports.knownSessionsToReport = exports.withRunSeqs = exports.KNOWN_SESSIONS_REPORTED = exports.staleConnectionAction = exports.askedToReconnect = exports.MAX_STALE_CONNECTION_DROPS = exports.createReportAckWatch = exports.REPORT_ACK_TIMEOUT_MS = exports.SESSION_REPORT_HEARTBEAT_MS = exports.SESSION_REPORT_INTERVAL_MS = exports.heartbeatVerdict = exports.pingDue = exports.PING_IDLE_MS = void 0;
-exports.pendingInputDecrypts = exports.MAX_PENDING_DECRYPTS = exports.MAX_INPUT_LANES = exports.validateInputMessage = exports.MAX_INPUT_BODY_CHARS = exports.MAX_INPUT_KEYS = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.fitSealedFrame = exports.SEALED_FRAME_MAX_BYTES = exports.stopAllStreams = exports.stopStream = exports.stopStreamOf = exports.handleTurnWatch = exports.sealTurnBatch = exports.resolveWatchTranscript = exports.MAX_CONCURRENT_STREAMS = exports.STREAM_RENEW_FRESH_MS = exports.STREAM_LEASE_MS = exports.claimFrameSend = exports.hasFrameBudget = exports.streamCadence = exports.MAX_FRAMES_PER_SEC = exports.BURST_WINDOW_MS = exports.BURST_INTERVAL_MS = exports.STREAM_INTERVAL_MS = exports.STREAM_CAPTURE_LINES = exports.scheduleInjectSnapshots = exports.historyLinesIn = exports.cursorLineFor = exports.parsePaneGeometry = exports.STREAM_GEOMETRY_FORMAT = exports.handleScreenHistoryRequest = exports.SCREEN_HISTORY_MAX_LINES = exports.handleSessionForgetRequest = exports.handleSessionExitRequest = exports.SESSION_EXIT_STEP_MS = exports.handleSessionResumeRequest = exports.handleScheduleListRequest = exports.handleFileBlobRequest = exports.handleFileTreeRequest = exports.handleDiffFileRequest = exports.handleDiffFilesRequest = exports.fileViewBytes = exports.handleScreenRequest = exports.setSubscriberTrust = exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = void 0;
-exports.handleListener = exports.liveScheduleRunnerDeps = exports.listenerSettings = exports.resolveWsUrl = exports.streamSession = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.displayFolder = exports.claimLanFile = exports.saveFileFromS3 = exports.downloadSealedEach = exports.answerFileBound = exports.downloadAttachments = exports.setAttachmentContext = exports.shellTextRefusal = exports.writeRemoteMarker = exports.isInventoried = exports.syncTmuxAgentNames = exports.recordInventory = exports.collectSessionsVerbose = exports.handleCommandInput = void 0;
+exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = exports.withSettledPrompts = exports.PROMPT_SEAL_WAIT_MS = exports.withBlockedPrompts = exports.setPromptSealer = exports.deriveSessionState = exports.resetSessionStates = exports.continueRuns = exports.runIdOfEpoch = exports.__checkoutCacheSize = exports.parseSessionName = exports.resetPaneFitClaims = exports.tmuxTargetFor = exports.subagentTranscriptFor = exports.recordTargets = exports.recordSubagentTranscripts = exports.isSubagentSessionName = exports.detectRemoteAgent = exports.sessionLiveness = exports.sessionExists = exports.liveSessionNames = exports.tmuxArgs = exports.silenceListenerLog = exports.invalidateTmuxSocketCache = exports.wheelInput = exports.wheelEvents = exports.WHEEL_STATE_FORMAT = exports.resolveWheel = exports.resolveKeys = exports.probePane = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.commandsReportDue = exports.commandsFingerprint = exports.COMMAND_SCAN_INTERVAL_MS = exports.sessionsReportDue = exports.sessionsFingerprint = exports.withRunSeqs = exports.staleConnectionAction = exports.askedToReconnect = exports.MAX_STALE_CONNECTION_DROPS = exports.createReportAckWatch = exports.REPORT_ACK_TIMEOUT_MS = exports.SESSION_REPORT_HEARTBEAT_MS = exports.SESSION_REPORT_INTERVAL_MS = exports.heartbeatVerdict = exports.pingDue = exports.PING_IDLE_MS = void 0;
+exports.recordInventory = exports.collectSessionsVerbose = exports.handleCommandInput = exports.pendingInputDecrypts = exports.MAX_PENDING_DECRYPTS = exports.MAX_INPUT_LANES = exports.validateInputMessage = exports.MAX_INPUT_BODY_CHARS = exports.MAX_INPUT_KEYS = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.fitSealedFrame = exports.SEALED_FRAME_MAX_BYTES = exports.stopAllStreams = exports.stopStream = exports.stopStreamOf = exports.handleTurnWatch = exports.sealTurnBatch = exports.resolveWatchTranscript = exports.MAX_CONCURRENT_STREAMS = exports.STREAM_RENEW_FRESH_MS = exports.STREAM_LEASE_MS = exports.claimFrameSend = exports.hasFrameBudget = exports.streamCadence = exports.MAX_FRAMES_PER_SEC = exports.BURST_WINDOW_MS = exports.BURST_INTERVAL_MS = exports.STREAM_INTERVAL_MS = exports.STREAM_CAPTURE_LINES = exports.scheduleInjectSnapshots = exports.historyLinesIn = exports.cursorLineFor = exports.parsePaneGeometry = exports.STREAM_GEOMETRY_FORMAT = exports.handleScreenHistoryRequest = exports.SCREEN_HISTORY_MAX_LINES = exports.handleSessionForgetRequest = exports.handleSessionExitRequest = exports.SESSION_EXIT_STEP_MS = exports.handleSessionResumeRequest = exports.handleScheduleListRequest = exports.handleFileBlobRequest = exports.handleFileTreeRequest = exports.handleDiffFileRequest = exports.handleDiffFilesRequest = exports.fileViewBytes = exports.handleScreenRequest = exports.setSubscriberTrust = void 0;
+exports.handleListener = exports.liveScheduleRunnerDeps = exports.listenerSettings = exports.resolveWsUrl = exports.streamSession = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.displayFolder = exports.claimLanFile = exports.saveFileFromS3 = exports.downloadSealedEach = exports.answerFileBound = exports.downloadAttachments = exports.setAttachmentContext = exports.shellTextRefusal = exports.writeRemoteMarker = exports.isInventoried = exports.syncTmuxAgentNames = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -55,6 +55,7 @@ const transcript_tail_js_1 = require("./transcript-tail.js");
 const listener_service_js_1 = require("./listener-service.js");
 const agent_state_js_1 = require("./agent-state.js");
 const inventory_offload_js_1 = require("./inventory-offload.js");
+const recent_projects_js_1 = require("./recent-projects.js");
 const sessions_report_js_1 = require("./sessions-report.js");
 const agent_rules_fetch_js_1 = require("./agent-rules-fetch.js");
 const crypto_js_1 = require("./crypto.js");
@@ -295,41 +296,12 @@ const staleConnectionAction = (message, drops) => {
     return drops < exports.MAX_STALE_CONNECTION_DROPS ? 'drop' : 'exhausted';
 };
 exports.staleConnectionAction = staleConnectionAction;
-exports.KNOWN_SESSIONS_REPORTED = 50;
 /** Each live run's first seq, for the report (Q24). A run that has recorded nothing yet has none. */
 const withRunSeqs = (sessions, seqs = (0, run_seqs_js_1.runSeqsByRun)()) => sessions.map((s) => {
     const block = s.runId ? seqs.get((0, run_seqs_js_1.runSeqsKey)(s.name, s.runId)) : undefined;
     return block ? { ...s, firstSeq: block.firstSeq } : s;
 });
 exports.withRunSeqs = withRunSeqs;
-const knownSessionsToReport = (live, now = Date.now(), seqs = (0, run_seqs_js_1.runSeqsByRun)()) => {
-    // By name, kind AND run: a slot that is live under claude may still hold an
-    // ended pi run — or an ended claude run before this one — and that run is a
-    // past session. Excluding the whole name would drop it from the report
-    // exactly the way the registry used to drop it from disk. The live run
-    // itself stays out for the reason below.
-    const running = new Set(live.map((s) => (0, session_registry_js_1.runKey)(s.name, s.agentKind, s.runId)));
-    return (0, session_registry_js_1.knownSessions)(now)
-        .filter((e) => !running.has((0, session_registry_js_1.runKey)(e.name, e.agentKind, e.runId)))
-        .slice(0, exports.KNOWN_SESSIONS_REPORTED)
-        .map((e) => ({
-        name: e.name,
-        agentKind: e.agentKind,
-        ...(e.project ? { project: e.project } : {}),
-        ...(e.label ? { label: e.label } : {}),
-        ...(e.runId ? { runId: e.runId } : {}),
-        ...(e.startedAt ? { startedAt: e.startedAt } : {}),
-        ...(e.runId ? seqs.get((0, run_seqs_js_1.runSeqsKey)(e.name, e.runId)) : undefined),
-        ...(e.tmuxRunIds?.length ? { tmuxRunIds: e.tmuxRunIds } : {}),
-        ...(e.providerSessionName ? { providerSessionName: e.providerSessionName } : {}),
-        ...(e.providerSessionName && e.providerSessionNameSource ? { providerSessionNameSource: e.providerSessionNameSource } : {}),
-        resumable: isResumable(e),
-        lastSeenAt: e.lastSeenAt,
-    }));
-};
-exports.knownSessionsToReport = knownSessionsToReport;
-const knownSessionsFingerprint = (known) => known.map((k) => `${k.name}${k.agentKind}${k.runId ?? ''}${k.lastSeenAt}${k.firstSeq ?? ''}${k.lastSeq ?? ''}${k.tmuxRunIds?.join(',') ?? ''} ${k.providerSessionNameSource ?? ''} ${k.providerSessionName ?? ''} ${k.resumable}`).sort().join('|');
-exports.knownSessionsFingerprint = knownSessionsFingerprint;
 const sessionsFingerprint = (sessions) => sessions
     .map((s) => JSON.stringify([
     s.name, s.attached, s.agentKind, s.agentSessionId ?? null,
@@ -369,6 +341,12 @@ const RATE_LIMIT_TOKENS = 120;
 const RATE_LIMIT_WINDOW_MS = 60_000;
 /** What one command submit costs, keeping its ceiling at the old 30/min. */
 const SUBMIT_COST = 4;
+/**
+ * What a fresh start costs on its family's own bucket (`start:<family base>`): three new agents a minute. Each one is a
+ * process left running, and every name of the family leads to the same bucket, so a session budget of 30 a minute
+ * cannot fill the family's 20 names in one burst.
+ */
+const FRESH_START_COST = RATE_LIMIT_TOKENS / 3;
 // Shells are refused: a shell prompt + send-keys = arbitrary command exec.
 const SHELL_COMMANDS = new Set(['bash', 'zsh', 'fish', 'sh', 'dash', 'ksh', 'tcsh', 'csh', 'pwsh']);
 // Auth-failure close codes: retrying with the same bad credentials hammers
@@ -1484,11 +1462,6 @@ const conversationRunning = (known, live) => {
         return current?.agentKind === known.agentKind && current.agentSessionId === id;
     });
 };
-/** What the report says about a run: the same answer a resume of it would act on. */
-const isResumable = (known) => {
-    const agent = remote_agents_js_1.REMOTE_AGENTS.find((a) => a.kind === known.agentKind);
-    return agent !== undefined && resumableConversation(agent, known) !== null;
-};
 /**
  * Start a remembered session again, detached, and tell the phone what happened.
  * Returns true when the message was ours to answer.
@@ -1546,13 +1519,16 @@ const handleSessionResumeRequest = (req, send) => {
     // the family `hwip cc` would pick (Q41), counted from the family base so a
     // busy `<base>-2` leads to `<base>-3`. A request without a run id is an
     // older app that only knows the name, and still gets the refusal it renders.
+    // A fresh start asks for a new session, so a live name is no refusal either, and no conversation is picked up —
+    // the live one holding the recorded conversation included.
+    const fresh = req.fresh === true;
     const live = new Set((0, tmux_liveness_js_1.liveSessionNames)() ?? []);
     const target = !live.has(sessionName)
         ? sessionName
-        : runId !== undefined
+        : runId !== undefined || fresh
             ? (0, wrapper_js_1.familyNames)(familyBase(sessionName)).find((name) => !live.has(name))
             : undefined;
-    if (!target || conversationRunning(known, live))
+    if (!target || (!fresh && conversationRunning(known, live)))
         return reply({ error: 'already_running' });
     if (!(0, session_registry_js_1.sessionDirectoryExists)(known)) {
         (0, listener_log_js_1.log)(`✗ resume ${sessionName}: ${known.cwd} is gone`);
@@ -1563,6 +1539,11 @@ const handleSessionResumeRequest = (req, send) => {
         (0, listener_log_js_1.log)(`✗ resume ${sessionName}: no binary for agent kind ${known.agentKind}`);
         return reply({ error: 'unknown_agent' });
     }
+    // A fresh start leaves one more process running each time, so the family pays on a bucket of its own as well —
+    // charged only here, where it starts one: a refusal above says why, not that the budget ran out.
+    if (fresh && !(0, exports.checkRateLimit)(`start:${familyBase(sessionName)}`, undefined, FRESH_START_COST)) {
+        return reply({ error: 'rate_limited' });
+    }
     // argv, never a shell string: the binary comes from the agent table and the
     // directory from our own record, and neither is concatenated into anything
     // a shell would re-parse. A recorded label means the session carried
@@ -1572,7 +1553,7 @@ const handleSessionResumeRequest = (req, send) => {
     const sidecar = known.label && known.project
         ? [';', 'set-option', config_js_1.SESSION_PROJECT_OPTION, known.project, ';', 'set-option', config_js_1.SESSION_LABEL_OPTION, known.label]
         : [];
-    const conversation = resumableConversation(agent, known);
+    const conversation = fresh ? null : resumableConversation(agent, known);
     // tmux gives the new pane this client's PATH. A login service's PATH has none
     // of the agent directories, so they go on as schedule launches add them —
     // otherwise the agent is not found and the session ends as it starts.
@@ -1583,7 +1564,7 @@ const handleSessionResumeRequest = (req, send) => {
     }
     const resumedFrom = conversation ? ` (conversation ${conversation.id.slice(0, 8)})` : '';
     const beside = target === sessionName ? '' : ` as ${target}`;
-    (0, listener_log_js_1.log)(`⟲ resume ${sessionName}${beside}: ${agent.binary}${resumedFrom} in ${known.cwd}`);
+    (0, listener_log_js_1.log)(`${fresh ? '＋ start' : '⟲ resume'} ${sessionName}${beside}: ${agent.binary}${resumedFrom} in ${known.cwd}`);
     return reply({ resumed: true, sessionName: target });
 };
 exports.handleSessionResumeRequest = handleSessionResumeRequest;
@@ -1708,7 +1689,7 @@ exports.handleSessionExitRequest = handleSessionExitRequest;
  * running, so only actually running that name again restores it.
  *
  * The refusals: unknown name is nothing to delete rather than something to
- * guess at. Still running means it is not a past session at all — the phone is
+ * guess at. Still running means it is not an ended run at all — the phone is
  * looking at a live one, and ending it is a different request that this must
  * not quietly stand in for.
  */
@@ -5296,14 +5277,12 @@ const streamSession = (wsUrl, apiKey) => {
             // Unchanged inventory + heartbeat not due → skip the send.
             // The 5 s local poll above still ran, so a change is never
             // delayed; only the no-op reports (idle listener) are culled.
-            // Past sessions ride the report that already exists rather than a
-            // request of their own: the phone is already reading this device
-            // record, and a second round trip would need its own timeout, its
-            // own failure wording and its own staleness question.
-            const seqs = (0, run_seqs_js_1.runSeqsByRun)();
-            const reported = (0, exports.withRunSeqs)(sessions, seqs);
-            const known = (0, exports.knownSessionsToReport)(sessions, Date.now(), seqs);
-            const fingerprint = `${(0, exports.sessionsFingerprint)(reported)}␞${(0, exports.knownSessionsFingerprint)(known)}`;
+            // The projects a new session can start in ride the report that
+            // already exists rather than a request of their own: the phone is
+            // already reading this device record (recent-projects.ts).
+            const reported = (0, exports.withRunSeqs)(sessions);
+            const recent = (0, recent_projects_js_1.recentProjectsToReport)();
+            const fingerprint = `${(0, exports.sessionsFingerprint)(reported)}␞${recent ? JSON.stringify(recent) : '-'}`;
             if (!(0, exports.sessionsReportDue)(fingerprint, lastSentFingerprint, lastSentAtMs, Date.now())) {
                 return;
             }
@@ -5313,7 +5292,7 @@ const streamSession = (wsUrl, apiKey) => {
             // One message when it fits; past 24 KB, parts (sessions-report.ts): API Gateway closes a
             // socket on a frame over 32 KB, so an uncut report from a machine with ~100 sessions would
             // drop the connection on every send.
-            const plan = (0, sessions_report_js_1.planSessionsReport)(reported, known);
+            const plan = (0, sessions_report_js_1.planSessionsReport)(reported, recent);
             if (plan.messages.length > 1) {
                 (0, listener_log_js_1.log)(`⧉ inventory of ${plan.sessionCount} session(s), ${Math.round(plan.wholeBytes / 1024)} KB, is over the ${sessions_report_js_1.SESSIONS_REPORT_MAX_BYTES / 1024} KB message limit — sent in ${plan.messages.length - 1} parts + names`);
                 for (const name of plan.oversized)

package/dist/recent-projects.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The projects the phone can start a new session in (hwip docs/session-runs.md Q47, Q49), as the
+ * `listener.sessions` report carries them.
+ *
+ * The phone never names a directory: it names a session, and the fresh start reads that session's
+ * folder and agent back from this machine's registry (`recallSession` · `recallRun`). So each entry
+ * is one agent of one project with the newest session it ran there. The list is newest first and
+ * carries no times — a running session's `lastSeenAt` moves on every sweep, and a field that changes
+ * every five seconds would defeat the report's unchanged-inventory gate.
+ */
+export interface RecentProject {
+    /** The newest session of this project and agent: what a fresh start is asked from. */
+    name: string;
+    agentKind: string;
+    /** Absent when the registry has none; the phone then calls the project by the session's name. */
+    project?: string;
+}
+/** A short list: the projects a person works in lately, not every folder the machine ever ran one in. */
+export declare const RECENT_PROJECTS_MAX = 12;
+/** Each project's agents, from the newest session of each, in the order `known` gives (newest first). */
+export declare const recentProjects: (known: readonly {
+    name: string;
+    agentKind: string;
+    project?: string;
+}[]) => RecentProject[];
+/**
+ * The list for this report, or undefined when the registry would not read — an empty list would
+ * clear what the server holds, and the phone would lose every project to start in.
+ */
+export declare const recentProjectsToReport: (now?: number) => RecentProject[] | undefined;
+//# sourceMappingURL=recent-projects.d.ts.map

package/dist/recent-projects.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * The projects the phone can start a new session in (hwip docs/session-runs.md Q47, Q49), as the
+ * `listener.sessions` report carries them.
+ *
+ * The phone never names a directory: it names a session, and the fresh start reads that session's
+ * folder and agent back from this machine's registry (`recallSession` · `recallRun`). So each entry
+ * is one agent of one project with the newest session it ran there. The list is newest first and
+ * carries no times — a running session's `lastSeenAt` moves on every sweep, and a field that changes
+ * every five seconds would defeat the report's unchanged-inventory gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recentProjectsToReport = exports.recentProjects = exports.RECENT_PROJECTS_MAX = void 0;
+const session_registry_js_1 = require("./session-registry.js");
+/** A short list: the projects a person works in lately, not every folder the machine ever ran one in. */
+exports.RECENT_PROJECTS_MAX = 12;
+/** `<parent>.<pane digits>` — a subagent pane has no project of its own (tmux turns `.` in a name into `_`). */
+const isSubagent = (name) => /\.\d+$/.test(name);
+/** A session a schedule started: starting from it would copy the scheduled run, not the project. */
+const isScheduled = (name) => name.includes('-sched-');
+/** Each project's agents, from the newest session of each, in the order `known` gives (newest first). */
+const recentProjects = (known) => {
+    const projects = new Set();
+    const seen = new Set();
+    const listed = [];
+    for (const e of known) {
+        if (isSubagent(e.name) || isScheduled(e.name))
+            continue;
+        const project = e.project || e.name;
+        if (!projects.has(project)) {
+            if (projects.size >= exports.RECENT_PROJECTS_MAX)
+                continue;
+            projects.add(project);
+        }
+        const key = `${project}\u0000${e.agentKind}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        listed.push({ name: e.name, agentKind: e.agentKind, ...(e.project ? { project: e.project } : {}) });
+    }
+    return listed;
+};
+exports.recentProjects = recentProjects;
+/**
+ * The list for this report, or undefined when the registry would not read — an empty list would
+ * clear what the server holds, and the phone would lose every project to start in.
+ */
+const recentProjectsToReport = (now = Date.now()) => (0, session_registry_js_1.registryUnreadable)() ? undefined : (0, exports.recentProjects)((0, session_registry_js_1.knownSessions)(now));
+exports.recentProjectsToReport = recentProjectsToReport;

package/dist/sessions-report.d.ts

@@ -14,7 +14,7 @@
  *   - parts of at most `SESSIONS_REPORT_MAX_BYTES`, each `listener.sessions`
  *     with `partial: true` and some of the sessions — the server upserts what
  *     it is given, by name, and acks each part. The first part also carries
- *     `knownSessions` (once is enough);
+ *     `recentProjects` (once is enough);
  *   - then `listener.sessions.names` with every session name in the report, so
  *     the server can drop the sessions that are no longer there — what a
  *     whole-list report does by replacing the list.
@@ -44,9 +44,13 @@ export interface SessionsReportPlan {
     /** Identifies a report in parts; the server echoes it (and `part`) in each ack. Absent for one message. */
     reportId?: string;
 }
+/**
+ * `recentProjects` undefined leaves the field out, so the server keeps what it holds (an unreadable
+ * registry must not clear the phone's project list).
+ */
 export declare const planSessionsReport: (sessions: readonly {
     name: string;
-}[], knownSessions: readonly unknown[], maxBytes?: number, reportId?: () => string) => SessionsReportPlan;
+}[], recentProjects: readonly unknown[] | undefined, maxBytes?: number, reportId?: () => string) => SessionsReportPlan;
 /** How long a part waits for its ack before the report is given up (and tried again on the next poll). */
 export declare const SESSIONS_ACK_TIMEOUT_MS = 10000;
 /**

package/dist/sessions-report.js

@@ -15,7 +15,7 @@
  *   - parts of at most `SESSIONS_REPORT_MAX_BYTES`, each `listener.sessions`
  *     with `partial: true` and some of the sessions — the server upserts what
  *     it is given, by name, and acks each part. The first part also carries
- *     `knownSessions` (once is enough);
+ *     `recentProjects` (once is enough);
  *   - then `listener.sessions.names` with every session name in the report, so
  *     the server can drop the sessions that are no longer there — what a
  *     whole-list report does by replacing the list.
@@ -35,24 +35,29 @@ const node_crypto_1 = require("node:crypto");
 /** Under API Gateway's 32 KB frame, with room for the envelope and a long session or two. */
 exports.SESSIONS_REPORT_MAX_BYTES = 24 * 1024;
 const bytes = (text) => Buffer.byteLength(text, 'utf-8');
-const planSessionsReport = (sessions, knownSessions, maxBytes = exports.SESSIONS_REPORT_MAX_BYTES, reportId = node_crypto_1.randomUUID) => {
-    const whole = JSON.stringify({ type: 'listener.sessions', data: { sessions, knownSessions } });
+/**
+ * `recentProjects` undefined leaves the field out, so the server keeps what it holds (an unreadable
+ * registry must not clear the phone's project list).
+ */
+const planSessionsReport = (sessions, recentProjects, maxBytes = exports.SESSIONS_REPORT_MAX_BYTES, reportId = node_crypto_1.randomUUID) => {
+    const extras = recentProjects ? { recentProjects } : {};
+    const whole = JSON.stringify({ type: 'listener.sessions', data: { sessions, ...extras } });
     const wholeBytes = bytes(whole);
     if (wholeBytes <= maxBytes) {
         return { messages: [whole], sessionCount: sessions.length, wholeBytes, oversized: [], namesOversized: false };
     }
     const id = reportId();
-    const knownBytes = bytes(JSON.stringify({ knownSessions }));
+    const extrasBytes = bytes(JSON.stringify(extras));
     const envelopeBytes = bytes(JSON.stringify({
         type: 'listener.sessions',
         data: { sessions: [], partial: true, reportId: id, part: 999, parts: 999 },
     }));
     // Greedy: a session goes in the current part while it fits. The first part gives up room for
-    // `knownSessions`; no part gives up less than one session.
+    // `recentProjects`; no part gives up less than one session.
     const groups = [];
     const oversized = [];
     let current = [];
-    let budget = Math.max(maxBytes - envelopeBytes - knownBytes, 0);
+    let budget = Math.max(maxBytes - envelopeBytes - extrasBytes, 0);
     let used = 0;
     for (const session of sessions) {
         // +1 for the comma between sessions in the array.
@@ -72,7 +77,7 @@ const planSessionsReport = (sessions, knownSessions, maxBytes = exports.SESSIONS
     const parts = groups.length;
     const messages = groups.map((group, index) => JSON.stringify({
         type: 'listener.sessions',
-        data: { sessions: group, partial: true, reportId: id, part: index + 1, parts, ...(index === 0 ? { knownSessions } : {}) },
+        data: { sessions: group, partial: true, reportId: id, part: index + 1, parts, ...(index === 0 ? extras : {}) },
     }));
     const names = JSON.stringify({ type: 'listener.sessions.names', data: { names: sessions.map((s) => s.name), reportId: id } });
     messages.push(names);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hwip/cli",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Hwip CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",