Add orchestra: named scripts for permission-free agent operations (#29)

* Add orchestra: named scripts for permission-free agent operations

14 named scripts that wrap common Hey, tracker, and vault operations
into single commands. When added to the Bash permission allowlist,
they eliminate repeated permission prompts during email triage and
vault operations.

Scripts derive vault path from their own location (portable).
Installer and updater copy them to Meta/scripts/ in the vault.
Postman agent and email-triage skill updated to prefer scripts
over inline pipelines.

* Address Copilot review feedback on orchestra scripts

- Pass shell variables to Python via sys.argv instead of string
  interpolation to prevent quoting/injection issues
- Validate --mailbox argument has a value before shifting
- Validate numeric arguments (hours, days) as integers
- Fix vault-stats folder list to use bash array (word splitting)
- Fix vault-inbox to handle missing 00-Inbox/ gracefully
- Remove unused import os from hey-check
- Narrow postman.md allowed commands from Meta/scripts/* wildcard
  to explicitly named scripts
- Add .core-manifest tracking for scripts in launchme.sh/updateme.sh
  with deprecation of removed scripts on update
- Fix contact-lookup description (matches senders only, not recipients)

* Fix orchestra scripts bugs, security allowlist, and docs consistency

- Replace deprecated datetime.utcnow() with datetime.now(timezone.utc)
  in hey-check for Python 3.12+ compatibility
- Replace bare except: with except Exception: in all 6 tracker/lookup
  scripts to avoid swallowing KeyboardInterrupt and SystemExit
- Fix postman.md Hey triage step numbering (5→7 gap, now 1-9 sequential)
- Add Meta/scripts/ commands to email-triage SKILL.md allowed Bash list
  (procedure referenced them but security section blocked them)
- Update email-triage templates from hardcoded "Gmail" to {{source}}
  placeholder for Hey/Gmail/MCP compatibility
- Add orchestra/ directory to README project structure tree and
  Meta/scripts/ to installed vault structure diagram

* Address Copilot review: timestamp comparison, stale scripts, naming, JSON

- Fix tracker-recent timestamp comparison: truncate both cutoff and
  active_at to YYYY-MM-DDTHH:MM:SS before comparing, avoiding
  unreliable lexicographic comparison of Z vs +00:00 suffixes
- Fix contact-lookup dedup: skip entries with no topic_id to prevent
  unrelated results collapsing into a single None key
- Rename hey-thread parameter from <topic_id> to <posting_id> to
  align with Hey CLI terminology and hey-seen naming
- Fix orchestra README JSON snippet: wrap in valid settings.json
  structure so users can copy/paste without syntax errors
- Add stale script cleanup to launchme.sh on reinstall, mirroring
  the existing agent deprecation logic
- Separate removed-scripts counter from deprecated-files counter
  in updateme.sh summary for accurate messaging

---------

Co-authored-by: gnekt <dima9610@gmail.com>

scripts/launchme.sh

@@ -157,6 +157,36 @@ if [[ -d "$REPO_DIR/skills" ]]; then
   success "Copied $SKILL_COUNT skills"
 fi
 
+# ── Deprecate stale orchestra scripts on reinstall ──────────────────────────
+OLD_ORCH_MANIFEST="$VAULT_DIR/Meta/scripts/.core-manifest"
+if [[ $EXISTING -eq 1 && -f "$OLD_ORCH_MANIFEST" ]]; then
+  while IFS= read -r old_script; do
+    [[ -z "$old_script" ]] && continue
+    [[ -f "$REPO_DIR/orchestra/$old_script" ]] && continue
+    vault_script="$VAULT_DIR/Meta/scripts/$old_script"
+    [[ -f "$vault_script" ]] || continue
+    rm "$vault_script"
+    warn "Removed stale script: $old_script"
+  done < "$OLD_ORCH_MANIFEST"
+fi
+
+# ── Copy orchestra scripts ──────────────────────────────────────────────────
+ORCH_COUNT=0
+if [[ -d "$REPO_DIR/orchestra" ]]; then
+  mkdir -p "$VAULT_DIR/Meta/scripts"
+  : > "$VAULT_DIR/Meta/scripts/.core-manifest"
+  for script in "$REPO_DIR/orchestra/"*; do
+    [[ -f "$script" ]] || continue
+    bname="$(basename "$script")"
+    [[ "$bname" == "README.md" ]] && continue
+    cp "$script" "$VAULT_DIR/Meta/scripts/"
+    chmod +x "$VAULT_DIR/Meta/scripts/$bname"
+    echo "$bname" >> "$VAULT_DIR/Meta/scripts/.core-manifest"
+    ORCH_COUNT=$((ORCH_COUNT + 1))
+  done
+  success "Copied $ORCH_COUNT orchestra scripts to Meta/scripts/"
+fi
+
 # ── Copy CLAUDE.md ───────────────────────────────────────────────────────────
 if [[ -f "$REPO_DIR/CLAUDE.md" ]]; then
   cp "$REPO_DIR/CLAUDE.md" "$VAULT_DIR/CLAUDE.md"
@@ -223,6 +253,8 @@ echo -e "   │   ├── skills/          ${DIM}← ${SKILL_COUNT:-0} crew sk
 echo -e "   │   ├── hooks/           ${DIM}← ${HOOK_COUNT:-0} hooks${NC}"
 echo -e "   │   ├── settings.json    ${DIM}← hooks configuration${NC}"
 echo -e "   │   └── references/      ${DIM}← shared docs${NC}"
+echo -e "   ├── Meta/"
+echo -e "   │   └── scripts/         ${DIM}← ${ORCH_COUNT:-0} orchestra scripts${NC}"
 echo -e "   ├── CLAUDE.md            ${DIM}← project instructions${NC}"
 if [[ "$MCP_ANSWER" =~ ^[Yy]$ ]]; then
 echo -e "   └── .mcp.json            ${DIM}← Gmail + Calendar${NC}"

scripts/updateme.sh

@@ -266,6 +266,41 @@ if [[ -f "$REPO_DIR/settings.json" ]]; then
   fi
 fi
 
+# ── Remove stale orchestra scripts ────────────────────────────────────────
+ORCH_MANIFEST="$VAULT_DIR/Meta/scripts/.core-manifest"
+REMOVED_SCRIPTS=0
+if [[ -d "$REPO_DIR/orchestra" && -f "$ORCH_MANIFEST" ]]; then
+  while IFS= read -r old_script; do
+    [[ -z "$old_script" ]] && continue
+    [[ -f "$REPO_DIR/orchestra/$old_script" ]] && continue
+    vault_script="$VAULT_DIR/Meta/scripts/$old_script"
+    [[ -f "$vault_script" ]] || continue
+    rm "$vault_script"
+    warn "Removed stale script: $old_script"
+    REMOVED_SCRIPTS=$((REMOVED_SCRIPTS + 1))
+  done < "$ORCH_MANIFEST"
+fi
+
+# ── Update orchestra scripts ──────────────────────────────────────────────
+ORCH_COUNT=0
+if [[ -d "$REPO_DIR/orchestra" ]]; then
+  mkdir -p "$VAULT_DIR/Meta/scripts"
+  : > "$VAULT_DIR/Meta/scripts/.core-manifest"
+  for script in "$REPO_DIR/orchestra/"*; do
+    [[ -f "$script" ]] || continue
+    bname="$(basename "$script")"
+    [[ "$bname" == "README.md" ]] && continue
+    echo "$bname" >> "$VAULT_DIR/Meta/scripts/.core-manifest"
+    dst="$VAULT_DIR/Meta/scripts/$bname"
+    if [[ ! -f "$dst" ]] || ! diff -q "$script" "$dst" >/dev/null 2>&1; then
+      cp "$script" "$dst"
+      chmod +x "$dst"
+      info "Updated script: $bname"
+      ORCH_COUNT=$((ORCH_COUNT + 1))
+    fi
+  done
+fi
+
 # ── Update CLAUDE.md ──────────────────────────────────────────────────────
 CLAUDE_MD_UPDATED=""
 if [[ -f "$REPO_DIR/CLAUDE.md" ]]; then
@@ -278,13 +313,16 @@ fi
 
 # ── Summary ─────────────────────────────────────────────────────────────────
 echo ""
-if [[ $AGENT_COUNT -eq 0 && $REF_COUNT -eq 0 && $SKILL_COUNT -eq 0 && $HOOK_COUNT -eq 0 && $DEPRECATED_COUNT -eq 0 && -z "$CLAUDE_MD_UPDATED" && -z "$SETTINGS_UPDATED" ]]; then
+if [[ $AGENT_COUNT -eq 0 && $REF_COUNT -eq 0 && $SKILL_COUNT -eq 0 && $HOOK_COUNT -eq 0 && $ORCH_COUNT -eq 0 && $DEPRECATED_COUNT -eq 0 && $REMOVED_SCRIPTS -eq 0 && -z "$CLAUDE_MD_UPDATED" && -z "$SETTINGS_UPDATED" ]]; then
   success "Everything is already up to date!"
 else
-  success "Updated $AGENT_COUNT agent(s), $SKILL_COUNT skill(s), $REF_COUNT reference(s), $HOOK_COUNT hook(s)"
+  success "Updated $AGENT_COUNT agent(s), $SKILL_COUNT skill(s), $REF_COUNT reference(s), $HOOK_COUNT hook(s), $ORCH_COUNT script(s)"
   if [[ $DEPRECATED_COUNT -gt 0 ]]; then
     warn "Deprecated $DEPRECATED_COUNT file(s) no longer in the project"
   fi
+  if [[ $REMOVED_SCRIPTS -gt 0 ]]; then
+    warn "Removed $REMOVED_SCRIPTS stale script(s) from Meta/scripts/"
+  fi
 fi
 echo ""
 echo -e "   ${DIM}Restart Claude Code to pick up the changes.${NC}"