legal-ai/docs/paperclip-quirks.md

Paperclip Quirks — מלכודות ידועות

הקשר: מה ש-Paperclip עושה בעצמו, מתחת לרגליהם של הסוכנים שלנו, ושאנחנו צריכים לעקוף אותו או לחיות איתו.

כל מלכודת מתועדת עם:

1. מה קורה בפועל
2. ראיה אמפירית מתוך לוגים
3. ההשפעה על הצינור שלנו
4. עקיפה / תיקון / קבלה

---

1. issue.released הופך done ל-todo

מה קורה

לאחר שסוכן מבצע PATCH /api/issues/{id} עם status: done, Paperclip מבצע פעולה נוספת בשם issue.released מספר שניות מאוחר יותר. ל-issue.released יש side-effect לא-מתועד שמחזיר את ה-status ל-todo.

ראיה אמפירית — תיק 8174-24, CMPA-18 (30/04/26)

מתוך activity_log:

ts        | action              | actor_type | details
----------+---------------------+------------+----------------------------------------
18:14:49  | issue.comment_added | agent      | comment by researcher
18:14:57  | issue.updated       | agent      | {"status": "done", "_previous": {"status": "in_progress"}}
18:15:35  | issue.released      | agent      |                       ← here

מצב מ-issues table 38 שניות לאחר ה-released:

identifier | status | updated_at
CMPA-18    | todo   | 18:15:35

ה-status חזר מ-done ל-todo למרות שאף סוכן או משתמש לא ביקש זאת.

ההשפעה על הצינור שלנו

Paperclip מזהה issue ב-todo כ"יש עבודה לעשות" → מיד מפעיל wakeup לסוכן הרלוונטי → הסוכן רץ שוב עם prompt cache מלא (~$0.10-0.50 פר-ריצה) → מסתכל סביב ומבין שהעבודה כבר נעשתה → סוגר את ה-issue שוב → issue.released חוזר על עצמו ⇒ פוטנציאל ללולאה.

עקיפה — בצד שלנו (ללא תיקון Paperclip)

הסוכן שלנו עושה זאת כבר היום בהצלחה במקרה שהוא רואה issue ב-todo עם תוצרים קיימים:

1. בודק שהקבצים הצפויים קיימים (Glob /documents/research/*.md)
2. בודק שה-DB מאוכלס (mcp__legal-ai__precedent_list, get_claims, וכו')
3. אם הכל קיים → לא מבצע עבודה כפולה → כותב comment "אין שינוי" → PATCH issue → done

הראיה: בריצה החוזרת (PID 309786 ב-30/04/26 18:15:54), המנתח של החוקר זיהה תוך 90 שניות שכל 9 התקדימים והקובץ קיימים, וסגר את ה-issue ב-PATCH → done שוב. הריצה הזאת עלתה כ-$0.20 — לא חינם, אבל לא לולאה.

אם תרצה לחקור פנימה

ה-issue.released נרשם ב-activity_log עם actor_type=agent אבל בלי agent_id שמסביר מי. הוא לא נכתב על ידי הסקריפטים שלנו (אנחנו לא קוראים endpoint כזה). מקור אפשרי:

• מנגנון executionLockedAt / executionWorkspaceId של Paperclip שמשחרר משאבים אחרי שריצה מסתיימת ובמקביל מאפס status

האפשרות הנכונה לסגור את הבאג היא ב-Paperclip עצמו — לתקן את issue.released שלא ידרוס status מסוף-מצב כמו done. עד שזה נסגר אצלם, אנחנו חיים עם self-recovery.

סטטוס

• לא נסגר ב-Paperclip (ידוע לפי 30/04/26)
• טופל בצד שלנו דרך self-recovery בסקייל של הסוכן (HEARTBEAT.md §4-recovery)
• לתעד עלות: כל ריצת self-recovery מוסיפה ~$0.20 לתיק

---

2. Bash backtick trap בעת בניית comment body דרך curl

מה קורה

הסוכן בונה pipeline מורכב כדי לפרסם comment עם markdown ארוך:

curl ... -d "$(python3 -c "
body = '''## כותרת
📁 קובץ: \`/path/to/file.md\`
'''
print(json.dumps({'body': body}))")"

ה-bash שמריץ את ה-$(...) הראשון רואה את ה-backticks ( ) בתוך המחרוזת של Python ומפרש אותם **כ-command substitution של bash**. הוא מנסה להריץ את/path/to/file.md` כפקודה, ומכיוון שהקובץ לא executable — מחזיר:

/bin/bash: line 56: /path/to/file.md: Permission denied

ההטעיה

ההודעה Permission denied היא לא באמת בעיית הרשאות:

• ls -la מראה שהקובץ הוא chaim:chaim עם -rw-r--r--
• touch ידני באותו נתיב מצליח
• ה-Write tool כבר כתב את הקובץ הזה בהצלחה דקה קודם

למה זה קורה דווקא בנתיבי מסמכים

Backticks הם תחביר markdown נפוץ לציטוט נתיבים: `/home/chaim/...`. בפלט markdown זה נכון, אבל כשהסוכן מטמיע את ה-markdown בתוך bash heredoc / command substitution, ה-backticks מפעילים את עצמם.

תיקון — דפוס "כתוב לקובץ זמני אז curl -d @file"

במקום:

curl ... -d "$(python3 -c "...long body with backticks...")"

עשה:

# 1. כתוב את ה-body לקובץ זמני דרך Write tool (בלי שום bash quoting)
Write("/tmp/comment.json", json.dumps({"body": markdown_body}))

# 2. אז curl קורא מהקובץ — אין shell expansion על התוכן
curl -s -X POST -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
  -H "Content-Type: application/json" \
  "$PAPERCLIP_API_URL/api/issues/{issue-id}/comments" \
  -d @/tmp/comment.json

הנתיב -d @file קורא את התוכן של הקובץ בלי שום ניתוח — אין shell, אין quoting, אין backticks-as-commands. זה גם מאפשר body של 10K+ תווים ללא הגבלת ARG_MAX.

סטטוס

• תיעוד ב-HEARTBEAT.md עם הוראה מפורשת להשתמש ב-Write+-d @file ל-bodies מעל 500 תווים
• השפעה היסטורית: לפני התיקון, הריצה ב-CMPA-18 (30/04/26) הצליחה (curl באמת רץ) — אבל ה-Permission denied בלוג היה מבלבל וגרם לחקירה. עתה שהסיבה ידועה, אפשר להתעלם.

---

3. CEO main issue auto-block ב-in_progress

מה קורה

CEO שמסיים turn (פרסם comment "ממתין לסיום של סוכן Y") ומשאיר את ה-issue ב-in_progress יקבל auto-block תוך דקה אחת מ-Paperclip ("live execution disappeared"). הסטטוס יקפוץ ל-blocked ויידרש wakeup ידני להמשיך.

עקיפה

CEO צריך להעביר את ה-issue ל-in_review (לא in_progress) כשהוא ממתין למשאב חיצוני (סוכן אחר, יו"ר). זה מתועד ב-CLAUDE.md זיכרון: feedback_paperclip_enums.md.

סטטוס

• תיקון ב-legal-ceo.md (commit a1969dd)
• נצפה עובד ב-CMPA-15 ב-30/04/26 — ה-CEO עבר ל-in_review נכון

---

4. Wakeup דרך DB ישיר ≠ wakeup דרך API

מה קורה

INSERT INTO agent_wakeup_requests ידני בלי לעבור דרך POST /api/agents/{id}/wakeup יוצר רשומת wakeup אבל לא יוצר heartbeat_run. בלי heartbeat_run, ה-runtime של Paperclip לא מזהה שיש משהו להריץ → הסוכן לעולם לא מתעורר.

עקיפה

תמיד להשתמש ב-API. כל הסקייל שלנו תועדו עם האזהרה הזאת.

סטטוס

• תיקון בכל הסקייל (CLAUDE.md זיכרון: reference_paperclip_wakeup.md)

---

5. מחיקת npx cache → crash-loop בהפעלה (השרת מנצח את הפאטצ')

מה קורה

Paperclip מופעל דרך exec npx -y paperclipai@<version> run ב-start-paperclip.sh. npx עושה reuse ל-cache שכבר חולץ (~/.npm/_npx/<hash>/node_modules/@paperclipai/server/) — הוא לא מחלץ מחדש בכל הפעלה. כל עוד ה-cache קיים, הפאטצ'ים שהוחלו עליו פעם אחת נשמרים על פני ריסטארטים.

הבעיה מתחילה כש-ה-cache נמחק (npm cache clean, prune, או ניקוי ידני) בזמן שהתהליך רץ. אז נוצרות שתי תקלות נפרדות:

1. התהליך הישן ממשיך "online" אבל שבור — המודולים של node כבר טעונים בזיכרון, אז /api/health עדיין מחזיר 200, אבל GET / קורא את ui-dist/index.html מהדיסק בכל בקשה (readFileSync) → ENOENT → HTTP 500 ({"error":"Internal server error"}). גם ה-URL הציבורי pc.nautilus... מחזיר 500.
2. בריסטארט נכנסים ל-crash-loop — npx מחלץ עותק טרי ולא-מתוקן. השרת מריץ assertCloudDatabaseContract() (ראה patch §4 ב-start script) שמסרב ל-embedded PG במצב authenticated/public → קורס מיד, לפני שלולאת-הרקע (5/20/60ש') מספיקה להחיל את פאטץ' ה-bypass. כל ריסטארט מחלץ-וקורס מחדש ⇒ עשרות ריסטארטים, שום דבר לא מאזין על 3100.

ראיה אמפירית — 06/06/26

# התהליך הישן: online 5D אבל GET / נכשל
GET / 500 — ENOENT: no such file or directory,
  open '.../@paperclipai/server/ui-dist/index.html'
/api/health → 200          # שורד כי לא קורא קבצים

# אחרי restart: crash-loop
pm2 describe paperclip → status: "waiting restart", restarts: 36, nothing on :3100
ERROR log → "Paperclip server failed to start.
  authenticated public deployments require DATABASE_URL ...;
  refusing embedded PostgreSQL fallback"

הורדת החבילה איטית (~30ש', native builds) — מה שמחמיר את ה-loop: min_uptime של PM2 קוטע את ה-npx באמצע ההורדה לפני שהוא מסיים לחלץ, כך שה-cache לעולם לא מתמלא.

ההשפעה על הצינור שלנו

Paperclip מושבת לגמרי — ה-UI לא עולה לאף משתמש, וכל סוכני Paperclip (14 הסוכנים) לא יכולים לרוץ כי הם חולקים את התהליך הזה.

תיקון — שער סינכרוני לפני הפעלת השרת

שורש הבעיה: פאטץ' ה-cloud-db-bypass חייב להיות על הדיסק לפני שהשרת רץ; לולאת-הרקע מאוחרת מדי. ב-start-paperclip.sh נוספה ensure_patched_before_run() (06/06/26) שרצה סינכרונית לפני exec:

1. בודקת אם @paperclipai/server/ui-dist/index.html קיים ב-cache (ראה "מלכודות בדרך" — זה הסמן הנכון, לא dist/index.js).
2. אם לא — מריצה npx -y paperclipai@<version> --help. זה מאלץ את npx לחלץ את כל החבילה (כולל ui-dist/) כדי להריץ את ה-CLI, שמדפיס help ויוצא לבד ב-exit 0 — לא מפעיל שרת ולא תופס את 3100 (אומת). אין תהליך-רקע, אין שרת לא-מתוקן מוקדם, ואין מה להרוג.
3. מחילה את כל הפאטצ'ים (כולל bypass) על ה-cache המחולץ — עם guard שלא מפיל את ה-wrapper אם patch נכשל.
4. רק אז exec npx ... run — npx עושה reuse ל-cache המתוקן והשרת עולה נקי.

לולאת-הרקע (post-exec) נשמרה כרשת-ביטחון idempotent.

אומת מקצה-לקצה (06/06/26): מחיקת ה-cache בכוונה + pm2 restart → השער חילץ אוטומטית דרך --help (~64ש'), תיקן, והשרת עלה ל-200 ב-~72ש'. מונה הריסטארטים של PM2 לא זז (אפס crash-loop).

מלכודות שהתגלו בדרך (גרסה ראשונה של הפיקס נכשלה):

1. סמן חילוץ שגוי — dist/index.js נכתב ~שניות לפני ui-dist/. שער שממתין ל-dist ומריץ מיד → ui-dist עדיין חסר → 500. הסמן הנכון הוא ui-dist/index.html (הקובץ האחרון, וגם זה שגרם ל-500 המקורי).
2. set -e + patch כושל — אם apply-hebrew.sh רץ בלי ui-dist הוא מחזיר שגיאה, ותחת set -e ה-wrapper מת → crash-loop חדש. הפתרון: apply_all_patches || echo WARNING.
3. pkill -f "paperclipai@..." תופס את עצמו — מחרוזת הדפוס מופיעה ב-command line של ה-shell שמריץ את ה-pkill, אז הוא הורג את עצמו (exit 144). זו הסיבה שגישת spawn-run-then-pkill ננטשה לטובת --help שיוצא לבד. אם בכל זאת צריך להרוג — לפי PID (kill $PID; pkill -P $PID), לא לפי -f.

שחזור — עם הפיקס פרוס, מספיק pm2 restart paperclip וה-ensure_patched_before_run() מתאושש לבד. אם צריך לעשות זאת ידנית (fix אחר, דיבוג):

pm2 stop paperclip                                     # לעצור loop אם קיים
export PATH=/home/chaim/.nvm/versions/node/v24.14.0/bin:$PATH
npx -y paperclipai@2026.529.0 --help >/dev/null 2>&1   # חילוץ נקי שיוצא לבד (לא מפעיל שרת)
find ~/.npm/_npx -path "*@paperclipai/server/ui-dist/index.html" -type f   # לאמת חילוץ מלא
# להחיל פאטצ'ים על ה-cache, ובמיוחד ה-bypass:
bash ~/.paperclip/hermes-patches/apply-cloud-db-bypass.sh
bash ~/.paperclip/hebrew/apply-hebrew.sh
bash ~/.paperclip/hermes-patches/apply-hermes-fixes.sh
bash ~/.paperclip/hermes-patches/apply-deepseek-reaper-fix.sh
grep -q HEBREW_PATCH_BYPASS_CLOUD_DB \
  ~/.npm/_npx/*/node_modules/@paperclipai/server/dist/index.js && echo "BYPASS OK"
pm2 start paperclip && pm2 save                         # reuse ל-cache המתוקן

אל תשתמש ב-pkill -f "paperclipai@..." / -f "@paperclipai/server" — הדפוס תופס את ה-shell של עצמך (exit 144). אם חייבים להרוג תהליך — לפי PID.

סטטוס

• תוקן ב-start script ע"י ensure_patched_before_run() (06/06/26) — שער סינכרוני שמחלץ+מתקן לפני exec.
• הערה מטעה תוקנה: ההערה הישנה בראש ה-script טענה ש-npx run מחלץ-מחדש בכל הפעלה (לכן הסתמכו על לולאת-הרקע בלבד) — זה לא נכון, npx עושה reuse ל-cache תקין; הסכנה היא cache מחוק.
• לקח כללי: כל patch שה-target שלו הוא assert בזמן-startup חייב להיות מוחל לפני exec, לא בלולאת-רקע.

---

6. issue.comment.created — מזהה-ה-issue ב-entityId, לא ב-payload.issueId

מה קורה

ל-event issue.comment.created שה-host שולח לפלאגין, מזהה-ה-issue נמצא ב-event.entityId (ה"ישות הראשית" של ה-event), ולא ב-payload. ה-payload נושא דווקא:

• commentId — מזהה התגובה
• bodySnippet — גוף קצוץ (לא הטקסט המלא)
• reopened / reopenedFrom — נדלקים כשהתגובה פתחה-מחדש issue ב-done

אין payload.issueId ואין payload.body מלא. מקור-אמת: @paperclipai/plugin-sdk index.d.ts — issueId: event.entityId.

ראיה אמפירית — תיק 8124-09-24, CMPA (17/06/26)

תגובת-משתמש על sub-issue של המנתח המשפטי (במצב done) לא הגיעה ל-CEO. הניתוב ב-plugin-legal-ai/src/worker.ts קרא payload.issueId (תמיד undefined) ולכן דילג בשקט:

WARN [plugin] issue.comment.created event missing issueId in payload, skipping
  { entityId: "6eb905ea-…",           ← זה ה-issue id האמיתי
    payload: { commentId: "31e35676-…", bodySnippet: "…", reopened: true,
               reopenedFrom: "done", identifier: "CMPA-94", … } }   ← אין issueId

ההשפעה על הצינור שלנו

הניתוב "תגובת-משתמש → CEO" (CLAUDE.md §"ניתוב comments דרך CEO") היה מת בשקט — כל תגובה דולגה. במקרה של תגובה על issue בבעלות ה-CEO זה "עבד" רק במקרה דרך מנגנון reopen-on-comment הנייטיב של Paperclip (פותח-מחדש done ומעיר את הסוכן-המשויך). על sub-issue של סוכן אחר, ה-wake הנייטיב כיוון לסוכן הלא-נכון וריצת-ה-CEO בתור בוטלה עם errorCode: issue_assignee_changed ("the new owner will be woken instead" — וה"בעלים" ב-done ⇒ כלום).

תיקון — בצד שלנו (PR ezer-mishpati/plugin-legal-ai#2)

ב-handler של issue.comment.created:

1. issueId = event.entityId (fallback ל-payload.issueId לעמידות מול גרסאות-host).
2. גוף-תגובה מלא: התאמת payload.commentId מתוך listComments (ה-payload נושא רק snippet); fallback ל-latest/snippet.
3. guard לדה-דופ: אם התגובה פתחה-מחדש issue שכבר משויך ל-CEO (issue.assigneeAgentId === ceoAgentId && payload.reopened), ה-wake הנייטיב כבר מטפל — מדלגים כדי לא להריץ את ה-CEO פעמיים. לכל issue אחר עדיין מנתבים ל-CEO.

אימות (17/06/26)

תגובת-בדיקה על אותו sub-issue של המנתח (543f997b, done) לאחר deploy → לוג Routed user comment to CEO agent עם runId, וריצת-CEO succeeded (לא cancelled).

סטטוס

• תוקן בצד שלנו (PR #2, נפרס דרך npm run build + pm2 restart paperclip — הפלאגין נטען מ-/home/chaim/plugin-legal-ai לפי package_path).
• לקח כללי: ל-events של הפלאגין — מזהה-הישות-הראשית הוא תמיד event.entityId; אל תניח ששדות נמצאים ב-payload בלי לאמת מול ה-.d.ts של ה-SDK או מול לוג חי.
• TaskMaster: legal-ai #149.