Partial edits and full source replacements need different promises
Choose a component and then choose how its source changes. Partial overlays and complete source replacements have precise preservation rules, with explicit build, publication and deployment stages.
Published 5 November 2026. Hostwatch engineering review; implementation limits are stated below.
Define what the word update will mean
An instruction to update an application can describe several different changes. It might mean replacing one component, editing two source files, rebuilding the complete application or applying a previously prepared image. Those choices affect what must be preserved and what evidence is needed before the live process changes. The operator and assistant should agree on the intended scope in ordinary language first. A useful statement might be “change the website's help text while preserving its other source files and its separate MCP component.” That sentence identifies a component, an editing scope and a preservation expectation before any archive or image exists.
Hostwatch supports both partial source changes and full source-tree replacement for components with configured source-build profiles. Component selection and source mode are independent choices. Updating a website target selects the process boundary; choosing partial mode selects how that target's approved source tree changes. Full mode selects an entirely supplied source tree for the same component. Neither choice means replacing the application's database or inventing new runtime mounts. Keeping these dimensions explicit prevents an assistant from interpreting “full update” as permission to change the whole server, or interpreting “partial” as a guarantee that the resulting application requires only a tiny build.
Start from an approved source snapshot
The live container is a runtime package, not necessarily a convenient editable repository. It may contain compiled output, generated assets and production dependencies while omitting the original source files. A trustworthy source-release workflow therefore begins with an operator-approved source snapshot and fixed recipe. That snapshot must correspond to the component's approved baseline rather than whatever a developer happens to have checked out locally. A source alias changed by an independent release needs operator reconciliation when it no longer matches the configured baseline. Refusing that mismatch is more useful than confidently applying a small patch to the wrong version of the product.
Read source_tree to inspect the approved paths, file sizes, modes, hashes and source revision. Manifest pagination must stay on the same revision; mixing pages across a concurrent change can produce a tree that never existed. Read selected files through source_file, keeping the reported whole-file hash with the content used for editing. Source inspection is owner-only because application code and prepared content can contain private information even when they are not credentials. The assistant should inspect what it needs to make the requested change and preserve the relevant evidence, rather than copying the entire source tree into an unrelated conversation simply because the read operation is available.
Partial mode preserves unmentioned source files
Partial mode overlays uploaded regular files on the approved current source. Files absent from the archive remain in place. A deliberate deletion is expressed through explicit deletePaths for existing regular files. This behavior fits a focused correction, a small feature or an asset replacement when the rest of the source should remain as reviewed. Consider changing a help paragraph and its image reference: include the edited source file and new asset, then name an old asset for deletion only if that removal is part of the intended change. Omitting the old file from the archive alone does not remove it from the resulting tree.
Review a partial change as a source diff, including generated content required by the trusted recipe. A small text edit can still trigger a complete framework compilation, and its output can affect more than the edited route. Partial describes source composition, not a promise about build duration, memory use or application behavior. It also does not make arbitrary host files editable through MCP. Paths must remain inside the component's approved relative source space. Environment configuration and runtime credentials stay protected outside that upload. If the intended fix actually requires a new mount, port or private environment reference, handle that profile change through the operator workflow rather than trying to smuggle it into the source archive.
Full mode starts with the complete intended tree
Full mode replaces the source tree with the supplied archive. Files that are missing disappear from that next source tree, and deletePaths is not accepted because omission already defines removal. This is useful when delivering a complete prepared release, replacing a snapshot whose overall contents have changed or establishing a clean source composition from a reviewed package. It requires a complete understanding of the builder's inputs. A framework may need its lockfile, workspace policy, configuration, content and public assets as well as the visible page code. Leaving one of these out is a real source removal, not a harmless way to reduce upload size.
Build the full archive from a prepared, reviewed source package with the dependencies and generated content expected by the installed recipe. Exclude local dependency directories and build outputs that the source protocol rejects. Do not assume a successful local build proves the remote recipe has identical inputs or execution policy. A full archive can be perfectly well-formed while missing an application resource that only a representative route reveals. Use the preview to validate archive and source constraints, then use the build and isolated runtime checks to establish more about the result. Full replacement gives a precise composition rule; the application owner still decides whether that composition is the intended release.
Archive safety is part of source correctness
The upload format is a gzip-compressed tar archive containing relative regular files and directories. Traversal paths, links, special files, credential paths and prohibited dependency or output directories are rejected. Limits cover the compressed upload, expanded source size, individual file size and file count. These constraints protect the component boundary and prevent a small compressed input from consuming unbounded resources during extraction. They also make archive composition predictable for the reviewer. A symlink into a home directory is not a clever way to include a missing file; it makes the source package depend on information outside the approved tree and must be treated as invalid input.
Inspect the target's advertised quotas before preparing the archive. Large prepared assets can be legitimate inputs, but they still need to fit the configured limits and available disk reserve. Hash the complete compressed bytes with SHA-256, keeping that value with the intended mode and component. Hashing the expanded directory or a separately regenerated archive produces different evidence. Keep private keys and environment values outside the package regardless of whether their filenames happen to trigger a validator. Filename checks provide a useful boundary, yet the code owner remains responsible for the content they authorize the assistant to upload. Source correctness includes the absence of unintended private material, not just a valid tar structure.
Upload exact bytes and resume from reported state
Hostwatch source uploads use bounded chunks with a stable upload ID, total byte length and whole-archive hash. The caller sends the next chunk at the expected byte offset and can read source_upload_status to recover after an interrupted request. Exact-byte retries are different from sending a newly generated archive under the same identity. If the source package changes, prepare a new upload identity and review it as a different input. This discipline matters with larger content archives, where a client can lose connectivity after the server has accepted a chunk but before the client receives the acknowledgment. The reported offset establishes where continuation should begin.
Wait for the upload to be sealed before asking for a source preview. An accepted chunk proves only that those bytes were accepted at that position. Sealing establishes that the complete bounded input matches the promised archive identity. It does not prove that the application builds or that the source tree expresses the user's intent. Keep upload, preview and build states distinct in the assistant's progress messages. When a limit or hash check fails, report the particular stage and correct the input deliberately. Repeating larger chunks, changing the total length midstream or creating new deployment requests cannot repair an invalid source upload and makes the operation history less understandable.
Preview binds the archive to the current builder
A source preview checks the sealed upload against the selected mode, approved source, staged image and trusted builder. It returns the source digest and revision required by source_build. Carry those exact values into the build request with the same upload ID, mode and deletion list. This binds the change to the state that was actually reviewed. If the recipe or source changed during preparation, take a new preview and assess the difference instead of treating the old approval as timeless. The builder is an operational input: changing it can change the image even when every application source byte remains the same.
Recipes belong to the operator configuration, with fixed container build behavior and resource limits. They should pin the intended base and honor the application's lockfile and build policy. A failure caused by a missing workspace policy file should be corrected in the recipe or approved source preparation, rather than weakening a global dependency policy until the install passes. The assistant can read the bounded build log to locate a real failure and propose the smallest relevant correction. It cannot replace the trusted recipe with arbitrary commands in the MCP request. That division lets source editing remain flexible while preserving the administrator's decisions about how code becomes an executable runtime on the server.
A staged image is a decision point
source_build runs asynchronously and stages its immutable result when successful. Poll image_publish_status using the stable operation key, and inspect source_build_log when the build fails. The receipt records the built image digest and resulting source revision. During this phase the live component continues using its existing deployment. That separation is valuable for both source modes. A partial edit can fail compilation without disrupting the serving process, and a full replacement can be examined as a staged result before publication. Describe a successful build as a prepared release, leaving the application step explicit in both the tool workflow and the human report.
Publication and deployment then use their own fresh previews. An absent registry tag can be published; an existing one needs its current published digest when updated or replaced. The container deployment preview supplies the expected source digest and runtime revision. The owner explicitly applies that reviewed component release and follows its terminal status. No CI/CD pipeline, Git watcher or background software updater connects these stages automatically. This gives a team room to inspect the staged result, coordinate an application-specific maintenance window and retain a previous image. The convenience comes from concise named operations and concrete evidence, rather than from allowing a source upload to imply every later production action.
Data and sibling components need separate checks
Source replacement changes files used to build one component. It does not replace protected environment references, persistent mounts or application databases. This boundary keeps both editing modes useful, but it also creates an important compatibility obligation. A complete new source tree may contain code that expects a different database schema or file layout. Recreating the old container after a failed health check cannot automatically reverse those application data changes. Before applying, identify migration behavior and the current writer, retain a usable backup and decide whether the previous image remains compatible. A successful archive extraction is much earlier evidence than a safe database transition.
After application, inspect the serving image, configured health check and a representative user flow. Confirm that durable data remains available under the expected runtime identity. Check sibling components when resource pressure or shared dependencies could affect them. For a product with a separate MCP endpoint, a website-only source change should leave that endpoint serving its intended version. Isolated validation containers can exercise a recipe with private empty data mounts and harmless preservation markers before production application. Such checks provide useful evidence without writing artificial records into live accounts. They should be reported honestly as isolated validation, followed by the production observations that support the final release claim.
Retain enough evidence to recover deliberately
Keep the source revision, archive identity, built digest and deployment receipt together with the reason for the change. Stable operation keys make interrupted requests inspectable and keep retries from becoming duplicate intent. A rolled_back result means the attempted deployment failed and the previous deployment was restored; it is not a successful release of the new application. An uncertain result requires inspection of the real runtime before another change is considered. Source history and operation history are bounded, so cleanup is also explicit. Discard eligible superseded source material after the relevant recovery needs are satisfied, while current and deployed source releases remain protected.
The choice between partial and full becomes easy to explain when the preservation rule is clear. Partial keeps unmentioned source and names deletions explicitly. Full uses the entire supplied tree and removes omitted source. Both operate on a selected component through an approved recipe; neither grants arbitrary host editing or data migration authority. Both leave publication and deployment as deliberate later actions. The operator can therefore choose the smallest suitable scope without depending on ambiguous phrases such as push everything. A good final message names the component, source mode, observed running result and any data limitation, allowing the next person to understand exactly what changed and what evidence supports it.
Partial preserves unmentioned source and names deletions explicitly. Full uses the complete supplied tree. Both stage an image first and leave publication, deployment and data compatibility as explicit later decisions.