@hwip/cli 0.1.19 → 0.1.21

package/README.md

@@ -435,9 +435,12 @@ block here.
    real terminal: `cd` and `export` stick, `sudo`/`ssh` prompts work, and a
    long command does not tie up an agent. `--label <x>` names it
    `hwip-<project>-<x>`; `--detach` creates it without attaching. Away from
-   the desk, open one from the phone through any running Claude Code
-   session by sending `!hwip sh --detach` (Claude Code's `!` bash mode —
-   see Defense item 7). Inside tmux it never attaches; it prints a
+   the desk, open one from the phone's **New session → Terminal**: the
+   listener runs the same `hwip sh --detach` in the directory the chosen
+   project last ran in (`session-shell-v1`; the phone names a session it saw,
+   never a directory). Through any running Claude Code session, sending
+   `!hwip sh --detach` does the same (Claude Code's `!` bash mode — see
+   Defense item 7). Inside tmux it never attaches; it prints a
    `tmux switch-client -t <session>` line instead. Running it again for a
    session it opened reattaches, and a session of that name it did not open
    is refused.
@@ -980,8 +983,11 @@ into a shell-adjacent pane). The defense is layered:
 What the marker does not stop: anything running as your user on this
 machine can set `@hwip_shell` on a session, or run `hwip sh` itself — and
 so can the phone, while a Claude Code session (`!tmux set-option …`) or a
-marked shell is open to it. It keeps the phone from choosing panes only
-when neither is.
+marked shell is open to it. And the phone can always open a marked shell of
+its own: New session → Terminal starts `hwip-<project>-sh` in any project
+this machine recorded. The marker keeps the phone from typing into panes
+you opened yourself (an agent's, a plain shell's), not from running
+commands on this machine.
 And no layer authenticates the sender: whoever holds your API key, or
 controls the backend, can type into every marked shell and, through `!`,
 every Claude Code session.

package/dist/device-presence.d.ts

@@ -4,6 +4,8 @@
  * offer it only to a computer that lists this.
  */
 export declare const SESSION_START_CAPABILITY = "session-start-v1";
+/** A fresh start that names agent kind `shell` opens the project's `hwip sh` Terminal (listener `startShellBeside`). */
+export declare const SESSION_SHELL_CAPABILITY = "session-shell-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 = exports.SESSION_START_CAPABILITY = void 0;
+exports.createDeviceKeyRegistration = exports.LISTENER_PRESENCE = exports.SESSION_SHELL_CAPABILITY = 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.
@@ -42,6 +42,8 @@ const schedule_js_1 = require("./schedule.js");
  * offer it only to a computer that lists this.
  */
 exports.SESSION_START_CAPABILITY = 'session-start-v1';
+/** A fresh start that names agent kind `shell` opens the project's `hwip sh` Terminal (listener `startShellBeside`). */
+exports.SESSION_SHELL_CAPABILITY = 'session-shell-v1';
 /** The one message both halves of presence ride; the server answers
  *  `listener.presence.ack` or `listener.presence.error`. */
 exports.LISTENER_PRESENCE = 'listener.presence';
@@ -52,7 +54,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, exports.SESSION_START_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, exports.SESSION_SHELL_CAPABILITY] } });
             if (!sent)
                 deps.log('device key: not registered — no connection right now, retried at the next open');
             return sent;

package/dist/installer.d.ts

@@ -28,6 +28,9 @@ export declare const failedStepCount: () => number;
 export declare const reportDetectedAgents: (agents: Agent[]) => void;
 /** The install's last line. Exported for tests. */
 export declare const closingLine: (failed: number) => string;
+/** Where the install's last screen sends a new user for the phone app. `ct`/`utm_source` name this surface. */
+export declare const APP_STORE_URL = "https://apps.apple.com/app/id6818053606?ct=cli-install";
+export declare const PLAY_STORE_URL = "https://play.google.com/store/apps/details?id=app.hwip&referrer=utm_source%3Dcli-install";
 /** Exported for tests (installGemini shells out to the real `gemini` binary,
  *  so the merge semantics can't be covered through it deterministically). */
 export declare const mergeJsonFile: (filePath: string, patch: Record<string, unknown>) => void;

package/dist/installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInstall = exports.serviceInstallChoice = exports.collectCredentials = exports.unknownOnlyIds = exports.filterAgentsByIds = exports.AGENT_INSTALLERS = exports.firstStderrLine = exports.injectCodexMcpEntry = exports.injectMcpEntry = exports.addAiderReadDirective = exports.writeManagedRule = exports.mergeJsonFile = exports.closingLine = exports.reportDetectedAgents = exports.failedStepCount = exports.failMerge = exports.mergeFailureLines = exports.shouldReauth = void 0;
+exports.handleInstall = exports.serviceInstallChoice = exports.collectCredentials = exports.unknownOnlyIds = exports.filterAgentsByIds = exports.AGENT_INSTALLERS = exports.firstStderrLine = exports.injectCodexMcpEntry = exports.injectMcpEntry = exports.addAiderReadDirective = exports.writeManagedRule = exports.mergeJsonFile = exports.PLAY_STORE_URL = exports.APP_STORE_URL = exports.closingLine = exports.reportDetectedAgents = exports.failedStepCount = exports.failMerge = exports.mergeFailureLines = exports.shouldReauth = void 0;
 const child_process_1 = require("child_process");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -136,6 +136,9 @@ const closingLine = (failed) => {
     return `Done, but ${steps} you: see the lines marked "-" above. Then restart your agents.`;
 };
 exports.closingLine = closingLine;
+/** Where the install's last screen sends a new user for the phone app. `ct`/`utm_source` name this surface. */
+exports.APP_STORE_URL = 'https://apps.apple.com/app/id6818053606?ct=cli-install';
+exports.PLAY_STORE_URL = 'https://play.google.com/store/apps/details?id=app.hwip&referrer=utm_source%3Dcli-install';
 /** An edit that would lose a comment of the user's names the file, like every other refusal. */
 const namingFile = (filePath, edit) => {
     try {
@@ -837,6 +840,8 @@ const handleInstall = async (args) => {
     console.log('\n  Testing connection...');
     await testConnection(apiKey, baseUrl);
     console.log(`\n  ${(0, exports.closingLine)(failedSteps)}\n`);
+    console.log(`  Get the app: ${exports.APP_STORE_URL}`);
+    console.log(`  Android:     ${exports.PLAY_STORE_URL}\n`);
     // The single most-reported surprise: pushes are not scoped to `hwip cc`.
     // Hooks fire for every session of every configured agent, so say it here —
     // at the moment the hooks get installed — together with the volume dials.

package/dist/listener.d.ts

@@ -549,6 +549,8 @@ export interface SessionResumeResult {
     error?: string;
     at: string;
 }
+/** The `agentKind` a fresh start names to ask for a Terminal (`hwip sh`) instead of an agent (`SESSION_SHELL_CAPABILITY`). */
+export declare const SHELL_START_KIND = "shell";
 /**
  * Start a remembered session again, detached, and tell the phone what happened.
  * Returns true when the message was ours to answer.

package/dist/listener.js

@@ -26,8 +26,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 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;
+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.SHELL_START_KIND = 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 = exports.recordInventory = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -1466,6 +1466,38 @@ const conversationRunning = (known, live) => {
         return current?.agentKind === known.agentKind && current.agentSessionId === id;
     });
 };
+/** The `agentKind` a fresh start names to ask for a Terminal (`hwip sh`) instead of an agent (`SESSION_SHELL_CAPABILITY`). */
+exports.SHELL_START_KIND = 'shell';
+/**
+ * A Terminal in `sessionName`'s project (hwip docs/session-runs.md Q50): `hwip sh --detach` in the directory this machine recorded for it — the login
+ * shell the phone may type into (`@hwip_shell`), audited as every shell input is. The phone names a session it saw, never
+ * a directory, as for an agent; the newest run of the name gives the directory, whichever agent ran it.
+ */
+const startShellBeside = (sessionName, reply) => {
+    const known = (0, session_registry_js_1.recallSession)(sessionName, Date.now());
+    if (!known) {
+        (0, listener_log_js_1.log)(`✗ shell beside ${sessionName}: never seen on this machine`);
+        return reply({ error: 'unknown_session' });
+    }
+    if (!(0, session_registry_js_1.sessionDirectoryExists)(known)) {
+        (0, listener_log_js_1.log)(`✗ shell beside ${sessionName}: ${known.cwd} is gone`);
+        return reply({ error: 'missing_directory' });
+    }
+    // One shell per project: a repeat tap reopens it, so this bucket only stops a flood of starts.
+    if (!(0, exports.checkRateLimit)(`start:shell:${known.cwd}`, undefined, FRESH_START_COST))
+        return reply({ error: 'rate_limited' });
+    const shell = process.env.SHELL || (0, os_1.userInfo)().shell || '/bin/sh';
+    const started = (0, wrapper_js_1.startShellSession)(known.cwd, shell, (args) => {
+        const r = (0, child_process_1.spawnSync)('tmux', (0, tmux_socket_js_1.tmuxArgs)(args), { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+        return { status: r.error ? null : r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+    });
+    if ('refused' in started) {
+        (0, listener_log_js_1.log)(`✗ shell beside ${sessionName}: ${started.refused}`);
+        return reply({ error: started.refused });
+    }
+    (0, listener_log_js_1.log)(`＋ shell ${started.session} in ${known.cwd}`);
+    return reply({ resumed: true, sessionName: started.session });
+};
 /**
  * Start a remembered session again, detached, and tell the phone what happened.
  * Returns true when the message was ours to answer.
@@ -1505,6 +1537,8 @@ const handleSessionResumeRequest = (req, send) => {
     // through whichever path is cheaper.
     if (!(0, exports.checkRateLimit)(sessionName, undefined, SUBMIT_COST))
         return reply({ error: 'rate_limited' });
+    if (req.fresh === true && req.agentKind === exports.SHELL_START_KIND)
+        return startShellBeside(sessionName, reply);
     // A named agent is answered with that run or not at all. Falling back to the
     // newest run would start claude for a phone that asked for pi — silently,
     // which is the exact failure this path exists to remove. A phone that names
@@ -5285,7 +5319,7 @@ const streamSession = (wsUrl, apiKey) => {
             // 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 recent = (0, recent_projects_js_1.recentProjectsToReport)(new Set(sessions.map((s) => s.name)));
             const fingerprint = `${(0, exports.sessionsFingerprint)(reported)}␞${recent ? JSON.stringify(recent) : '-'}`;
             if (!(0, exports.sessionsReportDue)(fingerprint, lastSentFingerprint, lastSentAtMs, Date.now())) {
                 return;

package/dist/recent-projects.d.ts

@@ -17,15 +17,21 @@ export interface RecentProject {
 }
 /** 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). */
+/**
+ * Each project's agents, from the newest session of each, in the order `known` gives (newest first).
+ *
+ * A project with a session in `live` is listed without counting toward the 12: a running session's entry is always the
+ * newest, so twelve running projects would leave no room for one the machine ran before (hwip docs/session-runs.md Q50).
+ * Its entries still go out — the agents it ran before and does not run now are only here.
+ */
 export declare const recentProjects: (known: readonly {
     name: string;
     agentKind: string;
     project?: string;
-}[]) => RecentProject[];
+}[], live?: ReadonlySet<string>) => RecentProject[];
 /**
- * The list for this report, or undefined when the registry would not read — an empty list would
+ * The list for this report beside `live`, the sessions it reports running, 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;
+export declare const recentProjectsToReport: (live: ReadonlySet<string>, now?: number) => RecentProject[] | undefined;
 //# sourceMappingURL=recent-projects.d.ts.map

package/dist/recent-projects.js

@@ -18,19 +18,27 @@ exports.RECENT_PROJECTS_MAX = 12;
 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();
+/**
+ * Each project's agents, from the newest session of each, in the order `known` gives (newest first).
+ *
+ * A project with a session in `live` is listed without counting toward the 12: a running session's entry is always the
+ * newest, so twelve running projects would leave no room for one the machine ran before (hwip docs/session-runs.md Q50).
+ * Its entries still go out — the agents it ran before and does not run now are only here.
+ */
+const recentProjects = (known, live = new Set()) => {
+    const projectOf = (e) => e.project || e.name;
+    const eligible = known.filter((e) => !isSubagent(e.name) && !isScheduled(e.name));
+    // As the phone counts running: a scheduled run or a subagent is no running session of the project there.
+    const running = new Set(eligible.filter((e) => live.has(e.name)).map(projectOf));
+    const past = 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)
+    for (const e of eligible) {
+        const project = projectOf(e);
+        if (!running.has(project) && !past.has(project)) {
+            if (past.size >= exports.RECENT_PROJECTS_MAX)
                 continue;
-            projects.add(project);
+            past.add(project);
         }
         const key = `${project}\u0000${e.agentKind}`;
         if (seen.has(key))
@@ -42,8 +50,8 @@ const recentProjects = (known) => {
 };
 exports.recentProjects = recentProjects;
 /**
- * The list for this report, or undefined when the registry would not read — an empty list would
+ * The list for this report beside `live`, the sessions it reports running, 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));
+const recentProjectsToReport = (live, now = Date.now()) => ((0, session_registry_js_1.registryUnreadable)() ? undefined : (0, exports.recentProjects)((0, session_registry_js_1.knownSessions)(now), live));
 exports.recentProjectsToReport = recentProjectsToReport;

package/dist/transcript-tail.js

@@ -507,6 +507,8 @@ const contentBlocks = (entry) => {
 const SYNTHETIC_BLOCKS = /<(task-notification|system-reminder|local-command-caveat|local-command-stdout|command-message|command-name|command-args)>[\s\S]*?<\/\1>/g;
 /** `<command-name>/simplify</command-name>` — the one wrapper worth keeping, as what it names. */
 const COMMAND_NAME = /<command-name>([^<]*)<\/command-name>/;
+/** `<command-args>prompt run</command-args>` — what the person typed after the command name. */
+const COMMAND_ARGS = /<command-args>([\s\S]*?)<\/command-args>/;
 /**
  * Whether this entry is a person speaking.
  *
@@ -577,10 +579,12 @@ const typedTextOf = (entry) => {
  * separate feature, not a reason to ship the path.
  */
 const stripAttachmentMarkers = (text) => {
-    const command = text.match(COMMAND_NAME)?.[1]?.trim();
+    const name = text.match(COMMAND_NAME)?.[1]?.trim();
+    const args = text.match(COMMAND_ARGS)?.[1]?.trim();
     const body = text.replace(SYNTHETIC_BLOCKS, '');
-    // A slash command is a person's turn, and its name is the whole of what they
-    // said — the wrapper around it is not.
+    // A slash command is a person's turn, and its name and arguments are the
+    // whole of what they said — the wrapper around them is not.
+    const command = name && args ? `${name} ${args}` : name;
     const withCommand = command ? `${command}\n${body}` : body;
     return withCommand.replace(/\[Image:[^\]]*\]/g, '').replace(/\n{3,}/g, '\n\n');
 };

package/dist/wrapper.d.ts

@@ -210,7 +210,7 @@ export declare const handleAgentSession: (agent: RemoteAgent, extra?: string[],
 /** What tmux holds under a `hwip sh` session name. */
 export type ShellSessionState = 'none' | 'marked' | 'unmarked';
 /** A tmux call, injectable for tests. */
-type RunTmux = (args: string[]) => {
+export type RunTmux = (args: string[]) => {
     status: number | null;
     stdout: string;
     stderr?: string;
@@ -258,6 +258,16 @@ export declare const shellTargets: (shell: string, opts: AgentLaunchOptions, inT
     create: SpawnTarget;
     attach: SpawnTarget | null;
 };
+/**
+ * The phone's Terminal start (hwip docs/session-runs.md Q50): `hwip sh --detach` run in `projectDir` — the same
+ * `hwip-<project>-sh` login shell, marked so the phone may type into it. One already open under that name is the answer
+ * as it is; a session of that name `hwip sh` did not mark is refused, never taken over.
+ */
+export declare const startShellSession: (projectDir: string, shell: string, run?: RunTmux) => {
+    session: string;
+} | {
+    refused: "already_running" | "start_failed";
+};
 /**
  * `hwip sh [--label x] [--detach]` — open (or reattach) `hwip-<project>-sh`
  * running the login shell, marked so the phone may type into it. The label

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleShellSession = 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.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;
 /**
  * `hwip cc` / `hwip codex` / `hwip gemini` — spawn an agent inside a named
  * tmux session so the resident listener (`hwip listener`) can address it
@@ -736,7 +736,7 @@ exports.readShellSessionState = readShellSessionState;
  * run is a detached one, as `--detach` is.
  */
 const shellTargets = (shell, opts, inTmux = !!process.env.TMUX) => {
-    const create = (0, exports.targetForAgent)(shell, ['-l'], 'shell', { label: opts.label ?? 'sh', detach: true });
+    const create = (0, exports.targetForAgent)(shell, ['-l'], 'shell', { projectDir: opts.projectDir, label: opts.label ?? 'sh', detach: true });
     const session = create.session ?? '';
     // `attach-session`, never `new -A`: a session that died since the probe
     // must not come back as a fresh, unmarked one.
@@ -744,6 +744,22 @@ const shellTargets = (shell, opts, inTmux = !!process.env.TMUX) => {
     return { create, attach: opts.detach || inTmux ? null : attach };
 };
 exports.shellTargets = shellTargets;
+/**
+ * The phone's Terminal start (hwip docs/session-runs.md Q50): `hwip sh --detach` run in `projectDir` — the same
+ * `hwip-<project>-sh` login shell, marked so the phone may type into it. One already open under that name is the answer
+ * as it is; a session of that name `hwip sh` did not mark is refused, never taken over.
+ */
+const startShellSession = (projectDir, shell, run = runTmux) => {
+    const { create } = (0, exports.shellTargets)(shell, { projectDir, detach: true }, true);
+    const session = create.session ?? '';
+    const plan = (0, exports.planShellSession)(create, null, (0, exports.readShellSessionState)(session, run));
+    if (plan.kind === 'refuse')
+        return { refused: 'already_running' };
+    if (plan.kind === 'create' && run(plan.args).status !== 0)
+        return { refused: 'start_failed' };
+    return { session };
+};
+exports.startShellSession = startShellSession;
 /**
  * `hwip sh [--label x] [--detach]` — open (or reattach) `hwip-<project>-sh`
  * running the login shell, marked so the phone may type into it. The label

package/package.json

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