pi-jscpd 0.1.0

package/docs/automatic-checkpoint.md

@@ -0,0 +1,235 @@
+# Automatic advisory checkpoint decision
+
+Status: **implemented with Effect-owned scheduling and automatic delivery**
+
+Scope: lifecycle and process model
+
+The completed Effect source migration preserves this trigger, generation,
+quiet-delivery, cancellation, and shutdown contract. Scheduling/background work
+uses scoped fibers and Effect transactions, application workflows compose native
+programs, and Pi host adapters use one managed runtime.
+
+## Decision
+
+Use Pi's `agent_settled` event as the only automatic-checkpoint eligibility
+signal. The handler must enqueue at most one generation-bound background check
+and return immediately; it must not await a jscpd process.
+
+Successful built-in `write` and `edit` results continue to mark the session
+changed and increment a mutation generation. They do not start scans. At
+`agent_settled`, the scheduler may start one check only when all of these remain
+true:
+
+- the session is enabled and trusted configuration has been restored;
+- at least one attributable mutation is newer than the last terminal automatic
+  attempt;
+- the pre-session baseline is accepted;
+- no automatic check already owns that mutation generation; and
+- the extension runtime is still active and Pi is idle.
+
+This makes the checkpoint **settled-triggered, dirty-coalesced, asynchronous,
+and latest-generation-only**. Multiple writes in one agent run produce one
+candidate check, not one process per write or model turn.
+
+## Evidence
+
+The decision was evaluated against Pi 0.84.4's installed extension
+documentation, public type definitions, and `AgentSession` runtime.
+
+Pi documents and types distinguish the candidate events as follows:
+
+- `tool_result` occurs after each tool execution and can interleave for parallel
+  tools.
+- `turn_end` occurs after one assistant response and its tool results; another
+  model/tool turn may start immediately.
+- `agent_end` ends one low-level agent run, but retry, automatic compaction, or a
+  queued continuation may still follow.
+- `agent_settled` occurs only after retry, compaction retry, and queued steering
+  or follow-up work are exhausted.
+- `session_shutdown` is the teardown boundary for quit, reload, new, resume, and
+  fork flows.
+
+The installed `AgentSession` runtime drains post-run retries, compaction, and
+queued messages before emitting `agent_settled`. Extension handlers are awaited,
+so doing the scan directly in the handler would extend prompt settlement by as
+much as the configured scan timeout. The handler therefore only schedules
+owned background work and returns.
+
+### Trigger cardinality
+
+For one logical user request with `W` successful attributable writes, `T` model
+turns, and `R` low-level runs caused by retry/compaction/queued continuations:
+
+| Candidate | Trigger opportunities | Settled tree? | Result |
+| --- | ---: | --- | --- |
+| `tool_result` | `W` | No | Reject: scan stampede and parallel-tool races |
+| `message_end` | user, assistant, and tool-result messages | No | Reject: noisy and not mutation-specific |
+| `turn_end` | `T` | No | Reject: can delay or race the next model turn |
+| `agent_end` | `R` | No | Reject: follow-ups and recovery may still mutate files |
+| `agent_settled` | 1 after the logical run settles | Yes | **Select as eligibility signal** |
+| next `before_agent_start` | 1 per later prompt | Previous run only | Reject as primary: delays the next user request |
+| idle/debounce timer | timing-dependent | Not guaranteed | Reject: duplicates Pi's settled lifecycle and adds timer races |
+| `session_shutdown` | 1 per teardown | Yes | Reject as scan trigger: too late to advise and conflicts with cleanup |
+
+`agent_settled` gives the lowest safe trigger cardinality. A dirty generation is
+still required because settled can occur after read-only work and because
+automatic work may be cancelled and retried later.
+
+## Runtime process model
+
+### While Pi is active
+
+1. A successful verified built-in mutation records its canonical project path,
+   invalidates acknowledgements touching that path, increments the mutation
+   generation, and marks automatic work dirty.
+2. No automatic scan runs during assistant streaming, tool execution, retries,
+   compaction recovery, steering, or queued follow-ups.
+3. `agent_settled` asks the scheduler to cover the latest dirty generation and
+   returns immediately.
+4. The scheduler reuses the existing bounded capability probe, accepted
+   baseline, full-project changed comparison, one serialized jscpd adapter, and
+   temporary-report ownership.
+5. A completion is accepted only if its runtime generation, branch scope,
+   mutation generation, and project identity are still current.
+6. Record a current terminal outcome—clean, findings, unavailable, timed out, or
+   failed—as the automatic attempt for the covered generation. Do not retry the
+   same unchanged generation after every later read-only prompt. Cancellation,
+   supersession, or a stale completion does not consume the generation; a newer
+   attributable mutation always becomes eligible.
+
+No interval, filesystem watcher, long-lived jscpd server, or process starts from
+the extension factory.
+
+### A new run during a background check
+
+A new accepted prompt or agent run supersedes an automatic check. Abort its
+owned signal, leave that generation unattempted, and discard any late completion.
+Cancellation should be requested before the new run can mutate files; cleanup
+may finish through the serialized adapter without blocking the prompt.
+
+Explicit `/jscpd` and `jscpd_run` operations also take priority over automatic
+work. They may cancel the automatic owner and then use the same serialized
+adapter. The automatic scheduler must never create a second process owner.
+
+### Queued steering and follow-ups
+
+Do nothing at intermediate `agent_end` events. Pi drains automatic retries,
+automatic compaction retries, steering, and follow-up messages before
+`agent_settled`, so all attributable mutations from that logical run coalesce
+into the same latest dirty generation. Follow-up delivery mode does not create
+an extra checkpoint between queued tasks.
+
+### Reload, session replacement, branch navigation, and shutdown
+
+- On reload, new, resume, or fork shutdown: close the scheduler first, abort its
+  owned check, invalidate queued work, and await existing adapter cleanup. The
+  replacement runtime restores only its active-branch state and creates a new
+  scheduler generation.
+- On `/tree` navigation: invalidate automatic work before restoring the target
+  branch. A completion from the abandoned branch must never update or
+  acknowledge the target branch.
+- On quit: cancel and clean up only. Never start a final scan from
+  `session_shutdown`.
+- Shutdown remains idempotent and bounded by the existing child-process
+  termination and cleanup model.
+
+## Context and presentation policy
+
+A clean automatic check must not call `pi.sendMessage()` and must not append a
+message entry. It may update bounded internal session state and terminal status,
+which stay outside model context.
+
+A failed automatic check is also quiet by default. `/jscpd status` remains the
+place to inspect bounded failure state; missing binaries stay dormant rather
+than producing one warning per settled run.
+
+For a new actionable finding, append one bounded custom finding message while
+Pi is still idle with `triggerTurn: false`. Pi persists that message and includes
+it in the next model context without starting a surprise LLM turn. It may also
+be displayed immediately by supported UI modes. Before appending, recheck the
+runtime, branch, mutation generation, and idle state; otherwise discard the
+completion and keep the generation dirty.
+
+Automatic acknowledgement must happen only after that durable finding message
+is successfully appended. The explicit changed executor's current
+"acknowledge on presentation" side effect therefore must not be reused blindly
+by a background scheduler. Omitted findings remain unacknowledged.
+
+## Rejected alternatives
+
+### Scan on every successful write/edit result
+
+This has the best proximity to a mutation but the worst multiplicity. Parallel
+or rapid tool batches can request overlapping scans while the agent is still
+working, and the result can become stale before it is presented.
+
+### Scan at every turn end
+
+A tool-using response can have many turns. Waiting in `turn_end` adds scan
+latency directly between model turns; detaching the work introduces races with
+the next tool batch. Dirty coalescing does not make an unsettled tree safe.
+
+### Scan at agent end
+
+`agent_end` is not a logical idle boundary. Pi may retry a provider error,
+compact and retry, or continue queued messages after it. Triggering there can
+scan intermediate source and duplicate work.
+
+### Scan before the next user prompt
+
+This sees the previous tree at rest but makes the user pay the full checkpoint
+latency before work starts, and no check occurs if the session ends. It remains
+a cancellation boundary, not the primary trigger.
+
+### Debounce timer after mutation
+
+A timer guesses idleness and must race streaming, queued messages, session
+replacement, and process cleanup. Pi already exposes the stronger settled
+signal, so an additional wall-clock debounce adds complexity without a better
+safety guarantee.
+
+### Scan during shutdown
+
+The result has no reliable advisory destination, can prolong exit, and opposes
+the invariant that shutdown only cancels and cleans owned work.
+
+## Implementation boundary
+
+M4.2 adds the bounded scheduler primitive: attributable mutations advance a
+generation, repeated automatic requests coalesce to one active plus one latest
+pending generation, explicit scans cancel only automatic ownership, deferred
+completions remain retryable, and reset or shutdown rejects stale work.
+
+M4.3 wires `agent_settled` to a detached automatic changed check. It reuses the
+configured capability, baseline, timeout, finding cap, changed-file set, and
+serialized adapter; cancellation or baseline-pending outcomes remain retryable,
+while other terminal failures are consumed once per unchanged generation.
+Lifecycle transitions cancel owned work and shutdown awaits bounded adapter
+cleanup. Automatic findings are deliberately not acknowledged or injected yet.
+
+M4.4 implements the presentation boundary. Automatic checks cap delivery at
+five findings, prioritize groups whose two locations changed in the session,
+and preserve deterministic size/location ordering within that priority. Clean
+and failed outcomes update only bounded session/footer status. A current
+finding result sends one custom message with `triggerTurn: false`, then commits
+only the delivered acknowledgement identities; omitted findings remain
+eligible. Non-TUI mode uses the same model-context message with transcript
+display disabled. Delivery failure, queued work, a newer mutation, or a stale
+lifecycle scope leaves the generation retryable without acknowledging it.
+
+M7.5 replaces the scheduler's mutable Promise/microtask owner with scoped Effect
+fibers, composes automatic checks directly through the scheduler's native Effect
+path, and moves acknowledgement staging plus Pi delivery ordering to Effect. M7.7
+supplies the managed host runtime, and M7.8 removes obsolete facade paths. See
+[Effect architecture and conformance](effect-architecture.md).
+
+Focused tests cover coalescing, scheduler freshness, clean and failure status,
+bounded finding delivery, repeated-finding suppression, non-TUI behavior,
+scoped interruption, and acknowledgement-after-delivery ordering.
+
+M6 must pin a Pi compatibility range that includes the documented
+`agent_settled` contract. If that contract is unavailable or changes, remain
+on-demand and revisit this decision; do not silently fall back to `agent_end`.
+
+The lifecycle decision adds no separate configuration and does not change the
+public command/tool contract.

package/docs/compatibility.md

@@ -0,0 +1,119 @@
+# Compatibility policy
+
+`pi-jscpd` deliberately has a narrow, tested host contract. The package uses
+Pi's extension, event, tool, custom-message, and TUI APIs directly, so an open
+peer range would imply compatibility that has not been verified.
+
+## Package identity and ownership
+
+The canonical package name is **`pi-jscpd`**. The source and package metadata are
+owned and maintained by [Revaz Zakalashvili](https://github.com/revazi) at
+[`revazi/pi-jscpd`](https://github.com/revazi/pi-jscpd). A public npm lookup
+returned no existing package when this name was selected, but a lookup does not
+reserve a name.
+
+The first supported release is `0.1.0`. The completed runtime design is
+documented in [Effect architecture and conformance](effect-architecture.md).
+The manual readiness workflow has no publication permission or credentials;
+tagged publication is handled separately by the protected release workflow. The
+source and package are MIT licensed; see the [release policy](release.md).
+
+## Supported and tested matrix
+
+| Component | Supported range | Tested fixture | Notes |
+| --- | --- | --- | --- |
+| Node.js | `>=22.19.0 <23 || >=24 <25` | `22.19.0`, `24.12.0` | Node 22.19.0 is Pi 0.84.4's minimum; Node 24 is the second supported LTS line. |
+| `@earendil-works/pi-coding-agent` | `>=0.84.4 <0.85.0` | `0.84.4` | The supported 0.84 patch line only. |
+| `@earendil-works/pi-ai` | `>=0.84.4 <0.85.0` | `0.84.4` | Kept on the same tested Pi release line. |
+| `@earendil-works/pi-tui` | `>=0.84.4 <0.85.0` | `0.84.4` | Required by the interactive overlay. |
+| `typebox` | `>=1.3.7 <2` | `1.3.7` | Required by the agent-tool schema. |
+| `effect` | Exact `3.22.1` | `3.22.1` | Reviewed MIT runtime for scoped process/analyzer, bounded-filesystem, lifecycle domain-state, scheduling, automatic delivery, application workflows, and the single managed Pi runtime. |
+| `jscpd` | Compatible v5 | `5.1.2` | Exact runtime dependency and fallback analyzer. |
+
+Effect `3.22.1` was the npm registry's current stable 3.x release when foundation
+issue [#64](https://github.com/revazi/pi-jscpd/issues/64) selected it. Installed
+package metadata confirms its MIT license, and the lockfile preserves the
+reviewed registry integrity. See
+[Effect architecture and conformance](effect-architecture.md) for dependency,
+service/error, resource, and runtime-boundary policy. No open range or automatic upgrade is implied.
+
+The Pi and TypeBox packages remain peer dependencies so the extension uses the
+host Pi installation instead of bundling a second runtime. Development
+dependencies pin the exact tested fixtures. Effect and jscpd are normal, exact
+runtime dependencies; installing `pi-jscpd` provides the reviewed composition
+foundation and analyzer without a later network request.
+`npm run compatibility:check` verifies the active Node version, peer ranges,
+aligned Pi fixture versions, installed fixture versions, locked Effect metadata
+and integrity, and the pinned jscpd runtime before type checking and tests.
+
+The supported ranges cover the Node 22 and 24 LTS lines, not the intervening
+non-LTS Node 23 line. They are a contract, not a claim that every patch
+combination was run separately. The minimum Node release and the current Node 24 fixture receive
+the full project check; Pi 0.84.4 is the API fixture. A future Pi `0.85` release,
+Node 25 release, or TypeBox 2 release requires an explicit compatibility review
+and range update rather than being accepted automatically.
+
+## Packed-artifact certification
+
+`npm run pack:certify` tests the artifact that would be published, not the source
+checkout alone. Its disposable install resolves the exact declared jscpd version
+through npm just as a user installation would; runtime checks remain offline. It:
+
+- compares `npm pack --json` output with the complete tracked runtime, license,
+  and public-document allowlist, including regular-file modes and unsafe/private
+  path rejection;
+- installs that exact tarball with lifecycle scripts disabled in a restrictive
+  disposable location and verifies exact, importable Effect `3.22.1` plus jscpd
+  `5.1.2` dependencies;
+- uses the locked Pi `0.84.4` CLI with isolated home, agent, session, and
+  temporary directories and only the explicit installed package enabled;
+- verifies that Pi discovers exactly one packaged `/skill:jscpd`, then verifies
+  `/jscpd` discovery and provider-free help/status behavior through RPC,
+  exercises the registered `jscpd_run` contract, Effect-owned analyzer resources,
+  and installed overlay component, proves the installed artifact resolves and
+  probes bundled jscpd `5.1.2`, and
+  checks JSON, print, and non-TUI fallback paths; and
+- separately places a deterministic fake jscpd v5 executable on the disposable
+  `PATH`, then stops Pi during an active scan and asserts that the process tree
+  and every `pi-jscpd-*` report directory are gone.
+
+The generated probe and fake executable remain certification fixtures for
+controlled output and process-tree behavior; the bundled capability check runs
+the real pinned jscpd release. CI runs this certification on both supported Node
+fixtures. The certification script itself is development tooling and is
+deliberately excluded from the publishable file allowlist.
+
+## Unsupported-version behavior
+
+- npm uses `engines.node` and peer dependency ranges during installation. Based
+  on the user's npm configuration, an unsupported Node or peer version may
+  produce a warning or reject dependency resolution.
+- The extension does not add a second runtime version detector or compatibility
+  shim. A forced install outside the declared ranges is unsupported and may fail
+  to load if Pi's API or Node's runtime behavior changed.
+- Once the extension loads on a supported host, its ordinary operational errors
+  remain advisory and fail open. That runtime policy does not turn an
+  unsupported host into a supported one.
+- The adapter first checks compatible project-local and `PATH` installations,
+  then falls back to the package-owned jscpd `5.1.2` dependency. A missing or
+  damaged bundled dependency is reported without breaking the Pi session; the
+  extension never invokes `npx` or downloads an analyzer at runtime.
+
+## Updating compatibility
+
+A support-range or Effect-runtime change must:
+
+1. update `engines`, peer ranges, exact development fixtures, and the exact
+   reviewed Effect dependency as applicable;
+2. run `npm install` so the lockfile records those fixtures;
+3. pass `npm run check` at the minimum supported Node version and the current
+   supported Node LTS fixture;
+4. run `npm run pack:certify` to smoke-test the exact tarball, extension loading,
+   representative command/tool/UI behavior, and shutdown cleanup with the
+   candidate Pi version; and
+5. update this matrix, Effect architecture checks, and release notes; and
+6. run the non-publishing `npm run release:check` gate documented in
+   [the release policy](release.md).
+
+Do not widen peer ranges solely because installation succeeds. Pi lifecycle and
+TUI behavior must be exercised before a new release line is declared supported.

package/docs/effect-architecture.md

@@ -0,0 +1,128 @@
+# Effect architecture and conformance
+
+Status: **implemented and recertified for the first public release**
+
+`pi-jscpd` uses Effect 3.22.1 for fallible asynchronous work, resource ownership,
+cancellation, concurrency, and shared service workflows. jscpd remains the source
+of truth for clone detection, while deterministic parsing, normalization,
+comparison, registry data, and presentation remain plain TypeScript.
+
+This document describes the final architecture. Migration issue history belongs
+in Git and the local maintainer roadmap rather than the published package.
+
+## Runtime topology
+
+Each extension instance owns exactly one `ManagedRuntime` created in
+`src/effect/runtime-boundary.ts`. Its production layer graph supplies:
+
+- `JscpdProcess` for shell-free bounded child-process execution;
+- `JscpdFileSystem` for canonical paths, metadata, bounded reads/writes,
+  restrictive temporary directories, and cleanup; and
+- `JscpdClock` for timeouts and scheduling.
+
+Pi tool, slash-command, lifecycle, and overlay adapters execute native programs
+through that runtime. Infrastructure, domain, and application modules never call
+`Effect.run*` or create independent runtimes. Isolated test execution lives under
+`test/support/`.
+
+Promise workflow orchestration is intentionally limited to three reviewed files:
+
+- `src/extension.ts` — imperative Pi callbacks and tracked shutdown coordination;
+- `src/overlay.ts` — the callback-driven TUI adapter; and
+- `src/effect/filesystem.ts` — Node filesystem promises wrapped by typed effects
+  and bracketed handle ownership.
+
+The AST architecture gate enforces these boundaries and rejects Promise service
+contracts, nested Effect runners, unmanaged timers, and direct filesystem access
+from migrated modules.
+
+## Services and layers
+
+Infrastructure services own effects and resources:
+
+- analyzer resolution and capability probing;
+- bounded process-tree execution;
+- report workspace creation, reading, and removal;
+- filesystem/configuration access;
+- lifecycle cancellation and time; and
+- narrow Pi persistence/delivery callbacks.
+
+Domain owners maintain one bounded state implementation each:
+
+- baseline generation and deferred completion;
+- changed-file project generation and canonical file set;
+- acknowledgement branch scope and revision;
+- verification checkpoints;
+- session mode and last-check status; and
+- Fallow coexistence policy and notice state.
+
+Application programs compose scan, changed comparison, status/session controls,
+automatic checkpoints, scheduling, and refactor verification. Service effects
+retain their process/filesystem requirements until the host runtime supplies the
+production layers.
+
+## Resource and cancellation ownership
+
+Every analyzer child is acquired and finalized by `JscpdProcess`. Execution uses
+argument arrays with `shell: false`, bounds combined output and time, propagates
+interruption, sends TERM before bounded KILL escalation, checks remaining process
+roots, destroys abandoned streams, and detaches listeners.
+
+Each analyzer run is serialized by an Effect semaphore. It creates a mode-0700
+workspace outside the project, supplies one fixed report path, reads only a
+bounded regular non-symlink artifact, consumes the report before cleanup, and
+removes the workspace on success, failure, timeout, cancellation, invalidation,
+or disposal. Cleanup uncertainty overrides an otherwise valid result.
+
+Bounded file reads use `acquireUseRelease`. Acquisition is bracketed, an in-flight
+read settles before the handle closes, and a handle acquired after interruption
+is closed without starting the read. Typed filesystem and size failures map to
+bounded report/configuration outcomes.
+
+Automatic checks run as scoped scheduler fibers. The scheduler owns one active
+and one latest pending generation, coalesces through `JscpdClock`, interrupts only
+its own automatic work when explicit scans take priority, and leaves interrupted,
+stale, or deferred generations retryable. Task construction and result delivery
+are suspended inside failure/finalizer boundaries so defects cannot strand active
+ownership.
+
+Quiet baseline capture is host-launched but explicitly tracked. Branch changes
+invalidate and await prior baseline settlement before replacement work starts;
+shutdown awaits baseline finalizers before disposing scheduler, capability,
+analyzer, and runtime resources. Shutdown is idempotent.
+
+## Failure and privacy contract
+
+Expected operational failures use tagged Effect errors for analyzer, process,
+filesystem, cancellation, timeout, limits, invalid input, stale work, workspace,
+persistence, and delivery conditions. Application and host boundaries translate
+them to the existing bounded fail-open result unions.
+
+Unexpected defects are contained only at reviewed outer workflow/host boundaries.
+Public output never includes raw exceptions, child output, environment values,
+source fragments, internal fingerprints, or temporary paths. Interruption remains
+distinct from ordinary failure so resource finalizers run and stale work cannot
+commit state.
+
+Automatic delivery rechecks generation, branch, idle state, and pending messages;
+appends findings with `triggerTurn: false`; commits acknowledgements only after
+successful delivery; and treats persistence/footer failures as advisory. Clean
+and failed automatic checks stay out of model context.
+
+## Conformance evidence
+
+The final non-publishing gate passes on Node 22.19.0 and 24.12.0 with the pinned
+Pi 0.84.4, TypeBox 1.3.7, Effect 3.22.1, and jscpd 5.1.2 fixtures. Evidence covers:
+
+- strict TypeScript and Biome checks;
+- architecture, documentation-link, and repository-hygiene gates;
+- more than 400 network-free tests, including cancellation and finalizer regressions;
+- Fallow dead-code, architecture, security, and full-audit checks;
+- a production dependency audit with no reported vulnerabilities; and
+- exact release tarball installation and runtime certification through RPC,
+  skill, tool, TUI-compatible, JSON, and print paths, package-owned jscpd probing,
+  active process-tree shutdown, and temporary-report cleanup.
+
+Certification proves only the reviewed source and artifact state. Versioning,
+tagging, and publication remain explicit maintainer decisions under the
+[release policy](release.md).

package/docs/fallow-coexistence.md

@@ -0,0 +1,120 @@
+# Fallow coexistence policy
+
+Status: implemented with Effect-owned policy evaluation
+
+Applies to: automatic `pi-jscpd` changed checks only
+
+Effect-owned policy evaluation uses the shared bounded filesystem service. These
+detection signals and coexistence outcomes remain product contracts and require a
+separate product decision to change.
+
+## Purpose
+
+Fallow and jscpd both detect duplication. When Pi Fallow or a project Fallow
+command already runs duplication analysis, two automatic warnings for the same
+change are noisy. `pi-jscpd` therefore detects only a small set of conservative
+signals and, on a high-confidence match, keeps its automatic changed checks on
+demand. Explicit `/jscpd` commands and `jscpd_run` remain available.
+
+No coexistence state disables Fallow, changes either analyzer's detection
+semantics, edits project configuration, or changes jscpd's own ignore and format
+policy.
+
+## Configuration
+
+`.pi/jscpd-guardrail.json` and its local override accept:
+
+```json
+{
+  "fallowCoexistence": "auto"
+}
+```
+
+- `auto` (default): apply conservative detection. A detected overlap suppresses
+  automatic jscpd changed checks and explains the choice once. Ambiguous or
+  absent evidence leaves automatic checks enabled.
+- `on-demand`: explicitly suppress automatic jscpd changed checks. Explicit
+  changed, project, and scoped scans remain available.
+- `allow`: explicitly allow both automatic analyzers, even when Fallow is
+  available.
+
+The normal trust-gated, strict, atomic extension configuration rules apply.
+
+## Supported signals
+
+Under `auto`, these are treated as high confidence:
+
+1. an active Pi tool named `fallow_run` together with project Fallow evidence
+   (a config file or `fallow`/`pi-fallow` dependency), because Pi Fallow's
+   default aggregate includes Fallow duplication;
+2. the first supported strict-JSON Fallow config (`.fallowrc` or
+   `.fallowrc.json`) contains a `duplicates` object whose `enabled` value is
+   `true` or omitted; or
+3. a direct `package.json` script command invokes `fallow`'s combined root,
+   `dupes`, `audit`, `all`, `check-changed`, or `review` command. Commands must
+   occur at a shell command-segment boundary; prose such as
+   `echo fallow dupes` is not accepted.
+
+A readable `duplicates.enabled: false` is authoritative for detection and keeps
+automatic jscpd checks enabled, even when the Fallow tool or script is present.
+This only observes Fallow's setting; it does not alter it.
+
+The following evidence is deliberately ambiguous and never suppresses an
+automatic check:
+
+- an active `fallow_run` tool with no project Fallow evidence;
+- a `fallow` or `pi-fallow` package dependency without an active tool or direct
+  duplication command;
+- a Fallow config with no `duplicates` section and no active Pi Fallow tool;
+- JSONC or TOML Fallow configuration, which this adapter does not partially
+  parse;
+- malformed, oversized, unreadable, non-regular, or out-of-project signal
+  files; and
+- an untrusted project, because project-use evidence is not inspected.
+
+Signal reads are trust-gated, no-follow, project-contained, and capped at 64
+KiB. Only fixed signal identifiers enter status; file contents and absolute
+paths do not.
+
+## User-visible behavior
+
+A detected automatic overlap emits one informational notice per Pi session:
+
+```text
+Fallow duplication analysis appears active. To avoid duplicate warnings,
+automatic jscpd changed checks are on demand; no configuration was changed.
+Use /jscpd changed or a scoped /jscpd scan <target>.
+```
+
+`/jscpd status` and the overlay report whether overlap is absent, ambiguous,
+detected/on-demand, or explicitly configured. Pending footer state says
+`jscpd: on demand (Fallow overlap)` instead of implying that an automatic check
+will run.
+
+The quiet pre-session jscpd baseline remains available so an explicit
+`/jscpd changed` request can still classify session deltas. Opening the overlay
+still performs status only. Automatic Fallow suppression does not acknowledge
+jscpd findings or consume scheduler generations.
+
+## Division of responsibility
+
+- **Fallow** is the broader JavaScript/TypeScript codebase analyzer: duplication,
+  dead code, complexity, architecture, security candidates, and related
+  evidence in one workflow.
+- **jscpd** remains the polyglot tokenization, clone-detection, format, and
+  duplication-statistics authority for `pi-jscpd`.
+- **pi-jscpd** adds Pi session attribution, changed-only comparisons,
+  acknowledgement, verification, and a jscpd-focused overlay. It is useful on
+  demand for polyglot or embedded-format coverage and for repositories whose
+  existing jscpd policy is authoritative.
+
+When both are desired, set `fallowCoexistence` to `allow`. Otherwise keep the
+default detected on-demand behavior and use scoped jscpd scans where its
+polyglot coverage adds value.
+
+## Known limitations
+
+Detection intentionally does not inspect arbitrary CI YAML, recursively resolve
+npm scripts, infer globally installed CLI binaries, parse shell expansions, or
+interpret JSONC/TOML. These omissions avoid false positives. Users can select
+`on-demand` or `allow` explicitly when unsupported project policy is known.