teleportation-cli 1.0.0 → 1.0.1

package/.claude/hooks/heartbeat.mjs

@@ -46,11 +46,53 @@ let intervalHandle = null;
 let heartbeatCount = 0;
 let failureCount = 0;
 let lastDaemonCheck = 0;
+// Module cache for lifecycle and pid-manager (imported once, reused)
+let lifecycleModule = null;
+let pidManagerModule = null;
+// Flag to prevent concurrent daemon start attempts
+let daemonStartInProgress = false;
 // Make interval configurable via environment variable (default 60 seconds)
 const DAEMON_CHECK_INTERVAL = Math.max(10000, Math.min(300000,
   parseInt(env.DAEMON_CHECK_INTERVAL || '60000', 10)
 )); // Default 60 seconds, min 10s, max 5min
 
+/**
+ * Update daemon state on relay
+ * @param {'running' | 'stopped'} status - Daemon status
+ * @param {string} reason - Reason for state change
+ */
+async function updateRelayDaemonState(status, reason) {
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+
+    const response = await fetch(`${RELAY_API_URL}/api/sessions/${SESSION_ID}/daemon-state`, {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${RELAY_API_KEY}`
+      },
+      body: JSON.stringify({
+        status,
+        started_at: status === 'running' ? Date.now() : null,
+        started_reason: status === 'running' ? reason : null
+      }),
+      signal: controller.signal
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok && DEBUG) {
+      console.log(`[Heartbeat] Failed to update relay daemon state: ${response.status}`);
+    }
+  } catch (error) {
+    if (DEBUG) {
+      console.log(`[Heartbeat] Error updating relay daemon state: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
 /**
  * Check if daemon is running and start it if not
  */
@@ -67,8 +109,15 @@ async function ensureDaemonRunning() {
   try {
     // Try to import lifecycle module from installed location
     const possibleLocations = [
+      // npm global install location
+      '/usr/local/lib/node_modules/teleportation-cli/lib/daemon/lifecycle.js',
+      // User's npm global install (common on macOS with nvm/fnm)
+      join(homedir(), '.local', 'lib', 'node_modules', 'teleportation-cli', 'lib', 'daemon', 'lifecycle.js'),
+      // Legacy location
       join(homedir(), '.teleportation', 'lib', 'daemon', 'lifecycle.js'),
+      // Relative to hooks dir (development)
       join(__dirname, '..', '..', 'lib', 'daemon', 'lifecycle.js'),
+      // Environment override
       env.TELEPORTATION_LIFECYCLE_PATH
     ].filter(Boolean);
 
@@ -116,9 +165,11 @@ async function ensureDaemonRunning() {
       }
 
       try {
-        await lifecycle.startDaemon({ silent: true });
+        // Use startDaemonIfNeeded to both start the daemon AND update the relay
+        // This ensures the mobile UI knows the daemon is running
+        await lifecycle.startDaemonIfNeeded(SESSION_ID, 'heartbeat');
         if (DEBUG) {
-          console.log(`[Heartbeat] Daemon started successfully`);
+          console.log(`[Heartbeat] Daemon started and relay updated successfully`);
         }
       } catch (error) {
         // Don't fail heartbeat if daemon start fails - it might already be starting
@@ -129,6 +180,20 @@ async function ensureDaemonRunning() {
         // Always reset flag, even if start fails
         daemonStartInProgress = false;
       }
+    } else if (status.running) {
+      // Daemon is running - ensure relay knows about it
+      // This handles the case where daemon was started manually or by another session
+      try {
+        await updateRelayDaemonState('running', 'heartbeat');
+        if (DEBUG) {
+          console.log(`[Heartbeat] Synced daemon running state to relay`);
+        }
+      } catch (error) {
+        // Ignore errors - just a sync, not critical
+        if (DEBUG) {
+          console.log(`[Heartbeat] Failed to sync daemon state: ${error.message}`);
+        }
+      }
     }
   } catch (error) {
     // Silently fail - daemon check shouldn't break heartbeat

package/.claude/hooks/permission_request.mjs

@@ -132,7 +132,10 @@ const fetchJson = async (url, opts) => {
   const RELAY_API_URL = env.RELAY_API_URL || config.relayApiUrl || '';
   const RELAY_API_KEY = env.RELAY_API_KEY || config.relayApiKey || '';
   const POLLING_INTERVAL_MS = parseInt(env.APPROVAL_POLL_INTERVAL_MS || '2000', 10);
-  const APPROVAL_TIMEOUT_MS = parseInt(env.APPROVAL_TIMEOUT_MS || '300000', 10); // 5 min default
+  const FAST_APPROVAL_TIMEOUT_MS = parseInt(
+    env.FAST_APPROVAL_TIMEOUT_MS || env.FAST_POLL_TIMEOUT_MS || '55000',
+    10
+  );
 
   if (!RELAY_API_URL || !RELAY_API_KEY) {
     log('No relay config - letting Claude Code handle permission locally');
@@ -224,13 +227,10 @@ const fetchJson = async (url, opts) => {
 
   // Poll for remote approval decision
   log('Polling for remote approval decision...');
-  const AUTO_AWAY_TIMEOUT_MS = parseInt(env.AUTO_AWAY_TIMEOUT_MS || '300000', 10); // 5 min default
-  const startTime = Date.now();
-  let hasSetAutoAway = false;
   let consecutiveFailures = 0;
   const MAX_CONSECUTIVE_FAILURES = 5;
 
-  const deadline = Date.now() + APPROVAL_TIMEOUT_MS;
+  const deadline = Date.now() + FAST_APPROVAL_TIMEOUT_MS;
   while (Date.now() < deadline) {
     try {
       const status = await fetchJson(`${RELAY_API_URL}/api/approvals/${approvalId}`, {
@@ -240,6 +240,30 @@ const fetchJson = async (url, opts) => {
 
       if (status.status === 'allowed') {
         log('Remote approval: ALLOWED');
+        // Acknowledge on the fast-path to prevent duplicate daemon execution.
+        // CRITICAL: If ACK fails, we must NOT proceed with local execution to avoid duplicates.
+        try {
+          const ackRes = await fetch(`${RELAY_API_URL}/api/approvals/${approvalId}/ack`, {
+            method: 'POST',
+            headers: { 'Authorization': `Bearer ${RELAY_API_KEY}` }
+          });
+          if (!ackRes.ok) {
+            throw new Error(`ACK returned ${ackRes.status}`);
+          }
+        } catch (e) {
+          log(`ERROR: Failed to ack approval ${approvalId}: ${e.message} - aborting to prevent duplicate execution`);
+          // Return early without allowing - let daemon handle it instead
+          const out = {
+            hookSpecificOutput: {
+              hookEventName: 'PermissionRequest',
+              permissionDecision: 'deny',
+              permissionDecisionReason: '⚠️ Teleportation: Approval received but acknowledgment failed. Request handed to daemon to prevent duplicate execution.'
+            },
+            suppressOutput: true
+          };
+          stdout.write(JSON.stringify(out));
+          return exit(0);
+        }
         const out = {
           hookSpecificOutput: {
             hookEventName: 'PermissionRequest',
@@ -270,25 +294,6 @@ const fetchJson = async (url, opts) => {
         log('Approval was invalidated - letting Claude Code handle');
         return exit(0);
       }
-
-      // Auto-set away after timeout (if not already away)
-      if (!hasSetAutoAway && (Date.now() - startTime) > AUTO_AWAY_TIMEOUT_MS) {
-        const timeoutMinutes = Math.round(AUTO_AWAY_TIMEOUT_MS / 1000 / 60);
-        log(`Approval waiting >${timeoutMinutes} minutes - auto-setting away mode`);
-        try {
-          await fetchJson(`${RELAY_API_URL}/api/sessions/${session_id}/daemon-state`, {
-            method: 'PATCH',
-            headers: {
-              'Content-Type': 'application/json',
-              'Authorization': `Bearer ${RELAY_API_KEY}`
-            },
-            body: JSON.stringify({ is_away: true })
-          });
-          hasSetAutoAway = true;
-        } catch (e) {
-          log(`Failed to auto-set away: ${e.message}`);
-        }
-      }
     } catch (e) {
       consecutiveFailures++;
       if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
@@ -301,7 +306,31 @@ const fetchJson = async (url, opts) => {
     await sleep(POLLING_INTERVAL_MS);
   }
 
-  // Timeout - let Claude Code handle it
-  log('Approval timeout - letting Claude Code handle');
+  // Fast-path timeout: do NOT fall back to local permission prompts while user is away.
+  // Instead, hand off to daemon (background) and inform Claude.
+  log('Fast-path approval timeout - handing off to daemon');
+
+  try {
+    await fetch(`${RELAY_API_URL}/api/sessions/${session_id}/daemon-state`, {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${RELAY_API_KEY}`
+      },
+      body: JSON.stringify({ last_approval_location: 'daemon_handoff', is_away: true })
+    });
+  } catch (e) {
+    log(`Warning: Failed to update daemon-state for handoff: ${e.message}`);
+  }
+
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PermissionRequest',
+      permissionDecision: 'deny',
+      permissionDecisionReason: '⏳ Teleportation: waiting for mobile approval timed out. This request was handed off to the daemon and will run in the background once approved. You will see a Daemon Work Update here when it completes.'
+    },
+    suppressOutput: true
+  };
+  stdout.write(JSON.stringify(out));
   return exit(0);
 })();

package/.claude/hooks/pre_tool_use.mjs

@@ -79,6 +79,7 @@ const fetchJson = async (url, opts) => {
   }
 
   let { session_id, tool_name, tool_input } = input || {};
+  tool_input = tool_input && typeof tool_input === 'object' ? tool_input : {};
   let claude_session_id = session_id; // Keep original ID
 
   log(`Session ID: ${session_id}, Tool: ${tool_name}, Input: ${JSON.stringify(tool_input).substring(0, 100)}`);
@@ -418,10 +419,36 @@ const fetchJson = async (url, opts) => {
     }
   };
 
+  if (tool_input.__teleportation_away) {
+    await updateSessionState({ is_away: true });
+    const out = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: '✅ Teleportation: Away mode enabled.'
+      },
+      suppressOutput: true
+    };
+    stdout.write(JSON.stringify(out));
+    return exit(0);
+  }
+
+  if (tool_input.__teleportation_back) {
+    await updateSessionState({ is_away: false });
+    const out = {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: '✅ Teleportation: Away mode disabled.'
+      },
+      suppressOutput: true
+    };
+    stdout.write(JSON.stringify(out));
+    return exit(0);
+  }
+
   // SMART AWAY MODE: Auto-mark as present ("back") on any activity
   // If the user is typing commands locally, they are clearly not away.
-  await updateSessionState({ is_away: false });
-
   // Note: Approval invalidation is handled by PermissionRequest hook
   // to avoid race conditions and duplicate API calls
 

package/.claude/hooks/session-register.mjs

@@ -145,19 +145,78 @@ export async function ensureSessionRegistered(session_id, cwd, config) {
 
           // Check if heartbeat is already running for this session
           const { tmpdir } = await import('os');
-          const { readFile } = await import('fs/promises');
+          const { readFile, unlink } = await import('fs/promises');
           const pidFile = join(tmpdir(), `teleportation-heartbeat-${session_id}.pid`);
-          
+
           let shouldStartHeartbeat = true;
           try {
-            await readFile(pidFile);
-            // PID file exists, heartbeat might be running
-            shouldStartHeartbeat = false;
+            const pidContent = await readFile(pidFile, 'utf8');
+            // Parse PID file (JSON format with session_id validation)
+            let pidData;
+            try {
+              pidData = JSON.parse(pidContent);
+            } catch {
+              // Fallback for old format (plain PID number)
+              pidData = { pid: parseInt(pidContent.trim(), 10) };
+            }
+
+            const pid = pidData.pid;
+            if (pid && !isNaN(pid)) {
+              // Check if the process is actually running
+              try {
+                process.kill(pid, 0); // Signal 0 checks existence without killing
+                // Process is running - don't start another heartbeat
+                shouldStartHeartbeat = false;
+                if (env.DEBUG) {
+                  console.error(`[SessionRegister] Heartbeat already running (PID: ${pid})`);
+                }
+              } catch (killError) {
+                if (killError.code === 'ESRCH') {
+                  // Process is dead - clean up stale PID file
+                  try {
+                    await unlink(pidFile);
+                    if (env.DEBUG) {
+                      console.error(`[SessionRegister] Cleaned up stale heartbeat PID file (PID: ${pid})`);
+                    }
+                  } catch (unlinkError) {
+                    if (env.DEBUG) {
+                      console.error(`[SessionRegister] Failed to unlink stale PID file: ${unlinkError.message}`);
+                    }
+                  }
+                  // Will start new heartbeat
+                } else {
+                  // Permission error - assume process exists, don't start duplicate
+                  shouldStartHeartbeat = false;
+                  if (env.DEBUG) {
+                    console.error(`[SessionRegister] Cannot check heartbeat (permission denied), assuming running (PID: ${pid})`);
+                  }
+                }
+              }
+            }
           } catch (e) {
             // PID file doesn't exist, start heartbeat
           }
 
           if (shouldStartHeartbeat) {
+            // Kill any orphan heartbeat processes for this session before starting a new one
+            // This handles race conditions where multiple processes pass the check simultaneously
+            try {
+              const { execSync } = await import('child_process');
+              // Use pkill with -f flag to match full command line (session_id argument)
+              // Returns 1 if no processes matched, so we ignore the exit code
+              execSync(`pkill -f "heartbeat.mjs ${session_id}" 2>/dev/null || true`, { stdio: 'ignore' });
+              if (env.DEBUG) {
+                console.error(`[SessionRegister] Cleaned up any orphan heartbeats for ${session_id}`);
+              }
+              // Small delay to let orphan processes terminate
+              await new Promise(r => setTimeout(r, 100));
+            } catch (pkillError) {
+              // Ignore pkill errors - process might not exist
+              if (env.DEBUG) {
+                console.error(`[SessionRegister] pkill cleanup failed: ${pkillError.message}`);
+              }
+            }
+
             const heartbeat = spawn('node', [heartbeatPath, session_id], {
               detached: true,
               stdio: 'ignore',

package/.claude/hooks/user_prompt_submit.mjs

@@ -9,6 +9,15 @@
 import { stdin, stdout, exit, env } from 'node:process';
 import { tmpdir } from 'os';
 import { join } from 'path';
+import { appendFile } from 'fs/promises';
+
+const HOOK_LOG = '/tmp/teleportation-hook.log';
+const log = async (msg) => {
+  const ts = new Date().toISOString();
+  try {
+    await appendFile(HOOK_LOG, `[${ts}] [UserPromptSubmit] ${msg}\n`);
+  } catch {}
+};
 
 const readStdin = () => new Promise((resolve, reject) => {
   let data = '';
@@ -18,6 +27,12 @@ const readStdin = () => new Promise((resolve, reject) => {
   stdin.on('error', reject);
 });
 
+const fetchJson = async (url, opts) => {
+  const res = await fetch(url, opts);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+};
+
 (async () => {
   let input = {};
   try {
@@ -31,6 +46,45 @@ const readStdin = () => new Promise((resolve, reject) => {
 
   const { session_id, prompt } = input;
 
+  // Clear away mode only on actual user activity (prompt submit), not on tool attempts.
+  // Also support /away and /back here in case they are handled as prompts.
+  if (session_id && prompt && typeof prompt === 'string') {
+    const trimmed = prompt.trim();
+    const lowered = trimmed.toLowerCase();
+
+    let desiredAway = null;
+    if (lowered === '/away' || lowered === 'teleportation away') desiredAway = true;
+    else if (lowered === '/back' || lowered === 'teleportation back') desiredAway = false;
+    else if (trimmed.length > 0) desiredAway = false;
+
+    if (desiredAway !== null) {
+      try {
+        const { loadConfig } = await import('./config-loader.mjs');
+        const config = await loadConfig();
+
+        const RELAY_API_URL = env.RELAY_API_URL || config.relayApiUrl || '';
+        const RELAY_API_KEY = env.RELAY_API_KEY || config.relayApiKey || '';
+
+        if (RELAY_API_URL && RELAY_API_KEY) {
+          await fetchJson(`${RELAY_API_URL}/api/sessions/${session_id}/daemon-state`, {
+            method: 'PATCH',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${RELAY_API_KEY}`
+            },
+            body: JSON.stringify({ is_away: desiredAway })
+          });
+        }
+      } catch (e) {
+        // Always log failures to hook log file for debugging (not just in DEBUG mode)
+        log(`Failed to update away state: ${e.message}`);
+        if (env.DEBUG) {
+          console.error(`[UserPromptSubmit] Failed to update away state: ${e.message}`);
+        }
+      }
+    }
+  }
+
   // Check if user is running /model command
   if (prompt && typeof prompt === 'string') {
     const trimmed = prompt.trim().toLowerCase();

package/README.md

@@ -10,13 +10,29 @@ Teleportation enables developers to approve Claude Code actions remotely from an
 
 ## Installation
 
-### Method 1: Quick Install (curl)
+### Method 1: npm (Recommended)
+
+```bash
+# Install globally via npm
+npm install -g teleportation-cli
+
+# Verify installation
+teleportation --version
+```
+
+**Requirements:**
+- **Bun >=1.3.0** - [Install Bun](https://bun.sh/docs/installation)
+- **Claude Code CLI** - [Install Claude Code](https://claude.ai/code)
+
+> **Note:** While the package uses npm for distribution, it requires Bun as the runtime. Make sure to install Bun first.
+
+### Method 2: Quick Install (curl)
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/dundas/teleportation-private/main/scripts/install.sh | bash
 ```
 
-### Method 2: From Source (Recommended)
+### Method 3: From Source
 
 **Requirements:** Bun >=1.3.0
 
@@ -31,15 +47,10 @@ bun install
 bun link  # Makes 'teleportation' command available globally
 ```
 
-### Method 3: GitHub Releases
+### Method 4: GitHub Releases
 
 Download the latest release from [GitHub Releases](https://github.com/dundas/teleportation-private/releases/latest) and extract to `~/.teleportation/`.
 
-## Requirements
-
-- **Bun >=1.3.0** (JavaScript runtime)
-- **Claude Code CLI** installed
-
 ### Installing Bun
 
 ```bash
@@ -77,16 +88,19 @@ bun install
 ## Quick Start
 
 ```bash
-# 1. Enable hooks
+# 1. Install via npm
+npm install -g teleportation-cli
+
+# 2. Enable hooks
 teleportation on
 
-# 2. Authenticate with your account
+# 3. Authenticate with your account
 teleportation login
 
-# 3. Check status
+# 4. Check status
 teleportation status
 
-# 4. Start Claude Code - approvals will be routed to your phone!
+# 5. Start Claude Code - approvals will be routed to your phone!
 ```
 
 ## Usage
@@ -229,6 +243,16 @@ bun run dev:all
 - **Multi-tenant isolation**: Your data is isolated from other users
 - **Privacy-preserving**: Session existence not revealed to unauthorized users
 
+## Known Limitations
+
+### Session Registry Race Condition
+
+The remote session registry uses file-based storage (`~/.teleportation/remote-sessions/sessions.json`). There is a theoretical race condition if multiple processes attempt to register the same session ID simultaneously. The check for existing sessions and the save operation are not atomic.
+
+**Impact**: This is an acceptable limitation for the current single-user CLI use case.
+
+**Future mitigation**: Future versions may implement file locking (e.g., using `proper-lockfile` package) or migrate to a database (e.g., SQLite) for multi-user or concurrent scenarios.
+
 ## License
 
 MIT