create-egregore 0.19.3 → 0.19.5

package/runtime/codex/bin/codex-install-skills.sh

@@ -71,7 +71,7 @@ for skill_dir in "$SOURCE_DIR"/*; do
   [ -f "$skill_dir/SKILL.md" ] || continue
   name="$(basename "$skill_dir")"
   mkdir -p "$TARGET_DIR/$name"
-  cp "$skill_dir/SKILL.md" "$TARGET_DIR/$name/SKILL.md"
+  cp -R "$skill_dir/." "$TARGET_DIR/$name/"
   copied=$((copied + 1))
 done
 

package/runtime/codex/bin/codex-render-spec.mjs

@@ -73,6 +73,12 @@ portable memory protocol below.
 Use the runtime-neutral bridge instead of Claude Code slash commands:
 
 \`\`\`bash
+bin/agent.sh branch --topic "auth review"
+bin/agent.sh save --message "Save: auth review" --topic "auth review"
+bin/agent.sh wrap --from alice --topic "auth review" \\
+  --summary "Implemented the OAuth callback parser and documented follow-ups." \\
+  --body "Open threads: review error cases and browser redirects."
+
 bin/agent.sh handoff --from alice --to bob --topic "auth review" \\
   --body "Implemented the OAuth callback parser. Bob should review error cases."
 
@@ -88,6 +94,17 @@ Each command writes to the existing Git-backed \`memory/\` repository and pushes
 when the memory repo has an \`origin\` remote. Agents that cannot run shell may
 write the same markdown files directly, following \`docs/AGENT-PROTOCOL.md\`.
 
+## Handoffs vs Emissaries
+
+\`bin/agent.sh handoff\` is the runtime-neutral path for internal team
+session-handoffs: it writes to \`memory/handoffs/\`, updates the index, and uses
+the same \`bin/handoff-run.sh\` machinery as Claude Code's \`/handoff\`.
+
+Portable external capsules are **emissaries**, not team handoffs. Claude Code
+routes those through \`/emissary\`; non-Claude agents should use the
+\`egregore-emissary\` CLI/skill when it is installed. Do not use the deprecated
+\`egregore-handoff\` CLI for Egregore project \`/handoff\` work.
+
 ## Compatibility
 
 Claude Code users continue using \`/handoff\`, \`/activity\`, \`/ask\`, \`/save\`, and
@@ -216,7 +233,7 @@ If this Codex build does not support hooks, follow the same discipline as a stan
 
 If the startup card output contains \`onboarding_needed\`, invoke the \`$onboarding\` skill instead of greeting.`;
 
-const COMMAND_AWARENESS_PREPEND = `Codex reserves leading \`/\` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching \`$name\` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: \`$activity\`, \`$handoff\`, \`$wrap\`, \`$announce\`, \`$harvest\`, \`$the-spiral\`, \`$dashboard\`, \`$deep-reflect\`, \`$quest\`, \`$invite\`, \`$ask\`, \`$save\`. Every other workflow has a generated adapter skill of the same name. \`$save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.`;
+const COMMAND_AWARENESS_PREPEND = `Codex reserves leading \`/\` for built-ins, so Egregore workflows are **skills**, not slash commands. Invoke them with the matching \`$name\` skill token or from natural language intent ("show activity", "make a handoff"). Hand-written native Codex skills: \`$activity\`, \`$handoff\`, \`$wrap\`, \`$announce\`, \`$harvest\`, \`$the-spiral\`, \`$dashboard\`, \`$deep-reflect\`, \`$quest\`, \`$invite\`, \`$ask\`, \`$save\`, \`$view\`, and \`$scroll\`. Every other workflow has a generated adapter skill of the same name. \`$save\` is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory — never make users manage the git workflow by hand.`;
 
 const SOCRATIC_BODY = `**Triggers**: "ask me questions", "question me", "help me think through", or any request to be questioned.
 

package/runtime/codex/bin/codex-session-start.sh

@@ -229,7 +229,7 @@ Follow AGENTS.md before code changes.
 After the user names what they are working on, use bin/agent.sh branch --topic "<work topic>" if you are not already in an appropriate task worktree, then continue file work from the printed worktree path.
 Use bin/agent.sh to update shared activity: handoff, ask, and answer write to memory/ and push when possible.
 Use bin/agent.sh handoff for internal team session-handoffs. Portable external capsules are emissaries; use egregore-emissary when installed, not the deprecated egregore-handoff CLI.
-Codex reserves leading slash commands for built-ins, so custom Egregore /activity-style commands will not reach the agent. Egregore native Codex skills are: \$activity, \$handoff, \$wrap, \$announce, \$harvest, \$the-spiral, \$dashboard, \$deep-reflect, \$quest, \$invite, \$ask, and \$save. Natural-language requests such as "show activity" or "make a handoff" work too. Remaining mirrored workflows are adapter skills for long-tail coverage.
+Codex reserves leading slash commands for built-ins, so custom Egregore /activity-style commands will not reach the agent. Egregore native Codex skills are: \$activity, \$handoff, \$wrap, \$announce, \$harvest, \$the-spiral, \$dashboard, \$deep-reflect, \$quest, \$invite, \$ask, \$save, \$view, and \$scroll. Natural-language requests such as "show activity", "make a handoff", or "render this as a scroll" work too. Remaining mirrored workflows are adapter skills for long-tail coverage.
 \$save is the user-facing abstraction for committing, pushing, opening or reusing pull requests, and syncing memory; do not make users manage the git workflow by hand.
 Egregore Codex workflows are skill invocations, not Claude Code slash commands. Do not rely on Claude Code-only command machinery.
 If onboarding_complete is false, use the memory protocol directly and make sure memory/people/${AUTHOR}.md exists before the first handoff.

package/runtime/codex/bin/codex-skill-render.mjs

@@ -143,7 +143,7 @@ function renderActivity(data) {
   const org = data.org || data.organization || 'Egregore';
   const date = data.date || '';
   const me = data.me?.github || data.me?.name || data.github_username || '';
-  const handoffs = firstArray(data, ['handoffs', 'pending_handoffs', 'me.handoffs', 'addressed_handoffs']);
+  const handoffs = firstArray(data, ['handoffs_to_me', 'handoffs', 'pending_handoffs', 'me.handoffs', 'addressed_handoffs']);
   const questions = firstArray(data, ['questions', 'pending_questions', 'me.questions']);
   const prs = asArray(data.prs);
   const mine = firstArray(data, ['local_sessions.my_sessions', 'my_sessions', 'sessions']);
@@ -159,12 +159,18 @@ function renderActivity(data) {
   if (questions.length === 0 && handoffs.length === 0) {
     lines.push(padLine('nothing pending'));
   } else {
-    questions.slice(0, 4).forEach((q) => {
-      lines.push(padLine(`? ${valueOf(q, ['from', 'author', 'asker'], 'someone')}: ${valueOf(q, ['topic', 'title', 'question'], 'question')}`));
-    });
-    handoffs.slice(0, 4).forEach((h) => {
-      lines.push(padLine(`> ${valueOf(h, ['author', 'from'], 'someone')}: ${valueOf(h, ['topic', 'title'], 'handoff')}`));
-    });
+    if (questions.length > 0) {
+      lines.push(padLine('QUESTIONS'));
+      questions.slice(0, 4).forEach((q) => {
+        lines.push(padLine(`● ${valueOf(q, ['from', 'author', 'asker'], 'someone')}: ${valueOf(q, ['topic', 'title', 'question'], 'question')}`));
+      });
+    }
+    if (handoffs.length > 0) {
+      lines.push(padLine('HANDOFFS'));
+      handoffs.slice(0, 4).forEach((h) => {
+        lines.push(padLine(`○ ${valueOf(h, ['author', 'from'], 'someone')}: ${valueOf(h, ['topic', 'title'], 'handoff')}`));
+      });
+    }
   }
 
   lines.push(rule());

package/runtime/codex/bin/codex-sync-skills.sh

@@ -19,6 +19,9 @@ NATIVE_SKILLS=(
   invite
   ask
   save
+  search
+  view
+  scroll
 )
 
 STRUCTURED_UX_SKILLS=(
@@ -54,6 +57,7 @@ STRUCTURED_UX_SKILLS=(
   emissary
   launch-site
   view
+  scroll
   visual-explain
   tui-design
 )

package/runtime/codex/bin/graph-op.sh

@@ -19,8 +19,11 @@ set -euo pipefail
 #                               remove-name to keep-name, stores remove-name as alias
 #   create-harvest <id> <topic> <intent> <initiator>
 #                               Create a Harvest node and link to initiator (WAL-backed)
-#   create-harvest-session <harvest-id> <session-id> <person-name>
-#                               Create a HarvestSession linked to a Harvest and Person
+#   create-harvest-session <harvest-id> <session-id> <person-name> [status]
+#                               Create a HarvestSession linked to a Harvest and Person.
+#                               status defaults to 'active' (back-compat). Valid values:
+#                               pending | active | answered | complete | incorporated.
+#                               Async respondents should be created with 'pending'.
 #   record-harvest-turn <session-id> <turn> <question> <intent> [answer] [eval]
 #                               Record a question-answer turn in a HarvestSession
 #   complete-harvest <harvest-id> <artifact-path>
@@ -42,6 +45,7 @@ if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
   echo "  merge-person <keep> <rm> Merge two Person nodes"
   echo "  claim-handoff <sid> <ho> Link implementing session to handoff"
   echo "  create-pr <sid> <num> <repo> <author> [title]"
+  echo "  register-artifact <id> <url> <title> <type> <author> <topics> <excerpt>"
   echo "  create-harvest / complete-harvest / record-harvest-turn"
   echo "  wal-status               Show WAL pending count"
   exit 0
@@ -202,6 +206,39 @@ case "$OP" in
     bash "$GS" query "$CYPHER" "$PARAMS"
     ;;
 
+  register-artifact)
+    # Index a published (hosted) artifact as an Artifact node so the finder can
+    # retrieve it from the graph in connected mode — by content (title/topics/
+    # excerpt CONTAINS) and by relationship (who made it, which quest). The node
+    # id is the registry FILENAME STEM (date-author-slug), matching sync-graph.sh
+    # so a later /save sync upserts the same node instead of duplicating it.
+    # args: <id> <url> <title> <type> <author-handle> <topics-csv> <excerpt>
+    A_ID="${1:?missing id}"
+    A_URL="${2:?missing url}"
+    A_TITLE="${3:-}"
+    A_TYPE="${4:-artifact}"
+    A_AUTHOR="$(printf '%s' "${5:-}" | tr '[:upper:]' '[:lower:]' | awk '{print $1}')"
+    A_TOPICS_JSON="$(printf '%s' "${6:-}" | jq -Rc 'split(",") | map(gsub("^\\s+|\\s+$";"")) | map(select(length > 0))' 2>/dev/null || echo '[]')"
+    A_EXCERPT="$(printf '%s' "${7:-}" | tr '\n' ' ' | cut -c1-2000)"
+    CYPHER="
+      MERGE (a:Artifact {id: \$id})
+      ON CREATE SET a.created = datetime()
+      SET a.title = \$title, a.type = \$type, a.url = \$url,
+          a.topics = \$topics, a.excerpt = \$excerpt, a.published = true
+      WITH a
+      OPTIONAL MATCH (p:Person)
+        WHERE \$author <> '' AND (toLower(p.name) = \$author OR p.github = \$author)
+      FOREACH (_ IN CASE WHEN p IS NOT NULL THEN [1] ELSE [] END |
+        MERGE (a)-[:CONTRIBUTED_BY]->(p))
+      RETURN a.id AS id
+    "
+    PARAMS="$(jq -n --arg id "$A_ID" --arg url "$A_URL" --arg title "$A_TITLE" --arg type "$A_TYPE" \
+      --arg author "$A_AUTHOR" --argjson topics "$A_TOPICS_JSON" --arg excerpt "$A_EXCERPT" \
+      '{id: $id, url: $url, title: $title, type: $type, author: $author, topics: $topics, excerpt: $excerpt}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    bash "$GS" query "$CYPHER" "$PARAMS"
+    ;;
+
   check-implements)
     SID="${1:?missing session-id}"
     bash "$GS" query "
@@ -305,16 +342,30 @@ case "$OP" in
     HID="${1:?missing harvest-id}"
     HSID="${2:?missing session-id}"
     PERSON="${3:?missing person-name}"
-    bash "$GS" query "
+    STATUS="${4:-active}"
+    case "$STATUS" in
+      pending|active|answered|complete|incorporated) ;;
+      *) jq -n --arg s "$STATUS" '{error:("invalid status: "+$s),valid:["pending","active","answered","complete","incorporated"]}' >&2; exit 2 ;;
+    esac
+    CYPHER="
       MATCH (h:Harvest {id: \$hid})
       MERGE (hs:HarvestSession {id: \$hsid})
-      ON CREATE SET hs.status = 'active', hs.created = datetime()
+      ON CREATE SET hs.status = \$status, hs.created = datetime()
       MERGE (h)-[:HAS_SESSION]->(hs)
       WITH hs
       MATCH (p:Person) WHERE toLower(p.name) = toLower(\$person) OR p.github = \$person
       MERGE (hs)-[:WITH]->(p)
       RETURN hs.id AS id, hs.status AS status
-    " "$(jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" '{hid: $hid, hsid: $hsid, person: $person}')"
+    "
+    PARAMS="$(jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" --arg status "$STATUS" '{hid: $hid, hsid: $hsid, person: $person, status: $status}')"
+    bash "$SCRIPT_DIR/bin/graph-wal.sh" append "$CYPHER" "$PARAMS" 2>/dev/null || true
+    OUT="$(bash "$GS" query "$CYPHER" "$PARAMS")"
+    if [ "$(echo "$OUT" | jq -r '.results | length' 2>/dev/null)" = "0" ]; then
+      jq -n --arg hid "$HID" --arg hsid "$HSID" --arg person "$PERSON" \
+        '{error:"create-harvest-session: harvest or person not found",hid:$hid,hsid:$hsid,person:$person}' >&2
+      exit 3
+    fi
+    echo "$OUT"
     ;;
 
   record-harvest-turn)

package/runtime/codex/bin/graph.sh

@@ -42,6 +42,22 @@ _millis() {
   fi
 }
 
+# --- Optional read-through cache (opt-in via EGREGORE_GRAPH_CACHE_TTL) ---
+# Read-only queries can be served from a local cache that bin/attendant.sh
+# keeps warm in the background, so callers on the launch path (session-start
+# greeting) pay zero network round-trips when warm. TTL in seconds; unset/0
+# disables. Mutating queries are never cached.
+_CACHE_TTL="${EGREGORE_GRAPH_CACHE_TTL:-0}"
+_CACHE_DIR="$HOME/.egregore/graph-cache/$(echo -n "$SCRIPT_DIR" | cksum | cut -d' ' -f1)"
+
+_cache_key() {
+  echo -n "$1|${2:-}" | cksum | cut -d' ' -f1
+}
+
+_is_read_query() {
+  ! echo "$1" | grep -qiE '\b(MERGE|CREATE|SET|DELETE|DETACH|REMOVE)\b'
+}
+
 if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
   # === API MODE: Call Egregore API gateway ===
 
@@ -54,6 +70,19 @@ if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
       params="{}"
     fi
 
+    local cache_file=""
+    if [ "$_CACHE_TTL" != "0" ] && _is_read_query "$cypher"; then
+      cache_file="$_CACHE_DIR/$(_cache_key "$cypher" "$params").json"
+      if [ -f "$cache_file" ]; then
+        local now cts
+        now=$(date +%s)
+        cts=$(jq -r '.ts // 0' "$cache_file" 2>/dev/null || echo 0)
+        if [ $(( now - cts )) -lt "$_CACHE_TTL" ]; then
+          jq -c '.result' "$cache_file" 2>/dev/null && return 0
+        fi
+      fi
+    fi
+
     local body
     body=$(jq -n --arg stmt "$cypher" --argjson params "$params" \
       '{statement: $stmt, parameters: $params}')
@@ -86,6 +115,13 @@ if [ -n "$API_URL" ] && [ -n "$API_KEY" ]; then
     bash "$SCRIPT_DIR/bin/telemetry.sh" emit "graph_query" \
       "$(jq -n --argjson latency "$latency_ms" '{latency_ms: $latency}')" 2>/dev/null &
 
+    # Store for the attendant to keep warm (query+params travel with the result)
+    if [ -n "$cache_file" ]; then
+      mkdir -p "$_CACHE_DIR" 2>/dev/null
+      jq -n --arg q "$cypher" --argjson p "$params" --argjson ts "$(date +%s)" --argjson r "$response" \
+        '{query: $q, params: $p, ts: $ts, result: $r}' > "$cache_file" 2>/dev/null || true
+    fi
+
     echo "$response"
   }
 

package/runtime/codex/bin/handoff-run.sh

@@ -48,6 +48,7 @@ PROJECT=""
 NO_PUSH=0
 NO_NOTIFY=0
 NO_PUBLISH=0
+COMPOSED=""    # optional house-kit JSON — the agent-composed render spec
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -55,6 +56,7 @@ while [ $# -gt 0 ]; do
     --topic)      TOPIC="${2:?}";     shift 2 ;;
     --recipient)  RECIPIENT="${2:-}"; shift 2 ;;
     --project)    PROJECT="${2:-}";   shift 2 ;;
+    --composed)   COMPOSED="${2:-}";  shift 2 ;;
     --no-push)    NO_PUSH=1;          shift ;;
     --no-notify)  NO_NOTIFY=1;        shift ;;
     --no-publish) NO_PUBLISH=1;       shift ;;
@@ -62,6 +64,16 @@ while [ $# -gt 0 ]; do
   esac
 done
 
+# The render source: the agent-composed house-kit JSON when supplied (rich
+# component render), else the markdown handoff (deterministic floor). The
+# markdown file is ALWAYS the memory record + graph index either way.
+RENDER_TYPE="handoff"
+RENDER_SRC=""   # resolved to $ABS_FILE after the file is written, unless composed
+if [ -n "$COMPOSED" ] && [ -f "$COMPOSED" ]; then
+  RENDER_TYPE="composed"
+  RENDER_SRC="$COMPOSED"
+fi
+
 [ -z "$AUTHOR" ] && { echo "Missing --author" >&2; exit 1; }
 [ -z "$TOPIC" ]  && { echo "Missing --topic"  >&2; exit 1; }
 
@@ -203,14 +215,13 @@ PID_GRAPH=$!
   ARTIFACTS_JSON="[]"
   if [ "$MODE" = "connected" ]; then
     YY=$(date +%Y); MM=$(date +%-m); DD_NUM=$(date +%-d)
-    PARAMS=$(jq -nc --arg gh "$AUTHOR" '{gh:$gh}')
     RAW=$(bash "$SCRIPT_DIR/bin/graph.sh" query "
       MATCH (a:Artifact)-[:CONTRIBUTED_BY]->(p:Person {github: \$gh})
       WHERE a.created >= datetime({year: $YY, month: $MM, day: $DD_NUM})
         AND NOT 'tutorial-generated' IN coalesce(a.topics, [])
       RETURN a.title AS title, a.type AS type, a.filePath AS path
       ORDER BY a.created DESC
-      LIMIT 5" "$PARAMS" 2>/dev/null || echo '{}')
+      LIMIT 5" "$(jq -nc --arg gh "$AUTHOR" '{gh:$gh}')" 2>/dev/null || echo '{}')
     # Response shape: {"fields":[...], "values":[[...], ...]}. Convert to
     # an array of {title, type, path} objects.
     ARTIFACTS_JSON=$(echo "$RAW" | jq -c '
@@ -282,24 +293,145 @@ PID_ARTIFACTS=$!
 PID_MEMORY=$!
 
 # --- Branch C: Publish artifact → Notify ---
+#
+# Strategy: handoffs publish ONCE, through the emissary write API, using
+# `render_mode: "custom"` so the server serves OUR pre-rendered HTML
+# verbatim (the same egregore-artifacts handoff template /view/ has
+# always used). This gives us:
+#   - one artifact, one URL (no legacy + new double-publish)
+#   - permanent egregore.xyz/emissary/e/<id> URL with /raw endpoint
+#   - handoff design fully owned client-side (egregore-artifacts) — the
+#     emissary server template is never invoked for handoffs and remains
+#     completely untouched
+#
+# Fallback: if emissary publish fails (token missing, network, size cap,
+# rendering failure), fall back to the legacy publish-artifact.sh path so
+# a handoff still gets a Telegram-able URL.
 (
+  V1URL=""
   AURL=""
-  if [ "$NO_PUBLISH" = "0" ] && [ -x "$SCRIPT_DIR/bin/publish-artifact.sh" ]; then
-    AURL=$(bash "$SCRIPT_DIR/bin/publish-artifact.sh" handoff "$ABS_FILE" \
+  if [ "$NO_PUBLISH" = "0" ]; then
+    EMISSARY_CONFIG="$HOME/.egregore/emissary-config.json"
+    EMISSARY_TOKEN=""
+    if [ -f "$EMISSARY_CONFIG" ]; then
+      EMISSARY_TOKEN=$(jq -r '.auth_token // empty' "$EMISSARY_CONFIG" 2>/dev/null)
+    fi
+    EMISSARY_API_URL="${EMISSARY_API_URL:-https://egregore-production-55f2.up.railway.app/api/v1/emissary}"
+
+    if [ -n "$EMISSARY_TOKEN" ]; then
+      # Step 1: render the handoff to HTML locally using egregore-artifacts.
+      # Same renderer + template publish-artifact.sh uses today — handoffs
+      # keep their familiar look.
+      RENDERED_HTML="$TMPD/handoff.html"
+      RENDER_OK=0
+      LOCAL_CLI="$SCRIPT_DIR/packages/egregore-artifacts/bin/cli.js"
+      if [ "${EGREGORE_USE_PUBLISHED:-0}" != "1" ] && [ -f "$LOCAL_CLI" ] && [ -d "$SCRIPT_DIR/packages/egregore-artifacts/node_modules/react" ]; then
+        if node "$LOCAL_CLI" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" --output "$RENDERED_HTML" >/dev/null 2>&1; then
+          RENDER_OK=1
+        fi
+      else
+        if npx egregore-artifacts "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" --output "$RENDERED_HTML" >/dev/null 2>&1; then
+          RENDER_OK=1
+        fi
+      fi
+
+      # Step 2: build the emissary payload. If rendering succeeded AND the
+      # HTML fits the server's 100KB cap, send it with render_mode=custom.
+      # If not, fall through to the structured-only path (server-rendered
+      # via the emissary template — undesirable for handoffs but still
+      # better than no URL).
+      if [ "$RENDER_OK" = "1" ] && [ -f "$RENDERED_HTML" ]; then
+        RENDER_SIZE=$(wc -c < "$RENDERED_HTML" | tr -d ' ')
+        if [ "$RENDER_SIZE" -gt 0 ] && [ "$RENDER_SIZE" -lt 100000 ]; then
+          # Author display name
+          DISPLAY_NAME="$AUTHOR"
+          PERSON_FILE="$SCRIPT_DIR/memory/people/${AUTHOR}.md"
+          if [ -f "$PERSON_FILE" ]; then
+            DISPLAY_NAME=$(head -1 "$PERSON_FILE" | sed 's/^# //')
+          fi
+
+          # addressed_to: only set if there's a recipient
+          ADDRESSED_TO="[]"
+          if [ -n "$RECIPIENT" ]; then
+            RECIP_HANDLE=$(echo "$RECIPIENT" | tr '[:upper:]' '[:lower:]' | awk '{print $1}')
+            ADDRESSED_TO=$(jq -nc --arg h "$RECIP_HANDLE" --arg d "$RECIPIENT" '[{"handle":$h,"display":$d}]')
+          fi
+
+          CLAIM=$(echo "$BRIEFING_LEAD" | cut -c1-200)
+
+          # body.prose is schema-required non-empty even when render_mode is
+          # "custom" (server validates structurally regardless of render
+          # mode). The visible page is the custom HTML; prose just needs to
+          # be non-empty plain text for /raw consumers and validation. Use
+          # the briefing lead (which the lead/claim is already derived from).
+          PROSE_TEXT="${BRIEFING_LEAD:-$TOPIC}"
+
+          # Use --rawfile so the rendered HTML is read directly from disk
+          # into a JSON-string. Faster than shell-var roundtrip and avoids
+          # any quoting headaches for HTML.
+          V1JSON=$(jq -nc \
+            --arg topic "$TOPIC" \
+            --arg claim "$CLAIM" \
+            --arg summary "$CLAIM" \
+            --arg prose "$PROSE_TEXT" \
+            --argjson addressed "$ADDRESSED_TO" \
+            --rawfile render_html "$RENDERED_HTML" \
+            '{
+              kind: "continuation",
+              topic: $topic,
+              claim: $claim,
+              summary: $summary,
+              body: { prose: $prose },
+              audience: {
+                addressed_to: $addressed,
+                visible_to: "public",
+                extendable_by: "anyone"
+              },
+              parents: [],
+              render_mode: "custom",
+              render_html: $render_html
+            }')
+
+          V1RESULT=$(curl -sf -X POST "$EMISSARY_API_URL/emissaries" \
+            -H "Content-Type: application/json" \
+            -H "Authorization: Bearer $EMISSARY_TOKEN" \
+            -d "$V1JSON" 2>/dev/null || echo '{}')
+
+          V1URL=$(echo "$V1RESULT" | jq -r '.url // ""' 2>/dev/null || echo "")
+        fi
+      fi
+    fi
+  fi
+
+  # Fallback: if the emissary publish didn't produce a URL (no token, no
+  # network, size cap, render failure), fire the legacy publish-artifact.sh
+  # so handoffs still get a Telegram-able URL.
+  if [ -z "$V1URL" ] && [ "$NO_PUBLISH" = "0" ] && [ -x "$SCRIPT_DIR/bin/publish-artifact.sh" ]; then
+    AURL=$(bash "$SCRIPT_DIR/bin/publish-artifact.sh" "$RENDER_TYPE" "${RENDER_SRC:-$ABS_FILE}" \
       --title "$TOPIC" \
       --author "$AUTHOR" \
       --description "$BRIEFING_LEAD" 2>/dev/null || echo "")
   fi
-  echo "$AURL" > "$TMPD/artifact"
+
+  # Prefer v1 (emissary-rendered) URL when available; fall back to the
+  # legacy egregore-artifacts URL only if the v1 publish failed.
+  NOTIFY_URL=""
+  if [ -n "$V1URL" ]; then
+    echo "$V1URL" > "$TMPD/artifact"
+    NOTIFY_URL="$V1URL"
+  else
+    echo "$AURL" > "$TMPD/artifact"
+    NOTIFY_URL="$AURL"
+  fi
 
   NS="skipped"
   if [ "$NO_NOTIFY" = "0" ]; then
-    if [ -n "$AURL" ]; then
+    if [ -n "$NOTIFY_URL" ]; then
       MSG_NOTIFY="Handoff from ${AUTHOR}: ${TOPIC}
 
 \"${BRIEFING_SHORT}\"
 
-View: ${AURL}"
+View: ${NOTIFY_URL}"
     else
       MSG_NOTIFY="Handoff from ${AUTHOR}: ${TOPIC}
 
@@ -345,9 +477,27 @@ if [ -s "$TMPD/graph" ]; then
   GRAPH_STATUS=$(sed -n '3p' "$TMPD/graph")
 fi
 [ -z "$RESOLVED" ] && RESOLVED=0
+# Sanitize: --argjson requires a number. If RESOLVED came back as a slug or
+# anything non-numeric (the index-handoff.sh output format has drifted in
+# the past — defensive guard), fall back to 0 so the result file still builds.
+if ! echo "$RESOLVED" | grep -qE '^[0-9]+$'; then
+  RESOLVED=0
+fi
 
 SUBGRAPH_JSON=$(cat "$TMPD/subgraph" 2>/dev/null || echo "null")
 [ -z "$SUBGRAPH_JSON" ] && SUBGRAPH_JSON="null"
+# Sanitize: --argjson requires valid JSON. Multiple writes to the same
+# tmpfile have produced concatenated values in the past (e.g. "null\n{...}"),
+# which jq rejects on multi-document input. Validate; on failure, take the
+# LAST non-empty line and re-validate; if still bad, fall back to null.
+if ! printf '%s' "$SUBGRAPH_JSON" | jq -s 'length == 1' 2>/dev/null | grep -q '^true$'; then
+  LAST_LINE=$(printf '%s\n' "$SUBGRAPH_JSON" | awk 'NF{last=$0} END{print last}')
+  if printf '%s' "$LAST_LINE" | jq -e '.' >/dev/null 2>&1; then
+    SUBGRAPH_JSON="$LAST_LINE"
+  else
+    SUBGRAPH_JSON="null"
+  fi
+fi
 
 MEMORY_STATUS=$(cat "$TMPD/memory"   2>/dev/null || echo "skipped")
 ARTIFACT_URL=$(cat "$TMPD/artifact"  2>/dev/null || echo "")

package/runtime/codex/bin/handoff-save-egregore.sh

@@ -45,6 +45,11 @@ SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 [ -z "$REPO_DIR" ] && REPO_DIR="$SCRIPT_DIR"
 cd "$REPO_DIR" || exit 1
 
+# Shared safe-staging guard — never auto-commit stray sibling-repo gitlinks.
+# shellcheck source=bin/lib/git-safe.sh
+. "$SCRIPT_DIR/bin/lib/git-safe.sh" 2>/dev/null || true
+type git_add_guarded >/dev/null 2>&1 || git_add_guarded() { git add -A 2>/dev/null || true; }
+
 # --- Early exit if nothing to do -----------------------------------------
 DIRTY=0
 [ -n "$(git status --porcelain 2>/dev/null)" ] && DIRTY=1
@@ -75,7 +80,7 @@ esac
 
 # --- Commit whatever is uncommitted --------------------------------------
 if [ -n "$(git status --porcelain 2>/dev/null)" ]; then
-  git add -A 2>/dev/null || true
+  git_add_guarded
   git commit -m "Handoff: ${TOPIC}" --quiet 2>/dev/null || true
 fi
 

package/runtime/codex/bin/index-handoff.sh

@@ -131,6 +131,10 @@ fi
 PROJECT="$(md_field 'Project')"
 [ -z "$PROJECT" ] && PROJECT="$(yaml_extract 'project')"
 
+# Handoff kind: used by readers to distinguish automatic captures from manual handoffs.
+KIND="$(md_field 'Kind')"
+[ -z "$KIND" ] && KIND="$(yaml_extract 'kind')"
+
 # Summary: 5-level precedence chain
 # 1. Frontmatter summary field
 SUMMARY="$(yaml_extract 'summary')"
@@ -198,8 +202,9 @@ fi
 
 Q1_CYPHER="MATCH (p:Person) WHERE toLower(p.name) = \$author OR p.github = \$author OR toLower(p.fullName) = \$author OR \$author IN [x IN coalesce(p.previousNames, []) | toLower(x)]
 MERGE (s:Session {id: \$sessionId})
-ON CREATE SET s.date = date(\$date), s.topic = \$topic, s.summary = \$summary, s.filePath = \$filePath, s.handoffStatus = 'pending', s.repoState = \$repoState, s.startedAt = datetime(\$date + 'T00:00:00Z')
-ON MATCH SET s.topic = \$topic, s.summary = \$summary, s.filePath = \$filePath, s.repoState = \$repoState
+ON CREATE SET s.date = date(\$date), s.topic = \$topic, s.summary = \$summary, s.filePath = \$filePath, s.author = \$author, s.handoffKind = CASE WHEN \$kind = '' THEN null ELSE \$kind END, s.handoffStatus = 'pending', s.repoState = \$repoState, s.startedAt = datetime(\$date + 'T00:00:00Z')
+ON MATCH SET s.topic = \$topic, s.summary = \$summary, s.filePath = \$filePath, s.author = \$author, s.handoffKind = CASE WHEN \$kind = '' THEN null ELSE \$kind END, s.repoState = \$repoState
+WITH s, p
 MERGE (s)-[:BY]->(p)${PROJECT_CYPHER}${HANDED_TO_CYPHER}
 RETURN s.id AS sessionId"
 
@@ -210,6 +215,7 @@ Q1_PARAMS=$(jq -n \
   --arg topic "$TOPIC" \
   --arg summary "$SUMMARY" \
   --arg filePath "$REL_PATH" \
+  --arg kind "$KIND" \
   --arg repoState "$REPO_STATE_JSON" \
   "${_PROJECT_ARGS[@]:+${_PROJECT_ARGS[@]}}" \
   "${_RECIP_ARGS[@]:+${_RECIP_ARGS[@]}}" \
@@ -273,7 +279,7 @@ CURRENT_SID=$(cat "$HOME/.egregore/session-${PROJ_HASH}.id" 2>/dev/null || echo
 if [ -n "$CURRENT_SID" ]; then
   bash "$SCRIPT_DIR/bin/graph.sh" query \
     "MATCH (s:Session {id: \$sid}) SET s.status = 'handed_off' RETURN s.id" \
-    "$(jq -n --arg sid "$CURRENT_SID" '{sid: $sid}')" 2>/dev/null || true
+    "$(jq -n --arg sid "$CURRENT_SID" '{sid: $sid}')" >/dev/null 2>&1 || true
 fi
 
 # --- Parse response ---