iit-mcp-autotask 0.38.4 → 0.38.6

package/.env.example

@@ -77,7 +77,7 @@ AUTOTASK_PROFILE=readonly
 # fixed offsets (+10:00, Etc/GMT-10) and names without a region (EST, Japan) are refused. An invalid name
 # fails boot. Time entries stay calendar days (YYYY-MM-DD), not UTC bounds.
 # AUTOTASK_USER_TIMEZONE=Australia/Sydney
-# Removed in 0.6.0 (boot fails if set): AUTOTASK_READ_ONLY, AUTOTASK_WRITE_POLICY, AUTOTASK_WRITE_ALLOW,
+# Removed in 0.6.0 (ignored with a boot warning, not honoured): AUTOTASK_READ_ONLY, AUTOTASK_WRITE_POLICY, AUTOTASK_WRITE_ALLOW,
 # AUTOTASK_SECRET_READS. authenticate.* (a credential-minting read) is always refused.
 
 # --- Per-tenant read cache (in-process; never cross-tenant; never on disk) ---

package/README.md

@@ -8,20 +8,11 @@ context into one call, a generic read layer for the long tail, one result envelo
 packaged playbooks, strong security boundaries, and predictable per-tenant in-process state (pooled
 client + SDK-owned TTL caches).
 
-> **Package status (2026-10-29):** the runtime dependency `node-autotask` is published to public npm
-> at `0.39.1`; the committed `pnpm-lock.yaml` pins that
-> release with its integrity hash, so installs resolve deterministically. The dependency is always npm
-> (node-autotask pinned exactly at `0.39.1`) — never a `file:`, `git:`, `link:` or workspace reference
-> to a local checkout.
-
-> **0.6.0 is a breaking release** (unreleased): tool names, result shapes and configuration all
-> changed. See [Migrating from 0.5.x](#migrating-from-05x) and the [CHANGELOG](CHANGELOG.md).
-
 ## Tool surface
 
 The **core** toolset (10 tools) is always served; `AUTOTASK_TOOLSETS` adds `service`, `records` and
 `finance` (or `all`, 17 tools); the operator profile adds two. The whole tool surface (19 tools) is
-listed below. Every other operation in the SDK's 1,281-operation registry stays
+listed below. Every other operation in the SDK's operation registry stays
 reachable through the generic layer: `autotask_catalog` finds the key, `autotask_describe` serves
 its contract (slim by default: transport and retry detail dropped, long text cut, the first two
 examples; `full: true` serves the complete record, `summary: true` about 2 KB), `autotask_read` runs it.
@@ -147,8 +138,8 @@ fields on writes: [`docs/company-location-fields.md`](docs/company-location-fiel
 Every write and delete is refused on the read path (`autotask_read`) before any request
 (`POLICY_DENIED`, status `denied`), on every profile. `authenticate.*` returns a live vendor token
 (credential-minting) and is never served, on any profile, through any tool. The 0.5.x variables `AUTOTASK_READ_ONLY`, `AUTOTASK_WRITE_POLICY`,
-`AUTOTASK_WRITE_ALLOW` and `AUTOTASK_SECRET_READS` were removed: boot fails if one is set, naming
-its replacement.
+`AUTOTASK_WRITE_ALLOW` and `AUTOTASK_SECRET_READS` were removed: they are ignored (the server logs a
+warning naming any unrecognised `AUTOTASK_*` variable at boot), so the profile governs.
 
 ### Operator profile (writes)
 
@@ -451,55 +442,6 @@ or in `.mcp.json` / Claude Desktop config:
 **From a clone**: `pnpm i && pnpm build`, then point the client at
 `node /abs/path/iit-mcp-autotask/dist/main.js --transport stdio`.
 
-## Migrating from 0.5.x
-
-No aliases: old names fail as unknown tools.
-
-| 0.5.x | 0.6.0 |
-|-------|-------|
-| `catalog`, `describe {operation}`, `read {operation,args}`, `fetch_many`, `ticket_full_context`, `company_full_profile` | unchanged (core) |
-| `read_batch {items}` / `relationship_map {resource_key}` | `read {items}` / `describe {resource}` |
-| `resource_who_am_i`, `version`, `threshold_information` | `tenant_status {parts}` (`identity` + `impersonationResourceId`, `version`, `thresholds`, `server`, `time`) |
-| `resolve_any` | `resolve {identifier, resources?}` |
-| `search_across_resources {query,resources,limit}` | `resolve {identifier, match: "contains", resources, limit}` |
-| `company_` / `configurationItems_` / `contact_` / `project_` / `ticket_resolve` | `resolve {identifier, resource}` |
-| `ticket_find_by_ticket_number`, `configurationItems_find_by_serial`, `contact_find_by_email` | `resolve {identifier, resource, by: "ticket_number" \| "serial" \| "email"}` |
-| `ticket_` / `timeEntry_` / `serviceCall_` / `contract_` / `timeOffRequest_query` | `query {resource, filter, ...}` |
-| `ticket_sla_health_check`, `company_unbilled_work`, `contract_profitability`, `aggregate` | `read {operation: "tickets.slaHealthCheck" \| "companies.unbilledWork" \| "contracts.profitability" \| "operations.aggregate", args}` + `autotask_guide` |
-| `invoice_get {id}` / `invoice_markup {id, format}` | `invoice_get {id, format}` (finance) |
-| `quote_get`, `contact_full_profile`, `contract_full_profile`, `project_get_context`, `resource_workload` | same names (toolsets) |
-| `configurationItem_profile`, `serviceCall_full_profile` | `configuration_item_profile`, `service_call_full_profile` |
-| `write`, `delete`, `timeEntry_create` | `write {operation, args, idempotency_key?}` then `apply {plan}` (operator profile) |
-| env `READ_ONLY` / `WRITE_POLICY` / `WRITE_ALLOW` / `SECRET_READS` | `AUTOTASK_PROFILE` + `AUTOTASK_WRITE` + `AUTOTASK_STATE_DIR` + `AUTOTASK_RUN_SCOPE`; boot fails if an old variable is set |
-| CLI default stdio, bind on all interfaces | http on `127.0.0.1` by default; local clients pass `--transport stdio` |
-| results: per-tool shapes, errors as a text JSON payload | one envelope; the old payload is the envelope `data` |
-
-**Upgrading a 0.5.x deployment, step by step:**
-
-1. Remove `AUTOTASK_READ_ONLY`, `AUTOTASK_WRITE_POLICY`, `AUTOTASK_WRITE_ALLOW` and
-   `AUTOTASK_SECRET_READS` from the environment: 0.6.0 refuses to boot while one is set, and names
-   the replacement.
-2. Local (stdio) clients: add `--transport stdio` (or `MCP_TRANSPORT=stdio`). Without it 0.6.0
-   starts HTTP on `127.0.0.1:8080` and the client hangs on stdin.
-3. HTTP off loopback: set `AUTOTASK_HTTP_ALLOWED_HOSTS` and `AUTOTASK_HTTP_AUTH` (`gateway` or
-   `tokens`); a server-held credential on HTTP needs `tokens`.
-4. Read-only use needs nothing else. Pick toolsets with `AUTOTASK_TOOLSETS` if the agent used the
-   service, records or finance tools.
-5. Writes (the operator profile): set `AUTOTASK_WRITE` (see [docs/write-gate.md](docs/write-gate.md)) and `AUTOTASK_DEDUP` (a time entry needs `startDateTime` for its duplicate
-   check, Service tickets need `startDateTime` and `endDateTime`, and `billingCodeID` must be an active
-   general allocation code), create the state dir's parent, and set
-   `AUTOTASK_PROFILE=operator`, `AUTOTASK_WRITE`, `AUTOTASK_STATE_DIR` and a run scope
-   (`AUTOTASK_RUN_SCOPE` on stdio and in gateway mode, shared by every principal; `runScope` per token in tokens mode). The first boot creates the state
-   dir (0700), its key and its lock. There is nothing to migrate: 0.5.x kept no write state.
-6. Update agent prompts and playbooks to the new tool names (table above) and to the envelope's
-   `status`/`next`.
-
-**Rolling back to 0.5.x:** pin the package back to version 0.5.0, restore the 0.5.x variables you
-removed in step 1 (and drop the 0.6.0 ones: 0.5.x ignores them but nothing should depend on them),
-and remove `--transport stdio` only if your client never passed a transport (0.5.x defaulted to
-stdio). Keep the operator state dir: its `audit.jsonl` is the record of every write 0.6.0 made, and
-0.5.x neither reads nor touches it. Plans and the ledger are not portable to 0.5.x, which has no
-preview/apply path; a plan previewed under 0.6.0 cannot be applied after a rollback.
 
 ## Endpoints
 
@@ -694,7 +636,7 @@ negative-cached or replayed.
 
 ## Per-tenant pool & cache
 
-The stateless default is amended by one **user-approved deviation** (SCOPING Stage-4, 2026-10-06;
+The stateless default is amended by one **user-approved deviation** (user-approved 2026-10-06;
 security decision D-1 ratified): a bounded **in-process** client pool with a per-tenant TTL read
 cache, because a fresh client per request would silently disable the SDK's local vendor-budget
 guards (rate limiter, 429 cooldown) — a worse security posture, not a safer one.
@@ -775,39 +717,23 @@ guards (rate limiter, 429 cooldown) — a worse security posture, not a safer on
   scans the image. This repo ships no GitHub Actions workflow; quality gates and publishing are
   run manually by the maintainer.
 
-Full control set: [`docs/architecture.md`](docs/architecture.md) (sections 7.3, 8 and 10) and the
-independent review with its resolutions, [`docs/reviews/0.6.0.md`](docs/reviews/0.6.0.md).
+Full control set: [`docs/architecture.md`](docs/architecture.md) (sections 7.3, 8 and 10).
 
 ## SDK dependency
 
-`iit-mcp-autotask` depends on **`node-autotask` from npm at exactly `0.39.1`** (an exact pin —
-no range operator; subpaths `.` / `/capabilities` / `/operations` / `/resources` / `/types` /
-`/pool`) — the only **vendor** dependency; the other two runtime dependencies are
-`@modelcontextprotocol/server` (the MCP framework) and `zod` (schema validation). It never
-depends on a cloned checkout — no `file:`, `git:`, `link:` or workspace references. Range
-operators are prohibited on this dependency: a fresh lockfile-less install (every `npx`/`npm`
-user — the published tarball ships no lockfile) must resolve to the release this surface was
-reviewed against, or the plan-hash boot check refuses to start.
-
-**Publishing `node-autotask` is the maintainer's action, done manually.** It is published on the
-public registry at `0.37.0` (published 2026-10-28 UTC); the
-exact pin and the committed `pnpm-lock.yaml` (with `pnpm-workspace.yaml`) pin the real published
-tarball with its integrity hash, so installs resolve to exactly that release — the lockfile
-freezes the pnpm/git/Docker paths, the pin freezes the npm/npx paths. The docs are written against this
-published-package baseline, and the pre-publish checklist still starts with a registry re-check
-(`npm view node-autotask version`) — which now passes.
-
-**Plan-hash drift gate.** At boot, before the listener binds, the installed `node-autotask`'s
-capability plan hash must equal the pin this surface was built and reviewed against
-(`assertPlanHash`); a mismatch refuses the boot naming the drifted groups. The server only runs
-against the SDK build it was reviewed against — a plan-changing SDK update can reach a user only
-through a deliberately re-pinned server release, so drift is refused at boot, not discovered
-mid-run.
-
-**Upgrading node-autotask** is a deliberate server release (pin bump, plan-hash re-pin, mirrored-surface
-re-review, gates) — not an npm-range float. The exact steps live in the [per-release
-checklist](CONTRIBUTING.md#per-release-checklist-node-autotask-upgrade) in CONTRIBUTING.md, and `pnpm
-fresh-install-check` re-proves the fresh-install property before every publish.
+`iit-mcp-autotask` depends on **`node-autotask` from npm at an exact pin** (see `package.json`;
+no range operator) - the only vendor dependency; the others are `@modelcontextprotocol/server`
+and `zod`. It never depends on a checkout (no `file:`, `git:`, `link:` or workspace references).
+The published tarball ships no lockfile, so a fresh `npx`/`npm` install must resolve to the release
+this surface was reviewed against, or the plan-hash boot check refuses to start.
+
+**Plan-hash drift gate.** At boot, before the listener binds, the installed SDK's capability plan
+hash must equal the pin this surface was reviewed against (`assertPlanHash`); a mismatch refuses
+the boot naming the drifted groups.
+
+**Upgrading node-autotask** is a deliberate server release (pin bump, plan-hash re-pin,
+mirrored-surface re-review, gates), not a range float: see the
+[per-release checklist](CONTRIBUTING.md#per-release-checklist-node-autotask-upgrade).
 
 ## Development
 
@@ -862,35 +788,4 @@ rate-limits per principal itself. Either way the vendor-side budget (10,000 req/
 per integration) is guarded by the SDK agent profile (8,000/hr local budget, 3 concurrent) and exposed
 live through `autotask_tenant_status`.
 
-## Known SDK gaps
-
-None of the ten confirmed workflows is blocked. Confirmed absent from the SDK (recommend SDK
-issues — do not implement in this server):
-
-- **Knowledge base** — `KnowledgeBaseArticles` (43 paths) + `KnowledgeBaseCategories` (12): a real
-  SDK gap vs the vendored spec.
-- **Warehouse inventory** — `InventoryItems` / `InventoryLocations` / `InventoryStockedItems{,Add,Remove,Transfer}` /
-  `InventoryTransfers` / `InventoryItemSerialNumbers` (the SDK covers `InventoryProducts` only).
-- **Documents/articles ecosystem** — `Document*`/`Article*` family (the whole KB/document layer).
-- **Sales & pricing** — `SalesOrders`, `PriceList*`, `Taxes`/`TaxCategories`/`TaxRegions`,
-  `Currencies`, `PaymentTerms`, `ShippingTypes`, standalone `ServiceBundles`.
-- **Attachment downloads** — metadata-only surfaces for company/project/task/resource/expense
-  parents (the SDK covers `ticket_attachments` + `time_entry_attachments` downloads only).
-
-Not in the vendor REST spec at all (vendor surface gaps, not SDK gaps): reporting/BI, estimates,
-physical assets (Autotask models them as Configuration Items — covered).
-
-## Known limitations & blockers
-
-| # | Item | Status |
-|---|------|--------|
-| B1 | **Project phase & task lists** (W7 sub-capability): no `project_tasks`/`project_phases` operations in the SDK's 1,281-op registry. W7 ships with project status + context; phase/task lists excluded and documented. Classification (SDK gap vs vendor API-version limit) is decided by recon's spec-side check (A2). | blocked — documented |
-| B2 | **Time-entry writes on ww29/australia-nz for API-only users**: vendor 500 (live-verified). Time-entry creation works where the API user is a real resource, through the operator profile (`log-time-entry`); on ww29 the write is classified `failed` (a 500 with a vendor `errors[]` body), never `unknown`. | zone limitation |
-| B3 | **`time_entries.getPosted`/`getUnposted`: the zone's TimeEntry entity has no `postedDate`**, so SDK 0.31 and earlier 500ed (and `postedWithin`/`dateWorkedWindow` silently counted every entry unposted). SDK 0.32.0 derives posted state from a `billing_items.timeEntryID` join and returns `{ items, hasMore, window, approvedCount, unapprovedCount }` (optional date-only `dateFrom`/`dateTo`; no dates reads only the first 500 entries). Needs BillingItems read permission (one extra request per call); `approvedCount`/`unapprovedCount` are not posted state. SDK 0.37.0 adds `cursor`/`nextCursor` (page past 500 entries), `unconfirmed` (entries whose posted state is unknown, kept out of both counts) and `countOnly: true` on the four posted-state ops. Reachable via the generic layer. | resolved in SDK 0.32.0 (not re-verified live) |
-| B4 | **CI create on tenants without products** (ww29 product wall: `products.count = 0`): `configuration_items.create` requires an existing `productID`. No dedicated CI-create in v1; the wall is documented on the generic side. | zone limitation |
-| B5 | **Blind count/query surfaces on ww29** (companies not owned by the caller; tickets): count/query return 0/empty even when data exists. Not fixable client-side; the surface carries the typed blind-surface sentinel — `get(id)`/full-profile are the authorities. | zone limitation |
-| B6 | **`node-autotask` npm publish**: the Phase-C install gate re-checks the registry; if still 404 the build pauses and escalates (SCOPING-resolved: the user publishes — no git/file dependency fallback). | open — user action |
-
-Zone-anchored curation note (recon F5): several description pins are facts observed on ww29
-(australia-nz) and are carried as zone-labelled pins, never silently deleted; on other tenants
-they may be zone/user-specific.
+See [docs/architecture.md](docs/architecture.md) section 5 for intentional omissions and blocked capabilities.

package/dist/config/constants.d.ts

@@ -1,4 +1,4 @@
-/** The closed value sets of the configuration: transports, profiles, toolsets, cache presets and the removed variables (issue #91). */
+/** The closed value sets of the configuration: transports, profiles, toolsets, cache presets (issue #91). */
 /** `stdio` = local path (Claude Code / Claude Desktop / VS Code); `http` = remote (gateway). */
 export declare const TRANSPORTS: readonly ["stdio", "http"];
 export type Transport = (typeof TRANSPORTS)[number];
@@ -12,11 +12,6 @@ export type Profile = (typeof PROFILES)[number];
 /** The optional toolsets `AUTOTASK_TOOLSETS` selects; `core` is always registered. */
 export declare const TOOLSETS: readonly ["service", "records", "finance"];
 export type Toolset = (typeof TOOLSETS)[number];
-/**
- * The variables since removed, with the replacement each boot refusal names. Boot fails when
- * any is set: a deployment that still sets one expects a behaviour this build no longer has.
- */
-export declare const REMOVED_VARIABLES: Readonly<Record<string, string>>;
 /** The per-tenant read-cache preset every client this server builds gets. */
 export declare const CACHE_PRESETS: readonly ["on", "off"];
 export type CachePreset = (typeof CACHE_PRESETS)[number];

package/dist/config/constants.js

@@ -1,4 +1,4 @@
-/** The closed value sets of the configuration: transports, profiles, toolsets, cache presets and the removed variables (issue #91). */
+/** The closed value sets of the configuration: transports, profiles, toolsets, cache presets (issue #91). */
 /** `stdio` = local path (Claude Code / Claude Desktop / VS Code); `http` = remote (gateway). */
 export const TRANSPORTS = ['stdio', 'http'];
 /**
@@ -9,21 +9,6 @@ export const TRANSPORTS = ['stdio', 'http'];
 export const PROFILES = ['readonly', 'operator'];
 /** The optional toolsets `AUTOTASK_TOOLSETS` selects; `core` is always registered. */
 export const TOOLSETS = ['service', 'records', 'finance'];
-/**
- * The variables since removed, with the replacement each boot refusal names. Boot fails when
- * any is set: a deployment that still sets one expects a behaviour this build no longer has.
- */
-export const REMOVED_VARIABLES = {
-    AUTOTASK_READ_ONLY: 'AUTOTASK_PROFILE=readonly (the default) or AUTOTASK_PROFILE=operator',
-    AUTOTASK_WRITE_POLICY: 'AUTOTASK_PROFILE=readonly (the default) or AUTOTASK_PROFILE=operator',
-    AUTOTASK_WRITE_ALLOW: 'AUTOTASK_PROFILE=operator (writes are governed by the operator write path)',
-    AUTOTASK_SECRET_READS: 'nothing: authenticate.* is always refused (credential-minting)',
-    AUTOTASK_ACCESS_FILE: 'AUTOTASK_WRITE (see docs/write-gate.md)',
-    AUTOTASK_ACCESS_KEY: 'AUTOTASK_WRITE (see docs/write-gate.md)',
-    AUTOTASK_TOOL_EXCLUDE: 'AUTOTASK_TOOLSETS for reads, AUTOTASK_WRITE for writes',
-    AUTOTASK_OPS_ALLOW: 'AUTOTASK_WRITE',
-    AUTOTASK_POLICY_FILE: 'AUTOTASK_WRITE, AUTOTASK_DEDUP and AUTOTASK_WRITE_LIMITS (see docs/write-gate.md)',
-};
 /** The per-tenant read-cache preset every client this server builds gets. */
 export const CACHE_PRESETS = ['on', 'off'];
 /** The vendor's hard cap on requests per hour per integration (the local limiter must not exceed it). */

package/dist/config/credentials.d.ts

@@ -1,5 +1,5 @@
 import { type Config } from './schema.js';
-/** The recognised AUTOTASK_* names: the config schema's AUTOTASK_ keys + the removed 0.5.x set (derived, never hand-listed). */
+/** The recognised AUTOTASK_* names: the config schema's AUTOTASK_ keys (derived, never hand-listed). */
 export declare function recognisedAutotaskVars(): string[];
 /** The set-but-unrecognised AUTOTASK_* env keys (stale 0.4.x-era vars the server never reads). */
 export declare function unrecognisedAutotaskVars(env: Record<string, string | undefined>): string[];

package/dist/config/credentials.js

@@ -1,11 +1,9 @@
 /** Server credential intake and defaults: recognised variables, the credential load, the stdio defaults (issue #91). */
 import { loadAutotaskCredentialsFromEnv } from 'node-autotask';
-import { REMOVED_VARIABLES } from './constants.js';
 import { CONFIG_FIELDS } from './schema.js';
-/** The recognised AUTOTASK_* names: the config schema's AUTOTASK_ keys + the removed 0.5.x set (derived, never hand-listed). */
+/** The recognised AUTOTASK_* names: the config schema's AUTOTASK_ keys (derived, never hand-listed). */
 export function recognisedAutotaskVars() {
-    const schemaKeys = Object.keys(CONFIG_FIELDS.shape).filter((k) => k.startsWith('AUTOTASK_'));
-    return [...new Set([...schemaKeys, ...Object.keys(REMOVED_VARIABLES)])].sort();
+    return Object.keys(CONFIG_FIELDS.shape).filter((k) => k.startsWith('AUTOTASK_')).sort();
 }
 /** The set-but-unrecognised AUTOTASK_* env keys (stale 0.4.x-era vars the server never reads). */
 export function unrecognisedAutotaskVars(env) {

package/dist/config/load.js

@@ -1,6 +1,5 @@
 /** `loadConfig`: the environment in, a validated Config out (issue #91). */
 import { MALFORMED_CREDENTIAL_REFUSAL, detectCredentialShape, malformedCredentialBootMessage } from '../credential.js';
-import { REMOVED_VARIABLES } from './constants.js';
 import { CONFIG_FIELDS, schema } from './schema.js';
 import { unrecognisedAutotaskVars, loadServerCredentials } from './credentials.js';
 import { ConfigError } from './error.js';
@@ -15,9 +14,6 @@ import { ConfigError } from './error.js';
  *   problem at once — a boot loop that surfaces one missing variable per restart wastes real minutes.
  */
 export function loadConfig(env = process.env) {
-    const removed = Object.entries(REMOVED_VARIABLES)
-        .filter(([name]) => env[name] !== undefined)
-        .map(([name, use]) => `  ${name}: removed, use ${use}`);
     const parsed = schema.safeParse(env);
     // The pre-dispatch credential shape gate (issue #4a). Runs BEFORE the schema verdict is thrown,
     // so a malformed load is reported alongside (or instead of) the structural problems rather than
@@ -41,10 +37,9 @@ export function loadConfig(env = process.env) {
         // text served is this server's own, value-free: the loader's verdict and the load recipe.
         shapeIssues.push(`  ${intake.sdkProblem.code}: ${MALFORMED_CREDENTIAL_REFUSAL}`);
     }
-    if (parsed.success && shapeIssues.length === 0 && removed.length === 0)
+    if (parsed.success && shapeIssues.length === 0)
         return parsed.data;
     const problems = [
-        ...removed,
         ...(parsed.success ? [] : parsed.error.issues.map((i) => `  ${i.path.join('.') || '(config)'}: ${i.message}`)),
     ];
     const all = [...problems, ...shapeIssues];
@@ -53,7 +48,7 @@ export function loadConfig(env = process.env) {
     const unrecognised = unrecognisedAutotaskVars(env);
     const section = [
         'AUTOTASK_* env vars:',
-        `  recognised and set: ${Object.keys(CONFIG_FIELDS.shape).filter((k) => k.startsWith('AUTOTASK_') && env[k] !== undefined).sort().join(', ') || 'none'} — the vars this server actually reads (removed names above are not read)`,
+        `  recognised and set: ${Object.keys(CONFIG_FIELDS.shape).filter((k) => k.startsWith('AUTOTASK_') && env[k] !== undefined).sort().join(', ') || 'none'} — the vars this server actually reads`,
         ...(unrecognised.length > 0
             ? [
                 `  unrecognised (ignored by this server): ${unrecognised.join(', ')}`,

package/dist/config.d.ts

@@ -7,7 +7,7 @@
  * credential discovered by a model mid-conversation is a far worse failure than a container that
  * never came up.
  *
- * The credential model (SCOPING, approved): Autotask's three-header identity
+ * The credential model (docs/architecture.md 7.2, approved): Autotask's three-header identity
  * (`AUTOTASK_API_INTEGRATION_CODE` / `AUTOTASK_USERNAME` / `AUTOTASK_SECRET`) + the zone origin
  * (`AUTOTASK_BASE_URL`; the base path `/atservicesrest` is fixed, never configurable) + an
  * optional impersonation resource id. Under `stdio` the process environment IS the trust
@@ -15,7 +15,7 @@
  * without its own `X-Autotask-*` headers runs as this identity, and that identity is only ever
  * presented to the `AUTOTASK_BASE_URL` default origin (never to a caller-named one).
  */
-export { TRANSPORTS, PROFILES, TOOLSETS, REMOVED_VARIABLES, CACHE_PRESETS, VENDOR_HOURLY_CAP } from './config/constants.js';
+export { TRANSPORTS, PROFILES, TOOLSETS, CACHE_PRESETS, VENDOR_HOURLY_CAP } from './config/constants.js';
 export type { Transport, Profile, Toolset, CachePreset } from './config/constants.js';
 export type { Config } from './config/schema.js';
 export { RUN_SCOPE, isLoopbackHost } from './config/parse.js';

package/dist/config.js

@@ -7,7 +7,7 @@
  * credential discovered by a model mid-conversation is a far worse failure than a container that
  * never came up.
  *
- * The credential model (SCOPING, approved): Autotask's three-header identity
+ * The credential model (docs/architecture.md 7.2, approved): Autotask's three-header identity
  * (`AUTOTASK_API_INTEGRATION_CODE` / `AUTOTASK_USERNAME` / `AUTOTASK_SECRET`) + the zone origin
  * (`AUTOTASK_BASE_URL`; the base path `/atservicesrest` is fixed, never configurable) + an
  * optional impersonation resource id. Under `stdio` the process environment IS the trust
@@ -15,7 +15,7 @@
  * without its own `X-Autotask-*` headers runs as this identity, and that identity is only ever
  * presented to the `AUTOTASK_BASE_URL` default origin (never to a caller-named one).
  */
-export { TRANSPORTS, PROFILES, TOOLSETS, REMOVED_VARIABLES, CACHE_PRESETS, VENDOR_HOURLY_CAP } from './config/constants.js';
+export { TRANSPORTS, PROFILES, TOOLSETS, CACHE_PRESETS, VENDOR_HOURLY_CAP } from './config/constants.js';
 export { RUN_SCOPE, isLoopbackHost } from './config/parse.js';
 export { recognisedAutotaskVars, unrecognisedAutotaskVars, serverCredentialDefaults, hasServerCredentialDefaults } from './config/credentials.js';
 export { ConfigError } from './config/error.js';

package/dist/credential.d.ts

@@ -1,3 +1,25 @@
+/**
+ * credential.ts — the pre-dispatch shape gate for Autotask credential values, and the value-free
+ * description of a credential the operator-facing doctor reports.
+ *
+ * Why this exists (2026-10-07 incident, issues #4/#5/#6): a `.env` file may SINGLE-QUOTE a value on
+ * purpose (a secret containing `$` must be, so the shell does not expand it). The shell strips those
+ * quotes when the file is loaded with `set -a; . ./.env; set +a`; a quote-PRESERVING loader (most
+ * `dotenv` variants, a hand-rolled `split('=')`) hands the value over with its quotes intact. Such a
+ * value is printable ASCII, so it passes every transport check, reaches the vendor as
+ * `Secret: 'a$b'` and comes back as an opaque 401 that reads like a rotated credential — on an
+ * account where repeated auth failures risk a lock.
+ *
+ * This module closes that at the boundary, on BOTH intake paths, before any client is constructed.
+ * It never inspects, stores or reports a credential VALUE — only shape facts derived from it (a
+ * length, a two-character prefix, and which anomaly was seen), so every structure here is safe to
+ * log and to serialize.
+ *
+ * The anomaly vocabulary and the anomaly NAMES are this package's own (`detectCredentialShape`), so
+ * the envelopes and the doctor report stay stable across SDK versions; the SDK's own validator
+ * (`credentialShapeProblem` / `INVALID_CREDENTIAL_SHAPE`) is consumed at construction, where it is
+ * part of the SDK's contract with its callers.
+ */
 /**
  * The env-load pitfall every shape rejection points at, without claiming which loader was used.
  * Byte-for-byte the SDK's own pointer (`CREDENTIAL_SHAPE_POINTER` is the same sentence in the SDK's
@@ -53,12 +75,6 @@ export interface CredentialReport {
 export declare function reportCredential(env: Record<string, string | undefined>, name: string): CredentialReport;
 /** The one-line, value-free boot refusal message for a malformed credential variable. */
 export declare function malformedCredentialBootMessage(name: string, anomalies: readonly string[], length: number): string;
-/**
- * The SDK's own verdict on a value, when it has one (`credentialShapeProblem` from node-autotask
- * 0.8.0). Exposed so callers can check that this package's vocabulary and the SDK's agree — and so
- * the companion `INVALID_CREDENTIAL_SHAPE` error the SDK throws at construction can be surfaced as
- * this server's typed `CREDENTIAL_MALFORMED` refusal without re-implementing the predicate.
- */
 /**
  * The server's OWN refusal text for the SDK loader's `INVALID_CREDENTIAL_SHAPE` verdict (issue #4).
  * Built from the loader's machine code only — the SDK's message embeds a value summary
@@ -66,4 +82,3 @@ export declare function malformedCredentialBootMessage(name: string, anomalies:
  * loader's verdict, and the load recipe; no length, no prefix, no character of any value.
  */
 export declare const MALFORMED_CREDENTIAL_REFUSAL: string;
-export declare function sdkShapeProblem(value: string): string | undefined;

package/dist/credential.js

@@ -20,7 +20,6 @@
  * (`credentialShapeProblem` / `INVALID_CREDENTIAL_SHAPE`) is consumed at construction, where it is
  * part of the SDK's contract with its callers.
  */
-import { credentialShapeProblem } from 'node-autotask';
 /**
  * The env-load pitfall every shape rejection points at, without claiming which loader was used.
  * Byte-for-byte the SDK's own pointer (`CREDENTIAL_SHAPE_POINTER` is the same sentence in the SDK's
@@ -104,12 +103,6 @@ export function malformedCredentialBootMessage(name, anomalies, length) {
     return (`${name} holds a value whose shape cannot be right (length ${length}, ${anomalies.join(', ')}); ` +
         `this server refuses to boot rather than present a malformed credential to Autotask (issue #4). ${CREDENTIAL_LOAD_HINT}`);
 }
-/**
- * The SDK's own verdict on a value, when it has one (`credentialShapeProblem` from node-autotask
- * 0.8.0). Exposed so callers can check that this package's vocabulary and the SDK's agree — and so
- * the companion `INVALID_CREDENTIAL_SHAPE` error the SDK throws at construction can be surfaced as
- * this server's typed `CREDENTIAL_MALFORMED` refusal without re-implementing the predicate.
- */
 /**
  * The server's OWN refusal text for the SDK loader's `INVALID_CREDENTIAL_SHAPE` verdict (issue #4).
  * Built from the loader's machine code only — the SDK's message embeds a value summary
@@ -119,7 +112,4 @@ export function malformedCredentialBootMessage(name, anomalies, length) {
 export const MALFORMED_CREDENTIAL_REFUSAL = 'one or more credential values were refused by the SDK\'s canonical loader as a malformed shape; ' +
     'no request was sent. Fix the value in the environment this server reads and reload it. ' +
     CREDENTIAL_LOAD_HINT;
-export function sdkShapeProblem(value) {
-    return credentialShapeProblem(value);
-}
 //# sourceMappingURL=credential.js.map

package/dist/main.js

@@ -10,7 +10,7 @@
  * only decision this file makes.
  */
 import { createMcpHandler } from '@modelcontextprotocol/server';
-import { ConfigError, loadConfig, serverCredentialDefaults } from './config.js';
+import { ConfigError, loadConfig, serverCredentialDefaults, unrecognisedAutotaskVars } from './config.js';
 import { runMoves } from './moves.js';
 import { runDoctor } from './doctor.js';
 import { createLogger } from './logger.js';
@@ -166,6 +166,10 @@ function main() {
     // the logs must stay on stderr.
     const logSink = config.MCP_TRANSPORT === 'http' ? process.stdout : process.stderr;
     const log = createLogger(config.LOG_LEVEL, (line) => logSink.write(line + '\n'));
+    // Stale or mistyped AUTOTASK_* names are ignored, never a boot failure: say so once.
+    const unrecognised = unrecognisedAutotaskVars(env);
+    if (unrecognised.length > 0)
+        log.warn('ignoring unrecognised AUTOTASK_* variables (removed in an earlier version, or misspelled)', { variables: unrecognised });
     // Security V9 (FT-3): the lab-only allow-any opt-in is a security-posture warning for the
     // operator. It is NOT part of the operational NDJSON stream (under http that is stdout), so
     // it goes straight to stderr on every transport — the stream an operator/monitor reads for

package/dist/tools/catalog-data.d.ts

@@ -96,7 +96,7 @@ export type AutotaskCacheOptions = {
     resourceNameCache?: false;
 };
 /**
- * The SDK cache options the preset selects (SCOPING Stage-4 deviation, user-approved):
+ * The SDK cache options the preset selects (approved cache deviation, docs/architecture.md 8.1):
  * `on` sends NO cache blocks — the SDK's default-on caches apply to every pooled tenant client
  * (read ~5 min + the plan-derived reference table, field ~5 min, resource-name ~1 h; in-process,
  * per-tenant, TTL-bounded, never cross-tenant, never on disk; the server holds no TTL value of

package/dist/tools/catalog-data.js

@@ -147,7 +147,7 @@ export function toolDescription(tool) {
     return text;
 }
 /**
- * The SDK cache options the preset selects (SCOPING Stage-4 deviation, user-approved):
+ * The SDK cache options the preset selects (approved cache deviation, docs/architecture.md 8.1):
  * `on` sends NO cache blocks — the SDK's default-on caches apply to every pooled tenant client
  * (read ~5 min + the plan-derived reference table, field ~5 min, resource-name ~1 h; in-process,
  * per-tenant, TTL-bounded, never cross-tenant, never on disk; the server holds no TTL value of

package/dist/tools/composites.js

@@ -26,7 +26,7 @@ import { AutotaskConfigError, NotFoundError } from 'node-autotask';
 import { TICKET_FULL_CONTEXT_INPUT, COMPANY_FULL_PROFILE_INPUT, COMPANY_PROFILE_PART_LIMIT_DEFAULT, CONFIGURATION_ITEM_PROFILE_INPUT, PROJECT_GET_CONTEXT_INPUT, QUOTE_GET_INPUT, INVOICE_GET_INPUT, CONTACT_FULL_PROFILE_INPUT, SERVICE_CALL_FULL_PROFILE_INPUT, CONTRACT_FULL_PROFILE_INPUT, RESOURCE_WORKLOAD_INPUT, closedInput, } from './schemas.js';
 import { abortedAnswer } from './dispatch.js';
 import { crossResourceUntrusted, documentCore, markFilePayload, markResult, ok } from './results.js';
-import { resolveOutputTarget, writeOutputBytes, writeOutputText } from './output-file.js';
+import { resolveOutputTarget, writeOutput } from './output-file.js';
 import { assertOperationPermitted } from '../policy.js';
 /** The cap on a fan-out `in` filter (the task-id join between two parts). */
 const IN_FILTER_CAP = 100;
@@ -265,7 +265,7 @@ export function buildInvoiceGet(ctx) {
                 // that arrives pre-wrapped is a vendor forgery — the pinned SDK's read path returns raw).
                 const doc = documentCore(result);
                 if (target !== undefined) {
-                    const bytes = await writeOutputText(target, doc);
+                    const bytes = await writeOutput(target, doc);
                     return ok(`Invoice ${args.format} export written to the configured output directory (${bytes} bytes); the file holds the raw document, the result carries only the path and size.`, { format: args.format, result: { outputPath: target.path, bytes, encoding: 'utf-8' } });
                 }
                 const buf = Buffer.from(doc, 'utf8');
@@ -276,7 +276,7 @@ export function buildInvoiceGet(ctx) {
             // pdf: the SDK's file payload { encoding, byteLength, truncated, data? }.
             const payload = markResult(result, ctx.untrustedFields(op));
             if (target !== undefined && payload.truncated !== true && typeof payload.data === 'string') {
-                const bytes = await writeOutputBytes(target, Buffer.from(payload.data, 'base64'));
+                const bytes = await writeOutput(target, Buffer.from(payload.data, 'base64'));
                 return ok(`Invoice ${args.format} export written to the configured output directory (${bytes} bytes); the file holds the raw document, the result carries only the path and size.`, { format: args.format, result: { outputPath: target.path, bytes, encoding: 'binary' } });
             }
             markFilePayload(payload);

package/dist/tools/context/client.d.ts

@@ -1,4 +1,5 @@
 import type { AutotaskConfig } from 'node-autotask';
+import { type ClientPool } from 'node-autotask/pool';
 import type { Config } from '../../config.js';
 import type { Logger } from '../../logger.js';
 import type { ToolClient } from './types.js';
@@ -21,3 +22,5 @@ export declare function buildStdioClient(config: Config, log: Logger): {
     client: ToolClient;
     origin: string;
 };
+/** The process-lifetime bounded per-tenant client pool of the http transport (security D-1, ratified). */
+export declare function createTenantPool(log: Logger): ClientPool;

package/dist/tools/context/client.js

@@ -1,5 +1,6 @@
 /** SDK client construction: the base options, the placeholder client and the stdio client (issue #91). */
 import { AutotaskClient } from 'node-autotask';
+import { createClientPool } from 'node-autotask/pool';
 import { serverCredentialDefaults } from '../../config.js';
 import { normalizeBaseUrl } from '../../base-hosts.js';
 import { cacheOptionsForPreset } from '../catalog-data.js';
@@ -34,7 +35,7 @@ export function buildSdkBaseOptions(config, log) {
             blockPrivateHosts: true,
             ...(defaultBaseUrl !== undefined ? { allowedOrigins: [defaultBaseUrl] } : {}),
         },
-        // The SCOPING Stage-4 cache deviation (user-approved): `on` sends no cache blocks (the SDK
+        // The approved cache deviation, docs/architecture.md 8.1 (user-approved): `on` sends no cache blocks (the SDK
         // default-on caches) UNLESS the AUTOTASK_FIELD_CACHE_TTL_MS override is set — then the
         // scalar fieldCache block rides (the TTL pass-through); `off` opts every channel out
         // explicitly (every read re-dials the vendor) and is never touched by the override.
@@ -93,4 +94,10 @@ export function buildStdioClient(config, log) {
     });
     return { client, origin: normalized.origin };
 }
+/** The process-lifetime bounded per-tenant client pool of the http transport (security D-1, ratified). */
+export function createTenantPool(log) {
+    const pool = createClientPool({ maxSize: 128 });
+    log.info('tenant client pool ready', { maxSize: 128 });
+    return pool;
+}
 //# sourceMappingURL=client.js.map

package/dist/tools/context.d.ts

@@ -15,7 +15,7 @@
  *   the pool + the credential-tuple config, so a vendor 401 deletes the entry (no negative
  *   caching; security S1/C1.8, S3/C3.5).
  *
- * Client state (SCOPING Stage-4 deviation, user-approved): under `http` one BOUNDED in-process
+ * Client state (approved cache deviation, docs/architecture.md 8.1): under `http` one BOUNDED in-process
  * LRU pool (`node-autotask/pool`, default capacity 128) of tenant clients, keyed by the SDK's
  * SHA-256 of the NORMALISED credential tuple (user, integration code, secret, resolved base URL,
  * impersonation id) — raw credentials never appear in keys, logs or eviction messages. Each
@@ -33,6 +33,5 @@
 export type { ToolClient, HourlyBudget, QueryWalkParams, QueryWalkResult, ToolOps, ToolDeps, WriteDeps, ToolContext, ResolvedRequestScope, HttpScopeResolver } from './context/types.js';
 export { defaultToolOps } from './context/ops.js';
 export { deriveToolContext, releaseClientOnError } from './context/derive.js';
-export { buildSdkBaseOptions, buildStdioClient } from './context/client.js';
+export { buildSdkBaseOptions, buildStdioClient, createTenantPool } from './context/client.js';
 export { createHttpScopeResolver } from './context/scope.js';
-export { createTenantPool } from './context/pool.js';

package/dist/tools/context.js

@@ -1,6 +1,5 @@
 export { defaultToolOps } from './context/ops.js';
 export { deriveToolContext, releaseClientOnError } from './context/derive.js';
-export { buildSdkBaseOptions, buildStdioClient } from './context/client.js';
+export { buildSdkBaseOptions, buildStdioClient, createTenantPool } from './context/client.js';
 export { createHttpScopeResolver } from './context/scope.js';
-export { createTenantPool } from './context/pool.js';
 //# sourceMappingURL=context.js.map

package/dist/tools/dispatch.js

@@ -260,24 +260,21 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
         // path and this bounded default is its contract; autotask_query refuses the missing filter because it is the guided surface.
         if (operation.endsWith('.query') && cleanArgs[0] === undefined)
             cleanArgs[0] = { limit: QUERY_LIMIT.parse(undefined) };
-        const given = cleanArgs[0];
-        // #173: a digit-string limit (a client that writes every value as text, e.g. Copilot Studio's
-        // limit: "5") is that number; the SDK still range-checks it.
-        if (given !== null && typeof given === 'object' && !Array.isArray(given) && typeof given.limit === 'string' && /^\d{1,9}$/.test(given.limit)) {
-            cleanArgs[0] = { ...given, limit: Number(given.limit) };
+        // #173: a digit-string limit or latest (a client that writes every value as text, e.g. Copilot Studio's
+        // limit: "5") is that number; the SDK still range-checks it (it refuses a string `latest`, so the
+        // default limit and the scope guard below must see the number).
+        for (const key of ['limit', 'latest']) {
+            const given = cleanArgs[0];
+            const v = given?.[key];
+            if (given !== null && typeof given === 'object' && !Array.isArray(given) && typeof v === 'string' && /^\d{1,9}$/.test(v))
+                cleanArgs[0] = { ...given, [key]: Number(v) };
         }
-        // The SDK validates `latest` with Number.isInteger too (a string is refused), so a digit-string
-        // latest gets the same coercion (and the default limit and the scope guard below see the number).
-        const given2 = cleanArgs[0];
-        if (given2 !== null && typeof given2 === 'object' && !Array.isArray(given2) && typeof given2.latest === 'string' && /^\d{1,9}$/.test(given2.latest)) {
-            cleanArgs[0] = { ...given2, latest: Number(given2.latest) };
-        }
-        const given3 = cleanArgs[0];
-        if (given3 !== null && typeof given3 === 'object' && !Array.isArray(given3)) {
-            assertFilterShape(given3.filter, operation);
+        const bagArg = cleanArgs[0];
+        if (bagArg !== null && typeof bagArg === 'object' && !Array.isArray(bagArg)) {
+            assertFilterShape(bagArg.filter, operation);
             // #234: ticket.<field> on tickets (task., project. likewise) is the own field
             const resource = operation.slice(0, operation.lastIndexOf('.'));
-            const bag = { ...given3 };
+            const bag = { ...bagArg };
             if (bag.filter !== undefined)
                 bag.filter = normalizeFilter(bag.filter, resource);
             if (Array.isArray(bag.includeFields))
@@ -319,6 +316,12 @@ export async function readOneItem(ctx, operation, args, signal, opts) {
         if (verdict.aborted)
             return { aborted: true, result: undefined };
         guardNote = verdict.note;
+        // #245: a no-filter walk answers the first rows of the tenant table; say so, so the page is not read as the full answer
+        const f = sent.filter;
+        if ((f === undefined || (Array.isArray(f) && f.length === 0)) && sent.latest === undefined && typeof sent.limit === 'number') {
+            const noFilter = `no filter: the first ${sent.limit} rows in id order, not a scoped or complete answer.`;
+            guardNote = guardNote === undefined ? noFilter : `${guardNote} ${noFilter}`;
+        }
     }
     if (operation === 'contracts.profitability') {
         const rawBag = cleanArgs[1];