Fix publication blockers for v0.1.0 release candidate

[darko-mijic]

Summary

This PR resolves the remaining pre-publication blockers for @libar-dev/agent-harness-kit v0.1.0 release candidate. It fixes stale documentation links and wording, normalizes npm package metadata, moves build-time tooling out of production dependencies, hardens image-content-block handling with a shared helper and regression tests, and replaces the fragile upstream-doc mirror workflow with direct markdown sync from code.claude.com.

It also removes the ephemeral planning context file that was added during the API parity pass; planning artifacts should not be committed to the public repo.

Detailed Changes

Documentation Fixes

• CONTRIBUTING.md: Fixed broken architecture overview link to point to docs/README.md.
• CHANGELOG.md: Expanded [0.1.0] release notes with ### Added (image content block support) and additional ### Changed entries (bin paths, repository URL, publishConfig.access).
• CHANGELOG.md: Removed stale [1.0.0] release link pointing to the old claude-code-hooks repo.
• SECURITY.md: Softened pre-1.0 maturity wording to "release candidate" and fixed grammar.

Package Metadata Normalization

• Moved tsx from dependencies to devDependencies (it is only used for local script execution; published CLIs use #!/usr/bin/env node shebangs).
• Regenerated pnpm-lock.yaml importer metadata to match the tsx move.
• Added top-level "sideEffects": false for improved tree-shaking by consumers.
• Existing normalized fields remain unchanged: bin paths without ./, repository.url with git+ prefix.

Image Content Block Hardening

• Extracted duplicated imagePlaceholder logic into src/processing/image-placeholder.ts.
• New helper imports isRecord from src/utils/index.js and explicitly rejects arrays, returning the generic [Image] placeholder.
• Updated src/processing/denoiser.ts and src/processing/block-decomposition.ts to import the shared helper.
• Added regression tests covering image sources that are arrays, null, or primitives for both denoiseSession and extractBlocks paths.
• No base64 image data is leaked — only safe media_type metadata is used in placeholders.

Upstream Docs Sync Automation

• Added scripts/sync-upstream-docs.mjs and pnpm run docs:sync-upstream to fetch canonical markdown directly from https://code.claude.com/docs/en/*.md.
• Updated docs/upstream/README.md to document the new source of truth and the refresh command.
• Refreshed the mirrored upstream docs for hooks, settings, CLI, and headless/programmatic usage from the live .md endpoints.
• Eliminated the manual copy-paste path that had already produced malformed mirrors (headless.md duplicated CLI content and hooks-reference.md contained mixed page sections).

Code Cleanup + Slop Removal

• Removed obvious comments, dead code, and over-defensive guards across source, tests, and docs.
• Deleted the .omo/ work-tracking directory and docs/internal/prometheus-implementation-context.md.
• Added a ## Public Repository Hygiene guardrail to AGENTS.md so future agents know ephemeral planning artifacts must not be merged.
• Tightened docs wording while preserving commands, examples, and API facts.
• Locked new behavior with regression tests for Setup/MessageDisplay and the expanded output builder methods.
• All quality gates green: 1201 tests, type-check, lint, build.

Why This Is Needed

1. Broken contributor link: The architecture overview link in CONTRIBUTING.md pointed to a non-existent file.
2. Missing sideEffects: false: Consumers cannot safely tree-shake the package without this explicit marker.
3. tsx in production dependencies: Adds unnecessary install weight and implies runtime dependency on a TypeScript executor that is not used by published artifacts.
4. Duplicated image placeholder logic: Two divergent implementations existed (denoiser.ts accepted arrays; block-decomposition.ts rejected them). The shared helper normalizes behavior and adds regression coverage for malformed image sources.
5. Stale/misleading docs: SECURITY wording was too strong for a pre-1.0 package, and the CHANGELOG contained a dead link to the old repo.
6. Untrustworthy upstream mirrors: Manual copy-paste had already introduced malformed docs into docs/upstream/, which made API-gap assessment noisy and easy to get wrong.
7. Planning artifacts in public repo: The ephemeral context file and .omo/ directory were useful during implementation but must not be shipped in a public release.

Comment Consistency Cleanup

After the initial cleanup pass, a plan was created to fix the inconsistent comment state it left behind. This branch now includes the final wave of that cleanup.

What changed

• Restored and expanded public API JSDoc in src/utils/index.ts for exported helpers:
  • toError — normalize an unknown value to an Error.
  • isRecord — type guard for non-null object records.
  • isProtectedFile — pattern-based protection check, with a security note that it is not a filesystem access-control boundary.
  • validateRequiredFields — required-field presence check, now with @returns void.
  • validateFilePath — path-traversal guard, now with @returns void.
  • sanitizeCommand — shell-metacharacter stripping, with an explicit note that it is not a full shell-injection sanitizer.
• Removed remaining banned filler words from source comments:
  • src/processing/tail.ts — "incremental" → "appended-block"; "automatically advanced" → "advances".
  • src/processing/types.ts — "incremental ingestion" → "ingestion of growing session files".
  • src/processing/discovery.ts — "supports filtering" → "filters".
  • src/lifecycle/stop-handler.ts — "TODO comments" → "TODO markers".
  • src/pre-tool-use/eslint-disable-blocker.ts — removed two "automatically" filler instances.

Verification

• Banned-phrase grep across src/ and tests/ returns only documented opt-outs:
  • src/cli/export-sessions.ts:219 — runtime CLI message string "incremental export".
  • src/processing/ordering.ts:7 — false-positive substring "re-exported from".
  • tests/tail.test.ts:1074,1390 — executable it() description strings containing "incremental".
• Final Verification Wave approvals:
  • F1. Plan Compliance Audit — APPROVE
  • F2. Code Quality Review — APPROVE
  • F3. Real Manual QA — APPROVE
  • F4. Scope Fidelity Check — APPROVE

Testing Performed

• pnpm run type-check — passes cleanly.
• pnpm run lint — passes.
• pnpm run lint:ci — passes.
• pnpm run test:run — 1201 tests passing, 0 failures.
• pnpm run build — produces correct dist/ structure.
• npm publish --dry-run --access public — passes.
• npm pack — produces clean tarball with required docs, dist/, and package.json; no src/, .DS_Store, or .omo/ leaks.
• pnpm run docs:sync-upstream — refreshes all mirrored upstream docs from canonical .md endpoints.
• pnpm run docs:sync-upstream -- settings — targeted sync works for a single mirrored page.
• pnpm run test:run -- tests/docs-round-trip.test.ts — passes with the refreshed mirrors.

Verification Checklist

• CONTRIBUTING.md architecture link points to existing docs/README.md
• CHANGELOG.md [0.1.0] section has expanded Added/Changed release notes
• CHANGELOG.md no longer contains stale old-repo release link
• SECURITY.md uses grammatically correct "release candidate" wording
• package.json contains "sideEffects": false
• tsx moved to devDependencies; lockfile regenerated
• pnpm install --frozen-lockfile succeeds
• Shared image-placeholder.ts helper exists and is used by both processing callers
• Image block regression tests cover array, null, and primitive sources
• No base64 image data leaked in placeholders
• Full test suite passes: 1201 tests
• npm publish --dry-run passes
• npm pack contents verified clean
• pnpm run docs:sync-upstream refreshes upstream mirrors from code.claude.com markdown endpoints
• docs/upstream/headless.md is no longer a duplicate of CLI reference content
• docs/upstream/hooks-reference.md is a clean hooks-reference mirror again
• tests/docs-round-trip.test.ts now uses content-based skip classification instead of brittle block indices
• Ephemeral planning artifacts removed (.omo/, docs/internal/prometheus-implementation-context.md)
• AGENTS.md includes Public Repository Hygiene guardrail
• Public API JSDoc restored and expanded in src/utils/index.ts
• Banned filler words removed from source comments

Breaking Changes

None. All changes are additive, metadata normalization, automation, or internal refactoring.

Claude Code Hook API Parity

This branch also closes the gap between the library and the current upstream Claude Code hook API surface (source of truth: docs/upstream/hooks-reference.md).

Added hook events

• Setup — modeled as a full hook event with SetupInput/SetupOutput, Zod schemas, type guards, validators, HookOutputBuilder.setupContext(), and a reference lifecycle handler (src/lifecycle/setup.ts).
• MessageDisplay — modeled with MessageDisplayInput/MessageDisplayOutput, UUID-aware schemas, type guards, validators, HookOutputBuilder.messageDisplayContent(), and a reference lifecycle handler (src/lifecycle/message-display.ts).

Expanded existing events

• SessionStart:
  • Input: model is now optional; added session_title.
  • Output: hookSpecificOutput now supports additionalContext, initialUserMessage, sessionTitle, watchPaths, and reloadSkills.
• Notification: enum widened to all 6 upstream notification types.
• StopFailure: enum widened to all 10 upstream stop-failure reasons.
• PostToolUse / PostToolUseFailure: added optional duration_ms to both inputs.
• PostToolUse output: added updatedToolOutput and widened updatedMCPToolOutput to unknown.
• Common base fields: effort on BaseHookInput, terminalSequence on BaseHookOutput.
• CommandHookHandler: added optional args?: string[] for the exec-form command surface.

Reference handlers and tooling

• New pnpm run hook:test:setup and pnpm run hook:test:message-display scripts.
• Lifecycle smoke tests for Setup and MessageDisplay handlers.
• Updated src/lifecycle/session-start.ts to tolerate a missing model and src/lifecycle/notification-handler.ts to classify new notification types.

Docs and metadata

• README/CLAUDE.md/package.json/docs references updated from 28 to 30 hook events.
• CHANGELOG.md entry added for the API parity changes.
• New test factories createSetupInput and createMessageDisplayInput in tests/test-utils.ts.

Verification

• pnpm run test:run — 1201 tests passing, 0 failures.
• pnpm run check — type-check + lint pass.
• pnpm run hook:test:setup — exits 0.
• pnpm run hook:test:message-display — exits 0.
• CLAUDE_PROJECT_DIR=/Users/darkomijic/dev-projects/claude-code-hooks pnpm run hook:test:session — exits 0.
• Scope enforcement checks pass: no new .passthrough(), no new any, package.json version unchanged, docs/upstream/ untouched, no public exports removed.

v0.2.0 endpoint discovery and silent hook forwarding

This PR now also provides the generic runtime seam used by Cockpit to replace brittle direct HTTP hook configuration.

What changed

• Bumps @libar-dev/agent-harness-kit to 0.2.0.
• Adds the versioned HookEndpointFile schema plus safe file reading, PID liveness, project-root containment, and hook URL helpers.
• Adds a standalone command-hook forwarder that reads stdin JSON, validates endpoint discovery, filters unrelated project roots, posts to loopback, relays only non-empty JSON decisions, and always exits 0 silently on every opt-out/failure path.
• Adds the managed POSIX wrapper asset for consumers to install at a stable path.
• Bundles the forwarder with esbuild into dist/standalone/hook-forwarder.mjs with Zod inlined and no runtime dependency lookup.
• Exposes endpoint-discovery and forwarder package subpaths, including a default resolver condition needed by packaged CommonJS consumers.
• Improves ExitPlanMode summaries to use the first Markdown heading from input.plan.

Additional validation

• pnpm run test:run — 30 files and 1258 tests passing, with type errors enabled
• pnpm run type-check
• pnpm run lint
• pnpm run build
• Forwarder subprocess tests cover decision relay plus missing file, dead PID, unmatched cwd, ECONNREFUSED, non-200, timeout, garbage stdin, and empty decision opt-outs
• Schema, path-boundary, Windows casing, export-map, and ExitPlanMode summary tests
• The final git tarball install was exercised by Cockpit and passed the consumer's macOS packaged smoke

Review feedback follow-up (2026-07-12)

The post-implementation review findings are now addressed in commit c3ee44817c555b748358f940fae8246fb3f6d3f5.

Additional hardening

• The standalone forwarder canonicalizes an existing hook-event cwd with realpath() before project-root filtering, while retaining the lexical fallback for missing or synthetic paths. This preserves silent forwarding when Claude Code and Cockpit reach the same project through different symlink paths.
• The forwarder subprocess suite now builds a fresh esbuild bundle and runs every scenario through the generated hook-forwarder.mjs, rather than executing the TypeScript source through tsx.
• The malformed-stdin regression therefore pins the actual shipped invariant: bundled artifact exit code 0, empty stdout, and empty stderr.
• A symlinked-cwd integration case verifies decision relay against a canonical published project root.
• The changelog records both review-driven fixes.

Final validation

• pnpm test:run — 30 files, 1,260 tests passing, 0 failures, type errors enabled
• pnpm type-check — passes
• pnpm lint / uncached ESLint — passes
• pnpm build — produces the 511.5 KiB standalone forwarder bundle
• Cockpit installed the final GitHub tarball pin and verified that dist/standalone/hook-forwarder.mjs contains the canonical-cwd logic
• Cockpit’s x64/arm64 packaging and packaged smoke both passed with this exact pin

The consumer pin is now c3ee44817c555b748358f940fae8246fb3f6d3f5.

Complete-session transcript tailing (Wave 1B)

This section records the session-level processing API added at branch head a7500f5b21bd415bcdbbf39f93293367533fb858.

Why this was needed

Existing raw-tail APIs accept one JSONL path. Claude Code stores subagent activity under <session-id>/subagents/*.jsonl, leaving every consumer to rediscover that layout, coordinate offsets, and merge sources. A privacy-safe Cockpit audit found 55,050 subagent records—about 52% of its corpus—outside the current main-file ingestion path.

Public API

Exported from @libar-dev/agent-harness-kit/processing:

• tailRawTranscriptSessionRecords(mainJsonlPath, options)
• watchRawTranscriptSessionRecords(mainJsonlPath, options)
• commitRawTranscriptSessionCheckpoint(mainJsonlPath, checkpoint, options)
• getRawTranscriptSessionMarkerPath(mainJsonlPath, markerDir, allowedMarkerRoots)

Results contain merged records, per-source diagnostics/rotation state, aggregate parse counts, and a serializable checkpoint. Existing single-file functions, markers, readRawSessionFiles, exports, and safe-redaction defaults remain compatible.

Ordering and provenance guarantees

• Rediscovers main and subagent sources on every pass, including late-created subagents.
• Preserves sourceKind, sourceId, byte ranges, payloads, and stable record IDs.
• Tracks offsets and generations independently per source.
• Uses the source's preceding timestamp only as an internal effective merge key; returned timestamps are not rewritten.
• Preserves file-local auxiliary-record position across incremental boundaries and cold restarts.
• Deterministic ties use effective timestamp, main before subagent, source ID, byte range, and stable ID.

Durable checkpoint and concurrency guarantees

Manual mode provides a persist-then-commit workflow: tail with checkpointMode: "manual", durably upsert by stable ID, then commit the returned checkpoint.

Checkpoints are bound to a SHA-256 digest of the resolved main path and an exact marker revision. Per-source generations allow shorter-file rotation while rejecting same-generation backward offsets. The checkpoint source set is authoritative at its revision, allowing disappeared subagents to be removed safely.

Automatic and manual writers share a cross-process mutation boundary: atomic lock-directory acquisition; token/PID/time ownership; marker re-read and progression validation inside the lock; UUID temporary files and atomic rename; owner-token verification; bounded retry; and dead-process stale-lock recovery. Automatic stale losers may replay but cannot regress or skip offsets. Manual stale siblings reject.

Snapshot, migration, and containment hardening

• Cold scans read only the pre-read stat range, so concurrent appends cannot create invalid checkpoints; later/partial bytes remain for the next pass.
• Version 1 markers replay once with stable IDs and migrate to version 2 revision/generation state.
• Stale-lock tombstones use a deterministic SHA-256 of validated owner or safe stat identity; raw/corrupt tokens never enter a pathname.
• Owner parsing requires UUIDv4, positive safe PID, and bounded positive timestamp.
• Traversal tokens, nested paths, malformed owners, crashed processes, validation failures, and forced write failures have regression coverage.
• Existing marker-root allow-list validation remains in force.

Adversarial review history

Independent review reproduced and corrected: records moved to the session end; cross-project checkpoint reuse; rotation/source-removal deadlocks; stat/read races; TOCTOU revision races allowing sibling success and marker regression; temporary-file collisions; and stale-owner traversal escaping the marker root or making locks unrecoverable.

Final stress review ran 100 in-process sibling races, a real sibling-process race, concurrent automatic writers, and 40 malformed-owner reclaimer races. Exactly one checkpoint won each contested revision, with no displacement or offset regression. Final disposition: GO, no findings.

Validation

• Focused suites — 178 tests across 8 files passed.
• Full suite — 1,316 tests across 34 files passed.
• TypeScript, uncached ESLint, distribution build/prepack, and git diff --check — passed.
• Cockpit installed the GitHub tarball and passed root typecheck plus its complete 364-test suite against this commit.

Consumer migration and limitation

The smallest migration changes the existing call to tailRawTranscriptSessionRecords(mainJsonlPath, options); the returned .records shape remains consumable. Durable consumers should use manual checkpoint mode and commit only after stable-ID upserts succeed.

Replacement detection remains size-based: a replacement preserving or increasing file size between observations cannot be distinguished reliably. Locking assumes a local filesystem with atomic mkdir/rename and a shared local PID namespace.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[greptile-apps]

Your trial has ended. Reactivate Greptile to resume code reviews.

[greptile-apps]

Too many files changed for review. (106 files found, 100 file limit)

Bypass the limit by tagging @greptile-apps to review.