ptbk 0.117.0-0 → 0.118.0-1

package/README.md

@@ -1,29 +1,37 @@
 # Promptbook (`ptbk`)
 
-`ptbk` is the repository’s single npm package. It installs the `ptbk` CLI for local coding tasks, with interchangeable coding harnesses, project checks, Git persistence, and a persistent loopback dashboard.
+Promptbook operates readable agent and task Books over a Git project. This repository publishes one npm package, `ptbk`, which installs the `ptbk` command. Runtime state, requests, traces and the shared browser profile live in ignored `.ptbk/` files.
 
-Requires Node.js 22.13+ in the Node 22 line, or Node 24+, npm 10+, and Git. macOS and Linux are target platforms; use WSL on Windows. Install a coding harness separately and authenticate with its provider.
+Requires Node.js 22.13+ in the Node 22 line, or Node 24+, and npm 10+.
 
 ```bash
 # Global installation
 npm install --global ptbk
-ptbk init --path ./my-project
+ptbk init --path ./project
 
-# Or install into a project
+# Project-local installation
 npm install --save-dev ptbk
 npx ptbk init
-npx ptbk add "Fix CSV quoting and add a regression test"
-npx ptbk list
-npx ptbk run --harness openai-codex --dry-run
-npx ptbk run --harness openai-codex --check "npm run check"
 ```
 
-The coder owns task state and commits. Harnesses receive instructions to leave commits to the coder. Initial project changes are preserved; the default run refuses a dirty working tree. Pull and push require explicit flags. `list` and `run --dry-run` are offline read-only operations.
+Initialization creates missing core agents, task templates and project conventions, preserving customized files. It offers supported harness installation and interactive authentication. `--no-install` skips installation; `--no-questions` avoids terminal prompts. Configure a meaningful project `check` script and commit the initialized project before starting work.
 
-Current Codex account execution requires explicit `--allow-credits` because its CLI cannot enforce the default credit prohibition. Add that flag only when authorizing account credits; see [the credit policy and provider limits](docs/coder.md#harnesses-planning-and-team).
+```bash
+ptbk add "Implement the new behavior and its acceptance checks" --commit
+ptbk list
+ptbk run --dry-run
+ptbk start                     # background agenda, localhost dashboard, reboot persistence
+ptbk show                      # inspect the same process and pending requests
+ptbk answer REQUEST_ID "Reply"
+ptbk stop                      # intentional stop also disables automatic restart
+```
+
+`start` discovers available authenticated harnesses, uses Manager for missing assignments, and executes one task at a time. It requires reported outcome evidence and passing project checks before committing implementation, dated task completion and learning follow-ups together. It watches future work and materializes goal enquiries when no unfinished backlog remains. Failures retain work and expose recovery diagnostics.
+
+Use `start --raw` for foreground logs or `start --interactive` for terminal controls. `--no-persist`, `--no-server`, `--no-qr` and `--port` customize startup. `run` executes a finite queue with one configuration; for example `ptbk run --harness openai-codex --check "npm run check" --limit 1`. Harness availability, account policy and capability checks happen before inference; unsupported installed provider features produce an actionable diagnostic.
 
-New work is stored as task Books under `tasks/`. Existing top-level Markdown tasks under `prompts/` remain supported by the same engine. Agent Books under `agents/` define roles and are distinct from task Books.
+Global installation, local `npx ptbk`, or a project script such as `"ptbk": "ptbk"` work outside this repository. Each process loads its own installed runtime/version and pins that installation for restart. See [runtime usage](docs/runtime.md), [compatibility and verification](docs/compatibility.md), and [the specification](https://github.com/webgptorg/promptbook/blob/main/specs/_main.md).
 
-See [the coder guide](docs/coder.md), [compatibility and verification](docs/compatibility.md), `ptbk --help`, and [the specification](https://github.com/webgptorg/promptbook/blob/main/specs/_main.md). Run `npm run check` to verify the build, deterministic fixtures, and installation of the actual npm tarball in an external project.
+For development, use `npm ci` and `npm run check`. Checks validate types, deterministic integration fixtures and real tarball installations in disposable external projects. CI runs on Linux, macOS and Windows with Node 22 and 24.
 
-This prerelease replaces the old collection of npm packages. Publishing runs only in GitHub Actions when a `vVERSION` tag is pushed. From a clean, committed tree on a named branch, `npm run release:preminor` or `npm run release:prerelease` checks the release, creates npm's version commit/tag, and atomically pushes the branch and exact tag. Normal releases, including numeric prereleases, use `latest` so the default install gets the current CLI. See [release and push-retry instructions](docs/coder.md#releasing).
+For releases, run `npm version patch`, `npm version minor`, or `npm version prerelease` on a clean named branch after committing your work. Basic `preversion` checks run locally; `postversion` atomically pushes the version commit and exact `vVERSION` tag. GitHub Actions checks and publishes only `ptbk` with npm provenance, then verifies the public registry and installed CLI. Configure npm trusted publishing once as described in [releasing](docs/releasing.md).

package/bin/ptbk.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-/** Runs the compiled CLI from either a local or global npm installation. */
-import('../dist/coder/cli.js')
-    .then(async ({ main }) => { process.exitCode = await main(process.argv.slice(2)); })
-    .catch(error => { process.stderr.write(`${error.message}\n`); process.exitCode = 1; });
+
+/** Load the runtime relative to this installation, independently of the project directory. */
+import('../dist/cli.js').then(({ main }) => main()).catch((error) => {
+    process.stderr.write(`ptbk: ${error.message}\n`);
+    process.exitCode = 1;
+});

package/changelog/_current-preversion.md

@@ -1,57 +1,9 @@
--   Removed npm installation deprecation warnings by upgrading ESLint from 8 to 10 and refreshing the lockfile.
-    Migrated to flat configuration, preserving custom rules and file overrides, and installed the previously
-    missing TypeScript lint dependencies and runtime global definitions.
-    Updated the declared Node.js requirement to 22.13+ in the Node 22 line, or 24+.
--   Replaced the former multi-package publishing pipeline with the single `ptbk` CLI package,
-    versioned as a pre-minor prerelease. Added compiled executable packaging,
-    release/version validation, npm prerelease tags, version-tag-triggered GitHub publication,
-    macOS/Linux CI, external local/global installation checks, and post-publication registry
-    version, dist-tag, artifact integrity and executable verification. Node 22.13+ is required.
--   Restricted npm publication to the official repository's GitHub Actions release job.
-    Local npm version hooks check types, metadata, a named branch and clean tracked/untracked
-    tree, create the normal version commit/tag, and atomically push the current
-    branch and exact new tag to trigger CI. Failed pushes can be retried with
-    `npm run postversion`; local registry verification remains available without publishing.
--   Wait for npm registry propagation after a successful upload instead of failing on the
-    first temporary missing-version response. Keep verification bounded and reject invalid
-    artifact metadata and authentication failures immediately.
--   Restore `latest` as the npm channel for normal `ptbk` releases, including numeric
-    prereleases, so default local/global installs receive the current coder CLI instead
-    of the legacy package. Verify unversioned installs against the released version and
-    clarify npm's selected-version publication date versus package-wide last publication.
--   Implemented the coder task engine with legacy Markdown and task Books, strict scheduling,
-    recurrence, deterministic migration, project initialization and authoring, safe Git/check
-    phase persistence, recovery journals, harness adapters, agent context and TEAM tools,
-    read-only planning, human verification, and a protected loopback persistent dashboard.
-    Read-only previews report blocked/future tasks without initializing or calling models.
-    Restored legacy trace filenames while preserving immutable occurrence records and exact
-    finalization outcomes in journals. This prerelease refuses Qwen/Cline TEAM before inference;
-    they require an agent without TEAM. OpenCode TEAM requires an explicit qualified model.
--   Codex account inference now requires either an advertised provider credit-prohibition
-    capability or explicit `--allow-credits`. Current Codex versions without that capability
-    are refused before inference, including accounts with remaining included usage. Account
-    and API authentication are forced explicitly; generated scripts never opt into credits.
--   Reorganized the specifications around `specs/_main.md`, splitting coder contracts into focused,
-    interlinked files and expanding the dictionary into a linked term index. Preserved the dated
-    audit, acceptance IDs and lower-authority historical agent/server specs in `specs/deprecated/`,
-    repaired specification links, and left `old-prompts` and implementation code untouched.
--   Translated all organized specifications into English, including examples and cross-reference labels,
-    updated heading links, and simplified the dictionary to linked bullet points. The `old-prompts` archive
-    and implementation code remain unchanged.
--   Simplified prose-heavy specification tables into bullet points and a numbered delivery list,
-    retaining tables for compact state/harness comparisons, module ownership and reference resolution.
--   Defined Promptbook in the specifications solely as the `ptbk` CLI, replacing the nested coder
-    commands with top-level workflows, grouping the contracts under `specs/cli/`, and retaining
-    the broader APT framework/server vision as historical material. Preserved legacy identifiers
-    and source references for compatibility; implementation code and `old-prompts` are unchanged.
--   Restored the compiled TypeScript CLI after the implementation cleanup and moved every workflow
-    to the top-level `ptbk` commands, including initialization, execution, checks, planning,
-    migration, recovery and the persistent dashboard. Historical storage paths and task markers
-    retain their compatibility meaning. The removed `coder` command group now explains the replacement.
--   Initialization upgrades only exact recognized generated npm callers, supplies root-command
-    run/list/fix/plan scripts, and diagnoses custom legacy scripts/workflows without rewriting them.
-    Checks reject both root and historical worker invocations, including indirect npm-script recursion.
--   Release preflight now rejects dirty/detached checkouts before doing other work and verifies the
-    compiled build before npm changes the version. CI checks all branches on macOS/Linux and Node 22/24;
-    publication remains restricted to the single `ptbk` package through GitHub Actions. Updated the
-    packed local/global installation regressions and documentation to exercise root commands.
+- Implement the complete `ptbk` runtime from the current specification, including modern task Books and legacy Markdown, normalized agent discovery and inheritance, core roles, Manager assignment, Expert agenda bootstrap, TEAM consultations and OPEN/CLOSED Teacher follow-ups.
+- Add finite checked execution and continuous project supervision with one task at a time, dated completion and implementation in one result commit, bounded retries, safe staging, recovery journals, synchronization and isolated worktree integration.
+- Add project-specific daemon/raw/interactive modes, authenticated shared CLI/terminal/dashboard/API controls, durable questions and answers, browser CDP tools with persistent sessions, and current-user startup persistence for Linux, macOS and Windows.
+- Preserve custom initialization files and routing requirements, schedule prerequisites and recurrence, and materialize bounded goal enquiries only when unfinished present/future work is exhausted.
+- Publish only the installable root `ptbk` npm package. Add local npm version preflight and atomic branch/tag push, tagged GitHub Actions publication with OIDC/provenance, and bounded public registry/default installation verification.
+- Validate Node 22/24 installations on Linux/macOS/Windows, deterministic provider and recovery fixtures, real local browser sessions where available, and checked task execution from local/global tarball installations in disposable external projects.
+- Fix Windows runtime state/browser startup sharing violations, process cancellation, secret-redaction scope, portable trace/learning paths and isolation recovery across Git checkout line-ending filters.
+- Make integration fixtures independent of host path separators and Git line-ending defaults, with bounded completion waits that tolerate hosted-runner load and surface runtime failures immediately.
+- Keep all platform checks running after a matrix failure, bound concurrent fixture processes, and document releasing code fixes under a new immutable version tag.

package/dist/cli.d.ts

@@ -0,0 +1,4 @@
+/** Return the selected installation's package version, independently of project metadata. @private */
+export declare function installedVersion(): Promise<string>;
+/** Run the installed root command and preserve its documented exit status. @private */
+export declare function main(args?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { main as runCli } from './coder/cli.js';
+/** Return the selected installation's package version, independently of project metadata. @private */
+export async function installedVersion() {
+    return JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8')).version;
+}
+/** Run the installed root command and preserve its documented exit status. @private */
+export async function main(args = process.argv.slice(2)) {
+    process.exitCode = await runCli(args);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,IAAI,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAEhD,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,gBAAgB;IAClC,OAAQ,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC,OAAO,CAAC;AAC5H,CAAC;AAED,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;AAC1C,CAAC"}

package/dist/coder/agents.d.ts

@@ -3,18 +3,56 @@ export interface TeamMember {
     name: string;
     path: string;
     declaringPath: string;
+    kind?: 'agent' | 'expert' | 'user' | 'void';
+}
+/** Learning permission belongs to the local Book, independently of its ancestors. @private */
+export interface LearningPolicy {
+    open: boolean;
+    limits?: string;
+}
+/** A discovered project identity, including hidden supporting definitions. @private */
+export interface AgentDefinition {
+    name: string;
+    normalizedName: string;
+    path: string;
+    hidden: boolean;
+    learning: LearningPolicy;
 }
 /** Immutable Book snapshot used for one inference attempt. @private */
 export interface PreparedAgent {
+    name: string;
+    path: string;
     instructions: string;
     aliases: string[];
     team: TeamMember[];
+    learning: LearningPolicy;
+    sources: Record<string, string>;
     model?: string;
     modelParameters?: Record<string, string>;
 }
+/** Missing core definitions are created from these installed-engine defaults only. @private */
+export declare const CORE_BOOKS: Readonly<Record<string, string>>;
+/** Normalize identity across case, diacritics, separators and camel case. @private */
+export declare function normalizeAgentName(name: string): string;
+/** Resolve engine-owned identities without consulting or materializing project files. @private */
+export declare function nonAgentReference(reference: string): {
+    name: string;
+    path: string;
+    kind: 'expert' | 'user' | 'void';
+} | undefined;
 /** Resolve a local file without allowing a symlink to escape the selected project. @private */
 export declare function agentLocalPath(path: string, projectPath: string): Promise<string>;
 /** Recognize public-network exclusions, including IPv4-mapped IPv6 literals. @private */
 export declare function isPrivateBookAddress(address: string): boolean;
-/** Compile persona, local/remote inheritance, knowledge and distinct advisor tools. @private */
+/** Discover canonical identities recursively, rejecting every ambiguity before selection. @private */
+export declare function discoverAgents(projectPath: string): Promise<AgentDefinition[]>;
+/** Repair missing core definitions individually; existing custom Books are never overwritten. @private */
+export declare function ensureCoreAgents(projectPath: string): Promise<string[]>;
+/** Resolve a shared identity from its declaring Book; filenames never override name uniqueness. @private */
+export declare function resolveAgentReference(raw: string, declaring: string, projectPath: string): Promise<string>;
+/** Resolve an inherited local MODEL without network, knowledge reads, setup or advisor calls. @private */
+export declare function readLocalAgentModel(agentPath: string, projectPath: string): Promise<string | undefined>;
+/** Compile immutable instruction provenance, inheritance, knowledge and distinct TEAM tools. @private */
 export declare function prepareAgent(agentPath: string, projectPath: string): Promise<PreparedAgent>;
+/** Validate every effective local Book before unattended execution, including hidden supporting roles. @private */
+export declare function validateAgents(projectPath: string): Promise<PreparedAgent[]>;