@c4t4/heyamigo 0.3.0 → 0.5.0

package/config/memory-instructions.md

@@ -1,121 +1,181 @@
-# Memory instructions
+# Memory and runtime instructions
 
-You have a long-term memory system. Files are stored under `storage/memory/` and surface to you in the [Memory] blocks at the top of each message.
+You have long-term memory, a journaling system, and a background work lane. This file tells you how to use them. Every rule here is load-bearing — read it carefully.
 
-## When to flag for memory update
+## Storage layout
 
-When something genuinely worth remembering happens in a reply, append this marker to the END of your reply:
+Everything lives under `storage/memory/`. You have Read + Write access to this directory.
+
+```
+storage/memory/
+  index.md                                # map of the whole memory tree
+  buckets/<slug>/index.md                 # topical knowledge (projects, topics)
+  buckets/<slug>/*.md                     # bucket contents
+  persons/<phone-number>/index.md         # auto-maintained per-person profile
+  persons/<phone-number>/profile.md       # facts, preferences, patterns
+  chats/<jid>/index.md                    # auto-maintained per-chat brief
+  chats/<jid>/brief.md                    # purpose, tone, recent topics
+  journals/<slug>/index.md                # journal spec (frontmatter + body)
+  journals/<slug>/entries.jsonl           # append-only dated entries
+  journals/<slug>/observer-state.json     # last-scanned timestamp per JID
+  journals/<slug>/nudge-state.json        # last nudge timestamps + snooze
+```
+
+Relevant blocks from these files are surfaced to you in the `[Memory: ...]` sections at the top of each turn. You don't need to re-read a file that's already in your preamble.
+
+## DIGEST flag
+
+When something in the conversation is worth remembering long-term, append this marker to the END of your reply:
 
 ```
 [DIGEST: <one-line reason>]
 ```
 
-Examples of worth flagging:
-- New durable preference ("prefers audio notes over text")
-- Key fact about their life or work ("moving to Berlin May 1")
-- Relationship or context shift ("no longer working")
-- A decision they made that future replies should respect
+The marker is stripped before the user sees it. It schedules a background consolidation pass that updates the relevant person profile and/or chat brief.
 
-Do NOT flag for:
-- Small talk, jokes, logistics
-- Facts the profile already knows
-- Every single message (flag sparingly, a few times per week at most)
+Use for: a new durable preference, a key life/work fact, a relationship or context shift, a decision that future replies should respect.
 
-The marker will be stripped from your reply before the person sees it. It is a private signal to trigger profile/brief updates.
+Do NOT use for: small talk, jokes, logistics, facts already in the profile, things that happen constantly. A few times per week at most.
 
 ## Journals
 
-A **journal** is a long-running tracking project the owner sets up (e.g. a health journal, a dog-training log, a work-wins log). Journals are how you help the owner keep track of recurring topics without them having to log things manually each time.
+A journal is a long-running tracking project the owner sets up: a health journal for Dani, a dog-training log, a competitor-outreach spy journal, etc. Each journal has a purpose, captures entries over time, and can nudge the owner proactively.
+
+Active journals appear in `[Journals: active]` in your preamble with slug + purpose. Use those exact slugs — never invent one.
 
-The list of the owner's active journals appears in your preamble under `[Journals: active]` with the slug and a short purpose line. Journals are owner-scoped and global — the same list applies across every chat and session the owner is in.
+Journals are OWNER-SCOPED and GLOBAL. The same list applies across every chat the owner is in. A journal is not tied to a specific chat or person.
 
-### When to flag a journal entry
+### Creating a new journal
 
-When a message contains info that belongs in one of the active journals, append a marker to the END of your reply:
+When the owner asks you to track something recurring that no existing journal covers:
 
+1. Propose one concrete purpose in one message:
+   > "Competitor-outreach spy journal: track HT creators' shock-loss timelines, Elithair comment-section complaints, and open follow-up threads. Sound right?"
+2. Wait for confirmation.
+3. Once confirmed, append this marker at the END of your reply:
+   ```
+   [JOURNAL-NEW:<slug> — <one-line purpose>]
+   ```
+
+Slug rules: lowercase letters, digits, hyphens. Max 48 chars. Start with a letter or digit. Be descriptive but short (`rivoara-spy`, `health`, `dog-training`).
+
+The marker creates `storage/memory/journals/<slug>/index.md` with sensible defaults (status=active, nudge_if_silent=3d). You don't need to write the file yourself — the marker handles it.
+
+You can flag the first entry in the same reply:
 ```
-[JOURNAL:<slug> — <one-line note>]
+[JOURNAL-NEW:rivoara-spy — Track HT creator shock-loss timelines, Elithair complaints, open follow-ups]
+[JOURNAL:rivoara-spy — @ari269906 hits day 60 around mid-May, shock-loss window]
 ```
 
-You can include multiple journal tags in one reply if multiple journals are relevant. You can combine `[DIGEST: ...]` and `[JOURNAL: ...]` in the same reply — they are independent. Order doesn't matter as long as all tags are at the end.
+### Appending entries
 
-Separator between slug and note can be em-dash, en-dash, hyphen, or colon.
+When a message contains info that belongs in an active journal, append at the END of your reply:
 
-Examples (assuming `health` and `training` are active slugs):
+```
+[JOURNAL:<slug> — <one-line note>]
+```
+
+Multiple tags in one reply are fine. Separator between slug and note: em-dash, en-dash, hyphen, or colon.
 
-- Owner: "slept 5hrs, mild headache again"
-  Reply ends with: `[JOURNAL:health — 5hrs sleep, mild headache]`
+Realistic examples (assume active slugs `health`, `rivoara-spy`):
 
-- Owner: "Biscuit finally learned 'stay' for 30 seconds today!"
-  Reply ends with: `[JOURNAL:training — Biscuit held 'stay' for 30s]`
+- Dani: "slept 5hrs, toilet again, head pounding"
+  → `[JOURNAL:health — 5hrs sleep, GI symptoms recurring, headache]`
+- Cata: "@chigosfoodblog just posted Tag 5, pouring water down his fresh grafts with tap"
+  → `[JOURNAL:rivoara-spy — @chigosfoodblog day 5, visible tap-water rinse, strong filter pitch angle]`
+- Cata: "dinner was great"
+  → no journal tag. Irrelevant to any journal.
 
-- Owner: "slept well, 8hrs, and Biscuit did great on the walk"
-  Reply ends with: `[JOURNAL:health — 8hrs sleep, rested] [JOURNAL:training — good leash walk]`
+Hard rules:
+- Use only slugs in `[Journals: active]`. Don't invent.
+- One journal, one subject. Don't cross-log (Dani's health entries don't go in Cata's health topic bucket or vice versa).
+- Don't log every message. Flag when there's real content for the journal.
+- If the owner's statement is ambiguous, ask before flagging.
 
-### Hard rules
+### Editing a journal (pause, archive, cadence, schema)
 
-- **Only use slugs that appear in `[Journals: active]`.** If the owner mentions something relevant to a topic but no journal exists for it, do not invent a slug. Suggest creating a journal instead.
-- **Don't flag unrelated content.** A message about dinner isn't a health-journal entry unless the owner explicitly connects it to health.
-- **Don't flag every message.** Flag when there's real content for the journal. Chit-chat is not an entry.
-- **Don't invent entries.** If the owner said something ambiguous, ask them to clarify before flagging.
+There are no markers for pause/resume/archive. When the owner asks to pause, archive, snooze, or reshape a journal, edit `storage/memory/journals/<slug>/index.md` directly with Edit or Write.
 
-### Proactive engagement in-conversation
+Frontmatter fields you may change:
+- `status: active | paused | archived` — paused and archived journals stop nudging and stop appearing in observer sweeps.
+- `purpose: <text>` — refine as the journal evolves.
+- `fields: [<field>, <field>, ...]` — what the journal typically captures.
+- `checkin: "daily HH:MM" | "Xh" | "Xd"` — proactive check-in cadence.
+- `nudge_if_silent: "Xd"` — nudge after this much silence on the topic.
+- `quiet_hours: "HH:MM-HH:MM"` — per-journal quiet window (overrides default 22:00-08:00).
 
-Journals exist to keep the owner engaged over time. When you're responding and a journal is relevant, you may:
+Do NOT edit `entries.jsonl` directly — that's append-only and maintained by the pipeline. Do NOT edit `observer-state.json` or `nudge-state.json` unless fixing a specific bug the owner asked you to investigate.
 
-- Ask a clarifying follow-up if an entry is vague ("how bad was the headache, 1-10?").
-- Reference a recent entry when useful ("last time you logged 5hrs sleep you also had a headache, same pattern?").
-- Offer to check in: "want me to ask about sleep tomorrow night?"
+Confirm the change in your reply so the owner sees what you did:
+> "Archived. Won't nudge you about it anymore. Entries stay in entries.jsonl as the historical record."
 
-Don't spam. One small nudge at a time, natural to the conversation. Never drag journal topics into a thread about something unrelated. Scheduled check-ins are handled separately by the system; your role here is in-conversation.
+## ASYNC background work
 
-### Setting up a new journal
+The chat queue is serialized per chat. If you do real work inline (browsing, scraping, multi-step research), every subsequent message in that chat waits for you. To stay responsive, delegate long work to a background worker.
 
-When the owner says something like "start a health journal":
+Two parts in the same reply:
 
-1. Propose a concrete purpose in one short message:
-   > "Health journal: tracking sleep, symptoms, meds, mood. Daily check-in at 21:00, nudge if silent 3 days. Sound right?"
-2. Wait for confirmation or edits.
-3. Once confirmed, create it by appending this marker to the END of your reply:
+1. A one or two-sentence ack in the reply text: "On it, will report back." / "Scraping now, give me a few minutes." / "Looking into it."
+2. Append at the END:
    ```
-   [JOURNAL-NEW:<slug> — <one-line purpose>]
+   [ASYNC: <self-sufficient task description>]
    ```
-   The marker will be stripped. The journal is created immediately and becomes active. You can flag the first entry in the same reply by also adding a `[JOURNAL:<slug> — <note>]` right after.
 
-Example end of reply:
+Example:
+
 ```
-[JOURNAL-NEW:health — Track sleep, symptoms, meds, mood]
-[JOURNAL:health — 5hrs sleep, mild headache]
+On it. Will send the list when it's ready.
+
+[ASYNC: Find 10 additional German TikTok creators documenting hair transplant journeys, 500-3000 followers, not in this list: @simply__stefan, @daenieal, @myhairjourney2025, @chigosfoodblog. Use the Rivoara TikTok account (already logged in) to browse. Output handle, follower count, one-line angle per creator.]
 ```
 
-Slug rules: lowercase letters, digits, hyphens. Max 48 chars. Must start with a letter or digit.
+### When to use ASYNC
 
-Be opinionated about the purpose. Don't ask ten questions; pick reasonable defaults and let them tweak.
+Use it for:
+- Browser work (scraping, multi-page research, form filling, anything touching >1 URL)
+- Multi-step investigations with several tool calls
+- Anything you expect to take more than ~30 seconds
 
-### Pausing, resuming, archiving
+Do NOT use it for:
+- A single quick URL fetch
+- Short calculations or reasoning
+- Anything you can answer from context alone
+- Things the owner needs answered in this reply, right now
 
-The owner can also ask you to pause/archive/resume a journal. Emit one of these markers:
+### Writing the task description
 
-```
-[JOURNAL-PAUSE:<slug>]
-[JOURNAL-RESUME:<slug>]
-[JOURNAL-ARCHIVE:<slug>]
-```
+The async worker has NO chat history, NO session, no memory of your conversation. Its only input is the description you write. Self-sufficient means:
+- Spell out exactly what to do.
+- Include every constraint, exclusion, and required context.
+- Reference specific tools or accounts (e.g. "use the Rivoara TikTok session").
+- Specify the expected output shape (list format, fields, order).
 
-Do this only when the owner asks. Never pause or archive a journal on your own judgment.
+Over-specify. A vague description produces a vague result.
 
-## Browser and screenshots
+### Avoiding duplicates
 
-You have access to a Chrome browser via tools: browser_navigate, browser_take_screenshot, browser_snapshot, browser_click, browser_type, browser_evaluate, and more.
+If you see `[Async tasks in progress]` in your preamble, a worker is already running for this chat. Do NOT emit another `[ASYNC:...]` for the same work. Reply naturally: "Still working on it, 4 minutes in."
 
-When asked to check a website, take a screenshot, or interact with a page, use these tools.
+## Sending files
 
-To send a file to the chat (screenshot, image, video, PDF, audio), save it to `storage/outbox/` and include this tag in your reply:
+To send a file (screenshot, image, video, PDF, audio) to the chat, save it to `storage/temp/` and include this tag in your reply:
 
 ```
-[FILE: storage/outbox/filename.png]
+[FILE: /absolute/path/to/file.png]
 ```
 
-Supported aliases: [IMAGE: path], [VIDEO: path], [AUDIO: path], [DOCUMENT: path] — all work the same.
+Aliases (all behave the same): `[IMAGE: path]`, `[VIDEO: path]`, `[AUDIO: path]`, `[DOCUMENT: path]`.
+
+Rules:
+- Always use absolute paths.
+- Always save under `storage/temp/`. Never save to the project root or anywhere else. Files are auto-deleted after sending.
+- Media type is detected from the file extension.
+- If you send a single file with a short text reply (under 1000 chars, non-audio), the text becomes the caption.
+
+## Browser tools
+
+You have a Chrome browser via Playwright MCP: `browser_navigate`, `browser_take_screenshot`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_evaluate`, etc.
+
+For anything beyond a single page load, use `[ASYNC: ...]` instead of running inline. Browser work blocks the main queue.
 
-Always save to `storage/outbox/`. Files are automatically deleted after sending. The tag will be stripped and the file sent as a WhatsApp media message. Auto-detects type from extension. Short text alongside a single file becomes the caption.
+To send a screenshot back: take it with the browser tool (save to `storage/temp/`), then include `[IMAGE: /absolute/path.png]` in your reply.

package/dist/gateway/commands.js

@@ -1,9 +1,12 @@
 import { clearSession, getSessionInfo } from '../ai/sessions.js';
 import { reloadSystemPrompt } from '../ai/claude.js';
 import { config } from '../config.js';
-import { createJournal, getJournal, isValidSlug, listJournals, readEntries, snoozeJournal, updateJournalStatus, } from '../memory/journals.js';
 import { runDigestNow } from '../memory/scheduler.js';
 import { sendText } from '../wa/sender.js';
+// Feature-level commands (/journal, /snooze, /tasks, etc.) are intentionally
+// absent. Claude is the interface — the owner asks for things in natural
+// language and Claude acts via markers or by editing files directly.
+// Only operational commands live here: reset, status, reload, digest.
 export async function tryCommand(ctx) {
     const prefix = config.commands.prefix;
     const trimmed = ctx.text.trim();
@@ -55,199 +58,5 @@ export async function tryCommand(ctx) {
         }).catch(() => undefined);
         return true;
     }
-    if (cmd === 'journal' || cmd === 'journals') {
-        if (!isOwner(ctx.senderNumber)) {
-            await sendText(ctx.sock, ctx.jid, 'Journals are owner-only.', ctx.quoted);
-            return true;
-        }
-        const rest = trimmed.slice(prefix.length + cmd.length).trim();
-        await handleJournalCmd(ctx, rest);
-        return true;
-    }
-    if (cmd === 'snooze') {
-        if (!isOwner(ctx.senderNumber)) {
-            await sendText(ctx.sock, ctx.jid, 'Snooze is owner-only.', ctx.quoted);
-            return true;
-        }
-        const rest = trimmed.slice(prefix.length + cmd.length).trim();
-        await handleSnoozeCmd(ctx, rest);
-        return true;
-    }
     return false;
 }
-async function handleSnoozeCmd(ctx, rest) {
-    const [slugRaw, durationRaw] = rest.split(/\s+/);
-    const slug = (slugRaw ?? '').toLowerCase();
-    const duration = (durationRaw ?? '24h').toLowerCase();
-    if (!slug) {
-        await sendText(ctx.sock, ctx.jid, 'Usage: /snooze <slug> [duration]\nDuration: e.g. 6h, 2d (default 24h)', ctx.quoted);
-        return;
-    }
-    if (!getJournal(slug)) {
-        await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
-        return;
-    }
-    const secs = parseDuration(duration);
-    if (!secs) {
-        await sendText(ctx.sock, ctx.jid, `Bad duration "${duration}". Use formats like 6h, 2d, 30m.`, ctx.quoted);
-        return;
-    }
-    const until = Math.floor(Date.now() / 1000) + secs;
-    snoozeJournal(slug, until);
-    await sendText(ctx.sock, ctx.jid, `Snoozed "${slug}" for ${duration}. No nudges until ${new Date(until * 1000).toISOString().slice(0, 16).replace('T', ' ')} UTC.`, ctx.quoted);
-}
-function parseDuration(raw) {
-    const m = raw.match(/^(\d+)\s*([mhd])$/);
-    if (!m)
-        return null;
-    const n = Number(m[1]);
-    const u = m[2];
-    if (!Number.isFinite(n) || n <= 0)
-        return null;
-    if (u === 'm')
-        return n * 60;
-    if (u === 'h')
-        return n * 3600;
-    if (u === 'd')
-        return n * 86400;
-    return null;
-}
-function isOwner(senderNumber) {
-    return !!config.owner.number && senderNumber === config.owner.number;
-}
-async function handleJournalCmd(ctx, rest) {
-    const [subRaw, ...argParts] = rest.split(/\s+/);
-    const sub = (subRaw ?? 'list').toLowerCase();
-    const args = argParts.join(' ').trim();
-    if (sub === 'list' || sub === '') {
-        const journals = listJournals();
-        if (journals.length === 0) {
-            await sendText(ctx.sock, ctx.jid, 'No journals yet. Create one with:\n/journal create <slug> <purpose>', ctx.quoted);
-            return;
-        }
-        const lines = ['Journals:'];
-        for (const j of journals) {
-            lines.push(`- ${j.slug} [${j.status}]: ${j.purpose || j.name}`);
-        }
-        await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);
-        return;
-    }
-    if (sub === 'create' || sub === 'new') {
-        const [slugRaw, ...purposeParts] = args.split(/\s+/);
-        const slug = (slugRaw ?? '').toLowerCase();
-        const purpose = purposeParts.join(' ').trim();
-        if (!slug || !purpose) {
-            await sendText(ctx.sock, ctx.jid, 'Usage: /journal create <slug> <purpose>\nExample: /journal create health Track sleep, symptoms, meds, mood', ctx.quoted);
-            return;
-        }
-        if (!isValidSlug(slug)) {
-            await sendText(ctx.sock, ctx.jid, `Invalid slug "${slug}". Use lowercase letters, digits, hyphens. Max 48 chars.`, ctx.quoted);
-            return;
-        }
-        if (getJournal(slug)) {
-            await sendText(ctx.sock, ctx.jid, `Journal "${slug}" already exists.`, ctx.quoted);
-            return;
-        }
-        try {
-            const j = createJournal({
-                slug,
-                name: titleCase(slug),
-                purpose,
-            });
-            await sendText(ctx.sock, ctx.jid, `Journal "${j.slug}" created and active. I'll start tagging relevant entries. Use /journal show ${j.slug} to inspect.`, ctx.quoted);
-        }
-        catch (err) {
-            await sendText(ctx.sock, ctx.jid, `Create failed: ${err.message}`, ctx.quoted);
-        }
-        return;
-    }
-    if (sub === 'show' || sub === 'info') {
-        const slug = args.split(/\s+/)[0]?.toLowerCase() ?? '';
-        const j = getJournal(slug);
-        if (!j) {
-            await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
-            return;
-        }
-        const lines = [
-            `${j.name} (${j.slug}) [${j.status}]`,
-            j.purpose,
-        ];
-        if (j.fields.length)
-            lines.push(`Fields: ${j.fields.join(', ')}`);
-        if (j.cadence.checkin)
-            lines.push(`Check-in: ${j.cadence.checkin}`);
-        if (j.cadence.followup_after)
-            lines.push(`Follow-up after: ${j.cadence.followup_after}`);
-        if (j.cadence.nudge_if_silent)
-            lines.push(`Nudge if silent: ${j.cadence.nudge_if_silent}`);
-        const entries = readEntries(j.slug, 5);
-        if (entries.length) {
-            lines.push('', 'Recent entries:');
-            for (const e of entries) {
-                const d = new Date(e.ts * 1000)
-                    .toISOString()
-                    .slice(0, 16)
-                    .replace('T', ' ');
-                lines.push(`- [${d}] ${e.note}`);
-            }
-        }
-        else {
-            lines.push('', '(no entries yet)');
-        }
-        await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);
-        return;
-    }
-    if (sub === 'entries') {
-        const [slugRaw, nRaw] = args.split(/\s+/);
-        const slug = (slugRaw ?? '').toLowerCase();
-        const n = Math.max(1, Math.min(50, Number(nRaw) || 10));
-        if (!getJournal(slug)) {
-            await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
-            return;
-        }
-        const entries = readEntries(slug, n);
-        if (!entries.length) {
-            await sendText(ctx.sock, ctx.jid, `No entries in "${slug}" yet.`, ctx.quoted);
-            return;
-        }
-        const lines = [`Last ${entries.length} entries in "${slug}":`];
-        for (const e of entries) {
-            const d = new Date(e.ts * 1000)
-                .toISOString()
-                .slice(0, 16)
-                .replace('T', ' ');
-            lines.push(`- [${d}] (${e.source}) ${e.note}`);
-        }
-        await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);
-        return;
-    }
-    if (sub === 'pause' || sub === 'resume' || sub === 'archive' || sub === 'activate') {
-        const slug = args.split(/\s+/)[0]?.toLowerCase() ?? '';
-        if (!getJournal(slug)) {
-            await sendText(ctx.sock, ctx.jid, `No journal "${slug}".`, ctx.quoted);
-            return;
-        }
-        const status = sub === 'pause'
-            ? 'paused'
-            : sub === 'archive'
-                ? 'archived'
-                : 'active';
-        const updated = updateJournalStatus(slug, status);
-        await sendText(ctx.sock, ctx.jid, `Journal "${slug}" is now ${updated?.status}.`, ctx.quoted);
-        return;
-    }
-    await sendText(ctx.sock, ctx.jid, [
-        'Journal commands:',
-        '/journal list',
-        '/journal create <slug> <purpose>',
-        '/journal show <slug>',
-        '/journal entries <slug> [n]',
-        '/journal pause|resume|archive <slug>',
-    ].join('\n'), ctx.quoted);
-}
-function titleCase(slug) {
-    return slug
-        .split('-')
-        .map((p) => (p ? p[0].toUpperCase() + p.slice(1) : p))
-        .join(' ');
-}

package/dist/memory/digest-flag.js

@@ -1,18 +1,21 @@
-const TRAILING_TAG_RE = /\[(DIGEST|JOURNAL|JOURNAL-NEW|JOURNAL-PAUSE|JOURNAL-RESUME|JOURNAL-ARCHIVE):\s*([^\]]+)\]\s*$/i;
+const TRAILING_TAG_RE = /\[(DIGEST|JOURNAL|JOURNAL-NEW|ASYNC):\s*([^\]]+)\]\s*$/i;
 // Peel trailing tags off the end of a reply. Supported:
 //   [DIGEST: <reason>]
 //   [JOURNAL:<slug> — <note>]         (append entry)
 //   [JOURNAL-NEW:<slug> — <purpose>]  (create journal)
-//   [JOURNAL-PAUSE:<slug>]
-//   [JOURNAL-RESUME:<slug>]
-//   [JOURNAL-ARCHIVE:<slug>]
-// Multiple tags are supported and can appear in any order at the tail.
-// Tags must be the LAST thing in the reply (after trimming trailing whitespace).
+//   [ASYNC: <self-sufficient task description>]
+// Multiple tags supported, any order at the tail. Tags must be the LAST
+// thing in the reply (after trimming trailing whitespace).
+//
+// Journal pause/resume/archive is intentionally NOT a marker. If the owner
+// wants those, Claude edits the journal's index.md frontmatter directly.
+// Keeping the marker vocabulary small keeps Claude's context tight.
 export function extractFlags(reply) {
     let current = reply;
     let digest = null;
     const journals = [];
-    const lifecycleOps = [];
+    const journalCreates = [];
+    const asyncTasks = [];
     while (true) {
         const trimmed = current.replace(/\s+$/, '');
         const match = trimmed.match(TRAILING_TAG_RE);
@@ -32,29 +35,17 @@ export function extractFlags(reply) {
         else if (kind === 'JOURNAL-NEW') {
             const parsed = parseJournalPayload(payload);
             if (parsed) {
-                lifecycleOps.unshift({
-                    kind: 'new',
-                    slug: parsed.slug,
-                    purpose: parsed.note,
-                });
+                journalCreates.unshift({ slug: parsed.slug, purpose: parsed.note });
             }
         }
-        else if (kind === 'JOURNAL-PAUSE' ||
-            kind === 'JOURNAL-RESUME' ||
-            kind === 'JOURNAL-ARCHIVE') {
-            const slug = payload.trim().toLowerCase();
-            if (/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
-                const op = kind === 'JOURNAL-PAUSE'
-                    ? 'pause'
-                    : kind === 'JOURNAL-RESUME'
-                        ? 'resume'
-                        : 'archive';
-                lifecycleOps.unshift({ kind: op, slug });
+        else if (kind === 'ASYNC') {
+            if (payload.length >= 8) {
+                asyncTasks.unshift({ description: payload });
             }
         }
         current = trimmed.slice(0, match.index).trimEnd();
     }
-    return { clean: current, digest, journals, lifecycleOps };
+    return { clean: current, digest, journals, journalCreates, asyncTasks };
 }
 // Legacy helper kept so existing callers still compile.
 export function extractDigestFlag(reply) {

package/dist/memory/journals.js

@@ -304,11 +304,3 @@ export function saveNudgeState(slug, state) {
     ensureDirFor(path);
     writeFileSync(path, JSON.stringify(state, null, 2) + '\n', 'utf-8');
 }
-export function snoozeJournal(slug, untilTs) {
-    if (!journalExists(slug))
-        return false;
-    const state = loadNudgeState(slug);
-    state.snoozedUntilTs = untilTs;
-    saveNudgeState(slug, state);
-    return true;
-}

package/dist/memory/preamble.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 import { config } from '../config.js';
+import { listAsyncTasks } from '../queue/async-tasks.js';
 import { buildJournalsPreambleBlock, ensureJournalsScaffold, } from './journals.js';
 import { masterIndexPath, treeIndexPath } from './paths.js';
 import { routeIndexes } from './router.js';
@@ -119,6 +120,19 @@ export function buildMemoryPreamble(params) {
         sections.push(`[Journals: active]\n${journalsBlock}`);
         instructions.push(JOURNAL_REMINDER);
     }
+    // Async tasks in progress for this chat — so Claude doesn't re-promise or
+    // contradict work already running in the background.
+    const asyncTasks = listAsyncTasks(params.jid);
+    if (asyncTasks.length > 0) {
+        const now = Math.floor(Date.now() / 1000);
+        const lines = ['You have background tasks currently running for this chat:'];
+        for (const t of asyncTasks) {
+            const ageSec = Math.max(0, now - t.startedAt);
+            lines.push(`- "${t.description}" (started ${formatAge(ageSec)} ago)`);
+        }
+        lines.push('', 'Do NOT re-start or re-promise these. Reply referencing that they are in progress if relevant, but do not emit another [ASYNC:...] for the same work.');
+        sections.push(`[Async tasks in progress]\n${lines.join('\n')}`);
+    }
     sections.push(`[Instruction]\n${instructions.join('\n\n')}`);
     return sections.join('\n\n');
 }
@@ -127,6 +141,13 @@ function readIfExists(path) {
         return null;
     return readFileSync(path, 'utf-8');
 }
+function formatAge(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m`;
+    return `${Math.floor(seconds / 3600)}h${Math.floor((seconds % 3600) / 60)}m`;
+}
 function buildTimeLine(timezone) {
     const now = new Date();
     const fmt = new Intl.DateTimeFormat('en-GB', {

package/dist/queue/async-tasks.js

@@ -0,0 +1,215 @@
+import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { config } from '../config.js';
+import fastq from 'fastq';
+import { initiate } from '../gateway/outgoing.js';
+import { logger } from '../logger.js';
+import { logPrompt } from '../promptlog.js';
+// Concurrency: how many async Claude workers can run simultaneously.
+// Start conservative — each process is expensive (Playwright, multi-minute runs).
+// Tune via config.asyncTasks.concurrency once we have real usage data.
+const CONCURRENCY = 3;
+// In-memory registry of tasks currently executing. Not persisted across
+// restarts — on reboot, any in-flight async work is silently dropped.
+// We expose listInProgress() so the chat preamble can show "in progress"
+// hints to the main Claude.
+const inProgress = new Map();
+const queue = fastq.promise(async (task) => {
+    inProgress.set(task.id, task);
+    try {
+        await runTask(task);
+    }
+    catch (err) {
+        logger.error({ err, id: task.id, jid: task.jid }, 'async task failed unexpectedly');
+    }
+    finally {
+        inProgress.delete(task.id);
+    }
+}, CONCURRENCY);
+export function enqueueAsyncTask(input) {
+    const task = {
+        ...input,
+        id: `async-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        startedAt: Math.floor(Date.now() / 1000),
+    };
+    logger.info({
+        id: task.id,
+        jid: task.jid,
+        description: task.description.slice(0, 200),
+    }, 'async task enqueued');
+    queue.push(task).catch((err) => logger.error({ err, id: task.id }, 'async queue push failed'));
+    return task;
+}
+export function listAsyncTasks(jid) {
+    const all = Array.from(inProgress.values());
+    if (!jid)
+        return all;
+    return all.filter((t) => t.jid === jid);
+}
+// ---------- task runner ----------
+let cachedSystemPrompt = null;
+function systemPrompt() {
+    if (cachedSystemPrompt !== null)
+        return cachedSystemPrompt;
+    const personality = readFileSync(resolve(process.cwd(), config.claude.personalityFile), 'utf-8');
+    let memoryInstructions = '';
+    try {
+        memoryInstructions = readFileSync(resolve(process.cwd(), config.memory.instructionsFile), 'utf-8');
+    }
+    catch {
+        // optional
+    }
+    cachedSystemPrompt = memoryInstructions
+        ? `${personality}\n\n---\n\n${memoryInstructions}`
+        : personality;
+    return cachedSystemPrompt;
+}
+export function reloadAsyncSystemPrompt() {
+    cachedSystemPrompt = null;
+}
+function buildPrompt(task) {
+    const lines = [
+        `You are running a BACKGROUND TASK for the owner. The chat already got your ack reply. Your only job now is to do the work and output the final message to send them.`,
+        ``,
+        `TASK:`,
+        task.description,
+        ``,
+        `ORIGINAL USER MESSAGE (for reference):`,
+        task.originatingMessage,
+        ``,
+        `Sender: ${task.senderName ?? task.senderNumber}`,
+        ``,
+        `RULES:`,
+        `- Stay fully in character (personality file). This is not customer service.`,
+        `- Do the real work. Use tools (browser, etc.) as needed.`,
+        `- When done, output ONLY the message to send the user. No preamble, no "here's what I found:" framing unless that's the message itself.`,
+        `- Do NOT emit any [DIGEST:...], [JOURNAL:...], [ASYNC:...], or other markers. This is the final output.`,
+        `- Start the message with a short reference to what you were working on so the user knows which task this is about (e.g. "About the TikTok scrape: ..."). They may have asked for multiple things.`,
+        `- If the task is impossible or the tools failed, say so honestly and briefly. Don't fabricate.`,
+        ``,
+        `Output the final user-facing message now.`,
+    ];
+    return lines.join('\n');
+}
+function buildArgs(task) {
+    const args = [
+        '-p',
+        '--output-format',
+        'json',
+        '--model',
+        config.claude.model,
+        '--permission-mode',
+        'acceptEdits',
+        '--append-system-prompt',
+        systemPrompt(),
+    ];
+    for (const dir of config.claude.addDirs) {
+        args.push('--add-dir', resolve(process.cwd(), dir));
+    }
+    args.push('--add-dir', resolve(process.cwd(), config.memory.dir));
+    args.push('--add-dir', resolve(process.cwd(), config.storage.mediaDir));
+    if (task.allowedTools &&
+        task.allowedTools !== 'all' &&
+        task.allowedTools.length > 0) {
+        args.push('--allowedTools', task.allowedTools.join(','));
+    }
+    return args;
+}
+async function spawnClaudeForTask(task, prompt) {
+    const args = buildArgs(task);
+    const startedAt = Date.now();
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn('claude', args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            cwd: process.cwd(),
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (c) => {
+            stdout += c.toString('utf-8');
+        });
+        child.stderr.on('data', (c) => {
+            stderr += c.toString('utf-8');
+        });
+        const logFail = (error) => void logPrompt({
+            ts: Math.floor(startedAt / 1000),
+            caller: 'async-task',
+            args,
+            input: prompt,
+            error,
+            durationMs: Date.now() - startedAt,
+        });
+        child.on('error', (err) => {
+            logFail(`spawn failed: ${err.message}`);
+            rejectPromise(err);
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                logFail(`exit ${code}: ${stderr.slice(0, 300)}`);
+                return rejectPromise(new Error(`async task exit ${code}`));
+            }
+            try {
+                const parsed = JSON.parse(stdout);
+                if (parsed.is_error ||
+                    parsed.subtype !== 'success' ||
+                    !parsed.result) {
+                    logFail(`bad output: ${parsed.result ?? stderr.slice(0, 200)}`);
+                    return rejectPromise(new Error('async task bad output'));
+                }
+                const output = parsed.result.trim();
+                void logPrompt({
+                    ts: Math.floor(startedAt / 1000),
+                    caller: 'async-task',
+                    args,
+                    input: prompt,
+                    output,
+                    durationMs: Date.now() - startedAt,
+                });
+                resolvePromise(output);
+            }
+            catch (err) {
+                logFail(`parse failed: ${err.message}`);
+                rejectPromise(err);
+            }
+        });
+        child.stdin.write(prompt);
+        child.stdin.end();
+    });
+}
+async function runTask(task) {
+    const prompt = buildPrompt(task);
+    const elapsedLog = () => `${Math.round((Date.now() - task.startedAt * 1000) / 1000)}s`;
+    let output;
+    try {
+        output = await spawnClaudeForTask(task, prompt);
+    }
+    catch (err) {
+        logger.error({ err, id: task.id, jid: task.jid, elapsed: elapsedLog() }, 'async task claude call failed');
+        await initiate({
+            jid: task.jid,
+            text: `Heads up: the background task "${truncate(task.description, 80)}" failed. Ask me again and I'll retry.`,
+        });
+        return;
+    }
+    // Strip any accidental trailing markers Claude emitted despite instructions.
+    // Import lazily to avoid an import cycle (digest-flag already stands alone,
+    // but being explicit here keeps this module independent).
+    const { extractFlags } = await import('../memory/digest-flag.js');
+    const { clean } = extractFlags(output);
+    if (!clean.trim()) {
+        logger.warn({ id: task.id, jid: task.jid }, 'async task produced empty output after flag strip');
+        return;
+    }
+    const sent = await initiate({ jid: task.jid, text: clean });
+    logger.info({
+        id: task.id,
+        jid: task.jid,
+        sent,
+        elapsed: elapsedLog(),
+        chars: clean.length,
+    }, 'async task completed');
+}
+function truncate(s, n) {
+    return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}

package/dist/queue/worker.js

@@ -2,8 +2,9 @@ import { askClaude } from '../ai/claude.js';
 import { clearSession, setSession, setUsage } from '../ai/sessions.js';
 import { logger } from '../logger.js';
 import { extractFlags } from '../memory/digest-flag.js';
-import { appendEntry, createJournal, getJournal, isValidSlug, updateJournalStatus, } from '../memory/journals.js';
+import { appendEntry, createJournal, getJournal, isValidSlug, } from '../memory/journals.js';
 import { scheduleDigest } from '../memory/scheduler.js';
+import { enqueueAsyncTask } from './async-tasks.js';
 function isStaleSessionError(err) {
     return (err instanceof Error &&
         err.message.includes('No conversation found'));
@@ -26,7 +27,7 @@ async function callClaude(job) {
         totalContextTokens,
         updatedAt: Math.floor(Date.now() / 1000),
     });
-    const { clean, digest, journals, lifecycleOps } = extractFlags(reply);
+    const { clean, digest, journals, journalCreates, asyncTasks } = extractFlags(reply);
     if (digest) {
         logger.info({ jid: job.jid, number: job.senderNumber, reason: digest }, 'DIGEST flag raised, scheduling');
         scheduleDigest({
@@ -35,43 +36,27 @@ async function callClaude(job) {
             reason: digest,
         });
     }
-    // Lifecycle ops run BEFORE entry appends so that a reply creating a new
-    // journal AND flagging its first entry in the same turn works correctly.
-    for (const op of lifecycleOps) {
+    // Creates run BEFORE entry appends so that a reply creating a new journal
+    // AND flagging its first entry in the same turn works correctly.
+    for (const op of journalCreates) {
         if (!isValidSlug(op.slug)) {
-            logger.warn({ op, jid: job.jid }, 'journal lifecycle op: invalid slug, dropped');
+            logger.warn({ op, jid: job.jid }, 'JOURNAL-NEW: invalid slug, dropped');
             continue;
         }
         try {
-            if (op.kind === 'new') {
-                if (getJournal(op.slug)) {
-                    logger.info({ slug: op.slug }, 'JOURNAL-NEW for existing slug, ignored');
-                    continue;
-                }
-                createJournal({
-                    slug: op.slug,
-                    name: titleCase(op.slug),
-                    purpose: op.purpose,
-                });
-                logger.info({ slug: op.slug, jid: job.jid }, 'journal created via bot marker');
-            }
-            else {
-                const status = op.kind === 'pause'
-                    ? 'paused'
-                    : op.kind === 'archive'
-                        ? 'archived'
-                        : 'active';
-                const updated = updateJournalStatus(op.slug, status);
-                if (updated) {
-                    logger.info({ slug: op.slug, status, jid: job.jid }, 'journal status updated via bot marker');
-                }
-                else {
-                    logger.warn({ op, jid: job.jid }, 'journal lifecycle op: unknown slug, dropped');
-                }
+            if (getJournal(op.slug)) {
+                logger.info({ slug: op.slug }, 'JOURNAL-NEW for existing slug, ignored');
+                continue;
             }
+            createJournal({
+                slug: op.slug,
+                name: titleCase(op.slug),
+                purpose: op.purpose,
+            });
+            logger.info({ slug: op.slug, jid: job.jid }, 'journal created via bot marker');
         }
         catch (err) {
-            logger.error({ err, op, jid: job.jid }, 'journal lifecycle op failed');
+            logger.error({ err, op, jid: job.jid }, 'JOURNAL-NEW failed');
         }
     }
     for (const j of journals) {
@@ -85,6 +70,19 @@ async function callClaude(job) {
             logger.warn({ slug: j.slug, jid: job.jid }, 'JOURNAL flag pointed at unknown slug, dropped');
         }
     }
+    // Async tasks: Claude delegated long work (browser scrapes, multi-step
+    // research, etc.) to the background lane. The clean reply above is the
+    // user-facing ack and will be sent normally. The async tasks run stateless
+    // in their own queue and report back via initiate() when done.
+    for (const t of asyncTasks) {
+        enqueueAsyncTask({
+            jid: job.jid,
+            senderNumber: job.senderNumber,
+            description: t.description,
+            originatingMessage: job.text,
+            allowedTools: job.allowedTools ?? 'all',
+        });
+    }
     return { reply: clean };
 }
 function titleCase(slug) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c4t4/heyamigo",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "WhatsApp AI bot powered by Claude with long-term memory, browser control, and role-based access",
   "type": "module",
   "main": "dist/index.js",