* fix(continuous-learning-v2): warn when the observer never survives a hook invocation (#2489)
The observer is lazy-started from a hook process that exits immediately
afterwards. start-observer.sh's liveness check runs inside that still-living
process tree, so it always sees a healthy observer and prints "Observer
started (PID: N)". On native Windows (Git Bash/MSYS2) the reap happens later,
when the hook's Job Object closes, so no self-check placed in
start-observer.sh can ever observe the failure.
The next hook invocation is the only place the death is visible, and
_CHECK_OBSERVER_RUNNING already found it there -- then discarded it, deleting
the stale PID file and restarting silently, once per tool call, forever. Users
were left with an observer-start.log full of success lines and an observer
that never completed a single analysis cycle.
Record the "well-formed PID that is no longer alive" case, count consecutive
non-survivals in ${PROJECT_DIR}/.observer-nosurvive-count, and log one
explanatory warning when the streak reaches ECC_OBSERVER_NOSURVIVE_WARN_AFTER
(default 3). Warning fires on equality so a persistent failure logs once per
streak rather than once per tool call; finding the observer alive resets the
streak. The Windows-specific explanation is gated on uname so Linux/macOS
users are pointed at observer.log instead of a wrong diagnosis.
Counting happens in the caller, not inside _CHECK_OBSERVER_RUNNING, because
that function is invoked once per PID file and again under the start lock.
The PowerShell backgrounding rewrite is deliberately not included: it cannot
be exercised on a non-Windows machine, and untested process-spawning code is
a worse outcome than an accurate diagnostic.
* docs(continuous-learning-v2): state observer platform support and the new warn threshold
The observer's Windows limitation was only discoverable by hitting it. Record
it next to observer.enabled, where it is read before the flag is set, and
document ECC_OBSERVER_NOSURVIVE_WARN_AFTER so the knob added alongside the
warning does not repeat the undocumented-env-var problem tracked in #2573.
zh-TW is intentionally left alone: translation parity is not enforced here and
the repo rejects blind translation imports without translator review.
* fix(continuous-learning-v2): serialize the non-survival streak under the lazy-start lock
observe.sh runs on every tool call, so the streak read-modify-write could race
between concurrent invocations -- losing an increment or logging the warning
twice. That is the same class of bug the signal counter hit in #2296, and this
repo's rule is to never fall back to an unlocked read-modify-write.
Rather than add a second lock, move the increment into _START_OBSERVER_LOGGED.
All three of its call sites already run inside the lazy-start lock
(flock / lockfile / mkdir), so the update is serialized with no new machinery.
Counting at the restart instead of at detection also means N racing hooks
record one death rather than N.
The reset stays in the caller: it is an idempotent unlink, not a
read-modify-write, so it needs no lock.
Adds a regression case pinning the increment inside _START_OBSERVER_LOGGED and
asserting all three call sites remain locked.
* fix(continuous-learning-v2): harden the non-survival threshold and warning output
Three review findings on the #2489 diagnostic:
- An all-zero threshold silently disabled it. `00` passes a digits-only check
but compares as zero, and the streak only grows, so the warning could never
fire. Normalize with base-10 arithmetic and fall back to the default for
anything below 1. Base 10 is forced explicitly because a leading zero would
otherwise be read as octal, and `08` is an arithmetic error that would abort
the hook under `set -e`. The same normalization now guards the streak read.
- An unwritable log silently swallowed the diagnostic. Build the message once
and fall back to stderr when the append fails. This cannot spam: the block
runs once per streak, not once per tool call. The counter write keeps its
`|| true` -- observe.sh runs on every tool call and the repo rule is that
hooks exit 0 on non-critical errors, so a full disk must not break tool use.
- The live-PID test fixture used process.pid, which is 1 in a container and is
deliberately rejected by _CHECK_OBSERVER_RUNNING; the reset case would then
fail for the wrong reason. Use a spawned child and clean it up.
Adds a regression case for the all-zero threshold. Verified on bash 3.2 (the
macOS CI runner shell) as well as bash 5.
* fix(continuous-learning-v2): warn only on a persisted streak increment
If the counter write fails, the file stays below the threshold, so every later
hook invocation rereads it, re-increments in memory, hits the equality check
and warns again -- turning the once-per-streak diagnostic into once-per-tool-
call spam. That is worse in exactly the case the stderr fallback added in the
previous commit was meant to cover, since a disk that cannot take the log
usually cannot take the counter either.
Gate the warning on the write succeeding. The write stays non-fatal: it runs
as an `if` condition, so `set -e` is satisfied and an unwritable counter costs
a delayed diagnostic rather than a broken tool call.
Tests: an unwritable counter must stay silent across repeated invocations while
the hook still exits 0, and a leading-zero threshold ("08") must be read as
decimal -- "00" alone did not exercise the base-10 conversion, since it is zero
either way.
---------
Co-authored-by: haelyra <49814733+haelyra@users.noreply.github.com>
2026-08-12 18:36:30 -04:00
devin-ai-integration[bot]GitHubDevin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>affaanDevin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>Affaan Mustafa
* chore(continuous-learning-v2): standardize shell shebangs to env bash
Three scripts under skills/continuous-learning-v2/ used the hardcoded
`#!/bin/bash` shebang while the other four already used the portable
`#!/usr/bin/env bash`:
- hooks/observe.sh (runs on every hook invocation)
- scripts/detect-project.sh
- agents/start-observer.sh
The hardcoded interpreter path fails to execute on systems where bash is
not installed at /bin/bash (NixOS, some Homebrew layouts, FreeBSD).
Standardize all three to `#!/usr/bin/env bash`, matching the repo-wide
majority convention, and add a regression test that asserts shebang
uniformity for every shell script in this skill so the inconsistency
cannot reappear.
Fixes#2303
* test(continuous-learning-v2): harden shebang test runner
Address review feedback on the shebang-consistency regression test:
- firstLine() now splits on /\r?\n/ so a script checked out with CRLF
line endings does not leave a trailing carriage return that would
break the shebang comparison on Windows.
- The test() helper now surfaces the full error (stack trace, not just
the message) on failure and writes pass/fail lines via
process.stdout/stderr so diagnostics are preserved.
* test(continuous-learning-v2): skip hidden dirs in shebang scan
The recursive shell-script scan now skips hidden directories (e.g. the
observer's runtime `.observer-tmp`). This keeps the shebang-consistency
check deterministic: only committed skill scripts are examined, and an
untracked local artifact left over from an observer run can no longer
cause a false failure.
* fix(clv2): surface SIGALRM timeout drops in observe.sh
The inline-Python observation writers in observe.sh arm a signal.SIGALRM
alarm (8s) so they self-terminate before the async hook's 10s timeout can
orphan them (#2278). The handler _ecc_bail called sys.exit(0) with no
logging, so when the alarm fired the in-flight observation was silently
dropped: nothing was logged, no partial write occurred, and the shell saw
a clean exit. There was no way to detect or count how many observations
were being lost.
Add a single stderr visibility line to both _ecc_bail handlers (the
parse-error fallback path and the main observation-writing path) before
sys.exit(0), using the repo's "[observe]" log prefix. Exit code stays 0:
in a Claude Code hook a non-zero exit signals a block, so changing it
would turn an internal timeout into a user-facing tool block. The warning
goes to stderr (not stdout) because both blocks redirect stdout into the
observations file.
Add tests/hooks/observe-signal-timeout.test.js: a static regression guard
that every _ecc_bail handler logs to stderr before exiting and keeps exit
0, plus a behavioral check that runs the real handler text extracted from
observe.sh and confirms a fired alarm exits 0 and emits the [observe]
warning on stderr only.
Fixes#2300
* test(clv2): exercise both _ecc_bail handlers end-to-end
The behavioral SIGALRM-fire test ran only handlers[0] (the parse-error
fallback path); the main observation-write path (handlers[1]) was covered
only by the static regex guard. The write path is the higher-value one to
verify end-to-end since it carries valid, parseable data that would succeed
given more time, so a silent drop there is the worst case.
Loop the behavioral check over every extracted handler so a regression that
silenced the second handler's stderr write is caught at runtime, not just by
the static guard.
* test(clv2): select timeout handlers by marker, not array index
The behavioral check looped over all extracted _ecc_bail handlers by index.
If an unrelated _ecc_bail were ever added to observe.sh, the loop would
either test the wrong block or be diluted. Filter the handlers to those
carrying the "[observe] SIGALRM timeout" marker so the live SIGALRM check
stays pinned to the two #2300 timeout handlers regardless of array order or
future additions.
* test(clv2): fail fast when python is missing in SIGALRM check
The behavioral test returned early when no python interpreter was found,
which the test harness records as a PASS — so the SIGALRM contract could go
entirely unverified yet still look green. Throw instead, matching the
existing insaits-security-monitor convention of failing when a required
Python runtime is absent, and drop the in-test console.log.
observe.sh bumps the SIGUSR1 throttle counter in
${PROJECT_DIR}/.observer-signal-counter with an unlocked read-modify-write.
The hook runs on every tool call, so concurrent invocations read the same
value, both increment, and lose a write, signaling the observer at
unpredictable intervals and defeating the #521 throttle.
Serialize the read-modify-write under a lock, and only ever bump the counter
while that lock is held:
- Prefer flock with a bounded -w wait (the OS auto-releases it when the fd
closes or the process dies, so there is no stale lock and no lost increment);
on a timeout the tick is skipped rather than bumped unlocked.
- Fall back to an atomic mkdir lock on platforms without flock, with a bounded
spin. An EXIT trap cleans up on normal completion; INT/TERM traps release the
lock and exit, so a signal cannot drop the lock and then continue the
read-modify-write without ownership. If the lock cannot be acquired in the
budget the tick is skipped rather than raced. No hand-rolled PID stale-reclaim
(which is racy and can delete a live re-acquirer's lock).
- Guard the counter read against a corrupt (non-integer) file that would abort
the hook under set -e.
Add tests/hooks/observe-signal-counter-race.test.js: 20 concurrent observe.sh
invocations must not lose increments (exact under flock; at most one dropped on
the best-effort mkdir fallback), the runner rejects on any hook execution
failure or hang, plus content guards for the lock and the corrupt-counter
handling.
Fixes#2296
The observe hook's secret-scrub regex used a generic ([A-Za-z]+\s+)? group
that overlapped the separator and value classes, causing exponential
backtracking on identifier-dense tool I/O — an orphaned python child then
pegged a core at ~100% CPU for days because the async hook timed out without
killing it.
- Rewrite _SECRET_RE as a linear matcher: bounded separator {1,8}, a fixed
set of auth schemes (bearer|basic|token|bot) instead of [A-Za-z]+, and a
bounded value {8,256}. Pathological input drops from hang to <1ms; real
secrets still redact (verified incl. 'Bearer <token>').
- Add a signal.alarm(8) self-timeout to both scrub blocks so any runaway
child self-terminates before the 10s async-hook timeout can orphan it.
The observe.sh Layer 1 entrypoint guard short-circuits with exit 0 when
CLAUDE_CODE_ENTRYPOINT is not in {cli, sdk-ts, claude-desktop}. Claude
Code's VS Code extension sets CLAUDE_CODE_ENTRYPOINT=claude-vscode, so
VS Code users see no observations recorded — observations.jsonl never
gets created and the instinct pipeline stays empty.
Add claude-vscode to the allowlist, mirroring the precedent in #1522
which added claude-desktop the same way.
Add a regression test that spawns observe.sh under bash -x for each
allowed entrypoint (cli, sdk-ts, claude-desktop, claude-vscode) and
each denied entrypoint (unknown-host, claude-cody, mcp), asserting
that allowed entrypoints reach Layer 2's ECC_HOOK_PROFILE check while
denied entrypoints stop at Layer 1.
Fixes#2102
On Windows 10/11 without Python installed from the Microsoft Store, the
"App Execution Alias" stubs at %LOCALAPPDATA%\Microsoft\WindowsApps\python.exe
and python3.exe are symlinks to AppInstallerPythonRedirector.exe. These
stubs neither launch Python nor honor `-c`; calls print a bare "Python "
line and exit, silently breaking every JSON-parsing step in observe.sh.
Net effect: observations.jsonl is never written, CLV2 appears installed
correctly, and the only residual artifact is `.last-purge`.
This commit:
1. Adds `_is_windows_app_installer_stub` helper that detects the stub
via `command -v` output and optional `readlink -f` resolution.
2. Teaches `resolve_python_cmd` to skip stub candidates and fall
through to the next real interpreter (typically C:\...\Python3xx\python.exe).
3. Exports the stub-aware CLV2_PYTHON_CMD before sourcing
detect-project.sh, which already honors an already-set value,
so the shared helper does not re-resolve and re-select the stub.
POSIX-compatible. No behavior change on macOS / Linux / WSL where no
such stub exists.
Refs: observations.jsonl empty on Windows Claude Desktop users.
Three fixes for the positive feedback loop causing runaway memory usage:
1. SIGUSR1 throttling in observe.sh: Signal observer only every 20
observations (configurable via ECC_OBSERVER_SIGNAL_EVERY_N) instead
of on every tool call. Uses a counter file to track invocations.
2. Re-entrancy guard in observer-loop.sh on_usr1(): ANALYZING flag
prevents parallel Claude analysis processes from spawning when
signals arrive while analysis is already running.
3. Cooldown + tail-based sampling in observer-loop.sh:
- 60s cooldown between analyses (ECC_OBSERVER_ANALYSIS_COOLDOWN)
- Only last 500 lines sent to LLM (ECC_OBSERVER_MAX_ANALYSIS_LINES)
instead of the entire observations file
Closes#521
* feat(continuous-learning-v2): add lazy-start observer logic
Auto-starts observer when observer.enabled: true in config and no .observer.pid exists.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(continuous-learning-v2): address PR review concerns
- Use flock for atomic check-then-act to prevent race conditions
- Check both project-scoped AND global PID files before starting
- Support CLV2_CONFIG override for config file path
- Check disabled file in lazy-start logic
- Use double-check pattern after acquiring lock
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(observe.sh): address PR review comments
- Add stale PID cleanup via _CHECK_OBSERVER_RUNNING function
- Add macOS fallback using lockfile when flock unavailable
- Fix CLV2_CONFIG override: use EFFECTIVE_CONFIG for both check and read
- Use proper Python context manager (with open() as f)
- Deduplicate signaled PIDs to avoid duplicate USR1 signals
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(observe.sh): wrap macOS lockfile fallback in subshell with trap
- Wrap lockfile block in subshell so exit 0 only terminates that block
- Add trap for EXIT to clean up lock file on script interruption
- Add -l 30 (30 second expiry) to prevent permanent lock file stuck
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(observe.sh): address remaining PR review comments
- Validate PID is a positive integer before kill calls to prevent
signaling invalid targets (e.g. -1 could signal all processes)
- Pass config path via env var instead of interpolating shell variable
into Python -c string to prevent injection/breakage on special paths
- Check CLV2_CONFIG-derived directory for disabled file so disable
guard respects the same config source as lazy-start
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Claude Code sends tool output as `tool_response` in PostToolUse hook
payloads, but observe.sh only checked for `tool_output` and `output`.
This caused all observations to have empty output fields, making the
observer pipeline blind to tool results.
Adds `tool_response` as the primary field to check, with backward-
compatible fallback to the existing `tool_output` and `output` fields.
* fix(hooks): scrub secrets and harden hook security
- Scrub common secret patterns (api_key, token, password, etc.) from
observation logs before persisting to JSONL (observe.sh)
- Auto-purge observation files older than 30 days (observe.sh)
- Strip embedded credentials from git remote URLs before saving to
projects.json (detect-project.sh)
- Add command prefix allowlist to runCommand — only git, node, npx,
which, where are permitted (utils.js)
- Sanitize CLAUDE_SESSION_ID in temp file paths to prevent path
traversal (suggest-compact.js)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(hooks): address review feedback from CodeRabbit and Cubic
- Reject shell command-chaining operators (;|&`) in runCommand, strip
quoted sections before checking to avoid false positives (utils.js)
- Remove command string from blocked error message to avoid leaking
secrets (utils.js)
- Fix Python regex quoting: switch outer shell string from double to
single quotes so regex compiles correctly (observe.sh)
- Add optional auth scheme match (Bearer, Basic) to secret scrubber
regex (observe.sh)
- Scope auto-purge to current project dir and match only archived
files (observations-*.jsonl), not live queue (observe.sh)
- Add second fallback after session ID sanitization to prevent empty
string (suggest-compact.js)
- Preserve backward compatibility when credential stripping changes
project hash — detect and migrate legacy directories
(detect-project.sh)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(hooks): block $() substitution, fix Bearer redaction, add security tests
- Add $ and \n to blocked shell metacharacters in runCommand to prevent
command substitution via $(cmd) and newline injection (utils.js)
- Make auth scheme group capturing so Bearer/Basic is preserved in
redacted output instead of being silently dropped (observe.sh)
- Add 10 unit tests covering runCommand allowlist blocking (rm, curl,
bash prefixes) and metacharacter rejection (;|&`$ chaining), plus
error message leak prevention (utils.test.js)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(hooks): scrub parse-error fallback, strengthen security tests
Address remaining reviewer feedback from CodeRabbit and Cubic:
- Scrub secrets in observe.sh parse-error fallback path (was writing
raw unsanitized input to observations file)
- Remove redundant re.IGNORECASE flag ((?i) inline flag already set)
- Add inline comment documenting quote-stripping limitation trade-off
- Fix misleading test name for error-output test
- Add 5 new security tests: single-quote passthrough, mixed
quoted+unquoted metacharacters, prefix boundary (no trailing space),
npx acceptance, and newline injection
- Improve existing quoted-metacharacter test to actually exercise
quote-stripping logic
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(security): block $() and backtick inside quotes in runCommand
Shell evaluates $() and backticks inside double quotes, so checking
only the unquoted portion was insufficient. Now $ and ` are rejected
anywhere in the command string, while ; | & remain quote-aware.
Addresses CodeRabbit and Cubic review feedback on PR #348.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Changes based on CodeRabbit review feedback:
1. Remove entire .cursor/ directory — it was an identical copy of the
main skills/commands/agents/rules, causing maintenance drift.
Users of Cursor can reference the canonical files directly.
2. Use explicit `is not None` checks instead of truthiness for
parsed['input'] and parsed['output']. Empty strings or empty
dicts are valid values that should be preserved.
The observe.sh script receives "pre" or "post" as $1 from the hook
config, but the Python code was looking for a "hook_type" field in
the stdin JSON. Claude Code does NOT include "hook_type" in the
JSON payload passed to hooks, so it always defaulted to "unknown",
causing all observations to be recorded as "tool_complete" —
PreToolUse events were never distinguished from PostToolUse.
Fix: capture $1 as HOOK_PHASE and pass it to Python via env var.
This also fixes TIMESTAMP export in the .cursor copy where inline
`VAR=val cmd` syntax didn't propagate to the python subprocess.
The inline environment variable syntax `TIMESTAMP="$timestamp" echo ...`
does not work correctly because:
1. The pipe creates a subshell that doesn't inherit the variable
2. The environment variable is set for echo, not for the piped python
Fixed by using `export` and separating the commands:
- export TIMESTAMP="$timestamp"
- echo "$INPUT_JSON" | python3 -c "..."
This ensures the TIMESTAMP variable is available to the python subprocess.
Fixes#227
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add try-catch around readFileSync in validate-agents, validate-commands,
validate-skills to handle TOCTOU races and file read errors
- Add validate-hooks.js and all test suites to package.json test script
(was only running 4/5 validators and 0/4 test files)
- Fix shell variable injection in observe.sh: use os.environ instead of
interpolating $timestamp/$OBSERVATIONS_FILE into Python string literals
- Fix $? always being 0 in start-observer.sh: capture exit code before
conditional since `if !` inverts the status
- Add OLD_VERSION validation in release.sh and use pipe delimiter in sed
to avoid issues with slash-containing values
- Add jq dependency check in evaluate-session.sh before parsing config
- Sync .cursor/ copies of all modified shell scripts
* fix: resolve multiple reported issues (#205, #182, #188, #172, #173)
- fix(observe.sh): replace triple-quote JSON parsing with stdin pipe to
prevent ~49% parse failures on payloads with quotes/backslashes/unicode
- fix(hooks.json): correct matcher syntax to use simple tool name regexes
instead of unsupported logical expressions; move command/path filtering
into hook scripts; use exit code 2 for blocking hooks
- fix(skills): quote YAML descriptions containing colons in 3 skill files
and add missing frontmatter to 2 skill files for Codex CLI compatibility
- feat(rules): add paths: filters to all 15 language-specific rule files
so they only load when working on matching file types
- fix(agents): align model fields with CONTRIBUTING.md recommendations
(opus for planner/architect, sonnet for reviewers/workers, haiku for
doc-updater)
* ci: use AgentShield GitHub Action instead of npx
Switch from npx ecc-agentshield to uses: affaan-m/agentshield@v1
for proper GitHub Action demo and marketplace visibility.
Fixes#113
The instinct commands referenced hardcoded paths that only work with
manual installation (~/.claude/skills/...). When installed as a plugin,
files are at ~/.claude/plugins/cache/.../skills/...
Changes:
- Updated instinct-status, instinct-import, evolve commands to use
${CLAUDE_PLUGIN_ROOT} with fallback to manual path
- Updated observe.sh hook documentation with both install methods
- Updated SKILL.md with plugin vs manual installation instructions
- Removed duplicate commands from skills/continuous-learning-v2/commands/
(already exist in commands/)
Users should use ${CLAUDE_PLUGIN_ROOT} in their hooks config when
installed as a plugin.
