@misterhuydo/sentinel 1.6.10 → 1.6.11

package/.cairn/.hint-lock

@@ -1 +1 @@
-2026-04-25T09:41:31.525Z
+2026-04-27T13:09:20.340Z

package/.cairn/memory/auto-memory/MEMORY.md

@@ -0,0 +1,21 @@
+# Memory Index
+
+- [sentinel_deployment_server](experience_sentinel_deployment_server.md) — Sentinel deploys on Oracle Ampere ARM server, SSH via ageri user `[experience]`
+- [publish_safety_check](experience_publish_safety_check.md) — Always syntax-check Python and JS files before npm publish `[experience]`
+- [cairn_session_discipline](experience_cairn_session_discipline.md) — Use cairn_resume at session start, cairn_checkpoint at end — not cairn_maintain `[experience]`
+- [secrets_in_gitignored_files](experience_secrets_in_gitignored_files.md) — All secrets go in gitignored files only — never in committed config `[experience]`
+- [auto_commit_auto_release_split](decision_auto_commit_auto_release_split.md) — AUTO_PUBLISH split into AUTO_COMMIT + AUTO_RELEASE with 3-level hierarchy `[decision]`
+- [bash_local_shadows_env_var](experience_bash_local_shadows_env_var.md) — bash `local var=""` shadows same-named env vars — use a distinct SENTINEL_*_OVERRIDE pattern `[experience]`
+- [sentinel_upgrade_requires_file_copy](knowledge_sentinel_upgrade_requires_file_copy.md) — npm install -g does NOT update the running instance — must copy files from npm package to /home/sentinel/sentinel/code/ and restart `[knowledge]`
+- [multi_repo_fix_architecture](decision_multi_repo_fix_architecture.md) — Multi-repo fix flow: parse_multi_repo_patch → atomic dry-run → per-repo apply/PR with sibling list `[decision]`
+- [per_project_claude_session](decision_per_project_claude_session.md) — Long-lived `claude --resume` session per project, persisted in claude_sessions table; per-project asyncio.Lock `[decision]`
+- [cairn_federation_for_sentinel_projects](knowledge_cairn_federation_for_sentinel_projects.md) — Sentinel project root + each sub-repo both run `cairn install`; federation auto-mounts via parent walk-up `[knowledge]`
+- [claude_resume_stale_context_risk](experience_claude_resume_stale_context_risk.md) — claude --resume carries file-content memory across turns — must use per-route session keys + force fresh Read `[experience]`
+- [no_api_key_for_heavy_coding](preference_no_api_key_for_heavy_coding.md) — Never bill heavy coding tasks against ANTHROPIC_API_KEY — must use Claude Pro OAuth `[preference]`
+- [cairn_hooks_block_oauth_read_edit](knowledge_cairn_hooks_block_oauth_read_edit.md) — Cairn PreToolUse hooks (minify, edit-guard) exit 2 to block Read/Edit; bypass via --setting-sources project,local + re-add MCP via --mcp-config `[knowledge]`
+- [git_apply_recount_for_llm_diffs](decision_git_apply_recount_for_llm_diffs.md) — Always pass `git apply --recount` for LLM-generated patches — fixes off-by-one hunk header counts `[decision]`
+- [mvn_negative_cache_blocks_cascade_retries](experience_mvn_negative_cache_blocks_cascade_retries.md) — mvn caches "artifact not found" responses for ~24h — pass `-U` to bypass when polling for a freshly-published artifact `[experience]`
+- [jenkins_wait_before_cascade](decision_jenkins_wait_before_cascade.md) — manage_release blocks on Jenkins build (wait=True) before firing cascade — eliminates Nexus race `[decision]`
+- [cicd_user_must_not_be_hardcoded](experience_cicd_user_must_not_be_hardcoded.md) — Jenkins triggers must use repo.cicd_user — hardcoded "sentinel" caused silent 401s for all elprint builds `[experience]`
+- [sentinel_repo_remotes](knowledge_sentinel_repo_remotes.md) — J:\Projects\Sentinel = source of truth; misterhuydo/Sentinel primary; exoreaction/Sentinel = downstream mirror `[knowledge]`
+- [sentinel_systemd_inactive_is_misleading](knowledge_sentinel_systemd_inactive_is_misleading.md) — systemctl status sentinel reports inactive even when workers run; check ps + per-project PID files instead `[knowledge]`

package/.cairn/memory/auto-memory/decision_auto_commit_auto_release_split.md

@@ -0,0 +1,22 @@
+---
+name: auto_commit_auto_release_split
+description: AUTO_PUBLISH split into AUTO_COMMIT + AUTO_RELEASE with 3-level hierarchy
+type: decision
+created_at: 2026-04-08T16:00:35.305Z
+updated_at: 2026-04-08T16:00:35.305Z
+---
+
+AUTO_PUBLISH was split into two independent flags (v1.5.17):
+
+- AUTO_COMMIT: push directly to main (no PR). Default: false.
+- AUTO_RELEASE: trigger Jenkins/GHA pipeline after push. Default: false.
+
+Both follow 3-level hierarchy: repo override → project default (sentinel.properties) → false.
+
+Current config:
+- sentinel-1881: AUTO_COMMIT=true, AUTO_RELEASE=false (project level)
+- sentinel-elprint: AUTO_COMMIT=true, AUTO_RELEASE=false (project level)
+- All individual repo configs: no AUTO_COMMIT/AUTO_RELEASE (inherit from project)
+
+Pending releases: when AUTO_COMMIT=true and AUTO_RELEASE=false, committed pushes are
+recorded in pending_releases table. get_status exposes them. manage_release clears them.

package/.cairn/memory/auto-memory/decision_git_apply_recount_for_llm_diffs.md

@@ -0,0 +1,17 @@
+---
+name: git_apply_recount_for_llm_diffs
+description: Always pass `git apply --recount` for LLM-generated patches — fixes off-by-one hunk header counts
+type: decision
+created_at: 2026-04-24T12:34:44.489Z
+updated_at: 2026-04-24T12:34:44.489Z
+---
+
+All `git apply` invocations in `sentinel/git_manager.py` (both `--check` dry-runs and actual applies, single-repo and multi-repo) MUST include `--recount`.
+
+**Why:** LLM-generated unified diffs frequently miscount hunk header line counts (`@@ -X,N +Y,M @@`) by ±1 — Claude can write a hunk body with 9 old / 19 new lines but emit a header `@@ -4,9 +4,18 @@`. Without `--recount`, this fails dry-run with "corrupt patch at line N". With `--recount`, git infers counts from the actual `+/-/ ` lines and the patch applies cleanly.
+
+**Origin:** v1.6.5 ended a long debugging arc where Claude in `--print` mode kept producing patches with miscounted hunks even after fixing cairn-hook permission denials and per-route session contamination. The actual content was always correct — only headers were off. `--recount` made every prior failure into a clean apply.
+
+**Where applied:** `git_manager.py:266` (apply_and_commit dry-run), `:271` (apply), `:380` (apply_and_commit_multi dry-run), `:412` (apply_and_commit_multi apply). All four sites now use `["apply", "--check", "--recount", "--ignore-whitespace", ...]` or `["apply", "--recount", "--ignore-whitespace", ...]`.
+
+**Caveat:** `--recount` only fixes header miscounts. If the actual `+/-/ ` lines are wrong (missing context, wrong content), the patch still fails — which is correct safety behavior.

package/.cairn/memory/auto-memory/decision_jenkins_wait_before_cascade.md

@@ -0,0 +1,23 @@
+---
+name: jenkins_wait_before_cascade
+description: manage_release blocks on Jenkins build (wait=True) before firing cascade — eliminates Nexus race
+type: decision
+created_at: 2026-04-24T13:57:52.942Z
+updated_at: 2026-04-24T13:57:52.942Z
+---
+
+When `Boss.manage_release(operation='release' or 'release_and_cascade', confirmed=True)` is called, sentinel_boss.py now invokes `_trigger_jenkins_release(repo, wait=True)` whenever a cascade will follow.
+
+**Why:** the cascade calls `mvn compile -DskipTests -U` per dependent repo, which queries Nexus for the new artifact. If Jenkins is still building, Nexus returns 404 and (without `-U` — fixed in v1.6.6) mvn caches that for ~24h. Even with `-U`, racing Jenkins is wasteful — better to know exactly when the build finished via Jenkins's own API.
+
+**How `_wait_for_jenkins_build` works** (`sentinel/cicd_trigger.py`):
+- Records `lastBuild` number BEFORE triggering
+- Polls `<job_url>/api/json` every 20s for up to 15 min (`JENKINS_RELEASE_TIMEOUT=900`)
+- Returns True only if a NEW build appears AND completes with `result=SUCCESS`
+- Returns False on FAILURE / ABORTED / TIMEOUT
+
+**Caveat:** Boss conversation BLOCKS for up to 15 min while waiting. Mitigation: a Slack `:hourglass_flowing_sand:` message is posted right before the wait so the user knows what's happening. Future improvement: run the wait async with periodic Slack updates.
+
+**Where applied:** `sentinel/sentinel_boss.py` `manage_release` handler, `operation in ("release", "release_and_cascade")` branch (around line 4912 in v1.6.7).
+
+Shipped in v1.6.7. Pairs with v1.6.6's `-U` fix to mvn — both are needed: -U for the case where someone runs the cascade independently, wait=True for the integrated trigger-then-cascade flow.

package/.cairn/memory/auto-memory/decision_multi_repo_fix_architecture.md

@@ -0,0 +1,25 @@
+---
+name: multi_repo_fix_architecture
+description: Multi-repo fix flow: parse_multi_repo_patch → atomic dry-run → per-repo apply/PR with sibling list
+type: decision
+created_at: 2026-04-24T10:45:04.157Z
+updated_at: 2026-04-24T10:45:04.157Z
+---
+
+Sentinel now supports cross-repo fixes (one task → multiple repos).
+
+**Patch format claude must produce:**
+- Paths prefixed `repos/<repo-name>/...` (relative to project root)
+- Optional `# Affected repos: a, b, c` header line — order = merge order (library first, consumer after)
+
+**Flow (in main._generate_apply_publish):**
+1. `generate_fix(..., all_repos=cfg_loader.repos.values())` — Claude runs from project root with cairn federation visibility, gets `--resume <session_id>` + `--output-format json`
+2. `apply_and_commit_multi(event, patch_path, all_repos, cfg)` — splits combined patch by `repos/<name>/` prefix, atomic dry-run all repos first; if ANY fails, ALL marked "aborted" with no commits. Then per-repo: apply + test + commit (per-repo failures don't block others)
+3. `publish_multi(event, results, cfg)` — pushes branches, opens PRs with `extra_body` listing sibling repo NAMES (URL cross-refs deferred to v2 — needs two-pass GitHub PATCH)
+4. Per-repo state goes to `fix_repos` table; primary repo also lands in legacy `fixes` for back-compat with reporter/Boss
+
+**Fallback:** If patch has no `repos/<name>/` prefix (legacy/manual), `apply_and_commit_multi` returns `[]` and main falls back to single-repo `apply_and_commit + publish`.
+
+**Files:** sentinel/git_manager.py (parse_multi_repo_patch + apply_and_commit_multi + publish_multi), sentinel/fix_engine.py (multi-repo prompt + JSON parser + session resume), sentinel/main.py (_generate_apply_publish + _apply_publish_single fallback).
+
+**Removed:** MAX_FILES_IN_PATCH=5 / MAX_LINES_IN_PATCH=200 limits. Claude is trusted to size patches appropriately.

package/.cairn/memory/auto-memory/decision_per_project_claude_session.md

@@ -0,0 +1,23 @@
+---
+name: per_project_claude_session
+description: Long-lived `claude --resume` session per project, persisted in claude_sessions table; per-project asyncio.Lock
+type: decision
+created_at: 2026-04-24T10:45:21.608Z
+updated_at: 2026-04-24T10:45:21.608Z
+---
+
+Each Sentinel project keeps ONE long-lived Claude conversation across fix tasks (NOT one subprocess — claude is still spawned per task, but with `--resume <session_id>` so it continues the previous conversation).
+
+**Why this design (not long-lived subprocess):**
+- `claude` CLI isn't built for stdin/stdout piping — no clean response framing, hangs on confirmations, ANSI escapes leak. Subprocess startup (~1s) is negligible vs the 30s-2min fix runtime.
+- `--resume` gives prompt-cache reuse + cross-task context without process-management complexity.
+
+**Mechanism:**
+- `state_store.claude_sessions(project_name PK, session_id, last_used, total_cost_usd, turn_count)` table
+- `fix_engine.generate_fix` reads `store.get_claude_session(cfg.project_name)` and passes the id via `--resume <id>`
+- After the call, parses `{"session_id": "...", "total_cost_usd": ...}` from the JSON output and `store.set_claude_session(project_name, id, cost_delta=cost)` — accumulates cost + turn count
+- `--output-format json` is required to extract session_id deterministically. Live tool-use progress streaming (`⏺ Bash(...)`, etc) is sacrificed — `_progress_from_line` is now dead code in the JSON path. stream-json migration deferred.
+
+**Concurrency safety:**
+- `main._project_locks: dict[str, asyncio.Lock]` keyed by `cfg.project_name` (or `"_default"` if empty)
+- `_handle_error` wraps `_generate_apply_publish` in `async with _project_lock(...)` — guarantees one Claude session active per project at a time. Different projects can run in parallel.

package/.cairn/memory/auto-memory/experience_bash_local_shadows_env_var.md

@@ -0,0 +1,11 @@
+---
+name: bash_local_shadows_env_var
+description: bash `local var=""` shadows same-named env vars — use a distinct SENTINEL_*_OVERRIDE pattern
+type: experience
+created_at: 2026-04-21T07:22:54.615Z
+updated_at: 2026-04-21T07:22:54.615Z
+---
+
+In fetch_log.sh, `local OUTPUT_DIR=""` inside fetch_from_properties() shadows any OUTPUT_DIR env var set by the Python caller. Python was setting env["OUTPUT_DIR"] = temp_path, but bash's local declaration wiped it, causing filtered logs to always write to $SCRIPT_DIR instead of the temp dir — so monitor results were always empty.
+
+Fix: use a dedicated env var (SENTINEL_OUTPUT_DIR_OVERRIDE) that doesn't conflict with a local variable name, and apply it after the local declarations. This is the same pattern already used for SENTINEL_GREP_FILTER_OVERRIDE.

package/.cairn/memory/auto-memory/experience_cairn_session_discipline.md

@@ -0,0 +1,9 @@
+---
+name: cairn_session_discipline
+description: Use cairn_resume at session start, cairn_checkpoint at end — not cairn_maintain
+type: experience
+created_at: 2026-03-31T03:26:44.345Z
+updated_at: 2026-03-31T03:26:44.345Z
+---
+
+At the start of a session, always call `cairn_resume` (not `cairn_maintain`) to get incremental re-index + memory surface from the last checkpoint. `cairn_maintain` does a full re-index and loses prior session context. At the end of every session, call `cairn_checkpoint` with a message, active_files, and any notes worth carrying forward. Skipping checkpoint means the next session starts cold.

package/.cairn/memory/auto-memory/experience_cicd_user_must_not_be_hardcoded.md

@@ -0,0 +1,17 @@
+---
+name: cicd_user_must_not_be_hardcoded
+description: Jenkins triggers must use repo.cicd_user — hardcoded "sentinel" caused silent 401s for all elprint builds
+type: experience
+created_at: 2026-04-24T14:06:02.248Z
+updated_at: 2026-04-24T14:06:02.248Z
+---
+
+In `sentinel/cicd_trigger.py`, `_trigger_jenkins(repo)` was passing `auth=("sentinel", repo.cicd_token)` — hardcoding "sentinel" as the username. This silently broke every Jenkins API call when the repo's API token was issued under a different user (e.g. CICD_USER=misterhuydo).
+
+**Detection** (2026-04-24): Boss tried to trigger 14 elprint builds; all returned HTTP 401. Direct curl from EC2 with `-u misterhuydo:<token>` returned HTTP 200, proving creds were valid. Bug was the hardcoded "sentinel" username.
+
+**Fix** (v1.6.8): use `auth=(repo.cicd_user or "sentinel", repo.cicd_token)` — same pattern already in use by `_trigger_jenkins_release` (which was unaffected). One-line fix.
+
+**Lesson:** when adding new auth code, always thread `repo.cicd_user` through. Never hardcode usernames. The fallback to "sentinel" is fine for backward compat, but the configured user must take priority.
+
+Affected functions: `_trigger_jenkins` (fixed in v1.6.8). Others (`_trigger_jenkins_release`, `_trigger_github_actions`) already correct.

package/.cairn/memory/auto-memory/experience_claude_resume_stale_context_risk.md

@@ -0,0 +1,23 @@
+---
+name: claude_resume_stale_context_risk
+description: claude --resume carries file-content memory across turns — must use per-route session keys + force fresh Read
+type: experience
+created_at: 2026-04-24T11:26:21.418Z
+updated_at: 2026-04-24T11:26:21.418Z
+---
+
+When using `claude --print --resume <session_id>` for sentinel fix engine, the resumed Claude carries memory of file contents from earlier turns. If the next task targets a DIFFERENT repo (or the same file has changed), Claude may patch from stale memory instead of re-reading the actual file → diff context mismatch → `git apply --check` fails.
+
+**Real incident (2026-04-24):**
+- Turn 1: fix attempt routed to `1881-SSOLoginWebApp` (local override of FirstName.java). Claude got session `d1c18a02`. Failed.
+- Turn 2: new fix routed to `Whydah-TypeLib` (the upstream FirstName.java which differs from the local override). With per-project resume, Claude resumed `d1c18a02` and patched TypeLib using the SSOLWA file's content from memory. Patch context didn't match TypeLib's actual file. Dry-run aborted.
+
+**Three layered defenses (all shipped in v1.6.2):**
+
+1. **Per-route session key**: in fix_engine.generate_fix, key claude_sessions by `f"{cfg.project_name}/{repo.repo_name}"` instead of just `cfg.project_name`. Different routes get fresh sessions.
+
+2. **Pre-fix `git pull` of every project repo** via `git_manager.pull_all_repos(all_repos)`. Closes the window where the on-disk file lags behind a recent sentinel commit or human commit.
+
+3. **Prompt instruction**: "CRITICAL — fresh reads only. Before you write ANY diff line, use the Read tool to view the CURRENT content of every file you intend to modify. Do NOT rely on prior memory ..."
+
+**General rule when using --resume:** if the task topic / file scope changes between turns, either start a fresh session OR explicitly tell Claude to re-read everything. Never trust memory across context boundaries.

package/.cairn/memory/auto-memory/experience_envelope_first_auth_detection.md

@@ -0,0 +1,11 @@
+---
+name: envelope_first_auth_detection
+description: Substring-based auth-error detection on LLM output triggers false positives when patches contain words like "UNAUTHORIZED" — check the JSON envelope first
+type: experience
+originSessionId: d78671ef-fb75-4934-949b-11dda1645051
+---
+When a Claude `--print --output-format json` invocation succeeds, its `result` field can contain arbitrary text from the codebase being patched — including unchanged-context diff lines like `return new ResponseEntity<>(err, HttpStatus.UNAUTHORIZED)`. Substring matching on the raw output (e.g. checking for `"unauthorized"`, `"unauthenticated"`, `"login required"`) will fire even when the request authenticated cleanly, producing false "auth failure" Slack alerts and wasting both attempts in a fallback loop.
+
+**Why:** On 2026-04-27 fp `6cb7a875` produced a valid HttpRequestMethodNotSupportedException handler patch, but the diff included an unchanged `HttpStatus.UNAUTHORIZED` context line for a sibling exception handler. Both OAuth and API-key attempts were marked auth-failed, the patch was discarded, and the user got a misleading "out of session?" alert. Cost ~$0.62 for the wasted retries; fix would have shipped to prod 3 hours earlier without the false positive.
+
+**How to apply:** Whenever you have both a structured envelope (`is_error` flag, JSON status) and a free-text scan, *consult the envelope first*. The substring scan is only valid as a fallback for early-exit failures that never produced a parseable envelope (binary missing, immediate stderr crash). Fix in `sentinel/fix_engine.py` shipped in v1.6.10: parse JSON before running `_is_auth_error()`; if `is_error:false` and `result` is non-empty, treat it as success regardless of body content.

package/.cairn/memory/auto-memory/experience_mvn_negative_cache_blocks_cascade_retries.md

@@ -0,0 +1,17 @@
+---
+name: mvn_negative_cache_blocks_cascade_retries
+description: mvn caches "artifact not found" responses for ~24h — pass `-U` to bypass when polling for a freshly-published artifact
+type: experience
+created_at: 2026-04-24T13:27:45.148Z
+updated_at: 2026-04-24T13:27:45.148Z
+---
+
+When a sentinel cascade fires immediately after triggering a Jenkins release, mvn often hits Nexus before Jenkins finishes publishing the new artifact. The `404 not found` response is **cached locally** in `~/.m2/repository/<group>/<artifact>/<version>/_remote.repositories` (or via the `--no-transfer-progress` machinery), and mvn refuses to re-check that artifact for ~24h (the default `updatePolicy` interval).
+
+Symptom: cascade reports "Artifact X:Y not yet in Nexus", user retries 5 minutes later, same failure even though Nexus actually has the artifact. The user can manually confirm via their local IDE (which has its OWN m2 cache and saw the artifact at a different time).
+
+**Fix:** add `-U` (`--update-snapshots`) to every `mvn` invocation in the cascade path. `-U` forces mvn to re-check remote repos on every call, bypassing the negative cache. Cost: slightly more network traffic. Benefit: cascade retries actually work.
+
+Shipped in v1.6.6 in `sentinel/git_manager.py:maven_compile_check` — added `-U` to the `mvn compile -DskipTests -q --batch-mode` command.
+
+**Also worth knowing:** Sentinel detects the Nexus URL from the project's `pom.xml` (`<repositories>` block), NOT from `~/.m2/settings.xml`. settings.xml only carries credentials, not URLs.

package/.cairn/memory/auto-memory/experience_publish_safety_check.md

@@ -0,0 +1,13 @@
+---
+name: publish_safety_check
+description: Always syntax-check Python and JS files before npm publish
+type: experience
+created_at: 2026-03-31T03:26:41.450Z
+updated_at: 2026-03-31T03:26:41.450Z
+---
+
+Before running `npm publish`, always validate modified files:
+- Python: `python -c "import ast; ast.parse(open('file.py').read())"`
+- JS/Node: `node --check file.js`
+
+The bundle step does NOT catch Python syntax errors. Backtick characters inside JS template literals will also break when embedding Python code blocks — avoid them or escape carefully.

package/.cairn/memory/auto-memory/experience_secrets_in_gitignored_files.md

@@ -0,0 +1,9 @@
+---
+name: secrets_in_gitignored_files
+description: All secrets go in gitignored files only — never in committed config
+type: experience
+created_at: 2026-03-31T03:26:47.431Z
+updated_at: 2026-03-31T03:26:47.431Z
+---
+
+Never put tokens, API keys, passwords, or any secrets in committed config files. Keep them in a gitignored file such as `private_*.properties`, `.env`, or equivalent that lives only on the server. If a project has a committed config template (e.g. `sentinel.properties`), use placeholder values like `<token>` and document that the real values go in the private file.

package/.cairn/memory/auto-memory/experience_sentinel_deployment_server.md

@@ -0,0 +1,13 @@
+---
+name: sentinel_deployment_server
+description: Sentinel deploys on EC2 server, SSH via ec2-user with sentinel.pem key
+type: experience
+created_at: 2026-03-31T03:23:46.605Z
+updated_at: 2026-04-21T00:00:00.000Z
+originSessionId: bbd5aef7-18ed-4068-be3f-60d68de4936f
+---
+Sentinel is deployed on EC2 at `13.50.101.130`. SSH: `ssh -i ~/.ssh/sentinel.pem ec2-user@13.50.101.130` (key at `C:\Users\huy\.ssh\sentinel.pem`).
+
+Single service: `sentinel.service` (not sentinel-1881 or sentinel-elprint — just `sentinel`).
+
+Deploy: `sudo npm install -g @misterhuydo/sentinel@<version> && sudo systemctl restart sentinel`

package/.cairn/memory/auto-memory/feedback_ageri_rag_architecture.md

@@ -0,0 +1,19 @@
+---
+name: Ageri RAG and CoreSkill architecture decisions
+description: CoreSkill is passive observer only; personal skill uses layered context pipeline for RAG
+type: feedback
+---
+
+CoreSkill must remain a passive observer — no URL fetching, no active retrieval. It only listens, extracts explicit facts, and writes to memory silently. The moment it fetches URLs it changes nature.
+
+Personal skill RAG uses a layered context pipeline (pre-LLM step):
+1. Memory search — what we know about this user/topic
+2. URL fetch — if message contains a URL, fetch it
+3. prior_results — what other skills returned this turn
+4. User-uploaded docs — files stored from previous uploads
+
+One context build → one LLM call. Not scattered retrieval inside each skill.
+
+**Why:** User confirmed this pushback explicitly. Separation of concerns — CoreSkill listens, research skill searches broadly, personal skill retrieves personal context.
+
+**How to apply:** Never add active retrieval to CoreSkill. When building personal skill RAG, use the pipeline approach above, not ad-hoc fetching in individual handlers.

package/.cairn/memory/auto-memory/feedback_design_principle.md

@@ -0,0 +1,16 @@
+---
+name: Design principle — simple but sophisticated
+description: User's core design philosophy for Sentinel and all work in this project
+type: feedback
+---
+
+"Simple but sophisticated" — the guiding principle for all design decisions.
+
+**Why:** User explicitly stated this after I added a redundant SLACK_WORKSPACE_ID workspace verification check that duplicated isolation Slack's own token architecture already provides.
+
+**How to apply:**
+- Solve the real problem, not hypothetical edge cases the platform already handles
+- Don't add config options, fields, or checks that guard against things that can't happen
+- When the underlying system (Slack, GitHub, SQLite, etc.) already enforces a constraint, trust it — don't re-enforce it in code
+- Prefer fewer moving parts. A sophisticated outcome should feel simple to operate.
+- Before adding any new mechanism, ask: "does something already handle this?"

package/.cairn/memory/auto-memory/feedback_publish_workflow.md

@@ -0,0 +1,14 @@
+---
+name: Sentinel publish workflow
+description: How to correctly publish Sentinel npm package
+type: feedback
+
+---
+
+Always run syntax checks before publishing: `python -c "import ast; ast.parse(open(f, encoding='utf-8').read())"` on modified Python files, and `node --check` on modified JS files.
+
+**Why:** Multiple bugs shipped due to literal newlines in JS strings and Python indentation errors. These are caught instantly by syntax checks.
+
+**How to apply:** Before every `npm publish`, check all modified files. The bundle step will succeed even with broken Python (it just copies files), so Python errors only surface at runtime on the server.
+
+Also: JS template literals containing backtick characters (Python f-strings with backtick code formatting) will cause syntax errors. Use string concatenation instead of template literals for multi-line Python code blocks in patch scripts.

package/.cairn/memory/auto-memory/feedback_secrets_handling.md

@@ -0,0 +1,15 @@
+---
+name: Secrets handling — never commit tokens
+description: All secrets (GITHUB_TOKEN, SLACK tokens, API keys) go in private_sentinel.properties only, never in committed config files
+type: feedback
+---
+
+Never put secrets in config repo files (sentinel.properties, repo-configs/*.properties). They get committed to GitHub.
+
+**Why:** GITHUB_TOKEN, SLACK_BOT_TOKEN, ANTHROPIC_API_KEY etc. were accidentally added to committed sentinel.properties files. These end up in GitHub history even if later removed.
+
+**How to apply:**
+- All secrets go in `private_sentinel.properties` (gitignored, lives next to the project dir on the server)
+- Committed `sentinel.properties` files contain only non-sensitive config (PROJECT_NAME, MAILS, POLL_INTERVAL, etc.)
+- The `.gitignore` in every sentinel config repo must include `private_sentinel.properties`
+- On the server: `~/sentinel/private_sentinel.properties` for workspace-level secrets

package/.cairn/memory/auto-memory/feedback_slack_admin_allowlist.md

@@ -0,0 +1,11 @@
+---
+name: SLACK_ADMIN_USERS implicitly allowed
+description: Admins are always allowed to talk to Boss — no need to also add them to SLACK_ALLOWED_USERS
+type: feedback
+---
+
+`SLACK_ADMIN_USERS` implies access. Do not require admins to also appear in `SLACK_ALLOWED_USERS`.
+
+**Why:** User pointed out the redundancy — if you're an admin you should obviously be able to talk to the bot. Fixed in slack_bot.py: allowlist check now skips users who are in `slack_admin_users`.
+
+**How to apply:** When configuring a new Sentinel instance, only set `SLACK_ADMIN_USERS` in `sentinel.properties`. `SLACK_ALLOWED_USERS` is only needed to grant access to non-admin users.

package/.cairn/memory/auto-memory/feedback_slack_thinking_status.md

@@ -0,0 +1,14 @@
+---
+name: Slack thinking status messages
+description: User confirmed they like the random thinking status messages in Slack Boss
+type: feedback
+---
+
+User explicitly approved the random thinking status approach (`_THINKING_STATUS` list with `random.choice()`).
+
+Messages like "poking around...", "on it...", "cooking..." are preferred over the static "thinking...".
+
+The "(still on it...)" suffix appended on long responses was also well received — it reassures the user the bot hasn't stalled.
+
+**Why:** More personality, less robotic. Matches the casual tone the user wants from Boss.
+**How to apply:** Keep the `_THINKING_STATUS` list and the "(still on it...)" update pattern. Do not revert to static "thinking...".

package/.cairn/memory/auto-memory/feedback_start_sh_patching.md

@@ -0,0 +1,16 @@
+---
+name: start.sh patching approach
+description: How to safely patch start.sh on the server — SSH double-quote expansion pitfall, $HOME vs hardcoded paths
+type: feedback
+---
+
+Always use `$HOME` (not hardcoded user paths like `/home/sentinel/`) in start.sh templates and patches. The script may run as any Linux user, not just `sentinel`.
+
+**Why:** The server user might not be `sentinel` — admin may choose any username. Using `$HOME` makes the script portable.
+
+**How to apply:** The generate.js template already uses `$HOME`. When patching start.sh on the server via SSH, never write Python patch scripts that include `$HOME` inside an SSH double-quoted string — bash will expand `$HOME` to the *local* machine's home before sending. Instead:
+- Use `sed -i` with single-quoted replacement strings (prevents local expansion)
+- Or write the Python patch to `/tmp/fix.py` via heredoc `<< 'PYEOF'` (single-quoted prevents expansion), then run separately
+- Or use SCP to upload the script file
+
+Also: `sentinel upgrade` regenerates start.sh from generate.js template. The template (line ~65 in generate.js) now includes auto-detection of JAVA_HOME via a for-loop over `$HOME/jdk-*` patterns, using `$HOME` throughout. This is permanent fix — no need to re-patch after upgrades.

package/.cairn/memory/auto-memory/knowledge_cairn_federation_for_sentinel_projects.md

@@ -0,0 +1,20 @@
+---
+name: cairn_federation_for_sentinel_projects
+description: Sentinel project root + each sub-repo both run `cairn install`; federation auto-mounts via parent walk-up
+type: knowledge
+created_at: 2026-04-24T10:45:36.058Z
+updated_at: 2026-04-24T10:45:36.058Z
+---
+
+Cairn supports nested federation natively. For Sentinel:
+- Project root (e.g. `/home/sentinel/sentinel/sentinel-1881/`) gets `.cairn/` (its own `.cairn-project` marker + `index.db`)
+- Each sub-repo under `repos/<name>/` ALSO gets its own `.cairn/`
+- When Claude runs from the project root, cairn's `mountParentSubIndexes` (Cairn `db.js:97`) auto-discovers sibling sub-indexes — no explicit registration needed (works "even if the parent project has never run cairn_maintain")
+
+**Sentinel wiring:**
+- `sentinel/cairn_client.py:_install_cairn_at(path)` — idempotent (skip if `.cairn/.cairn-project` marker exists), takes any path
+- `init_project_root(project_dir)` — wrapper invoked at sentinel startup
+- `index_repo(repo)` — same wrapper, called for each sub-repo (existing behaviour)
+- `main._startup_checks` calls `init_project_root(Path(cfg.workspace_dir).parent)` BEFORE iterating sub-repos with `index_repo`
+
+**Cairn CLI surface is limited** (`install`, `install-hooks`, `minify`, `edit-guard`, `validate-map`, `checkpoint --auto`, `resume-hint`). All federation/index queries are MCP-only — Claude calls them via MCP at runtime, Sentinel doesn't shell out for them.

package/.cairn/memory/auto-memory/knowledge_cairn_hooks_block_oauth_read_edit.md

@@ -0,0 +1,24 @@
+---
+name: cairn_hooks_block_oauth_read_edit
+description: Cairn PreToolUse hooks (minify, edit-guard) exit 2 to block Read/Edit; bypass via --setting-sources project,local + re-add MCP via --mcp-config
+type: knowledge
+created_at: 2026-04-24T12:00:46.946Z
+updated_at: 2026-04-24T12:00:46.946Z
+---
+
+Cairn ships two `PreToolUse` hooks installed in `~/.claude/settings.json`:
+- `cairn minify` on `Read` — exits with code 2 (blocking) and writes minified content to stderr; advances per-file state machine to `compressed`
+- `cairn edit-guard` on `Edit`/`Write` — exits 2 if file is in `compressed` state, shows full content, advances to `edit-ready`. Next Edit attempt then succeeds.
+
+This works fine for INTERACTIVE Claude Code (model retries naturally). In headless `claude --print` sessions doing complex multi-step work (26 turns of fix engine), the model often does NOT retry the blocked Edit — it falls back to hand-crafting a unified diff in markdown. That hand-crafted diff has off-by-one hunk-line counting bugs (`@@ -X,10 +X,11 @@` with a body of 9/10 lines) → `git apply --check` fails with "corrupt patch at line N".
+
+`--bare` would skip ALL hooks (per `claude --help`: "skip hooks, LSP, plugin sync...") but ALSO forces ANTHROPIC_API_KEY auth — incompatible with OAuth.
+
+**Surgical fix** for headless OAuth sessions:
+- `--setting-sources project,local` — skip user-scope settings.json (where cairn hooks live), keep project/local settings working
+- `--mcp-config '{"mcpServers":{"cairn":{"command":"cairn-mcp"}}}'` — re-add cairn MCP (which was also in user settings) standalone, so cairn_search/outline/checkpoint stay available
+- `--dangerously-skip-permissions` — keep, redundant given Read(**) allow but harmless
+
+This combo is in `sentinel/fix_engine.py:_claude_cmd` since v1.6.3.
+
+NOTE: When invoking `claude --mcp-config <json>` from a shell, the JSON string can be misparsed if a positional prompt follows. Use `--mcp-config=<json>` (= form) OR pass via Python subprocess as a list element (no shell). MCP config flag accepts space-separated values — that's why a positional prompt gets pulled in as a "second config".

package/.cairn/memory/auto-memory/knowledge_sentinel_repo_remotes.md

@@ -0,0 +1,28 @@
+---
+name: sentinel_repo_remotes
+description: J:\Projects\Sentinel = source of truth; misterhuydo/Sentinel primary; exoreaction/Sentinel = downstream mirror
+type: knowledge
+created_at: 2026-04-24T15:03:35.440Z
+updated_at: 2026-04-24T15:03:35.440Z
+---
+
+**Sentinel repo topology (set 2026-04-24):**
+
+- **J:\Projects\Sentinel** — single source of truth, primary working directory. ALL development happens here.
+- **misterhuydo/Sentinel** on GitHub — the personal/canonical remote, pushed to from J:\
+- **exoreaction/Sentinel** on GitHub — company-visible MIRROR. Always kept in sync with main; NOT the place to develop in.
+- **H:\Projects\exoreaction\Sentinel** — local clone of exoreaction/Sentinel; redundant when J:\ is the working dir, but harmless to keep around.
+
+**Workflow:**
+1. Edit, commit, and push from J:\Projects\Sentinel as usual.
+2. After pushing to misterhuydo, also push the same refs to exoreaction so the mirror stays current. Easiest: add exoreaction as a second remote in J:\ and push to both.
+
+```
+git -C /j/Projects/Sentinel remote add exoreaction git@github.com:exoreaction/Sentinel.git
+git -C /j/Projects/Sentinel push origin main
+git -C /j/Projects/Sentinel push exoreaction main
+```
+
+Or chain into one command via an alias / shell function.
+
+**Do NOT** do new work in H:\Projects\exoreaction\Sentinel — that workspace is just a local checkout of the mirror.

package/.cairn/memory/auto-memory/knowledge_sentinel_systemd_inactive_is_misleading.md

@@ -0,0 +1,18 @@
+---
+name: sentinel_systemd_inactive_is_misleading
+description: systemctl status sentinel shows inactive even when worker processes are healthy — check ps for python -m sentinel.main, not systemd
+type: knowledge
+originSessionId: 98f6382b-f7e7-45dd-8f41-8f5b249e0853
+---
+The `sentinel.service` systemd unit is `Type=forking` but its `ExecStart=/home/sentinel/sentinel/startAll.sh` backgrounds per-project children (`python -m sentinel.main`) without writing a `PIDFile=` that systemd can track. As a result `systemctl status sentinel` reports `inactive (dead)` immediately after start, even when all workers are running normally.
+
+**Why:** This is a unit-file design quirk, not an outage. The wrapper script + `Type=forking` mismatch means systemd loses track of the children. Restarting the unit will start a NEW set of workers without killing the existing ones — risk of duplicates.
+
+**How to apply:** When asked "is sentinel down?":
+1. Don't trust `systemctl is-active sentinel`.
+2. Check `ps -ef | grep "python3 -m sentinel.main"` and `ls /proc/<pid>/cwd` to map PIDs → projects.
+3. Cross-check against `sentinel.pid` in each `/home/sentinel/sentinel/<project>/`.
+4. Check `tail logs/sentinel.log` for recent activity.
+5. If duplicate processes for the same project exist (multiple PIDs with the same cwd), the older one is an orphan — `stop.sh` only kills the one in `sentinel.pid`. Kill orphans manually with `kill <pid>`.
+
+Never run `systemctl restart sentinel` to "fix" this without first stopping all running children, or you'll create duplicates.

package/.cairn/memory/auto-memory/knowledge_sentinel_upgrade_requires_file_copy.md

@@ -0,0 +1,20 @@
+---
+name: sentinel_upgrade_requires_file_copy
+description: npm install -g does NOT update the running instance — must copy files from npm package to /home/sentinel/sentinel/code/ and restart
+type: knowledge
+created_at: 2026-04-21T08:02:15.597Z
+updated_at: 2026-04-21T08:02:15.597Z
+---
+
+The running Sentinel instance uses PYTHONPATH=/home/sentinel/sentinel/code/ (not the npm package directory at /usr/lib/node_modules/@misterhuydo/sentinel/python/).
+
+`npm install -g @misterhuydo/sentinel@X.Y.Z` only updates the global npm package. To actually apply code changes to the running instance:
+
+1. Copy changed Python/shell files:
+   sudo cp /usr/lib/node_modules/@misterhuydo/sentinel/python/sentinel/<file>.py /home/sentinel/sentinel/code/sentinel/<file>.py
+   sudo cp /usr/lib/node_modules/@misterhuydo/sentinel/python/scripts/<file>.sh /home/sentinel/sentinel/code/scripts/<file>.sh
+
+2. Restart the instance:
+   sudo -u sentinel bash /home/sentinel/sentinel/sentinel-1881/stop.sh && sleep 2 && sudo -u sentinel bash /home/sentinel/sentinel/sentinel-1881/start.sh
+
+The `sentinel upgrade` CLI command (via Slack Boss) likely does this automatically, but manual deploys via SSH must do both steps.

package/.cairn/memory/auto-memory/preference_no_api_key_for_heavy_coding.md

@@ -0,0 +1,17 @@
+---
+name: no_api_key_for_heavy_coding
+description: Never bill heavy coding tasks against ANTHROPIC_API_KEY — must use Claude Pro OAuth
+type: preference
+created_at: 2026-04-24T11:39:14.740Z
+updated_at: 2026-04-24T11:39:14.740Z
+---
+
+User explicitly stated: "I never want to use API key for heavy coding tasks."
+
+**How to apply:**
+- For Sentinel fix_engine, ask_codebase, repo_task_engine: MUST use Claude Pro (OAuth) via the `claude` CLI's cached login, not `--bare`/API-key
+- API key remains acceptable for the lightweight Boss conversation loop (structured tool-use), but heavy code work is OAuth-only
+- If OAuth fails, do NOT silently fall back to API key — surface the failure and fix the OAuth issue instead
+- Configuration default: `CLAUDE_PRO_FOR_TASKS=true` is the only acceptable mode; do not propose API-key fallback as a "workaround"
+
+**Why:** Claude Pro covers heavy/agentic work via subscription. API credit is finite and gets exhausted (we hit the "Credit balance too low" wall earlier in 2026-04-24). Pro is the durable answer; falling back to API key is a regression in cost discipline.

package/.cairn/memory/auto-memory/project_ageri.md

@@ -0,0 +1,45 @@
+---
+name: Ageri project
+description: Personal AI platform — live on Oracle Ampere server, Slack connected, personal app responding
+type: project
+---
+
+Ageri is a personal AI platform, separate from Sentinel.
+
+**Domain:** ageri.ai (registered on Cloudflare)
+**GitHub:** git@github.com:misterhuydo/Ageri.git (private)
+**Local path:** J:\Projects\Ageri
+**Deploy key:** ~/.ssh/ageri_deploy on Oracle server
+
+**Server:** Oracle Ampere ARM 138.2.17.152, user: `ageri`
+**SSH from local:** `ssh -i /c/Users/huy/.ssh/oracle/devtest-arm-ampere.key ageri@138.2.17.152`
+**Code on server:** ~/ageri/code
+**Venv:** ~/ageri/venv
+**Config dir:** ~/ageri (ageri.properties + private_ageri.properties)
+**Log file:** ~/ageri/ageri.log
+**Start command:** `cd ~/ageri/code && AGERI_CONFIG=~/ageri ~/ageri/venv/bin/python -m ageri.main >> ~/ageri/ageri.log 2>&1 &`
+
+**Current status (2026-03-31):** LIVE — Ageri running on Oracle server, connected to Slack workspace via Socket Mode. Personal app active. DMs to @Ageri in Slack are working.
+
+**Architecture:**
+- Orchestrator → AppRegistry → Apps (personal, research, sentinel stubs)
+- Three-tier SQLite memory (session/working/long_term)
+- Slack Socket Mode interface
+- ageri-sdk: separate PyPI package at sdk/ — install with `pip install -e sdk/`
+- CLI at cli/ — `ageri init`, `ageri slack`, `ageri slack --update`
+
+**CLI (npm):** cli/ — not yet published. Run locally with `node bin/ageri.js`
+- `ageri init` — full setup (venv, pip, Slack prompts, config files)
+- `ageri slack` — prints one-click Slack manifest URL
+
+**Slack app:** messages_tab_enabled=true, interactivity=true, socket_mode=true
+**Scopes:** chat:write, im:*, channels:*, groups:*, reactions:write, users:read
+
+**Key fixes applied:**
+- Ubuntu 22.04 externally-managed Python → venv required
+- ageri-sdk not in requirements → `pip install -e sdk/` needed
+- setuptools.backends not available → changed to setuptools.build_meta
+- anthropic package missing from requirements.txt → added >=0.25
+- Slack messages tab disabled → added app_home.messages_tab_enabled=true to manifest
+
+**Why:** Platform play — Sentinel becomes an app module on top. BYOK + license business model.

package/.cairn/memory/auto-memory/project_ageri_architecture_v2.md

@@ -0,0 +1,89 @@
+---
+name: Ageri architecture v2 decisions
+description: Finalized architectural decisions — multi-profile, skill types, agent society, Orchestrator as God
+type: project
+---
+
+## Terminology: "App" → "Skill" ✓ DONE
+
+Renamed throughout codebase. SkillBase, SkillResult, SkillRegistry, ageri/skills/, SKILLS= config key. Backwards-compatible aliases kept until v1.0.
+
+## One Orchestrator, Multiple Agent Profiles ✓ FINALIZED
+
+- One Orchestrator process, one DB, one deployment
+- Multiple named Agent Profiles within it (e.g. Sammy, John, Peter, Selina)
+- Each profile has: name, channel bindings, memory scope (`profile:{id}:*`), personality, skill set
+- Reset = wipe `profile:{id}:*` memory only, config untouched
+- **Users can create as many profiles as they want** — profile count is a monetization lever (free tier limit, paid tier unlimited). Do not hardcode a profile cap in architecture.
+
+## Skill Assignment & Orchestrator Routing ✓ FINALIZED
+
+- A profile can hold multiple skills simultaneously (e.g. research + knowledge + zalo_adapter)
+- User intent determines required skills: "open Zalo, reply to customer questions" → needs research + knowledge + zalo_adapter on the same profile
+- If the active/addressed profile lacks a required skill, **Orchestrator suggests a profile that has the needed skill set** — does not silently fail or auto-delegate
+- Skill matching is capability-based, not name-based — Orchestrator inspects skill registry per profile
+
+## Memory Architecture ✓ FINALIZED
+
+Three scopes:
+1. **Global layer** (`global:*`) — shared across all profiles. User's name, location, timezone, language, who each profile is. Read by all profiles, written only by Orchestrator or explicit user action. "God's memory."
+2. **Profile scope** (`profile:{id}:*`) — private to each profile. What Sammy knows stays with Sammy.
+3. **Cross-profile transfer** — Orchestrator only, explicit user request. Logged and visible.
+
+## The Orchestrator as "God" ✓ FINALIZED
+
+- Omniscient: knows all profiles, all skills, all global facts
+- Omnipresent: receives every message from every channel
+- Controls: can read any profile's memory, broker conversations, delegate tasks
+- Transparent: logs every cross-profile interaction — user always has visibility
+- Suggests but doesn't act unilaterally on cross-profile decisions
+
+## Agent-to-Agent Communication ✓ FINALIZED
+
+- Agents cannot talk directly to each other
+- All communication routes through the Orchestrator
+- Orchestrator can facilitate: moves context between profiles, both agents contribute, user sees the thread
+- No private agent-to-agent conversations — Orchestrator is always present
+- Agents know each other exist IF the user has introduced them (stored in global layer)
+
+## Skills per Profile ✓ FINALIZED
+
+- Each profile has its own skill set (John the tutor has `english` skill, others don't)
+- Orchestrator knows who has what
+- Cross-profile skill borrowing with user approval: "Peter has that skill — want me to ask him?"
+
+## Skill Types ✓ FINALIZED
+
+Three categories:
+1. **Cognitive skills** — pure LLM reasoning (personal, research, memory). No external connections.
+2. **Adapter skills** — bridge to external systems. The skill owns the connection protocol.
+   - Examples: `openclaw`, `github`, `email`, `calendar`, `sentinel`
+   - User builds adapter skills to connect their own applications
+   - Platform doesn't need to know what the external system is — skill author does
+3. **Hybrid** — reasons + connects (e.g. research skill that searches the web)
+
+**Key insight:** A Skill is an adapter by nature. Ageri becomes an orchestration layer over ANY tool the user has — not by building every integration, but by letting community build adapter skills. Same model as VS Code extensions / browser extensions.
+
+## Language Handling ✓ FINALIZED
+
+- Mirror user's language dynamically by default
+- When user explicitly requests a language → save as `user:language` in profile memory → always use it
+- LLM can search internet for cultural context once location/culture known
+
+## Passive Learning ✓ FINALIZED
+
+- Learn silently but surface occasionally: "I noticed you prefer Vietnamese — I'll remember that"
+- Infer freely (location from "Tết", interests from topics, relationships from names)
+- All inferences written to DB. DB is source of truth — LLM enriches, doesn't replace.
+
+## Assistant Reset ✓ FINALIZED
+
+User can reset any profile — wipes its memory scope, preserves config and global layer.
+
+## Systemd ⚠ PENDING
+
+Ageri dies on server reboot. Need systemd unit for auto-restart. Not yet set up.
+
+## CLAUDE.md + docs updates ⚠ PENDING
+
+CLAUDE.md and ageri-engineering-brief.md need updates for Skill rename + all v2 architecture decisions. To be done in Ageri Claude session.

package/.cairn/memory/auto-memory/project_ageri_devtest.md

@@ -0,0 +1,15 @@
+---
+name: ageri_devtest_principle
+description: User wants solid devtest infrastructure built into Ageri from day one — lesson learned from Sentinel
+type: project
+---
+
+Ageri must have a devtest infrastructure built from the start, before the platform is complex.
+
+**Why:** Sentinel was painful to test — every change required npm publish → server upgrade → real Slack message → watch logs. No module-level testing. This made iteration slow and bugs hard to catch early. Ageri will have many workspaces built on top of it, so the core platform must be solid.
+
+**How to apply:**
+- Each module (Orchestrator, memory tiers, tool registry, workspace adapters) should be independently testable with mocked boundaries
+- Integration tests for full flows (message in → action out) before shipping
+- Local dev mode that mocks external services (Slack, GitHub, etc.) so no live infra needed for testing
+- Don't ship Ageri core until the test harness exists — platform stability is a prerequisite for workspace extensibility

package/.cairn/memory/auto-memory/project_ageri_personality.md

@@ -0,0 +1,61 @@
+---
+name: Ageri personality and user intelligence vision
+description: Vision for Ageri as a truly smart personal assistant — user profiling, cultural awareness, language adaptation, role-playing
+type: project
+---
+
+Ageri should evolve from a task executor into a genuinely intelligent companion that knows the user deeply.
+
+**Core vision:** Ageri studies the user over time and builds a persistent mental model of them — their habits, interests, communication style, culture, language, and routines. Every interaction is an opportunity to learn.
+
+## What Ageri should learn and remember
+
+**Language & communication style**
+- Detect the user's preferred language from their messages — respond in the same language automatically
+- Learn their tone (formal vs casual, humor level, how they phrase things)
+- Adapt vocabulary and register to match the user
+
+**Identity & address**
+- Learn the user's name and how they prefer to be addressed
+- Know their timezone, location (inferred from context or explicitly set)
+- Understand their role/occupation to contextualize requests
+
+**Culture & location**
+- Detect or ask where the user lives
+- Learn about their country's culture, customs, public holidays, food, language nuances
+- Use culturally appropriate greetings, references, and examples
+
+**Habits & routines**
+- Notice patterns: when they wake up, when they work, what they ask about on certain days
+- Learn recurring tasks, preferences, and rituals
+- Proactively suggest reminders based on observed routine
+
+**Interests & hobbies**
+- Build a topic map of what the user cares about
+- Remember what they've asked about before and connect topics over time
+- Surface relevant info without being asked
+
+**Relationships**
+- Remember names and context of people the user mentions (family, colleagues, friends)
+- Keep track of commitments made to specific people
+
+## Roles Ageri can play
+
+Depending on the user and context, Ageri adapts its role:
+- **Companion** — casual chat, humor, emotional check-ins
+- **Personal assistant** — reminders, tasks, memory
+- **Research assistant** — deep dives, synthesis, tracking topics
+- **Coach** — habits, routines, accountability (if user opts in)
+
+## How to implement
+
+All learned facts stored in `long_term` memory under structured keys:
+- `user:name`, `user:location`, `user:timezone`, `user:language`
+- `user:interest:{topic}`, `user:habit:{description}`, `user:person:{name}`
+- `user:style:tone`, `user:style:address` (how user likes to be addressed)
+
+**Language detection:** Already works — Claude responds in the user's language when the system prompt doesn't force English. No extra code needed for basic support.
+
+**User profiling intent:** Add `LEARN` intent to personal app — when Ageri notices something worth remembering about the user from their message, it silently writes to memory. This should happen passively during every ANSWER interaction too.
+
+**Why:** A complete smart assistant must feel like it *knows* you — not just execute tasks. The memory system is already built for this. The missing piece is actively populating it from every interaction.

package/.cairn/memory/auto-memory/project_ageri_platform_vision.md

@@ -0,0 +1,70 @@
+---
+name: Ageri platform vision and architecture decisions
+description: Full platform vision — own apps, skill marketplace, mobile runtime, presence, groups
+type: project
+---
+
+## Ageri is a Platform, Not a Slack Bot
+
+Ageri has its own native apps (mobile + desktop). Slack/WhatsApp/etc are adapter skills — outbound tools the user can activate, not the primary interface. No plans to integrate other messaging platforms.
+
+```
+Ageri App (mobile/desktop)     ← the interface Ageri owns
+    ↓
+Ageri Runtime                  ← the engine (installable anywhere)
+    ↓
+Skills                         ← capabilities
+    ├── personal, research     ← core cognitive skills
+    ├── slack, email, github   ← outbound adapter skills
+    └── camera, calendar       ← mobile-native skills
+```
+
+**Why:** Owning the interface = owning the user relationship. Not constrained by Slack API changes or pricing. Companion AI experience doesn't belong in a work tool.
+
+## Skill Mobility Attribute
+
+Each skill declares `mobility=true/false`:
+- `mobility=true` — works on mobile without a PC (personal, research, email, camera)
+- `mobility=false` — requires PC/desktop resources (code-runner, file-system, sentinel)
+
+A profile's available skills on mobile = all its skills where `mobility=true`. No separate mobile profile config needed.
+
+## Mobile Ageri Runtime
+
+- Same codebase, deployed on mobile device
+- Only loads `mobility=true` skills
+- Users without a PC can use Ageri mobile-only — download skills from marketplace
+- PC Ageri is the "home base" (source of truth for memory)
+- When PC is offline, mobile runs from last-synced state; reconciles delta when PC comes back
+
+## Sync and Privacy
+
+- **Cloud DB stores: presence only** — instance status, last_seen, type (desktop/mobile). Hashed user ID, no real identity.
+- **User data never touches the cloud** — memories, conversations, facts stay in local SQLite
+- **Sync is peer-to-peer** between instances, direct + encrypted, when both are online
+- **Single session lock** — only one mobile Ageri instance active at a time per user. Cloud DB acts as mutex. Prevents sync conflicts.
+
+## Agent Profile Groups
+
+Users can create a group where multiple profiles join:
+- Profiles addressed by name (@Mentor, @Selina)
+- All communication routes through Orchestrator — no direct agent-to-agent
+- Profiles contribute from their angle (Mentor asks the probing question, Colleague gives tactical take)
+- Presence-aware: offline profiles are greyed out in group
+
+## Skill Marketplace (Production — future)
+
+- Hosted page exposing skills to communities
+- Skill creators must register products via the system
+- Creators can sell skills (free or paid) — monetization planned post-production
+- Skills declare metadata: name, version, author, mobility, required permissions, price
+- `ageri add <skill-name>` installs from registry
+- Skills run locally — marketplace never sees user data
+- Verified skills badge (reviewed, trusted)
+
+## Business Model Notes
+
+- Not competing with Apple/Google on mass-market AI assistant
+- Winning paths: privacy-conscious power users → B2B enterprise (AI that never leaves your infra) → marketplace platform moat
+- Companion AI (private, local, customizable) addresses trust gap that Replika/Character.AI can't solve
+- Interface ownership is the most important long-term decision

package/.cairn/memory/auto-memory/project_publish_workflow.md

@@ -0,0 +1,23 @@
+---
+name: Sentinel npm publish workflow
+description: Who publishes to npm, when, and how — Dev Claude vs human+Claude
+type: project
+---
+
+User and Claude Code are joint project owners for Sentinel.
+
+**Publish workflow:**
+- Dev Claude fixes bugs autonomously → commits to `/home/sentinel/sentinel/code/` → live immediately on server
+- Dev Claude never publishes to npm (race condition risk with multiple instances)
+- User + Claude Code review Dev Claude's commits periodically and publish manually
+- Auto-upgrade (every 6h) distributes published versions to all running instances
+
+**How to publish:**
+- User says "publish", "release", or similar
+- Claude Code checks recent Dev Claude commits (`git log --oneline` on server or local)
+- Claude Code bumps patch version in `cli/package.json`
+- Runs syntax checks + `npm publish --access public` from `J:\Projects\Sentinel\cli\`
+
+**Current version:** 1.4.90 (published 2026-03-27)
+
+**Why:** Dev Claude (sentinel-1881) and Dev Claude (sentinel-elprint) both share the same source repo on the server. If both published to npm they'd conflict on version numbers.

package/.cairn/memory/auto-memory/project_sentinel_state.md

@@ -0,0 +1,44 @@
+---
+name: Sentinel project state
+description: Current state of Sentinel — latest npm version, key modules, architecture decisions
+type: project
+
+---
+
+Sentinel is published as @misterhuydo/sentinel on npm. Latest version: 1.4.96.
+
+**Why:** Autonomous DevOps agent — watches prod logs, generates Claude Code fixes, opens PRs. Deployed as one instance per project.
+
+**How to apply:** When making changes, always bump package.json version and run `npm publish --access public` from `J:\Projects\Sentinel\cli`. Python source is bundled into the npm package via `cli/scripts/bundle.js`.
+
+Key architecture decisions made:
+- Auth split: ANTHROPIC_API_KEY → Sentinel Boss (structured tools), Claude Pro OAuth → fix_engine/ask_codebase (heavy tasks). Controlled by CLAUDE_PRO_FOR_TASKS=true.
+- Per-user concurrent Slack sessions (no queue) — each user gets independent session, history persisted in SQLite.
+- notify.py: shared Slack alert module used by fix_engine + sentinel_boss — never silent on rate limits/auth failures.
+- sentinel_boss.py uses `<@USER_ID>` Slack mentions in all replies. user_id→display_name map stored in slack_users SQLite table.
+- post_file tool: Claude can upload files directly to Slack conversation via files_upload_v2.
+- bin/sentinel.js has self-heal: if upgrade.js fails to load, falls back to bare npm install.
+
+SQLite tables: errors, fixes, reports, conversations, submitted_issues, slack_users.
+
+Docs: README.md updated, docs/slack_integration.md created with full Slack setup guide including all 9 scopes.
+
+---
+
+## chain_release (as of 2026-03-26)
+
+- chain_release flow confirmed working end-to-end: TypeLib → Java-SDK → Admin-SDK.
+- chain_release pushes dep updates directly to master (not via PR) — this is an admin-confirmed operation.
+- cicd_trigger.py has wait=True Jenkins polling: 15-minute timeout, 20-second polling intervals.
+- datetime shadowing bug fixed in sentinel_boss.py (in the list_renovate_prs block).
+- Version reporting fix: chain_release now reports the actual released version read from the live pom, not the plan-time version.
+- The "auto-cascade" (execute_cascade) does NOT trigger automatically — chain_release must be called explicitly each time.
+
+## Pending upgrades (as of 2026-03-26)
+
+- STS, UAS, SSOLWA, UIB are planned for upgrade with Admin-SDK 3.1.6 at off-peak hours.
+
+## Server-side patch sync status
+
+- All server-side patches are applied directly to `/home/sentinel/sentinel/code/sentinel/` on the remote server.
+- These patches have NOT yet been synced back to the local git repo at `J:\Projects\Sentinel`.

package/.cairn/memory/auto-memory/project_sentinel_ui.md

@@ -0,0 +1,39 @@
+---
+name: Sentinel UI plan
+description: Web dashboard for Sentinel — planned but not urgent. To be hosted at sentinel.ageri.ai
+type: project
+---
+
+Sentinel needs a web dashboard UI. Not urgent but clearly defined scope.
+
+**Domain:** sentinel.ageri.ai (subdomain on ageri.ai, Cloudflare DNS)
+
+**Why:**
+- Share status/fix history with non-Slack users (e.g. boss, stakeholders)
+- Log browsing is painful in Slack
+- Admin management without requiring Slack login
+- Professional status page for showing what Sentinel has fixed/not fixed
+
+**Two audiences:**
+
+1. **Read-only viewers** (boss, stakeholders) — no login required or simple token link
+   - Live project status (running/down, last poll, error rate)
+   - Fix history: what was fixed, when, which repo, PR link
+   - Open issues: detected but not yet fixed
+   - Open PRs awaiting review
+
+2. **Admins** — authenticated
+   - User management
+   - Per-project config view
+   - PR management (merge/close without GitHub UI)
+   - Log viewer (searchable synced logs)
+   - Full error feed with severity + source
+
+**Tech stack:**
+- Backend: FastAPI (Python, fits existing codebase) — thin REST/WebSocket over state_store.py
+- Frontend: HTMX or plain HTML + Alpine.js — no React, keep it simple
+- Auth: single token-based (personal infra, no OAuth needed)
+
+**Priority:** OUTDATED DESIGN — needs full redesign before any work starts.
+**Build order:** Agent Profiles → Messenger adapter → Web UI redesign.
+**Do not start Web UI until Messenger adapter is done.**

package/.cairn/memory/auto-memory/reference_ageri_server.md

@@ -0,0 +1,35 @@
+---
+name: Ageri server reference
+description: SSH access, paths, and run commands for Ageri on Oracle Ampere
+type: reference
+---
+
+**Server:** Oracle Ampere ARM — 138.2.17.152 (24GB RAM)
+**User:** `ageri` (separate from `sentinel` user)
+**SSH from local:** `ssh -i /c/Users/huy/.ssh/oracle/devtest-arm-ampere.key ageri@138.2.17.152`
+
+**Directory layout:**
+- `~/ageri/code` — Python source (git clone of misterhuydo/Ageri)
+- `~/ageri/venv` — Python virtualenv
+- `~/ageri/ageri.properties` — main config
+- `~/ageri/private_ageri.properties` — secrets (chmod 600)
+- `~/ageri/ageri.log` — log file
+- `~/ageri/state.db` — SQLite memory store
+- `~/.ssh/ageri_deploy` — GitHub deploy key (read-only, added to Ageri repo)
+
+**Run:**
+```bash
+cd ~/ageri/code && AGERI_CONFIG=~/ageri ~/ageri/venv/bin/python -m ageri.main >> ~/ageri/ageri.log 2>&1 &
+tail -f ~/ageri/ageri.log
+```
+
+**Install sdk after git pull:**
+```bash
+~/ageri/venv/bin/pip install -e ~/ageri/code/sdk/
+```
+
+**GitHub clone (uses deploy key):**
+```bash
+git clone git@github-ageri:misterhuydo/Ageri.git ~/ageri/code
+```
+(Requires `~/.ssh/config` entry: `Host github-ageri` → `IdentityFile ~/.ssh/ageri_deploy`)

package/.cairn/memory/auto-memory/reference_cairn_federation.md

@@ -0,0 +1,26 @@
+---
+name: Cairn sub-index federation
+description: How Cairn federates multiple repo indexes — repos must be subdirectories of the workspace for automatic federation
+type: reference
+---
+
+Cairn's `cairn_maintain` indexes from `process.cwd()` — wherever the Claude Code session starts.
+There is no `--path` CLI flag; indexing is MCP-only (called from within a Claude Code session).
+
+**Sub-directory federation (built-in, passive):**
+- Each repo subdirectory can have its own `.cairn/index.db` (built when Claude Code runs there)
+- When `cairn_maintain` runs at the workspace root, it globs `**/.cairn/index.db` and federates all sub-indexes
+- `cairn_search` queries all federated sub-indexes and merges results
+- All tools use UNION ALL views across all indexes
+- Federation paths are persisted in `sub_indexes` table → `cairn_resume` re-federates automatically
+
+**Critical constraint:** Repos must be **subdirectories** of the workspace root — external paths (e.g. `~/git/repo`) are NOT discovered. There is no `cairn.repos` config or external path registration yet.
+
+**Implication for Sentinel:**
+- `fix_engine.py` must run `claude --print` with `cwd=repo.local_path` so Cairn hooks index that repo
+- For `sentinel_boss` to federate all repo indexes, repos must be subdirectories of the Sentinel project dir
+- Default `LOCAL_PATH` should be `<project_dir>/repos/<repo-name>` — user can override but loses federation
+- Shared repos used by multiple Sentinel projects: each project gets its own clone in its `repos/` dir
+
+**How to apply:** When setting `LOCAL_PATH` defaults in `sentinel add`, use `<project_dir>/repos/<repo-name>`.
+Wire `cwd=repo.local_path` into `fix_engine._run_claude_attempt`.

package/.cairn/memory/auto-memory/reference_oracle_servers.md

@@ -0,0 +1,24 @@
+---
+name: Oracle Cloud servers
+description: Two Oracle Always Free servers — Ampere ARM for personal/internal projects, micro for lightweight tasks
+type: reference
+---
+
+## Oracle Ampere (primary personal server)
+- **SSH:** `ssh -i /home/huy/.ssh/oracle/devtest-arm-ampere.key ubuntu@138.2.17.152`
+- **Key (Windows):** `C:\Users\huy\.ssh\oracle\devtest-arm-ampere.key`
+- **Specs:** ARM Ampere — up to 4 OCPUs, 24GB RAM (Oracle Always Free generous tier)
+- **OS:** Ubuntu
+- **Purpose:** Personal/internal projects — Ageri, personal tools, dev experiments
+- **Note:** Separate from EC2 (13.50.101.130) which is for company projects (1881, elprint)
+
+## Oracle Micro (tiny, secondary)
+- **SSH:** `ssh -i /home/huy/.ssh/oracle/devtest-arm-micro.key ubuntu@155.248.181.206`
+- **Key (Windows):** `C:\Users\huy\.ssh\oracle\devtest-arm-micro.key`
+- **Specs:** 1 OCPU, 1GB RAM — very limited
+- **Purpose:** Lightweight only — Cloudflare Tunnel endpoint, simple proxy, cron jobs, DNS, monitoring relay
+
+## Server allocation strategy
+- **EC2 (13.50.101.130):** Company projects — Sentinel for 1881, elprint, etc.
+- **Oracle Ampere (138.2.17.152):** Personal projects — Ageri, Taplo monitoring, personal Sentinel
+- **Oracle Micro (155.248.181.206):** Ultra-lightweight tasks only — tunnel, relay, watchdog

package/.cairn/memory/auto-memory/reference_sentinel_server.md

@@ -0,0 +1,15 @@
+---
+name: Sentinel server SSH connection
+description: SSH credentials and host for the Sentinel deployment server
+type: reference
+---
+
+- **Host:** 13.50.101.130
+- **User:** ec2-user
+- **Key (local Windows path):** C:\Users\huy\.ssh\sentinel.pem
+- **Key (in bash/WSL):** /c/Users/huy/.ssh/sentinel.pem
+- **Key (on server):** /home/huy/.ssh/sentinel.pem
+- **Command:** `ssh -l ec2-user -i /c/Users/huy/.ssh/sentinel.pem 13.50.101.130`
+- **Sentinel process user:** sentinel
+- **Code path:** /home/sentinel/sentinel/code/sentinel/
+- **Instance config:** /home/sentinel/sentinel/sentinel-1881/

package/.cairn/memory/auto-memory/reference_taplo.md

@@ -0,0 +1,52 @@
+---
+name: Taplo project reference
+description: Taplo platform — universal seller identity/QR discovery app, Cloudflare-native, pnpm monorepo
+type: reference
+---
+
+**Repo:** git@github.com:misterhuydo/taplo.git
+**Local:** J:\Projects\taplo
+**Domain:** taploapp.com + taploapp.vn (Cloudflare)
+**Account:** taplo.platform@gmail.com
+
+**What it is:** Universal seller identity + QR discovery platform. Sellers register, get a QR code instantly, customers scan it to see their page. Global, not Vietnam-specific.
+
+**Stack (100% Cloudflare-native):**
+- Workers (API), D1 (SQLite DB), R2 (images/QR files), KV (sessions/cache), Queues (async jobs), Pages (Next.js web)
+- pnpm workspaces + Turborepo monorepo
+- TypeScript strict everywhere
+- React Native + Expo (mobile — iOS + Android)
+- Next.js SSR for seller pages (SEO critical)
+
+**Business model:** Free → Basic ($5/mo) → Pro ($15/mo) → Business ($50/mo)
+
+**Current phase:** Phase 1 — Foundation (paused, resuming soon)
+**First build checklist:** monorepo → types → D1 schema → identity module → sellers module → QR module → seller page → search → dashboard → mobile skeleton → deploy
+
+**Key rules (never violate):**
+- No hardcoded VND/Vietnamese/HCMC assumptions
+- UUID v4 always, never sequential IDs
+- E.164 phone format always
+- Analytics events always via Queue, never blocking
+- Migrations only, never manual schema edits
+- Never hard DELETE — soft delete via status field
+- QR pages must always use KV edge cache
+
+**Testing + error monitoring need:**
+- User wants tests written per module as each is built
+- Sentinel can monitor Taplo in production (Cloudflare Worker logs → Sentinel)
+- Sentry for unhandled exceptions
+- Structured JSON logging from day one
+
+**Sentinel integration note:**
+- Taplo is 100% Cloudflare — no SSH servers
+- Sentinel CF log source (SOURCE_TYPE=cloudflare) covers Workers logs
+- CF Pages build errors, D1 errors surface in Worker logs
+- No separate DB log stream — all errors in Worker logs
+
+**TODOs saved in:** J:\Projects\taplo\TODOs.txt
+- WebAuthn/passkeys auth
+- Smart country code detection
+- Content moderation pipeline (Claude API for text, CF Images for photos)
+- iOS App Store compliance strategies (documented in detail)
+- taploapp.vn → auto Vietnamese locale

package/.cairn/session.json

@@ -1,6 +1,6 @@
 {
-  "message": "Auto-checkpoint at 2026-04-25T09:42:20.720Z",
-  "checkpoint_at": "2026-04-25T09:42:20.724Z",
+  "message": "Auto-checkpoint at 2026-04-27T12:15:40.415Z",
+  "checkpoint_at": "2026-04-27T12:15:40.417Z",
   "active_files": [
     "J:\\Projects\\Sentinel\\cli\\bin\\sentinel.js",
     "J:\\Projects\\Sentinel\\cli\\lib\\test.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@misterhuydo/sentinel",
-  "version": "1.6.10",
+  "version": "1.6.11",
   "description": "Sentinel — Autonomous DevOps Agent installer and manager",
   "bin": {
     "sentinel": "./bin/sentinel.js"

package/python/sentinel/__init__.py

@@ -1 +1 @@
-__version__ = "1.6.10"
+__version__ = "1.6.11"

package/python/sentinel/notify.py

@@ -310,7 +310,7 @@ def notify_fix_blocked(
         f"{repo_line}"
         f"*What Claude found:* {short_reason}\n\n"
         f"*Original report:*\n{report_block}\n\n"
-        f"_Reply `ignore` to dismiss, or assign someone to investigate._"
+        f"_Reply `ignore` to dismiss, or reply here to investigate._"
     )
 
     target_channel = origin_channel or cfg.slack_channel

package/python/sentinel/slack_bot.py

@@ -608,6 +608,21 @@ async def _dispatch(event: dict, client, cfg_loader, store) -> None:
     if not text:
         text = "hello"
 
+    # Thread-reply context: if the user is replying inside a thread (rather
+    # than starting one), pull the parent message so Boss sees what the user
+    # is actually focused on. Without this, a one-word reply like "ignore" or
+    # "investigate" in a fix-blocked alert thread arrives at Boss with no
+    # context at all — Boss can't tell which fingerprint or which error.
+    thread_ts = event.get("thread_ts")
+    if thread_ts and thread_ts != event.get("ts"):
+        parent = await _fetch_thread_parent(client, channel, thread_ts)
+        if parent:
+            text = (
+                "[Thread context — the message in this thread the user is replying to:]\n"
+                f"{parent}\n\n"
+                f"[User's reply:]\n{text}"
+            )
+
     # Allowlist check — if SLACK_ALLOWED_USERS is configured, only those users + admins may interact.
     # Admins (SLACK_ADMIN_USERS) are always allowed regardless of SLACK_ALLOWED_USERS.
     allowed = cfg_loader.sentinel.slack_allowed_users
@@ -806,3 +821,22 @@ def _strip_mention(text: str) -> str:
     """Remove leading <@BOTID> mention from message text."""
     import re
     return re.sub(r"^<@[A-Z0-9]+>\s*", "", text)
+
+
+async def _fetch_thread_parent(client, channel: str, thread_ts: str) -> str:
+    """Fetch the first (parent) message of a Slack thread.
+
+    Used so a user reply in a thread that Sentinel started (e.g. a fix-blocked
+    alert) gets the alert text injected into Boss's prompt — otherwise Boss
+    sees only the bare reply ("ignore", "investigate", ...) with no context.
+    """
+    try:
+        resp = await client.conversations_replies(
+            channel=channel, ts=thread_ts, limit=1, inclusive=True,
+        )
+        msgs = resp.get("messages", [])
+        if msgs:
+            return (msgs[0].get("text") or "").strip()
+    except Exception as exc:
+        logger.warning("Boss: could not fetch thread parent for %s: %s", thread_ts, exc)
+    return ""