@masslessai/push-todo 3.10.4 → 3.10.6

package/SKILL.md

@@ -54,7 +54,12 @@ When this command is invoked:
    - Follow the [Auto-Resume from Session Transcript](#auto-resume-from-session-transcript) procedure below
    - Only if the session transcript cannot be found should you begin working from scratch
 
-9. If no resumable session exists, begin working on the task normally
+9. **Load task attachments** before starting work:
+   - If the task has **screenshot attachments**: Read each image from `~/Library/Mobile Documents/iCloud~ai~massless~push/Documents/Screenshots/<filename>` using the Read tool. These provide essential visual context.
+   - If the task has **link attachments**: Use WebFetch to read linked content when relevant to the task.
+   - See [Reading Task Attachments](#reading-task-attachments) for full details.
+
+10. If no resumable session exists, begin working on the task normally
 
 ## Review Mode
 
@@ -339,6 +344,66 @@ Do NOT offer to start working on the task — the daemon is already handling it.
 If the session file cannot be found (daemon just started, no output yet):
 - Tell the user: "The daemon just started working on this task. Run `/push-todo <number>` again in a minute for a progress update."
 
+## Reading Task Attachments
+
+Tasks can have **screenshot images** and **reference links** attached. When working on a task, always check for and use these attachments — they provide critical visual and reference context.
+
+### Context App
+
+The task output may show a **Context App** field (e.g., `X`, `Safari`, `WeChat`, `Slack`). This tells you which app the user was in when they created the voice task. Use this as semantic context:
+- **Context App: X** + screenshot → the screenshot is likely a tweet or thread
+- **Context App: Safari** + link → the user was browsing a webpage
+- **Context App: Slack** → the task relates to a Slack conversation
+- If the field is absent or empty, the user created the task from the Push app directly
+
+This context helps interpret ambiguous voice transcripts like "fix this" or "do we need this?" — the context app + screenshot together reveal what "this" refers to.
+
+### Screenshot Attachments
+
+Screenshots are images captured from the user's phone screen when creating the task. They're stored in **iCloud Documents** and synced to the Mac automatically.
+
+**When the task output shows an Attachments > Screenshots section:**
+
+1. **Get the filename** from the task output (e.g., `ABC123.png`)
+2. **Read the image** directly from the iCloud folder:
+   ```
+   ~/Library/Mobile Documents/iCloud~ai~massless~push/Documents/Screenshots/<filename>
+   ```
+3. **Use the Read tool** to view the image — Claude Code is multimodal and can interpret screenshots
+
+Example:
+```bash
+# The task shows: "1. ABC123.png (1170x2532)"
+# Read it directly:
+```
+Then use the Read tool on:
+`~/Library/Mobile Documents/iCloud~ai~massless~push/Documents/Screenshots/ABC123.png`
+
+**Why this matters:** Screenshots often contain the actual UI, error message, design mockup, or reference material the user was looking at when they created the task. The voice transcript alone may say "fix this" — the screenshot shows WHAT to fix.
+
+**If the file doesn't exist locally:** iCloud may not have synced it yet. Tell the user: "The screenshot hasn't synced from iCloud yet. Try opening Finder > iCloud Drive > Push > Screenshots to trigger the download."
+
+### Link Attachments
+
+Links are reference URLs the user shared when creating the task (e.g., from Safari, WeChat, or other apps).
+
+**When the task output shows an Attachments > Links section:**
+
+1. Links are displayed as clickable markdown: `🔗 [Title](URL)`
+2. **Use WebFetch** to read the linked content when relevant to the task
+
+### Programmatic Access (JSON mode)
+
+For scripts or when you need raw attachment data:
+```bash
+push-todo <number> --json
+```
+
+Key JSON fields:
+- `screenshotAttachmentsJson` — JSON string array of `{id, imageFilename, width, height, capturedAt, sourceApp}`
+- `linkAttachmentsJson` — JSON string array of `{id, url, title, createdAt}`
+- `contextApp` — App the user was in when creating the task
+
 ## CLI Reference
 
 The `push-todo` CLI supports these commands:

package/hooks/session-end.js

@@ -78,6 +78,7 @@ async function reportSessionFinished(apiKey, activeTask) {
     : null;
 
   const payload = {
+    todoId: activeTask.taskId || undefined,
     displayNumber: activeTask.displayNumber,
     status: 'session_finished',
     machineId,

package/lib/daemon.js

@@ -406,13 +406,17 @@ async function fetchQueuedTasks() {
   }
 }
 
-async function updateTaskStatus(displayNumber, status, extra = {}) {
+async function updateTaskStatus(displayNumber, status, extra = {}, todoId = null) {
   try {
     const payload = {
       displayNumber,
       status,
       ...extra
     };
+    // Prefer UUID for API lookup (displayNumber kept for backward compat)
+    if (todoId) {
+      payload.todoId = todoId;
+    }
 
     const machineId = getMachineId();
     const machineName = getMachineName();
@@ -460,7 +464,7 @@ async function updateTaskStatus(displayNumber, status, extra = {}) {
   }
 }
 
-async function claimTask(displayNumber) {
+async function claimTask(displayNumber, todoId) {
   const machineId = getMachineId();
   const machineName = getMachineName();
 
@@ -473,12 +477,18 @@ async function claimTask(displayNumber) {
   const branch = `push-${displayNumber}-${suffix}`;
 
   const payload = {
-    displayNumber,
+    todoId: todoId || undefined,     // UUID lookup (primary, avoids display_number collisions)
+    displayNumber,                   // Fallback + kept for logging
     status: 'running',
     machineId,
     machineName,
     branch,
-    atomic: true
+    atomic: true,
+    event: {
+      type: 'started',
+      timestamp: new Date().toISOString(),
+      machineName: machineName || undefined,
+    }
   };
 
   try {
@@ -1276,6 +1286,9 @@ async function executeTask(task) {
     return null;
   }
 
+  // Extract UUID early — needed for claim and all status updates
+  const taskId = task.id || task.todo_id || '';
+
   // Get project path (use action_type for multi-agent routing)
   let projectPath = null;
   if (gitRemote) {
@@ -1290,7 +1303,7 @@ async function executeTask(task) {
       logError(`Task #${displayNumber}: Project path does not exist: ${projectPath}`);
       await updateTaskStatus(displayNumber, 'failed', {
         error: `Project path not found: ${projectPath}`
-      });
+      }, taskId);
       return null;
     }
 
@@ -1298,13 +1311,10 @@ async function executeTask(task) {
   }
 
   // Atomic task claiming - must await to actually check the result
-  if (!(await claimTask(displayNumber))) {
+  if (!(await claimTask(displayNumber, taskId))) {
     log(`Task #${displayNumber}: claim failed, skipping`);
     return null;
   }
-
-  // Auto-heal: check if previous execution already completed work for this task
-  const taskId = task.id || task.todo_id || '';
   const healed = await autoHealExistingWork(displayNumber, summary, projectPath, taskId);
   if (healed) {
     log(`Task #${displayNumber}: auto-healed from previous execution, skipping re-execution`);
@@ -1313,7 +1323,7 @@ async function executeTask(task) {
 
   // Track task details
   updateTaskDetail(displayNumber, {
-    taskId: task.id || task.todo_id || '',
+    taskId,
     summary,
     status: 'running',
     phase: 'starting',
@@ -1327,7 +1337,7 @@ async function executeTask(task) {
   // Create worktree
   const worktreePath = createWorktree(displayNumber, projectPath);
   if (!worktreePath) {
-    await updateTaskStatus(displayNumber, 'failed', { error: 'Failed to create git worktree' });
+    await updateTaskStatus(displayNumber, 'failed', { error: 'Failed to create git worktree' }, taskId);
     taskDetails.delete(displayNumber);
     return null;
   }
@@ -1425,7 +1435,7 @@ IMPORTANT:
     child.on('error', async (error) => {
       logError(`Task #${displayNumber} error: ${error.message}`);
       runningTasks.delete(displayNumber);
-      await updateTaskStatus(displayNumber, 'failed', { error: error.message });
+      await updateTaskStatus(displayNumber, 'failed', { error: error.message }, taskId);
       taskDetails.delete(displayNumber);
       updateStatusFile();
     });
@@ -1441,7 +1451,7 @@ IMPORTANT:
     return taskInfo;
   } catch (error) {
     logError(`Error starting Claude for task #${displayNumber}: ${error.message}`);
-    await updateTaskStatus(displayNumber, 'failed', { error: error.message });
+    await updateTaskStatus(displayNumber, 'failed', { error: error.message }, taskId);
     taskDetails.delete(displayNumber);
     return null;
   }
@@ -1499,13 +1509,13 @@ async function handleTaskCompletion(displayNumber, exitCode) {
       duration,
       sessionId,
       summary: executionSummary
-    });
+    }, info.taskId);
     if (!statusUpdated) {
       logError(`Task #${displayNumber}: Failed to update status to session_finished — will retry`);
       // Retry once
       await updateTaskStatus(displayNumber, 'session_finished', {
         duration, sessionId, summary: executionSummary
-      });
+      }, info.taskId);
     }
 
     if (NOTIFY_ON_COMPLETE) {
@@ -1581,7 +1591,7 @@ async function handleTaskCompletion(displayNumber, exitCode) {
       ? `${failureSummary}\nExit code ${exitCode}. Ran for ${durationStr} on ${machineName}.`
       : `Exit code ${exitCode}: ${stderr.slice(0, 200)}`;
 
-    await updateTaskStatus(displayNumber, 'failed', { error: errorMsg });
+    await updateTaskStatus(displayNumber, 'failed', { error: errorMsg }, info.taskId);
 
     if (NOTIFY_ON_FAILURE) {
       sendMacNotification(
@@ -1879,6 +1889,7 @@ async function recoverOrphanedTasks() {
 
     for (const task of orphaned) {
       const dn = task.displayNumber || task.display_number;
+      const tid = task.id || task.todo_id || null;
       log(`Task #${dn}: resetting from 'running' to 'queued' (orphaned by restart)`);
       await updateTaskStatus(dn, 'queued', {
         event: {
@@ -1887,7 +1898,7 @@ async function recoverOrphanedTasks() {
           machineName: getMachineName() || undefined,
           summary: 'Daemon restarted — re-queuing for auto-heal'
         }
-      });
+      }, tid);
     }
   } catch (error) {
     log(`Orphaned task recovery failed (non-fatal): ${error.message}`);

package/lib/fetch.js

@@ -250,6 +250,7 @@ async function trackActiveTask(task) {
   const machineId = getMachineId();
   const machineName = getMachineName();
   await api.updateTaskExecution({
+    todoId: task.id || undefined,
     displayNumber: task.displayNumber,
     status: 'running',
     machineId,

package/lib/utils/format.js

@@ -176,6 +176,12 @@ export function formatTaskForDisplay(task) {
     lines.push(`**Session:** Resumable (\`push-todo resume ${displayNum}\`) - continues the exact Claude Code conversation`);
   }
 
+  // Context app — which app the user was in when creating the task
+  const contextApp = task.contextApp || task.context_app;
+  if (contextApp) {
+    lines.push(`**Context App:** ${contextApp}`);
+  }
+
   const createdAt = task.createdAt || task.created_at;
   lines.push(`**Created:** ${createdAt || 'unknown'}`);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masslessai/push-todo",
-  "version": "3.10.4",
+  "version": "3.10.6",
   "description": "Voice tasks from Push iOS app for Claude Code",
   "type": "module",
   "bin": {