@hwip/cli 0.1.22 → 0.1.23

package/README.md

@@ -799,6 +799,13 @@ installs on one machine don't fight over it):
 hwip: listener 1.25.0 is stale — restarting on 1.26.0
 ```
 
+With the login service installed, launchd (or systemd) does the restart —
+and it starts the install the plist was written from, which need not be
+the `hwip` on your PATH (Homebrew's next to an nvm node's, say). When the
+restarted daemon is still the older build, `hwip cc` says which install
+the service runs instead of restarting it again on every launch; re-run
+`hwip listener --install-service` from the `hwip` you use to repoint it.
+
 If the PID file is missing (a different account started the daemon, or
 it was removed by hand) the singleton guard can't see it. Find the real
 process instead:
@@ -1353,7 +1360,7 @@ hwip notify --title "Hello" --json
 | `forget <session>` | Drop an ended session from this machine's record, so it leaves the app's past list (and the resume whitelist — the same thing deleting the row on the phone does). Refuses a session that is still running: kill it first. `--ended` forgets every remembered session tmux no longer has, which is what a machine that launches agents under a fresh name per task eventually needs |
 | `test` | Verify connection and API key |
 | `trust [deviceId]` | Advanced — nothing needs it: every device on the account is pinned the first time hwip seals for it, and a changed key replaces its pin with a warning. Shows this computer's key fingerprint and the devices pinned here — compare each with the fingerprint the app shows on that device's page. It also lists the computers of the account not pinned here yet, with their fingerprints; the first send seals for each and pins it. With a `deviceId`, pin the key the account now lists for that device: prints the pinned and the listed fingerprint and asks first, `--yes` skips the question. `--reset` forgets every pin (each is pinned again as hwip sees it), and until then the listener answers a request for a screen in plaintext. Exit 0 done, 1 refused or declined, 2 not a device id |
-| `cc` · `codex` · `gemini` · `cursor` · `hermes` · `pi` · `opencode` · `kimi` · `grok` · `agy` · `qwen` · `auggie` · `kilo` · `copilot` · `kiro-cli` · `droid` | Run the agent in a `hwip-<project>` tmux session — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works; when that daemon stops within a second and a half (no key, no tmux, a rejected key) it prints the daemon's last log line instead of "autostarted". Once a day it asks npm whether a newer hwip is out and prints the update line (cached in `~/.hwip/update-check.json`; skipped under `CI` or `HWIP_NO_UPDATE_CHECK`). Trailing args pass through to the agent (`hwip cc --resume "..."`). On node 22.15+ the wrapper hands its process to tmux rather than waiting on it, so a running session shows no `hwip cc` of its own in `ps` — older runtimes and Windows keep the waiting wrapper `--detach` / `--label <x>` (front of the args) create without attaching / pin the name; `--wt <name>` runs it in a git worktree made for the session — see "Run agents through the wrapper" above. |
+| `cc` · `codex` · `gemini` · `cursor` · `hermes` · `pi` · `opencode` · `kimi` · `grok` · `agy` · `qwen` · `auggie` · `kilo` · `copilot` · `kiro-cli` · `droid` | Run the agent in a `hwip-<project>` tmux session — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works; when that daemon stops within a second and a half (no key, no tmux, a rejected key) it prints the daemon's last log line instead of "autostarted". Once a day it asks npm whether a newer hwip is out and prints the update line (cached in `~/.hwip/update-check.json`; skipped under `CI` or `HWIP_NO_UPDATE_CHECK`). Trailing args pass through to the agent (`hwip cc --resume "..."`). When the tmux session ends (not on a detach), it prints the command that picks the conversation back up — `hwip: to resume: claude --resume <id>  (or hwip cc --resume <id>)` — for `cc` · `codex` · `hermes` · `pi` · `opencode`, from the id the listener recorded while the session ran (a session shorter than one 5 s sweep has none yet, and gets no line); the tmux command runs under a small `sh` for this, so no node process waits on the session. On node 22.15+ the wrapper hands its process to tmux rather than waiting on it, so a running session shows no `hwip cc` of its own in `ps` — older runtimes and Windows keep the waiting wrapper `--detach` / `--label <x>` (front of the args) create without attaching / pin the name; `--wt <name>` runs it in a git worktree made for the session — see "Run agents through the wrapper" above. |
 | `worktree [clean]` | List the git worktrees `--wt` made (path, branch, and `in use` / `clean` / `never used` / what keeps it: uncommitted, untracked or ignored files, commits not pushed). `clean` removes the ones nothing keeps and prints why the others stay; `--dry-run` removes nothing and records nothing. A worktree you made by hand is never listed or removed. Exit 0, also when some stay; `clean` exits 1 when git refused a removal it had cleared or tmux could not be asked (the list still prints, without `in use`); 2 for an unknown subcommand. See "Run agents through the wrapper" for when the listener does the same on its own |
 | `schedule` | Start an agent session on a timer, in the background. The listener starts it, so it has to be running (installing the listener as a login service keeps it up). A run missed while the computer slept or the listener was down is skipped, never started late, and the phone is told. At most 20 schedules and 3 scheduled sessions at once; a session is asked to end after `--max-runtime` (never killed). Schedules live in `~/.local/state/hwip/schedules`. `schedule add <agent> (--at HH:MM \| --on YYYY-MM-DD --at HH:MM \| --every <N>m\|<N>h) [-- <agent args…>]` adds one: `<agent>` is an agent command above (`cc`, `codex`, …) and the project is this one; `--on` runs it once. `schedule add --session <name> (…) --prompt <text>` types the prompt into that running session instead of starting one (waits up to 30 min for it to be idle and its terminal quiet). `schedule [list]` shows them, with the next run and the last result (`--json` for scripts). `schedule rm <id>` removes one; a session it already started keeps running. Options: `--days <days>` (with `--at`: `daily`, `weekdays`, or day names like `mon,wed,fri`), `--prompt <text>` (typed into the session once the agent's status rules say it is idle: Claude Code, Codex, Gemini CLI and pi only), `--label <x>`, `--wt <branch>` (a git worktree for the branch, not with `--label`), `--max-runtime <N>m\|<N>h` (default 2h, at most the `--every` period; 5m to 24h). See *Scheduled sessions* |
 | `sh` | Open (or reattach) `hwip-<project>-sh`, a login shell the phone may type into — the one shell pane the listener does not refuse. `--label <x>` / `--detach` as for the agents; inside tmux it never attaches and prints a `switch-client` hint. Refuses a session of that name it did not open. Input must be addressed to this machine, is audited, and agents (`agent send`, `hwip_agent_send`) skip it — see [Defense](#defense) |

package/dist/args.js

@@ -203,6 +203,7 @@ exports.COMMAND_FLAGS = {
         'install-service', 'uninstall-service', 'service-status',
     ],
     'remote-hook': [],
+    'resume-hint': ['session', 'type', 'at'],
 };
 /**
  * Flags the command would ignore, in the order typed. A typo (`--titel`) used

package/dist/cli.js

@@ -815,6 +815,8 @@ const main = async () => {
             return (await import('./listener.js')).handleListener(args);
         case 'remote-hook':
             return handleRemoteHook(args);
+        case 'resume-hint':
+            return (await import('./resume-hint.js')).handleResumeHint(args);
         default:
             printError(`Unknown command: ${command}`, (0, args_js_1.flagOn)(args, 'json', true));
             printUsage();

package/dist/resume-hint.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The line `hwip cc` / `hwip pi` leaves once its tmux session has ended: the
+ * command that picks the conversation back up (`claude --resume <id>`).
+ */
+import { type RemoteAgent } from './remote-agents.js';
+import { type KnownSession } from './session-registry.js';
+export interface ResumeHintDeps {
+    recall: (name: string, agentKind: string) => KnownSession | null;
+    /** Whether tmux still has the session: a detach returns from `tmux new` as well as an exit does. */
+    alive: (name: string) => boolean;
+    cwd: string;
+}
+/**
+ * What to print after the tmux session `session` of `agent` returned, or null
+ * when there is nothing true to say. `since` is when this `hwip` launched (ms):
+ * a record the sweep has not touched since is an earlier run of the same name,
+ * whose conversation is not the one just closed. A session shorter than one
+ * sweep has no record yet, and gets no line rather than a guess.
+ */
+export declare const resumeHint: (session: string, agent: Pick<RemoteAgent, "kind" | "binary" | "subcommands" | "resumeArgs">, since: number, deps?: ResumeHintDeps) => string | null;
+/**
+ * `hwip resume-hint --session <tmux name> --type <agent kind> --at <ms>` — the
+ * call `withResumeHint` leaves after tmux. Not for people: it always exits 0,
+ * so a missing record or a failed read never changes the agent's exit status.
+ */
+export declare const handleResumeHint: (args: Record<string, string | boolean>) => number;
+//# sourceMappingURL=resume-hint.d.ts.map

package/dist/resume-hint.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * The line `hwip cc` / `hwip pi` leaves once its tmux session has ended: the
+ * command that picks the conversation back up (`claude --resume <id>`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleResumeHint = exports.resumeHint = void 0;
+const remote_agents_js_1 = require("./remote-agents.js");
+const session_registry_js_1 = require("./session-registry.js");
+const tmux_liveness_js_1 = require("./tmux-liveness.js");
+const wrapper_js_1 = require("./wrapper.js");
+const defaultDeps = () => ({
+    recall: (name, kind) => (0, session_registry_js_1.recallRun)(name, kind),
+    // `unknown` included: no tmux server answering after `tmux new` returned is the last session gone with it.
+    alive: (name) => (0, tmux_liveness_js_1.sessionLiveness)(name) === 'running',
+    cwd: process.cwd(),
+});
+/**
+ * What to print after the tmux session `session` of `agent` returned, or null
+ * when there is nothing true to say. `since` is when this `hwip` launched (ms):
+ * a record the sweep has not touched since is an earlier run of the same name,
+ * whose conversation is not the one just closed. A session shorter than one
+ * sweep has no record yet, and gets no line rather than a guess.
+ */
+const resumeHint = (session, agent, since, deps = defaultDeps()) => {
+    if (!agent.resumeArgs || deps.alive(session))
+        return null;
+    const run = deps.recall(session, agent.kind);
+    if (!run?.agentSessionId || Date.parse(run.lastSeenAt) < since)
+        return null;
+    const args = agent.resumeArgs(run.agentSessionId, run.cwd);
+    if (!args)
+        return null;
+    const where = run.cwd === deps.cwd ? '' : ` in ${(0, wrapper_js_1.shellQuote)(run.cwd)}`;
+    const rest = args.map(wrapper_js_1.shellQuote).join(' ');
+    return `hwip: to resume${where}: ${agent.binary} ${rest}  (or hwip ${agent.subcommands[0]} ${rest})`;
+};
+exports.resumeHint = resumeHint;
+/**
+ * `hwip resume-hint --session <tmux name> --type <agent kind> --at <ms>` — the
+ * call `withResumeHint` leaves after tmux. Not for people: it always exits 0,
+ * so a missing record or a failed read never changes the agent's exit status.
+ */
+const handleResumeHint = (args) => {
+    const agent = remote_agents_js_1.REMOTE_AGENTS.find((a) => a.kind === args.type);
+    const since = Number(args.at);
+    if (typeof args.session !== 'string' || !agent || !Number.isFinite(since))
+        return 0;
+    try {
+        const line = (0, exports.resumeHint)(args.session, agent, since);
+        if (line)
+            console.log(line);
+    }
+    catch {
+        return 0;
+    }
+    return 0;
+};
+exports.handleResumeHint = handleResumeHint;

package/dist/wrapper.d.ts

@@ -121,7 +121,18 @@ export declare const splitAgentOptions: (extra: string[]) => {
     rest: string[];
     error?: string;
 };
+export declare const shellQuote: (s: string) => string;
 export declare const targetForAgent: (agent: string, extra: string[], agentKind?: string, opts?: AgentLaunchOptions) => SpawnTarget;
+/**
+ * `target` (an attached `tmux new`) run under `sh`, which outlives tmux by the
+ * one `hwip resume-hint` call and then exits with tmux's status. `sh` rather
+ * than this process waiting: the wrapper hands itself over with execve so no
+ * node heap sits resident for the whole session, and `sh` costs next to none.
+ */
+export declare const withResumeHint: (target: SpawnTarget, agent: Pick<RemoteAgent, "kind" | "resumeArgs">, since: number, hwip?: {
+    node: string;
+    cli: string;
+}) => SpawnTarget;
 /**
  * Whether the daemon on record is running a different build than the one
  * we're launching from. `npm i -g @hwip/cli` swaps dist/ but leaves the

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleShellSession = exports.startShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.targetForAgent = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.familyNames = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.agentLaunchArgs = exports.agentLaunchEnv = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
+exports.handleShellSession = exports.startShellSession = exports.shellTargets = exports.readShellSessionState = exports.planShellSession = exports.handleAgentSession = exports.tmuxMissingMessage = exports.inPaneNote = exports.handOffExec = exports.ensureListenerRunning = exports.takeListenerLaunchMarker = exports.listenerVersionDrifted = exports.withResumeHint = exports.targetForAgent = exports.shellQuote = exports.splitAgentOptions = exports.sanitizeLabel = exports.findAvailableSession = exports.familyNames = exports.firstFreeSession = exports.tmuxSessionName = exports.installedTmuxVersion = exports.agentLaunchArgs = exports.agentLaunchEnv = exports.herdrEnvArgs = exports.herdrSessionArgs = exports.sessionSidecarArgs = exports.detectProjectName = exports.detectProjectDir = exports.safeBasename = void 0;
 /**
  * `hwip cc` / `hwip codex` / `hwip gemini` — spawn an agent inside a named
  * tmux session so the resident listener (`hwip listener`) can address it
@@ -331,6 +331,7 @@ exports.splitAgentOptions = splitAgentOptions;
 /** POSIX shell-quote so passthrough args survive being joined into a tmux shell-command string. */
 const SHELL_SAFE = /^[\w\-./=:@%+,]+$/;
 const shellQuote = (s) => s.length > 0 && SHELL_SAFE.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+exports.shellQuote = shellQuote;
 const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     // Already inside tmux → no nested session, just run the agent in the
     // current pane. Nested tmux prefix collisions are confusing and the
@@ -364,7 +365,7 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     // tmux joins trailing argv into a single shell-command, so flags like
     // `--resume` would be eaten by tmux's own parser. Build one quoted
     // shell string instead, which tmux passes through verbatim.
-    const shellCmd = [agent, ...extra].map(shellQuote).join(' ');
+    const shellCmd = [agent, ...extra].map(exports.shellQuote).join(' ');
     // `-d`: create without attaching, so no TTY is needed and `new` fails
     // loudly on a taken name instead of `-A` silently attaching to whatever
     // runs there. `-c`: the agent's cwd must be the directory the session is
@@ -383,6 +384,22 @@ const targetForAgent = (agent, extra, agentKind, opts = {}) => {
     return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, ...herdrEnv, ...agentEnv, shellCmd, ...sidecar, ...(0, exports.herdrSessionArgs)(session)], session };
 };
 exports.targetForAgent = targetForAgent;
+/**
+ * `target` (an attached `tmux new`) run under `sh`, which outlives tmux by the
+ * one `hwip resume-hint` call and then exits with tmux's status. `sh` rather
+ * than this process waiting: the wrapper hands itself over with execve so no
+ * node heap sits resident for the whole session, and `sh` costs next to none.
+ */
+const withResumeHint = (target, agent, since, hwip = { node: process.execPath, cli: process.argv[1] ?? '' }) => {
+    if (target.kind !== 'tmux-new' || !target.session || !agent.resumeArgs || !hwip.cli)
+        return target;
+    const hint = [hwip.node, hwip.cli, 'resume-hint', '--session', target.session, '--type', agent.kind, '--at', String(since)]
+        .map(exports.shellQuote)
+        .join(' ');
+    const script = `tmux "$@"; s=$?; ${hint} || :; exit $s`;
+    return { ...target, cmd: 'sh', args: ['-c', script, 'sh', ...target.args] };
+};
+exports.withResumeHint = withResumeHint;
 // ── Background listener auto-start ────────────────────────────────────
 /**
  * Whether the daemon on record is running a different build than the one
@@ -444,6 +461,15 @@ const ensureListenerRunning = async (launchedByListener = (0, exports.takeListen
         }
         if (reportFailedStart(await (0, listener_process_js_1.awaitServiceListener)(logOffset, pid)))
             return;
+        // The service starts whatever install it was registered from, which
+        // need not be this one (`hwip` from Homebrew, the plist from an nvm
+        // node). Restarting it brings the same old build back, and every
+        // `hwip cc` after would restart it again without ever saying why.
+        const restarted = (0, listener_process_js_1.runningListenerVersion)();
+        if ((0, exports.listenerVersionDrifted)(restarted, config_js_1.VERSION)) {
+            console.error(staleServiceNote(restarted, (0, listener_service_js_1.serviceStatus)().cliPath));
+            return;
+        }
         if (pid === null)
             console.log(`hwip: listener started by ${owner} (log: ${listener_process_js_1.LISTENER_LOG_FILE})`);
         else
@@ -474,6 +500,10 @@ const ensureListenerRunning = async (launchedByListener = (0, exports.takeListen
     }
 };
 exports.ensureListenerRunning = ensureListenerRunning;
+/** What to say when the login service came back on an older install than this one. */
+const staleServiceNote = (running, serviceCli) => `hwip: the login service restarted the listener on ${running ?? 'an unstamped build'}, not ${config_js_1.VERSION} — ` +
+    `it runs ${serviceCli ?? 'another install'}.\n` +
+    '      Point it at this install: hwip listener --install-service';
 /** Say why a just-started listener is not running; true when it said anything. */
 const reportFailedStart = (started) => {
     const why = (0, listener_process_js_1.startFailure)(started);
@@ -558,6 +588,8 @@ const tmuxMissing = (command) => (0, exports.tmuxMissingMessage)(command, (0, tm
 const handleAgentSession = async (agent, extra = [], opts = {}, deps = {}) => {
     // First of all, before `ensureWorktree` runs git (its hooks would inherit the marker).
     const launchedByListener = (0, exports.takeListenerLaunchMarker)();
+    // The resume hint trusts only a registry record the sweep wrote after this.
+    const launchedAt = Date.now();
     // Best-effort: make sure the phone-bridge daemon is running, and running
     // the build we were launched from. The user shouldn't need to remember a
     // second command for the picker on their phone to work.
@@ -609,7 +641,8 @@ const handleAgentSession = async (agent, extra = [], opts = {}, deps = {}) => {
             return 1;
         }
     }
-    return (deps.launch ?? launchTarget)({ kind, cmd, args, session, env }, agent.binary);
+    const target = { kind, cmd, args, session, env };
+    return (deps.launch ?? launchTarget)((0, exports.withResumeHint)(target, agent, launchedAt), agent.binary);
 };
 exports.handleAgentSession = handleAgentSession;
 /**
@@ -666,7 +699,7 @@ const launchTarget = async ({ kind, cmd, args, session, env: agentEnv }, what) =
             // someone whose agent died inside a perfectly good pane to "run
             // from a plain shell pane" would send them after the wrong thing.
             if (kind === 'tmux-new' && code && code !== 0 && dur < 2000) {
-                console.error(`hwip: ${cmd} ${args.join(' ')} exited ${code} after ${dur}ms.\n` +
+                console.error(`hwip: tmux exited ${code} after ${dur}ms.\n` +
                     `  If this terminal is itself inside tmux (or an iTerm/Warp\n` +
                     `  tmux-integration pane), run \`hwip cc\` from a plain shell\n` +
                     `  pane instead — \`tmux new\` needs a real TTY to attach.`);

package/package.json

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